Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Mail Systems
Eclipse Documentation

How To Guides
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Problem Solutions
Privacy Policy




Gtk+/Gnome Application Development
Prev Home Next


GnomePropertyBox is used for application preferences, or to edit the properties of a user-visible object. It's a dialog with a GtkNotebook inside, and four buttons: "OK," "Apply," "Close," and "Help." The "OK" button is equivalent in all respects to clicking "Apply" followed by "Close." "Apply" should immediately make any changes the user has requested using the widgets you've placed in the GnomePropertyBox. Unsurprisingly, "Help" should display help. "OK" and "Close" are handled automatically by the property box, so you can ignore them.

You don't need to deal with the property box's buttons directly; instead GnomePropertyBox emits "apply" and "help" signals. Handlers for these should look like:

void handler(GtkWidget* propertybox, gint page_num, gpointer data);


page_num is the currently-active page of the GtkNotebook inside the dialog. (GtkNotebook pages are numbered from front to back, starting with 0; the front page is the first one you add to the notebook.) For "help", the page number lets you provide context-sensitive help. When the user clicks the "Apply" or "OK" button, the "apply" signal is emitted once per page, then emitted a final time with -1 as the page_num value. The multiple emissions of "apply" are something of an anachronism, because it has become de facto standard behavior to simply apply all pages when the -1 page number is received.

To create a property box, you first create the dialog, then create each page and add it. Creating a GnomePropertyBox is straightforward; gnome_property_box_new() takes no arguments.

       #include <libgnomeui/gnome-propertybox.h>

GtkWidget* gnome_property_box_new(void);

gint gnome_property_box_append_page(GnomePropertyBox* pb, GtkWidget* page, GtkWidget* tab);

Figure 8. GnomePropertyBox

You then create a widget for each page (probably a container with a number of controls inside), and append it to the property box with gnome_property_box_append_page() (Figure 8). Its page argument is the widget to place inside the new notebook page, and tab is a widget to use on the notebook tab. The page number of the newly-added page is returned, so you don't have to keep a count yourself.

It's your responsibility to keep track of any user interaction with the contents of each page. When the user changes a setting, you must notify the property box; it uses this information to set the "Apply" and "OK" buttons sensitive if and only if there are unapplied changes. The relevant routines are in Figure 9.

       #include <libgnomeui/gnome-propertybox.h>

void gnome_property_box_changed(GnomePropertyBox* pb);

void gnome_property_box_set_state(GnomePropertyBox* pb, gboolean setting);

Figure 9. Property Box State

gnome_property_box_changed() tells the property box about changes; the property box will automatically unset its internal "changes pending" flag when "apply" is emitted. If you need to change that internal flag for some reason (unlikely), you can use gnome_property_box_set_state().

Gtk+/Gnome Application Development
Prev Home Next

  Published under free license. Design by Interspire