Gnome User Interface Library Reference Manual
PrevNext

GnomePropertyBox

Name

GnomePropertyBox — Standarized dialog box for handling configuration

Synopsis


#include <gnome.h>


struct      GnomePropertyBox
#define     GNOME_PROPERTY_BOX_DIRTY
GtkWidget*  gnome_property_box_new          (void);
void        gnome_property_box_changed      (GnomePropertyBox *property_box);
void        gnome_property_box_set_state    (GnomePropertyBox *property_box,
                                             gboolean state);
gint        gnome_property_box_append_page  (GnomePropertyBox *property_box,
                                             GtkWidget *child,
                                             GtkWidget *tab_label);

Object Hierarchy


  GtkObject
   +----GtkWidget
         +----GtkContainer
               +----GtkBin
                     +----GtkWindow
                           +----GnomeDialog
                                 +----GnomePropertyBox

Signal Prototypes


'apply'     void        user_function      (GnomePropertyBox *propertybox,
                                            gint arg1,
                                            gpointer user_data);
'help'      void        user_function      (GnomePropertyBox *propertybox,
                                            gint arg1,
                                            gpointer user_data);

Description

The GnomePropertyBox widget simplifies coding a consistent dialog box for configuring properties of any kind.

The GnomePropertyBox is a toplevel widget (it will create its own window), inside it contains a GtkNotebook which is used to hold the various property pages.

The box will include ok, cancel, apply and help buttons (the actual buttons depends on the settings the user has, for example, apply can be hidden). The ok and apply buttons will start up in non-sensitive state, the programmer needs to configure the widgets inserted into the property box to inform the widget of any state changes to enable the ok and apply buttons. This is done by calling the gnome_property_box_changed() function.

To use this widget, you create the widget using gnome_property_box_new() and then you call gnome_property_box_append_page() for each property page you want in the property box.

The widget emits two signals: "apply" and "help". To make a functional dialog box you will want to connect to at least the "apply" signal: your function will be invoked once for each page and one more time at the end, passing a special value of -1 for the page number.

<!- Documentation author, Miguel de Icaza -->

Details

GnomePropertyBox

struct GnomePropertyBox;

GNOME_PROPERTY_BOX_DIRTY

#define GNOME_PROPERTY_BOX_DIRTY	"gnome_property_box_dirty"

gnome_property_box_new()

GtkWidget*  gnome_property_box_new          (void);

Creates a new GnomePropertyBox widget. The PropertyBox widget is useful for making consistent configuration dialog boxes.

When a setting has been made to a property in the PropertyBox your program needs to invoke the gnome_property_box_changed to signal a change (this will enable the Ok/Apply buttons).

Returns :a newly created GnomePropertyBox widget.

gnome_property_box_changed()

void        gnome_property_box_changed      (GnomePropertyBox *property_box);

When a setting has changed, the code needs to invoke this routine to make the Ok/Apply buttons sensitive.

property_box : The GnomePropertyBox that contains the changed data

gnome_property_box_set_state()

void        gnome_property_box_set_state    (GnomePropertyBox *property_box,
                                             gboolean state);

property_box : state : 

gnome_property_box_append_page()

gint        gnome_property_box_append_page  (GnomePropertyBox *property_box,
                                             GtkWidget *child,
                                             GtkWidget *tab_label);

Appends a new page to the GnomePropertyBox.

property_box : The property box where we are inserting a new pagechild : The widget that is being insertedtab_label : The widget used as the label for this confiugration pageReturns :the assigned index of the page inside the GnomePropertyBox or -1 if one of the arguments is invalid.

Signals

The 'apply' signal

void        user_function                  (GnomePropertyBox *propertybox,
                                            gint arg1,
                                            gpointer user_data);

This signal is invoked with the page number that is being applied. The signal is emited with the special page number -1 when it has finished emiting the signals for all of the property pages.

propertybox :the object which received the signal.arg1 :The page number. user_data :user data set when the signal handler was connected.

The 'help' signal

void        user_function                  (GnomePropertyBox *propertybox,
                                            gint arg1,
                                            gpointer user_data);

This signal is invoked when the user clicks on the help button in the property box. An argument is passed that identifies the currently active page number.

There are a number of utility functions in the module gnome-help that can help you hook help into your application: gnome_help_pbox_goto() and gnome_help_pbox_display provide two different ways to hook the help into this signal.

propertybox :the object which received the signal.arg1 : user_data :user data set when the signal handler was connected.

PrevHomeNext
GnomePixmapUpGnomeScores