Chapter 2. Let's Get Started

This tutorial assumes that you have already downloaded the Java-GNOME source and have installed it. Don't forget to include gtk.jar in your classpath.

My First GNOME Application

The best place to start is with a small example. This first example builds a small window. It is not very useful at this point but we will be building upon this example through this chapter.

Example 2-1. First.java


// First we import the libraries used by this example
import gtk.*;
import gnome.*;

public class First {

    public static void main(String[] args) {
        // Initialization
        Gnome.init("First", "0.1", 0, 0);
    
        GnomeApp app = new GnomeApp("First", "First App");
        app.setPolicy(false, true, false);
        app.setWmclass("First", "FirstApp");
        app.show();

        Gtk.main();
    }
}

The above program can be compiled using:

$javac First.java

Once compiled, the example can be ran as follows:

$java First.java

This command assumes that gtk.jar, gnome.jar and . are in your classpath. If they are not I would recommend doing so now as it will help you throughout this tutorial. I will not include these compile statements throught the remainder of this tutorial.

The first thing to note about this example is the import statements.There are three Java packages included in the gtk.jar file. They are gdk, gtk, and gnome. They correspond to the three main libraries that the Java-GNOME bindings provide access to.

OK! I did say I would provide some background so here it goes.

GTK+

GTK+ (the Gimp Tool Kit) is the GUI foundation that is utilized by the GNOME project. GTK+ is a general purpose GUI library written in C. It depends upon GLib, a utility library that provides memory management routines, data structures and the methods to operate on them, debugging macros, and a portability layer.

The GTK+ package actually contains two libraries. They are GTK and GDK. GDK (the Gimp Drawing Kit) is a simplified portability layer directly over the Windowing System. GDK is not only for low level library developers, but it also provides numerous drawing functions that will be of interest to GUI developers (Color and font manipulation to name a few).

GTK provides a large collection of widgets that can be used to construct windows. In addition to the widgets, GTK also provides window layout capabilities that is based upon the same concept as the Java Layout Managers.

GNOME

GNOME (the GNU Network Object Model Environment) is an application framework built upon GTK and numerious other libraries. From a developers standpoint it provides a common consistent framework for building applications that can run in the GNOME desktop environment. These applications can also run without the environment as well.

Now that I have covered a few of the basics it's time to get back to the code.

Explanation of the code

The example consists of one class. The first call you see in main is:

Example 2-2.


Gnome.init("First", "0.1", 0, 0);

The prototype for the Java method is:

public void Gnome.init(String app, String version, int a, int b);

This call initializes the application. This sets up all of the GNOME internals and prepares them. The first parameter, app, is the application id. The second parameter, version, should contain the application version. The third and fourth parameters are not used in the Java-GNOME bindings at this time.

The next call creates a GnomeApp object.

Example 2-3.


GnomeApp app = new GnomeApp("First", "First App");

The prototype for the constructor is:

public GnomeApp(String appname, String title);

The appname parameter is the name of the program as used in filesnames and paths. The title parameter is the window title for the application. Toplevel GNOME applicaions would usually only create one GnomeApp object as their toplevel window. The GnomeApp class has built-in support for menusbars, toolbars, and statusbars. It also takes care of loading the accelerators for you.

The next two calls were not necessary to get this application to run but I included them to introduce a couple of ideas that will be expanded upon later in this tutorial The first of these calls sets resize policies.

Example 2-4.


app.setPolicy(false, true, false);

The prototype for this method is:

public void setPolicy(boolean allow_shrink, boolean allow_grow, boolean auto_shrink);

This method changes how a toplevel window handles its' size requests and user resize attempts. There are only two reasonable ways to use this method:

1. app.setPolicy(false, true, false); means that the window is user resizable.

2. app.setPolicy(false, false, true); means that the window's size is program-controlled and should match the current size request of the window's children.

A toplevel window will always change size to make sure that all of the childres recieve their requested size.

The next call registers with the window manager.

Example 2-5.


app.setWmclass("First", "First App");

The prototype for this method is:

public void setWmclass(String wmclass_class, String wmclass_name);

We will be discussing the interaction with the window manager in detail in a later section so I will not go into it at this time.

Finally, we need to tell the GnomeApp to display itself.

Example 2-6.


app.show();

All widgets must call this method in order to be seen. When the toplevel widget calls this method the entire window is displayed.

The final call in this example is:

Example 2-7.


Gtk.main();

This call places the application in the main event loop. This must be called in every GNOME and GTK application.