<HTML
><HEAD
><TITLE
>GnomePropertyBox</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.74b"><LINK
REL="HOME"
TITLE="Gnome User Interface Library Reference Manual"
HREF="book1.html"><LINK
REL="UP"
TITLE="GNOME Widgets and Objects"
HREF="gnome-objects.html"><LINK
REL="PREVIOUS"
TITLE="GnomePixmap"
HREF="gnomepixmap.html"><LINK
REL="NEXT"
TITLE="GnomeScores"
HREF="gnomescores.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#000000"
CELLPADDING="1"
CELLSPACING="0"
><TR
><TH
COLSPAN="4"
ALIGN="center"
><FONT
COLOR="#FFFFFF"
SIZE="5"
>Gnome User Interface Library Reference Manual</FONT
></TH
></TR
><TR
><TD
WIDTH="25%"
BGCOLOR="#C00000"
ALIGN="left"
><A
HREF="gnomepixmap.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
><<< Previous Page</B
></FONT
></A
></TD
><TD
WIDTH="25%"
BGCOLOR="#0000C0"
ALIGN="center"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
><A
HREF="book1.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>Home</B
></FONT
></A
></B
></FONT
></TD
><TD
WIDTH="25%"
BGCOLOR="#00C000"
ALIGN="center"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
><A
HREF="gnome-objects.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>Up</B
></FONT
></A
></B
></FONT
></TD
><TD
WIDTH="25%"
BGCOLOR="#C00000"
ALIGN="right"
><A
HREF="gnomescores.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>Next Page >>></B
></FONT
></A
></TD
></TR
></TABLE
></DIV
><H1
><A
NAME="GNOMEPROPERTYBOX"
>GnomePropertyBox</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN23109"
></A
><H2
>Name</H2
>GnomePropertyBox -- Standarized dialog box for handling configuration</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN23112"
></A
><H2
>Synopsis</H2
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
> #include <gnome.h>
struct <A
HREF="gnomepropertybox.html#GNOMEPROPERTYBOX-STRUCT"
>GnomePropertyBox</A
>;
#define <A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-DIRTY-CAPS"
>GNOME_PROPERTY_BOX_DIRTY</A
>
<GTKDOCLINK
HREF="GTKWIDGET"
>GtkWidget</GTKDOCLINK
>* <A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-NEW"
>gnome_property_box_new</A
> (void);
void <A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-CHANGED"
>gnome_property_box_changed</A
> (<A
HREF="gnomepropertybox.html"
>GnomePropertyBox</A
> *property_box);
void <A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-SET-STATE"
>gnome_property_box_set_state</A
> (<A
HREF="gnomepropertybox.html"
>GnomePropertyBox</A
> *property_box,
<GTKDOCLINK
HREF="GBOOLEAN"
>gboolean</GTKDOCLINK
> state);
<GTKDOCLINK
HREF="GINT"
>gint</GTKDOCLINK
> <A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-APPEND-PAGE"
>gnome_property_box_append_page</A
> (<A
HREF="gnomepropertybox.html"
>GnomePropertyBox</A
> *property_box,
<GTKDOCLINK
HREF="GTKWIDGET"
>GtkWidget</GTKDOCLINK
> *child,
<GTKDOCLINK
HREF="GTKWIDGET"
>GtkWidget</GTKDOCLINK
> *tab_label); </PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN23129"
></A
><H2
>Object Hierarchy</H2
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
> <GTKDOCLINK
HREF="GTKOBJECT"
>GtkObject</GTKDOCLINK
>
+----<GTKDOCLINK
HREF="GTKWIDGET"
>GtkWidget</GTKDOCLINK
>
+----<GTKDOCLINK
HREF="GTKCONTAINER"
>GtkContainer</GTKDOCLINK
>
+----<GTKDOCLINK
HREF="GTKBIN"
>GtkBin</GTKDOCLINK
>
+----<GTKDOCLINK
HREF="GTKWINDOW"
>GtkWindow</GTKDOCLINK
>
+----<A
HREF="gnomedialog.html"
>GnomeDialog</A
>
+----GnomePropertyBox</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN23138"
></A
><H2
>Description</H2
><P
> The <SPAN
CLASS="TYPE"
>GnomePropertyBox</SPAN
> widget simplifies coding a
consistent dialog box for configuring properties of any kind.
</P
><P
> The <SPAN
CLASS="TYPE"
>GnomePropertyBox</SPAN
> is a toplevel widget (it will
create its own window), inside it contains a <SPAN
CLASS="TYPE"
>GtkNotebook</SPAN
>
which is used to hold the various property pages.
</P
><P
> 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 <A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-CHANGED"
>gnome_property_box_changed</A
>() function.
</P
><P
> To use this widget, you create the widget using
<A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-NEW"
>gnome_property_box_new</A
>() and then you call
<A
HREF="gnomepropertybox.html#GNOME-PROPERTY-BOX-APPEND-PAGE"
>gnome_property_box_append_page</A
>() for each property page you want
in the property box.
</P
><P
> 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.
</P
><P
>Here is a sample callback routine layout
<DIV
CLASS="EXAMPLE"
><A
NAME="AEN23152"
></A
><P
><B
>Example 1. Sample callback for the "apply" signal</B
></P
><TABLE
BORDER="0"
BGCOLOR="#D8F8D8"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void
dialog_apply_callback (GnomePropertyBox *property_box, gint page_num)
{
switch (page_num){
case 0:
apply_changes_page_0 (property_box);
break;
case 1:
apply_changes_page_1 (property_box);
break;
default:
}
}
</PRE
></TD
></TR
></TABLE
></DIV
>
</P
><P
>Some people just check for the last condition like this:
<DIV
CLASS="EXAMPLE"
><A
NAME="AEN23156"
></A
><P
><B
>Example 2. Sample callback for the "apply" signal</B
></P
><TABLE
BORDER="0"
BGCOLOR="#D8F8D8"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void
dialog_apply_callback (GnomePropertyBox *property_box, gint page_num)
{
if (page_num != -1)
return;
apply_all_changes (property_box);
}
</PRE
></TD
></TR
></TABLE
></DIV
>
</P
><P
> A fully finished program should also hook up to the "help" signal
to provide context sensitive help in the dialog box. This signal
also receives the page number in which the help is invoked, so you
can provide different help nodes for each page if you desire to do
so.
</P
><P
> The GNOME libraries include a number of helper routines that will
help you provide help in your application. Here is a sample piece
of code:
<DIV
CLASS="EXAMPLE"
><A
NAME="AEN23161"
></A
><P
><B
>Example 3. Sample callback for the "help" signal</B
></P
><TABLE
BORDER="0"
BGCOLOR="#D8F8D8"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void
dialog_help_callback (GnomePropertyBox *property_box, gint page_num)
{
GnomeHelpMenuEntry help_entry_page_0 = { "application-id", "page-0-help" };
GnomeHelpMenuEntry help_entry_page_1 = { "application-id", "page-1-help" };
switch (page_num){
case 0:
gnome_help_display (0, help_entry_page_0);
break;
case 1:
gnome_help_display (0, help_entry_page_1);
break;
}
}
</PRE
></TD
></TR
></TABLE
></DIV
>
The value "0" in the example above is ignored by the
gnome_help_display routines. This is done so that you can use a
hack to connect to help in simpler situations without having to
provide a full callback (like in this example).
</P
><P
> You can actually save some time if you use the
<GTKDOCLINK
HREF="GNOME-HELP-PBOX-DISPLAY"
>gnome_help_pbox_display</GTKDOCLINK
>() routine. This routine is designed to
work side-by-side with the <SPAN
CLASS="TYPE"
>GnomePropertyBox</SPAN
> object.
It works like this:
<DIV
CLASS="EXAMPLE"
><A
NAME="AEN23167"
></A
><P
><B
>Example 4. Connecting the "help" signal using the
<GTKDOCLINK
HREF="GNOME-HELP-PBOX-DISPLAY"
>gnome_help_pbox_display</GTKDOCLINK
>() routine</B
></P
><TABLE
BORDER="0"
BGCOLOR="#D8F8D8"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void
property_dialog_do_connections (GnomePropertyBox *property_box)
{
static GnomeHelpMenuEntry help_entry = { "application-id", "base-name" };
gtk_signal_connect (GTK_OBJECT (property_box), "help",
GTK_SIGNAL_FUNC(gnome_help_pbox_display), &help_entry);
}
</PRE
></TD
></TR
></TABLE
></DIV
>
This will use the "base-name" as a template to create the
fully-qualified name of the help file using the page number as
part of the filename component (the result is in the form
"base-name-$pagenum.html", where $pagenum is substituted with the
page number).
</P
><P
> See the documentation for <GTKDOCLINK
HREF="GNOME-HELP-PBOX-DISPLAY"
>gnome_help_pbox_display</GTKDOCLINK
>() for more information
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN23173"
></A
><H2
>Details</H2
><DIV
CLASS="REFSECT2"
><A
NAME="AEN23175"
></A
><H3
><A
NAME="GNOMEPROPERTYBOX-STRUCT"
></A
>struct GnomePropertyBox</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct GnomePropertyBox;</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN23180"
></A
><H3
><A
NAME="GNOME-PROPERTY-BOX-DIRTY-CAPS"
></A
>GNOME_PROPERTY_BOX_DIRTY</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define GNOME_PROPERTY_BOX_DIRTY "gnome_property_box_dirty"</PRE
></TD
></TR
></TABLE
><P
></P
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN23185"
></A
><H3
><A
NAME="GNOME-PROPERTY-BOX-NEW"
></A
>gnome_property_box_new ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
><GTKDOCLINK
HREF="GTKWIDGET"
>GtkWidget</GTKDOCLINK
>* gnome_property_box_new (void);</PRE
></TD
></TR
></TABLE
><P
>Creates a new GnomePropertyBox widget. The PropertyBox widget
is useful for making consistent configuration dialog boxes.</P
><P
>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).</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN23193"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Returns</I
></SPAN
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>a newly created GnomePropertyBox widget.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN23202"
></A
><H3
><A
NAME="GNOME-PROPERTY-BOX-CHANGED"
></A
>gnome_property_box_changed ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gnome_property_box_changed (<A
HREF="gnomepropertybox.html"
>GnomePropertyBox</A
> *property_box);</PRE
></TD
></TR
></TABLE
><P
>When a setting has changed, the code needs to invoke this routine
to make the Ok/Apply buttons sensitive.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN23209"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>property_box</I
></TT
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The GnomePropertyBox that contains the changed data</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN23218"
></A
><H3
><A
NAME="GNOME-PROPERTY-BOX-SET-STATE"
></A
>gnome_property_box_set_state ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gnome_property_box_set_state (<A
HREF="gnomepropertybox.html"
>GnomePropertyBox</A
> *property_box,
<GTKDOCLINK
HREF="GBOOLEAN"
>gboolean</GTKDOCLINK
> state);</PRE
></TD
></TR
></TABLE
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN23225"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>property_box</I
></TT
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> </TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>state</I
></TT
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> </TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
><HR><DIV
CLASS="REFSECT2"
><A
NAME="AEN23238"
></A
><H3
><A
NAME="GNOME-PROPERTY-BOX-APPEND-PAGE"
></A
>gnome_property_box_append_page ()</H3
><TABLE
BORDER="0"
BGCOLOR="#D6E8FF"
WIDTH="100%"
CELLPADDING="6"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
><GTKDOCLINK
HREF="GINT"
>gint</GTKDOCLINK
> gnome_property_box_append_page (<A
HREF="gnomepropertybox.html"
>GnomePropertyBox</A
> *property_box,
<GTKDOCLINK
HREF="GTKWIDGET"
>GtkWidget</GTKDOCLINK
> *child,
<GTKDOCLINK
HREF="GTKWIDGET"
>GtkWidget</GTKDOCLINK
> *tab_label);</PRE
></TD
></TR
></TABLE
><P
>Appends a new page to the GnomePropertyBox.</P
><P
></P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN23248"
></A
><P
></P
><TABLE
BORDER="0"
WIDTH="100%"
BGCOLOR="#FFD0D0"
CELLSPACING="0"
CELLPADDING="4"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>property_box</I
></TT
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The property box where we are inserting a new page</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>child</I
></TT
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The widget that is being inserted</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><TT
CLASS="PARAMETER"
><I
>tab_label</I
></TT
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
> The widget used as the label for this confiugration page</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="RIGHT"
VALIGN="TOP"
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Returns</I
></SPAN
> :</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="TOP"
>the assigned index of the page inside the GnomePropertyBox or
-1 if one of the arguments is invalid.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN23269"
></A
><H2
>See Also</H2
><P
><GTKDOCLINK
HREF="GNOME-HELP-PBOX-DISPLAY"
>gnome_help_pbox_display</GTKDOCLINK
>(), <GTKDOCLINK
HREF="GNOME-HELP-DISPLAY"
>gnome_help_display</GTKDOCLINK
>(), <A
HREF="gnomedialog.html"
>GnomeDialog</A
></P
></DIV
><DIV
CLASS="NAVFOOTER"
><BR
CLEAR="all"><BR><TABLE
WIDTH="100%"
BORDER="0"
BGCOLOR="#000000"
CELLPADDING="1"
CELLSPACING="0"
><TR
><TD
WIDTH="25%"
BGCOLOR="#C00000"
ALIGN="left"
><A
HREF="gnomepixmap.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
><<< Previous Page</B
></FONT
></A
></TD
><TD
WIDTH="25%"
BGCOLOR="#0000C0"
ALIGN="center"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
><A
HREF="book1.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>Home</B
></FONT
></A
></B
></FONT
></TD
><TD
WIDTH="25%"
BGCOLOR="#00C000"
ALIGN="center"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
><A
HREF="gnome-objects.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>Up</B
></FONT
></A
></B
></FONT
></TD
><TD
WIDTH="25%"
BGCOLOR="#C00000"
ALIGN="right"
><A
HREF="gnomescores.html"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>Next Page >>></B
></FONT
></A
></TD
></TR
><TR
><TD
COLSPAN="2"
ALIGN="left"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>GnomePixmap</B
></FONT
></TD
><TD
COLSPAN="2"
ALIGN="right"
><FONT
COLOR="#FFFFFF"
SIZE="3"
><B
>GnomeScores</B
></FONT
></TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
1bbf51ece72e40a5f40ad48678e7c5a5
>
files
>
474
