Java-GNOME 2.10 GNOME Tutorial
<<< Previous |  | Next >>>

# 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 and gnome.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 throughout the tutorial.

Example 1. First.java

    // First we import the libraries used by this example
    import org.gnu.gnome.App;
    import org.gnu.gnome.Program;
    import org.gnu.gtk.Gtk;

    public class First {

        public static void main(String[] args) {
            // Initialization
            Program.initGnomeUI("First", "0.1", args);

            App app = new App("First", "First App");
            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

This command assumes that gtk.jar and gnome.jar are in your classpath. If they are not I would recommend doing so now as it will help you throughout this tutorial. It might also be a good time to make sure the Java-GNOME shared objects are in your library path. This can be done in one of two ways. You can specify this path on the command- line by specifying '-Djava.library.path=path_to_shared_objects'. The other way to specify the shared object path is to make sure the path is included in the LD_LIBRARY_PATH environment variable.

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.

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. Program.initGnomeUI()

    Program.initGnomeUI("First", "0.1", args);

The prototype for the Java method is:

`public static Program `Program.initGnomeUI``(String `appId`, String `version`, String[] `argv`);

This call initializes the application. This sets up all of the GNOME internals and prepares them. The first parameter, appId, is the application id. The second parameter, version, should contain the application version. The third parameter is the command-line arguments. Gnome will parse the command-line arguments looking for information that it is interested in and will take the appropriate actions. We will be discussing this in more detail later in this tutorial.

The next call creates a App object.

Example 3. App constructor

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

The prototype for the constructor is:

`public `App``(String `appname`, String `title`);

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

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

Example 4. Widget.show()

    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 5. Gtk.main()

    Gtk.main();

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

<<< Previous | Home | Next >>>
Introduction |  | Adding Menus