Academic Tutorials

English | French | Portugese | German | Italian
Home Advertise Payments Recommended Websites Interview Questions FAQs
News Source Codes E-Books Downloads Jobs Web Hosting

Gnome Introduction
Gnome GTK Programming
Gnome GTK+
Gnome Programming
Gnome Libgnome Library
Gnome Framework
Gnome libgnomeui Library
Gnome Widget
Gnome Drag and Drop
Gnome Building
Gnome Application
Gnome Application - Part 2

HTML Tutorials
HTML Tutorial
XHTML Tutorial
CSS Tutorial
TCP/IP Tutorial
CSS 1.0
CSS 2.0
XML Tutorials
XML Tutorial
XSL Tutorial
XSLT Tutorial
DTD Tutorial
Schema Tutorial
XForms Tutorial
XSL-FO Tutorial
XML DOM Tutorial
XLink Tutorial
XQuery Tutorial
XPath Tutorial
XPointer Tutorial
RDF Tutorial
SOAP Tutorial
WSDL Tutorial
RSS Tutorial
WAP Tutorial
Web Services Tutorial
Browser Scripting
JavaScript Tutorial
VBScript Tutorial
DHTML Tutorial
HTML DOM Tutorial
WMLScript Tutorial
E4X Tutorial
Server Scripting
ASP Tutorial
PERL Tutorial
SQL Tutorial
ADO Tutorial
Apple Script
PL/SQL Tutorial
SQL Server
.NET (dotnet)
.Net Mobile
C# : C Sharp
SVG Tutorial
Flash Tutorial
Media Tutorial
SMIL Tutorial
Photoshop Tutorial
Gimp Tutorial
Gnuplot Programming
GIF Animation Tutorial
Scientific Visualization Tutorial
Web Building
Web Browsers
Web Hosting
W3C Tutorial
Web Building
Web Quality
Web Semantic
Web Careers
Weblogic Tutorial
Web Site Hosting
Domain Name
Java Tutorials
Java Tutorial
JSP Tutorial
Servlets Tutorial
Struts Tutorial
EJB Tutorial
JMS Tutorial
JMX Tutorial
Programming Langauges
C Tutorial
C++ Tutorial
Visual Basic Tutorial
Data Structures Using C
Assembly Language
Forth Programming
Lisp Programming
Data Warehousing
CGI Programming
Emacs Tutorial
Soft Skills
Communication Skills
Time Management
Project Management
Team Work
Leadership Skills
Corporate Communication
Negotiation Skills
Database Tutorials
Operating System
Software Testing
SAP Module
Business Warehousing
SAP Basis
Material Management
Sales & Distribution
Human Resource
Customer Relationship Management
Production and Planning
Networking Programming
Corba Tutorial
Networking Tutorial
Microsoft Office
Microsoft Word
Microsoft Outlook
Microsoft PowerPoint
Microsoft Publisher
Microsoft Excel
Microsoft Front Page
Microsoft InfoPath
Microsoft Access
Financial Accounting
Managerial Accounting
Network Sites

Using The Libgnomeui Library

Previoushome Next

Using the libgnomeui Library

Besides GnomeApp, the libgnomeui library contains a whole number of other objects and widgets, including standard dialogs, session managment, MDI, and other utility widgets.

It also contains the GnomeCanvas widget, which deserves separate treatment. This is the library that makes the programmers life easy. It is important that you use these widgets rather then plain GTK+ ones as these widgets give you consistency and features that a user of a GNOME application expects.

Stock Icons

Since most of the time you will want to use standard buttons and menu items (such as Open or Save as...), and you want to provide icons with the menu items or tool-bar buttons or just dialog buttons, to make it easier to navigate, you can use some of the predefined icons from gnome-libs. These are called Stock Icons. You have already seen an example of how to use stock menu icons and regular stock icons in menus and tool-bars (you just use the proper define from libgnomeui/gnome-stock.h). There are also stock buttons, where you can get back a button widget based on a stock description.

Here is a list of the normal gnome stock icons, these are regular sized for use in tool-bars and other places where you need a normal sized icon. They are given as defines of string constants and their meaning should be obvious.

#define GNOME_STOCK_PIXMAP_NEW         "New"
#define GNOME_STOCK_PIXMAP_OPEN        "Open"
#define GNOME_STOCK_PIXMAP_CLOSE       "Close"
#define GNOME_STOCK_PIXMAP_REVERT      "Revert"
#define GNOME_STOCK_PIXMAP_SAVE        "Save"
#define GNOME_STOCK_PIXMAP_SAVE_AS     "Save As"
#define GNOME_STOCK_PIXMAP_CUT         "Cut"
#define GNOME_STOCK_PIXMAP_COPY        "Copy"
#define GNOME_STOCK_PIXMAP_PASTE       "Paste"
#define GNOME_STOCK_PIXMAP_HELP        "Help"
#define GNOME_STOCK_PIXMAP_SCORES      "Scores"
#define GNOME_STOCK_PIXMAP_PRINT       "Print"
#define GNOME_STOCK_PIXMAP_SEARCH      "Search"
#define GNOME_STOCK_PIXMAP_SRCHRPL     "Search/Replace"
#define GNOME_STOCK_PIXMAP_BACK        "Back"
#define GNOME_STOCK_PIXMAP_FORWARD     "Forward"
#define GNOME_STOCK_PIXMAP_FIRST       "First"
#define GNOME_STOCK_PIXMAP_LAST        "Last"
#define GNOME_STOCK_PIXMAP_HOME        "Home"
#define GNOME_STOCK_PIXMAP_STOP        "Stop"
#define GNOME_STOCK_PIXMAP_REFRESH     "Refresh"
#define GNOME_STOCK_PIXMAP_UNDO        "Undo"
#define GNOME_STOCK_PIXMAP_REDO        "Redo"
#define GNOME_STOCK_PIXMAP_TIMER       "Timer"
#define GNOME_STOCK_PIXMAP_TIMER_STOP  "Timer Stopped"
#define GNOME_STOCK_PIXMAP_MAIL        "Mail"
#define GNOME_STOCK_PIXMAP_MAIL_RCV    "Receive Mail"
#define GNOME_STOCK_PIXMAP_MAIL_SND    "Send Mail"
#define GNOME_STOCK_PIXMAP_MAIL_RPL    "Reply to Mail"
#define GNOME_STOCK_PIXMAP_MAIL_FWD    "Forward Mail"
#define GNOME_STOCK_PIXMAP_TRASH       "Trash"
#define GNOME_STOCK_PIXMAP_MIC         "Microphone"
#define GNOME_STOCK_PIXMAP_LINE_IN     "Line In"
#define GNOME_STOCK_PIXMAP_CDROM       "Cdrom"
#define GNOME_STOCK_PIXMAP_VOLUME      "Volume"
#define GNOME_STOCK_PIXMAP_ABOUT       "About"
#define GNOME_STOCK_PIXMAP_QUIT        "Quit"
#define GNOME_STOCK_PIXMAP_NOT         "Not"
#define GNOME_STOCK_PIXMAP_CONVERT     "Convert"
#define GNOME_STOCK_PIXMAP_JUMP_TO     "Jump To"
#define GNOME_STOCK_PIXMAP_UP          "Up"
#define GNOME_STOCK_PIXMAP_DOWN        "Down"
#define GNOME_STOCK_PIXMAP_TOP         "Top"
#define GNOME_STOCK_PIXMAP_BOTTOM      "Bottom"
#define GNOME_STOCK_PIXMAP_ATTACH      "Attach"
#define GNOME_STOCK_PIXMAP_INDEX       "Index"
#define GNOME_STOCK_PIXMAP_FONT        "Font"
#define GNOME_STOCK_PIXMAP_EXEC        "Exec"




If you need to use these outside of GnomeUIInfo, you need to get the widget with the pixmap. What you do is you call the gnome_stock_pixmap_widget function with your main window as the first argument (so that it can copy it's style) and the icon name (one of the above defines) as the second argument. It returns a new widget which you can just use as a pixmap.


For menus you want to use the _MENU_ variety of the stock pixmaps. These are smaller and these should be the ones you use for the stock menu items in your GnomeUIInfo definitions.

#define GNOME_STOCK_MENU_BLANK        "Menu_"
#define GNOME_STOCK_MENU_NEW          "Menu_New"
#define GNOME_STOCK_MENU_SAVE         "Menu_Save"
#define GNOME_STOCK_MENU_SAVE_AS      "Menu_Save As"
#define GNOME_STOCK_MENU_REVERT       "Menu_Revert"
#define GNOME_STOCK_MENU_OPEN         "Menu_Open"
#define GNOME_STOCK_MENU_CLOSE        "Menu_Close"
#define GNOME_STOCK_MENU_QUIT         "Menu_Quit"
#define GNOME_STOCK_MENU_CUT          "Menu_Cut"
#define GNOME_STOCK_MENU_COPY         "Menu_Copy"
#define GNOME_STOCK_MENU_PASTE        "Menu_Paste"
#define GNOME_STOCK_MENU_PROP         "Menu_Properties"
#define GNOME_STOCK_MENU_PREF         "Menu_Preferences"
#define GNOME_STOCK_MENU_ABOUT        "Menu_About"
#define GNOME_STOCK_MENU_SCORES       "Menu_Scores"
#define GNOME_STOCK_MENU_UNDO         "Menu_Undo"
#define GNOME_STOCK_MENU_REDO         "Menu_Redo"
#define GNOME_STOCK_MENU_PRINT        "Menu_Print"
#define GNOME_STOCK_MENU_SEARCH       "Menu_Search"
#define GNOME_STOCK_MENU_SRCHRPL      "Menu_Search/Replace"
#define GNOME_STOCK_MENU_BACK         "Menu_Back"
#define GNOME_STOCK_MENU_FORWARD      "Menu_Forward"
#define GNOME_STOCK_MENU_FIRST        "Menu_First"
#define GNOME_STOCK_MENU_LAST         "Menu_Last"
#define GNOME_STOCK_MENU_HOME         "Menu_Home"
#define GNOME_STOCK_MENU_STOP         "Menu_Stop"
#define GNOME_STOCK_MENU_REFRESH      "Menu_Refresh"
#define GNOME_STOCK_MENU_MAIL         "Menu_Mail"
#define GNOME_STOCK_MENU_MAIL_RCV     "Menu_Receive Mail"
#define GNOME_STOCK_MENU_MAIL_SND     "Menu_Send Mail"
#define GNOME_STOCK_MENU_MAIL_RPL     "Menu_Reply to Mail"
#define GNOME_STOCK_MENU_MAIL_FWD     "Menu_Forward Mail"
#define GNOME_STOCK_MENU_MAIL_NEW     "Menu_New Mail"
#define GNOME_STOCK_MENU_TRASH        "Menu_Trash"
#define GNOME_STOCK_MENU_TRASH_FULL   "Menu_Trash Full"
#define GNOME_STOCK_MENU_UNDELETE     "Menu_Undelete"
#define GNOME_STOCK_MENU_TIMER        "Menu_Timer"
#define GNOME_STOCK_MENU_TIMER_STOP   "Menu_Timer Stopped"
#define GNOME_STOCK_MENU_SPELLCHECK   "Menu_Spellchecker"
#define GNOME_STOCK_MENU_MIC          "Menu_Microphone"
#define GNOME_STOCK_MENU_LINE_IN      "Menu_Line In"
#define GNOME_STOCK_MENU_CDROM        "Menu_Cdrom"
#define GNOME_STOCK_MENU_VOLUME       "Menu_Volume"
#define GNOME_STOCK_MENU_BOOK_RED     "Menu_Book Red"
#define GNOME_STOCK_MENU_BOOK_GREEN   "Menu_Book Green"
#define GNOME_STOCK_MENU_BOOK_BLUE    "Menu_Book Blue"
#define GNOME_STOCK_MENU_BOOK_YELLOW  "Menu_Book Yellow"
#define GNOME_STOCK_MENU_BOOK_OPEN    "Menu_Book Open"
#define GNOME_STOCK_MENU_CONVERT      "Menu_Convert"
#define GNOME_STOCK_MENU_JUMP_TO      "Menu_Jump To"
#define GNOME_STOCK_MENU_UP           "Menu_Up"
#define GNOME_STOCK_MENU_DOWN         "Menu_Down"
#define GNOME_STOCK_MENU_TOP          "Menu_Top"
#define GNOME_STOCK_MENU_BOTTOM       "Menu_Bottom"
#define GNOME_STOCK_MENU_ATTACH       "Menu_Attach"
#define GNOME_STOCK_MENU_INDEX        "Menu_Index"
#define GNOME_STOCK_MENU_FONT         "Menu_Font"
#define GNOME_STOCK_MENU_EXEC         "Menu_Exec"

#define GNOME_STOCK_MENU_ALIGN_LEFT     "Menu_Left"
#define GNOME_STOCK_MENU_ALIGN_RIGHT    "Menu_Right"

#define GNOME_STOCK_MENU_TEXT_BOLD      "Menu_Bold"
#define GNOME_STOCK_MENU_TEXT_ITALIC    "Menu_Italic"


If you are building the menu yourself and just want to get a menu-item that's built with the stock icon and a label, you can use the gnome_stock_menu_item convenience routine. It takes the stock icon type (one of the defines above) as the first argument, and the menu text as the second argument, and it returns a newly created menu-item widget.


Then there are stock buttons. These are for use in your dialogs (see the next section).

#define GNOME_STOCK_BUTTON_OK     "Button_Ok"
#define GNOME_STOCK_BUTTON_CANCEL "Button_Cancel"
#define GNOME_STOCK_BUTTON_YES    "Button_Yes"
#define GNOME_STOCK_BUTTON_NO     "Button_No"
#define GNOME_STOCK_BUTTON_CLOSE  "Button_Close"
#define GNOME_STOCK_BUTTON_APPLY  "Button_Apply"
#define GNOME_STOCK_BUTTON_HELP   "Button_Help"
#define GNOME_STOCK_BUTTON_NEXT   "Button_Next"
#define GNOME_STOCK_BUTTON_PREV   "Button_Prev"
#define GNOME_STOCK_BUTTON_UP     "Button_Up"
#define GNOME_STOCK_BUTTON_DOWN   "Button_Down"
#define GNOME_STOCK_BUTTON_FONT   "Button_Font"

To get a button widget with the stock icon and text, you can just use the function gnome_stock_button with the button type (one of the above defines) as the argument. Now sometimes you want to create a mixture of stock or ordinary buttons, what you can do is call the gnome_stock_or_ordinary_button function with either the type of a stock button or just a text for the button label. The function checks if it is one of the above strings, and if it's not it creates an ordinary button widget with the text as the label. Here is an example, it creates three buttons packing them into a box 'box' (I don't include code to make the box), two of the buttons are stock and one is normal:

GtkWidget *w;
GtkWidget *box;
int i;
char *buttons[]={
/* loop through all strings in buttons array */
for(i = 0; buttons[i] != NULL; i++) {

        /* create the button, stock or ordinary */
        w = gnome_stock_or_ordinary_button(buttons[i]);

        /* show and pack it */
        /* we should bind signals and other stuff here */



Generic Dialogs

If you need to create you own custom dialog, gnome-dialog is the way to do it. It can handle both modal and non-modal dialogs, although, it's definitely much more friendly to the users of your program if you use a non-modal dialog box, if at all possible, although non-modal dialog boxes tend to have problems associated with them, and sometimes can cause strange bugs, for example if a non-modal dialog box is associated with a window, you'd better bind the destroy signal of the window and set it to destroy the dialog box as well, since otherwise it could hang around even though the window or document it was supposed to act on is already dead. However modal dialogs (while definitely easier to program) are usually pretty annoying to use, so avoid them if you at all can.

To make a new GnomeDialog widget, just use the gnome_dialog_new function. You pass the title of the dialog as the first argument, and then multiple arguments as the button titles terminated by a NULL. The button titles can also be the GNOME_STOCK_BUTTON_* definitions if you want stock buttons on your dialog. Then you need to add content to the dialog, the dialog is created with a vertical box (GtkVBox) for you to use, just by using GNOME_DIALOG(dialog)->vbox. Into that you add your content.

You should also set the parent of the dialog to be your main application window (your GnomeApp). This allows the windowmanager to handle the window more appropriately rather then just like a generic window. You accomplish it with the following call:

gnome_dialog_set_parent(GNOME_DIALOG(dialog), GTK_WINDOW(app));


At this point you have to decide if you want to do a modal dialog or a non-modal dialog. In case you want to do a modal dialog, all you need to do is to call gnome_dialog_run_and_close function and it will run the dialog, wait for a user to press a button or close the dialog, and then close the dialog. This function will return the number of the button that was pressed or -1 if the dialog was just closed. In case you don't want to close the dialog when just any button is pressed, you use the gnome_dialog_run function, and after you get a result, do what you need to do for that particular button press. Then if you want to run the dialog more, you just loop back to gnome_dialog_run, and if you want to close, you run gnome_dialog_close. Here's an example of the second scheme.

GtkWidget *dlg;
GtkWidget *label;
int i;
/*create a new dialog, DON'T forget the NULL on the end,
  it is very important!*/
dlg = gnome_dialog_new("A Dialog",
/* here we assume that app is a pointer to our GnomeApp window */
gnome_dialog_set_parent(GNOME_DIALOG(dlg), GTK_WINDOW(app));
/*add some content to the dialog here*/
label = gtk_label_new("Some random content");
/*set up an infinite loop*/
for(;;) {
        i = gnome_dialog_run(GNOME_DIALOG(dlg));
        if(i == 0 || i == 2) {
                /*the user pressed OK or close, so we will get
                  out of the loop and close the dialog, or the
                  user pressed */
        } else if(i < 0) {
                /*the user closed the dialog from the window
        } else if(i == 1) {
                /*user pressed apply we don't want to close*/

By default the dialog is destroyed when closed, so you don't have to worry about it's destruction. You can change this behavior if you wish though.


If you are doing a non-modal dialog box, things get a little more complicated. You create the dialog as above, but then you bind the clicked signal of the GnomeDialog widget. That signal has as it's second argument the button number that was pressed. After that you should use the gnome_dialog_set_close function to tell GnomeDialog that we want to close the dialog when the user first presses any button, if you want that behavior, otherwise you'll have to do gnome_dialog_close in the clicked signal handler for the buttons you want to close on. After that is set up you just gtk_widget_show the dialog. An example follows:

/*the clicked signal handler*/
static void
dialog_clicked(GnomeDialog *dlg, int button, gpointer data)
        switch(button) {
        case 1:
                /*user pressed apply*/
        case 0:
                /*user pressed OK*/
                /*fall though to close*/
        case 2:
                /*user pressed close*/

/*somewhere else in the source file*/
GtkWidget *dlg;
/*create a new dialog, DON'T forget the NULL on the end, it
  is very important!*/
dlg = gnome_dialog_new("A Dialog",
/* here we assume that app is a pointer to our GnomeApp window */
gnome_dialog_set_parent(GNOME_DIALOG(dlg), GTK_WINDOW(app));
/*add some content to the dialog here*/
/*bind the clicked handler*/
/*show the dialog, note that this is not a modal dialog,
  so the program doesn't block here, but continues*/

This implements the same dialog as the modal example above, only non modal. Make sure that you have some way of destruction of the dialog in case it's no longer relevant, for example if a dialog is to modify some object, it should be destroyed when that object is destroyed. 

Message Box

GnomeMessageBox is an object derived from GnomeDialog. As such you use it in the exact same manner, the only difference here is that it automatically sets up the insides of the dialog to be a single label and an icon of the selected message box type. The message box types are as follows:

#define GNOME_MESSAGE_BOX_INFO      "info"
#define GNOME_MESSAGE_BOX_WARNING   "warning"
#define GNOME_MESSAGE_BOX_ERROR     "error"
#define GNOME_MESSAGE_BOX_QUESTION  "question"
#define GNOME_MESSAGE_BOX_GENERIC   "generic"

To create a message box, you use the function gnome_message_box_new with the first argument being the message text, the second argument being the type of the message box (one of the defines above), and then any number of buttons terminated by a NULL exactly as in the GnomeDialog's case. After created it is again used exactly the same as GnomeDialog

Property Dialogs

If you have some properties to set in your application, you should use a GnomePropertyBox dialog for the preferences to make the applications more consistent. Again this object is derived from GnomeDialog so it's use is similar. But GnomePropertyBox defines some new signals, namely apply and help. They both get passed the page number as the second argument. For help you should use this to display the proper help page, however for apply, this was created for adding a per-page apply button, which was not realized yet, so you should ignore any apply signal with the page number other then -1, which is the global apply. This can be done with a simple if statement at the top of your apply routine. You can choose to be per-page apply ready, by doing a per-page apply in your code, but it is not sure if this code will ever get completed. It should be safe to do just the global apply as that is the only thing implemented in gnome-libs 1.0.

To use property dialogs, you call gnome_property_box_new, which will create a completely new dialog for you with a notebook and the four buttons. OK, which will call your apply handler for all pages and then for the -1 page, and then it will close the dialog, Apply, which will call the apply handler for all pages and then for the -1 page, Close, which will just close the dialog, and Help which will call your help handler if you bound it. You then connect the apply signal to your apply handler, and most likely the destroy signal on the property box to destroy the data associated with the property box when it closes. You then create the different pages for your property box and add them with, gnome_property_box_append_page, which takes your page as the second argument and a label as the third (usually this will be just a GtkLabel). You also want to connect the different signals for the widgets on your pages, to mark the property box as changed (otherwise the Apply and OK buttons will not be sensitive). You do this by calling gnome_property_box_changed every time the user changed something with the widgets. For example on entry (and derived) widgets you connect to the changed signal. Example follows:

/*apply handler*/
static void
property_apply(GnomePropertyBox *box, int page_num, gpointer data)
        /*ignore page numbers other then -1*/
        /*do your apply routine here*/
/*somewhere else in the source file*/
GtkWidget *pbox;
GtkWidget *widget;
pbox = gnome_property_box_new();
/*you create a page for the property box and added it to the
  container called widget*/
/*then add other pages in similar manner*/
/*we show the dialog box*/


File Picking Dialog

Gnome doesn't have it's own file picking dialog, although this is planned for the future, for now you need to use the regular GTK+ file dialog.

Use of the file dialog is very simple. You create the dialog with gtk_file_selection_new, passing it the title of the dialog box as the argument. After this you bind the clicked signal on the OK and Cancel buttons. For example for a loading dialog box, you could check that the file is of the correct type when the user presses OK and if so then close the dialog (usually with gtk_widget_destroy). Or for saving dialog, you could ask if the file exists. File selection dialog boxes are usually safe and simple to do non-modal. Just make sure you'd destroy the file dialog box when the object or window it's supposed to work with. Here's the routine that invokes the save as dialog for Achtung, which is a presentation program we're working on.

presentation_save_as (AchtungPresentation *p)
        GtkFileSelection *fsel;
        g_return_if_fail (p != NULL);
        g_return_if_fail (p->doc != NULL);

        /* create a new file selection widget */
        fsel = GTK_FILE_SELECTION
                (gtk_file_selection_new (_("Save presentation as")));
        if (p->real_file && p->filename)
                gtk_file_selection_set_filename (fsel, p->filename);

        /* Connect the signals for Ok and Cancel */
        gtk_signal_connect (GTK_OBJECT (fsel->ok_button), "clicked",
                            GTK_SIGNAL_FUNC (save_ok), fsel);
                (GTK_OBJECT (fsel->cancel_button), "clicked",
                 GTK_SIGNAL_FUNC (gtk_widget_destroy), 

        /* set the position at the mouse cursor, we do this because this
           is not a gnome dialog and thus it isn't set for us.  You
           shouldn't do this for normal gnome dialogs though */
        gtk_window_position (GTK_WINDOW (fsel), GTK_WIN_POS_MOUSE);

        /*if the presentation dies so do it's dialogs*/
                (GTK_OBJECT (p), "destroy",
                 GTK_SIGNAL_FUNC (gtk_widget_destroy), 

        gtk_widget_show (GTK_WIDGET (fsel));

This is actually a save_as method for AchtungPresentation object in object oriented speak. AchtungPresentation is a GtkObject we use for storing all the presentation data (This is a nice example of how to use GtkObject for things not directly related to widgets or GUI programming). First we check the arguments to the function with g_return_if_fail which is for debugging purposes. Then we create a new GtkFileSelection with a title of "Save presentation as". Ignore the _() macro around the string for now, it's used for internationalization. Afterwards we check if the presentation already has a filename associated with it, and if so we set the filename on the file selection dialog to that. After that we connect the the OK button to a routine called save_ok defined elsewhere in the file and pass the file selection dialog as a data argument. Then we use connect_object to bind the Cancel button to destroying the file selection dialog. The connect_object method is similar to regular connect but when it calls the function itself it will pass the object from the data field as the first argument of the function. So connecting to gtk_widget_destroy will destroy the object passed in the data field, which is the file selection dialog. Then we position the dialog near the mouse button. In the future when this dialog is derived from GnomeDialog, you will not need to and actually should not do that, as that will be done according to use preferences as for all the other gnome dialogs. After this we use yet another signal connection method ... this time gtk_signal_connect_object_while_alive, which is similar to connect_object, but has a nice twist to it. The signal will be disconnected when the object passed in the data field dies. This needs to happen as the file dialog will most likely be destroyed before the the presentation itself is, then when the presentation is destroyed itself, it would try to destroy an already non-existent file selection dialog and most likely cause a segmentation fault and crash. This way it is safe and if the file selection dialog is still around when the presentation is destroyed, it is destroyed with it. 

About Box

You will probably want to have an "About" entry in the "Help" menu of your application, and it should display the standard about box. There is a dialog in gnome for just this sort of puprose, the GnomeAbout object. It is created with the gnome_about_new which has the following prototype

GtkWidget* gnome_about_new(const gchar *title, /* Name of the application. */
                           const gchar *version, /* Version. */
                           const gchar *copyright, /* Copyright notice
                                                      (one line.) */
                           const gchar **authors, /* NULL terminated list of
                                                     authors. */
                           const gchar *comments, /* Other comments. */
                           const gchar *logo /* A logo pixmap file. */


After you create the dialog box, you should set it's parent to be your application window with gnome_dialog_set_parent. And then you can just show the dialog. The following implements an about box dialog, we assume that VERSION has been #define'd to be the string with the version number. We also pass NULL as the logo, meaning we have no logo picture to display.

GtkWidget* dlg;
char *authors[] = {
        "George Lebl",

dlg = gnome_about_new("Some application", /* Name of the application. */
                      VERSION, /* Version. */
                      "(c) 1999 George Lebl, /* Copyright notice
                                                (one line.) */
                      authors, /* NULL terminated list of
                                  authors. */
                      "Just some application, "
                      "blah blah blah", /* Other comments. */
                      NULL /* A logo pixmap file. */

gnome_dialog_set_parent(GNOME_DIALOG(dlg), GTK_WINDOW(app));




Sometimes, especially in properties dialogs, you want fields for entering text, files, pixmaps, icons or double precision numbers. This is what the gnome-*entry widgets do.


This is an entry for regular text, but it includes history of previously entered values. Note that this widget is not derived from GtkEntry, but owns such a widget. This means that you can't use GtkEntry methods on this object directly, but you need to get a pointer to the GtkEntry object inside GnomeEntry. When you call gnome_entry_new, you pass a history_id string to it. This is a unique identifier to identify this entry, or this type of entries in your application. All the entries that share this history_id will have common history of values. After you create a GnomeEntry you use the gnome_entry_gtk_entry function to get a pointer to the GtkEntry object inside and bind any signals or manipulate text with that instead. Here is an example:

GtkWidget *gnomeentry;
GtkWidget *gtkentry;
gnomeentry = gnome_entry_new("text1");

/* get the GtkEntry to bind a "changed" signal to figure out when the
   user changed the entry */
gtkentry = gnome_entry_gtk_entry(GNOME_ENTRY(gnomeentry));
                   GTK_SIGNAL_FUNC(entry_changed), NULL);



GnomeEntry is a basis for GnomeFileEntry. Again it is not derived, but GnomeEntry is owned by GnomeFileEntry. This type of hierarchy is throughout all the gnome entry widgets. GnomeFileEntry adds a browse button on the right side of the entry, and also accepts file drops from the file manager for example. It's use is extremely similar to GnomeEntry. You create the entry with gnome_file_entry_new. The first argument is the history_id of the GnomeEntry, and the second argument is the title of the browse dialog box. To get the GtkEntry, you again use the gtk_entry method, named gnome_file_entry_gtk_entry. To finally get the filename, you can get the exact text from the GtkEntry, or you might use a convenience method, gnome_file_entry_get_full_path, which takes a flag file_must_exist as it's second argument. If this flag is set, the function returns NULL if the file doesn't exists. If the flag is not set or the file does exist, the function returns the full path to the file.


This is an entry for entering pixmaps (Images) of any size. It again includes (not derives from) GnomeFileEntry, so it can do everything the file entry can (including accepting drops). However this entry adds a preview box for the pixmap above the entry. Also it's file selection dialog includes a preview box to the right side of the file list. It's use is again very similar to the entries above. You call gnome_pixmap_entry_new with the same arguments as GnomeFileEntry, with an added flag, do_preview. This flag specifies if the preview box is visible or not. But be careful, it doesn't save memory not to show the preview, it just saves space. Again you use a gnome_pixmap_entry_gtk_entry to get the GtkEntry widget. To get a filename of the the pixmap, if it could be loaded as an image for the preview, you can use gnome_pixmap_entry_get_filename, which returns NULL if the pixmap files doesn't exist or could not be loaded, and the full filename otherwise.


The icon entry is very similar to the GnomePixmapEntry, but it is meant for images in the standard 48x48 icon size. Also instead of the preview box, there is a button with the image scaled to 48x48. If you press the button you get a listing of images from the same directory as the current icon. To create an icon entry use gnome_icon_entry_new with history_id and browse_dialog_title string arguments. Once you need an existing icon that is a real image, you use gnome_icon_entry_get_filename which works just like gnome_pixmap_entry_get_filename. You can also get the GtkEntry by using gnome_icon_entry_gtk_entry. Example:

GtkWidget *iconentry;
GtkWidget *gtkentry;
char *somefilename;

iconentry = gnome_icon_entry_new("icon","Browse...");

/* we want to set 'somefilename' as default icon */
gnome_icon_entry_set_icon(GNOME_ICON_ENTRY(iconentry), somefilename);

/* we get the GtkEntry to figure out when we changed */
gtkentry = gnome_icon_entry_gtk_entry(GNOME_ICON_ENTRY(iconentry));
                   GTK_SIGNAL_FUNC(entry_changed), NULL);

/* here we want to get the selected icon */
char *icon;
icon = gnome_icon_entry_get_filename(GNOME_ICON_ENTRY(iconentry);
/* make sure to free icon after use */



GnomeNumberEntry is an entry widget for entering double precision numbers with a calculator. Most of the time for number entries you want to use the GtkSpinButton widget, however for applications such as mortgage calculators, or finance programs, where calculations are necessary, you will want to use this entry type. Basically it's a GnomeEntry widget with a button on the right side of it which calls up a dialog with a calculator. The user can use the calculator and press OK and the number entry is updated to what it was on the calculator. To create a number entry widget, just use gnome_number_entry_new, passing it the history_id as the first argument and the title of the calculator dialog as the second argument. To get the GtkEntry widget just use gnome_number_entry_gtk_entry. To get the number as a double value, use gnome_number_entry_get_number method.

Using Images

When you need to use images in your apps, most likely you'll want the GnomePixmap widget. It's advantage is that it makes using images much easier without having to learn imlib, which is the image library used by this widget.

There are numerous new functions for GnomePixmap, depending on the source of the pixmap. The most used will probably be gnome_pixmap_new_from_file which takes a filename which is an image loadable by imlib and creates a pixmap widget for you. There is also gnome_pixmap_new_from_file_at_size to which you pass also the size to which the image should be scaled. If you have already loaded the image with imlib (in case you wanted to do other things to the pixmap first), you can use gnome_pixmap_new_from_imlib and gnome_pixmap_new_from_imlib_at_size. Which take a GdkImlibImage as the first argument. If you already have a pixmap widget and want to change the image inside it, you can use the gnome_pixmap_load_* which have almost the same syntax as the new functions, except that you pass the GnomePixmap as the first argument, and then the rest of the arguments as above, and of course replace the _new_from_ for _load_.

Here's an example of it's use:

GtkWidget *pix;
/*load somefile.png and scale it to 48x48*/
pix = gnome_pixmap_new_from_file_at_size("somefile.png",48,48);
/*now you can pack pix somewhere just like any other widget*/
/*now we want to change the files to otherfile.png and do no


Session Management

Your app should be able to save it's settings and restore them when the user restarts your application, it should also be able to do this for several different sessions. For instance the user might have a normal session, but sometimes log into a special session where he has different settings in applications. gnome-libs actually hides the ugly details of this. For the most part you do not need to worry about the real details of session management, unless you wish to do something very clever or if your app does some complicated state saving. To do simple session saving all you need is the following code (mostly taken from gnome-hello-4-SM example program):

/*the save_yourself handler, you can safely ignore most of the
  parameters, and just save your session and return TRUE*/
static int 
save_yourself(GnomeClient *client, int phase,
              GnomeSaveStyle save_style, int shutdown,
              GnomeInteractStyle interact_style, int fast,
              gpointer client_data)
        /*get the prefix for our config*/
        char *prefix= gnome_client_get_config_prefix (client);

        /*this is a "discard" command for discarding data from
          a saved session, usually this will work*/
        char *argv[]= { "rm", "-r", NULL };

        /* Save the state using gnome-config stuff. */
        gnome_config_push_prefix (prefix);

        gnome_config_pop_prefix ();

        /* Here is the real SM code. We set the argv to the
           parameters needed to restart/discard the session that
           we've just saved and call the
           gnome_session_set_*_command to tell the session
           manager it. */
        argv[2]= gnome_config_get_real_path (prefix);
        gnome_client_set_discard_command (client, 3, argv);

        /* Set commands to clone and restart this application.
           Note that we use the same values for both -- the
           session management code will automatically add
           whatever magic option is required to set the session
           id on startup. The client_data was set to the
           command used to start this application when
           save_yourself handler was connected. */
        argv[0]= (gchar*) client_data;
        gnome_client_set_clone_command (client, 1, argv);
        gnome_client_set_restart_command (client, 1, argv);
        return TRUE;

static void
die (GnomeClient *client, gpointer client_data)
        /* Just exit in a friendly way.  We don't need to
           save any state here, because the session manager
           should have sent us a save_yourself-message
           before.  */
        gtk_exit (0);

GnomeClient *client;
/*this is somewhere in your main function presumably.
  make sure this is done AFTER the gnome_init call!*/

/* Get the master client, that was hopefully connected to the
   session manager int the 'gnome_init' call.  All communication
   to the session manager will be done with this master client. */
client = gnome_master_client ();

/* Arrange to be told when something interesting happens.  */
gtk_signal_connect (GTK_OBJECT (client), "save_yourself",
                    GTK_SIGNAL_FUNC (save_yourself),
                    (gpointer) argv[0]);
gtk_signal_connect (GTK_OBJECT (client), "die",
                    GTK_SIGNAL_FUNC (die), NULL);

/*check if we are connected to a session manager*/
        /*we are connected, we will get the prefix under which
          we saved our session last time and load up our data*/
                (gnome_client_get_config_prefix (client));

        some_value = gnome_config_get_int("Section/Key=0");

        gnome_config_pop_prefix ();
} else {
        /*we are not connected to any session manager, here you
          will just initialize your session like you normally
          do without a session manager*/

This is a very simple session management which will be enough for most programs, for more information on session management, you should consult the gnome developer documentation which should be available by now. 

Multiple Document Interface

The Main MDI Window

If your app handles documents, most likely you will want it to handle multiple documents at one time. Gnome provides an MDI model that is customizable by the user and simple to use. They can use three models of the document display. Either a notebook style which is the most useful one, where documents can be docked in notebooks, and can be dragged out into separate windows if desired. Or a toplevel style where each document is a separate toplevel window. Or finally a modal style where there is only one window and the documents must be switched though a menu. (Note that the examples here are taken from the gnome-hello-7-mdi example app in gnome-libs, slightly modified. Also note that this example is no longer in gnome-libs, but I reproduce here the really important parts of that example)

To use the MDI features. You basically replace the the gnome_app_new call with gnome_mdi_new with the same arguments as gnome_app_new. To add menus and tool-bar, you use gnome_mdi_set_menubar_template and gnome_mdi_set_toolbar_template with the GnomeUIInfo as the argument. For MDI, these aren't the actual menus, as it will add it's own items to the menus of each child. After this you set where the menu additions take place. You call gnome_mdi_set_child_menu_path to the toplevel menu name after which the child's own menus are inserted. This is the "File" menu in most cases. Then you want to specify the path (menu name) to the menu into which you want to insert a list of the children, you do this by calling gnome_mdi_set_child_list_path with the name of the menu and add a '/' on the end of it to specify that you want to insert those items into the menu, not after the menu. Example:

GtkWidget *mdi;
mdi = gnome_mdi_new("gnome-hello-7-mdi", "GNOME MDI Hello");
/*main_menu and toolbar_info are the menu and tool-bar
gnome_mdi_set_menubar_template(mdi, main_menu);
gnome_mdi_set_toolbar_template(mdi, toolbar_info);

/* and document menu and document list paths (see
   gnome-app-helper menu insertion routines for details)  */
gnome_mdi_set_child_menu_path(GNOME_MDI(mdi), "File");
gnome_mdi_set_child_list_path(GNOME_MDI(mdi), "Children/");

In our GnomeUIInfo structures we have defined a menu named "File" and a menu named "Children". The children menu was not given any items, it's just an empty menu.


Then you should open the main toplevel window with gnome_mdi_open_toplevel. This will open a toplevel window without any children. If you wish to use MDI's session management functionality, you can define a function that creates a child given it's name. This is done with the gnome_mdi_restore_state method, which takes the config path as the second argument and a function pointer to a function which takes a string and returns a new GnomeMDIChild widget (a widget sub-classed from GnomeMDIChild actually). Say for example you are using the session management shown above, so you could use:

gnome_config_push_prefix (gnome_client_get_config_prefix (client));
restart_ok = gnome_mdi_restore_state(GNOME_MDI(mdi), "MDI Session",
gnome_config_pop_prefix ();

The restart_ok is a boolean value telling you if the loading actually loaded all the data correctly.


You should also bind the destroy signal of the mdi object to do gtk_main_quit when the mdi is destroyed.

The MDI Children

For complicated apps, all children should be derived from the virtual GnomeMDIChild object. For simple apps, you don't need to derive a new object, you can just use the GnomeMDIGenericChild, and use the fact that you can store arbitrary data on arbitrary GtkObjects to store your own data on the object.

To use the generic child object, you create it with gnome_mdi_generic_child_new to which you pass the name of the child. When you get the object, you will need to set it up for your use. First you add a function for creating new views of the same data. A view is just a different window displaying the same file or data. This is done with a call to gnome_mdi_generic_child_set_view_creator to which you pass a pointer to a creator function which takes the child widget and a data pointer as arguments and returns a data widget, which is not the actual child widget, but actually the child of the GnomeMDIGenericChild widget. After this you set the template for the child's menus with gnome_mdi_child_set_menu_template, to which you pass the GnomeUIInfo array pointer of the child menu definitions. Then you should call gnome_mdi_generic_child_set_config_func to set a function which returns a newly allocated string to save in the config file. This string will be used to load up the child next time you start and do the gnome_mdi_restore_state call. It should probably be a filename of the document, or some string from which you can completely recreate that window/document. Then you need to call gnome_mdi_generic_child_set_label_func with a pointer to a function that takes the GnomeMDIGenericChild as the first argument, the old label widget pointer as the second argument, which would be null if no label widget was yet set, and a data argument. This function can either create a new label and destroy the old one, or just set the label if the label exists. The label can be any widget, for example the gnome-hello-7-mdi example code uses a horizontal box widget into which it adds a pixmap and a gtk label. After this if you need to add the child to the mdi yourself, if you are loading a new file for example, you use gnome_mdi_add_child and gnome_mdi_add_view, to add a new child and a new view to the mdi. If you are creating a new child from the gnome_mdi_restore_state function, you should just return the child, the mdi will take care of adding it and adding the appropriate views. You also probably want to set some data on the child widget at this time to store your data with the object.

Here's a short example of creating a new child.

GnomeMDI *mdi;
GnomeMDIGenericChild *child;
/*create a new child named 'name'*/
if((child = gnome_mdi_generic_child_new(name)) != NULL) {
        /*creator of a view*/
                (child, my_child_create_view, NULL);
        /*set a menu template for child menu*/
                (GNOME_MDI_CHILD(child), main_child_menu);
        /*set function to get config string*/
                (child, my_child_get_config_string, NULL);
        /*set function that sets or creates a label*/
                (child, my_child_set_label, NULL);

        /* add the child to MDI */
        gnome_mdi_add_child(mdi, GNOME_MDI_CHILD(child));

        /* and add a new view of the child */
        gnome_mdi_add_view(mdi, GNOME_MDI_CHILD(child));


Miscellaneous Widgets

Displaying text with GnomeLess

Sometimes you might want to display a file from disk, such as a README, or perhaps display the results of running a certain command. This is what the GnomeLess widget was written for. It provides simple API to do these basic things, with minimum amount of work. First you must create a new GnomeLess widget and put it somewhere into your interface. You do this with the gnome_less_new function. Then to show a file from disk, you call the gnome_less_show_file method with the filename as the second argument. Example:

GtkWidget *less;
less = gnome_less_new();

/* This will read the file "README" from disk and show it inside
   the GnomeLess widget */
gnome_less_show_file(GNOME_LESS(less), "README");


If you want to show the result of a command, such as perhaps "ls", you can call the gnome_less_show_command method with the command as the second argument. Example:

GtkWidget *less;
less = gnome_less_new();

/* This will show the results of "ls" int he current directory inside
   the GnomeLess widget */
gnome_less_show_command(GNOME_LESS(less), "ls");

Do note however that this will block the application. This call does not return until the command ends execution. This means that you should not use it for commands that take a long time to execute, because the user interface would "freeze" until the command ended. For that you should use use some alternate logic. 

Web Links With GnomeHRef

Sometimes you might want to put a button in your app that starts a browser for the user or points an already running browser to some location. All you need to do is to call gnome_href_new with an URL as the first argument and the label as the second. This will create a button like widget, which you can place anywhere in your application. It will then display the URL using the gnome_url_show function. For example:

GtkWidget *widget;
widget = gnome_href_new("", "The GNOME Website");


Selecting Icons With GnomeIconSelection

Normally you will probably want to select icons using the GnomeIconEntry widget, but sometimes you maybe want to put the icon listing window directly into your application, without having to mess with the icon listing yourself. This widget is only useful if you have some directory from which to pick icons. You create the widget with the gnome_icon_selection_new. Then when you want to add a directory of icons, use gnome_icon_selection_add_directory method with the argument being the directory to add. You can add multiple directories. Then when you have added all that you want, you have to call gnome_icon_selection_show_icons and that will load and show the icons. To select a specific icon, use the gnome_icon_selection_select_icon with the filename of the icon to select. The filename should be just the base name of the icon not the entire path. Once you want to get the icon that was selected, you use the gnome_icon_selection_get_icon method which takes a boolean argument 'full_path' and returns a pointer to a string with the file or NULL if nothing was selected. If that 'full_path' argument is TRUE, the returned value will be the full path of the icon. Note that the returned value points to internal memory so you should not free it. Example:

GtkWidget *widget;
char *some_icon_directory;
char *some_other_icon_directory;
/* here we create the widget */
widget = gnome_icon_selection_new();

/* here we want to get the selection (as full path) */
char *filename;
filename = gnome_icon_selection_get_icon(GNOME_ICON_SELECTION(widget), TRUE);

Be the first one to comment on this page.

  Gnome eBooks

No eBooks on Gnome could be found as of now.

 Gnome FAQs
More Links » »
 Gnome Interview Questions
More Links » »
 Gnome Articles

No Gnome Articles could be found as of now.

 Gnome News

No News on Gnome could be found as of now.

 Gnome Jobs

No Gnome Articles could be found as of now.

Share And Enjoy:These icons link to social bookmarking sites where readers can share and discover new web pages.
  • blinkbits
  • BlinkList
  • blogmarks
  • co.mments
  • connotea
  • digg
  • Fark
  • feedmelinks
  • Furl
  • LinkaGoGo
  • Ma.gnolia
  • NewsVine
  • Netvouz
  • RawSugar
  • Reddit
  • scuttle
  • Shadows
  • Simpy
  • Smarking
  • Spurl
  • TailRank
  • Wists
  • YahooMyWeb

Previoushome Next

Keywords: Using the libgnomeui Library, GNOME, GNOME, GNOME tutorial, GNOME tutorial pdf, history of GNOME, Custamizing Style Sheet, learn GNOME

HTML Quizzes
CSS Quiz
CSS 1.0 Quiz
CSS 2.0 Quiz
XML Quizzes
XML Quiz
XSL Quiz
DTD Quiz
Schema Quiz
XForms Quiz
XLink Quiz
XQuery Quiz
XPath Quiz
XPointer Quiz
RDF Quiz
RSS Quiz
WAP Quiz
Web Services Quiz
Browser Scripting Quizzes
JavaScript Quiz
VBScript Quiz
WMLScript Quiz
E4X Quiz
Server Scripting Quizzes
ASP Quiz
SQL Quiz
ADO Quiz
CVS Quiz
Python Quiz
Apple Script Quiz
SQL Server Quiz
PHP Quiz
.NET (dotnet) Quizzes
Microsoft.Net Quiz
ASP.Net Quiz
.Net Mobile Quiz
C# : C Sharp Quiz
VC++ Quiz
Multimedia Quizzes
SVG Quiz
Flash Quiz
Media Quiz
Photoshop Quiz
Gimp Quiz
Matlab Quiz
Gnuplot Programming Quiz
GIF Animation Quiz
Scientific Visualization Quiz
Graphics Quiz
Web Building Quizzes
Web Browsers Quiz
Web Hosting Quiz
W3C Quiz
Web Building Quiz
Web Quality Quiz
Web Semantic Quiz
Web Careers Quiz
Weblogic Quiz
SEO Quiz
Web Site Hosting Quiz
Domain Name Quiz
Java Quizzes
Java Quiz
JSP Quiz
Servlets Quiz
Struts Quiz
EJB Quiz
JMS Quiz
JMX Quiz
Eclipse Quiz
J2ME Quiz
Programming Langauges Quizzes
C Quiz
C++ Quiz
Visual Basic Quiz
Data Structures Using C Quiz
Cobol Quiz
Assembly Language Quiz
Mainframe Quiz
Forth Programming Quiz
Lisp Programming Quiz
Pascal Quiz
Delphi Quiz
Fortran Quiz
OOPs Quiz
Data Warehousing Quiz
CGI Programming Quiz
Emacs Quiz
Gnome Quiz
ILU Quiz
Soft Skills Quizzes
Communication Skills Quiz
Time Management Quiz
Project Management Quiz
Team Work Quiz
Leadership Skills Quiz
Corporate Communication Quiz
Negotiation Skills Quiz
Database Quizzes
Oracle Quiz
MySQL Quiz
Operating System Quizzes
BSD Quiz
Symbian Quiz
Unix Quiz
Internet Quiz
IP-Masquerading Quiz
IPC Quiz
Software Testing Quizzes
Testing Quiz
Firewalls Quiz
SAP Module Quizzes
ERP Quiz
Business Warehousing Quiz
SAP Basis Quiz
Material Management Quiz
Sales & Distribution Quiz
Human Resource Quiz
Netweaver Quiz
Customer Relationship Management Quiz
Production and Planning Quiz
Networking Programming Quizzes
Corba Quiz
Networking Quiz
Microsoft Office Quizzes
Microsoft Word Quiz
Microsoft Outlook Quiz
Microsoft PowerPoint Quiz
Microsoft Publisher Quiz
Microsoft Excel Quiz
Microsoft Front Page Quiz
Microsoft InfoPath Quiz
Microsoft Access Quiz
Accounting Quizzes
Financial Accounting Quiz
Managerial Accounting Quiz
Testimonials | Contact Us | Link to Us | Site Map
Copyright 2008. Academic All rights reserved Privacy Policies | About Us
Our Portals : Academic Tutorials | Best eBooksworld | Beyond Stats | City Details | Interview Questions | Discussions World | Excellent Mobiles | Free Bangalore | Give Me The Code | Gog Logo | Indian Free Ads | Jobs Assist | New Interview Questions | One Stop FAQs | One Stop GATE | One Stop GRE | One Stop IAS | One Stop MBA | One Stop SAP | One Stop Testing | Webhosting in India | Dedicated Server in India | Sirf Dosti | Source Codes World | Tasty Food | Tech Archive | Testing Interview Questions | Tests World | The Galz | Top Masala | Vyom | Vyom eBooks | Vyom International | Vyom Links | Vyoms | Vyom World
Copyright 2003-2017 Vyom Technosoft Pvt. Ltd., All Rights Reserved.