Developing on the Solaris OS With "Java GNOME" Bindings

To simplify this setup, we are creating a Java GNOME NetBeans plugin, which is scheduled to be available shortly on the OpenSolaris.org Java Desktop System project downloads area (refer to Resources). When this is installed it will create the JavaGnomeLib automatically. Note that your application might not require all the Java GNOME API jars, but it is very convenient having a single JavaGnomeLibrary to add to any of your Java GNOME based projects.

Launch the NetBeans IDE and create a standard Java application.

• File/ New Project-> General -> Java Application

Name it "hello" and set it up to use the JavaGnomeLib.

• Go to File/"hello" Properties -> Libraries Category. In both the Compile and Run Tabs, click on Add Library and select the JavaGnomeLib.

Now you are ready to cut some code. Start with a simple "Hello World" just to be different!

Figure 1: "Hello World" Java Code Listing in NetBeans IDE 5.5

First you import the various APIs you want to use from the GTK+ bindings. (Refer to the Java GNOME man page, which is listed in the Resources section, for a full listing of the API imports.) If you want to browse the API sources, just right-click on the import statement and select Go To -> Source. All of the source files from the jar will be displayed in the Project panel, which can be very handy when you are not quite sure which API you want. The NetBeans IDE also supports code completion so just typing window. will display a list of the available APIs on the Window widget, along with the API Javadoc.

In Hello's constructor you create a top-level window and add a button to it with a "Hello!" title, then set its size and show it. The main routine initializes GTK, calls Hello's constructor, and then runs the main GTK event loop to process user input to the display application.

For the sake of brevity I have not shown you how to add a LifeCycleListener handler to the window to to close down the application cleanly when the user presses the close "x". To see how, refer to HelloWorld.java in the java-gnome-code.tar file under Sample Code Listings.

It's not very exciting but you've just created a native GTK application running in the Java programming language that will respond to any GNOME theme change you make on the desktop. Try it and see what I mean. In GNOME use Start Menu -> Preferences-> Theme to switch between Nimbus and Blueprint.

Figure 2a: "Hello World" Displayed in the Nimbus Theme in GNOME

Figure 2b: "Hello World" Displayed in the Blueprint Theme in GNOME

When you click the button nothing happens, so you need to add an action handler, just as you would in any Java desktop application framework. This is an org.gnu.gtk.event.ButtonListener.

Add the following button listener to the Hello constructor after the button, btn, has been created.

btn.addListener(new ButtonListener() {
	public void buttonEvent(ButtonEvent e) {
	 	if (e.isOfType(ButtonEvent.Type.CLICK))
	            { System.out.println("Hello cruel world!"); } } });

If there are any issues in your code, the NetBeans IDE will make suggestions through a little light bulb that appears to the right side of the code as you type. Note that you can also open these code hints by typing Ctrl-Space. So as you type in the aforementioned code, a light bulb will appear. Clicking on the light bulb prompts you to add an import statement for ButtonListener and then ButtonEvent and ButtonEvent.Type. (All very handy for those of us who are a little absent-minded.)

Figure 3: Code Hints in the NetBeans IDE

Running the application now and clicking on the Hello World button will generate the "Hello cruel world!" output on the standard output.

Figure 4: "Hello World" Responding to a Button Click

You can continue to build up your UI programmatically as you have done previously, but this can become rather tedious to say the least when you are dealing with a complex real-world desktop application. Wouldn't it be much better to be able to separate the UI definition from the code that manipulates it? This is exactly what Glade is designed to do. It is a GNOME UI designer that allows you to create your UI in a WYSIWYG editor and save it out in a UI XML specification file. This Glade file can then be loaded in any GNOME application that supports the LibGlade API, which is also part of the Java GNOME bindings.

So now you can create a little more complex UI than your Hello World application in Glade and load it in your test application, thanks to Andrew Overholt, whose Flash demo I shamelessly copied (see Recommended Reading).

Launch Glade

• All Applications -> Developer Tools -> Glade User Interface Designer

The Main Glade Window will appear along with a Palette, Widget Tree, and Properties Panel.

Figure 5: Glade User Interface Designer

• Click on New to create a new project and select GTK+ Project.

Now from the Palette "GTK+ Basic" section choose Window. Add a Vertical Box with three rows to this window (just hover over the palette items to see what they are called). Then into the top row add a Label, into the middle row a Button, and into the bottom row a Text Entry widget from the palette.

To change any properties of the created widgets, just select them in the Widget Tree or the displayed window and edit their settings in the Properties panel.

• Change the window1's title to TestGlade, the label1's label to "Label's are cool," the button1's label to "Press Me!". Then resize the main window so you have something along the lines of the UI illustrated in Figure 6.
• Now create a new NetBeans Java application project called TestGlade and as before set its properties to use the JavaGnomeLib. Then go back to the Glade main window and save the Glade project into the NetBeans TestGlade project directory under a new glade directory, setting the project name to "TestGlade." This will save the UI specification under glade/testglade.glade.

Figure 6: TestGlade UI Created in the Glade UI Designer

To get your GNOME application to use the new Glade UI you need to load the Glade file in our application constructor.

public TestGlade() {
    LibGlade glade = new LibGlade("glade/testglade.glade", this);
  }

The NetBeans IDE will prompt you to add your import for LibGlade and also prompt you to add a try block around this call as it will throw an exception if the Glade file is not found or the XML is malformed. For a full listing refer to TestGlade.java in the java-gnome-code.tar file under Sample Code Listings.

So this is certainly a simple way to create a UI but it's not doing very much at present. What you need to do is somehow pass user events to your application code where you can respond to them. Glade signal handlers provide the tool needed.

In Glade if you want to have your Java code respond to any user interaction, you need to associate a signal handler with the widget in Glade and then provide a signal handler implementation in your code, in much the same way as you set up action handlers in the first example. You can associate a broad range of signal handlers with any given widget in Glade. These signal handlers can then be implemented in your application code and will be triggered whenever the appropriate user interaction occurs within the running application.

It should be stressed that the signal handler and the Java implementation must have exactly the same name for all this to work. You can take the default name Glade and generate or modify it in Glade to something else as long as your Java method implementation has the same name.

Extend the TestGlade application so that upon clicking the "Press Me!" button it will display a message "Button Clicked!" to the standard output window.

First go back to your Test Glade project in Glade.

• Select button1 and in the Properties dialog click on the Signals tab. Click on the Signal selection "..." button and choose the "clicked" signal. Click Add to add the signal handler.

This creates a handler on_button1_clicked. Save the Glade project.

Here's a screen shot of Glade being used to set up the button1 signal handler on_button1_clicked in the Signals tab of the Properties dialog.

Figure 7: Adding a Signal Handler in the Glade UI Designer

Go back to the NetBeans TestGlade project.

• Add in an implementation for the "Press Me!" clicked signal handler.

public void on_button1_clicked() {
    System.out.println("Button Clicked!");
  }

Run the TestGlade application and click on the "Press Me!" button to see the signal handler in action.

When your application responds to user interaction in your signal handlers, you may need to access one or more of the UI widgets to modify the application in some way. For instance, when you click on "Press Me!" rather than just typing out a fixed message, you'd like the application to display on the standard output whatever text the user has entered in the Text Entry widget.

To do this you need to get a handle to the Glade widget and store this internally in the class for reference by the on_button1_clicked signal handler. In production code you would check that "entry" exists after the getWidget() call, if the getWidget() call did not throw an exception.

LibGlade glade = new LibGlade("glade/testglade.glade", this);
entry = (Entry)glade.getWidget("entry1");

When you type in the previous code, the NetBeans IDE will prompt you to "Create field entry in testglade.TestGlade" to add a "private Entry entry;" instance variable for yourself. You then change the signal handler to access the text in the Text Entry widget.

public void on_button1_clicked() {
    System.out.println("User typed: " + entry.getText());
  }

As an example of a little more interesting application I took the NetBeans BlueJ Calculator example (created by David J. Barnes and Michael Kolling) and ported it over to use a Glade UI and the Java GNOME API. The core calculation CalcEngine is essentially unchanged. For code listings refer to the conclusion of this article.

Figure 8: Java GNOME Calculator Example

Since the engine only supports addition and subtraction, I modeled the UI on the GNOME Calculator in the Solaris OS using Glade and just set the Sensitivity to "No" to disable unsupported buttons (Properties Panel -> Common Tab).

If you look at the code it is worth pointing out a few things.

GNOME application -- This is a GNOME application as opposed to a GTK+ application. This means that when you create a GNOME application in Glade you can create an application window in the Palette "GNOME" section as opposed to using a plain window as your starting point. The application window has a top-level menu, a toolbar, and an app bar (status message) that you can edit as required.

This is initialized slightly differently than the GTK applications already discussed using Program.initGnomeUI:

public static void main(String[] args) {

    Program prog = Program.initGnomeUI("Calculator", "1.0", args);

    new CalculatorApp();

    Gtk.main();

  }

Passing named objects to the signal handlers -- Sometimes you need to associate a given object with a signal handler and have it passed to the signal handler when it is triggered by the UI. In the calculator example for instance, rather than having a separate signal handler for each function button, you wanted to have just one signal handler and process the user input depending on which button the user had pressed. The way to do this in Glade is when you set up the signal handler for a button, also set the Object field to the name of the button. In this way the named button will be passed to the signal handler. To process this object just use the overloaded signal handler signature in your Java code, which takes the appropriate Event widget and a generic target Object, which must then be cast appropriately to use.

public void on_button_clicked(ButtonEvent event, Object target) {
    // Get the Named Button Widget set as the Signal Handler Object in Glade

    String command = ((Button) target).getLabel();

    System.out.println("Button Clicked: " + command);


    if( command.equals("0") || command.equals("1") ||
        command.equals("2") || command.equals("3") ||

	:

GConf -- This is GNOME's configuration system and should be used by applications to store user application preferences and data. In addition it can also be used by applications to retrieve GNOME system-wide data that are of use to the application, such as network proxy settings for a networked client. To demonstrate the use of GConf a number of functions have been added to UserInterface.java to both initialize GConf and get/set the last number typed into the calculator. This data is persisted between invocations of the calculator in the GConf system if you close the application using the File-> Quit menu. The use of GConf just requires you to get a handle on the GConf system. You then instruct the ConfClient which directories you want to interact with and after that you use this client instance to create, get, and set the GConf key values.

private final String lastResultKey = 
        "/apps/javagnome_calculator_app/last_result";
		:
public void setupGconfAccess() {
  client = ConfClient.getInstance();
  try {

    client.addDirectory("/apps/javagnome-calculator-app", 
        ConfClientPreloadType.NONE);
     
     :
 public String getGconfKeyValue(String configKey){
   try {
      return client.getString(configKey);
      :

 public void setGconfKeyValue(String configKey, String configKeyValue){
   try {
      if (null != configKeyValue)
        client.setString(configKey, configKeyValue);
      :

You can also add a ConfClientListener to the ConfClient instance to get notification for changes in specific GConf key values, if you want, using client.addListener (listener, configKey).

There is a lot more to do. Check out the examples provided with the Java GNOME bindings. In particular, look at the following TestGtk and TestGnome applications:

/usr/share/lib/java/javadoc/java-gnome/libgtk-java-##/examples/testgtk/TestGTK

/usr/share/lib/java/javadoc/java-gnome/libgnome-java-##/examples/testgnome/TestGNOME

GConf and Glade examples are also found under the libgconf and libglade subdirectories under the aforementioned javadoc/java-gnome directory. Check out some of the real-world applications on the Java GNOME community site (refer to "Java GNOME applications" in the Recommended Reading section). Feel free to drop on by the #java-gnome channel (irc.gimp.net) to chat with the developers and ask any questions you might have about using the bindings. If you create a cool app let them know, so they can help you strut your stuff!

The Java GNOME bindings offer developers who are already familiar with Glade-based GNOME/GTK+ application development a viable route to developing these types of desktop applications in the Java programming language. At present you can find reasonable coverage of the core libraries, but there are some obvious omissions, such as GNOME applet support and system tray support.

The Java GNOME community is already in the middle of a redesign of the bindings to allow a more automated generation of the bindings. This will help to provide nearly 100 percent API coverage of all the underlying GNOME platform and Cairo native libraries and ensure that they stay in sync with future releases of the GNOME platform.

Be sure to check out the community site for the latest updates. The community is always happy to get new contributors to the project. So get hacking in Java GNOME!

John Rice is a staff engineer at Sun who has been working with the OpenSolaris Desktop group over the past number of years. Before this he spent time with the OpenOffice team, helping to automate migration of macros from Microsoft Office to OpenOffice. He has more than 18 years of development experience in the software industry, mostly in the area of document management and desktop application development. A member of the GNOME Advisory Board, John lives by the sea on the east coast of Ireland and can be found at unseasonably early hours of the morning running along the nearby shore, preparing for his next marathon.

• Java GNOME community documentation
• Selected Tutorials and Demos:
• Glade2 tutorial
• Andrew Overholt's Eclipse + Java GNOME Flash demo
• Java GNOME Mailing Lists and IRC:
• java-gnome-developer@lists.sourceforge.net
• irc.gimp.net in #java-gnome
• GNOME Language Bindings
• GNOME Platform Bindings Requirements
• GNOME GConf Configuration System

Solaris Express, Developer Edition 2/07 - Java GNOME 2.16 installation:

• Installed packages:
  • SUNWgnome-base-libs-java
  • SUNWgnome-libs-java
  • SUNWgnome-config-java
  • SUNWgnome-terminal-java
• API jars (/usr/share/lib/java/):
  • cairo1.0.jar
  • glib0.4.jar
  • gtk2.10.jar
  • gnome2.12.jar
  • glade2.12.jar
  • gconf2.12.jar
  • vte0.12.jar
• API libraries (/usr/lib/):
  • libcairojni.so
  • libglibjni.so
  • libgtkjni.so
  • libgnomejni.so
  • libgladejni.so
  • libgconfjni.so
  • libvtejni.so
• API Javadoc: /usr/share/lib/java/javadoc/java-gnome/*/index.html
• API source jars: /usr/share/lib/java/src/java-gnome/*-src.jar
• API examples: /usr/share/lib/java/javadoc/java-gnome/*/examples/
• Man page (3): man java-gnome
• NetBeans IDE 5.5 download
• OpenSolaris.org Java Desktop System Project

Sample code listings are available in the java-gnome-code.tar file. The contents of the tar file are listed here:

java-gnome-code/
java-gnome-code/testglade/
java-gnome-code/testglade/TestGlade.java
java-gnome-code/testglade/glade/
java-gnome-code/testglade/glade/testglade.glade.txt
java-gnome-code/licensing.txt
java-gnome-code/hello/
java-gnome-code/hello/Hello.java
java-gnome-code/calculator/
java-gnome-code/calculator/UserInterface.java
java-gnome-code/calculator/CalcEngine.java
java-gnome-code/calculator/CalculatorApp.java
java-gnome-code/calculator/glade/
java-gnome-code/calculator/glade/calculator.glade.txt

Note: Files ending in glade.txt should be renamed as .glade files before use.