diff options
| author | BST 2000 Tony Gale <gale@gtk.org> | 2000-07-17 17:21:13 +0000 |
|---|---|---|
| committer | Tony Gale <gale@src.gnome.org> | 2000-07-17 17:21:13 +0000 |
| commit | 2465ad85f9d97f15841b7d22a87fe08afc19a815 (patch) | |
| tree | 64aa891bb493b461e23e9de9ff8856e0911d9b06 /docs/tutorial | |
| parent | 6c9b8cab3b0b28df7ebf0ee87ff13f5cae1fab65 (diff) | |
| download | gdk-pixbuf-2465ad85f9d97f15841b7d22a87fe08afc19a815.tar.gz | |
Clean ups.
Mon Jul 17 18:19:06 BST 2000 Tony Gale <gale@gtk.org>
* docs/tutorial/gtk-tut.sgml: Clean ups.
Diffstat (limited to 'docs/tutorial')
| -rwxr-xr-x | docs/tutorial/gtk-tut.sgml | 3887 |
1 files changed, 1950 insertions, 1937 deletions
diff --git a/docs/tutorial/gtk-tut.sgml b/docs/tutorial/gtk-tut.sgml index 0fa1ebe87..7f776f689 100755 --- a/docs/tutorial/gtk-tut.sgml +++ b/docs/tutorial/gtk-tut.sgml @@ -1,8 +1,8 @@ <!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []> -<book> +<book id="gtk-tut"> <bookinfo> - <date>July 15th 2000</date> + <date>July 17th 2000</date> <title>GTK+ 1.2 Tutorial</title> <authorgroup> <author> @@ -165,9 +165,9 @@ application.</para> <para>The next line:</para> -<para><literallayout> -<literal>gtk_init (&argc, &argv);</literal> -</literallayout></para> +<programlisting role="C"> +gtk_init (&argc, &argv); +</programlisting> <para>calls the function gtk_init(gint *argc, gchar ***argv) which will be called in all GTK applications. This sets up a few things for us such @@ -208,10 +208,10 @@ of standard arguments accepted by all GTK applications.</para> <para>The next two lines of code create and display a window.</para> -<para><literallayout> -<literal> window = gtk_window_new (GTK_WINDOW_TOPLEVEL);</literal> -<literal> gtk_widget_show (window);</literal> -</literallayout></para> +<programlisting role="C"> + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_widget_show (window); +</programlisting> <para>The <literal>GTK_WINDOW_TOPLEVEL</literal> argument specifies that we want the window to undergo window manager decoration and placement. Rather than @@ -223,9 +223,9 @@ the attributes of this widget, and that it can display it.</para> <para>The last line enters the GTK main processing loop.</para> -<para><literallayout> -<literal> gtk_main ();</literal> -</literallayout></para> +<programlisting role="C"> + gtk_main (); +</programlisting> <para>gtk_main() is another call you will see in every GTK application. When control reaches this point, GTK will sleep waiting for X events @@ -424,12 +424,12 @@ button.</para> catch these signals and call the appropriate function. This is done by using a function such as:</para> -<para><literallayout> -<literal>gint gtk_signal_connect( GtkObject *object, +<programlisting role="C"> +gint gtk_signal_connect( GtkObject *object, gchar *name, GtkSignalFunc func, - gpointer func_data );</literal> -</literallayout></para> + gpointer func_data ); +</programlisting> <para>where the first argument is the widget which will be emitting the signal, and the second the name of the signal you wish to catch. The @@ -439,10 +439,10 @@ fourth, the data you wish to have passed to this function.</para> <para>The function specified in the third argument is called a "callback function", and should generally be of the form</para> -<para><literallayout> -<literal>void callback_func( GtkWidget *widget, - gpointer callback_data );</literal> -</literallayout></para> +<programlisting role="C"> +void callback_func( GtkWidget *widget, + gpointer callback_data ); +</programlisting> <para>where the first argument will be a pointer to the widget that emitted the signal, and the second a pointer to the data given as the last @@ -455,21 +455,21 @@ signal provides both row and column parameters.</para> <para>Another call used in the <emphasis>helloworld</emphasis> example, is:</para> -<para><literallayout> -<literal>gint gtk_signal_connect_object( GtkObject *object, +<programlisting role="C"> +gint gtk_signal_connect_object( GtkObject *object, gchar *name, GtkSignalFunc func, - GtkObject *slot_object );</literal> -</literallayout></para> + GtkObject *slot_object ); +</programlisting> <para>gtk_signal_connect_object() is the same as gtk_signal_connect() except that the callback function only uses one argument, a pointer to a GTK object. So when using this function to connect signals, the callback should be of the form</para> -<para><literallayout> -<literal>void callback_func( GtkObject *object );</literal> -</literallayout></para> +<programlisting role="C"> +void callback_func( GtkObject *object ); +</programlisting> <para>where the object is usually a widget. We usually don't setup callbacks for gtk_signal_connect_object however. They are usually used to call a @@ -560,11 +560,11 @@ the above event names as the <literal>name</literal> parameter. The callback function for events has a slightly different form than that for signals:</para> -<para><literallayout> -<literal>void callback_func( GtkWidget *widget, +<programlisting role="C"> +void callback_func( GtkWidget *widget, GdkEvent *event, - gpointer callback_data );</literal> -</literallayout></para> + gpointer callback_data ); +</programlisting> <para>GdkEvent is a C <literal>union</literal> structure whose type will depend upon which of the above events has occurred. In order for us to tell which event @@ -611,22 +611,22 @@ event. Possible values for the type are:</para> <para>So, to connect a callback function to one of these events we would use something like:</para> -<para><literallayout> -<literal>gtk_signal_connect( GTK_OBJECT(button), "button_press_event", +<programlisting role="C"> +gtk_signal_connect( GTK_OBJECT(button), "button_press_event", GTK_SIGNAL_FUNC(button_press_callback), - NULL);</literal> -</literallayout></para> + NULL); +</programlisting> <para>This assumes that <literal>button</literal> is a Button widget. Now, when the mouse is over the button and a mouse button is pressed, the function <literal>button_press_callback</literal> will be called. This function may be declared as:</para> -<para><literallayout> -<literal>static gint button_press_callback( GtkWidget *widget, +<programlisting role="C"> +static gint button_press_callback( GtkWidget *widget, GdkEventButton *event, - gpointer data );</literal> -</literallayout></para> + gpointer data ); +</programlisting> <para>Note that we can declare the second argument as type <literal>GdkEventButton</literal> as we know what type of event will occur for this @@ -1123,12 +1123,16 @@ first. There are a lot of options, and it's not immediately obvious how they all fit together. In the end, however, there are basically five different styles.</para> -<para><? <CENTER> > -<? -<IMG SRC="gtk_tut_packbox1.gif" VSPACE="15" HSPACE="10" WIDTH="528" -HEIGHT="235" ALT="Box Packing Example Image"> -> -<? </CENTER> ></para> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="gtk_tut_packbox1.gif"> +</imageobject> +<imageobject> +<imagedata fileref="gtk_tut_packbox1.eps"> +</imageobject> +</inlinemediaobject> +</para> <para>Each line contains one horizontal box (hbox) with several buttons. The call to gtk_box_pack is shorthand for the call to pack each of the @@ -1137,13 +1141,13 @@ same way (i.e., same arguments to the gtk_box_pack_start() function).</para> <para>This is the declaration of the gtk_box_pack_start function.</para> -<para><literallayout> -<literal>void gtk_box_pack_start( GtkBox *box, +<programlisting role="C"> +void gtk_box_pack_start( GtkBox *box, GtkWidget *child, gint expand, gint fill, - gint padding );</literal> -</literallayout></para> + gint padding ); +</programlisting> <para>The first argument is the box you are packing the object into, the second is the object. The objects will all be buttons for now, so @@ -1165,10 +1169,10 @@ if the expand argument is also TRUE.</para> <para>When creating a new box, the function looks like this:</para> -<para><literallayout> -<literal>GtkWidget *gtk_hbox_new (gint homogeneous, - gint spacing);</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_hbox_new (gint homogeneous, + gint spacing); +</programlisting> <para>The homogeneous argument to gtk_hbox_new (and the same for gtk_vbox_new) controls whether each object in the box has the same @@ -1181,13 +1185,16 @@ and padding (set when elements are packed)? Spacing is added between objects, and padding is added on either side of an object. The following figure should make it clearer:</para> -<para><? <CENTER> > -<? -<IMG ALIGN="center" SRC="gtk_tut_packbox2.gif" WIDTH="509" -HEIGHT="213" VSPACE="15" HSPACE="10" -ALT="Box Packing Example Image"> -> -<? </CENTER> ></para> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="gtk_tut_packbox2.gif"> +</imageobject> +<imageobject> +<imagedata fileref="gtk_tut_packbox2.eps"> +</imageobject> +</inlinemediaobject> +</para> <para>Here is the code used to create the above images. I've commented it fairly heavily so I hope you won't have any problems following @@ -1509,11 +1516,11 @@ widgets may take up as many spaces as we specify.</para> <para>The first thing to look at, of course, is the gtk_table_new function:</para> -<para><literallayout> -<literal>GtkWidget *gtk_table_new( gint rows, +<programlisting role="C"> +GtkWidget *gtk_table_new( gint rows, gint columns, - gint homogeneous );</literal> -</literallayout></para> + gint homogeneous ); +</programlisting> <para>The first argument is the number of rows to make in the table, while the second, obviously, is the number of columns.</para> @@ -1594,14 +1601,14 @@ specified in pixels.</para> <para>gtk_table_attach() has a LOT of options. So, there's a shortcut:</para> -<para><literallayout> -<literal>void gtk_table_attach_defaults( GtkTable *table, +<programlisting role="C"> +void gtk_table_attach_defaults( GtkTable *table, GtkWidget *widget, gint left_attach, gint right_attach, gint top_attach, - gint bottom_attach );</literal> -</literallayout></para> + gint bottom_attach ); +</programlisting> <para>The X and Y options default to <literal>GTK_FILL | GTK_EXPAND</literal>, and X and Y padding are set to 0. The rest of the arguments are identical to the @@ -1611,36 +1618,36 @@ previous function.</para> gtk_table_set_col_spacing(). These places spacing between the rows at the specified row or column.</para> -<para><literallayout> -<literal>void gtk_table_set_row_spacing( GtkTable *table, +<programlisting role="C"> +void gtk_table_set_row_spacing( GtkTable *table, gint row, - gint spacing );</literal> -</literallayout></para> + gint spacing ); +</programlisting> <para>and</para> -<para><literallayout> -<literal>void gtk_table_set_col_spacing ( GtkTable *table, +<programlisting role="C"> +void gtk_table_set_col_spacing ( GtkTable *table, gint column, - gint spacing );</literal> -</literallayout></para> + gint spacing ); +</programlisting> <para>Note that for columns, the space goes to the right of the column, and for rows, the space goes below the row.</para> <para>You can also set a consistent spacing of all rows and/or columns with:</para> -<para><literallayout> -<literal>void gtk_table_set_row_spacings( GtkTable *table, - gint spacing );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_table_set_row_spacings( GtkTable *table, + gint spacing ); +</programlisting> <para>And,</para> -<para><literallayout> -<literal>void gtk_table_set_col_spacings( GtkTable *table, - gint spacing );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_table_set_col_spacings( GtkTable *table, + gint spacing ); +</programlisting> <para>Note that with these calls, the last row and last column do not get any spacing.</para> @@ -1656,12 +1663,16 @@ The first two buttons will be placed in the upper row. A third, quit button, is placed in the lower row, spanning both columns. Which means it should look something like this:</para> -<para><? <CENTER> > -<? -<IMG SRC="gtk_tut_table.gif" VSPACE="15" HSPACE="10" -ALT="Table Packing Example Image" WIDTH="180" HEIGHT="120"> -> -<? </CENTER> ></para> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="gtk_tut_table.gif"> +</imageobject> +<imageobject> +<imagedata fileref="gtk_tut_table.eps"> +</imageobject> +</inlinemediaobject> +</para> <para>Here's the source code:</para> @@ -1859,8 +1870,8 @@ learn how a widget works just by looking at the function declarations.</para> <para>For your reference, here is the class hierarchy tree used to implement widgets.</para> -<para><literallayout> -<literal> GtkObject +<programlisting role="C"> + GtkObject +GtkWidget | +GtkMisc | | +GtkLabel @@ -1952,8 +1963,8 @@ learn how a widget works just by looking at the function declarations.</para> +GtkData | +GtkAdjustment | `GtkTooltips - `GtkItemFactory</literal> -</literallayout></para> + `GtkItemFactory +</programlisting> </sect1> @@ -1965,8 +1976,8 @@ learn how a widget works just by looking at the function declarations.</para> capture events, you'll have to use the EventBox. See the section on the <link linkend="ch-EventBox">EventBox</link> widget.</para> -<para><literallayout> -<literal>GtkAlignment +<programlisting role="C"> +GtkAlignment GtkArrow GtkBin GtkBox @@ -1982,8 +1993,8 @@ GtkFrame GtkVBox GtkHBox GtkVSeparator -GtkHSeparator</literal> -</literallayout></para> +GtkHSeparator +</programlisting> <para>We'll further our exploration of GTK by examining each widget in turn, creating a few simple functions to display them. Another good source @@ -2202,8 +2213,8 @@ the "toggled" signal. To check the state of these buttons, set up a signal handler to catch the toggled signal, and access the structure to determine its state. The callback will look something like:</para> -<para><literallayout> -<literal>void toggle_button_callback (GtkWidget *widget, gpointer data) +<programlisting role="C"> +void toggle_button_callback (GtkWidget *widget, gpointer data) { if (GTK_TOGGLE_BUTTON (widget)->active) { @@ -2213,16 +2224,16 @@ to determine its state. The callback will look something like:</para> /* If control reaches here, the toggle button is up */ } -}</literal> -</literallayout></para> +} +</programlisting> <para>To force the state of a toggle button, and its children, the radio and check buttons, use this function:</para> -<para><literallayout> -<literal>void gtk_toggle_button_set_active( GtkToggleButton *toggle_button, - gint state );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_toggle_button_set_active( GtkToggleButton *toggle_button, + gint state ); +</programlisting> <para>The above call can be used to set the state of the toggle button, and its children the radio and check buttons. Passing in your created @@ -2234,9 +2245,9 @@ argument to specify whether it should be down (depressed) or up the state is actually changed, it causes the "clicked" signal to be emitted from the button.</para> -<para><literallayout> -<literal>void gtk_toggle_button_toggled (GtkToggleButton *toggle_button);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_toggle_button_toggled (GtkToggleButton *toggle_button); +</programlisting> <para>This simply toggles the button, and emits the "toggled" signal.</para> @@ -2254,11 +2265,11 @@ off in applications.</para> <para>The two creation functions are similar to those of the normal button.</para> -<para><literallayout> -<literal>GtkWidget *gtk_check_button_new( void );</para> +<programlisting role="C"> +GtkWidget *gtk_check_button_new( void ); -<para>GtkWidget *gtk_check_button_new_with_label ( gchar *label );</literal> -</literallayout></para> +GtkWidget *gtk_check_button_new_with_label ( gchar *label ); +</programlisting> <para>The new_with_label function creates a check button with a label beside it.</para> @@ -2269,7 +2280,8 @@ toggle button.</para> </sect1> <!-- ----------------------------------------------------------------- --> -<sect1> Radio Buttons <label id="ch-Radio_Buttons"></para> +<sect1> +<title>Radio Buttons</title> <para>Radio buttons are similar to check buttons except they are grouped so that only one may be selected/depressed at a time. This is good for @@ -2278,21 +2290,21 @@ of options.</para> <para>Creating a new radio button is done with one of these calls:</para> -<para><literallayout> -<literal>GtkWidget *gtk_radio_button_new( GSList *group );</para> +<programlisting role="C"> +GtkWidget *gtk_radio_button_new( GSList *group ); -<para>GtkWidget *gtk_radio_button_new_with_label( GSList *group, - gchar *label );</literal> -</literallayout></para> +GtkWidget *gtk_radio_button_new_with_label( GSList *group, + gchar *label ); +</programlisting> <para>You'll notice the extra argument to these calls. They require a group to perform their duty properly. The first call to gtk_radio_button_new_with_label or gtk_radio_button_new_with_label should pass NULL as the first argument. Then create a group using:</para> -<para><literallayout> -<literal>GSList *gtk_radio_button_group( GtkRadioButton *radio_button );</literal> -</literallayout></para> +<programlisting role="C"> +GSList *gtk_radio_button_group( GtkRadioButton *radio_button ); +</programlisting> <para>The important thing to remember is that gtk_radio_button_group must be called for each new button added to the group, with the previous @@ -2305,19 +2317,19 @@ established. The example below should make this clear.</para> removes the need for a variable to hold the list of buttons. This form is used in the example to create the third button:</para> -<para><literallayout> -<literal> button2 = gtk_radio_button_new_with_label( +<programlisting role="C"> + button2 = gtk_radio_button_new_with_label( gtk_radio_button_group (GTK_RADIO_BUTTON (button1)), - "button2");</literal> -</literallayout></para> + "button2"); +</programlisting> <para>It is also a good idea to explicitly set which button should be the default depressed button with:</para> -<para><literallayout> -<literal>void gtk_toggle_button_set_active( GtkToggleButton *toggle_button, - gint state );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_toggle_button_set_active( GtkToggleButton *toggle_button, + gint state ); +</programlisting> <para>This is described in the section on toggle buttons, and works in exactly the same way. Once the radio buttons are grouped together, @@ -2461,21 +2473,22 @@ that incorporate them: <link linkend="ch-Viewports">Viewports</link>, <link linkend="ch-ScrolledWindow">Scrolled Windows</link>, and others.</para> -<para><sect1> -<title> Creating an Adjustment</title> +<!-- ----------------------------------------------------------------- --> +<sect1> +<title>Creating an Adjustment</title> <para>Many of the widgets which use adjustment objects do so automatically, but some cases will be shown in later examples where you may need to create one yourself. You create an adjustment using:</para> -<para><literallayout> -<literal>GtkObject *gtk_adjustment_new( gfloat value, +<programlisting role="C"> +GtkObject *gtk_adjustment_new( gfloat value, gfloat lower, gfloat upper, gfloat step_increment, gfloat page_increment, - gfloat page_size );</literal> -</literallayout></para> + gfloat page_size ); +</programlisting> <para>The <literal>value</literal> argument is the initial value you want to give to the adjustment, usually corresponding to the topmost or leftmost position @@ -2526,12 +2539,12 @@ you <emphasis>share</emphasis> an adjustment object between a scrollbar and a te widget, manipulating the scrollbar will automagically adjust the text widget? Of course it will! Just like this:</para> -<para><literallayout> -<literal> /* creates its own adjustments */ +<programlisting role="C"> + /* creates its own adjustments */ text = gtk_text_new (NULL, NULL); /* uses the newly-created adjustment for the scrollbar as well */ - vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj);</literal> -</literallayout></para> + vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj); +</programlisting> </sect1> @@ -2545,8 +2558,8 @@ how do I get at the value of the adjustment in these handlers? To answer these questions and more, let's start by taking a look at <literal>struct _GtkAdjustment</literal> itself:</para> -<para><literallayout> -<literal>struct _GtkAdjustment +<programlisting role="C"> +struct _GtkAdjustment { GtkData data; @@ -2556,8 +2569,8 @@ answer these questions and more, let's start by taking a look at gfloat step_increment; gfloat page_increment; gfloat page_size; -}; </literal> -</literallayout></para> +}; +</programlisting> <para>The first thing you should know is that there aren't any handy-dandy macros or accessor functions for getting the <literal>value</literal> out of an @@ -2570,10 +2583,10 @@ type-casting macros, actually).</para> want the change to be reflected by every widget that uses this adjustment, GTK provides this convenience function to do this:</para> -<para><literallayout> -<literal>void gtk_adjustment_set_value( GtkAdjustment *adjustment, - gfloat value );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_adjustment_set_value( GtkAdjustment *adjustment, + gfloat value ); +</programlisting> <para>As mentioned earlier, Adjustment is a subclass of Object just like all the various widgets, and thus it is able to emit signals. @@ -2583,9 +2596,9 @@ all adjustable widgets connect signal handlers to their adjustment's <literal>value_changed</literal> signal, as can your program. Here's the definition of this signal in <literal>struct _GtkAdjustmentClass</literal>:</para> -<para><literallayout> -<literal> void (* value_changed) (GtkAdjustment *adjustment);</literal> -</literallayout></para> +<programlisting role="C"> + void (* value_changed) (GtkAdjustment *adjustment); +</programlisting> <para>The various widgets that use the Adjustment object will emit this signal on an adjustment whenever they change its value. This happens @@ -2595,28 +2608,28 @@ well as when the program explicitly changes the value with widget, and you want to change the rotation of a picture whenever its value changes, you would create a callback like this:</para> -<para><literallayout> -<literal>void cb_rotate_picture (GtkAdjustment *adj, GtkWidget *picture) +<programlisting role="C"> +void cb_rotate_picture (GtkAdjustment *adj, GtkWidget *picture) { set_picture_rotation (picture, adj->value); -...</literal> -</literallayout></para> +... +</programlisting> <para>and connect it to the scale widget's adjustment like this:</para> -<para><literallayout> -<literal>gtk_signal_connect (GTK_OBJECT (adj), "value_changed", - GTK_SIGNAL_FUNC (cb_rotate_picture), picture);</literal> -</literallayout></para> +<programlisting role="C"> +gtk_signal_connect (GTK_OBJECT (adj), "value_changed", + GTK_SIGNAL_FUNC (cb_rotate_picture), picture); +</programlisting> <para>What about when a widget reconfigures the <literal>upper</literal> or <literal>lower</literal> fields of its adjustment, such as when a user adds more text to a text widget? In this case, it emits the <literal>changed</literal> signal, which looks like this:</para> -<para><literallayout> -<literal> void (* changed) (GtkAdjustment *adjustment);</literal> -</literallayout></para> +<programlisting role="C"> + void (* changed) (GtkAdjustment *adjustment); +</programlisting> <para>Range widgets typically connect a handler to this signal, which changes their appearance to reflect the change - for example, the size @@ -2630,9 +2643,9 @@ change any of the values in a Adjustment directly, you should emit this signal on it to reconfigure whatever widgets are using it, like this:</para> -<para><literallayout> -<literal>gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed");</literal> -</literallayout></para> +<programlisting role="C"> +gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed"); +</programlisting> <para>Now go forth and adjust!</para> @@ -2640,10 +2653,9 @@ this:</para> </chapter> <!-- ***************************************************************** --> -<chapter id="ch-Range Widgets"> +<chapter id="ch-RangeWidgets"> <title>Range Widgets</title> -<para> <para>The category of range widgets includes the ubiquitous scrollbar widget and the less common "scale" widget. Though these two types of widgets are generally used for different purposes, they are quite similar in @@ -2664,7 +2676,7 @@ change the value of the adjustment.</para> <!-- ----------------------------------------------------------------- --> <sect1> -<title> Scrollbar Widgets</title> +<title>Scrollbar Widgets</title> <para>These are your standard, run-of-the-mill scrollbars. These should be used only for scrolling some other widget, such as a list, a text box, @@ -2677,11 +2689,11 @@ There really isn't much to say about these. You create them with the following functions, defined in <literal><gtk/gtkhscrollbar.h></literal> and <literal><gtk/gtkvscrollbar.h></literal>:</para> -<para><literallayout> -<literal>GtkWidget *gtk_hscrollbar_new( GtkAdjustment *adjustment );</para> +<programlisting role="C"> +GtkWidget *gtk_hscrollbar_new( GtkAdjustment *adjustment ); -<para>GtkWidget *gtk_vscrollbar_new( GtkAdjustment *adjustment );</literal> -</literallayout></para> +GtkWidget *gtk_vscrollbar_new( GtkAdjustment *adjustment ); +</programlisting> <para>and that's about it (if you don't believe me, look in the header files!). The <literal>adjustment</literal> argument can either be a pointer to an @@ -2716,13 +2728,11 @@ in <literal><gtk/gtkvscale.h></literal> and <literal><gtk/gtkhscale.h></literal>, create vertical and horizontal scale widgets, respectively:</para> -<para><tscreen> -<verb> -GtkWidget *gtk_vscale_new( GtkAdjustment *adjustment );</para> +<programlisting role="C"> +GtkWidget *gtk_vscale_new( GtkAdjustment *adjustment ); -<para>GtkWidget *gtk_hscale_new( GtkAdjustment *adjustment ); -</verb> -</tscreen></para> +GtkWidget *gtk_hscale_new( GtkAdjustment *adjustment ); +</programlisting> <para>The <literal>adjustment</literal> argument can either be an adjustment which has already been created with <literal>gtk_adjustment_new()</literal>, or <literal>NULL</literal>, in @@ -2731,24 +2741,24 @@ values set to <literal>0.0</literal> (which isn't very useful in this case). In order to avoid confusing yourself, you probably want to create your adjustment with a <literal>page_size</literal> of <literal>0.0</literal> so that its <literal>upper</literal> value actually corresponds to the highest value the user can select. -(If you're <emphasis>already</emphasis> thoroughly confused, read the section on <ref -id="ch-Adjustment"> Adjustments </ulink> again for an explanation of +(If you're <emphasis>already</emphasis> thoroughly confused, read the section on <link +linkend="ch-Adjustment">Adjustments</link> again for an explanation of what exactly adjustments do and how to create and manipulate them.)</para> </sect2> <!-- ----------------------------------------------------------------- --> <sect2> -<title> Functions and Signals (well, functions, at least)</title> +<title>Functions and Signals (well, functions, at least)</title> <para>Scale widgets can display their current value as a number beside the trough. The default behaviour is to show the value, but you can change this with this function:</para> -<para><literallayout> -<literal>void gtk_scale_set_draw_value( GtkScale *scale, - gint draw_value );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_scale_set_draw_value( GtkScale *scale, + gint draw_value ); +</programlisting> <para>As you might have guessed, <literal>draw_value</literal> is either <literal>TRUE</literal> or <literal>FALSE</literal>, with predictable consequences for either one.</para> @@ -2757,12 +2767,10 @@ this with this function:</para> by default, as is the <literal>value</literal> field in its GtkAdjustment. You can change this with:</para> -<para><tscreen> -<verb> +<programlisting role="C"> void gtk_scale_set_digits( GtkScale *scale, gint digits ); -</verb> -</tscreen></para> +</programlisting> <para>where <literal>digits</literal> is the number of decimal places you want. You can set <literal>digits</literal> to anything you like, but no more than 13 decimal @@ -2771,23 +2779,21 @@ places will actually be drawn on screen.</para> <para>Finally, the value can be drawn in different positions relative to the trough:</para> -<para><tscreen> -<verb> +<programlisting role="C"> void gtk_scale_set_value_pos( GtkScale *scale, GtkPositionType pos ); -</verb> -</tscreen></para> +</programlisting> <para>The argument <literal>pos</literal> is of type <literal>GtkPositionType</literal>, which is defined in <literal><gtk/gtkenums.h></literal>, and can take one of the following values:</para> -<para><literallayout> -<literal> GTK_POS_LEFT +<programlisting role="C"> + GTK_POS_LEFT GTK_POS_RIGHT GTK_POS_TOP - GTK_POS_BOTTOM</literal> -</literallayout></para> + GTK_POS_BOTTOM +</programlisting> <para>If you position the value on the "side" of the trough (e.g., on the top or bottom of a horizontal scale widget), then it will follow the @@ -2803,7 +2809,8 @@ of all widgets that interest you,</para> </sect1> <!-- ----------------------------------------------------------------- --> -<sect1> Common Range Functions +<sect1> +<title>Common Range Functions</title> <para>The Range widget class is fairly complicated internally, but, like all the "base class" widgets, most of its complexity is only @@ -2813,11 +2820,9 @@ derived widgets. There are, however, a few useful functions that are defined in <literal><gtk/gtkrange.h></literal> and will work on all range widgets.</para> -</sect1> - <!-- ----------------------------------------------------------------- --> <sect2> -<title> Setting the Update Policy</title> +<title>Setting the Update Policy</title> <para>The "update policy" of a range widget defines at what points during user interaction it will change the <literal>value</literal> field of its @@ -2829,28 +2834,27 @@ are:</para> <itemizedlist> <listitem><simpara>GTK_UPDATE_POLICY_CONTINUOUS - This is the default. The "value_changed" signal is emitted continuously, i.e., whenever the -slider is moved by even the tiniest amount. -</item></simpara> +slider is moved by even the tiniest amount.</simpara> </listitem> + <listitem><simpara>GTK_UPDATE_POLICY_DISCONTINUOUS - The "value_changed" signal is only emitted once the slider has stopped moving and the user has -released the mouse button. -</item></simpara> +released the mouse button.</simpara> </listitem> + <listitem><simpara>GTK_UPDATE_POLICY_DELAYED - The "value_changed" signal is emitted when the user releases the mouse button, or if the slider stops moving -for a short period of time. -</item></simpara> +for a short period of time.</simpara> </listitem> </itemizedlist> <para>The update policy of a range widget can be set by casting it using the <literal>GTK_RANGE (Widget)</literal> macro and passing it to this function:</para> -<para><literallayout> -<literal>void gtk_range_set_update_policy( GtkRange *range, - GtkUpdateType policy) ;</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_range_set_update_policy( GtkRange *range, + GtkUpdateType policy); +</programlisting> </sect2> @@ -2861,12 +2865,12 @@ for a short period of time. <para>Getting and setting the adjustment for a range widget "on the fly" is done, predictably, with:</para> -<para><literallayout> -<literal>GtkAdjustment* gtk_range_get_adjustment( GtkRange *range );</para> +<programlisting role="C"> +GtkAdjustment* gtk_range_get_adjustment( GtkRange *range ); -<para>void gtk_range_set_adjustment( GtkRange *range, - GtkAdjustment *adjustment );</literal> -</literallayout></para> +void gtk_range_set_adjustment( GtkRange *range, + GtkAdjustment *adjustment ); +</programlisting> <para><literal>gtk_range_get_adjustment()</literal> returns a pointer to the adjustment to which <literal>range</literal> is connected.</para> @@ -2883,15 +2887,16 @@ section on adjustments, if you wish to reuse the same Adjustment, when you modify its values directly, you should emit the "changed" signal on it, like this:</para> -<para><literallayout> -<literal>gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed");</literal> -</literallayout></para> +<programlisting role="C"> +gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed"); +</programlisting> + </sect2> </sect1> <!-- ----------------------------------------------------------------- --> <sect1> -<title> Key and Mouse bindings</title> +<title>Key and Mouse bindings</title> <para>All of the GTK range widgets react to mouse clicks in more or less the same way. Clicking button-1 in the trough will cause its @@ -2907,9 +2912,9 @@ think your users will find this too confusing, you can always disable this by unsetting the <literal>GTK_CAN_FOCUS</literal> flag on the scrollbar, like this:</para> -<para><literallayout> -<literal>GTK_WIDGET_UNSET_FLAGS (scrollbar, GTK_CAN_FOCUS);</literal> -</literallayout></para> +<programlisting role="C"> +GTK_WIDGET_UNSET_FLAGS (scrollbar, GTK_CAN_FOCUS); +</programlisting> <para>The key bindings (which are, of course, only active when the widget has focus) are slightly different between horizontal and vertical @@ -2919,8 +2924,9 @@ obvious reasons (possibly to avoid confusion between the keys for horizontal and vertical scrollbars in scrolled windows, where both operate on the same area).</para> -<para><sect2> -<title> Vertical Range Widgets</title> +<!-- ----------------------------------------------------------------- --> +<sect2> +<title>Vertical Range Widgets</title> <para>All vertical range widgets can be operated with the up and down arrow keys, as well as with the <literal>Page Up</literal> and <literal>Page Down</literal> keys. The @@ -2933,6 +2939,8 @@ done with the <literal>Home</literal> and <literal>End</literal> keys, whereas w VScrollbar widget, this is done by typing <literal>Control-Page Up</literal> and <literal>Control-Page Down</literal>.</para> +</sect2> + <!-- ----------------------------------------------------------------- --> <sect2> <title> Horizontal Range Widgets</title> @@ -2949,7 +2957,8 @@ while for HScrollbar, it's done with <literal>Control-Home</literal> and </sect1> <!-- ----------------------------------------------------------------- --> -<sect1> Example +<sect1> +<title>Example</title> <para>This example is a somewhat modified version of the "range controls" test from <literal>testgtk.c</literal>. It basically puts up a window with three @@ -3276,18 +3285,18 @@ EventBox</link> widget or a Button widget.</para> <para>To create a new label, use:</para> -<para><literallayout> -<literal>GtkWidget *gtk_label_new( char *str );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_label_new( char *str ); +</programlisting> <para>The sole argument is the string you wish the label to display.</para> <para>To change the label's text after creation, use the function:</para> -<para><literallayout> -<literal>void gtk_label_set_text( GtkLabel *label, - char *str );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_label_set_text( GtkLabel *label, + char *str ); +</programlisting> <para>The first argument is the label you created previously (cast using the <literal>GTK_LABEL()</literal> macro), and the second is the new string.</para> @@ -3298,10 +3307,10 @@ the label string.</para> <para>To retrieve the current string, use:</para> -<para><literallayout> -<literal>void gtk_label_get( GtkLabel *label, - char **str );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_label_get( GtkLabel *label, + char **str ); +</programlisting> <para>The first argument is the label you've created, and the second, the return for the string. Do not free the return string, as it is @@ -3309,41 +3318,41 @@ used internally by GTK.</para> <para>The label text can be justified using:</para> -<para><literallayout> -<literal>void gtk_label_set_justify( GtkLabel *label, - GtkJustification jtype );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_label_set_justify( GtkLabel *label, + GtkJustification jtype ); +</programlisting> <para>Values for <literal>jtype</literal> are:</para> -<para><literallayout> -<literal> GTK_JUSTIFY_LEFT +<programlisting role="C"> + GTK_JUSTIFY_LEFT GTK_JUSTIFY_RIGHT GTK_JUSTIFY_CENTER (the default) - GTK_JUSTIFY_FILL</literal> -</literallayout></para> + GTK_JUSTIFY_FILL +</programlisting> <para>The label widget is also capable of line wrapping the text automatically. This can be activated using:</para> -<para><literallayout> -<literal>void gtk_label_set_line_wrap (GtkLabel *label, - gboolean wrap);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_label_set_line_wrap (GtkLabel *label, + gboolean wrap); +</programlisting> <para>The <literal>wrap</literal> argument takes a TRUE or FALSE value.</para> <para>If you want your label underlined, then you can set a pattern on the label:</para> -<para><literallayout> -<literal>void gtk_label_set_pattern (GtkLabel *label, - const gchar *pattern);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_label_set_pattern (GtkLabel *label, + const gchar *pattern); +</programlisting> <para>The pattern argument indicates how the underlining should look. It consists of a string of underscore and space characters. An underscore indicates that the corresponding character in the label should be -underlined. For example, the string <verb/"__ __"/ would underline the +underlined. For example, the string <literal>"__ __"</literal> would underline the first two characters and eight and ninth characters.</para> <para>Below is a short example to illustrate these functions. This example @@ -3457,7 +3466,7 @@ int main( int argc, <!-- ----------------------------------------------------------------- --> <sect1> -<title> Arrows</title> +<title>Arrows</title> <para>The Arrow widget draws an arrowhead, facing in a number of possible directions and having a number of possible styles. It can be very @@ -3466,36 +3475,36 @@ widget, it emits no signals.</para> <para>There are only two functions for manipulating an Arrow widget:</para> -<para><literallayout> -<literal>GtkWidget *gtk_arrow_new( GtkArrowType arrow_type, - GtkShadowType shadow_type );</para> +<programlisting role="C"> +GtkWidget *gtk_arrow_new( GtkArrowType arrow_type, + GtkShadowType shadow_type ); -<para>void gtk_arrow_set( GtkArrow *arrow, +void gtk_arrow_set( GtkArrow *arrow, GtkArrowType arrow_type, - GtkShadowType shadow_type );</literal> -</literallayout></para> + GtkShadowType shadow_type ); +</programlisting> <para>The first creates a new arrow widget with the indicated type and appearance. The second allows these values to be altered retrospectively. The <literal>arrow_type</literal> argument may take one of the following values:</para> -<para><literallayout> -<literal> GTK_ARROW_UP +<programlisting role="C"> + GTK_ARROW_UP GTK_ARROW_DOWN GTK_ARROW_LEFT - GTK_ARROW_RIGHT</literal> -</literallayout></para> + GTK_ARROW_RIGHT +</programlisting> <para>These values obviously indicate the direction in which the arrow will point. The <literal>shadow_type</literal> argument may take one of these values:</para> -<para><literallayout> -<literal> GTK_SHADOW_IN +<programlisting role="C"> + GTK_SHADOW_IN GTK_SHADOW_OUT (the default) GTK_SHADOW_ETCHED_IN - GTK_SHADOW_ETCHED_OUT</literal> -</literallayout></para> + GTK_SHADOW_ETCHED_OUT +</programlisting> <para>Here's a brief example to illustrate their use.</para> @@ -3595,19 +3604,19 @@ own window) will not work with tooltips.</para> this once for a set of tooltips as the <literal>GtkTooltips</literal> object this function returns can be used to create multiple tooltips.</para> -<para><literallayout> -<literal>GtkTooltips *gtk_tooltips_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkTooltips *gtk_tooltips_new( void ); +</programlisting> <para>Once you have created a new tooltip, and the widget you wish to use it on, simply use this call to set it:</para> -<para><literallayout> -<literal>void gtk_tooltips_set_tip( GtkTooltips *tooltips, +<programlisting role="C"> +void gtk_tooltips_set_tip( GtkTooltips *tooltips, GtkWidget *widget, const gchar *tip_text, - const gchar *tip_private );</literal> -</literallayout></para> + const gchar *tip_private ); +</programlisting> <para>The first argument is the tooltip you've already created, followed by the widget you wish to have this tooltip pop up for, and the text you @@ -3615,12 +3624,12 @@ wish it to say. The last argument is a text string that can be used as an identifier when using GtkTipsQuery to implement context sensitive help. For now, you can set it to NULL.</para> -<para><!-- TODO: sort out what how to do the context sensitive help --></para> +<!-- TODO: sort out what how to do the context sensitive help --> <para>Here's a short example:</para> -<para><literallayout> -<literal>GtkTooltips *tooltips; +<programlisting role="C"> +GtkTooltips *tooltips; GtkWidget *button; . . @@ -3630,39 +3639,38 @@ button = gtk_button_new_with_label ("button 1"); . . . -gtk_tooltips_set_tip (tooltips, button, "This is button 1", NULL);</literal> -</literallayout></para> +gtk_tooltips_set_tip (tooltips, button, "This is button 1", NULL); +</programlisting> <para>There are other calls that can be used with tooltips. I will just list them with a brief description of what they do.</para> -<para><literallayout> -<literal>void gtk_tooltips_enable( GtkTooltips *tooltips );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tooltips_enable( GtkTooltips *tooltips ); +</programlisting> <para>Enable a disabled set of tooltips.</para> -<para><literallayout> -<literal>void gtk_tooltips_disable( GtkTooltips *tooltips );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tooltips_disable( GtkTooltips *tooltips ); +</programlisting> <para>Disable an enabled set of tooltips.</para> -<para><literallayout> -<literal>void gtk_tooltips_set_delay( GtkTooltips *tooltips, - gint delay );</para> - -<para></verb></tscreen></para> +<programlisting role="C"> +void gtk_tooltips_set_delay( GtkTooltips *tooltips, + gint delay ); +</programlisting> <para>Sets how many milliseconds you have to hold your pointer over the widget before the tooltip will pop up. The default is 500 milliseconds (half a second).</para> -<para><literallayout> -<literal>void gtk_tooltips_set_colors( GtkTooltips *tooltips, +<programlisting role="C"> +void gtk_tooltips_set_colors( GtkTooltips *tooltips, GdkColor *background, - GdkColor *foreground );</literal> -</literallayout></para> + GdkColor *foreground ); +</programlisting> <para>Set the foreground and background color of the tooltips.</para> @@ -3672,7 +3680,8 @@ you'll ever want to know :-)</para> </sect1> <!-- ----------------------------------------------------------------- --> -<sect1> Progress Bars +<sect1> +<title>Progress Bars</title> <para>Progress bars are used to show the status of an operation. They are pretty easy to use, as you will see with the code below. But first @@ -3683,28 +3692,28 @@ no arguments, and one that takes an Adjustment object as an argument. If the former is used, the progress bar creates its own adjustment object.</para> -<para><literallayout> -<literal>GtkWidget *gtk_progress_bar_new( void );</para> +<programlisting role="C"> +GtkWidget *gtk_progress_bar_new( void ); -<para>GtkWidget *gtk_progress_bar_new_with_adjustment( GtkAdjustment *adjustment );</literal> -</literallayout></para> +GtkWidget *gtk_progress_bar_new_with_adjustment( GtkAdjustment *adjustment ); +</programlisting> <para>The second method has the advantage that we can use the adjustment object to specify our own range parameters for the progress bar.</para> <para>The adjustment of a progress object can be changed dynamically using:</para> -<para><literallayout> -<literal>void gtk_progress_set_adjustment( GtkProgress *progress, - GtkAdjustment *adjustment );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_set_adjustment( GtkProgress *progress, + GtkAdjustment *adjustment ); +</programlisting> <para>Now that the progress bar has been created we can use it.</para> -<para><literallayout> -<literal>void gtk_progress_bar_update( GtkProgressBar *pbar, - gfloat percentage );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_bar_update( GtkProgressBar *pbar, + gfloat percentage ); +</programlisting> <para>The first argument is the progress bar you wish to operate on, and the second argument is the amount "completed", meaning the amount the @@ -3718,20 +3727,20 @@ its current value and its range.</para> <para>A progress bar may be set to one of a number of orientations using the function</para> -<para><literallayout> -<literal>void gtk_progress_bar_set_orientation( GtkProgressBar *pbar, - GtkProgressBarOrientation orientation );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_bar_set_orientation( GtkProgressBar *pbar, + GtkProgressBarOrientation orientation ); +</programlisting> <para>The <literal>orientation</literal> argument may take one of the following values to indicate the direction in which the progress bar moves:</para> -<para><literallayout> -<literal> GTK_PROGRESS_LEFT_TO_RIGHT +<programlisting role="C"> + GTK_PROGRESS_LEFT_TO_RIGHT GTK_PROGRESS_RIGHT_TO_LEFT GTK_PROGRESS_BOTTOM_TO_TOP - GTK_PROGRESS_TOP_TO_BOTTOM</literal> -</literallayout></para> + GTK_PROGRESS_TOP_TO_BOTTOM +</programlisting> <para>When used as a measure of how far a process has progressed, the ProgressBar can be set to display its value in either a continuous @@ -3741,24 +3750,24 @@ of discrete blocks. The number of blocks is also configurable.</para> <para>The style of a progress bar can be set using the following function.</para> -<para><literallayout> -<literal>void gtk_progress_bar_set_bar_style( GtkProgressBar *pbar, - GtkProgressBarStyle style );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_bar_set_bar_style( GtkProgressBar *pbar, + GtkProgressBarStyle style ); +</programlisting> <para>The <literal>style</literal> parameter can take one of two values:</para> -<para><literallayout> -<literal> GTK_PROGRESS_CONTINUOUS - GTK_PROGRESS_DISCRETE</literal> -</literallayout></para> +<programlisting role="C"> + GTK_PROGRESS_CONTINUOUS + GTK_PROGRESS_DISCRETE +</programlisting> <para>The number of discrete blocks can be set by calling</para> -<para><literallayout> -<literal>void gtk_progress_bar_set_discrete_blocks( GtkProgressBar *pbar, - guint blocks );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_bar_set_discrete_blocks( GtkProgressBar *pbar, + guint blocks ); +</programlisting> <para>As well as indicating the amount of progress that has occured, the progress bar may be set to just indicate that there is some @@ -3767,30 +3776,30 @@ measured against a value range. Activity mode is not effected by the bar style that is described above, and overrides it. This mode is either TRUE or FALSE, and is selected by the following function.</para> -<para><literallayout> -<literal>void gtk_progress_set_activity_mode( GtkProgress *progress, - guint activity_mode );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_set_activity_mode( GtkProgress *progress, + guint activity_mode ); +</programlisting> <para>The step size of the activity indicator, and the number of blocks are set using the following functions.</para> -<para><literallayout> -<literal>void gtk_progress_bar_set_activity_step( GtkProgressBar *pbar, - guint step );</para> +<programlisting role="C"> +void gtk_progress_bar_set_activity_step( GtkProgressBar *pbar, + guint step ); -<para>void gtk_progress_bar_set_activity_blocks( GtkProgressBar *pbar, - guint blocks );</literal> -</literallayout></para> +void gtk_progress_bar_set_activity_blocks( GtkProgressBar *pbar, + guint blocks ); +</programlisting> <para>When in continuous mode, the progress bar can also display a configurable text string within its trough, using the following function.</para> -<para><literallayout> -<literal>void gtk_progress_set_format_string( GtkProgress *progress, - gchar *format);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_set_format_string( GtkProgress *progress, + gchar *format); +</programlisting> <para>The <literal>format</literal> argument is similiar to one that would be used in a C <literal>printf</literal> statement. The following directives may be used within the @@ -3809,19 +3818,19 @@ format string:</para> <para>The displaying of this text string can be toggled using:</para> -<para><literallayout> -<literal>void gtk_progress_set_show_text( GtkProgress *progress, - gint show_text );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_progress_set_show_text( GtkProgress *progress, + gint show_text ); +</programlisting> <para>The <literal>show_text</literal> argument is a boolean TRUE/FALSE value. The appearance of the text can be modified further using:</para> -<para><literallayout> -<literal>void gtk_progress_set_text_alignment( GtkProgress *progress, +<programlisting role="C"> +void gtk_progress_set_text_alignment( GtkProgress *progress, gfloat x_align, - gfloat y_align );</literal> -</literallayout></para> + gfloat y_align ); +</programlisting> <para>The <literal>x_align</literal> and <literal>y_align</literal> arguments take values between 0.0 and 1.0. Their values indicate the position of the text string within @@ -3836,22 +3845,22 @@ freed by the application (using the g_free() function). These functions return the formatted string that would be displayed within the trough.</para> -<para><literallayout> -<literal>gchar *gtk_progress_get_current_text( GtkProgress *progress );</para> +<programlisting role="C"> +gchar *gtk_progress_get_current_text( GtkProgress *progress ); -<para>gchar *gtk_progress_get_text_from_value( GtkProgress *progress, - gfloat value );</literal> -</literallayout></para> +gchar *gtk_progress_get_text_from_value( GtkProgress *progress, + gfloat value ); +</programlisting> <para>There is yet another way to change the range and value of a progress object using the following function:</para> -<para><literallayout> -<literal>void gtk_progress_configure( GtkProgress *progress, +<programlisting role="C"> +void gtk_progress_configure( GtkProgress *progress, gfloat value, gfloat min, - gfloat max );</literal> -</literallayout></para> + gfloat max ); +</programlisting> <para>This function provides quite a simple interface to the range and value of a progress object.</para> @@ -3859,20 +3868,20 @@ of a progress object.</para> <para>The remaining functions can be used to get and set the current value of a progess object in various types and formats:</para> -<para><literallayout> -<literal>void gtk_progress_set_percentage( GtkProgress *progress, - gfloat percentage );</para> +<programlisting role="C"> +void gtk_progress_set_percentage( GtkProgress *progress, + gfloat percentage ); -<para>void gtk_progress_set_value( GtkProgress *progress, - gfloat value );</para> +void gtk_progress_set_value( GtkProgress *progress, + gfloat value ); -<para>gfloat gtk_progress_get_value( GtkProgress *progress );</para> +gfloat gtk_progress_get_value( GtkProgress *progress ); -<para>gfloat gtk_progress_get_current_percentage( GtkProgress *progress );</para> +gfloat gtk_progress_get_current_percentage( GtkProgress *progress ); -<para>gfloat gtk_progress_get_percentage_from_value( GtkProgress *progress, - gfloat value );</literal> -</literallayout></para> +gfloat gtk_progress_get_percentage_from_value( GtkProgress *progress, + gfloat value ); +</programlisting> <para>These functions are pretty self explanatory. The last function uses the the adjustment of the specified progess object to compute the @@ -4119,15 +4128,15 @@ int main( int argc, <para>The Dialog widget is very simple, and is actually just a window with a few things pre-packed into it for you. The structure for a Dialog is:</para> -<para><literallayout> -<literal>struct GtkDialog +<programlisting role="C"> +struct GtkDialog { GtkWindow window; GtkWidget *vbox; GtkWidget *action_area; -};</literal> -</literallayout></para> +}; +</programlisting> <para>So you see, it simply creates a window, and then packs a vbox into the top, which contains a separator and then an hbox called the @@ -4137,36 +4146,36 @@ top, which contains a separator and then an hbox called the other similar tasks. It is really basic, and there is only one function for the dialog box, which is:</para> -<para><literallayout> -<literal>GtkWidget *gtk_dialog_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_dialog_new( void ); +</programlisting> <para>So to create a new dialog box, use,</para> -<para><literallayout> -<literal> GtkWidget *window; - window = gtk_dialog_new ();</literal> -</literallayout></para> +<programlisting role="C"> + GtkWidget *window; + window = gtk_dialog_new (); +</programlisting> <para>This will create the dialog box, and it is now up to you to use it. You could pack a button in the action_area by doing something like this:</para> -<para><literallayout> -<literal> button = ... +<programlisting role="C"> + button = ... gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button, TRUE, TRUE, 0); - gtk_widget_show (button);</literal> -</literallayout></para> + gtk_widget_show (button); +</programlisting> <para>And you could add to the vbox area by packing, for instance, a label in it, try something like this:</para> -<para><literallayout> -<literal> label = gtk_label_new ("Dialogs are groovy"); +<programlisting role="C"> + label = gtk_label_new ("Dialogs are groovy"); gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->vbox), label, TRUE, TRUE, 0); - gtk_widget_show (label);</literal> -</literallayout></para> + gtk_widget_show (label); +</programlisting> <para>As an example in using the dialog box, you could put two buttons in the action_area, a Cancel button and an Ok button, and a label in the @@ -4183,7 +4192,8 @@ vertical box.</para> </sect1> <!-- ----------------------------------------------------------------- --> -<sect1> Pixmaps +<sect1> +<title>Pixmaps</title> <para>Pixmaps are data structures that contain pictures. These pictures can be used in various places, but most commonly as icons on the X @@ -4212,12 +4222,12 @@ routines from the GDK layer. Pixmaps can either be created from in-memory data, or from data read from a file. We'll go through each of the calls to create a pixmap.</para> -<para><literallayout> -<literal>GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window, +<programlisting role="C"> +GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window, gchar *data, gint width, - gint height );</literal> -</literallayout></para> + gint height ); +</programlisting> <para>This routine is used to create a single-plane pixmap (2 colors) from data in memory. Each bit of the data represents whether that pixel is @@ -4225,26 +4235,26 @@ off or on. Width and height are in pixels. The GdkWindow pointer is to the current window, since a pixmap's resources are meaningful only in the context of the screen where it is to be displayed.</para> -<para><literallayout> -<literal>GdkPixmap *gdk_pixmap_create_from_data( GdkWindow *window, +<programlisting role="C"> +GdkPixmap *gdk_pixmap_create_from_data( GdkWindow *window, gchar *data, gint width, gint height, gint depth, GdkColor *fg, - GdkColor *bg );</literal> -</literallayout></para> + GdkColor *bg ); +</programlisting> <para>This is used to create a pixmap of the given depth (number of colors) from the bitmap data specified. <literal>fg</literal> and <literal>bg</literal> are the foreground and background color to use.</para> -<para><literallayout> -<literal>GdkPixmap *gdk_pixmap_create_from_xpm( GdkWindow *window, +<programlisting role="C"> +GdkPixmap *gdk_pixmap_create_from_xpm( GdkWindow *window, GdkBitmap **mask, GdkColor *transparent_color, - const gchar *filename );</literal> -</literallayout></para> + const gchar *filename ); +</programlisting> <para>XPM format is a readable pixmap representation for the X Window System. It is widely used and many different utilities are available @@ -4254,12 +4264,12 @@ the pixmap structure. The mask specifies which bits of the pixmap are opaque. All other bits are colored using the color specified by transparent_color. An example using this follows below.</para> -<para><literallayout> -<literal>GdkPixmap *gdk_pixmap_create_from_xpm_d( GdkWindow *window, +<programlisting role="C"> +GdkPixmap *gdk_pixmap_create_from_xpm_d( GdkWindow *window, GdkBitmap **mask, GdkColor *transparent_color, - gchar **data );</literal> -</literallayout></para> + gchar **data ); +</programlisting> <para>Small images can be incorporated into a program as data in the XPM format. A pixmap is created using this data, instead of reading it @@ -4287,8 +4297,8 @@ static const char * xpm_data[] = { " .XXXXXXX. ", " ......... ", " ", -" "};</literal> -</literallayout></para> +" "}; +</programlisting> <para>When we're done using a pixmap and not likely to reuse it again soon, it is a good idea to release the resource using @@ -4301,24 +4311,24 @@ the user may be running the X server on a small personal computer.</para> must create a GTK pixmap widget to contain the GDK pixmap. This is done using</para> -<para><literallayout> -<literal>GtkWidget *gtk_pixmap_new( GdkPixmap *pixmap, - GdkBitmap *mask );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_pixmap_new( GdkPixmap *pixmap, + GdkBitmap *mask ); +</programlisting> <para>The other pixmap widget calls are</para> -<para><literallayout> -<literal>guint gtk_pixmap_get_type( void );</para> +<programlisting role="C"> +guint gtk_pixmap_get_type( void ); -<para>void gtk_pixmap_set( GtkPixmap *pixmap, +void gtk_pixmap_set( GtkPixmap *pixmap, GdkPixmap *val, - GdkBitmap *mask );</para> + GdkBitmap *mask ); -<para>void gtk_pixmap_get( GtkPixmap *pixmap, +void gtk_pixmap_get( GtkPixmap *pixmap, GdkPixmap **val, - GdkBitmap **mask);</literal> -</literallayout></para> + GdkBitmap **mask); +</programlisting> <para>gtk_pixmap_set is used to change the pixmap that the widget is currently managing. Val is the pixmap created using GDK.</para> @@ -4421,15 +4431,15 @@ int main( int argc, <para>To load a file from an XPM data file called icon0.xpm in the current directory, we would have created the pixmap thus</para> -<para><literallayout> -<literal> /* load a pixmap from a file */ +<programlisting role="C"> + /* load a pixmap from a file */ pixmap = gdk_pixmap_create_from_xpm( window->window, &mask, &style->bg[GTK_STATE_NORMAL], "./icon0.xpm" ); pixmapwid = gtk_pixmap_new( pixmap, mask ); gtk_widget_show( pixmapwid ); - gtk_container_add( GTK_CONTAINER(window), pixmapwid );</literal> -</literallayout></para> + gtk_container_add( GTK_CONTAINER(window), pixmapwid ); +</programlisting> <para>A disadvantage of using pixmaps is that the displayed object is always rectangular, regardless of the image. We would like to create desktops @@ -4519,12 +4529,12 @@ static char * WheelbarrowFull_xpm[] = { " .XoO ", " +@#$%o& ", " *=-;#::o+ ", -" >,<12#:34 ", +" >,<12#:34 ", " 45671#:X3 ", -" +89<02qwo ", +" +89<02qwo ", "e* >,67;ro ", "ty> 459@>+&& ", -"$2u+ ><ipas8* ", +"$2u+ ><ipas8* ", "%$;=* *3:.Xa.dfg> ", "Oh$;ya *3d.a8j,Xe.d3g8+ ", " Oh$;ka *3d$a8lz,,xxc:.e3g54 ", @@ -4534,27 +4544,27 @@ static char * WheelbarrowFull_xpm[] = { " Oh$@,Od.czlllllzlmmqV@V#V@fxxxxxxxf:%j5& ", " Oh$1hd5lllslllCCZrV#r#:#2AxxxxxxxxxcdwM* ", " OXq6c.%8vvvllZZiqqApA:mq:Xxcpcxxxxxfdc9* ", -" 2r<6gde3bllZZrVi7S@SV77A::qApxxxxxxfdcM ", +" 2r<6gde3bllZZrVi7S@SV77A::qApxxxxxxfdcM ", " :,q-6MN.dfmZZrrSS:#riirDSAX@Af5xxxxxfevo", " +A26jguXtAZZZC7iDiCCrVVii7Cmmmxxxxxx%3g", " *#16jszN..3DZZZZrCVSA2rZrV7Dmmwxxxx&en", " p2yFvzssXe:fCZZCiiD7iiZDiDSSZwwxx8e*>", -" OA1<jzxwwc:$d%NDZZZZCCCZCCZZCmxxfd.B ", +" OA1<jzxwwc:$d%NDZZZZCCCZCCZZCmxxfd.B ", " 3206Bwxxszx%et.eaAp77m77mmmf3&eeeg* ", " @26MvzxNzvlbwfpdettttttttttt.c,n& ", -" *;16=lsNwwNwgsvslbwwvccc3pcfu<o ", -" p;<69BvwwsszslllbBlllllllu<5+ ", +" *;16=lsNwwNwgsvslbwwvccc3pcfu<o ", +" p;<69BvwwsszslllbBlllllllu<5+ ", " OS0y6FBlvvvzvzss,u=Blllj=54 ", " c1-699Blvlllllu7k96MMMg4 ", -" *10y8n6FjvllllB<166668 ", -" S-kg+>666<M<996-y6n<8* ", +" *10y8n6FjvllllB<166668 ", +" S-kg+>666<M<996-y6n<8* ", " p71=4 m69996kD8Z-66698&& ", -" &i0ycm6n4 ogk17,0<6666g ", -" N-k-<> >=01-kuu666> ", +" &i0ycm6n4 ogk17,0<6666g ", +" N-k-<> >=01-kuu666> ", " ,6ky& &46-10ul,66, ", -" Ou0<> o66y<ulw<66& ", +" Ou0<> o66y<ulw<66& ", " *kk5 >66By7=xu664 ", -" <<M4 466lj<Mxu66o ", +" <<M4 466lj<Mxu66o ", " *>> +66uv,zN666* ", " 566,xxj669 ", " 4666FF666> ", @@ -4627,14 +4637,14 @@ press event signal to make it do something. The following few lines would make the picture sensitive to a mouse button being pressed which makes the application terminate.</para> -<para><literallayout> -<literal> gtk_widget_set_events( window, +<programlisting role="C"> + gtk_widget_set_events( window, gtk_widget_get_events( window ) | - GDK_BUTTON_PRESS_MASK );</para> + GDK_BUTTON_PRESS_MASK ); -<para> gtk_signal_connect( GTK_OBJECT(window), "button_press_event", - GTK_SIGNAL_FUNC(close_application), NULL );</literal> -</literallayout></para> + gtk_signal_connect( GTK_OBJECT(window), "button_press_event", + GTK_SIGNAL_FUNC(close_application), NULL ); +</programlisting> </sect1> @@ -4651,38 +4661,38 @@ pointer relative to the ruler.</para> <para>A ruler must first be created. Horizontal and vertical rulers are created using</para> -<para><literallayout> -<literal>GtkWidget *gtk_hruler_new( void ); /* horizontal ruler */</para> +<programlisting role="C"> +GtkWidget *gtk_hruler_new( void ); /* horizontal ruler */ -<para>GtkWidget *gtk_vruler_new( void ); /* vertical ruler */ +GtkWidget *gtk_vruler_new( void ); /* vertical ruler */ </programlisting> <para>Once a ruler is created, we can define the unit of measurement. Units of measure for rulers can be<literal>GTK_PIXELS</literal>, <literal>GTK_INCHES</literal> or <literal>GTK_CENTIMETERS</literal>. This is set using</para> -<para><literallayout> -<literal>void gtk_ruler_set_metric( GtkRuler *ruler, - GtkMetricType metric );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_ruler_set_metric( GtkRuler *ruler, + GtkMetricType metric ); +</programlisting> <para>The default measure is <literal>GTK_PIXELS</literal>.</para> -<para><literallayout> -<literal> gtk_ruler_set_metric( GTK_RULER(ruler), GTK_PIXELS );</literal> -</literallayout></para> +<programlisting role="C"> + gtk_ruler_set_metric( GTK_RULER(ruler), GTK_PIXELS ); +</programlisting> <para>Other important characteristics of a ruler are how to mark the units of scale and where the position indicator is initially placed. These are set for a ruler using</para> -<para><literallayout> -<literal>void gtk_ruler_set_range( GtkRuler *ruler, +<programlisting role="C"> +void gtk_ruler_set_range( GtkRuler *ruler, gfloat lower, gfloat upper, gfloat position, - gfloat max_size );</literal> -</literallayout></para> + gfloat max_size ); +</programlisting> <para>The lower and upper arguments define the extent of the ruler, and max_size is the largest possible number that will be displayed. @@ -4691,17 +4701,17 @@ the ruler.</para> <para>A vertical ruler can span an 800 pixel wide window thus</para> -<para><literallayout> -<literal> gtk_ruler_set_range( GTK_RULER(vruler), 0, 800, 0, 800);</literal> -</literallayout></para> +<programlisting role="C"> + gtk_ruler_set_range( GTK_RULER(vruler), 0, 800, 0, 800); +</programlisting> <para>The markings displayed on the ruler will be from 0 to 800, with a number for every 100 pixels. If instead we wanted the ruler to range from 7 to 16, we would code</para> -<para><literallayout> -<literal> gtk_ruler_set_range( GTK_RULER(vruler), 7, 16, 0, 20);</literal> -</literallayout></para> +<programlisting role="C"> + gtk_ruler_set_range( GTK_RULER(vruler), 7, 16, 0, 20); +</programlisting> <para>The indicator on the ruler is a small triangular mark that indicates the position of the pointer relative to the ruler. If the ruler is @@ -4709,13 +4719,13 @@ used to follow the mouse pointer, the motion_notify_event signal should be connected to the motion_notify_event method of the ruler. To follow all mouse movements within a window area, we would use</para> -<para><literallayout> -<literal>#define EVENT_METHOD(i, x) GTK_WIDGET_CLASS(GTK_OBJECT(i)->klass)->x</para> +<programlisting role="C"> +#define EVENT_METHOD(i, x) GTK_WIDGET_CLASS(GTK_OBJECT(i)->klass)->x -<para> gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event", + gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event", (GtkSignalFunc)EVENT_METHOD(ruler, motion_notify_event), - GTK_OBJECT(ruler) );</literal> -</literallayout></para> + GTK_OBJECT(ruler) ); +</programlisting> <para>The following example creates a drawing area with a horizontal ruler above it and a vertical ruler to the left of it. The size of the @@ -4827,32 +4837,32 @@ identifier order.</para> <para>A statusbar is created with a call to:</para> -<para><literallayout> -<literal>GtkWidget *gtk_statusbar_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_statusbar_new( void ); +</programlisting> <para>A new Context Identifier is requested using a call to the following function with a short textual description of the context:</para> -<para><literallayout> -<literal>guint gtk_statusbar_get_context_id( GtkStatusbar *statusbar, - const gchar *context_description );</literal> -</literallayout></para> +<programlisting role="C"> +guint gtk_statusbar_get_context_id( GtkStatusbar *statusbar, + const gchar *context_description ); +</programlisting> <para>There are three functions that can operate on statusbars:</para> -<para><literallayout> -<literal>guint gtk_statusbar_push( GtkStatusbar *statusbar, +<programlisting role="C"> +guint gtk_statusbar_push( GtkStatusbar *statusbar, guint context_id, - gchar *text );</para> + gchar *text ); -<para>void gtk_statusbar_pop( GtkStatusbar *statusbar) - guint context_id );</para> +void gtk_statusbar_pop( GtkStatusbar *statusbar) + guint context_id ); -<para>void gtk_statusbar_remove( GtkStatusbar *statusbar, +void gtk_statusbar_remove( GtkStatusbar *statusbar, guint context_id, - guint message_id ); </literal> -</literallayout></para> + guint message_id ); +</programlisting> <para>The first, gtk_statusbar_push, is used to add a new message to the statusbar. It returns a Message Identifier, which can be passed later @@ -4958,11 +4968,11 @@ to replace, prepend or append the current contents of the Entry widget.</para> <para>There are two functions for creating Entry widgets:</para> -<para><literallayout> -<literal>GtkWidget *gtk_entry_new( void );</para> +<programlisting role="C"> +GtkWidget *gtk_entry_new( void ); -<para>GtkWidget *gtk_entry_new_with_max_length( guint16 max );</literal> -</literallayout></para> +GtkWidget *gtk_entry_new_with_max_length( guint16 max ); +</programlisting> <para>The first just creates a new Entry widget, whilst the second creates a new Entry and sets a limit on the length of the text within the Entry.</para> @@ -4970,16 +4980,16 @@ new Entry and sets a limit on the length of the text within the Entry.</para> <para>There are several functions for altering the text which is currently within the Entry widget.</para> -<para><literallayout> -<literal>void gtk_entry_set_text( GtkEntry *entry, - const gchar *text );</para> +<programlisting role="C"> +void gtk_entry_set_text( GtkEntry *entry, + const gchar *text ); -<para>void gtk_entry_append_text( GtkEntry *entry, - const gchar *text );</para> +void gtk_entry_append_text( GtkEntry *entry, + const gchar *text ); -<para>void gtk_entry_prepend_text( GtkEntry *entry, - const gchar *text );</literal> -</literallayout></para> +void gtk_entry_prepend_text( GtkEntry *entry, + const gchar *text ); +</programlisting> <para>The function gtk_entry_set_text sets the contents of the Entry widget, replacing the current contents. The functions gtk_entry_append_text @@ -4988,17 +4998,17 @@ and prepended to.</para> <para>The next function allows the current insertion point to be set.</para> -<para><literallayout> -<literal>void gtk_entry_set_position( GtkEntry *entry, - gint position );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_entry_set_position( GtkEntry *entry, + gint position ); +</programlisting> <para>The contents of the Entry can be retrieved by using a call to the following function. This is useful in the callback functions described below.</para> -<para><literallayout> -<literal>gchar *gtk_entry_get_text( GtkEntry *entry );</literal> -</literallayout></para> +<programlisting role="C"> +gchar *gtk_entry_get_text( GtkEntry *entry ); +</programlisting> <para>The value returned by this function is used internally, and must not be freed using either free() or g_free()</para> @@ -5006,10 +5016,10 @@ be freed using either free() or g_free()</para> <para>If we don't want the contents of the Entry to be changed by someone typing into it, we can change its editable state.</para> -<para><literallayout> -<literal>void gtk_entry_set_editable( GtkEntry *entry, - gboolean editable );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_entry_set_editable( GtkEntry *entry, + gboolean editable ); +</programlisting> <para>The function above allows us to toggle the editable state of the Entry widget by passing in a TRUE or FALSE value for the <literal>editable</literal> @@ -5019,20 +5029,20 @@ argument.</para> visible, for example when a password is being entered, we can use the following function, which also takes a boolean flag.</para> -<para><literallayout> -<literal>void gtk_entry_set_visibility( GtkEntry *entry, - gboolean visible );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_entry_set_visibility( GtkEntry *entry, + gboolean visible ); +</programlisting> <para>A region of the text may be set as selected by using the following function. This would most often be used after setting some default text in an Entry, making it easy for the user to remove it.</para> -<para><literallayout> -<literal>void gtk_entry_select_region( GtkEntry *entry, +<programlisting role="C"> +void gtk_entry_select_region( GtkEntry *entry, gint start, - gint end );</literal> -</literallayout></para> + gint end ); +</programlisting> <para>If we want to catch when the user has entered text, we can connect to the <literal>activate</literal> or <literal>changed</literal> signal. Activate is raised when the @@ -5165,14 +5175,14 @@ button can take. This makes for a powerful Spin Button widget.</para> <para>Recall that an adjustment widget is created with the following function, which illustrates the information that it holds:</para> -<para><literallayout> -<literal>GtkObject *gtk_adjustment_new( gfloat value, +<programlisting role="C"> +GtkObject *gtk_adjustment_new( gfloat value, gfloat lower, gfloat upper, gfloat step_increment, gfloat page_increment, - gfloat page_size );</literal> -</literallayout></para> + gfloat page_size ); +</programlisting> <para>These attributes of an Adjustment are used by the Spin Button in the following way:</para> @@ -5198,11 +5208,11 @@ mouse button 2 on a button</simpara> <literal>upper</literal> or <literal>lower</literal> values when used to select one of the buttons. Lets look at how to create a Spin Button:</para> -<para><literallayout> -<literal>GtkWidget *gtk_spin_button_new( GtkAdjustment *adjustment, +<programlisting role="C"> +GtkWidget *gtk_spin_button_new( GtkAdjustment *adjustment, gfloat climb_rate, - guint digits );</literal> -</literallayout></para> + guint digits ); +</programlisting> <para>The <literal>climb_rate</literal> argument take a value between 0.0 and 1.0 and indicates the amount of acceleration that the Spin Button has. The @@ -5212,12 +5222,12 @@ the value will be displayed.</para> <para>A Spin Button can be reconfigured after creation using the following function:</para> -<para><literallayout> -<literal>void gtk_spin_button_configure( GtkSpinButton *spin_button, +<programlisting role="C"> +void gtk_spin_button_configure( GtkSpinButton *spin_button, GtkAdjustment *adjustment, gfloat climb_rate, - guint digits );</literal> -</literallayout></para> + guint digits ); +</programlisting> <para>The <literal>spin_button</literal> argument specifies the Spin Button widget that is to be reconfigured. The other arguments are as specified above.</para> @@ -5225,57 +5235,57 @@ to be reconfigured. The other arguments are as specified above.</para> <para>The adjustment can be set and retrieved independantly using the following two functions:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_adjustment( GtkSpinButton *spin_button, - GtkAdjustment *adjustment );</para> +<programlisting role="C"> +void gtk_spin_button_set_adjustment( GtkSpinButton *spin_button, + GtkAdjustment *adjustment ); -<para>GtkAdjustment *gtk_spin_button_get_adjustment( GtkSpinButton *spin_button );</literal> -</literallayout></para> +GtkAdjustment *gtk_spin_button_get_adjustment( GtkSpinButton *spin_button ); +</programlisting> <para>The number of decimal places can also be altered using:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_digits( GtkSpinButton *spin_button, - guint digits) ;</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_set_digits( GtkSpinButton *spin_button, + guint digits) ; +</programlisting> <para>The value that a Spin Button is currently displaying can be changed using the following function:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_value( GtkSpinButton *spin_button, - gfloat value );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_set_value( GtkSpinButton *spin_button, + gfloat value ); +</programlisting> <para>The current value of a Spin Button can be retrieved as either a floating point or integer value with the following functions:</para> -<para><literallayout> -<literal>gfloat gtk_spin_button_get_value_as_float( GtkSpinButton *spin_button );</para> +<programlisting role="C"> +gfloat gtk_spin_button_get_value_as_float( GtkSpinButton *spin_button ); -<para>gint gtk_spin_button_get_value_as_int( GtkSpinButton *spin_button );</literal> -</literallayout></para> +gint gtk_spin_button_get_value_as_int( GtkSpinButton *spin_button ); +</programlisting> <para>If you want to alter the value of a Spin Value relative to its current value, then the following function can be used:</para> -<para><literallayout> -<literal>void gtk_spin_button_spin( GtkSpinButton *spin_button, +<programlisting role="C"> +void gtk_spin_button_spin( GtkSpinButton *spin_button, GtkSpinType direction, - gfloat increment );</literal> -</literallayout></para> + gfloat increment ); +</programlisting> <para>The <literal>direction</literal> parameter can take one of the following values:</para> -<para><literallayout> -<literal> GTK_SPIN_STEP_FORWARD +<programlisting role="C"> + GTK_SPIN_STEP_FORWARD GTK_SPIN_STEP_BACKWARD GTK_SPIN_PAGE_FORWARD GTK_SPIN_PAGE_BACKWARD GTK_SPIN_HOME GTK_SPIN_END - GTK_SPIN_USER_DEFINED</literal> -</literallayout></para> + GTK_SPIN_USER_DEFINED +</programlisting> <para>This function packs in quite a bit of functionality, which I will attempt to clearly explain. Many of these settings use values from the @@ -5307,36 +5317,36 @@ Spin Button such that it may only contain a numeric value. This prevents a user from typing anything other than numeric values into the text box of a Spin Button:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_numeric( GtkSpinButton *spin_button, - gboolean numeric );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_set_numeric( GtkSpinButton *spin_button, + gboolean numeric ); +</programlisting> <para>You can set whether a Spin Button will wrap around between the upper and lower range values with the following function:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_wrap( GtkSpinButton *spin_button, - gboolean wrap );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_set_wrap( GtkSpinButton *spin_button, + gboolean wrap ); +</programlisting> <para>You can set a Spin Button to round the value to the nearest <literal>step_increment</literal>, which is set within the Adjustment object used with the Spin Button. This is accomplished with the following function:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_snap_to_ticks( GtkSpinButton *spin_button, - gboolean snap_to_ticks );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_set_snap_to_ticks( GtkSpinButton *spin_button, + gboolean snap_to_ticks ); +</programlisting> <para>The update policy of a Spin Button can be changed with the following function:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_update_policy( GtkSpinButton *spin_button, - GtkSpinButtonUpdatePolicy policy );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_set_update_policy( GtkSpinButton *spin_button, + GtkSpinButtonUpdatePolicy policy ); +</programlisting> <para><!-- TODO: find out what this does - TRG --></para> @@ -5358,25 +5368,25 @@ text into a numeric value.</para> <para>The appearance of the buttons used in a Spin Button can be changed using the following function:</para> -<para><literallayout> -<literal>void gtk_spin_button_set_shadow_type( GtkSpinButton *spin_button, - GtkShadowType shadow_type );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_set_shadow_type( GtkSpinButton *spin_button, + GtkShadowType shadow_type ); +</programlisting> <para>As usual, the <literal>shadow_type</literal> can be one of:</para> -<para><literallayout> -<literal> GTK_SHADOW_IN +<programlisting role="C"> + GTK_SHADOW_IN GTK_SHADOW_OUT GTK_SHADOW_ETCHED_IN - GTK_SHADOW_ETCHED_OUT</literal> -</literallayout></para> + GTK_SHADOW_ETCHED_OUT +</programlisting> <para>Finally, you can explicitly request that a Spin Button update itself:</para> -<para><literallayout> -<literal>void gtk_spin_button_update( GtkSpinButton *spin_button );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_spin_button_update( GtkSpinButton *spin_button ); +</programlisting> <para>It's example time again.</para> @@ -5625,39 +5635,39 @@ can type a different option directly into the text box.</para> <para>The following extract from the structure that defines a Combo Box identifies several of the components:</para> -<para><literallayout> -<literal>struct _GtkCombo { +<programlisting role="C"> +struct _GtkCombo { GtkHBox hbox; GtkWidget *entry; GtkWidget *button; GtkWidget *popup; GtkWidget *popwin; GtkWidget *list; - ... };</literal> -</literallayout></para> + ... }; +</programlisting> <para>As you can see, the Combo Box has two principal parts that you really care about: an entry and a list.</para> <para>First off, to create a combo box, use:</para> -<para><literallayout> -<literal>GtkWidget *gtk_combo_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_combo_new( void ); +</programlisting> <para>Now, if you want to set the string in the entry section of the combo box, this is done by manipulating the <literal>entry</literal> widget directly:</para> -<para><literallayout> -<literal> gtk_entry_set_text(GTK_ENTRY(GTK_COMBO(combo)->entry), "My String.");</literal> -</literallayout></para> +<programlisting role="C"> + gtk_entry_set_text(GTK_ENTRY(GTK_COMBO(combo)->entry), "My String."); +</programlisting> <para>To set the values in the popdown list, one uses the function:</para> -<para><literallayout> -<literal>void gtk_combo_set_popdown_strings( GtkCombo *combo, - GList *strings );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_combo_set_popdown_strings( GtkCombo *combo, + GList *strings ); +</programlisting> <para>Before you can do this, you have to assemble a GList of the strings that you want. GList is a linked list implementation that is part of @@ -5665,10 +5675,10 @@ that you want. GList is a linked list implementation that is part of moment, the quick and dirty explanation is that you need to set up a GList pointer, set it equal to NULL, then append strings to it with</para> -<para><literallayout> -<literal>GList *g_list_append( GList *glist, - gpointer data );</literal> -</literallayout></para> +<programlisting role="C"> +GList *g_list_append( GList *glist, + gpointer data ); +</programlisting> <para>It is important that you set the initial GList pointer to NULL. The value returned from the g_list_append function must be used as the new @@ -5676,16 +5686,16 @@ pointer to the GList.</para> <para>Here's a typical code segment for creating a set of options:</para> -<para><literallayout> -<literal> GList *glist=NULL;</para> +<programlisting role="C"> + GList *glist=NULL; -<para> glist = g_list_append(glist, "String 1"); + glist = g_list_append(glist, "String 1"); glist = g_list_append(glist, "String 2"); glist = g_list_append(glist, "String 3"); - glist = g_list_append(glist, "String 4");</para> + glist = g_list_append(glist, "String 4"); -<para> gtk_combo_set_popdown_strings( GTK_COMBO(combo), glist) ;</literal> -</literallayout></para> + gtk_combo_set_popdown_strings( GTK_COMBO(combo), glist) ; +</programlisting> <para>The combo widget makes a copy of the strings passed to it in the glist structure. As a result, you need to make sure you free the memory used @@ -5695,16 +5705,16 @@ by the list if that is appropriate for your application.</para> There are a few aspects of its behavior that you can change. These are accomplished with the functions: </para> -<para><literallayout> -<literal>void gtk_combo_set_use_arrows( GtkCombo *combo, - gint val );</para> +<programlisting role="C"> +void gtk_combo_set_use_arrows( GtkCombo *combo, + gint val ); -<para>void gtk_combo_set_use_arrows_always( GtkCombo *combo, - gint val );</para> +void gtk_combo_set_use_arrows_always( GtkCombo *combo, + gint val ); -<para>void gtk_combo_set_case_sensitive( GtkCombo *combo, - gint val );</literal> -</literallayout></para> +void gtk_combo_set_case_sensitive( GtkCombo *combo, + gint val ); +</programlisting> <para><literal>gtk_combo_set_use_arrows()</literal> lets the user change the value in the entry using the up/down arrow keys. This doesn't bring up the list, but @@ -5746,47 +5756,47 @@ attach to the activate signal, which indicates that the user has pressed the Return or Enter key, and read the text. The first is accomplished using something like:</para> -<para><literallayout> -<literal> gtk_signal_connect(GTK_OBJECT(GTK_COMB(combo)->entry), "activate", - GTK_SIGNAL_FUNC (my_callback_function), my_data);</literal> -</literallayout></para> +<programlisting role="C"> + gtk_signal_connect(GTK_OBJECT(GTK_COMB(combo)->entry), "activate", + GTK_SIGNAL_FUNC (my_callback_function), my_data); +</programlisting> <para>Getting the text at any arbitrary time is accomplished by simply using the entry function:</para> -<para><literallayout> -<literal>gchar *gtk_entry_get_text(GtkEntry *entry);</literal> -</literallayout></para> +<programlisting role="C"> +gchar *gtk_entry_get_text(GtkEntry *entry); +</programlisting> <para>Such as:</para> -<para><literallayout> -<literal> char *string;</para> +<programlisting role="C"> + char *string; -<para> string = gtk_entry_get_text(GTK_ENTRY(GTK_COMBO(combo)->entry));</literal> -</literallayout></para> + string = gtk_entry_get_text(GTK_ENTRY(GTK_COMBO(combo)->entry)); +</programlisting> <para>That's about all there is to it. There is a function</para> -<para><literallayout> -<literal>void gtk_combo_disable_activate(GtkCombo *combo);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_combo_disable_activate(GtkCombo *combo); +</programlisting> <para>that will disable the activate signal on the entry widget in the combo box. Personally, I can't think of why you'd want to use it, but it does exist.</para> -<para><!-- There is also a function to set the string on a particular item, void +<!-- There is also a function to set the string on a particular item, void gtk_combo_set_item_string(GtkCombo *combo, GtkItem *item, const gchar *item_value), but this requires that you have a pointer to the appropriate Item. Frankly, I have no idea how to do that. ---></para> +--> </sect1> <!-- ----------------------------------------------------------------- --> <sect1> -<title> Calendar</title> +<title>Calendar</title> <para>The Calendar widget is an effective way to display and retrieve monthly date related information. It is a very simple widget to create @@ -5794,20 +5804,20 @@ and work with.</para> <para>Creating a GtkCalendar widget is a simple as: </para> -<para><literallayout> -<literal>GtkWidget *gtk_calendar_new();</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_calendar_new(); +</programlisting> <para>There might be times where you need to change a lot of information within this widget and the following functions allow you to make multiple change to a Calendar widget without the user seeing multiple on-screen updates.</para> -<para><literallayout> -<literal>void gtk_calendar_freeze( GtkCalendar *Calendar );</para> +<programlisting role="C"> +void gtk_calendar_freeze( GtkCalendar *Calendar ); -<para>void gtk_calendar_thaw ( GtkCalendar *Calendar );</literal> -</literallayout></para> +void gtk_calendar_thaw ( GtkCalendar *Calendar ); +</programlisting> <para>They work just like the freeze/thaw functions of every other widget.</para> @@ -5815,10 +5825,10 @@ widget.</para> <para>The Calendar widget has a few options that allow you to change the way the widget both looks and operates by using the function</para> -<para><literallayout> -<literal>void gtk_calendar_display_options( GtkCalendar *calendar, - GtkCalendarDisplayOptions flags );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_calendar_display_options( GtkCalendar *calendar, + GtkCalendarDisplayOptions flags ); +</programlisting> <para>The <literal>flags</literal> argument can be formed by combining either of the following five options using the logical bitwise OR (|) operation:</para> @@ -5827,23 +5837,24 @@ following five options using the logical bitwise OR (|) operation:</para> <listitem><simpara> GTK_CALENDAR_SHOW_HEADING - this option specifies that the month and year should be shown when drawing the calendar.</simpara> </listitem> + <listitem><simpara> GTK_CALENDAR_SHOW_DAY_NAMES - this option specifies that the three letter descriptions should be displayed for each day (eg -Mon,Tue, etc.).</para> -</simpara> +Mon,Tue, etc.).</simpara> </listitem> + <listitem><simpara> GTK_CALENDAR_NO_MONTH_CHANGE - this option states that the user should not and can not change the currently displayed month. This can be good if you only need to display a particular month such as if you are displaying 12 calendar widgets for every month in a particular -year.</para> -</simpara> +year.</simpara> </listitem> + <listitem><simpara> GTK_CALENDAR_SHOW_WEEK_NUMBERS - this option specifies that the number for each week should be displayed down the left side of the -calendar. (eg. Jan 1 = Week 1,Dec 31 = Week 52).</para> -</simpara> +calendar. (eg. Jan 1 = Week 1,Dec 31 = Week 52).</simpara> </listitem> + <listitem><simpara> GTK_CALENDAR_WEEK_START_MONDAY - this option states that the calander week will start on Monday instead of Sunday which is the default. This only affects the order in which days are displayed from @@ -5853,14 +5864,15 @@ left to right.</simpara> <para>The following functions are used to set the the currently displayed date:</para> -<para><literallayout> -<literal>gint gtk_calendar_select_month( GtkCalendar *calendar, + +<programlisting role="C"> +gint gtk_calendar_select_month( GtkCalendar *calendar, guint month, - guint year );</para> + guint year ); -<para>void gtk_calendar_select_day( GtkCalendar *calendar, - guint day );</literal> -</literallayout></para> +void gtk_calendar_select_day( GtkCalendar *calendar, + guint day ); +</programlisting> <para>The return value from <literal>gtk_calendar_select_month()</literal> is a boolean value indicating whether the selection was successful.</para> @@ -5874,15 +5886,15 @@ may be "marked". A marked day is highlighted within the calendar display. The following functions are provided to manipulate marked days:</para> -<para><literallayout> -<literal>gint gtk_calendar_mark_day( GtkCalendar *calendar, - guint day);</para> +<programlisting role="C"> +gint gtk_calendar_mark_day( GtkCalendar *calendar, + guint day); -<para>gint gtk_calendar_unmark_day( GtkCalendar *calendar, - guint day);</para> +gint gtk_calendar_unmark_day( GtkCalendar *calendar, + guint day); -<para>void gtk_calendar_clear_marks( GtkCalendar *calendar);</literal> -</literallayout></para> +void gtk_calendar_clear_marks( GtkCalendar *calendar); +</programlisting> <para>The currently marked days are stored within an array within the GtkCalendar structure. This array is 31 elements long so to test @@ -5890,13 +5902,13 @@ whether a particular day is currently marked, you need to access the corresponding element of the array (don't forget in C that array elements are numbered 0 to n-1). For example:</para> -<para><literallayout> -<literal> GtkCalendar *calendar; - calendar = gtk_calendar_new();</para> +<programlisting role="C"> + GtkCalendar *calendar; + calendar = gtk_calendar_new(); -<para> ...</para> + ... -<para> /* Is day 7 marked? */ + /* Is day 7 marked? */ if (calendar->marked_date[7-1]) /* day is marked */ </programlisting> @@ -5906,12 +5918,12 @@ elements are numbered 0 to n-1). For example:</para> <para>The final Calendar widget function is used to retrieve the currently selected date, month and/or year.</para> -<para><literallayout> -<literal>void gtk_calendar_get_date( GtkCalendar *calendar, +<programlisting role="C"> +void gtk_calendar_get_date( GtkCalendar *calendar, guint *year, guint *month, - guint *day );</literal> -</literallayout></para> + guint *day ); +</programlisting> <para>This function requires you to pass the addresses of <literal>guint</literal> variables, into which the result will be placed. Passing <literal>NULL</literal> as @@ -5941,7 +5953,7 @@ and are:</para> <para>That just leaves us with the need to put all of this together into example code.</para> -<para><tscreen><verb> +<programlisting role="C"> /* example-start calendar calendar.c */ /* * Copyright (C) 1998 Cesar Miquel, Shawn T. Amundson, Mattias Grönlund @@ -6105,11 +6117,11 @@ void calendar_set_flags( CalendarData *calendar ) gint i; gint options=0; for (i=0;i<5;i++) - if (calendar->settings[i]) + if (calendar-<settings[i]) { - options=options + (1<<i); + options=options + (1<<i); } - if (calendar->window) + if (calendar-<window) gtk_calendar_display_options (GTK_CALENDAR (calendar->window), options); } @@ -6391,18 +6403,18 @@ explicitly through gtk_color_selection_set_color().</para> us. The widget comes in two flavours: gtk_color_selection and gtk_color_selection_dialog.</para> -<para><literallayout> -<literal>GtkWidget *gtk_color_selection_new( void ); -</verb></tscreen> +<programlisting role="C"> +GtkWidget *gtk_color_selection_new( void ); +</programlisting> -You'll probably not be using this constructor directly. It creates an +<para>You'll probably not be using this constructor directly. It creates an orphan ColorSelection widget which you'll have to parent yourself. The ColorSelection widget inherits from the VBox widget.</para> -<para><tscreen><verb> -GtkWidget *gtk_color_selection_dialog_new( const gchar *title );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_color_selection_dialog_new( const gchar *title ); +</programlisting> <para>This is the most common color selection constructor. It creates a ColorSelectionDialog. It consists of a Frame containing a @@ -6412,10 +6424,10 @@ the "ok_button", "cancel_button" and "help_button" widgets in the ColorSelectionDialog structure, (i.e., <literal>GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button</literal>)).</para> -<para><literallayout> -<literal>void gtk_color_selection_set_update_policy( GtkColorSelection *colorsel, - GtkUpdateType policy );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_color_selection_set_update_policy( GtkColorSelection *colorsel, + GtkUpdateType policy ); +</programlisting> <para>This function sets the update policy. The default policy is <literal>GTK_UPDATE_CONTINUOUS</literal> which means that the current color is @@ -6424,20 +6436,20 @@ mouse and drags in the hue-saturation wheel or value bar. If you experience performance problems, you may want to set the policy to <literal>GTK_UPDATE_DISCONTINUOUS</literal> or <literal>GTK_UPDATE_DELAYED</literal>.</para> -<para><literallayout> -<literal>void gtk_color_selection_set_opacity( GtkColorSelection *colorsel, - gint use_opacity );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_color_selection_set_opacity( GtkColorSelection *colorsel, + gint use_opacity ); +</programlisting> <para>The color selection widget supports adjusting the opacity of a color (also known as the alpha channel). This is disabled by default. Calling this function with use_opacity set to TRUE enables opacity. Likewise, use_opacity set to FALSE will disable opacity.</para> -<para><literallayout> -<literal>void gtk_color_selection_set_color( GtkColorSelection *colorsel, - gdouble *color );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_color_selection_set_color( GtkColorSelection *colorsel, + gdouble *color ); +</programlisting> <para>You can set the current color explicitly by calling this function with a pointer to an array of colors (gdouble). The length of the array @@ -6447,10 +6459,10 @@ red component, 1 is green, 2 is blue and opacity is at position 3 gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0.</para> -<para><literallayout> -<literal>void gtk_color_selection_get_color( GtkColorSelection *colorsel, - gdouble *color );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_color_selection_get_color( GtkColorSelection *colorsel, + gdouble *color ); +</programlisting> <para>When you need to query the current color, typically when you've received a "color_changed" signal, you use this function. Color is a @@ -6628,7 +6640,7 @@ gint main( gint argc, <!-- ----------------------------------------------------------------- --> <sect1> -<title> File Selections</title> +<title>File Selections</title> <para>The file selection widget is a quick and simple way to display a File dialog box. It comes complete with Ok, Cancel, and Help buttons, a @@ -6636,30 +6648,30 @@ great way to cut down on programming time.</para> <para>To create a new file selection box use:</para> -<para><literallayout> -<literal>GtkWidget *gtk_file_selection_new( gchar *title );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_file_selection_new( gchar *title ); +</programlisting> <para>To set the filename, for example to bring up a specific directory, or give a default filename, use this function:</para> -<para><literallayout> -<literal>void gtk_file_selection_set_filename( GtkFileSelection *filesel, - gchar *filename );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_file_selection_set_filename( GtkFileSelection *filesel, + gchar *filename ); +</programlisting> <para>To grab the text that the user has entered or clicked on, use this function:</para> -<para><literallayout> -<literal>gchar *gtk_file_selection_get_filename( GtkFileSelection *filesel );</literal> -</literallayout></para> +<programlisting role="C"> +gchar *gtk_file_selection_get_filename( GtkFileSelection *filesel ); +</programlisting> <para>There are also pointers to the widgets contained within the file selection widget. These are:</para> -<para><literallayout> -<literal> dir_list +<programlisting role="C"> + dir_list file_list selection_entry selection_text @@ -6667,9 +6679,9 @@ selection widget. These are:</para> ok_button cancel_button help_button -</verb></tscreen> +</programlisting> -Most likely you will want to use the ok_button, cancel_button, and +<para>Most likely you will want to use the ok_button, cancel_button, and help_button pointers in signaling their use.</para> <para>Included here is an example stolen from testgtk.c, modified to run on @@ -6737,9 +6749,10 @@ int main( int argc, <title>Container Widgets</title> <!-- ----------------------------------------------------------------- --> -<sect1>The EventBox -<p> -Some GTK widgets don't have associated X windows, so they just draw on +<sect1> +<title>The EventBox</title> + +<para>Some GTK widgets don't have associated X windows, so they just draw on their parents. Because of this, they cannot receive events and if they are incorrectly sized, they don't clip so you can get messy overwriting, etc. If you require more from these widgets, the EventBox @@ -6758,15 +6771,15 @@ event-handling function, the widget can also be used for clipping. <para>To create a new EventBox widget, use:</para> -<para><literallayout> -<literal>GtkWidget *gtk_event_box_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_event_box_new( void ); +</programlisting> <para>A child widget can then be added to this EventBox:</para> -<para><literallayout> -<literal> gtk_container_add( GTK_CONTAINER(event_box), child_widget );</literal> -</literallayout></para> +<programlisting role="C"> + gtk_container_add( GTK_CONTAINER(event_box), child_widget ); +</programlisting> <para>The following example demonstrates both uses of an EventBox - a label is created that is clipped to a small box, and set up so that a @@ -6842,8 +6855,8 @@ within the window.</para> <para>There are only two functions associated with the Alignment widget:</para> -<para><literallayout> -<literal>GtkWidget* gtk_alignment_new( gfloat xalign, +<programlisting role="C"> +GtkWidget* gtk_alignment_new( gfloat xalign, gfloat yalign, gfloat xscale, gfloat yscale );</para> @@ -6852,8 +6865,8 @@ within the window.</para> gfloat xalign, gfloat yalign, gfloat xscale, - gfloat yscale );</literal> -</literallayout></para> + gfloat yscale ); +</programlisting> <para>The first function creates a new Alignment widget with the specified parameters. The second function allows the alignment paramters of an @@ -6867,9 +6880,9 @@ space allocated to the widget.</para> <para>A child widget can be added to this Alignment widget using:</para> -<para><literallayout> -<literal> gtk_container_add( GTK_CONTAINER(alignment), child_widget );</literal> -</literallayout></para> +<programlisting role="C"> + gtk_container_add( GTK_CONTAINER(alignment), child_widget ); +</programlisting> <para>For an example of using an Alignment widget, refer to the example for the <link linkend="ch-ProgressBar">Progress Bar</link> widget.</para> @@ -6886,8 +6899,8 @@ position of the widgets can be changed dynamically.</para> <para>There are only three functions associated with the fixed widget:</para> -<para><literallayout> -<literal>GtkWidget* gtk_fixed_new( void );</para> +<programlisting role="C"> +GtkWidget* gtk_fixed_new( void );</para> <para>void gtk_fixed_put( GtkFixed *fixed, GtkWidget *widget, @@ -6897,8 +6910,8 @@ position of the widgets can be changed dynamically.</para> <para>void gtk_fixed_move( GtkFixed *fixed, GtkWidget *widget, gint16 x, - gint16 y );</literal> -</literallayout></para> + gint16 y ); +</programlisting> <para>The function <literal>gtk_fixed_new</literal> allows you to create a new Fixed container.</para> @@ -7004,10 +7017,10 @@ widgets in your scrolling area.</para> <para>A Layout container is created using:</para> -<para><literallayout> -<literal>GtkWidget *gtk_layout_new( GtkAdjustment *hadjustment, - GtkAdjustment *vadjustment );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_layout_new( GtkAdjustment *hadjustment, + GtkAdjustment *vadjustment ); +</programlisting> <para>As you can see, you can optionally specify the Adjustment objects that the Layout widget will use for its scrolling.</para> @@ -7015,8 +7028,8 @@ the Layout widget will use for its scrolling.</para> <para>You can add and move widgets in the Layout container using the following two functions:</para> -<para><literallayout> -<literal>void gtk_layout_put( GtkLayout *layout, +<programlisting role="C"> +void gtk_layout_put( GtkLayout *layout, GtkWidget *widget, gint x, gint y );</para> @@ -7024,16 +7037,16 @@ following two functions:</para> <para>void gtk_layout_move( GtkLayout *layout, GtkWidget *widget, gint x, - gint y );</literal> -</literallayout></para> + gint y ); +</programlisting> <para>The size of the Layout container can be set using the next function:</para> -<para><literallayout> -<literal>void gtk_layout_set_size( GtkLayout *layout, +<programlisting role="C"> +void gtk_layout_set_size( GtkLayout *layout, guint width, - guint height );</literal> -</literallayout></para> + guint height ); +</programlisting> <para>Layout containers are one of the very few widgets in the GTK widget set that actively repaint themselves on screen as they are changed @@ -7045,17 +7058,17 @@ requests which are then processed when control returns to the you can use the following two functions to disable and re-enable this repainting functionality:</para> -<para><literallayout> -<literal>void gtk_layout_freeze( GtkLayout *layout );</para> +<programlisting role="C"> +void gtk_layout_freeze( GtkLayout *layout );</para> -<para>void gtk_layout_thaw( GtkLayout *layout );</literal> -</literallayout></para> +<para>void gtk_layout_thaw( GtkLayout *layout ); +</programlisting> <para>The final four functions for use with Layout widgets are for manipulating the horizontal and vertical adjustment widgets:</para> -<para><literallayout> -<literal>GtkAdjustment* gtk_layout_get_hadjustment( GtkLayout *layout );</para> +<programlisting role="C"> +GtkAdjustment* gtk_layout_get_hadjustment( GtkLayout *layout );</para> <para>GtkAdjustment* gtk_layout_get_vadjustment( GtkLayout *layout );</para> @@ -7063,8 +7076,8 @@ manipulating the horizontal and vertical adjustment widgets:</para> GtkAdjustment *adjustment );</para> <para>void gtk_layout_set_vadjustment( GtkLayout *layout, - GtkAdjustment *adjustment);</literal> -</literallayout></para> + GtkAdjustment *adjustment); +</programlisting> </sect1> @@ -7077,27 +7090,27 @@ style of the box can be altered to suit.</para> <para>A Frame can be created with the following function:</para> -<para><literallayout> -<literal>GtkWidget *gtk_frame_new( const gchar *label );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_frame_new( const gchar *label ); +</programlisting> <para>The label is by default placed in the upper left hand corner of the frame. A value of NULL for the <literal>label</literal> argument will result in no label being displayed. The text of the label can be changed using the next function.</para> -<para><literallayout> -<literal>void gtk_frame_set_label( GtkFrame *frame, - const gchar *label );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_frame_set_label( GtkFrame *frame, + const gchar *label ); +</programlisting> <para>The position of the label can be changed using this function:</para> -<para><literallayout> -<literal>void gtk_frame_set_label_align( GtkFrame *frame, +<programlisting role="C"> +void gtk_frame_set_label_align( GtkFrame *frame, gfloat xalign, - gfloat yalign );</literal> -</literallayout></para> + gfloat yalign ); +</programlisting> <para><literal>xalign</literal> and <literal>yalign</literal> take values between 0.0 and 1.0. <literal>xalign</literal> indicates the position of the label along the top horizontal of the @@ -7107,19 +7120,19 @@ is 0.0 which places the label at the left hand end of the frame.</para> <para>The next function alters the style of the box that is used to outline the frame.</para> -<para><literallayout> -<literal>void gtk_frame_set_shadow_type( GtkFrame *frame, - GtkShadowType type);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_frame_set_shadow_type( GtkFrame *frame, + GtkShadowType type); +</programlisting> <para>The <literal>type</literal> argument can take one of the following values:</para> -<para><literallayout> -<literal> GTK_SHADOW_NONE +<programlisting role="C"> + GTK_SHADOW_NONE GTK_SHADOW_IN GTK_SHADOW_OUT GTK_SHADOW_ETCHED_IN (the default) - GTK_SHADOW_ETCHED_OUT</literal> -</literallayout></para> + GTK_SHADOW_ETCHED_OUT +</programlisting> <para>The following code example illustrates the use of the Frame widget.</para> @@ -7195,8 +7208,8 @@ the original image. To create a new aspect frame use: </para> -<para><literallayout> -<literal>GtkWidget *gtk_aspect_frame_new( const gchar *label, +<programlisting role="C"> +GtkWidget *gtk_aspect_frame_new( const gchar *label, gfloat xalign, gfloat yalign, gfloat ratio, @@ -7210,8 +7223,8 @@ Otherwise, it is given by <literal>ratio</literal>. To change the options of an existing aspect frame, you can use: </para> -<para><literallayout> -<literal>void gtk_aspect_frame_set( GtkAspectFrame *aspect_frame, +<programlisting role="C"> +void gtk_aspect_frame_set( GtkAspectFrame *aspect_frame, gfloat xalign, gfloat yalign, gfloat ratio, @@ -7222,8 +7235,8 @@ As an example, the following program uses an AspectFrame to present a drawing area whose aspect ratio will always be 2:1, no matter how the user resizes the top-level window. </para> -<para><literallayout> -<literal>/* example-start aspectframe aspectframe.c */ +<programlisting role="C"> +/* example-start aspectframe aspectframe.c */ #include <gtk/gtk.h> @@ -7283,17 +7296,17 @@ horizontal (HPaned) or vertical (VPaned). To create a new paned window, call one of: </para> -<para><literallayout> -<literal>GtkWidget *gtk_hpaned_new (void);</para> +<programlisting role="C"> +GtkWidget *gtk_hpaned_new (void);</para> -<para>GtkWidget *gtk_vpaned_new (void);</literal> -</literallayout></para> +<para>GtkWidget *gtk_vpaned_new (void); +</programlisting> <para>After creating the paned window widget, you need to add child widgets to its two halves. To do this, use the functions: </para> -<para><literallayout> -<literal>void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child);</para> +<programlisting role="C"> +void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child);</para> <para>void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child); </verb></tscreen> @@ -7305,13 +7318,13 @@ right or bottom half of the paned window.</para> <para>A paned widget can be changed visually using the following two functions.</para> -<para><literallayout> -<literal>void gtk_paned_set_handle_size( GtkPaned *paned, +<programlisting role="C"> +void gtk_paned_set_handle_size( GtkPaned *paned, guint16 size);</para> <para>void gtk_paned_set_gutter_size( GtkPaned *paned, - guint16 size);</literal> -</literallayout></para> + guint16 size); +</programlisting> <para>The first of these sets the size of the handle and the second sets the size of the gutter that is between the two parts of the paned window.</para> @@ -7492,10 +7505,10 @@ is currently in view.</para> <para>A Viewport is created with the function</para> -<para><literallayout> -<literal>GtkWidget *gtk_viewport_new( GtkAdjustment *hadjustment, - GtkAdjustment *vadjustment );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_viewport_new( GtkAdjustment *hadjustment, + GtkAdjustment *vadjustment ); +</programlisting> <para>As you can see you can specify the horizontal and vertical Adjustments that the widget is to use when you create the widget. It will create @@ -7504,8 +7517,8 @@ its own if you pass NULL as the value of the arguments.</para> <para>You can get and set the adjustments after the widget has been created using the following four functions:</para> -<para><literallayout> -<literal>GtkAdjustment *gtk_viewport_get_hadjustment (GtkViewport *viewport );</para> +<programlisting role="C"> +GtkAdjustment *gtk_viewport_get_hadjustment (GtkViewport *viewport );</para> <para>GtkAdjustment *gtk_viewport_get_vadjustment (GtkViewport *viewport );</para> @@ -7513,19 +7526,19 @@ using the following four functions:</para> GtkAdjustment *adjustment );</para> <para>void gtk_viewport_set_vadjustment( GtkViewport *viewport, - GtkAdjustment *adjustment );</literal> -</literallayout></para> + GtkAdjustment *adjustment ); +</programlisting> <para>The only other viewport function is used to alter its appearance:</para> -<para><literallayout> -<literal>void gtk_viewport_set_shadow_type( GtkViewport *viewport, - GtkShadowType type );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_viewport_set_shadow_type( GtkViewport *viewport, + GtkShadowType type ); +</programlisting> <para>Possible values for the <literal>type</literal> parameter are:</para> -<para><literallayout> -<literal> GTK_SHADOW_NONE, +<programlisting role="C"> + GTK_SHADOW_NONE, GTK_SHADOW_IN, GTK_SHADOW_OUT, GTK_SHADOW_ETCHED_IN, @@ -7544,20 +7557,20 @@ scrollbars.</para> <para>The following function is used to create a new scrolled window.</para> -<para><literallayout> -<literal>GtkWidget *gtk_scrolled_window_new( GtkAdjustment *hadjustment, - GtkAdjustment *vadjustment );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_scrolled_window_new( GtkAdjustment *hadjustment, + GtkAdjustment *vadjustment ); +</programlisting> <para>Where the first argument is the adjustment for the horizontal direction, and the second, the adjustment for the vertical direction. These are almost always set to NULL.</para> -<para><literallayout> -<literal>void gtk_scrolled_window_set_policy( GtkScrolledWindow *scrolled_window, +<programlisting role="C"> +void gtk_scrolled_window_set_policy( GtkScrolledWindow *scrolled_window, GtkPolicyType hscrollbar_policy, - GtkPolicyType vscrollbar_policy );</literal> -</literallayout></para> + GtkPolicyType vscrollbar_policy ); +</programlisting> <para>This sets the policy to be used with respect to the scrollbars. The first argument is the scrolled window you wish to change. The second @@ -7572,10 +7585,10 @@ will always leave the scrollbars there.</para> <para>You can then place your object into the scrolled window using the following function.</para> -<para><literallayout> -<literal>void gtk_scrolled_window_add_with_viewport( GtkScrolledWindow *scrolled_window, - GtkWidget *child);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_scrolled_window_add_with_viewport( GtkScrolledWindow *scrolled_window, + GtkWidget *child); +</programlisting> <para>Here is a simple example that packs a table eith 100 toggle buttons into a scrolled window. I've only commented on the parts that may be @@ -7694,61 +7707,61 @@ buttons. They come in both horizontal and vertical flavours. You create a new Button Box with one of the following calls, which create a horizontal or vertical box, respectively:</para> -<para><literallayout> -<literal>GtkWidget *gtk_hbutton_box_new( void );</para> +<programlisting role="C"> +GtkWidget *gtk_hbutton_box_new( void );</para> -<para>GtkWidget *gtk_vbutton_box_new( void );</literal> -</literallayout></para> +<para>GtkWidget *gtk_vbutton_box_new( void ); +</programlisting> <para>The only attributes pertaining to button boxes effect how the buttons are laid out. You can change the spacing between the buttons with:</para> -<para><literallayout> -<literal>void gtk_hbutton_box_set_spacing_default( gint spacing );</para> +<programlisting role="C"> +void gtk_hbutton_box_set_spacing_default( gint spacing );</para> -<para>void gtk_vbutton_box_set_spacing_default( gint spacing );</literal> -</literallayout></para> +<para>void gtk_vbutton_box_set_spacing_default( gint spacing ); +</programlisting> <para>Similarly, the current spacing values can be queried using:</para> -<para><literallayout> -<literal>gint gtk_hbutton_box_get_spacing_default( void );</para> +<programlisting role="C"> +gint gtk_hbutton_box_get_spacing_default( void );</para> -<para>gint gtk_vbutton_box_get_spacing_default( void );</literal> -</literallayout></para> +<para>gint gtk_vbutton_box_get_spacing_default( void ); +</programlisting> <para>The second attribute that we can access effects the layout of the buttons within the box. It is set using one of:</para> -<para><literallayout> -<literal>void gtk_hbutton_box_set_layout_default( GtkButtonBoxStyle layout );</para> +<programlisting role="C"> +void gtk_hbutton_box_set_layout_default( GtkButtonBoxStyle layout );</para> -<para>void gtk_vbutton_box_set_layout_default( GtkButtonBoxStyle layout );</literal> -</literallayout></para> +<para>void gtk_vbutton_box_set_layout_default( GtkButtonBoxStyle layout ); +</programlisting> <para>The <literal>layout</literal> argument can take one of the following values:</para> -<para><literallayout> -<literal> GTK_BUTTONBOX_DEFAULT_STYLE +<programlisting role="C"> + GTK_BUTTONBOX_DEFAULT_STYLE GTK_BUTTONBOX_SPREAD GTK_BUTTONBOX_EDGE GTK_BUTTONBOX_START - GTK_BUTTONBOX_END</literal> -</literallayout></para> + GTK_BUTTONBOX_END +</programlisting> <para>The current layout setting can be retrieved using:</para> -<para><literallayout> -<literal>GtkButtonBoxStyle gtk_hbutton_box_get_layout_default( void );</para> +<programlisting role="C"> +GtkButtonBoxStyle gtk_hbutton_box_get_layout_default( void );</para> -<para>GtkButtonBoxStyle gtk_vbutton_box_get_layout_default( void );</literal> -</literallayout></para> +<para>GtkButtonBoxStyle gtk_vbutton_box_get_layout_default( void ); +</programlisting> <para>Buttons are added to a Button Box using the usual function:</para> -<para><literallayout> -<literal> gtk_container_add( GTK_CONTAINER(button_box), child_widget );</literal> -</literallayout></para> +<programlisting role="C"> + gtk_container_add( GTK_CONTAINER(button_box), child_widget ); +</programlisting> <para>Here's an example that illustrates all the different layout settings for Button Boxes.</para> @@ -7894,25 +7907,25 @@ icons, labels, or both.</para> <para>Creating a toolbar is (as one may already suspect) done with the following function:</para> -<para><literallayout> -<literal>GtkWidget *gtk_toolbar_new( GtkOrientation orientation, - GtkToolbarStyle style );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_toolbar_new( GtkOrientation orientation, + GtkToolbarStyle style ); +</programlisting> <para>where orientation may be one of:</para> -<para><literallayout> -<literal> GTK_ORIENTATION_HORIZONTAL - GTK_ORIENTATION_VERTICAL</literal> -</literallayout></para> +<programlisting role="C"> + GTK_ORIENTATION_HORIZONTAL + GTK_ORIENTATION_VERTICAL +</programlisting> <para>and style one of:</para> -<para><literallayout> -<literal> GTK_TOOLBAR_TEXT +<programlisting role="C"> + GTK_TOOLBAR_TEXT GTK_TOOLBAR_ICONS - GTK_TOOLBAR_BOTH</literal> -</literallayout></para> + GTK_TOOLBAR_BOTH +</programlisting> <para>The style applies to all the buttons created with the `item' functions (not to buttons inserted into toolbar as separate widgets).</para> @@ -7924,8 +7937,8 @@ tooltip text, a private tooltip text, an icon for the button and a callback function for it. For example, to append or prepend an item you may use the following functions:</para> -<para><literallayout> -<literal>GtkWidget *gtk_toolbar_append_item( GtkToolbar *toolbar, +<programlisting role="C"> +GtkWidget *gtk_toolbar_append_item( GtkToolbar *toolbar, const char *text, const char *tooltip_text, const char *tooltip_private_text, @@ -7939,58 +7952,58 @@ you may use the following functions:</para> const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc callback, - gpointer user_data );</literal> -</literallayout></para> + gpointer user_data ); +</programlisting> <para>If you want to use gtk_toolbar_insert_item, the only additional parameter which must be specified is the position in which the item should be inserted, thus:</para> -<para><literallayout> -<literal>GtkWidget *gtk_toolbar_insert_item( GtkToolbar *toolbar, +<programlisting role="C"> +GtkWidget *gtk_toolbar_insert_item( GtkToolbar *toolbar, const char *text, const char *tooltip_text, const char *tooltip_private_text, GtkWidget *icon, GtkSignalFunc callback, gpointer user_data, - gint position );</literal> -</literallayout></para> + gint position ); +</programlisting> <para>To simplify adding spaces between toolbar items, you may use the following functions:</para> -<para><literallayout> -<literal>void gtk_toolbar_append_space( GtkToolbar *toolbar );</para> +<programlisting role="C"> +void gtk_toolbar_append_space( GtkToolbar *toolbar );</para> <para>void gtk_toolbar_prepend_space( GtkToolbar *toolbar );</para> <para>void gtk_toolbar_insert_space( GtkToolbar *toolbar, gint position ); - </literal> -</literallayout></para> + +</programlisting> <para>While the size of the added space can be set globally for a whole toolbar with the function:</para> -<para><literallayout> -<literal>void gtk_toolbar_set_space_size( GtkToolbar *toolbar, - gint space_size) ;</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_toolbar_set_space_size( GtkToolbar *toolbar, + gint space_size) ; +</programlisting> <para>If it's required, the orientation of a toolbar and its style can be changed "on the fly" using the following functions:</para> -<para><literallayout> -<literal>void gtk_toolbar_set_orientation( GtkToolbar *toolbar, +<programlisting role="C"> +void gtk_toolbar_set_orientation( GtkToolbar *toolbar, GtkOrientation orientation );</para> <para>void gtk_toolbar_set_style( GtkToolbar *toolbar, GtkToolbarStyle style );</para> <para>void gtk_toolbar_set_tooltips( GtkToolbar *toolbar, - gint enable );</literal> -</literallayout></para> + gint enable ); +</programlisting> <para>Where <literal>orientation</literal> is one of <literal>GTK_ORIENTATION_HORIZONTAL</literal> or <literal>GTK_ORIENTATION_VERTICAL</literal>. The <literal>style</literal> is used to set @@ -8002,8 +8015,8 @@ appearance of the toolbar items by using one of the following program (we'll interrupt the listing with some additional explanations):</para> -<para><literallayout> -<literal>#include <gtk/gtk.h></para> +<programlisting role="C"> +#include <gtk/gtk.h></para> <para>#include "gtk.xpm"</para> @@ -8013,15 +8026,15 @@ gint delete_event (GtkWidget *widget, GdkEvent *event, gpointer data) { gtk_main_quit (); return(FALSE); -}</literal> -</literallayout></para> +} +</programlisting> <para>The above beginning seems for sure familiar to you if it's not your first GTK program. There is one additional thing though, we include a nice XPM picture to serve as an icon for all of the buttons.</para> -<para><literallayout> -<literal>GtkWidget* close_button; /* This button will emit signal to close +<programlisting role="C"> +GtkWidget* close_button; /* This button will emit signal to close * application */ GtkWidget* tooltips_button; /* to enable/disable tooltips */ GtkWidget* text_button, @@ -8055,16 +8068,16 @@ void toggle_event (GtkWidget *widget, gpointer data) { gtk_toolbar_set_tooltips (GTK_TOOLBAR ( data ), GTK_TOGGLE_BUTTON (widget)->active ); -}</literal> -</literallayout></para> +} +</programlisting> <para>The above are just two callback functions that will be called when one of the buttons on a toolbar is pressed. You should already be familiar with things like this if you've already used toggle buttons (and radio buttons).</para> -<para><literallayout> -<literal>int main (int argc, char *argv[]) +<programlisting role="C"> +int main (int argc, char *argv[]) { /* Here is our main window (a dialog) and a handle for the handlebox */ GtkWidget* dialog; @@ -8099,8 +8112,8 @@ radio buttons).</para> * so that it can be detached from the main window */ handlebox = gtk_handle_box_new (); gtk_box_pack_start ( GTK_BOX ( GTK_DIALOG(dialog)->vbox ), - handlebox, FALSE, FALSE, 5 );</literal> -</literallayout></para> + handlebox, FALSE, FALSE, 5 ); +</programlisting> <para>The above should be similar to any other GTK application. Just initialization of GTK, creating the window, etc. There is only one @@ -8113,8 +8126,8 @@ contents are reparented to a new freely floating window). It is usually nice to have a detachable toolbar, so these two widgets occur together quite often.</para> -<para><literallayout> -<literal> /* toolbar will be horizontal, with both icons and text, and +<programlisting role="C"> + /* toolbar will be horizontal, with both icons and text, and * with 5pxl spaces between items and finally, * we'll also put it into our handlebox */ toolbar = gtk_toolbar_new ( GTK_ORIENTATION_HORIZONTAL, @@ -8126,8 +8139,8 @@ together quite often.</para> <para> /* now we create icon with mask: we'll reuse it to create * icon widgets for toolbar items */ icon = gdk_pixmap_create_from_xpm_d ( dialog->window, &mask, - &dialog->style->white, gtk_xpm );</literal> -</literallayout></para> + &dialog->style->white, gtk_xpm ); +</programlisting> <para>Well, what we do above is just a straightforward initialization of the toolbar widget and creation of a GDK pixmap with its mask. If you @@ -8135,8 +8148,8 @@ want to know something more about using pixmaps, refer to GDK documentation or to the <link linkend="ch-Pixmaps">Pixmaps</link> section earlier in this tutorial.</para> -<para><literallayout> -<literal> /* our first item is <close> button */ +<programlisting role="C"> + /* our first item is <close> button */ iconw = gtk_pixmap_new ( icon, mask ); /* icon widget */ close_button = gtk_toolbar_append_item ( GTK_TOOLBAR (toolbar), /* our toolbar */ @@ -8157,8 +8170,8 @@ space, so the following items will not touch each other. As you see gtk_toolbar_append_item returns a pointer to our newly created button widget, so that we can work with it in the normal way.</para> -<para><literallayout> -<literal> /* now, let's make our radio buttons group... */ +<programlisting role="C"> + /* now, let's make our radio buttons group... */ iconw = gtk_pixmap_new ( icon, mask ); icon_button = gtk_toolbar_append_element( GTK_TOOLBAR(toolbar), @@ -8170,8 +8183,8 @@ widget, so that we can work with it in the normal way.</para> iconw, /* icon */ GTK_SIGNAL_FUNC (radio_event), /* signal */ toolbar); /* data for signal */ - gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) );</literal> -</literallayout></para> + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); +</programlisting> <para>Here we begin creating a radio buttons group. To do this we use gtk_toolbar_append_element. In fact, using this function one can also @@ -8183,8 +8196,8 @@ list of buttons can be easily constructed (see the section on <ref id="ch-Radio_Buttons"> Radio Buttons </ulink> earlier in this tutorial).</para> -<para><literallayout> -<literal> /* following radio buttons refer to previous ones */ +<programlisting role="C"> + /* following radio buttons refer to previous ones */ iconw = gtk_pixmap_new ( icon, mask ); text_button = gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), @@ -8210,15 +8223,15 @@ tutorial).</para> GTK_SIGNAL_FUNC (radio_event), toolbar); gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); - gtk_toggle_button_set_active(GTK_TOGGLE_BUTTON(both_button),TRUE);</literal> -</literallayout></para> + gtk_toggle_button_set_active(GTK_TOGGLE_BUTTON(both_button),TRUE); +</programlisting> <para>In the end we have to set the state of one of the buttons manually (otherwise they all stay in active state, preventing us from switching between them).</para> -<para><literallayout> -<literal> /* here we have just a simple toggle button */ +<programlisting role="C"> + /* here we have just a simple toggle button */ iconw = gtk_pixmap_new ( icon, mask ); tooltips_button = gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), @@ -8231,14 +8244,14 @@ between them).</para> GTK_SIGNAL_FUNC (toggle_event), toolbar); gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); - gtk_toggle_button_set_active(GTK_TOGGLE_BUTTON(tooltips_button),TRUE);</literal> -</literallayout></para> + gtk_toggle_button_set_active(GTK_TOGGLE_BUTTON(tooltips_button),TRUE); +</programlisting> <para>A toggle button can be created in the obvious way (if one knows how to create radio buttons already).</para> -<para><literallayout> -<literal> /* to pack a widget into toolbar, we only have to +<programlisting role="C"> + /* to pack a widget into toolbar, we only have to * create it and append it with an appropriate tooltip */ entry = gtk_entry_new (); gtk_toolbar_append_widget( GTK_TOOLBAR (toolbar), @@ -8247,15 +8260,15 @@ radio buttons already).</para> "Private" );</para> <para> /* well, it isn't created within thetoolbar, so we must still show it */ - gtk_widget_show ( entry );</literal> -</literallayout></para> + gtk_widget_show ( entry ); +</programlisting> <para>As you see, adding any kind of widget to a toolbar is simple. The one thing you have to remember is that this widget must be shown manually (contrary to other items which will be shown together with the toolbar).</para> -<para><literallayout> -<literal> /* that's it ! let's show everything. */ +<programlisting role="C"> + /* that's it ! let's show everything. */ gtk_widget_show ( toolbar ); gtk_widget_show (handlebox); gtk_widget_show ( dialog );</para> @@ -8264,8 +8277,8 @@ one thing you have to remember is that this widget must be shown manually gtk_main (); return 0; -}</literal> -</literallayout></para> +} +</programlisting> <para>So, here we are at the end of toolbar tutorial. Of course, to appreciate it in full you need also this nice XPM icon, so here it is:</para> @@ -8317,8 +8330,8 @@ static char * gtk_xpm[] = { ".........++###+$$$@++...........", "..........++##+$@+++............", "...........+++++++..............", -".............++++..............."};</literal> -</literallayout></para> +".............++++..............."}; +</programlisting> </sect1> @@ -8335,9 +8348,9 @@ information that warrant separation in their display.</para> <para>The first function call you will need to know, as you can probably guess by now, is used to create a new notebook widget.</para> -<para><literallayout> -<literal>GtkWidget *gtk_notebook_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_notebook_new( void ); +</programlisting> <para>Once the notebook has been created, there are a number of functions that operate on the notebook widget. Let's look at them individually.</para> @@ -8346,19 +8359,19 @@ that operate on the notebook widget. Let's look at them individually.</para> These page indicators or "tabs" as they are referred to, can be positioned in four ways: top, bottom, left, or right.</para> -<para><literallayout> -<literal>void gtk_notebook_set_tab_pos( GtkNotebook *notebook, - GtkPositionType pos );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_notebook_set_tab_pos( GtkNotebook *notebook, + GtkPositionType pos ); +</programlisting> <para>GtkPositionType will be one of the following, which are pretty self explanatory:</para> -<para><literallayout> -<literal> GTK_POS_LEFT +<programlisting role="C"> + GTK_POS_LEFT GTK_POS_RIGHT GTK_POS_TOP - GTK_POS_BOTTOM</literal> -</literallayout></para> + GTK_POS_BOTTOM +</programlisting> <para><literal>GTK_POS_TOP</literal> is the default.</para> @@ -8366,15 +8379,15 @@ explanatory:</para> ways to add pages to the NoteBook. Let's look at the first two together as they are quite similar.</para> -<para><literallayout> -<literal>void gtk_notebook_append_page( GtkNotebook *notebook, +<programlisting role="C"> +void gtk_notebook_append_page( GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label );</para> <para>void gtk_notebook_prepend_page( GtkNotebook *notebook, GtkWidget *child, - GtkWidget *tab_label );</literal> -</literallayout></para> + GtkWidget *tab_label ); +</programlisting> <para>These functions add pages to the notebook by inserting them from the back of the notebook (append), or the front of the notebook (prepend). @@ -8387,12 +8400,12 @@ setup witin one of the other container widgets, such as a table.</para> the properties of the previous two, but it allows you to specify what position you want the page to be in the notebook.</para> -<para><literallayout> -<literal>void gtk_notebook_insert_page( GtkNotebook *notebook, +<programlisting role="C"> +void gtk_notebook_insert_page( GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label, - gint position );</literal> -</literallayout></para> + gint position ); +</programlisting> <para>The parameters are the same as _append_ and _prepend_ except it contains an extra parameter, <literal>position</literal>. This parameter is used to @@ -8402,19 +8415,19 @@ having position zero.</para> <para>Now that we know how to add a page, lets see how we can remove a page from the notebook.</para> -<para><literallayout> -<literal>void gtk_notebook_remove_page( GtkNotebook *notebook, - gint page_num );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_notebook_remove_page( GtkNotebook *notebook, + gint page_num ); +</programlisting> <para>This function takes the page specified by <literal>page_num</literal> and removes it from the widget pointed to by <literal>notebook</literal>.</para> <para>To find out what the current page is in a notebook use the function:</para> -<para><literallayout> -<literal>gint gtk_notebook_get_current_page( GtkNotebook *notebook );</literal> -</literallayout></para> +<programlisting role="C"> +gint gtk_notebook_get_current_page( GtkNotebook *notebook ); +</programlisting> <para>These next two functions are simple calls to move the notebook page forward or backward. Simply provide the respective function call with @@ -8424,40 +8437,40 @@ notebook will wrap back to the first page. Likewise, if the NoteBook is on the first page, and gtk_notebook_prev_page is called, the notebook will wrap to the last page.</para> -<para><literallayout> -<literal>void gtk_notebook_next_page( GtkNoteBook *notebook );</para> +<programlisting role="C"> +void gtk_notebook_next_page( GtkNoteBook *notebook );</para> -<para>void gtk_notebook_prev_page( GtkNoteBook *notebook );</literal> -</literallayout></para> +<para>void gtk_notebook_prev_page( GtkNoteBook *notebook ); +</programlisting> <para>This next function sets the "active" page. If you wish the notebook to be opened to page 5 for example, you would use this function. Without using this function, the notebook defaults to the first page.</para> -<para><literallayout> -<literal>void gtk_notebook_set_page( GtkNotebook *notebook, - gint page_num );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_notebook_set_page( GtkNotebook *notebook, + gint page_num ); +</programlisting> <para>The next two functions add or remove the notebook page tabs and the notebook border respectively.</para> -<para><literallayout> -<literal>void gtk_notebook_set_show_tabs( GtkNotebook *notebook, +<programlisting role="C"> +void gtk_notebook_set_show_tabs( GtkNotebook *notebook, gboolean show_tabs);</para> <para>void gtk_notebook_set_show_border( GtkNotebook *notebook, - gboolean show_border );</literal> -</literallayout></para> + gboolean show_border ); +</programlisting> <para>The next function is useful when the you have a large number of pages, and the tabs don't fit on the page. It allows the tabs to be scrolled through using two arrow buttons.</para> -<para><literallayout> -<literal>void gtk_notebook_set_scrollable( GtkNotebook *notebook, - gboolean scrollable );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_notebook_set_scrollable( GtkNotebook *notebook, + gboolean scrollable ); +</programlisting> <para><literal>show_tabs</literal>, <literal>show_border</literal> and <literal>scrollable</literal> can be either TRUE or FALSE.</para> @@ -8683,12 +8696,12 @@ it have?</para> <para>Not all columns have to be visible and can be used to store data that is related to a certain cell in the list.</para> -<para><literallayout> -<literal>GtkWidget *gtk_clist_new ( gint columns );</para> +<programlisting role="C"> +GtkWidget *gtk_clist_new ( gint columns );</para> <para>GtkWidget *gtk_clist_new_with_titles( gint columns, - gchar *titles[] );</literal> -</literallayout></para> + gchar *titles[] ); +</programlisting> <para>The first form is very straightforward, the second might require some explanation. Each column can have a title associated with it, and this @@ -8711,10 +8724,10 @@ functionality. This is a change from the GTK 1.0 implementation.</para> <para>There are several attributes that can be used to alter the behaviour of a CList. First there is</para> -<para><literallayout> -<literal>void gtk_clist_set_selection_mode( GtkCList *clist, - GtkSelectionMode mode );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_clist_set_selection_mode( GtkCList *clist, + GtkSelectionMode mode ); +</programlisting> <para>which, as the name implies, sets the selection mode of the CList. The first argument is the CList widget, and the second @@ -8747,20 +8760,20 @@ on. This is currently the <bf>default</bf> for the CList widget.</para> <para>We can also define what the border of the CList widget should look like. It is done through</para> -<para><literallayout> -<literal>void gtk_clist_set_shadow_type( GtkCList *clist, - GtkShadowType border );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_clist_set_shadow_type( GtkCList *clist, + GtkShadowType border ); +</programlisting> <para>The possible values for the second argument are</para> -<para><literallayout> -<literal> GTK_SHADOW_NONE +<programlisting role="C"> + GTK_SHADOW_NONE GTK_SHADOW_IN GTK_SHADOW_OUT GTK_SHADOW_ETCHED_IN - GTK_SHADOW_ETCHED_OUT</literal> -</literallayout></para> + GTK_SHADOW_ETCHED_OUT +</programlisting> </sect1> @@ -8775,8 +8788,8 @@ they can be passive, in which case they are nothing more than a title. There are four different calls that aid us in setting the status of the title buttons.</para> -<para><literallayout> -<literal>void gtk_clist_column_title_active( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_column_title_active( GtkCList *clist, gint column );</para> <para>void gtk_clist_column_title_passive( GtkCList *clist, @@ -8784,8 +8797,8 @@ status of the title buttons.</para> <para>void gtk_clist_column_titles_active( GtkCList *clist );</para> -<para>void gtk_clist_column_titles_passive( GtkCList *clist );</literal> -</literallayout></para> +<para>void gtk_clist_column_titles_passive( GtkCList *clist ); +</programlisting> <para>An active title is one which acts as a normal button, a passive one is just a label. The first two calls above will activate/deactivate the @@ -8796,20 +8809,20 @@ activate/deactivate all title buttons in the supplied clist widget.</para> and so they can be hidden and shown at will using the following two calls.</para> -<para><literallayout> -<literal>void gtk_clist_column_titles_show( GtkCList *clist );</para> +<programlisting role="C"> +void gtk_clist_column_titles_show( GtkCList *clist );</para> -<para>void gtk_clist_column_titles_hide( GtkCList *clist );</literal> -</literallayout></para> +<para>void gtk_clist_column_titles_hide( GtkCList *clist ); +</programlisting> <para>For titles to be really useful we need a mechanism to set and change them, and this is done using</para> -<para><literallayout> -<literal>void gtk_clist_set_column_title( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_column_title( GtkCList *clist, gint column, - gchar *title );</literal> -</literallayout></para> + gchar *title ); +</programlisting> <para>Note that only the title of one column can be set at a time, so if all the titles are known from the beginning, then I really suggest using @@ -8820,11 +8833,11 @@ not all titles will be text. CList provides us with title buttons that can in fact incorporate whole widgets, for example a pixmap. It's all done through</para> -<para><literallayout> -<literal>void gtk_clist_set_column_widget( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_column_widget( GtkCList *clist, gint column, - GtkWidget *widget );</literal> -</literallayout></para> + GtkWidget *widget ); +</programlisting> <para>which should require no special explanation.</para> @@ -8837,11 +8850,11 @@ all done through</para> <para>It is possible to change the justification for a column, and it is done through</para> -<para><literallayout> -<literal>void gtk_clist_set_column_justification( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_column_justification( GtkCList *clist, gint column, - GtkJustification justification );</literal> -</literallayout></para> + GtkJustification justification ); +</programlisting> <para>The GtkJustification type can take the following values:</para> @@ -8870,21 +8883,21 @@ the setup of all CList widgets. When the list is created, the width of the various columns are chosen to match their titles, and since this is seldom the right width we have to set it using</para> -<para><literallayout> -<literal>void gtk_clist_set_column_width( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_column_width( GtkCList *clist, gint column, - gint width );</literal> -</literallayout></para> + gint width ); +</programlisting> <para>Note that the width is given in pixels and not letters. The same goes for the height of the cells in the columns, but as the default value is the height of the current font this isn't as critical to the application. Still, it is done through</para> -<para><literallayout> -<literal>void gtk_clist_set_row_height( GtkCList *clist, - gint height );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_clist_set_row_height( GtkCList *clist, + gint height ); +</programlisting> <para>Again, note that the height is given in pixels.</para> @@ -8892,13 +8905,13 @@ application. Still, it is done through</para> does require that we know what we are looking for. Or in other words, we need the row and column of the item we want to scroll to.</para> -<para><literallayout> -<literal>void gtk_clist_moveto( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_moveto( GtkCList *clist, gint row, gint column, gfloat row_align, - gfloat col_align );</literal> -</literallayout></para> + gfloat col_align ); +</programlisting> <para>The gfloat row_align is pretty important to understand. It's a value between 0.0 and 1.0, where 0.0 means that we should scroll the list so @@ -8912,18 +8925,18 @@ though 0.0 marks left and 1.0 marks right instead.</para> item that is already visible to us. So how do we know if it is visible? As usual, there is a function to find that out as well.</para> -<para><literallayout> -<literal>GtkVisibility gtk_clist_row_is_visible( GtkCList *clist, - gint row );</literal> -</literallayout></para> +<programlisting role="C"> +GtkVisibility gtk_clist_row_is_visible( GtkCList *clist, + gint row ); +</programlisting> <para>The return value is is one of the following:</para> -<para><literallayout> -<literal> GTK_VISIBILITY_NONE +<programlisting role="C"> + GTK_VISIBILITY_NONE GTK_VISIBILITY_PARTIAL - GTK_VISIBILITY_FULL</literal> -</literallayout></para> + GTK_VISIBILITY_FULL +</programlisting> <para>Note that it will only tell us if a row is visible. Currently there is no way to determine this for a column. We can get partial information @@ -8936,15 +8949,15 @@ are outside.</para> particular row. This is useful for marking the row selected by the user, and the two functions that is used to do it are</para> -<para><literallayout> -<literal>void gtk_clist_set_foreground( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_foreground( GtkCList *clist, gint row, GdkColor *color );</para> <para>void gtk_clist_set_background( GtkCList *clist, gint row, - GdkColor *color );</literal> -</literallayout></para> + GdkColor *color ); +</programlisting> <para>Please note that the colors must have been previously allocated.</para> @@ -8957,22 +8970,22 @@ user, and the two functions that is used to do it are</para> <para>We can add rows in three ways. They can be prepended or appended to the list using</para> -<para><literallayout> -<literal>gint gtk_clist_prepend( GtkCList *clist, +<programlisting role="C"> +gint gtk_clist_prepend( GtkCList *clist, gchar *text[] );</para> <para>gint gtk_clist_append( GtkCList *clist, - gchar *text[] );</literal> -</literallayout></para> + gchar *text[] ); +</programlisting> <para>The return value of these two functions indicate the index of the row that was just added. We can insert a row at a given place using</para> -<para><literallayout> -<literal>void gtk_clist_insert( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_insert( GtkCList *clist, gint row, - gchar *text[] );</literal> -</literallayout></para> + gchar *text[] ); +</programlisting> <para>In these calls we have to provide a collection of pointers that are the texts we want to put in the columns. The number of pointers should @@ -8985,18 +8998,18 @@ has to be done manually).</para> <para>To remove an individual row we use</para> -<para><literallayout> -<literal>void gtk_clist_remove( GtkCList *clist, - gint row );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_clist_remove( GtkCList *clist, + gint row ); +</programlisting> <para>There is also a call that removes all rows in the list. This is a lot faster than calling gtk_clist_remove once for each row, which is the only alternative.</para> -<para><literallayout> -<literal>void gtk_clist_clear( GtkCList *clist );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_clist_clear( GtkCList *clist ); +</programlisting> <para>There are also two convenience functions that should be used when a lot of changes have to be made to the list. This is to prevent the @@ -9005,11 +9018,11 @@ annoying to the user. So instead it is a good idea to freeze the list, do the updates to it, and finally thaw it which causes the list to be updated on the screen.</para> -<para><literallayout> -<literal>void gtk_clist_freeze( GtkCList * clist );</para> +<programlisting role="C"> +void gtk_clist_freeze( GtkCList * clist );</para> -<para>void gtk_clist_thaw( GtkCList * clist );</literal> -</literallayout></para> +<para>void gtk_clist_thaw( GtkCList * clist ); +</programlisting> </sect1> @@ -9020,8 +9033,8 @@ updated on the screen.</para> <para>A cell can contain a pixmap, text or both. To set them the following functions are used.</para> -<para><literallayout> -<literal>void gtk_clist_set_text( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_text( GtkCList *clist, gint row, gint column, const gchar *text );</para> @@ -9038,8 +9051,8 @@ functions are used.</para> gchar *text, guint8 spacing, GdkPixmap *pixmap, - GdkBitmap *mask );</literal> -</literallayout></para> + GdkBitmap *mask ); +</programlisting> <para>It's quite straightforward. All the calls have the CList as the first argument, followed by the row and column of the cell, followed by the @@ -9049,8 +9062,8 @@ text. In all cases the data is copied into the widget.</para> <para>To read back the data, we instead use</para> -<para><literallayout> -<literal>gint gtk_clist_get_text( GtkCList *clist, +<programlisting role="C"> +gint gtk_clist_get_text( GtkCList *clist, gint row, gint column, gchar **text );</para> @@ -9067,8 +9080,8 @@ text. In all cases the data is copied into the widget.</para> gchar **text, guint8 *spacing, GdkPixmap **pixmap, - GdkBitmap **mask );</literal> -</literallayout></para> + GdkBitmap **mask ); +</programlisting> <para>The returned pointers are all pointers to the data stored within the widget, so the referenced data should not be modified or released. It @@ -9078,42 +9091,42 @@ clist) can be NULL. So if we want to read back only the text from a cell that is of type pixtext, then we would do the following, assuming that clist, row and column already exist:</para> -<para><literallayout> -<literal>gchar *mytext;</para> +<programlisting role="C"> +gchar *mytext;</para> -<para>gtk_clist_get_pixtext(clist, row, column, &mytext, NULL, NULL, NULL);</literal> -</literallayout></para> +<para>gtk_clist_get_pixtext(clist, row, column, &mytext, NULL, NULL, NULL); +</programlisting> <para>There is one more call that is related to what's inside a cell in the clist, and that's</para> -<para><literallayout> -<literal>GtkCellType gtk_clist_get_cell_type( GtkCList *clist, +<programlisting role="C"> +GtkCellType gtk_clist_get_cell_type( GtkCList *clist, gint row, - gint column );</literal> -</literallayout></para> + gint column ); +</programlisting> <para>which returns the type of data in a cell. The return value is one of</para> -<para><literallayout> -<literal> GTK_CELL_EMPTY +<programlisting role="C"> + GTK_CELL_EMPTY GTK_CELL_TEXT GTK_CELL_PIXMAP GTK_CELL_PIXTEXT - GTK_CELL_WIDGET</literal> -</literallayout></para> + GTK_CELL_WIDGET +</programlisting> <para>There is also a function that will let us set the indentation, both vertical and horizontal, of a cell. The indentation value is of type gint, given in pixels, and can be both positive and negative.</para> -<para><literallayout> -<literal>void gtk_clist_set_shift( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_shift( GtkCList *clist, gint row, gint column, gint vertical, - gint horizontal );</literal> -</literallayout></para> + gint horizontal ); +</programlisting> </sect1> @@ -9128,8 +9141,8 @@ additional data.</para> <para>The functions should be fairly self-explanatory by now.</para> -<para><literallayout> -<literal>void gtk_clist_set_row_data( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_set_row_data( GtkCList *clist, gint row, gpointer data );</para> @@ -9142,8 +9155,8 @@ additional data.</para> gint row );</para> <para>gint gtk_clist_find_row_from_data( GtkCList *clist, - gpointer data );</literal> -</literallayout></para> + gpointer data ); +</programlisting> </sect1> @@ -9154,27 +9167,27 @@ additional data.</para> <para>There are also functions available that let us force the (un)selection of a row. These are</para> -<para><literallayout> -<literal>void gtk_clist_select_row( GtkCList *clist, +<programlisting role="C"> +void gtk_clist_select_row( GtkCList *clist, gint row, gint column );</para> <para>void gtk_clist_unselect_row( GtkCList *clist, gint row, - gint column );</literal> -</literallayout></para> + gint column ); +</programlisting> <para>And also a function that will take x and y coordinates (for example, read from the mousepointer), and map that onto the list, returning the corresponding row and column.</para> -<para><literallayout> -<literal>gint gtk_clist_get_selection_info( GtkCList *clist, +<programlisting role="C"> +gint gtk_clist_get_selection_info( GtkCList *clist, gint x, gint y, gint *row, - gint *column );</literal> -</literallayout></para> + gint *column ); +</programlisting> <para>When we detect something of interest (it might be movement of the pointer, a click somewhere in the list) we can read the pointer @@ -9207,22 +9220,22 @@ activated. It sends the same information as select_row</para> <para>So if we want to connect a callback to select_row, the callback function would be declared like this</para> -<para><literallayout> -<literal>void select_row_callback(GtkWidget *widget, +<programlisting role="C"> +void select_row_callback(GtkWidget *widget, gint row, gint column, GdkEventButton *event, - gpointer data);</literal> -</literallayout></para> + gpointer data); +</programlisting> <para>The callback is connected as usual with</para> -<para><literallayout> -<literal>gtk_signal_connect(GTK_OBJECT( clist), +<programlisting role="C"> +gtk_signal_connect(GTK_OBJECT( clist), "select_row" GTK_SIGNAL_FUNC(select_row_callback), - NULL);</literal> -</literallayout></para> + NULL); +</programlisting> </sect1> @@ -9231,8 +9244,8 @@ function would be declared like this</para> <title>A CList example</title> </para> -<para><literallayout> -<literal>/* example-start clist clist.c */ +<programlisting role="C"> +/* example-start clist clist.c */ #include <gtk/gtk.h> @@ -9433,14 +9446,14 @@ columns optionally have titles that are displayed along the top of the CTree widget. Hence there are two functions for creating a new CTree widget:</para> -<para><literallayout> -<literal>GtkWidget *gtk_ctree_new_with_titles( gint columns, +<programlisting role="C"> +GtkWidget *gtk_ctree_new_with_titles( gint columns, gint tree_column, gchar *titles[] );</para> <para>GtkWidget *gtk_ctree_new( gint columns, - gint tree_column );</literal> -</literallayout></para> + gint tree_column ); +</programlisting> <para>The <literal>columns</literal> argument specifies the number of columns that the CTree will contain. The <literal>tree_column</literal> argumnet specifies which of @@ -9452,13 +9465,13 @@ array of strings that contain the captions for the column headings. A typical code fragment using the <literal>gtk_ctree_new_with_titles()</literal> function would be:</para> -<para><literallayout> -<literal> /* CTree column titles /* +<programlisting role="C"> + /* CTree column titles /* char *titles[] = { "Location" , "Description" }; GtkWidget *ctree;</para> -<para> ctree = gtk_ctree_new_with_titles(2, 0, titles);</literal> -</literallayout></para> +<para> ctree = gtk_ctree_new_with_titles(2, 0, titles); +</programlisting> <para>This would create a new CTree with two columns entitled "Location" and "Description", with the first column containing the tree.</para> @@ -9472,8 +9485,8 @@ into a CTree in such a way as to create a hierarchy (although the order of insertion is not critical). The following function is used to insert a node:</para> -<para><literallayout> -<literal>GtkCTreeNode *gtk_ctree_insert_node( GtkCTree *ctree, +<programlisting role="C"> +GtkCTreeNode *gtk_ctree_insert_node( GtkCTree *ctree, GtkCTreeNode *parent, GtkCTreeNode *sibling, gchar *text[], @@ -9483,8 +9496,8 @@ insert a node:</para> GdkPixmap *pixmap_opened, GdkBitmap *mask_opened, gboolean is_leaf, - gboolean expanded );</literal> -</literallayout></para> + gboolean expanded ); +</programlisting> <para>This function looks a little daunting, but that is merely due to the power of the CTreee widget. Not all of the parameters above are @@ -9539,10 +9552,10 @@ signal pertains to.</para> <para>To remove a node for a CTree, the following function is provided:</para> -<para><literallayout> -<literal>void gtk_ctree_remove_node( GtkCTree *ctree, - GtkCTreeNode *node );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_ctree_remove_node( GtkCTree *ctree, + GtkCTreeNode *node ); +</programlisting> <para>As you can see, you merely need to specify a CTree and the node to remove.</para> @@ -9557,13 +9570,13 @@ remove.</para> CTree instance as a whole (rather than to a particular node). The first group set padding attributes that effect how the widget is drawn:</para> -<para><literallayout> -<literal>void gtk_ctree_set_indent( GtkCTree *ctree, +<programlisting role="C"> +void gtk_ctree_set_indent( GtkCTree *ctree, gint indent );</para> <para>void gtk_ctree_set_spacing( GtkCTree *ctree, - gint spacing );</literal> -</literallayout></para> + gint spacing ); +</programlisting> <para>The function <literal>gtk_ctree_set_indent()</literal> sets how far a new branch is indented in relation to it's parent. The default is 20.</para> @@ -9577,35 +9590,35 @@ are drawn to represent the tree structure. An expander is a grpahical component that the user can select to expand and collapse a branch of the tree.</para> -<para><literallayout> -<literal>void gtk_ctree_set_line_style( GtkCTree *ctree, +<programlisting role="C"> +void gtk_ctree_set_line_style( GtkCTree *ctree, GtkCTreeLineStyle line_style );</para> <para>void gtk_ctree_set_expander_style( GtkCTree *ctree, - GtkCTreeExpanderStyle expander_style );</literal> -</literallayout></para> + GtkCTreeExpanderStyle expander_style ); +</programlisting> <para>The function <literal>gtk_ctree_set_line_style()</literal> is used to select the style of line that is drawn between nodes of the tree. The parameter <literal>line_style</literal> can be one of:</para> -<para><literallayout> -<literal> GTK_CTREE_LINES_NONE +<programlisting role="C"> + GTK_CTREE_LINES_NONE GTK_CTREE_LINES_SOLID GTK_CTREE_LINES_DOTTED - GTK_CTREE_LINES_TABBED</literal> -</literallayout></para> + GTK_CTREE_LINES_TABBED +</programlisting> <para>The function <literal>gtk_ctree_set_expander_style()</literal> is used to select the style of branch expander, and the parameter <literal>expander_style</literal> can be one of:</para> -<para><literallayout> -<literal> GTK_CTREE_EXPANDER_NONE +<programlisting role="C"> + GTK_CTREE_EXPANDER_NONE GTK_CTREE_EXPANDER_SQUARE GTK_CTREE_EXPANDER_TRIANGLE - GTK_CTREE_EXPANDER_CIRCULAR</literal> -</literallayout></para> + GTK_CTREE_EXPANDER_CIRCULAR +</programlisting> </sect1> @@ -9623,16 +9636,16 @@ allows a set of data to be referenced.</para> <para>There are two functions for setting row data:</para> -<para><literallayout> -<literal>void gtk_ctree_node_set_row_data( GtkCTree *ctree, +<programlisting role="C"> +void gtk_ctree_node_set_row_data( GtkCTree *ctree, GtkCTreeNode *node, gpointer data );</para> <para>void gtk_ctree_node_set_row_data_full( GtkCTree *ctree, GtkCTreeNode *node, gpointer data, - GtkDestroyNotify destroy );</literal> -</literallayout></para> + GtkDestroyNotify destroy ); +</programlisting> <para>The function <literal>gtk_ctree_node_set_row_data()</literal> simply takes as arguments pointers to the CTree, node and data.</para> @@ -9643,9 +9656,9 @@ function that will be called when the row is destroyed. Typically, this function would take responsibility for freeing the memory used by the row data. This function should take the form:</para> -<para><literallayout> -<literal>void destroy_func( gpointer data );</literal> -</literallayout></para> +<programlisting role="C"> +void destroy_func( gpointer data ); +</programlisting> <para>The paramter passed to this function will be the row data.</para> @@ -9677,9 +9690,9 @@ not derived from CList, so you cannot use them interchangeably.</para> <para>A Tree is created in the usual way, using:</para> -<para><literallayout> -<literal>GtkWidget *gtk_tree_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_tree_new( void ); +</programlisting> <para>Like the CList widget, a Tree will simply keep growing as more items are added to it, as well as when subtrees are expanded. For @@ -9693,21 +9706,21 @@ it. <link linkend="ch-TreeItemWidget">The Tree Item Widget</link> below explains the gory details of TreeItem. For now, it'll suffice to create one, using:</para> -<para><literallayout> -<literal>GtkWidget *gtk_tree_item_new_with_label( gchar *label );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_tree_item_new_with_label( gchar *label ); +</programlisting> <para>You can then add it to the tree using one of the following (see <link linkend="ch-TreeFunctions">Functions and Macros</link> below for more options):</para> -<para><literallayout> -<literal>void gtk_tree_append( GtkTree *tree, +<programlisting role="C"> +void gtk_tree_append( GtkTree *tree, GtkWidget *tree_item );</para> <para>void gtk_tree_prepend( GtkTree *tree, - GtkWidget *tree_item );</literal> -</literallayout></para> + GtkWidget *tree_item ); +</programlisting> <para>Note that you must add items to a Tree one at a time - there is no equivalent to gtk_list_*_items().</para> @@ -9721,10 +9734,10 @@ equivalent to gtk_list_*_items().</para> <para>A subtree is created like any other Tree widget. A subtree is added to another tree beneath a tree item, using:</para> -<para><literallayout> -<literal>void gtk_tree_item_set_subtree( GtkTreeItem *tree_item, - GtkWidget *subtree );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_item_set_subtree( GtkTreeItem *tree_item, + GtkWidget *subtree ); +</programlisting> <para>You do not need to call gtk_widget_show() on a subtree before or after adding it to a TreeItem. However, you <emphasis>must</emphasis> have added the @@ -9750,10 +9763,10 @@ expects.</para> it is possible to control the behaviour of the tree (somewhat) by setting the selection type using:</para> -<para><literallayout> -<literal>void gtk_tree_set_selection_mode( GtkTree *tree, - GtkSelectionMode mode );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_set_selection_mode( GtkTree *tree, + GtkSelectionMode mode ); +</programlisting> <para>The semantics associated with the various selection modes are described in the section on the CList widget. As with the CList @@ -9791,8 +9804,8 @@ to call gtk_signal_connect() for every subtree.</para> <para>The Tree's struct definition looks like this:</para> -<para><literallayout> -<literal>struct _GtkTree +<programlisting role="C"> +struct _GtkTree { GtkContainer container;</para> @@ -9807,8 +9820,8 @@ to call gtk_signal_connect() for every subtree.</para> guint selection_mode : 2; guint view_mode : 1; guint view_line : 1; -};</literal> -</literallayout></para> +}; +</programlisting> <para>The perils associated with accessing the <literal>selection</literal> field directly have already been mentioned. The other important fields of @@ -9826,13 +9839,13 @@ duplicate of the original list, so it's advisable to free it up using g_list_free() after you're done with it, or to iterate on it destructively, like this:</para> -<para><literallayout> -<literal> children = gtk_container_children (GTK_CONTAINER (tree)); +<programlisting role="C"> + children = gtk_container_children (GTK_CONTAINER (tree)); while (children) { do_something_nice (GTK_TREE_ITEM (children->data)); children = g_list_remove_link (children, children); -}</literal> -</literallayout></para> +} +</programlisting> <para>The <literal>tree_owner</literal> field is defined only in subtrees, where it points to the TreeItem widget which holds the tree in question. @@ -9845,18 +9858,18 @@ after a Tree widget is actually mapped (i.e. drawn on the screen).</para> <!-- ----------------------------------------------------------------- --> <sect2> Signals -<para><literallayout> -<literal>void selection_changed( GtkTree *tree );</literal> -</literallayout></para> +<programlisting role="C"> +void selection_changed( GtkTree *tree ); +</programlisting> <para>This signal will be emitted whenever the <literal>selection</literal> field of a Tree has changed. This happens when a child of the Tree is selected or deselected.</para> -<para><literallayout> -<literal>void select_child( GtkTree *tree, - GtkWidget *child );</literal> -</literallayout></para> +<programlisting role="C"> +void select_child( GtkTree *tree, + GtkWidget *child ); +</programlisting> <para>This signal is emitted when a child of the Tree is about to get selected. This happens on calls to gtk_tree_select_item(), @@ -9865,10 +9878,10 @@ gtk_tree_item_toggle() and gtk_item_toggle(). It may sometimes be indirectly triggered on other occasions where children get added to or removed from the Tree.</para> -<para><literallayout> -<literal>void unselect_child (GtkTree *tree, - GtkWidget *child);</literal> -</literallayout></para> +<programlisting role="C"> +void unselect_child (GtkTree *tree, + GtkWidget *child); +</programlisting> <para>This signal is emitted when a child of the Tree is about to get deselected. As of GTK 1.0.4, this seems to only occur on calls to @@ -9878,46 +9891,46 @@ child, nor on emission of the "toggle" signal by gtk_item_toggle().</para> <para><sect2> Functions and Macros<label id="ch-Tree_Functions"></para> -<para><literallayout> -<literal>guint gtk_tree_get_type( void );</literal> -</literallayout></para> +<programlisting role="C"> +guint gtk_tree_get_type( void ); +</programlisting> <para>Returns the "GtkTree" type identifier.</para> -<para><literallayout> -<literal>GtkWidget* gtk_tree_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget* gtk_tree_new( void ); +</programlisting> <para>Create a new Tree object. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.</para> -<para><literallayout> -<literal>void gtk_tree_append( GtkTree *tree, - GtkWidget *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_append( GtkTree *tree, + GtkWidget *tree_item ); +</programlisting> <para>Append a tree item to a Tree.</para> -<para><literallayout> -<literal>void gtk_tree_prepend( GtkTree *tree, - GtkWidget *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_prepend( GtkTree *tree, + GtkWidget *tree_item ); +</programlisting> <para>Prepend a tree item to a Tree.</para> -<para><literallayout> -<literal>void gtk_tree_insert( GtkTree *tree, +<programlisting role="C"> +void gtk_tree_insert( GtkTree *tree, GtkWidget *tree_item, - gint position );</literal> -</literallayout></para> + gint position ); +</programlisting> <para>Insert a tree item into a Tree at the position in the list specified by <literal>position.</literal></para> -<para><literallayout> -<literal>void gtk_tree_remove_items( GtkTree *tree, - GList *items );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_remove_items( GtkTree *tree, + GList *items ); +</programlisting> <para>Remove a list of items (in the form of a GList *) from a Tree. Note that removing an item from a tree dereferences (and thus usually) @@ -9925,62 +9938,62 @@ destroys it <emphasis>and</emphasis> its subtree, if it has one, <emphasis>and</ subtrees in that subtree. If you want to remove only one item, you can use gtk_container_remove().</para> -<para><literallayout> -<literal>void gtk_tree_clear_items( GtkTree *tree, +<programlisting role="C"> +void gtk_tree_clear_items( GtkTree *tree, gint start, - gint end );</literal> -</literallayout></para> + gint end ); +</programlisting> <para>Remove the items from position <literal>start</literal> to position <literal>end</literal> from a Tree. The same warning about dereferencing applies here, as gtk_tree_clear_items() simply constructs a list and passes it to gtk_tree_remove_items().</para> -<para><literallayout> -<literal>void gtk_tree_select_item( GtkTree *tree, - gint item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_select_item( GtkTree *tree, + gint item ); +</programlisting> <para>Emits the "select_item" signal for the child at position <literal>item</literal>, thus selecting the child (unless you unselect it in a signal handler).</para> -<para><literallayout> -<literal>void gtk_tree_unselect_item( GtkTree *tree, - gint item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_unselect_item( GtkTree *tree, + gint item ); +</programlisting> <para>Emits the "unselect_item" signal for the child at position <literal>item</literal>, thus unselecting the child.</para> -<para><literallayout> -<literal>void gtk_tree_select_child( GtkTree *tree, - GtkWidget *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_select_child( GtkTree *tree, + GtkWidget *tree_item ); +</programlisting> <para>Emits the "select_item" signal for the child <literal>tree_item</literal>, thus selecting it.</para> -<para><literallayout> -<literal>void gtk_tree_unselect_child( GtkTree *tree, - GtkWidget *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_unselect_child( GtkTree *tree, + GtkWidget *tree_item ); +</programlisting> <para>Emits the "unselect_item" signal for the child <literal>tree_item</literal>, thus unselecting it.</para> -<para><literallayout> -<literal>gint gtk_tree_child_position( GtkTree *tree, - GtkWidget *child );</literal> -</literallayout></para> +<programlisting role="C"> +gint gtk_tree_child_position( GtkTree *tree, + GtkWidget *child ); +</programlisting> <para>Returns the position in the tree of <literal>child</literal>, unless <literal>child</literal> is not in the tree, in which case it returns -1.</para> -<para><literallayout> -<literal>void gtk_tree_set_selection_mode( GtkTree *tree, - GtkSelectionMode mode );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_set_selection_mode( GtkTree *tree, + GtkSelectionMode mode ); +</programlisting> <para>Sets the selection mode, which can be one of <literal>GTK_SELECTION_SINGLE</literal> (the default), <literal>GTK_SELECTION_BROWSE</literal>, <literal>GTK_SELECTION_MULTIPLE</literal>, or @@ -9988,10 +10001,10 @@ default), <literal>GTK_SELECTION_BROWSE</literal>, <literal>GTK_SELECTION_MULTIP makes sense, since the root tree "owns" the selection. Setting it for subtrees has no effect at all; the value is simply ignored.</para> -<para><literallayout> -<literal>void gtk_tree_set_view_mode( GtkTree *tree, - GtkTreeViewMode mode ); </literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_set_view_mode( GtkTree *tree, + GtkTreeViewMode mode ); +</programlisting> <para>Sets the "view mode", which can be either <literal>GTK_TREE_VIEW_LINE</literal> (the default) or <literal>GTK_TREE_VIEW_ITEM</literal>. The view mode propagates from a @@ -10004,52 +10017,52 @@ If it's <literal>GTK_TREE_VIEW_LINE</literal>, the entire TreeItem widget is highlighted, while for <literal>GTK_TREE_VIEW_ITEM</literal>, only the child widget (i.e., usually the label) is highlighted.</para> -<para><literallayout> -<literal>void gtk_tree_set_view_lines( GtkTree *tree, - guint flag );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_set_view_lines( GtkTree *tree, + guint flag ); +</programlisting> <para>Controls whether connecting lines between tree items are drawn. <literal>flag</literal> is either TRUE, in which case they are, or FALSE, in which case they aren't.</para> -<para><literallayout> -<literal>GtkTree *GTK_TREE (gpointer obj);</literal> -</literallayout></para> +<programlisting role="C"> +GtkTree *GTK_TREE (gpointer obj); +</programlisting> <para>Cast a generic pointer to "GtkTree *".</para> -<para><literallayout> -<literal>GtkTreeClass *GTK_TREE_CLASS (gpointer class);</literal> -</literallayout></para> +<programlisting role="C"> +GtkTreeClass *GTK_TREE_CLASS (gpointer class); +</programlisting> <para>Cast a generic pointer to "GtkTreeClass *".</para> -<para><literallayout> -<literal>gint GTK_IS_TREE (gpointer obj);</literal> -</literallayout></para> +<programlisting role="C"> +gint GTK_IS_TREE (gpointer obj); +</programlisting> <para>Determine if a generic pointer refers to a "GtkTree" object.</para> -<para><literallayout> -<literal>gint GTK_IS_ROOT_TREE (gpointer obj)</literal> -</literallayout></para> +<programlisting role="C"> +gint GTK_IS_ROOT_TREE (gpointer obj) +</programlisting> <para>Determine if a generic pointer refers to a "GtkTree" object <emphasis>and</emphasis> is a root tree. Though this will accept any pointer, the results of passing it a pointer that does not refer to a Tree are undefined and possibly harmful.</para> -<para><literallayout> -<literal>GtkTree *GTK_TREE_ROOT_TREE (gpointer obj)</literal> -</literallayout></para> +<programlisting role="C"> +GtkTree *GTK_TREE_ROOT_TREE (gpointer obj) +</programlisting> <para>Return the root tree of a pointer to a "GtkTree" object. The above warning applies.</para> -<para><literallayout> -<literal>GList *GTK_TREE_SELECTION( gpointer obj)</literal> -</literallayout></para> +<programlisting role="C"> +GList *GTK_TREE_SELECTION( gpointer obj) +</programlisting> <para>Return the selection list of the root tree of a "GtkTree" object. The above warning applies here, too.</para> @@ -10064,8 +10077,8 @@ the only one we need be concerned with is the <literal>subtree</literal> field.< <para>The definition for the TreeItem struct looks like this:</para> -<para><literallayout> -<literal>struct _GtkTreeItem +<programlisting role="C"> +struct _GtkTreeItem { GtkItem item;</para> @@ -10076,8 +10089,8 @@ the only one we need be concerned with is the <literal>subtree</literal> field.< <para> GList *pixmaps; /* pixmap node for this items color depth */</para> <para> guint expanded : 1; -};</literal> -</literallayout></para> +}; +</programlisting> <para>The <literal>pixmaps_box</literal> field is an EventBox which catches clicks on the plus/minus symbol which controls expansion and collapsing. The @@ -10094,14 +10107,14 @@ provided. The same effect can be achieved using code like the following, which is actually copied verbatim from gtk_tree_item_new_with_label():</para> -<para><literallayout> -<literal>tree_item = gtk_tree_item_new (); +<programlisting role="C"> +tree_item = gtk_tree_item_new (); label_widget = gtk_label_new (label); gtk_misc_set_alignment (GTK_MISC (label_widget), 0.0, 0.5);</para> <para>gtk_container_add (GTK_CONTAINER (tree_item), label_widget); -gtk_widget_show (label_widget);</literal> -</literallayout></para> +gtk_widget_show (label_widget); +</programlisting> <para>As one is not forced to add a Label to a TreeItem, you could also add an HBox or an Arrow, or even a Notebook (though your @@ -10112,8 +10125,8 @@ unparented, unless you reference it beforehand, and the TreeItem which owns it will be collapsed. So, if you want it to stick around, do something like the following:</para> -<para><literallayout> -<literal>gtk_widget_ref (tree); +<programlisting role="C"> +gtk_widget_ref (tree); owner = GTK_TREE(tree)->tree_owner; gtk_container_remove (GTK_CONTAINER(tree), item); if (tree->parent == NULL){ @@ -10121,8 +10134,8 @@ if (tree->parent == NULL){ gtk_tree_item_set_subtree (GTK_TREE_ITEM(owner), tree); } else - gtk_widget_unref (tree);</literal> -</literallayout></para> + gtk_widget_unref (tree); +</programlisting> <para>Finally, drag-n-drop <emphasis>does</emphasis> work with TreeItems. You just have to make sure that the TreeItem you want to make into a drag @@ -10138,17 +10151,17 @@ or gtk_widget_dnd_drop_set(). Otherwise, strange things will happen.</para> from Item. In addition, it adds two signals of its own, "expand" and "collapse".</para> -<para><literallayout> -<literal>void select( GtkItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void select( GtkItem *tree_item ); +</programlisting> <para>This signal is emitted when an item is about to be selected, either after it has been clicked on by the user, or when the program calls gtk_tree_item_select(), gtk_item_select(), or gtk_tree_select_child().</para> -<para><literallayout> -<literal>void deselect( GtkItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void deselect( GtkItem *tree_item ); +</programlisting> <para>This signal is emitted when an item is about to be unselected, either after it has been clicked on by the user, or when the program calls @@ -10156,9 +10169,9 @@ gtk_tree_item_deselect() or gtk_item_deselect(). In the case of TreeItems, it is also emitted by gtk_tree_unselect_child(), and sometimes gtk_tree_select_child().</para> -<para><literallayout> -<literal>void toggle( GtkItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void toggle( GtkItem *tree_item ); +</programlisting> <para>This signal is emitted when the program calls gtk_item_toggle(). The effect it has when emitted on a TreeItem is to call @@ -10166,17 +10179,17 @@ gtk_tree_select_child() (and never gtk_tree_unselect_child()) on the item's parent tree, if the item has a parent tree. If it doesn't, then the highlight is reversed on the item.</para> -<para><literallayout> -<literal>void expand( GtkTreeItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void expand( GtkTreeItem *tree_item ); +</programlisting> <para>This signal is emitted when the tree item's subtree is about to be expanded, that is, when the user clicks on the plus sign next to the item, or when the program calls gtk_tree_item_expand().</para> -<para><literallayout> -<literal>void collapse( GtkTreeItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void collapse( GtkTreeItem *tree_item ); +</programlisting> <para>This signal is emitted when the tree item's subtree is about to be collapsed, that is, when the user clicks on the minus sign next to the @@ -10185,93 +10198,93 @@ item, or when the program calls gtk_tree_item_collapse().</para> <para><sect2> <title> Functions and Macros</title> -<para><literallayout> -<literal>guint gtk_tree_item_get_type( void );</literal> -</literallayout></para> +<programlisting role="C"> +guint gtk_tree_item_get_type( void ); +</programlisting> <para>Returns the "GtkTreeItem" type identifier.</para> -<para><literallayout> -<literal>GtkWidget* gtk_tree_item_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget* gtk_tree_item_new( void ); +</programlisting> <para>Create a new TreeItem object. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.</para> -<para><literallayout> -<literal>GtkWidget* gtk_tree_item_new_with_label (gchar *label);</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget* gtk_tree_item_new_with_label (gchar *label); +</programlisting> <para>Create a new TreeItem object, having a single GtkLabel as the sole child. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.</para> -<para><literallayout> -<literal>void gtk_tree_item_select( GtkTreeItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_item_select( GtkTreeItem *tree_item ); +</programlisting> <para>This function is basically a wrapper around a call to <literal>gtk_item_select (GTK_ITEM (tree_item))</literal> which will emit the select signal.</para> -<para><literallayout> -<literal>void gtk_tree_item_deselect( GtkTreeItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_item_deselect( GtkTreeItem *tree_item ); +</programlisting> <para>This function is basically a wrapper around a call to gtk_item_deselect (GTK_ITEM (tree_item)) which will emit the deselect signal.</para> -<para><literallayout> -<literal>void gtk_tree_item_set_subtree( GtkTreeItem *tree_item, - GtkWidget *subtree );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_item_set_subtree( GtkTreeItem *tree_item, + GtkWidget *subtree ); +</programlisting> <para>This function adds a subtree to tree_item, showing it if tree_item is expanded, or hiding it if tree_item is collapsed. Again, remember that the tree_item must have already been added to a tree for this to work.</para> -<para><literallayout> -<literal>void gtk_tree_item_remove_subtree( GtkTreeItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_item_remove_subtree( GtkTreeItem *tree_item ); +</programlisting> <para>This removes all of tree_item's subtree's children (thus unreferencing and destroying it, any of its children's subtrees, and so on...), then removes the subtree itself, and hides the plus/minus sign.</para> -<para><literallayout> -<literal>void gtk_tree_item_expand( GtkTreeItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_item_expand( GtkTreeItem *tree_item ); +</programlisting> <para>This emits the "expand" signal on tree_item, which expands it.</para> -<para><literallayout> -<literal>void gtk_tree_item_collapse( GtkTreeItem *tree_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_tree_item_collapse( GtkTreeItem *tree_item ); +</programlisting> <para>This emits the "collapse" signal on tree_item, which collapses it.</para> -<para><literallayout> -<literal>GtkTreeItem *GTK_TREE_ITEM (gpointer obj)</literal> -</literallayout></para> +<programlisting role="C"> +GtkTreeItem *GTK_TREE_ITEM (gpointer obj) +</programlisting> <para>Cast a generic pointer to "GtkTreeItem *".</para> -<para><literallayout> -<literal>GtkTreeItemClass *GTK_TREE_ITEM_CLASS (gpointer obj)</literal> -</literallayout></para> +<programlisting role="C"> +GtkTreeItemClass *GTK_TREE_ITEM_CLASS (gpointer obj) +</programlisting> <para>Cast a generic pointer to "GtkTreeItemClass".</para> -<para><literallayout> -<literal>gint GTK_IS_TREE_ITEM (gpointer obj)</literal> -</literallayout></para> +<programlisting role="C"> +gint GTK_IS_TREE_ITEM (gpointer obj) +</programlisting> <para>Determine if a generic pointer refers to a "GtkTreeItem" object. </para> -<para><literallayout> -<literal>GtkWidget GTK_TREE_ITEM_SUBTREE (gpointer obj)</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget GTK_TREE_ITEM_SUBTREE (gpointer obj) +</programlisting> <para>Returns a tree item's subtree (<literal>obj</literal> should point to a "GtkTreeItem" object).</para> @@ -10526,9 +10539,9 @@ GtkWidget *gtk_menu_bar_new( void ); gtk_container_add to pack this into a window, or the box_pack functions to pack it into a box - the same as buttons.</para> -<para><literallayout> -<literal>GtkWidget *gtk_menu_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_menu_new( void ); +</programlisting> <para>This function returns a pointer to a new menu; it is never actually shown (with gtk_widget_show), it is just a container for the menu @@ -10538,15 +10551,15 @@ example below.</para> <para>The next two calls are used to create menu items that are packed into the menu (and menubar).</para> -<para><literallayout> -<literal>GtkWidget *gtk_menu_item_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_menu_item_new( void ); +</programlisting> <para>and</para> -<para><literallayout> -<literal>GtkWidget *gtk_menu_item_new_with_label( const char *label );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_menu_item_new_with_label( const char *label ); +</programlisting> <para>These calls are used to create the menu items that are to be displayed. Remember to differentiate between a "menu" as created with @@ -10566,8 +10579,8 @@ the item is selected by the user, we need to connect to the standard <literal>File</literal> menu, with the options <literal>Open</literal>, <literal>Save</literal>, and <literal>Quit</literal>, the code would look something like:</para> -<para><literallayout> -<literal> file_menu = gtk_menu_new (); /* Don't need to show menus */</para> +<programlisting role="C"> + file_menu = gtk_menu_new (); /* Don't need to show menus */</para> <para> /* Create the menu items */ open_item = gtk_menu_item_new_with_label ("Open"); @@ -10595,21 +10608,21 @@ standard <literal>File</literal> menu, with the options <literal>Open</literal>, <para> /* We do need to show menu items */ gtk_widget_show (open_item); gtk_widget_show (save_item); - gtk_widget_show (quit_item);</literal> -</literallayout></para> + gtk_widget_show (quit_item); +</programlisting> <para>At this point we have our menu. Now we need to create a menubar and a menu item for the <literal>File</literal> entry, to which we add our menu. The code looks like this:</para> -<para><literallayout> -<literal> menu_bar = gtk_menu_bar_new (); +<programlisting role="C"> + menu_bar = gtk_menu_bar_new (); gtk_container_add (GTK_CONTAINER (window), menu_bar); gtk_widget_show (menu_bar);</para> <para> file_item = gtk_menu_item_new_with_label ("File"); - gtk_widget_show (file_item);</literal> -</literallayout></para> + gtk_widget_show (file_item); +</programlisting> <para>Now we need to associate the menu with <literal>file_item</literal>. This is done with the function</para> @@ -10621,9 +10634,9 @@ void gtk_menu_item_set_submenu( GtkMenuItem *menu_item, <para>So, our example would continue with</para> -<para><literallayout> -<literal> gtk_menu_item_set_submenu (GTK_MENU_ITEM (file_item), file_menu);</literal> -</literallayout></para> +<programlisting role="C"> + gtk_menu_item_set_submenu (GTK_MENU_ITEM (file_item), file_menu); +</programlisting> <para>All that is left to do is to add the menu to the menubar, which is accomplished using the function</para> @@ -10635,18 +10648,18 @@ void gtk_menu_bar_append( GtkMenuBar *menu_bar, <para>which in our case looks like this:</para> -<para><literallayout> -<literal> gtk_menu_bar_append (GTK_MENU_BAR (menu_bar), file_item);</literal> -</literallayout></para> +<programlisting role="C"> + gtk_menu_bar_append (GTK_MENU_BAR (menu_bar), file_item); +</programlisting> <para>If we wanted the menu right justified on the menubar, such as help menus often are, we can use the following function (again on <literal>file_item</literal> in the current example) before attaching it to the menubar.</para> -<para><literallayout> -<literal>void gtk_menu_item_right_justify( GtkMenuItem *menu_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_menu_item_right_justify( GtkMenuItem *menu_item ); +</programlisting> <para>Here is a summary of the steps needed to create a menu bar with menus attached:</para> @@ -11011,21 +11024,21 @@ respectively.</para> <para>There is only one function for creating a new Text widget.</para> -<para><literallayout> -<literal>GtkWidget *gtk_text_new( GtkAdjustment *hadj, - GtkAdjustment *vadj );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_text_new( GtkAdjustment *hadj, + GtkAdjustment *vadj ); +</programlisting> <para>The arguments allow us to give the Text widget pointers to Adjustments that can be used to track the viewing position of the widget. Passing NULL values to either or both of these arguments will cause the gtk_text_new function to create its own.</para> -<para><literallayout> -<literal>void gtk_text_set_adjustments( GtkText *text, +<programlisting role="C"> +void gtk_text_set_adjustments( GtkText *text, GtkAdjustment *hadj, - GtkAdjustment *vadj );</literal> -</literallayout></para> + GtkAdjustment *vadj ); +</programlisting> <para>The above function allows the horizontal and vertical adjustments of a text widget to be changed at any time.</para> @@ -11035,11 +11048,11 @@ the amount of text to be displayed is too long for the display window. We therefore have to create and add them to the display layout ourselves.</para> -<para><literallayout> -<literal> vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj); +<programlisting role="C"> + vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj); gtk_box_pack_start(GTK_BOX(hbox), vscrollbar, FALSE, FALSE, 0); - gtk_widget_show (vscrollbar);</literal> -</literallayout></para> + gtk_widget_show (vscrollbar); +</programlisting> <para>The above code snippet creates a new vertical scrollbar, and attaches it to the vertical adjustment of the text widget, <literal>text</literal>. It then @@ -11053,10 +11066,10 @@ the user to edit a body of text, or to allow us to display multiple lines of text to the user. In order for us to switch between these modes of operation, the text widget has the following function:</para> -<para><literallayout> -<literal>void gtk_text_set_editable( GtkText *text, - gint editable );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_text_set_editable( GtkText *text, + gint editable ); +</programlisting> <para>The <literal>editable</literal> argument is a TRUE or FALSE value that specifies whether the user is permitted to edit the contents of the Text @@ -11071,10 +11084,10 @@ at any time, and can insert text at any time.</para> single line of the display window. Its default behaviour is to break words across line breaks. This can be changed using the next function:</para> -<para><literallayout> -<literal>void gtk_text_set_word_wrap( GtkText *text, - gint word_wrap );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_text_set_word_wrap( GtkText *text, + gint word_wrap ); +</programlisting> <para>Using this function allows us to specify that the text widget should wrap long lines on word boundaries. The <literal>word_wrap</literal> argument is a @@ -11086,26 +11099,26 @@ TRUE or FALSE value.</para> <sect1>Text Manipulation <P> The current insertion point of a Text widget can be set using</para> -<para><literallayout> -<literal>void gtk_text_set_point( GtkText *text, - guint index );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_text_set_point( GtkText *text, + guint index ); +</programlisting> <para>where <literal>index</literal> is the position to set the insertion point.</para> <para>Analogous to this is the function for getting the current insertion point:</para> -<para><literallayout> -<literal>guint gtk_text_get_point( GtkText *text );</literal> -</literallayout></para> +<programlisting role="C"> +guint gtk_text_get_point( GtkText *text ); +</programlisting> <para>A function that is useful in combination with the above two functions is</para> -<para><literallayout> -<literal>guint gtk_text_get_length( GtkText *text );</literal> -</literallayout></para> +<programlisting role="C"> +guint gtk_text_get_length( GtkText *text ); +</programlisting> <para>which returns the current length of the Text widget. The length is the number of characters that are within the text block of the widget, @@ -11116,14 +11129,14 @@ lines.</para> widget, the function gtk_text_insert is used, which also allows us to specify background and foreground colors and a font for the text.</para> -<para><literallayout> -<literal>void gtk_text_insert( GtkText *text, +<programlisting role="C"> +void gtk_text_insert( GtkText *text, GdkFont *font, GdkColor *fore, GdkColor *back, const char *chars, - gint length );</literal> -</literallayout></para> + gint length ); +</programlisting> <para>Passing a value of <literal>NULL</literal> in as the value for the foreground color, background color or font will result in the values set within the @@ -11143,23 +11156,23 @@ updates are complete.</para> <para>The following two functions perform this freeze and thaw action:</para> -<para><literallayout> -<literal>void gtk_text_freeze( GtkText *text );</para> +<programlisting role="C"> +void gtk_text_freeze( GtkText *text );</para> -<para>void gtk_text_thaw( GtkText *text ); </literal> -</literallayout></para> +<para>void gtk_text_thaw( GtkText *text ); +</programlisting> <para>Text is deleted from the text widget relative to the current insertion point by the following two functions. The return value is a TRUE or FALSE indicator of whether the operation was successful.</para> -<para><literallayout> -<literal>gint gtk_text_backward_delete( GtkText *text, +<programlisting role="C"> +gint gtk_text_backward_delete( GtkText *text, guint nchars );</para> <para>gint gtk_text_forward_delete ( GtkText *text, - guint nchars );</literal> -</literallayout></para> + guint nchars ); +</programlisting> <para>If you want to retrieve the contents of the text widget, then the macro <literal>GTK_TEXT_INDEX(t, index)</literal> allows you to retrieve the @@ -11167,11 +11180,11 @@ character at position <literal>index</literal> within the text widget <literal>t <para>To retrieve larger blocks of text, we can use the function</para> -<para><literallayout> -<literal>gchar *gtk_editable_get_chars( GtkEditable *editable, +<programlisting role="C"> +gchar *gtk_editable_get_chars( GtkEditable *editable, gint start_pos, - gint end_pos ); </literal> -</literallayout></para> + gint end_pos ); +</programlisting> <para>This is a function of the parent class of the text widget. A value of -1 as <literal>end_pos</literal> signifies the end of the text. The index of the @@ -11972,8 +11985,8 @@ used to set style, padding, size, etc.</para> <para>(Maybe I should make a whole section on accelerators.)</para> -<para><literallayout> -<literal>void gtk_widget_install_accelerator( GtkWidget *widget, +<programlisting role="C"> +void gtk_widget_install_accelerator( GtkWidget *widget, GtkAcceleratorTable *table, gchar *signal_name, gchar key, @@ -12012,8 +12025,8 @@ GtkStyle *gtk_widget_get_style( GtkWidget *widget );</para> <para>void gtk_widget_show( GtkWidget *widget );</para> -<para>void gtk_widget_hide( GtkWidget *widget );</literal> -</literallayout></para> +<para>void gtk_widget_hide( GtkWidget *widget ); +</programlisting> </chapter> @@ -12030,11 +12043,11 @@ Well, you have several options. Using the following function you can create a timeout function that will be called every "interval" milliseconds.</para> -<para><literallayout> -<literal>gint gtk_timeout_add( guint32 interval, +<programlisting role="C"> +gint gtk_timeout_add( guint32 interval, GtkFunction function, - gpointer data );</literal> -</literallayout></para> + gpointer data ); +</programlisting> <para>The first argument is the number of milliseconds between calls to your function. The second argument is the function you wish to have called, @@ -12042,9 +12055,9 @@ and the third, the data passed to this callback function. The return value is an integer "tag" which may be used to stop the timeout by calling:</para> -<para><literallayout> -<literal>void gtk_timeout_remove( gint tag );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_timeout_remove( gint tag ); +</programlisting> <para>You may also stop the timeout function by returning zero or FALSE from your callback function. Obviously this means if you want your function @@ -12053,9 +12066,9 @@ i.e., TRUE.</para> <para>The declaration of your callback should look something like this:</para> -<para><literallayout> -<literal>gint timeout_callback( gpointer data );</literal> -</literallayout></para> +<programlisting role="C"> +gint timeout_callback( gpointer data ); +</programlisting> </sect1> @@ -12068,12 +12081,12 @@ ability to have it check for data on a file descriptor for you (as returned by open(2) or socket(2)). This is especially useful for networking applications. The function:</para> -<para><literallayout> -<literal>gint gdk_input_add( gint source, +<programlisting role="C"> +gint gdk_input_add( gint source, GdkInputCondition condition, GdkInputFunction function, - gpointer data );</literal> -</literallayout></para> + gpointer data ); +</programlisting> <para>Where the first argument is the file descriptor you wish to have watched, and the second specifies what you want GDK to look for. This @@ -12096,17 +12109,17 @@ satisfied, and the fourth is the data to pass to this function.</para> <para>The return value is a tag that may be used to stop GDK from monitoring this file descriptor using the following function.</para> -<para><literallayout> -<literal>void gdk_input_remove( gint tag );</literal> -</literallayout></para> +<programlisting role="C"> +void gdk_input_remove( gint tag ); +</programlisting> <para>The callback function should be declared as:</para> -<para><literallayout> -<literal>void input_callback( gpointer data, +<programlisting role="C"> +void input_callback( gpointer data, gint source, - GdkInputCondition condition );</literal> -</literallayout></para> + GdkInputCondition condition ); +</programlisting> <para>Where <literal>source</literal> and <literal>condition</literal> are as specified above.</para> @@ -12120,17 +12133,17 @@ this file descriptor using the following function.</para> What if you have a function which you want to be called when nothing else is happening ?</para> -<para><literallayout> -<literal>gint gtk_idle_add( GtkFunction function, - gpointer data );</literal> -</literallayout></para> +<programlisting role="C"> +gint gtk_idle_add( GtkFunction function, + gpointer data ); +</programlisting> <para>This causes GTK to call the specified function whenever nothing else is happening.</para> -<para><literallayout> -<literal>void gtk_idle_remove( gint tag );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_idle_remove( gint tag ); +</programlisting> <para>I won't explain the meaning of the arguments as they follow very much like the ones above. The function pointed to by the first argument to @@ -12154,8 +12167,8 @@ called.</para> <title>Connecting and Disconnecting Signal Handlers</title> </para> -<para><literallayout> -<literal>guint gtk_signal_connect( GtkObject *object, +<programlisting role="C"> +guint gtk_signal_connect( GtkObject *object, const gchar *name, GtkSignalFunc func, gpointer func_data );</para> @@ -12207,8 +12220,8 @@ called.</para> <para>void gtk_signal_disconnect_by_func( GtkObject *object, GtkSignalFunc func, - gpointer data );</literal> -</literallayout></para> + gpointer data ); +</programlisting> </sect2> @@ -12216,8 +12229,8 @@ called.</para> <sect2> <title>Blocking and Unblocking Signal Handlers</title> -<para><literallayout> -<literal>void gtk_signal_handler_block( GtkObject *object, +<programlisting role="C"> +void gtk_signal_handler_block( GtkObject *object, guint handler_id);</para> <para>void gtk_signal_handler_block_by_func( GtkObject *object, @@ -12235,8 +12248,8 @@ called.</para> gpointer data );</para> <para>void gtk_signal_handler_unblock_by_data( GtkObject *object, - gpointer data );</literal> -</literallayout></para> + gpointer data ); +</programlisting> </sect2> @@ -12244,8 +12257,8 @@ called.</para> <sect2> <title>Emitting and Stopping Signals</title> -<para><literallayout> -<literal>void gtk_signal_emit( GtkObject *object, +<programlisting role="C"> +void gtk_signal_emit( GtkObject *object, guint signal_id, ... );</para> @@ -12271,8 +12284,8 @@ called.</para> guint signal_id );</para> <para>void gtk_signal_emit_stop_by_name( GtkObject *object, - const gchar *name );</literal> -</literallayout></para> + const gchar *name ); +</programlisting> </sect2> </sect1> @@ -12376,8 +12389,8 @@ selections and targets are identified by atoms.</para> <para>Retrieving the selection is an asynchronous process. To start the process, you call:</para> -<para><literallayout> -<literal>gint gtk_selection_convert( GtkWidget *widget, +<programlisting role="C"> +gint gtk_selection_convert( GtkWidget *widget, GdkAtom selection, GdkAtom target, guint32 time ); @@ -12396,8 +12409,8 @@ is not available (for instance, if the conversion was triggered by a for this signal receives a pointer to a <literal>GtkSelectionData</literal> structure, which is defined as:</para> -<para><literallayout> -<literal>struct _GtkSelectionData +<programlisting role="C"> +struct _GtkSelectionData { GdkAtom selection; GdkAtom target; @@ -12405,8 +12418,8 @@ structure, which is defined as:</para> gint format; guchar *data; gint length; -};</literal> -</literallayout></para> +}; +</programlisting> <para><literal>selection</literal> and <literal>target</literal> are the values you gave in your <literal>gtk_selection_convert()</literal> call. <literal>type</literal> is an atom that @@ -12537,12 +12550,12 @@ int main( int argc, handlers that will be called when your selection is requested. For each selection/target pair you will handle, you make a call to:</para> -<para><literallayout> -<literal>void gtk_selection_add_target (GtkWidget *widget, +<programlisting role="C"> +void gtk_selection_add_target (GtkWidget *widget, GdkAtom selection, GdkAtom target, - guint info);</literal> -</literallayout></para> + guint info); +</programlisting> <para><literal>widget</literal>, <literal>selection</literal>, and <literal>target</literal> identify the requests this handler will manage. When a request for a selection is received, @@ -12551,12 +12564,12 @@ enumerator to identify the specific target within the callback function.</para> <para>The callback function has the signature:</para> -<para><literallayout> -<literal>void "selection_get" (GtkWidget *widget, +<programlisting role="C"> +void "selection_get" (GtkWidget *widget, GtkSelectionData *selection_data, guint info, - guint time);</literal> -</literallayout></para> + guint time); +</programlisting> <para>The GtkSelectionData is the same as above, but this time, we're responsible for filling in the fields <literal>type</literal>, <literal>format</literal>, @@ -12566,13 +12579,13 @@ needs to be byte-swapped or not. Usually it will be 8 - <emphasis>i.e.</emphasis character - or 32 - <emphasis>i.e.</emphasis> a. integer.) This is done by calling the function:</para> -<para><literallayout> -<literal>void gtk_selection_data_set( GtkSelectionData *selection_data, +<programlisting role="C"> +void gtk_selection_data_set( GtkSelectionData *selection_data, GdkAtom type, gint format, guchar *data, - gint length );</literal> -</literallayout></para> + gint length ); +</programlisting> <para>This function takes care of properly making a copy of the data so that you don't have to worry about keeping it around. (You should not fill @@ -12581,11 +12594,11 @@ in the fields of the GtkSelectionData structure by hand.)</para> <para>When prompted by the user, you claim ownership of the selection by calling:</para> -<para><literallayout> -<literal>gint gtk_selection_owner_set( GtkWidget *widget, +<programlisting role="C"> +gint gtk_selection_owner_set( GtkWidget *widget, GdkAtom selection, - guint32 time );</literal> -</literallayout></para> + guint32 time ); +</programlisting> <para>If another application claims ownership of the selection, you will receive a "selection_clear_event".</para> @@ -12747,8 +12760,8 @@ not.</para> <para>Definitions for the extremes of many of the standard types are:</para> -<para><literallayout> -<literal>G_MINFLOAT +<programlisting role="C"> +G_MINFLOAT G_MAXFLOAT G_MINDOUBLE G_MAXDOUBLE @@ -12757,16 +12770,16 @@ G_MAXSHORT G_MININT G_MAXINT G_MINLONG -G_MAXLONG</literal> -</literallayout></para> +G_MAXLONG +</programlisting> <para>Also, the following typedefs. The ones left unspecified are dynamically set depending on the architecture. Remember to avoid counting on the size of a pointer if you want to be portable! E.g., a pointer on an Alpha is 8 bytes, but 4 on Intel 80x86 family CPUs.</para> -<para><literallayout> -<literal>char gchar; +<programlisting role="C"> +char gchar; short gshort; long glong; int gint; @@ -12788,8 +12801,8 @@ guint8 gint16 guint16 gint32 -guint32</literal> -</literallayout></para> +guint32 +</programlisting> </sect1> @@ -12818,18 +12831,18 @@ they accept a pointer to the beginning of the list, and return the all of the operations that add or remove elements, be sure to save the returned value!</para> -<para><literallayout> -<literal>GList *g_list_append( GList *list, - gpointer data );</literal> -</literallayout></para> +<programlisting role="C"> +GList *g_list_append( GList *list, + gpointer data ); +</programlisting> <para>This adds a new element (with value <literal>data</literal>) onto the end of the list. <tscreen><verb> GList *g_list_prepend( GList *list, - gpointer data );</literal> -</literallayout></para> + gpointer data ); +</programlisting> <para>This adds a new element (with value <literal>data</literal>) to the beginning of the list.</para> @@ -12845,17 +12858,17 @@ GList *g_list_insert( GList *list, given position. If position is 0, this is just like g_list_prepend(); if position is less than 0, this is just like g_list_append().</para> -<para><literallayout> -<literal>GList *g_list_remove( GList *list, - gpointer data );</literal> -</literallayout></para> +<programlisting role="C"> +GList *g_list_remove( GList *list, + gpointer data ); +</programlisting> <para>This removes the element in the list with the value <literal>data</literal>; if the element isn't there, the list is unchanged.</para> -<para><literallayout> -<literal>void g_list_free( GList *list );</literal> -</literallayout></para> +<programlisting role="C"> +void g_list_free( GList *list ); +</programlisting> <para>This frees all of the memory used by a GList. If the list elements refer to dynamically-allocated memory, then they should be freed @@ -12898,8 +12911,8 @@ GList *g_list_find( GList *list, <para>Many of the above functions for singly linked lists are identical to the above. Here is a list of some of their operations:</para> -<para><literallayout> -<literal>GSList *g_slist_append( GSList *list, +<programlisting role="C"> +GSList *g_slist_append( GSList *list, gpointer data ); GSList *g_slist_prepend( GSList *list, @@ -12930,8 +12943,8 @@ GSList *g_slist_last( GSList *list );</para> <para>void g_slist_foreach( GSList *list, GFunc func, gpointer user_data ); - </literal> -</literallayout></para> + +</programlisting> </sect1> @@ -12939,44 +12952,44 @@ GSList *g_slist_last( GSList *list );</para> <sect1> <title>Memory Management</title> -<para><literallayout> -<literal>gpointer g_malloc( gulong size );</literal> -</literallayout></para> +<programlisting role="C"> +gpointer g_malloc( gulong size ); +</programlisting> <para>This is a replacement for malloc(). You do not need to check the return value as it is done for you in this function. If the memory allocation fails for whatever reasons, your applications will be terminated.</para> -<para><literallayout> -<literal>gpointer g_malloc0( gulong size );</literal> -</literallayout></para> +<programlisting role="C"> +gpointer g_malloc0( gulong size ); +</programlisting> <para>Same as above, but zeroes the memory before returning a pointer to it.</para> -<para><literallayout> -<literal>gpointer g_realloc( gpointer mem, - gulong size );</literal> -</literallayout></para> +<programlisting role="C"> +gpointer g_realloc( gpointer mem, + gulong size ); +</programlisting> <para>Relocates "size" bytes of memory starting at "mem". Obviously, the memory should have been previously allocated.</para> -<para><literallayout> -<literal>void g_free( gpointer mem );</literal> -</literallayout></para> +<programlisting role="C"> +void g_free( gpointer mem ); +</programlisting> <para>Frees memory. Easy one. If <literal>mem</literal> is NULL it simply returns.</para> -<para><literallayout> -<literal>void g_mem_profile( void );</literal> -</literallayout></para> +<programlisting role="C"> +void g_mem_profile( void ); +</programlisting> <para>Dumps a profile of used memory, but requires that you add <literal>#define MEM_PROFILE</literal> to the top of glib/gmem.c and re-make and make install.</para> -<para><literallayout> -<literal>void g_mem_check( gpointer mem );</literal> -</literallayout></para> +<programlisting role="C"> +void g_mem_check( gpointer mem ); +</programlisting> <para>Checks that a memory location is valid. Requires you add <literal>#define MEM_CHECK</literal> to the top of gmem.c and re-make and make install.</para> @@ -12993,8 +13006,8 @@ You can then use g_timer_start() to start timing an operation, g_timer_stop() to stop timing an operation, and g_timer_elapsed() to determine the elapsed time.</para> -<para><literallayout> -<literal>GTimer *g_timer_new( void );</para> +<programlisting role="C"> +GTimer *g_timer_new( void );</para> <para>void g_timer_destroy( GTimer *timer );</para> @@ -13021,20 +13034,20 @@ overflow programming errors within your program. This is a very important feature, and hence I recommend that you make use of GStrings. GString itself has a simple public definition:</para> -<para><literallayout> -<literal>struct GString +<programlisting role="C"> +struct GString { gchar *str; /* Points to the string's current \0-terminated value. */ gint len; /* Current length */ -};</literal> -</literallayout></para> +}; +</programlisting> <para>As you might expect, there are a number of operations you can do with a GString.</para> -<para><literallayout> -<literal>GString *g_string_new( gchar *init );</literal> -</literallayout></para> +<programlisting role="C"> +GString *g_string_new( gchar *init ); +</programlisting> <para>This constructs a GString, copying the string value of <literal>init</literal> into the GString and returning a pointer to it. NULL may be given as @@ -13043,17 +13056,17 @@ the argument for an initially empty GString. <tscreen><verb></para> <para>void g_string_free( GString *string, - gint free_segment );</literal> -</literallayout></para> + gint free_segment ); +</programlisting> <para>This frees the memory for the given GString. If <literal>free_segment</literal> is TRUE, then this also frees its character data.</para> -<para><literallayout> -<literal> +<programlisting role="C"> + GString *g_string_assign( GString *lval, - const gchar *rval );</literal> -</literallayout></para> + const gchar *rval ); +</programlisting> <para>This copies the characters from rval into lval, destroying the previous contents of lval. Note that lval will be lengthened as @@ -13095,62 +13108,62 @@ void g_string_sprintfa ( GString *string, <sect1> <title>Utility and Error Functions</title> -<para><literallayout> -<literal>gchar *g_strdup( const gchar *str );</literal> -</literallayout></para> +<programlisting role="C"> +gchar *g_strdup( const gchar *str ); +</programlisting> <para>Replacement strdup function. Copies the original strings contents to newly allocated memory, and returns a pointer to it.</para> -<para><literallayout> -<literal>gchar *g_strerror( gint errnum );</literal> -</literallayout></para> +<programlisting role="C"> +gchar *g_strerror( gint errnum ); +</programlisting> <para>I recommend using this for all error messages. It's much nicer, and more portable than perror() or others. The output is usually of the form:</para> -<para><literallayout> -<literal>program name:function that failed:file or further description:strerror</literal> -</literallayout></para> +<programlisting role="C"> +program name:function that failed:file or further description:strerror +</programlisting> <para>Here's an example of one such call used in our hello_world program:</para> -<para><literallayout> -<literal>g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno));</literal> -</literallayout></para> +<programlisting role="C"> +g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno)); +</programlisting> -<para><literallayout> -<literal>void g_error( gchar *format, ... );</literal> -</literallayout></para> +<programlisting role="C"> +void g_error( gchar *format, ... ); +</programlisting> <para>Prints an error message. The format is just like printf, but it prepends "** ERROR **: " to your message, and exits the program. Use only for fatal errors.</para> -<para><literallayout> -<literal>void g_warning( gchar *format, ... );</literal> -</literallayout></para> +<programlisting role="C"> +void g_warning( gchar *format, ... ); +</programlisting> <para>Same as above, but prepends "** WARNING **: ", and does not exit the program.</para> -<para><literallayout> -<literal>void g_message( gchar *format, ... );</literal> -</literallayout></para> +<programlisting role="C"> +void g_message( gchar *format, ... ); +</programlisting> <para>Prints "message: " prepended to the string you pass in.</para> -<para><literallayout> -<literal>void g_print( gchar *format, ... );</literal> -</literallayout></para> +<programlisting role="C"> +void g_print( gchar *format, ... ); +</programlisting> <para>Replacement for printf().</para> <para>And our last function:</para> -<para><literallayout> -<literal>gchar *g_strsignal( gint signum );</literal> -</literallayout></para> +<programlisting role="C"> +gchar *g_strsignal( gint signum ); +</programlisting> <para>Prints out the name of the Unix system signal given the signal number. Useful in generic signal handling functions.</para> @@ -13175,9 +13188,9 @@ can also be used to tile pixmaps onto the background of some widgets. </para> <para>When your application starts, you should include a call to:</para> -<para><literallayout> -<literal>void gtk_rc_parse( char *filename );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_rc_parse( char *filename ); +</programlisting> <para>Passing in the filename of your rc file. This will cause GTK to parse this file, and use the style settings for the widget types defined @@ -13187,10 +13200,10 @@ there.</para> different style from others, or any other logical division of widgets, use a call to:</para> -<para><literallayout> -<literal>void gtk_widget_set_name( GtkWidget *widget, - gchar *name );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_widget_set_name( GtkWidget *widget, + gchar *name ); +</programlisting> <para>Passing your newly created widget as the first argument, and the name you wish to give it as the second. This will allow you to change the @@ -13198,10 +13211,10 @@ attributes of this widget by name through the rc file.</para> <para>If we use a call something like this:</para> -<para><literallayout> -<literal>button = gtk_button_new_with_label ("Special Button"); -gtk_widget_set_name (button, "special button");</literal> -</literallayout></para> +<programlisting role="C"> +button = gtk_button_new_with_label ("Special Button"); +gtk_widget_set_name (button, "special button"); +</programlisting> <para>Then this button is given the name "special button" and may be addressed by name in the rc file as "special button.GtkButton". [<--- Verify ME!]</para> @@ -13210,16 +13223,16 @@ name in the rc file as "special button.GtkButton". [<--- Verify ME!]</para> all children of that main window inherit the style described by the "main button" style. The code used in the application is:</para> -<para><literallayout> -<literal>window = gtk_window_new (GTK_WINDOW_TOPLEVEL); -gtk_widget_set_name (window, "main window");</literal> -</literallayout></para> +<programlisting role="C"> +window = gtk_window_new (GTK_WINDOW_TOPLEVEL); +gtk_widget_set_name (window, "main window"); +</programlisting> <para>And then the style is defined in the rc file using:</para> -<para><literallayout> -<literal>widget "main window.*GtkButton*" style "main_button"</literal> -</literallayout></para> +<programlisting role="C"> +widget "main window.*GtkButton*" style "main_button" +</programlisting> <para>Which sets all the Button widgets in the "main window" to the "main_buttons" style as defined in the rc file.</para> @@ -13274,9 +13287,9 @@ activated, it will take these attributes.</simpara> <para>When using the "fg" and "bg" keywords to set the colors of widgets, the format is:</para> -<para><literallayout> -<literal>fg[<STATE>] = { Red, Green, Blue }</literal> -</literallayout></para> +<programlisting role="C"> +fg[<STATE>] = { Red, Green, Blue } +</programlisting> <para>Where STATE is one of the above states (PRELIGHT, ACTIVE, etc), and the Red, Green and Blue are values in the range of 0 - 1.0, { 1.0, 1.0, 1.0 } being @@ -13291,9 +13304,9 @@ filename.</para> searched for any pixmap you specify.</para> <para>The font directive is simply:</para> -<para><literallayout> -<literal>font = "<font name>"</literal> -</literallayout></para> +<programlisting role="C"> +font = "<font name>" +</programlisting> <para>The only hard part is figuring out the font string. Using xfontsel or a similar utility should help.</para> @@ -13315,13 +13328,13 @@ the attributes of its parent in the application.</para> <para>When defining a style, you may assign the attributes of a previously defined style to this new one.</para> -<para><literallayout> -<literal>style "main_button" = "button" +<programlisting role="C"> +style "main_button" = "button" { font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*" bg[PRELIGHT] = { 0.75, 0, 0 } -}</literal> -</literallayout></para> +} +</programlisting> <para>This example takes the "button" style, and creates a new "main_button" style simply by changing the font and prelight background color of the "button" @@ -13336,8 +13349,8 @@ simple matter of common sense really. Anything that could apply, should.</para> <sect1> <title>Example rc file</title> -<para><literallayout> -<literal># pixmap_path "<dir 1>:<dir 2>:<dir 3>:..." +<programlisting role="C"> +# pixmap_path "<dir 1>:<dir 2>:<dir 3>:..." # pixmap_path "/usr/include/X11R6/pixmaps:/home/imain/pixmaps" # @@ -13461,8 +13474,8 @@ widget_class "*GtkText" style "text"</para> <para># This sets all the buttons that are children of the "main window" to # the main_button style. These must be documented to be taken advantage of. -widget "main window.*GtkButton*" style "main_button"</literal> -</literallayout></para> +widget "main window.*GtkButton*" style "main_button" +</programlisting> </sect1> </chapter> @@ -13518,8 +13531,8 @@ first field in the class structure must be a copy of the parent's class structure. The declaration of the class structure of GtkButtton looks like:</para> -<para><literallayout> -<literal>struct _GtkButtonClass +<programlisting role="C"> +struct _GtkButtonClass { GtkContainerClass parent_class;</para> @@ -13528,8 +13541,8 @@ looks like:</para> void (* clicked) (GtkButton *button); void (* enter) (GtkButton *button); void (* leave) (GtkButton *button); -};</literal> -</literallayout></para> +}; +</programlisting> <para>When a button is treated as a container (for instance, when it is resized), its class structure can be cast to GtkContainerClass, and @@ -13541,8 +13554,8 @@ is different for each instance of the widget. We'll call this structure the <emphasis>object structure</emphasis>. For the Button class, it looks like:</para> -<para><literallayout> -<literal>struct _GtkButton +<programlisting role="C"> +struct _GtkButton { GtkContainer container;</para> @@ -13550,8 +13563,8 @@ like:</para> <para> guint in_button : 1; guint button_down : 1; -};</literal> -</literallayout></para> +}; +</programlisting> <para>Note that, similar to the class structure, the first field is the object structure of the parent class, so that this structure can be @@ -13614,8 +13627,8 @@ class structures for that widget, along with public functions. A couple of features are worth pointing out. To prevent duplicate definitions, we wrap the entire header file in:</para> -<para><literallayout> -<literal>#ifndef __TICTACTOE_H__ +<programlisting role="C"> +#ifndef __TICTACTOE_H__ #define __TICTACTOE_H__ . . @@ -13625,8 +13638,8 @@ definitions, we wrap the entire header file in:</para> <para>And to keep C++ programs that include the header file happy, in:</para> -<para><literallayout> -<literal>#ifdef __cplusplus +<programlisting role="C"> +#ifdef __cplusplus extern "C" { #endif /* __cplusplus */ . @@ -13703,8 +13716,8 @@ function for every widget is the function GTK about the widget class, and gets an ID that uniquely identifies the widget class. Upon subsequent calls, it just returns the ID.</para> -<para><literallayout> -<literal>guint +<programlisting role="C"> +guint tictactoe_get_type () { static guint ttt_type = 0;</para> @@ -13726,13 +13739,13 @@ tictactoe_get_type () }</para> <para> return ttt_type; -}</literal> -</literallayout></para> +} +</programlisting> <para>The GtkTypeInfo structure has the following definition:</para> -<para><literallayout> -<literal>struct _GtkTypeInfo +<programlisting role="C"> +struct _GtkTypeInfo { gchar *type_name; guint object_size; @@ -13741,8 +13754,8 @@ tictactoe_get_type () GtkObjectInitFunc object_init_func; GtkArgSetFunc arg_set_func; GtkArgGetFunc arg_get_func; -};</literal> -</literallayout></para> +}; +</programlisting> <para>The fields of this structure are pretty self-explanatory. We'll ignore the <literal>arg_set_func</literal> and <literal>arg_get_func</literal> fields here: they have an important, @@ -13787,8 +13800,8 @@ tictactoe_class_init (TictactoeClass *class) gtk_object_class_add_signals (object_class, tictactoe_signals, LAST_SIGNAL);</para> <para> class->tictactoe = NULL; -}</literal> -</literallayout></para> +} +</programlisting> <para>Our widget has just one signal, the <literal>tictactoe</literal> signal that is invoked when a row, column, or diagonal is completely filled in. Not @@ -13798,16 +13811,16 @@ things are going to get a bit complicated.</para> <para>The function:</para> -<para><literallayout> -<literal>gint gtk_signal_new( const gchar *name, +<programlisting role="C"> +gint gtk_signal_new( const gchar *name, GtkSignalRunType run_type, GtkType object_type, gint function_offset, GtkSignalMarshaller marshaller, GtkType return_val, guint nparams, - ...);</literal> -</literallayout></para> + ...); +</programlisting> <para>Creates a new signal. The parameters are:</para> @@ -13840,8 +13853,8 @@ pre-supplied marshaller function <literal>gtk_signal_default_marshaller</literal <para>When specifying types, the <literal>GtkType</literal> enumeration is used:</para> -<para><literallayout> -<literal>typedef enum +<programlisting role="C"> +typedef enum { GTK_TYPE_INVALID, GTK_TYPE_NONE, @@ -13869,8 +13882,8 @@ pre-supplied marshaller function <literal>gtk_signal_default_marshaller</literal <para> GTK_TYPE_OBJECT</para> -<para>} GtkFundamentalType;</literal> -</literallayout></para> +<para>} GtkFundamentalType; +</programlisting> <para><literal>gtk_signal_new()</literal> returns a unique integer identifier for the signal, that we store in the <literal>tictactoe_signals</literal> array, which we @@ -13895,8 +13908,8 @@ structure. Usually, this function has the fairly limited role of setting the fields of the structure to default values. For composite widgets, however, this function also creates the component widgets.</para> -<para><literallayout> -<literal>static void +<programlisting role="C"> +static void tictactoe_init (Tictactoe *ttt) { GtkWidget *table; @@ -13917,8 +13930,8 @@ tictactoe_init (Tictactoe *ttt) gtk_widget_set_usize (ttt->buttons[i][j], 20, 20); gtk_widget_show (ttt->buttons[i][j]); } -}</literal> -</literallayout></para> +} +</programlisting> </sect2> @@ -14000,13 +14013,13 @@ tictactoe_toggle (GtkWidget *widget, Tictactoe *ttt) break; } } -}</literal> -</literallayout></para> +} +</programlisting> <para>And finally, an example program using our Tictactoe widget:</para> -<para><literallayout> -<literal>#include <gtk/gtk.h> +<programlisting role="C"> +#include <gtk/gtk.h> #include "tictactoe.h"</para> <para>/* Invoked when a row, column or diagonal is completed */ @@ -14253,8 +14266,8 @@ are pretty similar.</para> we have some functions to provide information about the widget and initialize it:</para> -<para><literallayout> -<literal>#include <math.h> +<programlisting role="C"> +#include <math.h> #include <stdio.h> #include <gtk/gtkmain.h> #include <gtk/gtksignal.h></para> @@ -14363,8 +14376,8 @@ gtk_dial_destroy (GtkObject *object) <para> if (GTK_OBJECT_CLASS (parent_class)->destroy) (* GTK_OBJECT_CLASS (parent_class)->destroy) (object); -}</literal> -</literallayout></para> +} +</programlisting> <para>Note that this <literal>init()</literal> function does less than for the Tictactoe widget, since this is not a composite widget, and the <literal>new()</literal> @@ -14376,8 +14389,8 @@ use it) so that GTK can keep track of when it can be safely destroyed.</para> <para> <para>Also, there are a few function to manipulate the widget's options:</para> -<para><literallayout> -<literal>GtkAdjustment* +<programlisting role="C"> +GtkAdjustment* gtk_dial_get_adjustment (GtkDial *dial) { g_return_val_if_fail (dial != NULL, NULL); @@ -14424,8 +14437,8 @@ gtk_dial_set_adjustment (GtkDial *dial, dial->old_upper = adjustment->upper;</para> <para> gtk_dial_update (dial); -}</literal> -</literallayout></para> +} +</programlisting> <para><sect2> <literal>gtk_dial_realize()</literal></para> @@ -14446,8 +14459,8 @@ pointer to the widget in the user data field of the GdkWindow. This last step allows GTK to dispatch events for this window to the correct widget.</para> -<para><literallayout> -<literal>static void +<programlisting role="C"> +static void gtk_dial_realize (GtkWidget *widget) { GtkDial *dial; @@ -14481,8 +14494,8 @@ gtk_dial_realize (GtkWidget *widget) <para> gdk_window_set_user_data (widget->window, widget);</para> <para> gtk_style_set_background (widget->style, widget->window, GTK_STATE_ACTIVE); -}</literal> -</literallayout></para> +} +</programlisting> <para><sect2> <title> Size negotiation</title> @@ -14495,15 +14508,15 @@ function <literal>gtk_dial_size_request()</literal>. Since our widget isn't a container widget, and has no real constraints on its size, we just return a reasonable default value.</para> -<para><literallayout> -<literal>static void +<programlisting role="C"> +static void gtk_dial_size_request (GtkWidget *widget, GtkRequisition *requisition) { requisition->width = DIAL_DEFAULT_SIZE; requisition->height = DIAL_DEFAULT_SIZE; -}</literal> -</literallayout></para> +} +</programlisting> <para> <para>After all the widgets have requested an ideal size, the layout of the @@ -14516,8 +14529,8 @@ as well as computing the sizes of some component pieces for future use, this routine also does the grunt work of moving the widget's X window into the new position and size.</para> -<para><literallayout> -<literal>static void +<programlisting role="C"> +static void gtk_dial_size_allocate (GtkWidget *widget, GtkAllocation *allocation) { @@ -14554,8 +14567,8 @@ the use of the function <literal>gtk_draw_polygon</literal> to draw the pointer three dimensional shading according to the colors stored in the widget's style.</para> -<para><literallayout> -<literal>static gint +<programlisting role="C"> +static gint gtk_dial_expose (GtkWidget *widget, GdkEventExpose *event) { @@ -14623,8 +14636,8 @@ gtk_dial_expose (GtkWidget *widget, TRUE); return FALSE; -}</literal> -</literallayout></para> +} +</programlisting> </sect2> @@ -14651,8 +14664,8 @@ set, "value_changed" events are either generated instantly <literal>gtk_timeout_add()</literal> (<literal>GTK_UPDATE_DELAYED</literal>), or only when the button is released (<literal>GTK_UPDATE_DISCONTINUOUS</literal>).</para> -<para><literallayout> -<literal>static gint +<programlisting role="C"> +static gint gtk_dial_button_press (GtkWidget *widget, GdkEventButton *event) { @@ -14830,8 +14843,8 @@ gtk_dial_update_mouse (GtkDial *dial, gint x, gint y) } } } -}</literal> -</literallayout></para> +} +</programlisting> <para>Changes to the Adjustment by external means are communicated to our widget by the "changed" and "value_changed" signals. The handlers @@ -14839,8 +14852,8 @@ for these functions call <literal>gtk_dial_update()</literal> to validate the arguments, compute the new pointer angle, and redraw the widget (by calling <literal>gtk_widget_draw()</literal>).</para> -<para><literallayout> -<literal>static void +<programlisting role="C"> +static void gtk_dial_update (GtkDial *dial) { gfloat new_value; @@ -14908,8 +14921,8 @@ gtk_dial_adjustment_value_changed (GtkAdjustment *adjustment, <para> dial->old_value = adjustment->value; } -}</literal> -</literallayout></para> +} +</programlisting> </sect2> @@ -15001,8 +15014,8 @@ information about the event. For instance, motion event handlers are passed a pointer to a GdkEventMotion structure which looks (in part) like:</para> -<para><literallayout> -<literal>struct _GdkEventMotion +<programlisting role="C"> +struct _GdkEventMotion { GdkEventType type; GdkWindow *window; @@ -15012,8 +15025,8 @@ like:</para> ... guint state; ... -};</literal> -</literallayout></para> +}; +</programlisting> <para><literal>type</literal> will be set to the event type, in this case <literal>GDK_MOTION_NOTIFY</literal>, window is the window in which the event @@ -15022,8 +15035,8 @@ occurred. <literal>x</literal> and <literal>y</literal> give the coordinates of occurred (that is, it specifies which modifier keys and mouse buttons were pressed). It is the bitwise OR of some of the following:</para> -<para><literallayout> -<literal>GDK_SHIFT_MASK +<programlisting role="C"> +GDK_SHIFT_MASK GDK_LOCK_MASK GDK_CONTROL_MASK GDK_MOD1_MASK @@ -15035,25 +15048,25 @@ GDK_BUTTON1_MASK GDK_BUTTON2_MASK GDK_BUTTON3_MASK GDK_BUTTON4_MASK -GDK_BUTTON5_MASK</literal> -</literallayout></para> +GDK_BUTTON5_MASK +</programlisting> <para>As for other signals, to determine what happens when an event occurs we call <literal>gtk_signal_connect()</literal>. But we also need let GTK know which events we want to be notified about. To do this, we call the function:</para> -<para><literallayout> -<literal>void gtk_widget_set_events (GtkWidget *widget, - gint events);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_widget_set_events (GtkWidget *widget, + gint events); +</programlisting> <para>The second field specifies the events we are interested in. It is the bitwise OR of constants that specify different types of events. For future reference the event types are:</para> -<para><literallayout> -<literal>GDK_EXPOSURE_MASK +<programlisting role="C"> +GDK_EXPOSURE_MASK GDK_POINTER_MOTION_MASK GDK_POINTER_MOTION_HINT_MASK GDK_BUTTON_MOTION_MASK @@ -15070,8 +15083,8 @@ GDK_FOCUS_CHANGE_MASK GDK_STRUCTURE_MASK GDK_PROPERTY_CHANGE_MASK GDK_PROXIMITY_IN_MASK -GDK_PROXIMITY_OUT_MASK </literal> -</literallayout></para> +GDK_PROXIMITY_OUT_MASK +</programlisting> <para>There are a few subtle points that have to be observed when calling <literal>gtk_widget_set_events()</literal>. First, it must be called before the X window @@ -15081,8 +15094,8 @@ widget must have an associated X window. For efficiency, many widget types do not have their own window, but draw in their parent's window. These widgets are:</para> -<para><literallayout> -<literal>GtkAlignment +<programlisting role="C"> +GtkAlignment GtkArrow GtkBin GtkBox @@ -15098,8 +15111,8 @@ GtkFrame GtkVBox GtkHBox GtkVSeparator -GtkHSeparator</literal> -</literallayout></para> +GtkHSeparator +</programlisting> <para>To capture events for these widgets, you need to use an EventBox widget. See the section on the <link linkend="ch-EventBox">EventBox</link> widget for details.</para> @@ -15130,12 +15143,12 @@ our window, or after a button press or release event. Subsequent motion events will be suppressed until we explicitly ask for the position of the pointer using the function:</para> -<para><literallayout> -<literal>GdkWindow* gdk_window_get_pointer (GdkWindow *window, +<programlisting role="C"> +GdkWindow* gdk_window_get_pointer (GdkWindow *window, gint *x, gint *y, - GdkModifierType *mask);</literal> -</literallayout></para> + GdkModifierType *mask); +</programlisting> <para>(There is another function, <literal>gtk_widget_get_pointer()</literal> which has a simpler interface, but turns out not to be very useful, since @@ -15144,8 +15157,8 @@ are pressed.)</para> <para>The code to set the events for our window then looks like:</para> -<para><literallayout> -<literal> gtk_signal_connect (GTK_OBJECT (drawing_area), "expose_event", +<programlisting role="C"> + gtk_signal_connect (GTK_OBJECT (drawing_area), "expose_event", (GtkSignalFunc) expose_event, NULL); gtk_signal_connect (GTK_OBJECT(drawing_area),"configure_event", (GtkSignalFunc) configure_event, NULL); @@ -15158,15 +15171,15 @@ are pressed.)</para> | GDK_LEAVE_NOTIFY_MASK | GDK_BUTTON_PRESS_MASK | GDK_POINTER_MOTION_MASK - | GDK_POINTER_MOTION_HINT_MASK);</literal> -</literallayout></para> + | GDK_POINTER_MOTION_HINT_MASK); +</programlisting> <para>We'll save the "expose_event" and "configure_event" handlers for later. The "motion_notify_event" and "button_press_event" handlers are pretty simple:</para> -<para><literallayout> -<literal>static gint +<programlisting role="C"> +static gint button_press_event (GtkWidget *widget, GdkEventButton *event) { if (event->button == 1 && pixmap != NULL) @@ -15194,8 +15207,8 @@ motion_notify_event (GtkWidget *widget, GdkEventMotion *event) draw_brush (widget, x, y); return TRUE; -}</literal> -</literallayout></para> +} +</programlisting> </sect1> @@ -15209,17 +15222,17 @@ widget is essentially an X window and nothing more. It is a blank canvas in which we can draw whatever we like. A drawing area is created using the call:</para> -<para><literallayout> -<literal>GtkWidget* gtk_drawing_area_new (void);</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget* gtk_drawing_area_new (void); +</programlisting> <para>A default size for the widget can be specified by calling:</para> -<para><literallayout> -<literal>void gtk_drawing_area_size (GtkDrawingArea *darea, +<programlisting role="C"> +void gtk_drawing_area_size (GtkDrawingArea *darea, gint width, - gint height);</literal> -</literallayout></para> + gint height); +</programlisting> <para>This default size can be overridden, as is true for all widgets, by calling <literal>gtk_widget_set_usize()</literal>, and that, in turn, can @@ -15243,12 +15256,12 @@ relevant portions onto the screen.</para> <para>To create an offscreen pixmap, we call the function:</para> -<para><literallayout> -<literal>GdkPixmap* gdk_pixmap_new (GdkWindow *window, +<programlisting role="C"> +GdkPixmap* gdk_pixmap_new (GdkWindow *window, gint width, gint height, - gint depth);</literal> -</literallayout></para> + gint depth); +</programlisting> <para>The <literal>window</literal> parameter specifies a GDK window that this pixmap takes some of its properties from. <literal>width</literal> and <literal>height</literal> @@ -15284,8 +15297,8 @@ configure_event (GtkWidget *widget, GdkEventConfigure *event) widget->allocation.height);</para> <para> return TRUE; -}</literal> -</literallayout></para> +} +</programlisting> <para>The call to <literal>gdk_draw_rectangle()</literal> clears the pixmap initially to white. We'll say more about that in a moment.</para> @@ -15307,8 +15320,8 @@ expose_event (GtkWidget *widget, GdkEventExpose *event) event->area.width, event->area.height);</para> <para> return FALSE; -}</literal> -</literallayout></para> +} +</programlisting> <para>We've now seen how to keep the screen up to date with our pixmap, but how do we actually draw interesting stuff on our pixmap? There are a @@ -15319,8 +15332,8 @@ image). We've already seen two such calls above, <literal>gdk_draw_rectangle()</literal> and <literal>gdk_draw_pixmap()</literal>. The complete list is:</para> -<para><literallayout> -<literal>gdk_draw_line () +<programlisting role="C"> +gdk_draw_line () gdk_draw_rectangle () gdk_draw_arc () gdk_draw_polygon () @@ -15330,8 +15343,8 @@ gdk_draw_pixmap () gdk_draw_bitmap () gdk_draw_image () gdk_draw_points () -gdk_draw_segments ()</literal> -</literallayout></para> +gdk_draw_segments () +</programlisting> <para>See the reference documentation or the header file <literal><gdk/gdk.h></literal> for further details on these functions. @@ -15348,24 +15361,24 @@ the section GTK's rc file.) This, among other things, stores a number of graphics contexts. Some examples of accessing these graphics contexts are:</para> -<para><literallayout> -<literal>widget->style->white_gc +<programlisting role="C"> +widget->style->white_gc widget->style->black_gc widget->style->fg_gc[GTK_STATE_NORMAL] -widget->style->bg_gc[GTK_WIDGET_STATE(widget)]</literal> -</literallayout></para> +widget->style->bg_gc[GTK_WIDGET_STATE(widget)] +</programlisting> <para>The fields <literal>fg_gc</literal>, <literal>bg_gc</literal>, <literal>dark_gc</literal>, and <literal>light_gc</literal> are indexed by a parameter of type <literal>GtkStateType</literal> which can take on the values:</para> -<para><literallayout> -<literal>GTK_STATE_NORMAL, +<programlisting role="C"> +GTK_STATE_NORMAL, GTK_STATE_ACTIVE, GTK_STATE_PRELIGHT, GTK_STATE_SELECTED, -GTK_STATE_INSENSITIVE</literal> -</literallayout></para> +GTK_STATE_INSENSITIVE +</programlisting> <para>For instance, for <literal>GTK_STATE_SELECTED</literal> the default foreground color is white and the default background color, dark blue.</para> @@ -15390,16 +15403,16 @@ draw_brush (GtkWidget *widget, gdouble x, gdouble y) update_rect.x, update_rect.y, update_rect.width, update_rect.height); gtk_widget_draw (widget, &update_rect); -}</literal> -</literallayout></para> +} +</programlisting> <para>After we draw the rectangle representing the brush onto the pixmap, we call the function:</para> -<para><literallayout> -<literal>void gtk_widget_draw (GtkWidget *widget, - GdkRectangle *area);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_widget_draw (GtkWidget *widget, + GdkRectangle *area); +</programlisting> <para>which notifies X that the area given by the <literal>area</literal> parameter needs to be updated. X will eventually generate an expose event @@ -15441,8 +15454,8 @@ url="http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html"> XInput-HOWTO structure, we see that it has fields to support extended device information.</para> -<para><literallayout> -<literal>struct _GdkEventMotion +<programlisting role="C"> +struct _GdkEventMotion { GdkEventType type; GdkWindow *window; @@ -15456,8 +15469,8 @@ information.</para> gint16 is_hint; GdkInputSource source; guint32 deviceid; -};</literal> -</literallayout></para> +}; +</programlisting> <para><literal>pressure</literal> gives the pressure as a floating point number between 0 and 1. <literal>xtilt</literal> and <literal>ytilt</literal> can take on values between @@ -15467,12 +15480,12 @@ event occurred in two different ways. <literal>source</literal> gives some simpl information about the type of device. It can take the enumeration values:</para> -<para><literallayout> -<literal>GDK_SOURCE_MOUSE +<programlisting role="C"> +GDK_SOURCE_MOUSE GDK_SOURCE_PEN GDK_SOURCE_ERASER -GDK_SOURCE_CURSOR</literal> -</literallayout></para> +GDK_SOURCE_CURSOR +</programlisting> <para><literal>deviceid</literal> specifies a unique numeric ID for the device. This can be used to find out further information about the device using the @@ -15486,9 +15499,9 @@ the mouse.)</para> <para>To let GTK know about our interest in the extended device information, we merely have to add a single line to our program:</para> -<para><literallayout> -<literal>gtk_widget_set_extension_events (drawing_area, GDK_EXTENSION_EVENTS_CURSOR);</literal> -</literallayout></para> +<programlisting role="C"> +gtk_widget_set_extension_events (drawing_area, GDK_EXTENSION_EVENTS_CURSOR); +</programlisting> <para>By giving the value <literal>GDK_EXTENSION_EVENTS_CURSOR</literal> we say that we are interested in extension events, but only if we don't have @@ -15506,8 +15519,8 @@ the InputDialog widget to automate this process. The following procedure manages an InputDialog widget. It creates the dialog if it isn't present, and raises it to the top otherwise.</para> -<para><literallayout> -<literal>void +<programlisting role="C"> +void input_dialog_destroy (GtkWidget *w, gpointer data) { *((GtkWidget **)data) = NULL; @@ -15539,8 +15552,8 @@ create_input_dialog () else gdk_window_raise(inputd->window); } -}</literal> -</literallayout></para> +} +</programlisting> <para>(You might want to take note of the way we handle this dialog. By connecting to the "destroy" signal, we make sure that we don't keep a @@ -15567,16 +15580,16 @@ events are not enabled.</para> <literal>gdk_window_get_pointer</literal> doesn't return the extended device information.</para> -<para><literallayout> -<literal>void gdk_input_window_get_pointer( GdkWindow *window, +<programlisting role="C"> +void gdk_input_window_get_pointer( GdkWindow *window, guint32 deviceid, gdouble *x, gdouble *y, gdouble *pressure, gdouble *xtilt, gdouble *ytilt, - GdkModifierType *mask);</literal> -</literallayout></para> + GdkModifierType *mask); +</programlisting> <para>When calling this function, we need to specify the device ID as well as the window. Usually, we'll get the device ID from the @@ -15589,8 +15602,8 @@ enabled. (In this case, <literal>event->deviceid</literal> will have the value doesn't change much - we just need to add code to deal with the extended information.</para> -<para><literallayout> -<literal>static gint +<programlisting role="C"> +static gint button_press_event (GtkWidget *widget, GdkEventButton *event) { print_button_press (event->deviceid); @@ -15623,8 +15636,8 @@ motion_notify_event (GtkWidget *widget, GdkEventMotion *event) draw_brush (widget, event->source, x, y, pressure); return TRUE; -}</literal> -</literallayout></para> +} +</programlisting> <para>We also need to do something with the new information. Our new <literal>draw_brush()</literal> function draws with a different color for @@ -15664,8 +15677,8 @@ draw_brush (GtkWidget *widget, GdkInputSource source, update_rect.x, update_rect.y, update_rect.width, update_rect.height); gtk_widget_draw (widget, &update_rect); -}</literal> -</literallayout></para> +} +</programlisting> <para><sect2> <title> Finding out more about a device</title> @@ -15674,16 +15687,16 @@ draw_brush (GtkWidget *widget, GdkInputSource source, will print the name of the device that generates each button press. To find out the name of a device, we call the function:</para> -<para><literallayout> -<literal>GList *gdk_input_list_devices (void);</literal> -</literallayout></para> +<programlisting role="C"> +GList *gdk_input_list_devices (void); +</programlisting> <para>which returns a GList (a linked list type from the GLib library) of GdkDeviceInfo structures. The GdkDeviceInfo structure is defined as:</para> -<para><literallayout> -<literal>struct _GdkDeviceInfo +<programlisting role="C"> +struct _GdkDeviceInfo { guint32 deviceid; gchar *name; @@ -15694,8 +15707,8 @@ as:</para> GdkAxisUse *axes; gint num_keys; GdkDeviceKey *keys; -};</literal> -</literallayout></para> +}; +</programlisting> <para>Most of these fields are configuration information that you can ignore unless you are implementing XInput configuration saving. The fieldwe @@ -15709,8 +15722,8 @@ we need to draw our own cursor. But since we've specified the returned list until it finds a match, then prints out the name of the device.</para> -<para><literallayout> -<literal>static void +<programlisting role="C"> +static void print_button_press (guint32 deviceid) { GList *tmp_list;</para> @@ -15731,8 +15744,8 @@ print_button_press (guint32 deviceid) <para> tmp_list = tmp_list->next; } -}</literal> -</literallayout></para> +} +</programlisting> <para>That completes the changes to "XInputize" our program.</para> @@ -15749,13 +15762,13 @@ file.</para> <para>To restore the state next time the program is run, GDK provides functions to change device configuration:</para> -<para><literallayout> -<literal>gdk_input_set_extension_events() +<programlisting role="C"> +gdk_input_set_extension_events() gdk_input_set_source() gdk_input_set_mode() gdk_input_set_axes() -gdk_input_set_key()</literal> -</literallayout></para> +gdk_input_set_key() +</programlisting> <para>(The list returned from <literal>gdk_input_list_devices()</literal> should not be modified directly.) An example of doing this can be found in the @@ -15955,10 +15968,10 @@ using the signals listed in this section.</para> <sect1> <title>GtkObject</title> -<para><literallayout> -<literal>void GtkObject::destroy (GtkObject *, - gpointer);</literal> -</literallayout></para> +<programlisting role="C"> +void GtkObject::destroy (GtkObject *, + gpointer); +</programlisting> </sect1> @@ -16138,8 +16151,8 @@ gboolean GtkWidget::visibility-notify-event (GtkWidget *, gpointer); void GtkWidget::debug-msg (GtkWidget *, GtkString *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> </sect1> @@ -16147,17 +16160,17 @@ void GtkWidget::debug-msg (GtkWidget *, <sect1> <title>GtkData</title> -<para><literallayout> -<literal>void GtkData::disconnect (GtkData *, - gpointer);</literal> -</literallayout></para> +<programlisting role="C"> +void GtkData::disconnect (GtkData *, + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkContainer</title> -<para><literallayout> -<literal>void GtkContainer::add (GtkContainer *, +<programlisting role="C"> +void GtkContainer::add (GtkContainer *, GtkWidget *, gpointer); void GtkContainer::remove (GtkContainer *, @@ -16170,15 +16183,15 @@ GtkDirectionType GtkContainer::focus (GtkContainer *, gpointer); void GtkContainer::set-focus-child (GtkContainer *, GtkWidget *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkCalendar</title> -<para><literallayout> -<literal>void GtkCalendar::month-changed (GtkCalendar *, +<programlisting role="C"> +void GtkCalendar::month-changed (GtkCalendar *, gpointer); void GtkCalendar::day-selected (GtkCalendar *, gpointer); @@ -16191,15 +16204,15 @@ void GtkCalendar::next-month (GtkCalendar *, void GtkCalendar::prev-year (GtkCalendar *, gpointer); void GtkCalendar::next-year (GtkCalendar *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkEditable</title> -<para><literallayout> -<literal>void GtkEditable::changed (GtkEditable *, +<programlisting role="C"> +void GtkEditable::changed (GtkEditable *, gpointer); void GtkEditable::insert-text (GtkEditable *, GtkString *, @@ -16246,15 +16259,15 @@ void GtkEditable::cut-clipboard (GtkEditable *, void GtkEditable::copy-clipboard (GtkEditable *, gpointer); void GtkEditable::paste-clipboard (GtkEditable *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkTipsQuery</title> -<para><literallayout> -<literal>void GtkTipsQuery::start-query (GtkTipsQuery *, +<programlisting role="C"> +void GtkTipsQuery::start-query (GtkTipsQuery *, gpointer); void GtkTipsQuery::stop-query (GtkTipsQuery *, gpointer); @@ -16268,15 +16281,15 @@ gboolean GtkTipsQuery::widget-selected (GtkTipsQuery *, GtkString *, GtkString *, GdkEvent *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkCList</title> -<para><literallayout> -<literal>void GtkCList::select-row (GtkCList *, +<programlisting role="C"> +void GtkCList::select-row (GtkCList *, ggint, ggint, GdkEvent *, @@ -16325,15 +16338,15 @@ void GtkCList::scroll-horizontal (GtkCList *, ggfloat, gpointer); void GtkCList::abort-column-resize (GtkCList *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkNotebook</title> -<para><literallayout> -<literal>void GtkNotebook::switch-page (GtkNotebook *, +<programlisting role="C"> +void GtkNotebook::switch-page (GtkNotebook *, ggpointer, gguint, gpointer);</para> @@ -16344,23 +16357,23 @@ void GtkCList::abort-column-resize (GtkCList *, <sect1> <title>GtkList</title> -<para><literallayout> -<literal>void GtkList::selection-changed (GtkList *, +<programlisting role="C"> +void GtkList::selection-changed (GtkList *, gpointer); void GtkList::select-child (GtkList *, GtkWidget *, gpointer); void GtkList::unselect-child (GtkList *, GtkWidget *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkMenuShell</title> -<para><literallayout> -<literal>void GtkMenuShell::deactivate (GtkMenuShell *, +<programlisting role="C"> +void GtkMenuShell::deactivate (GtkMenuShell *, gpointer); void GtkMenuShell::selection-done (GtkMenuShell *, gpointer); @@ -16371,43 +16384,43 @@ void GtkMenuShell::activate-current (GtkMenuShell *, gboolean, gpointer); void GtkMenuShell::cancel (GtkMenuShell *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkToolbar</title> -<para><literallayout> -<literal>void GtkToolbar::orientation-changed (GtkToolbar *, +<programlisting role="C"> +void GtkToolbar::orientation-changed (GtkToolbar *, ggint, gpointer); void GtkToolbar::style-changed (GtkToolbar *, ggint, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkTree</title> -<para><literallayout> -<literal>void GtkTree::selection-changed (GtkTree *, +<programlisting role="C"> +void GtkTree::selection-changed (GtkTree *, gpointer); void GtkTree::select-child (GtkTree *, GtkWidget *, gpointer); void GtkTree::unselect-child (GtkTree *, GtkWidget *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkButton</title> -<para><literallayout> -<literal>void GtkButton::pressed (GtkButton *, +<programlisting role="C"> +void GtkButton::pressed (GtkButton *, gpointer); void GtkButton::released (GtkButton *, gpointer); @@ -16416,51 +16429,51 @@ void GtkButton::clicked (GtkButton *, void GtkButton::enter (GtkButton *, gpointer); void GtkButton::leave (GtkButton *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkItem</title> -<para><literallayout> -<literal>void GtkItem::select (GtkItem *, +<programlisting role="C"> +void GtkItem::select (GtkItem *, gpointer); void GtkItem::deselect (GtkItem *, gpointer); void GtkItem::toggle (GtkItem *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkWindow</title> -<para><literallayout> -<literal>void GtkWindow::set-focus (GtkWindow *, +<programlisting role="C"> +void GtkWindow::set-focus (GtkWindow *, ggpointer, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkHandleBox</title> -<para><literallayout> -<literal>void GtkHandleBox::child-attached (GtkHandleBox *, +<programlisting role="C"> +void GtkHandleBox::child-attached (GtkHandleBox *, GtkWidget *, gpointer); void GtkHandleBox::child-detached (GtkHandleBox *, GtkWidget *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkToggleButton</title> -<para><literallayout> -<literal>void GtkToggleButton::toggled (GtkToggleButton *, +<programlisting role="C"> +void GtkToggleButton::toggled (GtkToggleButton *, gpointer);</para> <para></verb></tscreen></para> @@ -16469,19 +16482,19 @@ void GtkHandleBox::child-detached (GtkHandleBox *, <sect1> <title>GtkMenuItem</title> -<para><literallayout> -<literal>void GtkMenuItem::activate (GtkMenuItem *, +<programlisting role="C"> +void GtkMenuItem::activate (GtkMenuItem *, gpointer); void GtkMenuItem::activate-item (GtkMenuItem *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkListItem</title> -<para><literallayout> -<literal>void GtkListItem::toggle-focus-row (GtkListItem *, +<programlisting role="C"> +void GtkListItem::toggle-focus-row (GtkListItem *, gpointer); void GtkListItem::select-all (GtkListItem *, gpointer); @@ -16507,72 +16520,72 @@ void GtkListItem::scroll-vertical (GtkListItem *, void GtkListItem::scroll-horizontal (GtkListItem *, GtkEnum, ggfloat, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkTreeItem</title> -<para><literallayout> -<literal>void GtkTreeItem::collapse (GtkTreeItem *, +<programlisting role="C"> +void GtkTreeItem::collapse (GtkTreeItem *, gpointer); void GtkTreeItem::expand (GtkTreeItem *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkCheckMenuItem</title> -<para><literallayout> -<literal>void GtkCheckMenuItem::toggled (GtkCheckMenuItem *, - gpointer);</literal> -</literallayout></para> +<programlisting role="C"> +void GtkCheckMenuItem::toggled (GtkCheckMenuItem *, + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkInputDialog</title> -<para><literallayout> -<literal>void GtkInputDialog::enable-device (GtkInputDialog *, +<programlisting role="C"> +void GtkInputDialog::enable-device (GtkInputDialog *, ggint, gpointer); void GtkInputDialog::disable-device (GtkInputDialog *, ggint, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkColorSelection</title> -<para><literallayout> -<literal>void GtkColorSelection::color-changed (GtkColorSelection *, - gpointer);</literal> -</literallayout></para> +<programlisting role="C"> +void GtkColorSelection::color-changed (GtkColorSelection *, + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkStatusBar</title> -<para><literallayout> -<literal>void GtkStatusbar::text-pushed (GtkStatusbar *, +<programlisting role="C"> +void GtkStatusbar::text-pushed (GtkStatusbar *, gguint, GtkString *, gpointer); void GtkStatusbar::text-popped (GtkStatusbar *, gguint, GtkString *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkCTree</title> -<para><literallayout> -<literal>void GtkCTree::tree-select-row (GtkCTree *, +<programlisting role="C"> +void GtkCTree::tree-select-row (GtkCTree *, GtkCTreeNode *, ggint, gpointer); @@ -16593,28 +16606,28 @@ void GtkCTree::tree-move (GtkCTree *, gpointer); void GtkCTree::change-focus-row-expansion (GtkCTree *, GtkCTreeExpansionType, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkCurve</title> -<para><literallayout> -<literal>void GtkCurve::curve-type-changed (GtkCurve *, - gpointer);</literal> -</literallayout></para> +<programlisting role="C"> +void GtkCurve::curve-type-changed (GtkCurve *, + gpointer); +</programlisting> <!-- ----------------------------------------------------------------- --> <sect1> <title>GtkAdjustment -<para><literallayout> -<literal>void GtkAdjustment::changed (GtkAdjustment *, +<programlisting role="C"> +void GtkAdjustment::changed (GtkAdjustment *, gpointer); void GtkAdjustment::value-changed (GtkAdjustment *, - gpointer);</literal> -</literallayout></para> + gpointer); +</programlisting> </chapter> @@ -16797,8 +16810,8 @@ to the signal handler. As you will see below, each of the event data structures has a member of this type. It is defined as an enumeration type as follows:</para> -<para><literallayout> -<literal>typedef enum +<programlisting role="C"> +typedef enum { GDK_NOTHING = -1, GDK_DELETE = 0, @@ -16832,8 +16845,8 @@ type as follows:</para> GDK_VISIBILITY_NOTIFY = 28, GDK_NO_EXPOSE = 29, GDK_OTHER_EVENT = 9999 /* Deprecated, use filters instead */ -} GdkEventType;</literal> -</literallayout></para> +} GdkEventType; +</programlisting> <para>The other event type that is different from the others is <literal>GdkEvent</literal> itself. This is a union of all the other @@ -16843,8 +16856,8 @@ event data type within a signal handler.</para> <para><!-- Just a big list for now, needs expanding upon - TRG --> So, the event data types are defined as follows:</para> -<para><literallayout> -<literal>struct _GdkEventAny +<programlisting role="C"> +struct _GdkEventAny { GdkEventType type; GdkWindow *window; @@ -17100,8 +17113,8 @@ So, the event data types are defined as follows:</para> GdkWindow *window; gint8 send_event; GdkXEvent *xevent; -};</literal> -</literallayout></para> +}; +</programlisting> </chapter> @@ -18190,8 +18203,8 @@ gtk_dial_adjustment_value_changed (GtkAdjustment *adjustment, <sect2> <title> dial_test.c</title> -<para><literallayout> -<literal>#include <stdio.h> +<programlisting role="C"> +#include <stdio.h> #include <gtk/gtk.h> #include "gtkdial.h" @@ -18757,15 +18770,15 @@ to it full extent.</para> <para>There is one field inside the structure definition of the List widget that will be of greater interest to us, this is:</para> -<para><literallayout> -<literal>struct _GtkList +<programlisting role="C"> +struct _GtkList { ... GList *selection; guint selection_mode; ... -}; </literal> -</literallayout></para> +}; +</programlisting> <para>The selection field of a List points to a linked list of all items that are currently selected, or NULL if the selection is empty. So to @@ -18806,18 +18819,18 @@ field. The selection_mode may be one of the following:</para> <sect1> <title>Signals</title> -<para><literallayout> -<literal>void selection_changed( GtkList *list );</literal> -</literallayout></para> +<programlisting role="C"> +void selection_changed( GtkList *list ); +</programlisting> <para>This signal will be invoked whenever the selection field of a List has changed. This happens when a child of thekList got selected or deselected.</para> -<para><literallayout> -<literal>void select_child( GtkList *list, - GtkWidget *child);</literal> -</literallayout></para> +<programlisting role="C"> +void select_child( GtkList *list, + GtkWidget *child); +</programlisting> <para>This signal is invoked when a child of the List is about to get selected. This happens mainly on calls to gtk_list_select_item(), @@ -18825,10 +18838,10 @@ gtk_list_select_child(), button presses and sometimes indirectly triggered on some else occasions where children get added to or removed from the List.</para> -<para><literallayout> -<literal>void unselect_child( GtkList *list, - GtkWidget *child );</literal> -</literallayout></para> +<programlisting role="C"> +void unselect_child( GtkList *list, + GtkWidget *child ); +</programlisting> <para>This signal is invoked when a child of the List is about to get deselected. This happens mainly on calls to gtk_list_unselect_item(), @@ -18842,51 +18855,51 @@ removed from the List.</para> <sect1> <title> Functions</title> -<para><literallayout> -<literal>guint gtk_list_get_type( void );</literal> -</literallayout></para> +<programlisting role="C"> +guint gtk_list_get_type( void ); +</programlisting> <para>Returns the "GtkList" type identifier.</para> -<para><literallayout> -<literal>GtkWidget *gtk_list_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_list_new( void ); +</programlisting> <para>Create a new List object. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.</para> -<para><literallayout> -<literal>void gtk_list_insert_items( GtkList *list, +<programlisting role="C"> +void gtk_list_insert_items( GtkList *list, GList *items, - gint position );</literal> -</literallayout></para> + gint position ); +</programlisting> <para>Insert list items into the list, starting at <literal>position</literal>. <literal>items</literal> is a doubly linked list where each nodes data pointer is expected to point to a newly created ListItem. The GList nodes of <literal>items</literal> are taken over by the list.</para> -<para><literallayout> -<literal>void gtk_list_append_items( GtkList *list, - GList *items);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_append_items( GtkList *list, + GList *items); +</programlisting> <para>Insert list items just like gtk_list_insert_items() at the end of the list. The GList nodes of <literal>items</literal> are taken over by the list.</para> -<para><literallayout> -<literal>void gtk_list_prepend_items( GtkList *list, - GList *items);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_prepend_items( GtkList *list, + GList *items); +</programlisting> <para>Insert list items just like gtk_list_insert_items() at the very beginning of the list. The GList nodes of <literal>items</literal> are taken over by the list.</para> -<para><literallayout> -<literal>void gtk_list_remove_items( GtkList *list, - GList *items);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_remove_items( GtkList *list, + GList *items); +</programlisting> <para>Remove list items from the list. <literal>items</literal> is a doubly linked list where each nodes data pointer is expected to point to a direct child @@ -18894,78 +18907,78 @@ of list. It is the callers responsibility to make a call to g_list_free(items) afterwards. Also the caller has to destroy the list items himself.</para> -<para><literallayout> -<literal>void gtk_list_clear_items( GtkList *list, +<programlisting role="C"> +void gtk_list_clear_items( GtkList *list, gint start, - gint end );</literal> -</literallayout></para> + gint end ); +</programlisting> <para>Remove and destroy list items from the list. A widget is affected if its current position within the list is in the range specified by <literal>start</literal> and <literal>end</literal>.</para> -<para><literallayout> -<literal>void gtk_list_select_item( GtkList *list, - gint item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_select_item( GtkList *list, + gint item ); +</programlisting> <para>Invoke the select_child signal for a list item specified through its current position within the list.</para> -<para><literallayout> -<literal>void gtk_list_unselect_item( GtkList *list, - gint item);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_unselect_item( GtkList *list, + gint item); +</programlisting> <para>Invoke the unselect_child signal for a list item specified through its current position within the list.</para> -<para><literallayout> -<literal>void gtk_list_select_child( GtkList *list, - GtkWidget *child);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_select_child( GtkList *list, + GtkWidget *child); +</programlisting> <para>Invoke the select_child signal for the specified child.</para> -<para><literallayout> -<literal>void gtk_list_unselect_child( GtkList *list, - GtkWidget *child);</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_unselect_child( GtkList *list, + GtkWidget *child); +</programlisting> <para>Invoke the unselect_child signal for the specified child.</para> -<para><literallayout> -<literal>gint gtk_list_child_position( GtkList *list, - GtkWidget *child);</literal> -</literallayout></para> +<programlisting role="C"> +gint gtk_list_child_position( GtkList *list, + GtkWidget *child); +</programlisting> <para>Return the position of <literal>child</literal> within the list. "-1" is returned on failure.</para> -<para><literallayout> -<literal>void gtk_list_set_selection_mode( GtkList *list, - GtkSelectionMode mode );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_set_selection_mode( GtkList *list, + GtkSelectionMode mode ); +</programlisting> <para>Set the selection mode MODE which can be of GTK_SELECTION_SINGLE, GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE or GTK_SELECTION_EXTENDED.</para> -<para><literallayout> -<literal>GtkList *GTK_LIST( gpointer obj );</literal> -</literallayout></para> +<programlisting role="C"> +GtkList *GTK_LIST( gpointer obj ); +</programlisting> <para>Cast a generic pointer to "GtkList *".</para> -<para><literallayout> -<literal>GtkListClass *GTK_LIST_CLASS( gpointer class);</literal> -</literallayout></para> +<programlisting role="C"> +GtkListClass *GTK_LIST_CLASS( gpointer class); +</programlisting> <para>Cast a generic pointer to "GtkListClass *". </para> -<para><literallayout> -<literal>gint GTK_IS_LIST( gpointer obj);</literal> -</literallayout></para> +<programlisting role="C"> +gint GTK_IS_LIST( gpointer obj); +</programlisting> <para>Determine if a generic pointer refers to a "GtkList" object.</para> @@ -19296,59 +19309,59 @@ the signals of a Item.</para> <sect1> <title> Functions</title> -<para><literallayout> -<literal>guint gtk_list_item_get_type( void );</literal> -</literallayout></para> +<programlisting role="C"> +guint gtk_list_item_get_type( void ); +</programlisting> <para>Returns the "GtkListItem" type identifier.</para> -<para><literallayout> -<literal>GtkWidget *gtk_list_item_new( void );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_list_item_new( void ); +</programlisting> <para>Create a new ListItem object. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.</para> -<para><literallayout> -<literal>GtkWidget *gtk_list_item_new_with_label( gchar *label );</literal> -</literallayout></para> +<programlisting role="C"> +GtkWidget *gtk_list_item_new_with_label( gchar *label ); +</programlisting> <para>Create a new ListItem object, having a single GtkLabel as the sole child. The new widget is returned as a pointer to a GtkWidget object. NULL is returned on failure.</para> -<para><literallayout> -<literal>void gtk_list_item_select( GtkListItem *list_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_item_select( GtkListItem *list_item ); +</programlisting> <para>This function is basically a wrapper around a call to gtk_item_select (GTK_ITEM (list_item)) which will emit the select signal. *Note GtkItem::, for more info.</para> -<para><literallayout> -<literal>void gtk_list_item_deselect( GtkListItem *list_item );</literal> -</literallayout></para> +<programlisting role="C"> +void gtk_list_item_deselect( GtkListItem *list_item ); +</programlisting> <para>This function is basically a wrapper around a call to gtk_item_deselect (GTK_ITEM (list_item)) which will emit the deselect signal. *Note GtkItem::, for more info.</para> -<para><literallayout> -<literal>GtkListItem *GTK_LIST_ITEM( gpointer obj );</literal> -</literallayout></para> +<programlisting role="C"> +GtkListItem *GTK_LIST_ITEM( gpointer obj ); +</programlisting> <para>Cast a generic pointer to "GtkListItem *".</para> -<para><literallayout> -<literal>GtkListItemClass *GTK_LIST_ITEM_CLASS( gpointer class );</literal> -</literallayout></para> +<programlisting role="C"> +GtkListItemClass *GTK_LIST_ITEM_CLASS( gpointer class ); +</programlisting> <para>Cast a generic pointer to GtkListItemClass*. *Note Standard Macros::, for more info.</para> -<para><literallayout> -<literal>gint GTK_IS_LIST_ITEM( gpointer obj );</literal> -</literallayout></para> +<programlisting role="C"> +gint GTK_IS_LIST_ITEM( gpointer obj ); +</programlisting> <para>Determine if a generic pointer refers to a `GtkListItem' object. *Note Standard Macros::, for more info. @@ -19361,4 +19374,4 @@ for more info.</para> ListItem as well.</para> </sect1> - </chapter>
\ No newline at end of file + </chapter> |