9. Miscellaneous Widgets

9.1 Labels

Labels are used a lot in GTK, and are relatively simple. Labels emit no signals as they do not have an associated X window. If you need to catch signals, or do clipping, place it inside a EventBox widget or a Button widget. To create a new label, use:

The sole argument is the string you wish the label to display. To change the label's text after creation, use the function:

The first argument is the label you created previously (cast using the GTK_LABEL() macro), and the second is the new string. The space needed for the new string will be automatically adjusted if needed. You can produce multi-line labels by putting line breaks in the label string.

To retrieve the current string, use:

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 used internally by GTK. The label text can be justified using:

Values for j_type are:

The label widget is also capable of line wrapping the text automatically. This can be activated using:

The wrap argument takes a TRUE or FALSE value. If you want your label underlined, then you can set a pattern on the label:

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 '__ __' would underline the first two characters and eight and ninth characters.

Below is a short example to illustrate these functions. This example makes use of the Frame widget to better demonstrate the label styles. You can ignore this aspect of the program for now as the Frame widget is explained later on.

9.2 Arrows

The Arrow widget draws an arrowhead, facing in a number of possible directions and having a number of possible styles. It can be very useful when placed on a button in many applications. Like the Label widget, it emits no signals. There are only two functions for manipulating an Arrow widget:

The first creates a new arrow widget with the indicated type and appearance. The second allows these values to be altered retrospectively. The arrow_type argument may take one of the following values:

These values obviously indicate the direction in which the arrow will point. The shadow_type argument may take one of these values:

* the default

Here's a brief example to illustrate their use.

9.3 The Tooltips Object

These are the little text strings that pop up when you leave your pointer over a button or other widget for a few seconds. They are easy to use, so I will just explain them without giving an example. If you want to see some code, take a look at the the example in the 10.11 Toolbar section.

Widgets that don't receive events (widgets that don't have their own window) won't work with tooltips.

The first call you will use creates a new tooltip. You only need to do this once for a set of tooltips as the GtkTooltips object this function returns can be used to create multiple tooltips.

Once you have created a new tooltip, and the widget you wish to use it on, simply use this call to set it:

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 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 NIL. Here's a short example:

There are other calls that can be used with tooltips. I will just list them with a brief description of what they do.

- enable a disabled set of tooltips.

- disable an enabled set of tooltips.

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

- set the foreground and background colour of the tooltips.

And that's all the functions associated with tooltips. More than you'll ever want to know :-)

9.4 Progress bars

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 lets start out with the calls to create a new progress bar.

There are two ways to create a progress bar, one simple one that takes 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.

The second method has the advantage that we can use the Adjustment object to specify our own range parameters for the progress bar. The adjustment of a progress object can be changed dynamically using:

Now that the progress bar has been created we can use it.

The first argument is the progress bar you wish to operate on, and the second argument is the amount completed, meaning the amount the progress bar has been filled from 0-100%. This is passed to the procedure as a real number ranging from 0 to 1.

GTK v1.2 has added new functionality to the progress bar that enables it to display its value in different ways, and to inform the user of its current value and its range.

A progress bar may be set to one of a number of orientations using the procedure:

The orientation argument may take one of the following values to indicate the direction in which the progress bar moves:

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 or discrete mode. In continuous mode, the progress bar is updated for each value. In discrete mode, the progress bar is updated in a number of discrete blocks. The number of blocks is also configurable.

The style of a progress bar can be set using the following procedure:

The style parameter can take one of two values:

The number of discrete blocks can be set by calling

As well as indicating the amount of progress that has occured, the progress bar may be set to just indicate that there is some activity. This can be useful in situations where progress cannot be measured against a value range. Activity mode is not affected by the bar style that is described above, it overrides it. This mode is either TRUE or FALSE, and is selected by the following procedure.

The step size of the activity indicator, and the number of blocks are set using the following procedures:

When in continuous mode, the progress bar can also display a configurable text string within its trough, using the following procedure.

The format argument is similiar to one that would be used in a C printf statement. The following directives may be used within the format string:

The displaying of this text string can be toggled using:

The show_text argument is a boolean TRUE/FALSE value. The appearance of the text can be modified further using:

The x_align and y_align arguments take values between 0.0 and 1.0. Their values indicate the position of the text string within the trough. Values of 0.0 for both would place the string in the top left hand corner; values of 0.5 (the default) centres the text, and values of 1.0 place the text in the lower right-hand corner.

The current text setting of a progress object can be retrieved using the current or a specified adjustment value using the following two functions. The character string returned by these functions should be freed by the application (using the g_free() function). These functions return the formatted string that would be displayed within the trough.

There is yet another way to change the range and value of a progress object using the following procedure:

This procedure provides quite a simple interface to the range and value of a progress object. The remaining two procedures and three functions can be used to get and set the current value of a progess object in various types and formats:

These functions/procedures are pretty self explanatory. The last function uses the the adjustment of the specified progess object to compute the percentage value of the given range value.

Progress Bars are usually used with timeouts or other such functions (see section on Timeouts, IO and Idle Functions) to give the illusion of multitasking. All will employ the gtk_progress_bar_update() procedure in the same manner.

Here is an example of the progress bar, updated using timeouts. This code also shows you how to reset the Progress Bar.

9.5 Dialogs

The Dialog widget is very simple, and is actually just a window with a few things pre-packed into it for you. The structure of a Dialog is:

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 action_area.

The Dialog widget can be used for pop-up messages to the user, and other similar tasks. It is really basic, and there is only one function for the dialog box, which is:

So to create a new dialog box, use,

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:

And you could add to the vbox area by packing, for instance, a label in it, try something like this:

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 vbox area, asking the user a question or giving an error etc. Then you could attach a different signal to each of the buttons and perform the operation the user selects.

If the simple functionality provided by the default vertical and horizontal boxes in the two areas doesn't give you enough control for your application, then you can simply pack another layout widget into the boxes provided. For example, you could pack a table into the vertical box.

9.6 Pixmaps

Pixmaps are data structures that contain pictures. These pictures can be used in various places, but most commonly as icons on the X desktop, or as cursors.

A pixmap which only has two colors is called a bitmap, and there are a few additional routines for handling this common special case.

To understand pixmaps, it would help to understand how X window system works. Under X, applications do not need to be running on the same computer that is interacting with the user. Instead, the various applications, called clients, all communicate with a program which displays the graphics and handles the keyboard and mouse. This program which interacts directly with the user is called a display server or X server. Since the communication might take place over a network, it's important to keep some information with the X server. Pixmaps, for example, are stored in the memory of the X server. This means that once pixmap values are set, they don't need to keep getting transmitted over the network; instead a command is sent to display pixmap number XYZ here. Even if you aren't using X with GTK currently, using constructs such as Pixmaps will make your programs work acceptably under X.

To use pixmaps in GTK, we must first build a GdkPixmap structure using 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.

This routine is used to create a single-plane pixmap (two colors) from data in memory. Each bit of the data represents whether that pixel is 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.

This is used to create a pixmap of the given depth (number of colours) from the bitmap data specified. fg and bg are the foreground and background colour to use.

The XPM format is a readable pixmap representation for the X Window System. It is widely used and many different utilities are available for creating image files in this format. The file specified by filename must contain an image in that format and it is loaded into the pixmap structure. The mask specifies which bits of the pixmap are opaque. All other bits are coloured using the colour specified by transparent_colour. An example using this follows below.

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 from a file. An example of such data is

You should see the resemblence between the above and the image it produces on this button:

This is the pixmap button produced by the example program that follows shortly.

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 gdk_pixmap_unref(). Pixmaps should be considered a precious resource, because they take up memory in the end-user's X server process. Even though the X client you write may run on a powerful server computer, the user may be running the X server on a small personal computer.

Once we've created a pixmap, we can display it as a GTK widget. We must create a GTK pixmap widget to contain the GDK pixmap. This is done using

The other pixmap widget calls are

gtk_pixmap_set() is used to change the pixmap that the widget is currently managing. val is the pixmap created using GDK.

The following is an example of using a pixmap in a button.

To load a file from an XPM data file called icon0.xpm in the current directory, we would have created the pixmap thus

A disadvantage of using pixmaps is that the displayed object is always rectangular, regardless of the image. We would like to create desktops and applications with icons that have more natural shapes. For example, for a game interface, we would like to have round buttons to push. The way to do this is using shaped windows.

A shaped window is simply a pixmap where the background pixels are transparent. This way, when the background image is multi-coloured, we don't overwrite it with a rectangular, non-matching border around our icon. The following example displays a full wheelbarrow image on the desktop. This is what it looks like on a white desktop:

        ('48 48 64 1',
        '       c None',
        '.      c #DF7DCF3CC71B',
        'X      c #965875D669A6',
        'o      c #71C671C671C6',
        'O      c #A699A289A699',
        '+      c #965892489658',
        '@      c #8E38410330C2',
        '#      c #D75C7DF769A6',
        '$      c #F7DECF3CC71B',
        '%      c #96588A288E38',
        '&      c #A69992489E79',
        '*      c #8E3886178E38',
        '=      c #104008200820',
        '-      c #596510401040',
        ';      c #C71B30C230C2',
        ':      c #C71B9A699658',
        '>      c #618561856185',
        ',      c #20811C712081',
        '<      c #104000000000',
        '1      c #861720812081',
        '2      c #DF7D4D344103',
        '3      c #79E769A671C6',
        '4      c #861782078617',
        '5      c #41033CF34103',
        '6      c #000000000000',
        '7      c #49241C711040',
        '8      c #492445144924',
        '9      c #082008200820',
        '0      c #69A618611861',
        'q      c #B6DA71C65144',
        'w      c #410330C238E3',
        'e      c #CF3CBAEAB6DA',
        'r      c #71C6451430C2',
        't      c #EFBEDB6CD75C',
        'y      c #28A208200820',
        'u      c #186110401040',
        'i      c #596528A21861',
        'p      c #71C661855965',
        'a      c #A69996589658',
        's      c #30C228A230C2',
        'd      c #BEFBA289AEBA',
        'f      c #596545145144',
        'g      c #30C230C230C2',
        'h      c #8E3882078617',
        'j      c #208118612081',
        'k      c #38E30C300820',
        'l      c #30C2208128A2',
        'z      c #38E328A238E3',
        'x      c #514438E34924',
        'c      c #618555555965',
        'v      c #30C2208130C2',
        'b      c #38E328A230C2',
        'n      c #28A228A228A2',
        'm      c #41032CB228A2',
        'M      c #104010401040',
        'N      c #492438E34103',
        'B      c #28A2208128A2',
        'V      c #A699596538E3',
        'C      c #30C21C711040',
        'Z      c #30C218611040',
        'A      c #965865955965',
        'S      c #618534D32081',
        'D      c #38E31C711040',
        'F      c #082000000820',
        '                                                ',
        '          .XoO                                  ',
        '         +@#$%o&                                ',
        '         *=-;#::o+                              ',
        '           >,<12#:34                            ',
        '             45671#:X3                          ',
        '               +89<02qwo                        ',
        'e*                >,67;ro                       ',
        'ty>                 459@>+&&                    ',
        '$2u+                  ><ipas8*                  ',
        '%$;=*                *3:.Xa.dfg>                ',
        'Oh$;ya             *3d.a8j,Xe.d3g8+             ',
        ' Oh$;ka          *3d$a8lz,,xxc:.e3g54           ',
        '  Oh$;kO       *pd$%svbzz,sxxxxfX..&wn>         ',
        '   Oh$@mO    *3dthwlsslszjzxxxxxxx3:td8M4       ',
        '    Oh$@g& *3d$XNlvvvlllm,mNwxxxxxxxfa.:,B*     ',
        '     Oh$@,Od.czlllllzlmmqV@V#V@fxxxxxxxf:%j5&   ',
        '      Oh$1hd5lllslllCCZrV#r#:#2AxxxxxxxxxcdwM*  ',
        '       OXq6c.%8vvvllZZiqqApA:mq:Xxcpcxxxxxfdc9* ',
        '        2r<6gde3bllZZrVi7S@SV77A::qApxxxxxxfdcM ',
        '        :,q-6MN.dfmZZrrSS:#riirDSAX@Af5xxxxxfevo',
        '         +A26jguXtAZZZC7iDiCCrVVii7Cmmmxxxxxx%3g',
        '          *#16jszN..3DZZZZrCVSA2rZrV7Dmmwxxxx&en',
        '           p2yFvzssXe:fCZZCiiD7iiZDiDSSZwwxx8e*>',
        '           OA1<jzxwwc:$d%NDZZZZCCCZCCZZCmxxfd.B ',
        '            3206Bwxxszx%et.eaAp77m77mmmf3&eeeg* ',
        '             @26MvzxNzvlbwfpdettttttttttt.c,n&  ',
        '             *;16=lsNwwNwgsvslbwwvccc3pcfu<o    ',
        '              p;<69BvwwsszslllbBlllllllu<5+     ',
        '              OS0y6FBlvvvzvzss,u=Blllj=54       ',
        '               c1-699Blvlllllu7k96MMMg4         ',
        '               *10y8n6FjvllllB<166668           ',
        '                S-kg+>666<M<996-y6n<8*          ',
        '                p71=4 m69996kD8Z-66698&&        ',
        '                &i0ycm6n4 ogk17,0<6666g         ',
        '                 N-k-<>     >=01-kuu666>        ',
        '                 ,6ky&      &46-10ul,66,        ',
        '                 Ou0<>       o66y<ulw<66&       ',
        '                  *kk5       >66By7=xu664       ',
        '                   <<M4      466lj<Mxu66o       ',
        '                   *>>       +66uv,zN666*       ',
        '                              566,xxj669        ',
        '                              4666FF666>        ',
        '                               >966666M         ',
        '                                oM6668+         ',
        '                                  *4            ',
        '                                                ',
        '                                                ');

As it stands you'll need to terminate the program with a command like CTRL+C. To make the wheelbarrow image sensitive, we could attach the button press event signal to make it do something. The following line would make the picture sensitive to a mouse button being pressed and make the application terminate.

9.7 Rulers

Ruler widgets are used to indicate the location of the mouse pointer in a given window. A window can have a vertical ruler spanning across the width and a horizontal ruler spanning down the height. A small triangular indicator on the ruler shows the exact location of the pointer relative to the ruler.

A ruler must first be created. Horizontal and vertical rulers are created using

Once a ruler is created, we can define the unit of measurement. Units of measure for rulers can be GTK_PIXELS, GTK_INCHES or GTK_CENTIMETERS. This is set using

The default measure is GTK_PIXELS.

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

The lower and upper arguments define the extent of the ruler, and max_size is the largest possible number that will be displayed. Position defines the initial position of the pointer indicator within the ruler.

A vertical ruler can span an 800 pixel wide window thus

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

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 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

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 drawing area is 600 pixels wide by 400 pixels high. The horizontal ruler spans from 7 to 13 with a mark every 100 pixels, while the vertical ruler spans from 0 to 400 with a mark every 100 pixels. Placement of the drawing area and the rulers is done using a table. The following example program produces an output like this:

9.8 Statusbars

Statusbars are simple widgets used to display a text message. They keep a stack of the messages pushed onto them, so that popping the current message will re-display the previous text message.

In order to allow different parts of an application to use the same statusbar to display messages, the statusbar widget issues Context Identifiers which are used to identify different users. The message on top of the stack is the one displayed, no matter what context it is in. Messages are stacked in last-in-first-out order, not context identifier order.

A statusbar is created with a call to:

A new Context Identifier is requested using a call to the following function with a short textual description of the context:

There are two procedures and one function that can operate on statusbars:

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 to the function gtk_statusbar_remove() to remove the message with the given Message and Context Identifiers from the statusbar's stack.

The function gtk_statusbar_pop() removes the message highest in the stack with the given Context Identifier.

The following example creates a statusbar and two buttons, one for pushing items onto the statusbar, and one for popping the last item back off. When compiled and run it should look like this:

9.9 Text Entries

The Entry widget allows text to be typed and displayed in a single line text box. The text may be set with function calls that allow new text to replace, prepend or append the current contents of the Entry widget.

There are two functions for creating Entry widgets:

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.

There are several functions for altering the text which is currently within the Entry widget.

The function gtk_entry_set_text() sets the contents of the Entry widget, replacing the current contents. The functions gtk_entry_append_text() and gtk_entry_prepend_text() allow the current contents to be appended and prepended to.

The next function allows the current insertion point to be set.

The contents of the Entry can be retrieved by using a call to the following function. This is useful in the callbacks described below.

The value returned by this function is used internally, and must not be freed using dispose().

If we don't want the contents of the Entry to be changed by someone typing into it, we can change its editable state.

The function above allows us to toggle the editable state of the Entry widget by passing in a TRUE or FALSE value for the editable argument.

If we are using the Entry where we don't want the text entered to be visible, for example when a password is being entered, we can use the following function, which also takes a boolean argument.

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.

If we want to catch when the user has entered text, we can connect to the activate or changed signal. Activate is raised when the user hits the enter key within the Entry widget. Changed is raised when the text changes at all, e.g., for every character entered or removed.

The following code is an example of using an Entry widget. Compiled and run it should look like this:

9.10 Spin Buttons

The Spin Button widget is generally used to allow the user to select a value from a range of numeric values. It consists of a text entry box with up and down arrow buttons attached to the side. Selecting one of the buttons causes the value to spin up and down the range of possible values. The entry box may also be edited directly to enter a specific value.

The Spin Button allows the value to have zero or a number of decimal places and to be incremented/decremented in configurable steps. The action of holding down one of the buttons optionally results in an acceleration of change in the value according to how long it is depressed.

The Spin Button uses an Adjustment object to hold information about the range of values that the spin button can take. This makes for a powerful Spin Button widget.

Recall that an adjustment widget is created with the following function, which illustrates the information that it holds:

These attributes of an Adjustment are used by the Spin Button in the following way:

Additionally, mouse button 3 can be used to jump directly to the upper or lower values when used to select one of the buttons. Lets look at how to create a Spin Button:

The climb_rate argument take a value between 0.0 and 1.0 and indicates the amount of acceleration that the Spin Button has. The digits argument specifies the number of decimal places to which the value will be displayed.

A Spin Button can be reconfigured after creation using the following function:

The spin_button argument specifies the Spin Button widget that is to be reconfigured. The other arguments are as specified above.

The adjustment can be set and retrieved independently using the following procedure and function:

The number of decimal places can also be altered using:

The value that a Spin Button is currently displaying can be changed using the following procedure:

The current value of a Spin Button can be retrieved as either a floating point or integer value with the following functions:

If you want to alter the value of a Spin Value relative to its current value, then the following function can be used:

The direction parameter can take one of the following values:

This function packs in quite a bit of functionality, which I will attempt to clearly explain. Many of these settings use values from the Adjustment object that is associated with a Spin Button.

GTK_SPIN_STEP_FORWARD and GTK_SPIN_STEP_BACKWARD change the value of the Spin Button by the amount specified by increment, unless increment is equal to 0, in which case the value is changed by the value of step_increment in the Adjustment.

GTK_SPIN_PAGE_FORWARD and GTK_SPIN_PAGE_BACKWARD simply alter the value of the Spin Button by increment.

GTK_SPIN_HOME sets the value of the Spin Button to the bottom of the Adjustments range.

GTK_SPIN_END sets the value of the Spin Button to the top of the Adjustments range.

GTK_SPIN_USER_DEFINED simply alters the value of the Spin Button by the specified amount.

We move away from functions for setting and retrieving the range attributes of the Spin Button now, and move on to procedures that effect the appearance and behaviour of the Spin Button widget itself.

The first of these procedures is used to constrain the text box of the 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:

You can set whether a Spin Button will wrap around between the upper and lower range values with the following procedure:

You can set a Spin Button to round the value to the nearest step_increment, which is set within the Adjustment object used with the Spin Button. This is accomplished with the following procedure:

The update policy of a Spin Button can be changed with the following procedure:

The possible values of policy are either GTK_UPDATE_ALWAYS or GTK_UPDATE_IF_VALID.

These policies affect the behavior of a Spin Button when parsing inserted text and syncing its value with the values of the Adjustment.

In the case of GTK_UPDATE_IF_VALID the Spin Button only value gets changed if the text input is a numeric value that is within the range specified by the Adjustment. Otherwise the text is reset to the current value.

In case of GTK_UPDATE_ALWAYS we ignore errors while converting text into a numeric value.

The appearance of the buttons used in a Spin Button can be changed using the following procedure:

As usual, the shadow_type can be one of:

Finally, you can explicitly request that a Spin Button update itself:

It's example time again. The program produces the output shown, but it's not a static output. Clicking the up/down arrows increases/decreases the numbers as you'd expect. Not accelerated means that you can't type the numbers in from the keyboard. The number 57 at the bottom of the Accelerated box is the result of pressing the Value as Int button for the value 56.500.

9.11 Combo Box

The combo box is another fairly simple widget that is really just a collection of other widgets. From the user's point of view, the widget consists of a text entry box and a pull down menu from which the user can select one of a set of predefined entries. Alternatively, the user can type a different option directly into the text box.

The following extract from the structure that defines a Combo Box identifies several of the components:

As you can see, the Combo Box has two principal parts that you really care about: an entry and a list.

First of all, to create a combo box, use:

Now, if you want to set the string in the entry section of the combo box, this is done by manipulating the entry widget directly:

To set the values in the popdown list, one uses the procedure:

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 GLib, a library supporting GTK. For the moment, the quick and dirty explanation is that you need to set up a GList pointer, set it equal to NIL, then append strings to it with

It is important that you set the initial GList pointer to NIL. The value returned from the g_list_append() function must be used as the new pointer to the GList. Here's a typical code segment for creating a set of options:

At this point you have a working combo box that has been set up. There are a few aspects of its behavior that you can change. These are accomplished with the procedures:

gtk_combo_set_use_arrows() lets the user change the value in the entry using the up/down arrow keys. This doesn't bring up the list, but rather replaces the current text in the entry with the next list entry (up or down, as your key choice indicates). It does this by searching in the list for the item corresponding to the current value in the entry and selecting the previous/next item accordingly. Usually in an entry the arrow keys are used to change focus (you can do that anyway using TAB). Note that when the current item is the last of the list and you press arrow-down it changes the focus (the same applies with the first item and arrow-up).

If the current value in the entry is not in the list, then the function of gtk_combo_set_use_arrows() is disabled.

gtk_combo_set_use_arrows_always() similarly allows the use the the up/down arrow keys to cycle through the choices in the dropdown list, except that it wraps around the values in the list, completely disabling the use of the up and down arrow keys for changing focus.

gtk_combo_set_case_sensitive() toggles whether or not GTK searches for entries in a case sensitive manner. This is used when the Combo widget is asked to find a value from the list using the current entry in the text box. This completion can be performed in either a case sensitive or insensitive manner, depending upon the use of this function. The Combo widget can also simply complete the current entry if the user presses the key combination MOD-1 and Tab. MOD-1 is often mapped to the Alt key, by the xmodmap utility. Note, however that some window managers also use this key combination, which will override its use within GTK.

Now that we have a combo box, tailored to look and act how we want it, all that remains is being able to get data from the combo box. This is relatively straightforward. The majority of the time, all you are going to care about getting data from is the entry. The entry is accessed simply by

The two principal things that you are going to want to do with it are 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:

Getting the text at any arbitrary time is accomplished by simply using the entry function:

Such as:

That's all about comboboxes. There is a procedure which is declared as following:

It 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.

9.12 Colour Selection

The colour selection widget is, not surprisingly, a widget for interactive selection of colours. This composite widget lets the user select a colour by manipulating RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done either by adjusting single values with sliders or entries, or by picking the desired color from a hue-saturation wheel/value bar. Optionally, the opacity of the colour can also be set.

The colour selection widget currently emits only one signal, color_changed, which is emitted whenever the current colour in the widget changes, either when the user changes it or if it's set explicitly through gtk_color_selection_set_color().

Lets have a look at what the colour selection widget has to offer us. The widget comes in two flavours: gtk_color_selection() and gtk_color_selection_dialog().

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.

This is the most common colour selection constructor. It creates a ColorSelectionDialog. It consists of a Frame containing a ColorSelection widget, an HSeparator and an HBox with three buttons, OK, Cancel and Help. You can reach these buttons by accessing the ok_button, cancel_button and help_button widgets in the ColorSelectionDialog record, (i.e., GTK_COLOR_SELECTION_DIALOG(colorseldialog)^.ok_button)).

This function sets the update policy. The default policy is GTK_UPDATE_CONTINUOUS which means that the current colour is updated continuously when the user drags the sliders or presses the mouse and drags in the hue-saturation wheel or value bar. If you experience performance problems, you may want to set the policy to GTK_UPDATE_DISCONTINUOUS or GTK_UPDATE_DELAYED.

The colour selection widget supports adjusting the opacity of a colour (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.

You can set the current colour explicitly by calling this function with a pointer to an array of colours (gdouble). The length of the array depends on whether opacity is enabled or not. Position 0 contains the red component, 1 is green, 2 is blue and opacity is at position 3 (only if opacity is enabled, see gtk_color_selection_set_opacity() ). All values are between 0.0 and 1.0.

When you need to query the current colour, typically when you've received a color_changed signal, you use this function. Colour is a pointer to the array of colours to fill in. See the gtk_color_selection_set_color() function for the description of this array.

Here's a simple example demonstrating the use of the ColorSelectionDialog. The program displays a window containing a drawing area. Clicking on it opens a colour selection dialog, and changing the colour in the colour selection dialog changes the background colour.

9.13 File Selections

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 great way to cut down on programming time.

To create a new file selection box use:

To set the filename, for example to bring up a specific directory, or give a default filename, use this procedure:

To grab the text that the user has entered or clicked on, use this function:

There are also pointers to the widgets contained within the file selection widget. These are:

Most likely you will want to use the ok_button, cancel_button, and help_button pointers in signaling their use.

Included here is an example stolen from testgtk.c, modified to run on its own and translated into Pascal. As you will see, there is nothing much to creating a file selection widget. If you compile and run the program you'll find that the buttons across the top (Create Dir etc.) work even though our program doesn't handle their signals.