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