GNOME Programming in Linux using GTK+ LG #70

This article provides us with an overview of GNOME Programming in Linux using GTK+ Toolkit. Please note: It is assumed that the reader knows the basics of getting around in Linux, knows how to use the GNOME environment, and possesses the required level of C and/or C++ programming experience.

The code samples that have been provided along with the text, have been checked on a computer system with the following configuration: Compaq Presario 4010 Series computer system, 15.5 GB Hard Disk Space, 96 MB RAM, 400 MHz Intel Celeron Processor, Red Hat Linux 7.1 Distribution Release underlying kernel: 2.4.2-2

This article has been divided into the following sections for easy understanding of the subject matter:

Before entering into the exciting world of Gnome programming in Linux, let's try to understand what Gnome actually refers to. GNOME is the acronym for "GNU's Not Unix Network Object Model Environment". Though it sounds a bit complicated, Gnome is a software project with a simple aim: To provide all Linux users with an extremely user-friendly, yet a powerful and complete programming Desktop environment. GNOME is currently the default Desktop system installed with the latest releases of Red Hat and Debian Distribution releases of Linux.

For more specific info on GNOME and it's various wonderful features, make sure you check out the GNOME Project home page at http://www.gnome.org which provide readers with a wealth of information on GNOME, including online documentation, news; and one could also download the binaries and source code of GNOME compatible with most Linux systems.

Now let's look at GNOME from both a "Linux programmer's" as well as a "Linux System Administrator's" point of view. The basic question that comes to mind is: do they think and feel the same when they talk about GNOME? The answer to this question is not so easy to answer. Most Linux system administrators currently are/or have been Linux programmers in the past or so, which makes it quite difficult to answer this question. For an average Linux system administrator, the GNOME environment provides a wealth of tools that makes his/her administrative job so simple. Meanwhile, the the GNOME programmer has a responsibility to continue providing these facilities by designing even better programs. So, they are in perfect harmony with each other as far as their respective works are concerned.

Now let's take a bit closer look at Gnome's functionality. GNOME is actually a programming layer that is placed in between the X Window System (or X) and the Window Manager software. Thus, as mentioned earlier, it provides Linux GUI programmers with an enormous functionality that they can then harness to design Linux based programs. But most significant of all, the reason why GNOME is nearly indispensable for all Linux/Unix developers is because GNOME provides these developers/programmers with an Integrated Framework which was specifically designed for building open-source applications with a consistent graphical user interface.

The GNOME Project started in August, 1997. Some of the initial founders included, amongst others, Peter Mattis, Spencer Kimball, Richard Stallman, and Erik Troan and Mark Ewing of Red Hat, Inc.

GNOME's extremely powerful, yet flexible architecture is what provides GNOME its terrific functionality. The base toolkit in GNOME is named GTK+(the GIMP toolkit). It was originally written for using in GIMP(GNU Image Manipulation Program). The proper understanding of GTK+ is extremely necessary for the understanding of GNOME Programming. GTK+ is an object-oriented, cross-platform language-neutral toolkit that is primarily used for creating applications independently of GNOME. Then the question that comes up is: Then why was GTK+ chosen as the toolkit for GNOME? The answer is simple: It was for its support for many programming languages including C, C++, PERL, Python, ADA etc. But it is helpful to keep in mind always that both GNOME as well as GTK+ was written using C; so we would be dealing here with C only.

Another question that should come up in the reader's mind is: Hey, what do these things called "Toolkits" contain? Toolkits like GTK+, Qt (the KDE Environment is based on Qt) are collections of widgets. Which brings us to the question: What are "Widgets"?

Widgets are GUI objects like buttons, menus, dialog boxes and other such objects or object-related general functions. This can be compared with Active Template Library (ATL 3.0) on the Microsoft Platform, which provides Component Object Model (COM) developers with a ready-made framework for creating COM Objects and Components (ActiveX EXEs & ActiveX DLLs).

GLIB data type	C language type
gchar	char
gshort	short
glong	long
gint	int
gboolean	boolean
gpointer	void*

8. A vital requirement for proper understanding of GTK+ is the concept of "Widget Hierarchy". Widgets in GTK+ belong to a hierarchy so that functions that are common to a set of widgets need only be implemented once.

For example, the function gtk_widget_show. This leads to removal of duplicate code, thus leading to better and faster program development. New widgets are derived from existing higher-level widgets so that only the unique features of this widget are to be written by the programmer. For example, let's look closely at this particular widget hierarchy:

Thus, if you look carefully, you can see that GnomeApp widget is derived from the higher-level GtkWindow, which itself has been derived from the higher-level GtkBin and so on. If we take into the consideration the essential features of the C++ programming language, well, this reminds us of the concept of "Inheritance". Doesn't it? Well, surely it does. And it is this feature of the "Widget Hierarchy" that incorporates the derived functionality in GTK+.

Let's now take a brief look at the widget creation functions. For these functions to operate correctly, one must make sure that all the GNOME and GTK+ libraries are correctly installed. Another important thing to be kept in mind is that the library's path must be correctly set before trying to compile any code.

Let's first consider the widget creation function, gnome_app_new(). This function as shown returns a GtkWidget pointer, which is the generic widget. This maybe shown as:

Please note that this also means that if we want to call a GnomeApp specific function such as gnome_app_set_menus(), then we have to use a macro to perform the cast from a GtkWidget type to a GnomeApp type; which is only possible because GnomeApp is derived from GtkWidget (see hierarchy above).

The best way to learn Linux programming is to understand the internal workings of the kernel and by doing programming yourself. So, let's now look at a small program to understand the subject matter better.

Boot your system in Linux, and if you are in the CLI (command line interface) mode, switch over to gnome, using the command "switchdesk gnome", and then issue a "startx" command to boot into the X Window System GUI mode. Once into the GNOME environment, open the GNOME Terminal, create a file named myapp.c using vi, and type in the following:

Now, to compile the program myapp.c, make sure you type in: (note the back-ticks carefully)

Note, GNOME comes with a shell script named gnome-config that supplies the compiler with the correct flags required for compilation. Once compiled, run the program using the command:

An empty window will appear on the screen, which you can move, resize, as well close. Now, let's take a closer look at the code. At the top, we introduced a few commented lines, describing the program, it's creator and date of creation. Though not necessary, it's a good programming practice to include those to each and every program. Then, we included the header file, gnome.h, that takes care of all necessary GNOME and GTK+ library functions and definitions. Then comes "ghosh", which is a GtkWidget pointer. This would point to our new Window object. The function gnome_init is then called. It initializes libraries, and is used for correct session management. The ID passed to this gnome_init function is "sample", the version number being "0.1", and then the usual command line arguments of main. These are necessary for the internal workings of GNOME. Then comes the function gnome_app_new(), which when executed, creates our window. This takes two arguments, as shown in the sample code: "sample" and "My Window". "sample" is the application name, and "My Window" is the window title. But please note: Though the name of this function is gnome_app_new(); it does NOT create any sort of new application or so. It creates a top-level window, that's all. The next function called is gtk_widget_show(), which makes our window visible. Next comes gtk_main() which is a very important function, as it makes sure that GNOME functions such as events nd button presses are executed, by handing on the functionality to GNOME.

Now let's take a deeper look into the GNOME programming environment: "Signals" and "Callbacks". What are these and what are they used for? Do we really need them? Every single time the mouse moves, enters and leaves widgets, buttons are pressed, toggle buttons are toggled on or off, and such things are done, a signal is sent to the application. This signal can be passed to a callback function. So, though not always, yet at times, applications need to connect to these events for taking certain actions. In GNOME/GTK+, we call a function called gtk_signal_connect to connect signals to handler functions.

It should be noted that various kinds of widgets emit different signals. The signals from buttons are as follows:

We will look into signals and callbacks playing a vital role in the applications that we would develop later.

Next, we look into another vital component of GNOME programming: containers. GTK+ uses containers a great deal, because GTK+ is actually a "container-based" toolkit. That means we have a parent container within which we have to place our other widgets. Windows are single widget containers. Thus, the important point to keep in mind is that GTK+ utilizes invisible "packing boxes" which can hold multiple widgets to create windows layouts. These "packing boxes" are of two types: horizontal and vertical, created by using the functionality of the functions gtk_hbox_new and gtk_vbox_new, respectively. We would see these functions in action soon, in the applications that we create later. For now, let's take a look into the parameters of these two functions. They have the following parameters:

Next we come to another very vital component: Buttons. GTK+ provides 4 different kinds of buttons:

Creating radio buttons is very similar to check boxes, and all that we need to do extra is to specify a group the radio button belongs to. Radio buttons are derived from check buttons, which are derived from toggle buttons, so this means that we have the same set of functions to read and modify their state and also use the same old events. Please note: For more information of specific functions, consult the GTK+ Reference Documentation available at: http://www.gtk.org

For creating single-line text widgets, which are commonly called "Entry widgets", we utilize a function called gtk_entry_new(). Entry widgets are mainly used to enter small amounts of information. Let's know take a look at a program that creates a "Login Window", and outputs the password field, when the activate signal occurs, when the button is pressed. Type in the following and execute the program as has been explained above.

/* Creating a Login GNOME-style using GTK+ Toolkit:
Created By: Subhasish Ghosh
Date: Wednesday, August 8, 2001
*/

static void enter_pressed(GtkWidget *button, gpointer data)
{
GtkWidget *text_entry = data;
char *string = gtk_entry_get_text(GTK_ENTRY(text_entry));
g_print(string);
}

int main(int argc, char *argv[])
{
GtkWidget *app;
GtkWidget *text_entry;
GtkWidget *label;
GtkWidget *hbox; gchar *text;

gnome_init("example", "0.1", argc, argv);
app = gnome_app_new("example", "entry widget");
gtk_container_border_width(GTK_CONTAINER(app), 5);

/* we now create a Label: */
label = gtk_label_new("Password: ");
gtk_misc_set_alignment(GTK_MISC(label), 0, 1.0);
gtk_box_pack_start(GTK_BOX(hbox), label, FALSE, FALSE, 0);

text_entry = gtk_entry_new();
gtk_entry_set_visibility(GTK_ENTRY(text_entry), FALSE);
gtk_box_pack_start(GTK_BOX(hbox), text_entry, FALSE, FALSE, 0);

gtk_signal_connect(GTK_OBJECT(app), "delete_event", GTK_SIGNAL_FUNC(gtk_main_quit), NULL);
gtk_signal_connect(GTK_OBJECT(text_entry), "activate", GTK_SIGNAL_FUNC(enter_pressed), text_entry);

gnome_app_set_contents(GNOME_APP(app), hbox);
gtk_widget_show_all(app);
gtk_main( );
return 0;
}

This program when executed, a login window should appear on the screen. Type in any text (assuming it to be a password), press enter and observe what happens.

List boxes and Combo boxes play the same role as they play on the Microsoft platform. List box widgets hold a list of strings that allow users to select one or more entries; concerned the widget is so configured. Combo boxes are entry widgets with an added pull-down menu that allow users to select options also.

The various widgets that we have come across until now are simple widgets that don't provide some extra-ordinary functionality. We now look at some specific GNOME programming libraries that offer more complicated widgets with rich functionality.

Just hang on for a second, someone may ask: "Hey, we were doing pretty well with ordinary code and all the stuff that you discussed earlier. What's the use of this so-called "specific GNOME programming libraries"? Are they indeed useful? Or are you just including them here for making your article a bit longer?"

Well, here's the reason for considering specific GNOME programming libraries. With plain GTK+ code, though nearly everything can be done, which we usually would do using specific GNOME programming libraries, but using simple and plain GTK+ code often leads to much code repetition, inefficient code blocks and such other things, making the whole program a bloated one. Now, to prevent this from happening, we use specific GNOME programming libraries that provide a great deal of extra functionality and much lower programming overhead.

So, let's talk about "Menus" and "Toolbars". GNOME lets us create menus and toolbars for our GnomeApp widgets that can be docked and undocked from the window. First you fill up arrays with the necessary information, then call gnome_app_create_menus or gnome_app_create_toolbar.

The menus and toolbar items each have properties, defined in arrays. A few such properties include type, string, callback pointer, etc. Most of the time the menu entries are pretty simple, and we can just use one of a set of macros provided by GNOME to create the structure for us. So let's check out a few of the most used top-level macros.

Please note: These macros are the ones that create top-level menus when passed an array containing any or all of the following GnomeUIInfo structures.

Menu	Macro
File	GNOMEUIINFO_MENU_FILE_TREE(tree)
Edit	GNOMEUIINFO_MENU_EDIT_TREE(tree)
View	GNOMEUIINFO_MENU_VIEW_TREE(tree)
Settings	GNOMEUIINFO_MENU_SETTINGS_TREE(tree)
Windows	GNOMEUIINFO_MENU_WINDOWS_TREE(tree)
Help	GNOMEUIINFO_MENU_HELP_TREE(tree)
Game	GNOMEUIINFO_MENU_GAME_TREE(tree)

Within the top-level menu there exists over thirty macros for creating common menu items. The macros associate small images (pixmaps) and accelerator keys with each menu item. A callback function is required to be called when the item is selected and a data pointer is to be passed to that function.

File -->>
New --> GNOMEUIINFO_MENU_NEW_ITEM (label, hint, cb, data)
Open --> GNOMEUIINFO_MENU_OPEN_ITEM (cb, data)
Save --> GNOMEUIINFO_MENU_SAVE_ITEM (cb, data)
Print --> GNOMEUIINFO_MENU_PRINT_ITEM (cb, data)
Exit --> GNOMEUIINFO_MENU_EXIT_ITEM (cb, data)

Edit -->>
Cut --> GNOMEUIINFO_MENU_CUT_ITEM (cb, data)
Copy --> GNOMEUIINFO_MENU_COPY_ITEM (cb, data)
Paste --> GNOMEUIINFO_MENU_PASTE_ITEM (cb, data)

Like menu bars, toolbars require an array using the GNOMEUIINFO_ITEM_STOCK (label, tooltip, callback, stock_id) macro. Here, "stock_id" is the id of a predefined icon that we want to use for that item.

static void callback (GtkWidget *button, gpointer data)
{
g_print("Item Selected");
}

GnomeUIInfo file_menu[ ] = {
GNOMEUIINFO_ITEM_NONE ("A menu item", "This is the Status bar info", callback),
GNOMEUIINFO_MENU_EXIT_ITEM (gtk_main_quit, NULL),
GNOMEUIINFO_END
};

GnomeUIInfo menubar[ ] = {
GNOMEUIINFO_MENU_FILE_TREE (file_menu),
GNOMEUIINFO_END
};

GnomeUIInfo toolbar[ ] = {
GNOMEUIINFO_ITEM_STOCK ("Print", "This is another tooltip", callback, GNOME_STOCK_PIXMAP_PRINT),
GNOMEUIINFO_ ITEM_STOCK ("Exit", "Exit the application", gtk_main_quit, GNOME_STOCK_PIXMAP_EXIT),
GNOMEUIINFO_END
};

gnome_init ("example", "0.1", argc, argv);
app = gnome_app_new ("example", "A Sample Toolbar and Menu");

gnome_app_create_menus (GNOME_APP (app), menubar);
gnome_app_create_toolbar (GNOME_APP (app), toolbar);

This program creates a small window with an embedded menu and toolbar. You can click, dock, undock and drag it around the screen.

Let's now look at the widget that displays textual information to the user in the GNOME environment. Yes, we are referring to the Dialog box. When we need to create dialog boxes, we call the gnome_message_box_new function and pass it the message text, also mention the type of dialog box we need, and the buttons we want on it. All of this mentioned in a NULL terminated list. Then we bind the "clicked" signal of the dialog widget that we have just created to a handling function that is passed the button that the user pressed as an integer. Finally, we call the gtk_widget_show function for displaying a non-modal box.

Let's look at this code extract from a program, which creates a simple question dialog box, adds three buttons and responds to the user's code.

dlg = gnome_message_box_new("Hi, pal, how are you doing??? I am fine!",
GNOME_MESSAGE_BOX_QUESTION,
GNOME_STOCK_BUTTON_OK,
GNOME_STOCK_BUTTON_APPLY,
GNOME_STOCK_BUTTON_CLOSE,
NULL);

gtk_signal_connect (GTK_OBJECT(dlg), "clicked", GTK_SIGNAL_FUNC(messagebox_clicked), NULL);

This sums up our journey of the exciting world of GNOME programming using GTK+ toolkit.

Please note: GNOME Programming is not at all difficult. Once you have a little understanding, it's really easy to grasp. There is still much more to learn after this article, but if done diligently, it can definitely be mastered.

For more information and detailed coverage of this topic, check out the following links:

"Linux Gazette...making Linux just a little more fun!"

GNOME Programming in Linux using GTK+

By Subhasish Ghosh

Subhasish Ghosh

Copyright © 2001, Subhasish Ghosh.
Copying license http://www.linuxgazette.com/copying.html
Published in Issue 70 of Linux Gazette, September 2001

"Linux Gazette...making Linux just a little more fun!"

GNOME Programming in Linux using GTK+

By Subhasish Ghosh

Subhasish Ghosh

Copyright © 2001, Subhasish Ghosh. Copying license http://www.linuxgazette.com/copying.html Published in Issue 70 of Linux Gazette, September 2001

Copyright © 2001, Subhasish Ghosh.
Copying license http://www.linuxgazette.com/copying.html
Published in Issue 70 of Linux Gazette, September 2001