diff --git a/ChangeLog b/ChangeLog index 9fc0b94f71..4ab263bd4f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Sun Oct 4 17:45:43 BST 1998 Tony Gale + + * docs/gtk_tut.sgml: update I've had sat around: + - Grammar patch from James R. Van Zandt + - Range Widget update from David Huggins-Daines + - New Toolbar section from Jacek Wojdel + 1998-10-01 Martin Baulig * gtk/gtkclist.h (GtkCListColumn): Added `visible'. diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 9fc0b94f71..4ab263bd4f 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,10 @@ +Sun Oct 4 17:45:43 BST 1998 Tony Gale + + * docs/gtk_tut.sgml: update I've had sat around: + - Grammar patch from James R. Van Zandt + - Range Widget update from David Huggins-Daines + - New Toolbar section from Jacek Wojdel + 1998-10-01 Martin Baulig * gtk/gtkclist.h (GtkCListColumn): Added `visible'. diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 9fc0b94f71..4ab263bd4f 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,10 @@ +Sun Oct 4 17:45:43 BST 1998 Tony Gale + + * docs/gtk_tut.sgml: update I've had sat around: + - Grammar patch from James R. Van Zandt + - Range Widget update from David Huggins-Daines + - New Toolbar section from Jacek Wojdel + 1998-10-01 Martin Baulig * gtk/gtkclist.h (GtkCListColumn): Added `visible'. diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 9fc0b94f71..4ab263bd4f 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,10 @@ +Sun Oct 4 17:45:43 BST 1998 Tony Gale + + * docs/gtk_tut.sgml: update I've had sat around: + - Grammar patch from James R. Van Zandt + - Range Widget update from David Huggins-Daines + - New Toolbar section from Jacek Wojdel + 1998-10-01 Martin Baulig * gtk/gtkclist.h (GtkCListColumn): Added `visible'. diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 9fc0b94f71..4ab263bd4f 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,10 @@ +Sun Oct 4 17:45:43 BST 1998 Tony Gale + + * docs/gtk_tut.sgml: update I've had sat around: + - Grammar patch from James R. Van Zandt + - Range Widget update from David Huggins-Daines + - New Toolbar section from Jacek Wojdel + 1998-10-01 Martin Baulig * gtk/gtkclist.h (GtkCListColumn): Added `visible'. diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 9fc0b94f71..4ab263bd4f 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,10 @@ +Sun Oct 4 17:45:43 BST 1998 Tony Gale + + * docs/gtk_tut.sgml: update I've had sat around: + - Grammar patch from James R. Van Zandt + - Range Widget update from David Huggins-Daines + - New Toolbar section from Jacek Wojdel + 1998-10-01 Martin Baulig * gtk/gtkclist.h (GtkCListColumn): Added `visible'. diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 9fc0b94f71..4ab263bd4f 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,10 @@ +Sun Oct 4 17:45:43 BST 1998 Tony Gale + + * docs/gtk_tut.sgml: update I've had sat around: + - Grammar patch from James R. Van Zandt + - Range Widget update from David Huggins-Daines + - New Toolbar section from Jacek Wojdel + 1998-10-01 Martin Baulig * gtk/gtkclist.h (GtkCListColumn): Added `visible'. diff --git a/docs/gtk_tut.sgml b/docs/gtk_tut.sgml index b17bb492c1..85215bb46c 100644 --- a/docs/gtk_tut.sgml +++ b/docs/gtk_tut.sgml @@ -10,7 +10,7 @@ name="<imain@gtk.org>">, Tony Gale -August 13th, 1998 +September 2nd, 1998 Introduction @@ -175,7 +175,7 @@ void hello (GtkWidget *widget, gpointer data) gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data) { - g_print ("delete event occured\n"); + g_print ("delete event occurred\n"); /* if you return FALSE in the "delete_event" signal handler, * GTK will emit the "destroy" signal. Returning TRUE means * you don't want the window to be destroyed. @@ -228,7 +228,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("Hello World"); /* When the button receives the "clicked" signal, it will call the - * function hello() passing it NULL as it's argument. The hello() function is + * function hello() passing it NULL as its argument. The hello() function is * defined above. */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (hello), NULL); @@ -411,7 +411,7 @@ attached to these events. These events are: In order to connect a callback function to one of these events, you use the function gtk_signal_connect, as described above, using one of the above event names as the void callback_func( GtkWidget *widget, @@ -420,7 +420,7 @@ void callback_func( GtkWidget *widget, GdkEvent is a C -This callback is a bit special. The "delete_event" occurs when the +The next callback is a bit special. The "delete_event" occurs when the window manager sends this event to the application. We have a choice here as to what to do about these events. We can ignore them, make some sort of response, or simply quit the application. @@ -526,7 +526,7 @@ signal handler. gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data) { - g_print ("delete event occured\n"); + g_print ("delete event occurred\n"); return (TRUE); } @@ -653,7 +653,7 @@ which are designed to layout multiple widgets in various ways. gtk_container_add (GTK_CONTAINER (window), button); -Now that we have everything setup the way we want it to be. With all the +Now we have everything set up the way we want it to be. With all the signal handlers in place, and the button placed in the window where it should be, we ask GTK to "show" the widgets on the screen. The window widget is shown last so the whole window will pop up at once rather than @@ -685,7 +685,7 @@ information, our program sets up a signal handler to catch that signal, which dispatches the function of our choice. In our example, when the button we created is "clicked", the hello() function is called with a NULL argument, and then the next handler for this signal is called. This calls -the gtk_widget_destroy() function, passing it the window widget as it's +the gtk_widget_destroy() function, passing it the window widget as its argument, destroying the window widget. This causes the window to emit the "destroy" signal, which is caught, and calls our destroy() callback function, which simply exits GTK. @@ -821,7 +821,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("Button 1"); /* Now when the button is clicked, we call the "callback" function - * with a pointer to "button 1" as it's argument */ + * with a pointer to "button 1" as its argument */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 1"); @@ -1305,7 +1305,7 @@ widget in the table. If homogeneous is FALSE, the size of a table boxes is dictated by the tallest widget in its same row, and the widest widget in its column. -The rows and columnts are laid out from 0 to n, where n was the +The rows and columns are laid out from 0 to n, where n was the number specified in the call to gtk_table_new. So, if you specify rows = 2 and columns = 2, the layout would look something like this: @@ -1486,7 +1486,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("button 1"); /* when the button is clicked, we call the "callback" function - * with a pointer to "button 1" as it's argument */ + * with a pointer to "button 1" as its argument */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 1"); @@ -1501,7 +1501,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("button 2"); /* when the button is clicked, we call the "callback" function - * with a pointer to "button 2" as it's argument */ + * with a pointer to "button 2" as its argument */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 2"); /* insert button 2 into the upper right quadrant of the table */ @@ -1602,7 +1602,7 @@ of these widgets may be used with the GTK_CONTAINER macro to pass them to functions that ask for containers. Unfortunately, these macros are not extensively covered in the tutorial, but I -recomend taking a look through the GTK header files. It can be very +recommend taking a look through the GTK header files. It can be very educational. In fact, it's not difficult to learn how a widget works just by looking at the function declarations. @@ -1735,7 +1735,7 @@ gtk/testgtk.c. Normal Buttons

We've almost seen all there is to see of the button widget. It's pretty -simple. There is however two ways to create a button. You can use the +simple. There are however two ways to create a button. You can use the gtk_button_new_with_label() to create a button with a label, or use gtk_button_new() to create a blank button. It's then up to you to pack a label or pixmap into this new button. To do this, create a new box, and @@ -1743,7 +1743,7 @@ then pack your objects into this box using the usual gtk_box_pack_start, and then use gtk_container_add to pack the box into the button. Here's an example of using gtk_button_new to create a button with a -picture and a label in it. I've broken the code to create a box up from +picture and a label in it. I've broken up the code to create a box from the rest so you can use it in your programs. @@ -1857,7 +1857,7 @@ int main (int argc, char *argv[]) The xpm_label_box function could be used to pack xpm's and labels into any widget that can be a container. -The Buton widget has the following signals: +The Button widget has the following signals: pressed @@ -1896,7 +1896,7 @@ buttons, we use a macro as shown in our example below. This tests the state of the toggle in a callback. The signal of interest emitted to us by toggle buttons (the toggle button, check button, and radio button widgets), is the "toggled" signal. To check the state of these buttons, set up a signal -handler to catch the toggled signal, and use the macro to determine it's +handler to catch the toggled signal, and use the macro to determine its state. The callback will look something like: @@ -1918,10 +1918,10 @@ void gtk_toggle_button_set_state( GtkToggleButton *toggle_button, gint state ); -The above call can be used to set the state of the toggle button, and it's +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 button as the first argument, and a TRUE or FALSE for the second state argument to -specify whether it should be up (released) or down (depressed). Default +specify whether it should be down (depressed) or up (released). Default is up, or FALSE. Note that when you use the gtk_toggle_button_set_state() function, and the @@ -1956,7 +1956,7 @@ Checking the state of the check button is identical to that of the toggle button. - Radio Buttons + Radio Buttons

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 places in @@ -1972,7 +1972,9 @@ GtkWidget *gtk_radio_button_new_with_label( GSList *group, You'll notice the extra argument to these calls. They require a group to -perform they're duty properly. The first call should pass NULL as the first +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: @@ -2086,185 +2088,49 @@ removes the need for a variable to hold the list of buttons: "button2"); - + -Range Widgets + Adjustments

-The category of range widgets includes the ubiquitous scrollbar -widget and the less common scale widget. Though these two -types of widgets are typically used for vastly different -purposes, they are quite similar in function and implementation. -Range widgets allow the user to visually manipulate a value -within a specified range (hence the name). +GTK+ has various widgets that can be visually adjusted by the user +using the mouse or the keyboard, such as the range widgets, described +in the section. There +are also a few widgets that display some adjustable portion of a larger +area of data, such as the text widget and the viewport widget. -All range widgets share a set of common graphic elements, each -of which has its own X window and receives events. They all -contain a "trough" and a "slider" (what is sometimes called a -"thumbwheel" in other GUI environments). Dragging the slider -with the pointer moves it back and forth within the trough, -while clicking in the trough advances the slider towards the -location of the click, either completely, or by a designated -amount (called a "page"), depending on which button was used. +Obviously, an application needs to be able to react to changes the +user makes in range widgets. One way to do this would be to have each +widget emit its own type of signal when its adjustment changes, and +either pass the new value to the signal handler, or require it to look +inside the widget's data structure in order to ascertain the value. +But you may also want to connect the adjustments of several widgets +together, so that adjusting one adjusts the others. The most obvious +example of this is connecting a scrollbar to a panning viewport or a +scrolling text area. If each widget has its own way of setting or +getting the adjustment value, then the programmer may have to write +their own signal handlers to translate between the output of one +widget's signal and the "input" of another's adjustment setting +function. - -The Scale Widgets -

-Scale widgets are used to set an explicitly numeric parameter -which has a visual correlate, and which the user might be -expected to adjust primarily by sight. For example, the -GtkColorSelection compound widget contains scale widgets which -control the components of the colour being selected. -Typically, the precise value of the number is less important -here than its side-effects, and thus the user should be spared -the effort of reaching for the keyboard. +GTK+ solves this problem using the GtkAdjustment object, which is a +way for widgets to store and pass adjustment information in an +abstract and flexible form. The most obvious use of GtkAdjustment is +to store the configuration parameters and values of range widgets, +such as scrollbars and scale controls. However, since GtkAdjustments +are derived from GtkObject, they have some special powers beyond those +of normal data structures. Most importantly, they can emit signals, +just like widgets, and these signals can be used not only to allow +your program to react to user input on adjustable widgets, but also to +propagate adjustment values transparently between adjustable widgets. - -Creating a Scale Widget -

-There are actually two types of scale widget: GtkHScale -widgets, which are horizontal, and GtkVScale widgets, which - -are vertical. (Most programmers seem to favour horizontal -scale widgets). Since they work essentially the same way, -there's no need to treat them separately here. The -following functions, defined in -<gtk/gtkvscale.h> and -<gtk/gtkhscale.h>, create vertical and -horizontal scale widgets, respectively: - - -GtkWidget* gtk_vscale_new( GtkAdjustment *adjustment ); - -GtkWidget* gtk_hscale_new( GtkAdjustment *adjustment ); - - - -below for an explanation of what exactly the -Functions, Signals, and Macros -

-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: - - -void gtk_scale_set_draw_value( GtkScale *scale, - gint draw_value ); - - -As you might have guessed, -void gtk_scale_set_digits( GtkScale *scale, - gint digits); - - -where -void gtk_scale_set_value_pos( GtkScale *scale, - GtkPositionType pos ); - - -If you've read the section on the notebook widget, then you -know what the possible values of GtkPositionType and can take one -of the following values: - - -GTK_POS_LEFT -GTK_POS_RIGHT -GTK_POS_TOP -GTK_POS_BOTTOM - - -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 slider up and down -the trough. - -All the preceding functions are defined in -<gtk/gtkscale.h>. The other signals and -functions defined in the header files for the scale widgets -are either not useful for anyone other than writers of scale -widgets, or are the standard GTK+ type-casting macros and -functions. - - -The Scrollbar Widgets -

-These are your standard, run-of-the-mill scrollbars. As with -the scale widgets, there are separate types for horizontal and -vertical scrollbars. There really isn't much to say about -these. You create them with the following functions: - - -GtkWidget* gtk_hscrollbar_new( GtkAdjustment *adjustment ); - -GtkWidget* gtk_vscrollbar_new( GtkAdjustment *adjustment ); - - -and that's about it (if you don't believe me, look in the -header files!). Again, -The Adjustment Object

-As you might have noticed, there really isn't much to the -various range widgets themselves from the programmer's point -of view. Most of your program's interaction with these -widgets will take place by way of the heretofore mysterious - -Creating a GtkAdjustment + Creating an Adjustment

You create an adjustment using: - + -GtkObject* gtk_adjustment_new( gfloat value, +GtkObject *gtk_adjustment_new( gfloat value, gfloat lower, gfloat upper, gfloat step_increment, @@ -2272,69 +2138,68 @@ GtkObject* gtk_adjustment_new( gfloat value, gfloat page_size ); -It may or may not be obvious by now that the values given to - below -describes the default key and mouse bindings for range -widgets, and how they relate to these increments. The - -GtkObject *adj; - -adj = gtk_adjustment_new (0, first_line, last_line, 1, - window_height - 2, window_height); - - -where last_line - -window_height (or, in more general terms, upper - -page_height). This is a little confusing at first, but -it makes sense if you think about it in terms of what the -user expects to see in a scrolled window when the -scrollbar's slider is moved all the way to the end of the -trough. - -Since the size of the slider on scale widgets is invariable, -to avoid excessive confusion, it's a good idea to set the - -Inside the GtkAdjustment object + Using Adjustments the Easy Way

-OK, you say, that's nice, but how do I get at all these -values, and, more importantly, how do I know when the user -has moved the slider around? To answer these questions and -more, let's start by taking a look at + /* 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); + + + + + Adjustment Internals +

+OK, you say, that's nice, but what if I want to create my own handlers +to respond when the user adjusts a range widget or a spin button, and +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 +struct _GtkAdjustment itself: struct _GtkAdjustment @@ -2348,53 +2213,43 @@ struct _GtkAdjustment gfloat page_increment; gfloat page_size; }; - -struct _GtkAdjustmentClass -{ - GtkDataClass parent_class; - - void (* changed) (GtkAdjustment *adjustment); - void (* value_changed) (GtkAdjustment *adjustment); -}; -The first thing you should know is that there aren't any -handy-dandy macros or accessor functions for getting the -GTK_ADJUSTMENT (Object) macro does -run-time type checking (as do all the GTK+ type-casting -macros, actually). On the other hand, unless you're writing -a new type of range widget, you probably don't want to -GTK_ADJUSTMENT +(Object) macro does run-time type checking (as do all the GTK+ +type-casting macros, actually). + +Since, when you set the void gtk_adjustment_set_value( GtkAdjustment *adjustment, gfloat value ); -If you need to change the other fields, and you don't intend -to do this very frequently, it's best to create a new -GtkAdjustment and set it with - below. +As mentioned earlier, GtkAdjustment is a subclass of GtkObject just +like all the various widgets, and thus it is able to emit signals. +This is, of course, why updates hapen automagically when you share an +adjustment object between a scrollbar and another adjustable widget; +all adjustable widgets connect signal handlers to their adjustment's + + void (* value_changed) (GtkAdjustment *adjustment); + -The various widgets that use the GtkAdjustment object will -emit the "value_changed" signal on an adjustment whenever -they change its value (see below for more detail). This -happens both when user input causes the slider to move on a -range widget, as well as when the program explicitly changes -the value with void cb_rotate_picture (GtkAdjustment *adj, GtkWidget *picture) @@ -2410,163 +2265,320 @@ gtk_signal_connect (GTK_OBJECT (adj), "value_changed", GTK_SIGNAL_FUNC (cb_rotate_picture), picture); -The "changed" signal is somewhat more elusive. It is never -emitted directly due to the -Common Functions, Signals, and Macros

-The GtkRange widget class is fairly complicated internally, -but, like all the "base class" widgets, most of its complexity -is only interesting if you want to hack on it. Also, almost -all of the functions and signals it defines are only really -used in writing derived widgets. There are, however, a few -useful functions and concepts that are defined in gtkrange.h -and are common to all range widgets. - - -Update Policies

-The "update policy" of a range widget defines at what points -during user interaction it will change the <gtk/gtkenums.h> as the enum -GtkUpdateType, are: - - -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. - - -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. - - -GTK_UPDATE_POLICY_DELAYED - The "value_change" -signal is emitted when the user releases the mouse button, -or if the slider stops moving for a short period of -time. - - - -The update policy of a range widget can be set by casting it -using the GTK_RANGE (Widget) macro and passing it -to this function: +What about when a widget reconfigures the -void gtk_range_set_update_policy( GtkRange *range, - GtkUpdateType policy ); + void (* changed) (GtkAdjustment *adjustment); - -Getting and setting adjustments -

-Getting and setting the adjustment for a range widget "on -the fly" is done, predictably, with: - - -GtkAdjustment* gtk_range_get_adjustment( GtkRange *range ); +Range widgets typically connect a handler to this signal, which +changes their appearance to reflect the change - for example, the size +of the slider in a scrollbar will grow or shrink in inverse proportion +to the difference between the - - - gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed"); - -Key and Mouse bindings

-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 adjustment's + -The key bindings, by contrast, are slightly different -between horizontal and vertical range widgets, for obvious -reasons. They are also not quite the same for scale widgets -as they are for scrollbars, for somewhat less obvious -reasons (possibly to avoid confusion between the keys for -horizontal and vertical scrollbars in scrolled windows, -where both operate on the same area). + + Range Widgets

+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 +function and implementation. All range widgets share a set of common +graphic elements, each of which has its own X window and receives +events. They all contain a "trough" and a "slider" (what is sometimes +called a "thumbwheel" in other GUI environments). Dragging the slider +with the pointer moves it back and forth within the trough, while +clicking in the trough advances the slider towards the location of the +click, either completely, or by a designated amount, depending on +which mouse button is used. + +As mentioned in above, +all range widgets are associated with an adjustment object, from which +they calculate the length of the slider and it's position within the +trough. When the user manipulates the slider, the range widget +will change the value of the adjustment. -Vertical Range Widgets + Scrollbar Widgets

-All vertical range widgets can be operated with the up and -down arrow keys, as well as with the Control-Page Up and -Control-Page Down. +There are separate types for horizontal and vertical scrollbars. +There really isn't much to say about these. You create them with the +following functions, defined in <gtk/gtkhscrollbar.h> +and <gtk/gtkvscrollbar.h>: + + +GtkWidget *gtk_hscrollbar_new( GtkAdjustment *adjustment ); + +GtkWidget *gtk_vscrollbar_new( GtkAdjustment *adjustment ); + + +and that's about it (if you don't believe me, look in the header +files!). The -Horizontal Range Widgets + Scale Widgets

-The left and right arrow keys work as you might expect in -these widgets, moving the slider back and forth by -Control-Left and -Control-Right, while for GtkHScrollbar, it's done -with Control-Home and Control-End. +Scale widgets are used to allow the user to visually select and +manipulate a value within a specific range. You might want to use a +scale widget, for example, to adjust the magnification level on a +zoomed preview of a picture, or to control the brightness of a colour, +or to specify the number of minutes of inactivity before a screensaver +takes over the screen. -Example

-This example is a somewhat modified version of the "range -widgets" test from <gtk/gtkvscale.h> and +<gtk/gtkhscale.h>, create vertical and horizontal scale +widgets, respectively: + + + +GtkWidget *gtk_vscale_new( GtkAdjustment *adjustment ); + +GtkWidget *gtk_hscale_new( GtkAdjustment *adjustment ); + + + +The again for an explanation of +what exactly adjustments do and how to create and manipulate them). + + + Functions and Signals (well, functions, at least) +

+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: + + +void gtk_scale_set_draw_value( GtkScale *scale, + gint draw_value ); + + +As you might have guessed, + +void gtk_scale_set_digits( GtkScale *scale, + gint digits ); + + + +where + +void gtk_scale_set_value_pos( GtkScale *scale, + GtkPositionType pos ); + + + +If you've read the section on the notebook widget, then you already +know what the possible values of enum GtkPositionType in <gtk/gtkenums.h> and +are pretty self-explanatory. 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 slider up and down the trough. + +All the preceding functions are defined in +<gtk/gtkscale.h>. + + + + + Common Functions

+The GtkRange widget class is fairly complicated internally, but, like +all the "base class" widgets, most of its complexity is only +interesting if you want to hack on it. Also, almost all of the +functions and signals it defines are only really used in writing +derived widgets. There are, however, a few useful functions that +are defined in <gtk/gtkrange.h> and will work on all range widgets. + + + Setting the Update Policy +

+The "update policy" of a range widget defines at what points during +user interaction it will change the <gtk/gtkenums.h> as type enum GtkUpdateType, +are: + + +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. + +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. + +GTK_UPDATE_POLICY_DELAYED - The "value_change" signal is emitted +when the user releases the mouse button, or if the slider stops moving +for a short period of time. + + + +The update policy of a range widget can be set by casting it using the +GTK_RANGE (Widget) macro and passing it to this function: + + +void gtk_range_set_update_policy (GtkRange *range, + GtkUpdateType policy); + + + +Getting and Setting Adjustments +

+Getting and setting the adjustment for a range widget "on the fly" is +done, predictably, with: + + +GtkAdjustment* gtk_range_get_adjustment( GtkRange *range ); + +void gtk_range_set_adjustment( GtkRange *range, + GtkAdjustment *adjustment ); + + + +gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed"); + + + + + + Key and Mouse bindings +

+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 +adjustment's +GTK_WIDGET_UNSET_FLAGS (scrollbar, GTK_CAN_FOCUS); + + +The key bindings (which are, of course, only active when the widget +has focus) are slightly different between horizontal and vertical +range widgets, for obvious reasons. They are also not quite the same +for scale widgets as they are for scrollbars, for somewhat less +obvious reasons (possibly to avoid confusion between the keys for +horizontal and vertical scrollbars in scrolled windows, where both +operate on the same area). + + Vertical Range Widgets +

+All vertical range widgets can be operated with the up and down arrow +keys, as well as with the Control-Page Up +and Control-Page Down. + + + Horizontal Range Widgets +

+The left and right arrow keys work as you might expect in these +widgets, moving the slider back and forth by Control-Left and Control-Right, +while for GtkHScrollbar, it's done with Control-Home and +Control-End. + + + + + Example

+This example is a somewhat modified version of the "range widgets" +test from /* example-start rangewidgets rangewidgets.c */ @@ -2856,9 +2868,11 @@ int main (int argc, char *argv[]) /* example-end */ + + - Miscallaneous Widgets + Miscellaneous Widgets @@ -2895,7 +2909,7 @@ void gtk_label_get( GtkLabel *label, char **str ); -Where the first arguement is the label you've created, and the second, the +Where the first argument is the label you've created, and the second, the return for the string. @@ -3155,7 +3169,7 @@ struct GtkDialog So you see, it simply creates a window, and then packs a vbox into the top, -then a seperator, and then an hbox for the "action_area". +then a separator, and then an hbox for 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 @@ -3204,7 +3218,7 @@ application, then you can simply pack another layout widget into the boxes provided. For example, you could pack a table into the vertical box. - Pixmaps + Pixmaps

Pixmaps are data structures that contain pictures. These pictures can be used in various places, but most visibly as icons on the X-Windows desktop, @@ -3966,14 +3980,14 @@ gchar *gtk_entry_get_text( GtkEntry *entry ); If we don't want the contents of the Entry to be changed by someone typing -into it, we can change it's editable state. +into it, we can change its editable state. void gtk_entry_set_editable( GtkEntry *entry, gboolean editable ); -This function allows us to toggle the edittable state of the Entry widget +This function allows us to toggle the editable state of the Entry widget by passing in a TRUE or FALSE value for the This function sets the update policy. The default policy is -GTK_UPDATE_CONTINOUS which means that the current color is updated -continously when the user drags the sliders or presses the mouse and drags +GTK_UPDATE_CONTINUOUS which means that the current color 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_DISCONTINOUS or +problems, you may want to set the policy to GTK_UPDATE_DISCONTINUOUS or GTK_UPDATE_DELAYED. @@ -4381,7 +4395,7 @@ 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 it's own. As you will see, there is nothing much to creating a file +on its own. As you will see, there is nothing much to creating a file selection widget. While in this example the Help button appears on the screen, it does nothing as there is not a signal attached to it. @@ -4442,7 +4456,7 @@ int main (int argc, char *argv[])

The NoteBook Widget is a collection of 'pages' that overlap each other, each page contains different information. This widget has become more common -lately in GUI programming, and it is a good way to show blocks similar +lately in GUI programming, and it is a good way to show blocks of similar information that warrant separation in their display. The first function call you will need to know, as you can probably @@ -4752,9 +4766,9 @@ GTK applications.

Scrolled windows are used to create a scrollable area inside a real window. You may insert any type of widget into a scrolled window, and it will -be accessable regardless of the size by using the scrollbars. +be accessible regardless of the size by using the scrollbars. -The following function is used to create a new scolled window. +The following function is used to create a new scrolled window. GtkWidget *gtk_scrolled_window_new( GtkAdjustment *hadjustment, @@ -4772,13 +4786,13 @@ void gtk_scrolled_window_set_policy( GtkScrolledWindow *scrolled_window, This sets the policy to be used with respect to the scrollbars. -The first arguement is the scrolled window you wish to change. The second -sets the policiy for the horizontal scrollbar, and the third the policy for +The first argument is the scrolled window you wish to change. The second +sets the policy for the horizontal scrollbar, and the third the policy for the vertical scrollbar. The policy may be one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS. GTK_POLICY_AUTOMATIC will automatically decide whether you need -scrollbars, wheras GTK_POLICY_ALWAYS will always leave the scrollbars +scrollbars, whereas GTK_POLICY_ALWAYS will always leave the scrollbars there. Here is a simple example that packs 100 toggle buttons into a scrolled window. @@ -4807,7 +4821,7 @@ int main (int argc, char *argv[]) /* Create a new dialog window for the scrolled window to be * packed into. A dialog is just like a normal window except it has a - * vbox and a horizontal seperator packed into it. It's just a shortcut + * vbox and a horizontal separator packed into it. It's just a shortcut * for creating dialogs */ window = gtk_dialog_new (); gtk_signal_connect (GTK_OBJECT (window), "destroy", @@ -4823,7 +4837,7 @@ int main (int argc, char *argv[]) /* the policy is one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS. * GTK_POLICY_AUTOMATIC will automatically decide whether you need - * scrollbars, wheras GTK_POLICY_ALWAYS will always leave the scrollbars + * scrollbars, whereas GTK_POLICY_ALWAYS will always leave the scrollbars * there. The first one is the horizontal scrollbar, the second, * the vertical. */ gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window), @@ -5067,6 +5081,408 @@ main (int argc, char *argv[]) /* example-end */ + +Toolbar +

+Toolbars are usually used to group some number of widgets in order to simplify +customization of their look and layout. Typically a toolbar consists of buttons +with icons, labels and tooltips, but any other widget can also +be put inside a toolbar. Finally, items can be arranged horizontally +or vertically and buttons can be displayed with icons, labels or both. + +Creating a toolbar is (as one may already suspect) done with the following +function: + + +GtkWidget *gtk_toolbar_new( GtkOrientation orientation, + GtkToolbarStyle style ); + + +where orientation may be one of: + + + GTK_ORIENTATION_HORIZONTAL + GTK_ORIENTATION_VERTICAL + + +and style one of: + + + GTK_TOOLBAR_TEXT + GTK_TOOLBAR_ICONS + GTK_TOOLBAR_BOTH + + +The style applies to all the buttons created with the `item' functions +(not to buttons inserted into toolbar as separate widgets). + +After creating a toolbar one can append,prepend and insert items (that +means simple buttons) into the toolbar. To describe an item we need a +label text, a tooltip text, a private tooltip text, an icon +for the button and a callback function for it. For example, to append +an item you may use the following function: + + +GtkWidget *gtk_toolbar_append_item( GtkToolbar *toolbar, + const char *text, + const char *tooltip_text, + const char *tooltip_private_text, + GtkWidget *icon, + GtkSignalFunc callback, + gpointer user_data ); + + +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. + +To simplify adding spaces between toolbar items, you may use the following +function: + + +void gtk_toolbar_append_space( GtkToolbar *toolbar ); + +void gtk_toolbar_prepend_space( GtkToolbar *toolbar ); + +void gtk_toolbar_insert_space( GtkToolbar *toolbar, + gint position ); + + + +While the size of the added space can be set globally for a +whole toolbar with the function: + + +void gtk_toolbar_set_space_size( GtkToolbar *toolbar, + gint space_size) ; + + +If it's needed the orientation of a toolbar and its style can be changed +`on the fly' using the following functions: + + +void gtk_toolbar_set_orientation( GtkToolbar *toolbar, + GtkOrientation orientation ); + +void gtk_toolbar_set_style( GtkToolbar *toolbar, + GtkToolbarStyle style ); + +void gtk_toolbar_set_tooltips( GtkToolbar *toolbar, + gint enable ); + + +To show some other things that can be done with a toolbar, let's take the +following program (we'll interrupt the listing with some additional explanations): + + +#include + +#include "gtk.xpm" + +/* This function is connected to the Close button or + * closing the window from the WM */ +void delete_event (GtkWidget *widget, GdkEvent *event, gpointer data) +{ + gtk_main_quit (); +} + + +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. + + +GtkWidget* close_button; // this button will emit signal to close application +GtkWidget* tooltips_button; // to enable/disable tooltips +GtkWidget* text_button, + * icon_button, + * both_button; // radio buttons for toolbar style +GtkWidget* entry; // a text entry to show packing any widget into toolbar + + +In fact not all of the above widgets are needed here, but to make things +clearer I put them all together. + + +/* that's easy... when one of the buttons is toggled, we just + * check which one is active and set the style of the toolbar + * accordingly + * ATTENTION: our toolbar is passed as data to callback ! */ +void radio_event (GtkWidget *widget, gpointer data) +{ + if (GTK_TOGGLE_BUTTON (text_button)->active) + gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_TEXT); + else if (GTK_TOGGLE_BUTTON (icon_button)->active) + gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_ICONS); + else if (GTK_TOGGLE_BUTTON (both_button)->active) + gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_BOTH); +} + +/* even easier, just check given toggle button and enable/disable + * tooltips */ +void toggle_event (GtkWidget *widget, gpointer data) +{ + gtk_toolbar_set_tooltips (GTK_TOOLBAR ( data ), + GTK_TOGGLE_BUTTON (widget)->active ); +} + + +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). + + +int main (int argc, char *argv[]) +{ + /* Here is our main window (a dialog) and a handle for the handlebox */ + GtkWidget* dialog; + GtkWidget* handlebox; + + /* Ok, we need a toolbar, an icon with a mask (one for all of + the buttons) and an icon widget to put this icon in (but + we'll create a separate widget for each button) */ + GtkWidget * toolbar; + GdkPixmap * icon; + GdkBitmap * mask; + GtkWidget * iconw; + + /* this is called in all GTK application. */ + gtk_init (&argc, &argv); + + /* create a new window with a given title, and nice size */ + dialog = gtk_dialog_new (); + gtk_window_set_title ( GTK_WINDOW ( dialog ) , "GTKToolbar Tutorial"); + gtk_widget_set_usize( GTK_WIDGET ( dialog ) , 600 , 300 ); + GTK_WINDOW ( dialog ) ->allow_shrink = TRUE; + + /* typically we quit if someone tries to close us */ + gtk_signal_connect ( GTK_OBJECT ( dialog ), "delete_event", + GTK_SIGNAL_FUNC ( delete_event ), NULL); + + /* we need to realize the window because we use pixmaps for + * items on the toolbar in the context of it */ + gtk_widget_realize ( dialog ); + + /* to make it nice we'll put the toolbar into the handle box, + * 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 ); + + +The above should be similar to any other GTK application. Just initialization +of GTK, creating the window etc.. There is only one thing that probably +needs some explanation: a handle box. A handle box is just another box +that can be used to pack widgets in to. The difference between it and typical +boxes is that it can be detached from a parent window (or, in fact, the handle +box remains in the parent, but it is reduced to a very small rectangle, while +all of its 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. + + + /* 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, + GTK_TOOLBAR_BOTH ); + gtk_container_border_width ( GTK_CONTAINER ( toolbar ) , 5 ); + gtk_toolbar_set_space_size ( GTK_TOOLBAR ( toolbar ), 5 ); + gtk_container_add ( GTK_CONTAINER ( handlebox ) , toolbar ); + + /* 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 ); + + +Well, what we do above is just a straight-forward initialization of the toolbar +widget and creation of a GDK pixmap with its mask. If you want to know +something more about using pixmaps, refer to GDK documentation +or to the section earlier in this tutorial. + + + /* our first item is button */ + iconw = gtk_pixmap_new ( icon, mask ); // icon widget + close_button = + gtk_toolbar_append_item ( GTK_TOOLBAR (toolbar), // our toolbar + "Close", // button label + "Closes this app", // tooltip for this button + "Private", // tooltip private string + iconw, // icon widget + GTK_SIGNAL_FUNC (delete_event), // a signal + NULL ); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); // space after item + + +In the above code you see the simplest case: adding a button to toolbar. +Just before appending a new item, we have to construct a pixmap widget +to serve as an icon for this item; this step will have to be repeated for +each new item. Just after the item we also add a 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. + + + /* now, let's make our radio buttons group... */ + iconw = gtk_pixmap_new ( icon, mask ); + icon_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_RADIOBUTTON, // a type of element + NULL, // pointer to widget + "Icon", // label + "Only icons in toolbar", // tooltip + "Private", // tooltip private string + iconw, // icon + GTK_SIGNAL_FUNC (radio_event), // signal + toolbar); // data for signal + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + + +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 add simple items or even spaces +(type = GTK_TOOLBAR_CHILD_SPACE or GTK_TOOLBAR_CHILD_BUTTON). In the above +case we start creating a radio group. In creating other radio buttons for +this group a pointer to the previous button in the group is required, +so that a list of buttons can be easily constructed (see the section on + earlier in this tutorial). + + + /* following radio buttons refer to previous ones */ + iconw = gtk_pixmap_new ( icon, mask ); + text_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_RADIOBUTTON, + icon_button, + "Text", + "Only texts in toolbar", + "Private", + iconw, + GTK_SIGNAL_FUNC (radio_event), + toolbar); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + + iconw = gtk_pixmap_new ( icon, mask ); + both_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_RADIOBUTTON, + text_button, + "Both", + "Icons and text in toolbar", + "Private", + iconw, + GTK_SIGNAL_FUNC (radio_event), + toolbar); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(both_button),TRUE); + + +In the end we have set the state of one of the buttons manually (otherwise +they all stay in active state, preventing us from switching between them). + + + /* here we have just a simple toggle button */ + iconw = gtk_pixmap_new ( icon, mask ); + tooltips_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_TOGGLEBUTTON, + NULL, + "Tooltips", + "Toolbar with or without tips", + "Private", + iconw, + GTK_SIGNAL_FUNC (toggle_event), + toolbar); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(tooltips_button),TRUE); + + +A toggle button can be created in the obvious way (if one knows how to create +radio buttons already). + + + /* 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), + entry, + "This is just an entry", + "Private" ); + + /* well, it isn't created within thetoolbar, so we must still show it */ + gtk_widget_show ( entry ); + + +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). + + + /* that's it ! let's show everything. */ + gtk_widget_show ( toolbar ); + gtk_widget_show (handlebox); + gtk_widget_show ( dialog ); + + /* rest in gtk_main and wait for the fun to begin! */ + gtk_main (); + + return 0; +} + + +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: + + +/* XPM */ +static char * gtk_xpm[] = { +"32 39 5 1", +". c none", +"+ c black", +"@ c #3070E0", +"# c #F05050", +"$ c #35E035", +"................+...............", +"..............+++++.............", +"............+++++@@++...........", +"..........+++++@@@@@@++.........", +"........++++@@@@@@@@@@++........", +"......++++@@++++++++@@@++.......", +".....+++@@@+++++++++++@@@++.....", +"...+++@@@@+++@@@@@@++++@@@@+....", +"..+++@@@@+++@@@@@@@@+++@@@@@++..", +".++@@@@@@+++@@@@@@@@@@@@@@@@@@++", +".+#+@@@@@@++@@@@+++@@@@@@@@@@@@+", +".+##++@@@@+++@@@+++++@@@@@@@@$@.", +".+###++@@@@+++@@@+++@@@@@++$$$@.", +".+####+++@@@+++++++@@@@@+@$$$$@.", +".+#####+++@@@@+++@@@@++@$$$$$$+.", +".+######++++@@@@@@@++@$$$$$$$$+.", +".+#######+##+@@@@+++$$$$$$@@$$+.", +".+###+++##+##+@@++@$$$$$$++$$$+.", +".+###++++##+##+@@$$$$$$$@+@$$@+.", +".+###++++++#+++@$$@+@$$@++$$$@+.", +".+####+++++++#++$$@+@$$++$$$$+..", +".++####++++++#++$$@+@$++@$$$$+..", +".+#####+++++##++$$++@+++$$$$$+..", +".++####+++##+#++$$+++++@$$$$$+..", +".++####+++####++$$++++++@$$$@+..", +".+#####++#####++$$+++@++++@$@+..", +".+#####++#####++$$++@$$@+++$@@..", +".++####++#####++$$++$$$$$+@$@++.", +".++####++#####++$$++$$$$$$$$+++.", +".+++####+#####++$$++$$$$$$$@+++.", +"..+++#########+@$$+@$$$$$$+++...", +"...+++########+@$$$$$$$$@+++....", +".....+++######+@$$$$$$$+++......", +"......+++#####+@$$$$$@++........", +".......+++####+@$$$$+++.........", +".........++###+$$$@++...........", +"..........++##+$@+++............", +"...........+++++++..............", +".............++++..............."}; + + Aspect Frames

@@ -5088,7 +5504,7 @@ GtkWidget *gtk_aspect_frame_new( const gchar *label, gint obey_child); - Creating a GtkCList widget @@ -5349,7 +5765,7 @@ The GtkJustification type can take the following values: GTK_JUSTIFY_FILL - The text will use up all available space in the column. It is normally done by inserting extra blank spaces between words -(or between inidvidual letters of it's a single word). Much in the same way as +(or between individual letters if it's a single word). Much in the same way as any ordinary WYSIWYG text editor. @@ -5515,7 +5931,7 @@ void gtk_clist_set_pixtext( GtkCList *clist, It's quite straightforward. All the calls have the GtkCList as the first -argument, followed by the row and column of the cell, follwed by the data to be +argument, followed by the row and column of the cell, followed by the data to be set. The gint8 spacing argument in gtk_clist_set_pixtext is the number of pixels between the pixmap and the beginning of the text. @@ -5593,7 +6009,7 @@ void gtk_clist_set_shift( GtkCList *clist, Storing data pointers

With a GtkCList it is possible to set a data pointer for a row. This -pointer will not be visible for the user, but is merely a convinience for +pointer will not be visible for the user, but is merely a convenience for the programmer to associate a row with a pointer to some additional data. The functions should be fairly self-explanatory by now @@ -5730,7 +6146,7 @@ gint main (int argc, gchar *argv[]) clist = gtk_clist_new_with_titles( 2, titles); /* When a selection is made, we want to know about it. The callback - * used is selection_made, and it's code can be found further down */ + * used is selection_made, and its code can be found further down */ gtk_signal_connect(GTK_OBJECT(clist), "select_row", GTK_SIGNAL_FUNC(selection_made), NULL); @@ -5873,11 +6289,11 @@ NOTE: The GtkList widget has been superseded by the GtkCList widget. The GtkList widget is designed to act as a vertical container for widgets that should be of the type GtkListItem. -A GtkList widget has its own window to receive events and it's own -background color which is usualy white. As it is directly derived from a +A GtkList widget has its own window to receive events and its own +background color which is usually white. As it is directly derived from a GtkContainer it can be treated as such by using the GTK_CONTAINER(List) macro, see the GtkContainer widget for more on this. -One should already be familar whith the usage of a GList and its +One should already be familiar with the usage of a GList and its related functions g_list_*() to be able to use the GtkList widget to it full extent. @@ -5895,7 +6311,7 @@ struct _GtkList The selection field of a GtkList points to a linked list of all items -that are curently selected, or NULL if the selection is empty. +that are currently selected, or NULL if the selection is empty. So to learn about the current selection we read the GTK_LIST()->selection field, but do not modify it since the internal fields are maintained by the gtk_list_*() functions. @@ -6165,7 +6581,7 @@ gint main (int argc, gchar *argv[]) gtk_container_add(GTK_CONTAINER(window), vbox); gtk_widget_show(vbox); - /* this is the scolled window to put the GtkList widget inside */ + /* this is the scrolled window to put the GtkList widget inside */ scrolled_window=gtk_scrolled_window_new(NULL, NULL); gtk_widget_set_usize(scrolled_window, 250, 150); gtk_container_add(GTK_CONTAINER(vbox), scrolled_window); @@ -6194,7 +6610,7 @@ gint main (int argc, gchar *argv[]) gtk_widget_show(frame); /* connect the sigh_button_event() signal handler to the GtkList - * wich will handle the "arresting" of list items + * which will handle the "arresting" of list items */ gtk_signal_connect(GTK_OBJECT(gtklist), "button_release_event", @@ -6207,8 +6623,8 @@ gint main (int argc, gchar *argv[]) gtk_container_add(GTK_CONTAINER(vbox), separator); gtk_widget_show(separator); - /* finaly create a button and connect itīs "clicked" signal - * to the destroyment of the window + /* finally create a button and connect itīs "clicked" signal + * to the destruction of the window */ button=gtk_button_new_with_label("Close"); gtk_container_add(GTK_CONTAINER(vbox), button); @@ -6265,7 +6681,7 @@ gint main (int argc, gchar *argv[]) } gtk_list_append_items(GTK_LIST(gtklist), dlist); - /* finaly we want to see the window, donīt we? ;) + /* finally we want to see the window, don't we? ;) */ gtk_widget_show(window); @@ -6304,7 +6720,7 @@ sigh_button_event (GtkWidget *gtklist, else new_prisoner=NULL; - /* look for already prisoned list items, we + /* look for already imprisoned list items, we * will put them back into the list * remember to free the doubly linked list that * gtk_container_children() returns @@ -6393,12 +6809,12 @@ to one child, providing functions for selection/deselection just like the GtkList widget requires them for its children. A GtkListItem has its own window to receive events and has its own -background color which is usualy white. +background color which is usually white. As it is directly derived from a GtkItem it can be treated as such by using the GTK_ITEM(ListItem) macro, see the GtkItem widget for more on this. -Usualy a GtkListItem just holds a label to identify e.g. a filename +Usually a GtkListItem just holds a label to identify e.g. a filename within a GtkList -- therefore the convenience function gtk_list_item_new_with_label() is provided. The same effect can be achieved by creating a GtkLabel on its own, setting its alignment @@ -6442,7 +6858,7 @@ GtkWidget object. NULL is returned on failure. void gtk_list_item_select( GtkListItem *list_item ); -This function is basicaly a wrapper around a call to +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. @@ -6451,7 +6867,7 @@ select signal. void gtk_list_item_deselect( GtkListItem *list_item ); -This function is basicaly a wrapper around a call to +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. @@ -6816,10 +7232,10 @@ to its subtrees, and can't be set exclusively to a subtree (this is not exactly true - see the example code comments). The term "view mode" is rather ambiguous - basically, it controls the -way the hilight is drawn when one of a tree's children is selected. +way the highlight is drawn when one of a tree's children is selected. If it's GTK_TREE_VIEW_LINE, the entire GtkTreeItem widget is -hilighted, while for GTK_TREE_VIEW_ITEM, only the child widget -(i.e. usually the label) is hilighted. +highlighted, while for GTK_TREE_VIEW_ITEM, only the child widget +(i.e. usually the label) is highlighted. void gtk_tree_set_view_lines( GtkTree *tree, @@ -7025,7 +7441,7 @@ GtkWidget object. NULL is returned on failure. void gtk_tree_item_select( GtkTreeItem *tree_item ); -This function is basicaly a wrapper around a call to +This function is basically a wrapper around a call to gtk_item_select (GTK_ITEM (tree_item)) which will emit the select signal. @@ -7033,7 +7449,7 @@ select signal. void gtk_tree_item_deselect( GtkTreeItem *tree_item ); -This function is basicaly a wrapper around a call to +This function is basically a wrapper around a call to gtk_item_deselect (GTK_ITEM (tree_item)) which will emit the deselect signal. @@ -7089,7 +7505,7 @@ Determine if a generic pointer refers to a `GtkTreeItem' object. GtkWidget GTK_TREE_ITEM_SUBTREE (gpointer obj) -Return's a tree item's subtree (obj should point to a `GtkTreeItem' +Returns a tree item's subtree (obj should point to a `GtkTreeItem' object). Tree Example @@ -7228,7 +7644,7 @@ int main (int argc, char *argv[]) g_print ("-> item %s->%p, subtree %p\n", itemnames[i], item, subtree); - /* This is still necesary if you want these signals to be called + /* This is still necessary if you want these signals to be called for the subtree's children. Note that selection_change will be signalled for the root tree regardless. */ gtk_signal_connect (GTK_OBJECT(subtree), "select_child", @@ -7309,9 +7725,9 @@ There are three widgets that go into making a menubar and submenus: This is slightly complicated by the fact that menu item widgets are used -for two different things. They are both the widets that are packed into +for two different things. They are both the widgets that are packed into the menu, and the widget that is packed into the menubar, which, -when selected, activiates the menu. +when selected, activates the menu. Let's look at the functions that are used to create menus and menubars. This first function is used to create a new menubar. @@ -7845,7 +8261,7 @@ GtkWidget *gtk_text_new( GtkAdjustment *hadj, 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 it's own. +function to create its own. void gtk_text_set_adjustments( GtkText *text, @@ -7856,7 +8272,7 @@ void gtk_text_set_adjustments( GtkText *text, The above function allows the horizontal and vertical adjustments of a Text widget to be changed at any time. -The text widget will not automatically create it's own scrollbars when +The text widget will not automatically create its own scrollbars when 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. @@ -7892,7 +8308,7 @@ two modes. You can toggle the editable state of the text widget at any time, and can insert text at any time. The text widget wraps lines of text that are too long to -fit onto a single line of the display window. It's default behaviour is +fit onto a single line of the display window. Its default behaviour is to break words across line breaks. This can be changed using the next function: @@ -8000,7 +8416,7 @@ to free it with a call to g_free when you have finished with it. Keyboard Shortcuts

-The text widget has a number of pre-installed keyboard shotcuts for common +The text widget has a number of pre-installed keyboard shortcuts for common editing, motion and selection functions. These are accessed using Control and Alt key combinations. @@ -8008,7 +8424,7 @@ In addition to these, holding down the Control key whilst using cursor key movement will move the cursor by words rather than characters. Holding down Shift whilst using cursor movement will extend the selection. -Motion Shotcuts +Motion Shortcuts

Ctrl-A Beginning of line @@ -8238,16 +8654,13 @@ If you must use one of these widgets that are undocumented, I strongly suggest you take a look at their respective header files in the GTK distribution. GTK's function names are very descriptive. Once you have an understanding of how things work, it's not difficult to figure out how to -use a widget simply by looking at it's function declarations. This, along +use a widget simply by looking at its function declarations. This, along with a few examples from others' code, and it should be no problem. When you do come to understand all the functions of a new undocumented -widget, please consider writing a tutorial on it so others may benifit +widget, please consider writing a tutorial on it so others may benefit from your time. - - Toolbar -

Fixed Container

@@ -8283,19 +8696,19 @@ But there's more. Previews allow for side-by-side pre-previews. In other words, you write a plug-in (e.g. the filterpack simulation) which would have a number of here's-what-it-would-look-like-if-you-were-to-do-this previews. An approach like this acts as a sort of a preview palette and is very -effective fow subtle changes. Let's go previews! +effective for subtle changes. Let's go previews! There's more. For certain plug-ins real-time image-specific human intervention maybe necessary. In the SuperNova plug-in, for example, the user is asked to enter the coordinates of the center of the future supernova. The easiest way to do this, really, is to present the user with a -preview and ask him to intereactively select the spot. Let's go previews! +preview and ask him to interactively select the spot. Let's go previews! Finally, a couple of misc uses. One can use previews even when not working -with big images. For example, they are useful when rendering compicated +with big images. For example, they are useful when rendering complicated patterns. (Just check out the venerable Diffraction plug-in + many other ones!) As another example, take a look at the colormap rotation plug-in -(work in progress). You can also use previews for little logo's inside you +(work in progress). You can also use previews for little logos inside you plug-ins and even for an image of yourself, The Author. Let's go previews! When Not to Use Previews @@ -8314,7 +8727,7 @@ necessary borders. [Image][Image] Previews in many ways are like any other widgets in GTK (whatever that -means) except they possess an addtional feature: they need to be filled with +means) except they possess an additional feature: they need to be filled with some sort of an image! First, we will deal exclusively with the GTK aspect of previews and then we'll discuss how to fill them. @@ -8366,7 +8779,7 @@ this case you may want to pass a pointer to the preview to a One more important note that may one day save you a lot of time. Sometimes it is desirable to label you preview. For example, you may label the preview containing the original image as "Original" and the one containing the -modified image as "Less Original". It might occure to you to pack the +modified image as "Less Original". It might occur to you to pack the preview along with the appropriate label into a vbox. The unexpected caveat is that if the label is wider than the preview (which may happen for a variety of reasons unforseeable to you, from the dynamic decision on the @@ -8377,7 +8790,7 @@ situations as well. [Image] The solution is to place the preview and the label into a 2x1 table and by -attaching them with the following paramters (this is one possible variations +attaching them with the following parameters (this is one possible variations of course. The key is no GTK_FILL in the second attachment): gtk_table_attach(GTK_TABLE(table),label,0,1,0,1, @@ -8453,7 +8866,7 @@ For the GIMP users I have a few pointers to add. Image Preview -It is probably wize to keep a reduced version of the image around with just +It is probably wise to keep a reduced version of the image around with just enough pixels to fill the preview. This is done by selecting every n'th pixel where n is the ratio of the size of the image to the size of the preview. All further operations (including filling in the previews) are then @@ -8473,7 +8886,7 @@ typedef struct { enum { SELECTION_ONLY, - SELCTION_IN_CONTEXT, + SELECTION_IN_CONTEXT, ENTIRE_IMAGE }; @@ -8484,7 +8897,7 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, { /* This function reduced the image down to the the selected preview size */ /* The preview size is determine by LongerSize, i.e. the greater of the */ - /* two dimentions. Works for RGB images only! */ + /* two dimensions. Works for RGB images only! */ gint RH, RW; /* Reduced height and reduced width */ gint width, height; /* Width and Height of the area being reduced */ gint bytes=drawable->bpp; @@ -8515,7 +8928,7 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, y2=drawable->height; } - /* If we want to preview a selection with some surronding area we */ + /* If we want to preview a selection with some surrounding area we */ /* have to expand it a little bit. Consider it a bit of a riddle. */ if (Selection==SELECTION_IN_CONTEXT) { x1=MAX(0, x1-width/2.0); @@ -8542,7 +8955,7 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, RW=(float)width * (float) LongerSize/ (float) height; } - /* The intire image is stretched into a string! */ + /* The entire image is stretched into a string! */ tempRGB = (guchar *) malloc(RW*RH*bytes); tempmask = (guchar *) malloc(RW*RH); @@ -8586,8 +8999,8 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, } The following is a preview function which used the same ReducedImage type! -Note that it uses fakes transparancy (if one is present by means of -fake_transparancy which is defined as follows: +Note that it uses fakes transparency (if one is present by means of +fake_transparency which is defined as follows: gint fake_transparency(gint i, gint j) { @@ -8645,7 +9058,7 @@ void gtk_preview_size (GtkPreview *preview, gint width, gint height); /* Allows you to resize an existing preview. */ -/* Apparantly there's a bug in GTK which makes */ +/* Apparently there's a bug in GTK which makes */ /* this process messy. A way to clean up a mess */ /* is to manually resize the window containing */ /* the preview after resizing the preview. */ @@ -8702,9 +9115,9 @@ That's all, folks!

Some gtk widgets don't have associated X windows, so they just draw on -their parents. Because of this, they cannot recieve events +their parents. Because of this, they cannot receive events and if they are incorrectly sized, they don't clip so you can get -messy overwritting etc. If you require more from these widgets, the +messy overwriting etc. If you require more from these widgets, the EventBox is for you. At first glance, the EventBox widget might appear to be totally @@ -8714,7 +9127,7 @@ its child widget. This is important as many GTK widgets do not have an associated X window. Not having an X window saves memory and improves performance, but also has some drawbacks. A widget without an X window cannot receive events, and does not perform any clipping on -it's contents. Although the name gdk_atom_intern(), to get the atom corresponding to a string, and gdk_atom_name(), to get the name of an atom. Both -selections and targets are identifed by atoms. +selections and targets are identified by atoms. Retrieving the selection @@ -9226,7 +9639,7 @@ get_targets (GtkWidget *widget, gpointer data) { static GdkAtom targets_atom = GDK_NONE; - /* Get the atom corresonding to the string "TARGETS" */ + /* Get the atom corresponding to the string "TARGETS" */ if (targets_atom == GDK_NONE) targets_atom = gdk_atom_intern ("TARGETS", FALSE); @@ -9520,7 +9933,7 @@ G_MAXLONG 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! Eg, a pointer on an Alpha is 8 bytes, but 4 +pointer if you want to be portable! E.g., a pointer on an Alpha is 8 bytes, but 4 on Intel. @@ -9653,7 +10066,7 @@ gpointer g_malloc( gulong size ); This is a replacement for malloc(). You do not need to check the return -vaule as it is done for you in this function. +value as it is done for you in this function. gpointer g_malloc0( gulong size ); @@ -9679,7 +10092,7 @@ Frees memory. Easy one. void g_mem_profile( void ); -Dumps a profile of used memory, but requries that you add #define +Dumps a profile of used memory, but requires that you add #define MEM_PROFILE to the top of glib/gmem.c and re-make and make install. @@ -9819,7 +10232,7 @@ to document any function, just send me an email! GTK's rc Files

-GTK has it's own way of dealing with application defaults, by using rc +GTK has its own way of dealing with application defaults, by using rc files. These can be used to set the colors of just about any widget, and can also be used to tile pixmaps onto the background of some widgets. @@ -9926,7 +10339,7 @@ doesn't matter if it's not recognized. Unrecognized values are set to 0. bg_pixmap is very similar to the above, except the colors are replaced by a filename. -pixmap_path is a list of paths seperated by ":"'s. These paths will be +pixmap_path is a list of paths separated by ":"'s. These paths will be searched for any pixmap you specify. The font directive is simply: @@ -9940,7 +10353,7 @@ similar utility should help. The "widget_class" sets the style of a class of widgets. These classes are listed in the widget overview on the class hierarchy. -The "widget" directive sets a specificaly named set of widgets to a +The "widget" directive sets a specifically named set of widgets to a given style, overriding any style set for the given widget class. These widgets are registered inside the application using the gtk_widget_set_name() call. This allows you to specify the attributes of a @@ -9949,7 +10362,7 @@ entire widget class. I urge you to document any of these special widgets so users may customize them. When the keyword parent is used as an attribute, the widget will take on -the attributes of it's parent in the application. +the attributes of its parent in the application. When defining a style, you may assign the attributes of a previously defined style to this new one. @@ -10030,7 +10443,7 @@ style "scale" fg[NORMAL] = { 1.0, 0, 0 } - #Sets the background pixmap of this widget to that of it's parent. + #Sets the background pixmap of this widget to that of its parent. bg_pixmap[NORMAL] = "" } @@ -10064,7 +10477,7 @@ style "toggle_button" = "button" fg[NORMAL] = { 1.0, 0, 0 } fg[ACTIVE] = { 1.0, 0, 0 } - # This sets the background pixmap of the toggle_button to that of it's + # This sets the background pixmap of the toggle_button to that of its # parent widget (as defined in the application). bg_pixmap[NORMAL] = "" } @@ -10097,7 +10510,7 @@ widget_class "*Ruler" style "ruler" widget_class "*GtkText" style "text" # This sets all the buttons that are children of the "main window" to -# the main_buton style. These must be documented to be taken advantage of. +# the main_button style. These must be documented to be taken advantage of. widget "main window.*GtkButton*" style "main_button" @@ -10110,7 +10523,7 @@ widget "main window.*GtkButton*" style "main_button"

Although the GTK distribution comes with many types of widgets that should cover most basic needs, there may come a time when you need to -create your own new widget type. Since GTK uses widget inheretence +create your own new widget type. Since GTK uses widget inheritance extensively, and there is already a widget that is close to what you want, it is often possible to make a useful new widget type in just a few lines of code. But before starting work on a new widget, check @@ -10491,7 +10904,7 @@ instead. After creating our signals, we need to tell GTK to associate our signals with the Tictactoe class. We do that by calling @@ -10724,7 +11137,7 @@ an Changes to the Adjustment by external means are communicated to our -widget by the ``changed'' and ``value_changed'' signals. The handlers +widget by the `changed' and `value_changed' signals. The handlers for these functions call @@ -11797,7 +12210,7 @@ void gtk_drawing_area_size (GtkDrawingArea *darea, gint height); -This default size can be overriden, as is true for all widgets, +This default size can be overridden, as is true for all widgets, by calling gtk_widget_set_usize(), and that, in turn, can be overridden if the user manually resizes the the window containing the drawing area. @@ -12269,7 +12682,7 @@ GList *gdk_input_list_devices (void); which returns a GList (a linked list type from the glib library) -of GdkDeviceInfo structures. The GdkDeviceInfo strucure is defined +of GdkDeviceInfo structures. The GdkDeviceInfo structure is defined as: @@ -12326,7 +12739,7 @@ print_button_press (guint32 deviceid) } -That completes the changes to ``XInputize'' our program. As with +That completes the changes to `XInputize' our program. As with the first version, the complete source is available at the location from which you got this tutorial, or from: @@ -12367,7 +12780,7 @@ applications. This probably belongs at a slightly higher level than GTK, perhaps in the GNOME library.

-Another major ommission that we have mentioned above is the lack of +Another major omission that we have mentioned above is the lack of cursor drawing. Platforms other than XFree86 currently do not allow simultaneously using a device as both the core pointer and directly by an application. See the -An application that draws it's own cursor needs to do two things: +An application that draws its own cursor needs to do two things: determine if the current device needs a cursor drawn or not, and determine if the current device is in proximity. (If the current device is a drawing tablet, it's a nice touch to make the cursor @@ -12394,7 +12807,7 @@ found in the 'testinput' program found in the GTK distribution.

This section is simply a gathering of wisdom, general style guidelines and hints to -creating good GTK applications. It is totally useless right now cause it's +creating good GTK applications. It is totally useless right now cause its only a topic sentence :) Use GNU autoconf and automake! They are your friends :) I am planning to @@ -12502,10 +12915,10 @@ versions.

If you are intending to incorporate this document into a published work, please contact the maintainer, and we will make an effort to ensure that you have the most up to date information available. -

There is no guarentee that this document lives up to its intended +

There is no guarantee that this document lives up to its intended purpose. This is simply provided as a free resource. As such, the authors and maintainers of the information provided within can -not make any guarentee that the information is even accurate. +not make any guarantee that the information is even accurate. @@ -13376,7 +13789,7 @@ void gtk_dial_set_adjustment (GtkDial *dial, #define SCROLL_DELAY_LENGTH 300 #define DIAL_DEFAULT_SIZE 100 -/* Forward declararations */ +/* Forward declarations */ static void gtk_dial_class_init (GtkDialClass *klass); static void gtk_dial_init (GtkDial *dial); diff --git a/docs/tutorial/gtk_tut.sgml b/docs/tutorial/gtk_tut.sgml index b17bb492c1..85215bb46c 100644 --- a/docs/tutorial/gtk_tut.sgml +++ b/docs/tutorial/gtk_tut.sgml @@ -10,7 +10,7 @@ name="<imain@gtk.org>">, Tony Gale -August 13th, 1998 +September 2nd, 1998 Introduction @@ -175,7 +175,7 @@ void hello (GtkWidget *widget, gpointer data) gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data) { - g_print ("delete event occured\n"); + g_print ("delete event occurred\n"); /* if you return FALSE in the "delete_event" signal handler, * GTK will emit the "destroy" signal. Returning TRUE means * you don't want the window to be destroyed. @@ -228,7 +228,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("Hello World"); /* When the button receives the "clicked" signal, it will call the - * function hello() passing it NULL as it's argument. The hello() function is + * function hello() passing it NULL as its argument. The hello() function is * defined above. */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (hello), NULL); @@ -411,7 +411,7 @@ attached to these events. These events are: In order to connect a callback function to one of these events, you use the function gtk_signal_connect, as described above, using one of the above event names as the void callback_func( GtkWidget *widget, @@ -420,7 +420,7 @@ void callback_func( GtkWidget *widget, GdkEvent is a C -This callback is a bit special. The "delete_event" occurs when the +The next callback is a bit special. The "delete_event" occurs when the window manager sends this event to the application. We have a choice here as to what to do about these events. We can ignore them, make some sort of response, or simply quit the application. @@ -526,7 +526,7 @@ signal handler. gint delete_event(GtkWidget *widget, GdkEvent *event, gpointer data) { - g_print ("delete event occured\n"); + g_print ("delete event occurred\n"); return (TRUE); } @@ -653,7 +653,7 @@ which are designed to layout multiple widgets in various ways. gtk_container_add (GTK_CONTAINER (window), button); -Now that we have everything setup the way we want it to be. With all the +Now we have everything set up the way we want it to be. With all the signal handlers in place, and the button placed in the window where it should be, we ask GTK to "show" the widgets on the screen. The window widget is shown last so the whole window will pop up at once rather than @@ -685,7 +685,7 @@ information, our program sets up a signal handler to catch that signal, which dispatches the function of our choice. In our example, when the button we created is "clicked", the hello() function is called with a NULL argument, and then the next handler for this signal is called. This calls -the gtk_widget_destroy() function, passing it the window widget as it's +the gtk_widget_destroy() function, passing it the window widget as its argument, destroying the window widget. This causes the window to emit the "destroy" signal, which is caught, and calls our destroy() callback function, which simply exits GTK. @@ -821,7 +821,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("Button 1"); /* Now when the button is clicked, we call the "callback" function - * with a pointer to "button 1" as it's argument */ + * with a pointer to "button 1" as its argument */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 1"); @@ -1305,7 +1305,7 @@ widget in the table. If homogeneous is FALSE, the size of a table boxes is dictated by the tallest widget in its same row, and the widest widget in its column. -The rows and columnts are laid out from 0 to n, where n was the +The rows and columns are laid out from 0 to n, where n was the number specified in the call to gtk_table_new. So, if you specify rows = 2 and columns = 2, the layout would look something like this: @@ -1486,7 +1486,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("button 1"); /* when the button is clicked, we call the "callback" function - * with a pointer to "button 1" as it's argument */ + * with a pointer to "button 1" as its argument */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 1"); @@ -1501,7 +1501,7 @@ int main (int argc, char *argv[]) button = gtk_button_new_with_label ("button 2"); /* when the button is clicked, we call the "callback" function - * with a pointer to "button 2" as it's argument */ + * with a pointer to "button 2" as its argument */ gtk_signal_connect (GTK_OBJECT (button), "clicked", GTK_SIGNAL_FUNC (callback), (gpointer) "button 2"); /* insert button 2 into the upper right quadrant of the table */ @@ -1602,7 +1602,7 @@ of these widgets may be used with the GTK_CONTAINER macro to pass them to functions that ask for containers. Unfortunately, these macros are not extensively covered in the tutorial, but I -recomend taking a look through the GTK header files. It can be very +recommend taking a look through the GTK header files. It can be very educational. In fact, it's not difficult to learn how a widget works just by looking at the function declarations. @@ -1735,7 +1735,7 @@ gtk/testgtk.c. Normal Buttons

We've almost seen all there is to see of the button widget. It's pretty -simple. There is however two ways to create a button. You can use the +simple. There are however two ways to create a button. You can use the gtk_button_new_with_label() to create a button with a label, or use gtk_button_new() to create a blank button. It's then up to you to pack a label or pixmap into this new button. To do this, create a new box, and @@ -1743,7 +1743,7 @@ then pack your objects into this box using the usual gtk_box_pack_start, and then use gtk_container_add to pack the box into the button. Here's an example of using gtk_button_new to create a button with a -picture and a label in it. I've broken the code to create a box up from +picture and a label in it. I've broken up the code to create a box from the rest so you can use it in your programs. @@ -1857,7 +1857,7 @@ int main (int argc, char *argv[]) The xpm_label_box function could be used to pack xpm's and labels into any widget that can be a container. -The Buton widget has the following signals: +The Button widget has the following signals: pressed @@ -1896,7 +1896,7 @@ buttons, we use a macro as shown in our example below. This tests the state of the toggle in a callback. The signal of interest emitted to us by toggle buttons (the toggle button, check button, and radio button widgets), is the "toggled" signal. To check the state of these buttons, set up a signal -handler to catch the toggled signal, and use the macro to determine it's +handler to catch the toggled signal, and use the macro to determine its state. The callback will look something like: @@ -1918,10 +1918,10 @@ void gtk_toggle_button_set_state( GtkToggleButton *toggle_button, gint state ); -The above call can be used to set the state of the toggle button, and it's +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 button as the first argument, and a TRUE or FALSE for the second state argument to -specify whether it should be up (released) or down (depressed). Default +specify whether it should be down (depressed) or up (released). Default is up, or FALSE. Note that when you use the gtk_toggle_button_set_state() function, and the @@ -1956,7 +1956,7 @@ Checking the state of the check button is identical to that of the toggle button. - Radio Buttons + Radio Buttons

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 places in @@ -1972,7 +1972,9 @@ GtkWidget *gtk_radio_button_new_with_label( GSList *group, You'll notice the extra argument to these calls. They require a group to -perform they're duty properly. The first call should pass NULL as the first +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: @@ -2086,185 +2088,49 @@ removes the need for a variable to hold the list of buttons: "button2"); - + -Range Widgets + Adjustments

-The category of range widgets includes the ubiquitous scrollbar -widget and the less common scale widget. Though these two -types of widgets are typically used for vastly different -purposes, they are quite similar in function and implementation. -Range widgets allow the user to visually manipulate a value -within a specified range (hence the name). +GTK+ has various widgets that can be visually adjusted by the user +using the mouse or the keyboard, such as the range widgets, described +in the section. There +are also a few widgets that display some adjustable portion of a larger +area of data, such as the text widget and the viewport widget. -All range widgets share a set of common graphic elements, each -of which has its own X window and receives events. They all -contain a "trough" and a "slider" (what is sometimes called a -"thumbwheel" in other GUI environments). Dragging the slider -with the pointer moves it back and forth within the trough, -while clicking in the trough advances the slider towards the -location of the click, either completely, or by a designated -amount (called a "page"), depending on which button was used. +Obviously, an application needs to be able to react to changes the +user makes in range widgets. One way to do this would be to have each +widget emit its own type of signal when its adjustment changes, and +either pass the new value to the signal handler, or require it to look +inside the widget's data structure in order to ascertain the value. +But you may also want to connect the adjustments of several widgets +together, so that adjusting one adjusts the others. The most obvious +example of this is connecting a scrollbar to a panning viewport or a +scrolling text area. If each widget has its own way of setting or +getting the adjustment value, then the programmer may have to write +their own signal handlers to translate between the output of one +widget's signal and the "input" of another's adjustment setting +function. - -The Scale Widgets -

-Scale widgets are used to set an explicitly numeric parameter -which has a visual correlate, and which the user might be -expected to adjust primarily by sight. For example, the -GtkColorSelection compound widget contains scale widgets which -control the components of the colour being selected. -Typically, the precise value of the number is less important -here than its side-effects, and thus the user should be spared -the effort of reaching for the keyboard. +GTK+ solves this problem using the GtkAdjustment object, which is a +way for widgets to store and pass adjustment information in an +abstract and flexible form. The most obvious use of GtkAdjustment is +to store the configuration parameters and values of range widgets, +such as scrollbars and scale controls. However, since GtkAdjustments +are derived from GtkObject, they have some special powers beyond those +of normal data structures. Most importantly, they can emit signals, +just like widgets, and these signals can be used not only to allow +your program to react to user input on adjustable widgets, but also to +propagate adjustment values transparently between adjustable widgets. - -Creating a Scale Widget -

-There are actually two types of scale widget: GtkHScale -widgets, which are horizontal, and GtkVScale widgets, which - -are vertical. (Most programmers seem to favour horizontal -scale widgets). Since they work essentially the same way, -there's no need to treat them separately here. The -following functions, defined in -<gtk/gtkvscale.h> and -<gtk/gtkhscale.h>, create vertical and -horizontal scale widgets, respectively: - - -GtkWidget* gtk_vscale_new( GtkAdjustment *adjustment ); - -GtkWidget* gtk_hscale_new( GtkAdjustment *adjustment ); - - - -below for an explanation of what exactly the -Functions, Signals, and Macros -

-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: - - -void gtk_scale_set_draw_value( GtkScale *scale, - gint draw_value ); - - -As you might have guessed, -void gtk_scale_set_digits( GtkScale *scale, - gint digits); - - -where -void gtk_scale_set_value_pos( GtkScale *scale, - GtkPositionType pos ); - - -If you've read the section on the notebook widget, then you -know what the possible values of GtkPositionType and can take one -of the following values: - - -GTK_POS_LEFT -GTK_POS_RIGHT -GTK_POS_TOP -GTK_POS_BOTTOM - - -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 slider up and down -the trough. - -All the preceding functions are defined in -<gtk/gtkscale.h>. The other signals and -functions defined in the header files for the scale widgets -are either not useful for anyone other than writers of scale -widgets, or are the standard GTK+ type-casting macros and -functions. - - -The Scrollbar Widgets -

-These are your standard, run-of-the-mill scrollbars. As with -the scale widgets, there are separate types for horizontal and -vertical scrollbars. There really isn't much to say about -these. You create them with the following functions: - - -GtkWidget* gtk_hscrollbar_new( GtkAdjustment *adjustment ); - -GtkWidget* gtk_vscrollbar_new( GtkAdjustment *adjustment ); - - -and that's about it (if you don't believe me, look in the -header files!). Again, -The Adjustment Object

-As you might have noticed, there really isn't much to the -various range widgets themselves from the programmer's point -of view. Most of your program's interaction with these -widgets will take place by way of the heretofore mysterious - -Creating a GtkAdjustment + Creating an Adjustment

You create an adjustment using: - + -GtkObject* gtk_adjustment_new( gfloat value, +GtkObject *gtk_adjustment_new( gfloat value, gfloat lower, gfloat upper, gfloat step_increment, @@ -2272,69 +2138,68 @@ GtkObject* gtk_adjustment_new( gfloat value, gfloat page_size ); -It may or may not be obvious by now that the values given to - below -describes the default key and mouse bindings for range -widgets, and how they relate to these increments. The - -GtkObject *adj; - -adj = gtk_adjustment_new (0, first_line, last_line, 1, - window_height - 2, window_height); - - -where last_line - -window_height (or, in more general terms, upper - -page_height). This is a little confusing at first, but -it makes sense if you think about it in terms of what the -user expects to see in a scrolled window when the -scrollbar's slider is moved all the way to the end of the -trough. - -Since the size of the slider on scale widgets is invariable, -to avoid excessive confusion, it's a good idea to set the - -Inside the GtkAdjustment object + Using Adjustments the Easy Way

-OK, you say, that's nice, but how do I get at all these -values, and, more importantly, how do I know when the user -has moved the slider around? To answer these questions and -more, let's start by taking a look at + /* 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); + + + + + Adjustment Internals +

+OK, you say, that's nice, but what if I want to create my own handlers +to respond when the user adjusts a range widget or a spin button, and +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 +struct _GtkAdjustment itself: struct _GtkAdjustment @@ -2348,53 +2213,43 @@ struct _GtkAdjustment gfloat page_increment; gfloat page_size; }; - -struct _GtkAdjustmentClass -{ - GtkDataClass parent_class; - - void (* changed) (GtkAdjustment *adjustment); - void (* value_changed) (GtkAdjustment *adjustment); -}; -The first thing you should know is that there aren't any -handy-dandy macros or accessor functions for getting the -GTK_ADJUSTMENT (Object) macro does -run-time type checking (as do all the GTK+ type-casting -macros, actually). On the other hand, unless you're writing -a new type of range widget, you probably don't want to -GTK_ADJUSTMENT +(Object) macro does run-time type checking (as do all the GTK+ +type-casting macros, actually). + +Since, when you set the void gtk_adjustment_set_value( GtkAdjustment *adjustment, gfloat value ); -If you need to change the other fields, and you don't intend -to do this very frequently, it's best to create a new -GtkAdjustment and set it with - below. +As mentioned earlier, GtkAdjustment is a subclass of GtkObject just +like all the various widgets, and thus it is able to emit signals. +This is, of course, why updates hapen automagically when you share an +adjustment object between a scrollbar and another adjustable widget; +all adjustable widgets connect signal handlers to their adjustment's + + void (* value_changed) (GtkAdjustment *adjustment); + -The various widgets that use the GtkAdjustment object will -emit the "value_changed" signal on an adjustment whenever -they change its value (see below for more detail). This -happens both when user input causes the slider to move on a -range widget, as well as when the program explicitly changes -the value with void cb_rotate_picture (GtkAdjustment *adj, GtkWidget *picture) @@ -2410,163 +2265,320 @@ gtk_signal_connect (GTK_OBJECT (adj), "value_changed", GTK_SIGNAL_FUNC (cb_rotate_picture), picture); -The "changed" signal is somewhat more elusive. It is never -emitted directly due to the -Common Functions, Signals, and Macros

-The GtkRange widget class is fairly complicated internally, -but, like all the "base class" widgets, most of its complexity -is only interesting if you want to hack on it. Also, almost -all of the functions and signals it defines are only really -used in writing derived widgets. There are, however, a few -useful functions and concepts that are defined in gtkrange.h -and are common to all range widgets. - - -Update Policies

-The "update policy" of a range widget defines at what points -during user interaction it will change the <gtk/gtkenums.h> as the enum -GtkUpdateType, are: - - -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. - - -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. - - -GTK_UPDATE_POLICY_DELAYED - The "value_change" -signal is emitted when the user releases the mouse button, -or if the slider stops moving for a short period of -time. - - - -The update policy of a range widget can be set by casting it -using the GTK_RANGE (Widget) macro and passing it -to this function: +What about when a widget reconfigures the -void gtk_range_set_update_policy( GtkRange *range, - GtkUpdateType policy ); + void (* changed) (GtkAdjustment *adjustment); - -Getting and setting adjustments -

-Getting and setting the adjustment for a range widget "on -the fly" is done, predictably, with: - - -GtkAdjustment* gtk_range_get_adjustment( GtkRange *range ); +Range widgets typically connect a handler to this signal, which +changes their appearance to reflect the change - for example, the size +of the slider in a scrollbar will grow or shrink in inverse proportion +to the difference between the - - - gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed"); - -Key and Mouse bindings

-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 adjustment's + -The key bindings, by contrast, are slightly different -between horizontal and vertical range widgets, for obvious -reasons. They are also not quite the same for scale widgets -as they are for scrollbars, for somewhat less obvious -reasons (possibly to avoid confusion between the keys for -horizontal and vertical scrollbars in scrolled windows, -where both operate on the same area). + + Range Widgets

+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 +function and implementation. All range widgets share a set of common +graphic elements, each of which has its own X window and receives +events. They all contain a "trough" and a "slider" (what is sometimes +called a "thumbwheel" in other GUI environments). Dragging the slider +with the pointer moves it back and forth within the trough, while +clicking in the trough advances the slider towards the location of the +click, either completely, or by a designated amount, depending on +which mouse button is used. + +As mentioned in above, +all range widgets are associated with an adjustment object, from which +they calculate the length of the slider and it's position within the +trough. When the user manipulates the slider, the range widget +will change the value of the adjustment. -Vertical Range Widgets + Scrollbar Widgets

-All vertical range widgets can be operated with the up and -down arrow keys, as well as with the Control-Page Up and -Control-Page Down. +There are separate types for horizontal and vertical scrollbars. +There really isn't much to say about these. You create them with the +following functions, defined in <gtk/gtkhscrollbar.h> +and <gtk/gtkvscrollbar.h>: + + +GtkWidget *gtk_hscrollbar_new( GtkAdjustment *adjustment ); + +GtkWidget *gtk_vscrollbar_new( GtkAdjustment *adjustment ); + + +and that's about it (if you don't believe me, look in the header +files!). The -Horizontal Range Widgets + Scale Widgets

-The left and right arrow keys work as you might expect in -these widgets, moving the slider back and forth by -Control-Left and -Control-Right, while for GtkHScrollbar, it's done -with Control-Home and Control-End. +Scale widgets are used to allow the user to visually select and +manipulate a value within a specific range. You might want to use a +scale widget, for example, to adjust the magnification level on a +zoomed preview of a picture, or to control the brightness of a colour, +or to specify the number of minutes of inactivity before a screensaver +takes over the screen. -Example

-This example is a somewhat modified version of the "range -widgets" test from <gtk/gtkvscale.h> and +<gtk/gtkhscale.h>, create vertical and horizontal scale +widgets, respectively: + + + +GtkWidget *gtk_vscale_new( GtkAdjustment *adjustment ); + +GtkWidget *gtk_hscale_new( GtkAdjustment *adjustment ); + + + +The again for an explanation of +what exactly adjustments do and how to create and manipulate them). + + + Functions and Signals (well, functions, at least) +

+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: + + +void gtk_scale_set_draw_value( GtkScale *scale, + gint draw_value ); + + +As you might have guessed, + +void gtk_scale_set_digits( GtkScale *scale, + gint digits ); + + + +where + +void gtk_scale_set_value_pos( GtkScale *scale, + GtkPositionType pos ); + + + +If you've read the section on the notebook widget, then you already +know what the possible values of enum GtkPositionType in <gtk/gtkenums.h> and +are pretty self-explanatory. 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 slider up and down the trough. + +All the preceding functions are defined in +<gtk/gtkscale.h>. + + + + + Common Functions

+The GtkRange widget class is fairly complicated internally, but, like +all the "base class" widgets, most of its complexity is only +interesting if you want to hack on it. Also, almost all of the +functions and signals it defines are only really used in writing +derived widgets. There are, however, a few useful functions that +are defined in <gtk/gtkrange.h> and will work on all range widgets. + + + Setting the Update Policy +

+The "update policy" of a range widget defines at what points during +user interaction it will change the <gtk/gtkenums.h> as type enum GtkUpdateType, +are: + + +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. + +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. + +GTK_UPDATE_POLICY_DELAYED - The "value_change" signal is emitted +when the user releases the mouse button, or if the slider stops moving +for a short period of time. + + + +The update policy of a range widget can be set by casting it using the +GTK_RANGE (Widget) macro and passing it to this function: + + +void gtk_range_set_update_policy (GtkRange *range, + GtkUpdateType policy); + + + +Getting and Setting Adjustments +

+Getting and setting the adjustment for a range widget "on the fly" is +done, predictably, with: + + +GtkAdjustment* gtk_range_get_adjustment( GtkRange *range ); + +void gtk_range_set_adjustment( GtkRange *range, + GtkAdjustment *adjustment ); + + + +gtk_signal_emit_by_name (GTK_OBJECT (adjustment), "changed"); + + + + + + Key and Mouse bindings +

+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 +adjustment's +GTK_WIDGET_UNSET_FLAGS (scrollbar, GTK_CAN_FOCUS); + + +The key bindings (which are, of course, only active when the widget +has focus) are slightly different between horizontal and vertical +range widgets, for obvious reasons. They are also not quite the same +for scale widgets as they are for scrollbars, for somewhat less +obvious reasons (possibly to avoid confusion between the keys for +horizontal and vertical scrollbars in scrolled windows, where both +operate on the same area). + + Vertical Range Widgets +

+All vertical range widgets can be operated with the up and down arrow +keys, as well as with the Control-Page Up +and Control-Page Down. + + + Horizontal Range Widgets +

+The left and right arrow keys work as you might expect in these +widgets, moving the slider back and forth by Control-Left and Control-Right, +while for GtkHScrollbar, it's done with Control-Home and +Control-End. + + + + + Example

+This example is a somewhat modified version of the "range widgets" +test from /* example-start rangewidgets rangewidgets.c */ @@ -2856,9 +2868,11 @@ int main (int argc, char *argv[]) /* example-end */ + + - Miscallaneous Widgets + Miscellaneous Widgets @@ -2895,7 +2909,7 @@ void gtk_label_get( GtkLabel *label, char **str ); -Where the first arguement is the label you've created, and the second, the +Where the first argument is the label you've created, and the second, the return for the string. @@ -3155,7 +3169,7 @@ struct GtkDialog So you see, it simply creates a window, and then packs a vbox into the top, -then a seperator, and then an hbox for the "action_area". +then a separator, and then an hbox for 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 @@ -3204,7 +3218,7 @@ application, then you can simply pack another layout widget into the boxes provided. For example, you could pack a table into the vertical box. - Pixmaps + Pixmaps

Pixmaps are data structures that contain pictures. These pictures can be used in various places, but most visibly as icons on the X-Windows desktop, @@ -3966,14 +3980,14 @@ gchar *gtk_entry_get_text( GtkEntry *entry ); If we don't want the contents of the Entry to be changed by someone typing -into it, we can change it's editable state. +into it, we can change its editable state. void gtk_entry_set_editable( GtkEntry *entry, gboolean editable ); -This function allows us to toggle the edittable state of the Entry widget +This function allows us to toggle the editable state of the Entry widget by passing in a TRUE or FALSE value for the This function sets the update policy. The default policy is -GTK_UPDATE_CONTINOUS which means that the current color is updated -continously when the user drags the sliders or presses the mouse and drags +GTK_UPDATE_CONTINUOUS which means that the current color 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_DISCONTINOUS or +problems, you may want to set the policy to GTK_UPDATE_DISCONTINUOUS or GTK_UPDATE_DELAYED. @@ -4381,7 +4395,7 @@ 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 it's own. As you will see, there is nothing much to creating a file +on its own. As you will see, there is nothing much to creating a file selection widget. While in this example the Help button appears on the screen, it does nothing as there is not a signal attached to it. @@ -4442,7 +4456,7 @@ int main (int argc, char *argv[])

The NoteBook Widget is a collection of 'pages' that overlap each other, each page contains different information. This widget has become more common -lately in GUI programming, and it is a good way to show blocks similar +lately in GUI programming, and it is a good way to show blocks of similar information that warrant separation in their display. The first function call you will need to know, as you can probably @@ -4752,9 +4766,9 @@ GTK applications.

Scrolled windows are used to create a scrollable area inside a real window. You may insert any type of widget into a scrolled window, and it will -be accessable regardless of the size by using the scrollbars. +be accessible regardless of the size by using the scrollbars. -The following function is used to create a new scolled window. +The following function is used to create a new scrolled window. GtkWidget *gtk_scrolled_window_new( GtkAdjustment *hadjustment, @@ -4772,13 +4786,13 @@ void gtk_scrolled_window_set_policy( GtkScrolledWindow *scrolled_window, This sets the policy to be used with respect to the scrollbars. -The first arguement is the scrolled window you wish to change. The second -sets the policiy for the horizontal scrollbar, and the third the policy for +The first argument is the scrolled window you wish to change. The second +sets the policy for the horizontal scrollbar, and the third the policy for the vertical scrollbar. The policy may be one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS. GTK_POLICY_AUTOMATIC will automatically decide whether you need -scrollbars, wheras GTK_POLICY_ALWAYS will always leave the scrollbars +scrollbars, whereas GTK_POLICY_ALWAYS will always leave the scrollbars there. Here is a simple example that packs 100 toggle buttons into a scrolled window. @@ -4807,7 +4821,7 @@ int main (int argc, char *argv[]) /* Create a new dialog window for the scrolled window to be * packed into. A dialog is just like a normal window except it has a - * vbox and a horizontal seperator packed into it. It's just a shortcut + * vbox and a horizontal separator packed into it. It's just a shortcut * for creating dialogs */ window = gtk_dialog_new (); gtk_signal_connect (GTK_OBJECT (window), "destroy", @@ -4823,7 +4837,7 @@ int main (int argc, char *argv[]) /* the policy is one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS. * GTK_POLICY_AUTOMATIC will automatically decide whether you need - * scrollbars, wheras GTK_POLICY_ALWAYS will always leave the scrollbars + * scrollbars, whereas GTK_POLICY_ALWAYS will always leave the scrollbars * there. The first one is the horizontal scrollbar, the second, * the vertical. */ gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window), @@ -5067,6 +5081,408 @@ main (int argc, char *argv[]) /* example-end */ + +Toolbar +

+Toolbars are usually used to group some number of widgets in order to simplify +customization of their look and layout. Typically a toolbar consists of buttons +with icons, labels and tooltips, but any other widget can also +be put inside a toolbar. Finally, items can be arranged horizontally +or vertically and buttons can be displayed with icons, labels or both. + +Creating a toolbar is (as one may already suspect) done with the following +function: + + +GtkWidget *gtk_toolbar_new( GtkOrientation orientation, + GtkToolbarStyle style ); + + +where orientation may be one of: + + + GTK_ORIENTATION_HORIZONTAL + GTK_ORIENTATION_VERTICAL + + +and style one of: + + + GTK_TOOLBAR_TEXT + GTK_TOOLBAR_ICONS + GTK_TOOLBAR_BOTH + + +The style applies to all the buttons created with the `item' functions +(not to buttons inserted into toolbar as separate widgets). + +After creating a toolbar one can append,prepend and insert items (that +means simple buttons) into the toolbar. To describe an item we need a +label text, a tooltip text, a private tooltip text, an icon +for the button and a callback function for it. For example, to append +an item you may use the following function: + + +GtkWidget *gtk_toolbar_append_item( GtkToolbar *toolbar, + const char *text, + const char *tooltip_text, + const char *tooltip_private_text, + GtkWidget *icon, + GtkSignalFunc callback, + gpointer user_data ); + + +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. + +To simplify adding spaces between toolbar items, you may use the following +function: + + +void gtk_toolbar_append_space( GtkToolbar *toolbar ); + +void gtk_toolbar_prepend_space( GtkToolbar *toolbar ); + +void gtk_toolbar_insert_space( GtkToolbar *toolbar, + gint position ); + + + +While the size of the added space can be set globally for a +whole toolbar with the function: + + +void gtk_toolbar_set_space_size( GtkToolbar *toolbar, + gint space_size) ; + + +If it's needed the orientation of a toolbar and its style can be changed +`on the fly' using the following functions: + + +void gtk_toolbar_set_orientation( GtkToolbar *toolbar, + GtkOrientation orientation ); + +void gtk_toolbar_set_style( GtkToolbar *toolbar, + GtkToolbarStyle style ); + +void gtk_toolbar_set_tooltips( GtkToolbar *toolbar, + gint enable ); + + +To show some other things that can be done with a toolbar, let's take the +following program (we'll interrupt the listing with some additional explanations): + + +#include + +#include "gtk.xpm" + +/* This function is connected to the Close button or + * closing the window from the WM */ +void delete_event (GtkWidget *widget, GdkEvent *event, gpointer data) +{ + gtk_main_quit (); +} + + +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. + + +GtkWidget* close_button; // this button will emit signal to close application +GtkWidget* tooltips_button; // to enable/disable tooltips +GtkWidget* text_button, + * icon_button, + * both_button; // radio buttons for toolbar style +GtkWidget* entry; // a text entry to show packing any widget into toolbar + + +In fact not all of the above widgets are needed here, but to make things +clearer I put them all together. + + +/* that's easy... when one of the buttons is toggled, we just + * check which one is active and set the style of the toolbar + * accordingly + * ATTENTION: our toolbar is passed as data to callback ! */ +void radio_event (GtkWidget *widget, gpointer data) +{ + if (GTK_TOGGLE_BUTTON (text_button)->active) + gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_TEXT); + else if (GTK_TOGGLE_BUTTON (icon_button)->active) + gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_ICONS); + else if (GTK_TOGGLE_BUTTON (both_button)->active) + gtk_toolbar_set_style(GTK_TOOLBAR ( data ), GTK_TOOLBAR_BOTH); +} + +/* even easier, just check given toggle button and enable/disable + * tooltips */ +void toggle_event (GtkWidget *widget, gpointer data) +{ + gtk_toolbar_set_tooltips (GTK_TOOLBAR ( data ), + GTK_TOGGLE_BUTTON (widget)->active ); +} + + +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). + + +int main (int argc, char *argv[]) +{ + /* Here is our main window (a dialog) and a handle for the handlebox */ + GtkWidget* dialog; + GtkWidget* handlebox; + + /* Ok, we need a toolbar, an icon with a mask (one for all of + the buttons) and an icon widget to put this icon in (but + we'll create a separate widget for each button) */ + GtkWidget * toolbar; + GdkPixmap * icon; + GdkBitmap * mask; + GtkWidget * iconw; + + /* this is called in all GTK application. */ + gtk_init (&argc, &argv); + + /* create a new window with a given title, and nice size */ + dialog = gtk_dialog_new (); + gtk_window_set_title ( GTK_WINDOW ( dialog ) , "GTKToolbar Tutorial"); + gtk_widget_set_usize( GTK_WIDGET ( dialog ) , 600 , 300 ); + GTK_WINDOW ( dialog ) ->allow_shrink = TRUE; + + /* typically we quit if someone tries to close us */ + gtk_signal_connect ( GTK_OBJECT ( dialog ), "delete_event", + GTK_SIGNAL_FUNC ( delete_event ), NULL); + + /* we need to realize the window because we use pixmaps for + * items on the toolbar in the context of it */ + gtk_widget_realize ( dialog ); + + /* to make it nice we'll put the toolbar into the handle box, + * 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 ); + + +The above should be similar to any other GTK application. Just initialization +of GTK, creating the window etc.. There is only one thing that probably +needs some explanation: a handle box. A handle box is just another box +that can be used to pack widgets in to. The difference between it and typical +boxes is that it can be detached from a parent window (or, in fact, the handle +box remains in the parent, but it is reduced to a very small rectangle, while +all of its 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. + + + /* 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, + GTK_TOOLBAR_BOTH ); + gtk_container_border_width ( GTK_CONTAINER ( toolbar ) , 5 ); + gtk_toolbar_set_space_size ( GTK_TOOLBAR ( toolbar ), 5 ); + gtk_container_add ( GTK_CONTAINER ( handlebox ) , toolbar ); + + /* 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 ); + + +Well, what we do above is just a straight-forward initialization of the toolbar +widget and creation of a GDK pixmap with its mask. If you want to know +something more about using pixmaps, refer to GDK documentation +or to the section earlier in this tutorial. + + + /* our first item is button */ + iconw = gtk_pixmap_new ( icon, mask ); // icon widget + close_button = + gtk_toolbar_append_item ( GTK_TOOLBAR (toolbar), // our toolbar + "Close", // button label + "Closes this app", // tooltip for this button + "Private", // tooltip private string + iconw, // icon widget + GTK_SIGNAL_FUNC (delete_event), // a signal + NULL ); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); // space after item + + +In the above code you see the simplest case: adding a button to toolbar. +Just before appending a new item, we have to construct a pixmap widget +to serve as an icon for this item; this step will have to be repeated for +each new item. Just after the item we also add a 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. + + + /* now, let's make our radio buttons group... */ + iconw = gtk_pixmap_new ( icon, mask ); + icon_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_RADIOBUTTON, // a type of element + NULL, // pointer to widget + "Icon", // label + "Only icons in toolbar", // tooltip + "Private", // tooltip private string + iconw, // icon + GTK_SIGNAL_FUNC (radio_event), // signal + toolbar); // data for signal + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + + +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 add simple items or even spaces +(type = GTK_TOOLBAR_CHILD_SPACE or GTK_TOOLBAR_CHILD_BUTTON). In the above +case we start creating a radio group. In creating other radio buttons for +this group a pointer to the previous button in the group is required, +so that a list of buttons can be easily constructed (see the section on + earlier in this tutorial). + + + /* following radio buttons refer to previous ones */ + iconw = gtk_pixmap_new ( icon, mask ); + text_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_RADIOBUTTON, + icon_button, + "Text", + "Only texts in toolbar", + "Private", + iconw, + GTK_SIGNAL_FUNC (radio_event), + toolbar); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + + iconw = gtk_pixmap_new ( icon, mask ); + both_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_RADIOBUTTON, + text_button, + "Both", + "Icons and text in toolbar", + "Private", + iconw, + GTK_SIGNAL_FUNC (radio_event), + toolbar); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(both_button),TRUE); + + +In the end we have set the state of one of the buttons manually (otherwise +they all stay in active state, preventing us from switching between them). + + + /* here we have just a simple toggle button */ + iconw = gtk_pixmap_new ( icon, mask ); + tooltips_button = + gtk_toolbar_append_element(GTK_TOOLBAR(toolbar), + GTK_TOOLBAR_CHILD_TOGGLEBUTTON, + NULL, + "Tooltips", + "Toolbar with or without tips", + "Private", + iconw, + GTK_SIGNAL_FUNC (toggle_event), + toolbar); + gtk_toolbar_append_space ( GTK_TOOLBAR ( toolbar ) ); + gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(tooltips_button),TRUE); + + +A toggle button can be created in the obvious way (if one knows how to create +radio buttons already). + + + /* 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), + entry, + "This is just an entry", + "Private" ); + + /* well, it isn't created within thetoolbar, so we must still show it */ + gtk_widget_show ( entry ); + + +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). + + + /* that's it ! let's show everything. */ + gtk_widget_show ( toolbar ); + gtk_widget_show (handlebox); + gtk_widget_show ( dialog ); + + /* rest in gtk_main and wait for the fun to begin! */ + gtk_main (); + + return 0; +} + + +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: + + +/* XPM */ +static char * gtk_xpm[] = { +"32 39 5 1", +". c none", +"+ c black", +"@ c #3070E0", +"# c #F05050", +"$ c #35E035", +"................+...............", +"..............+++++.............", +"............+++++@@++...........", +"..........+++++@@@@@@++.........", +"........++++@@@@@@@@@@++........", +"......++++@@++++++++@@@++.......", +".....+++@@@+++++++++++@@@++.....", +"...+++@@@@+++@@@@@@++++@@@@+....", +"..+++@@@@+++@@@@@@@@+++@@@@@++..", +".++@@@@@@+++@@@@@@@@@@@@@@@@@@++", +".+#+@@@@@@++@@@@+++@@@@@@@@@@@@+", +".+##++@@@@+++@@@+++++@@@@@@@@$@.", +".+###++@@@@+++@@@+++@@@@@++$$$@.", +".+####+++@@@+++++++@@@@@+@$$$$@.", +".+#####+++@@@@+++@@@@++@$$$$$$+.", +".+######++++@@@@@@@++@$$$$$$$$+.", +".+#######+##+@@@@+++$$$$$$@@$$+.", +".+###+++##+##+@@++@$$$$$$++$$$+.", +".+###++++##+##+@@$$$$$$$@+@$$@+.", +".+###++++++#+++@$$@+@$$@++$$$@+.", +".+####+++++++#++$$@+@$$++$$$$+..", +".++####++++++#++$$@+@$++@$$$$+..", +".+#####+++++##++$$++@+++$$$$$+..", +".++####+++##+#++$$+++++@$$$$$+..", +".++####+++####++$$++++++@$$$@+..", +".+#####++#####++$$+++@++++@$@+..", +".+#####++#####++$$++@$$@+++$@@..", +".++####++#####++$$++$$$$$+@$@++.", +".++####++#####++$$++$$$$$$$$+++.", +".+++####+#####++$$++$$$$$$$@+++.", +"..+++#########+@$$+@$$$$$$+++...", +"...+++########+@$$$$$$$$@+++....", +".....+++######+@$$$$$$$+++......", +"......+++#####+@$$$$$@++........", +".......+++####+@$$$$+++.........", +".........++###+$$$@++...........", +"..........++##+$@+++............", +"...........+++++++..............", +".............++++..............."}; + + Aspect Frames

@@ -5088,7 +5504,7 @@ GtkWidget *gtk_aspect_frame_new( const gchar *label, gint obey_child); - Creating a GtkCList widget @@ -5349,7 +5765,7 @@ The GtkJustification type can take the following values: GTK_JUSTIFY_FILL - The text will use up all available space in the column. It is normally done by inserting extra blank spaces between words -(or between inidvidual letters of it's a single word). Much in the same way as +(or between individual letters if it's a single word). Much in the same way as any ordinary WYSIWYG text editor. @@ -5515,7 +5931,7 @@ void gtk_clist_set_pixtext( GtkCList *clist, It's quite straightforward. All the calls have the GtkCList as the first -argument, followed by the row and column of the cell, follwed by the data to be +argument, followed by the row and column of the cell, followed by the data to be set. The gint8 spacing argument in gtk_clist_set_pixtext is the number of pixels between the pixmap and the beginning of the text. @@ -5593,7 +6009,7 @@ void gtk_clist_set_shift( GtkCList *clist, Storing data pointers

With a GtkCList it is possible to set a data pointer for a row. This -pointer will not be visible for the user, but is merely a convinience for +pointer will not be visible for the user, but is merely a convenience for the programmer to associate a row with a pointer to some additional data. The functions should be fairly self-explanatory by now @@ -5730,7 +6146,7 @@ gint main (int argc, gchar *argv[]) clist = gtk_clist_new_with_titles( 2, titles); /* When a selection is made, we want to know about it. The callback - * used is selection_made, and it's code can be found further down */ + * used is selection_made, and its code can be found further down */ gtk_signal_connect(GTK_OBJECT(clist), "select_row", GTK_SIGNAL_FUNC(selection_made), NULL); @@ -5873,11 +6289,11 @@ NOTE: The GtkList widget has been superseded by the GtkCList widget. The GtkList widget is designed to act as a vertical container for widgets that should be of the type GtkListItem. -A GtkList widget has its own window to receive events and it's own -background color which is usualy white. As it is directly derived from a +A GtkList widget has its own window to receive events and its own +background color which is usually white. As it is directly derived from a GtkContainer it can be treated as such by using the GTK_CONTAINER(List) macro, see the GtkContainer widget for more on this. -One should already be familar whith the usage of a GList and its +One should already be familiar with the usage of a GList and its related functions g_list_*() to be able to use the GtkList widget to it full extent. @@ -5895,7 +6311,7 @@ struct _GtkList The selection field of a GtkList points to a linked list of all items -that are curently selected, or NULL if the selection is empty. +that are currently selected, or NULL if the selection is empty. So to learn about the current selection we read the GTK_LIST()->selection field, but do not modify it since the internal fields are maintained by the gtk_list_*() functions. @@ -6165,7 +6581,7 @@ gint main (int argc, gchar *argv[]) gtk_container_add(GTK_CONTAINER(window), vbox); gtk_widget_show(vbox); - /* this is the scolled window to put the GtkList widget inside */ + /* this is the scrolled window to put the GtkList widget inside */ scrolled_window=gtk_scrolled_window_new(NULL, NULL); gtk_widget_set_usize(scrolled_window, 250, 150); gtk_container_add(GTK_CONTAINER(vbox), scrolled_window); @@ -6194,7 +6610,7 @@ gint main (int argc, gchar *argv[]) gtk_widget_show(frame); /* connect the sigh_button_event() signal handler to the GtkList - * wich will handle the "arresting" of list items + * which will handle the "arresting" of list items */ gtk_signal_connect(GTK_OBJECT(gtklist), "button_release_event", @@ -6207,8 +6623,8 @@ gint main (int argc, gchar *argv[]) gtk_container_add(GTK_CONTAINER(vbox), separator); gtk_widget_show(separator); - /* finaly create a button and connect itīs "clicked" signal - * to the destroyment of the window + /* finally create a button and connect itīs "clicked" signal + * to the destruction of the window */ button=gtk_button_new_with_label("Close"); gtk_container_add(GTK_CONTAINER(vbox), button); @@ -6265,7 +6681,7 @@ gint main (int argc, gchar *argv[]) } gtk_list_append_items(GTK_LIST(gtklist), dlist); - /* finaly we want to see the window, donīt we? ;) + /* finally we want to see the window, don't we? ;) */ gtk_widget_show(window); @@ -6304,7 +6720,7 @@ sigh_button_event (GtkWidget *gtklist, else new_prisoner=NULL; - /* look for already prisoned list items, we + /* look for already imprisoned list items, we * will put them back into the list * remember to free the doubly linked list that * gtk_container_children() returns @@ -6393,12 +6809,12 @@ to one child, providing functions for selection/deselection just like the GtkList widget requires them for its children. A GtkListItem has its own window to receive events and has its own -background color which is usualy white. +background color which is usually white. As it is directly derived from a GtkItem it can be treated as such by using the GTK_ITEM(ListItem) macro, see the GtkItem widget for more on this. -Usualy a GtkListItem just holds a label to identify e.g. a filename +Usually a GtkListItem just holds a label to identify e.g. a filename within a GtkList -- therefore the convenience function gtk_list_item_new_with_label() is provided. The same effect can be achieved by creating a GtkLabel on its own, setting its alignment @@ -6442,7 +6858,7 @@ GtkWidget object. NULL is returned on failure. void gtk_list_item_select( GtkListItem *list_item ); -This function is basicaly a wrapper around a call to +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. @@ -6451,7 +6867,7 @@ select signal. void gtk_list_item_deselect( GtkListItem *list_item ); -This function is basicaly a wrapper around a call to +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. @@ -6816,10 +7232,10 @@ to its subtrees, and can't be set exclusively to a subtree (this is not exactly true - see the example code comments). The term "view mode" is rather ambiguous - basically, it controls the -way the hilight is drawn when one of a tree's children is selected. +way the highlight is drawn when one of a tree's children is selected. If it's GTK_TREE_VIEW_LINE, the entire GtkTreeItem widget is -hilighted, while for GTK_TREE_VIEW_ITEM, only the child widget -(i.e. usually the label) is hilighted. +highlighted, while for GTK_TREE_VIEW_ITEM, only the child widget +(i.e. usually the label) is highlighted. void gtk_tree_set_view_lines( GtkTree *tree, @@ -7025,7 +7441,7 @@ GtkWidget object. NULL is returned on failure. void gtk_tree_item_select( GtkTreeItem *tree_item ); -This function is basicaly a wrapper around a call to +This function is basically a wrapper around a call to gtk_item_select (GTK_ITEM (tree_item)) which will emit the select signal. @@ -7033,7 +7449,7 @@ select signal. void gtk_tree_item_deselect( GtkTreeItem *tree_item ); -This function is basicaly a wrapper around a call to +This function is basically a wrapper around a call to gtk_item_deselect (GTK_ITEM (tree_item)) which will emit the deselect signal. @@ -7089,7 +7505,7 @@ Determine if a generic pointer refers to a `GtkTreeItem' object. GtkWidget GTK_TREE_ITEM_SUBTREE (gpointer obj) -Return's a tree item's subtree (obj should point to a `GtkTreeItem' +Returns a tree item's subtree (obj should point to a `GtkTreeItem' object). Tree Example @@ -7228,7 +7644,7 @@ int main (int argc, char *argv[]) g_print ("-> item %s->%p, subtree %p\n", itemnames[i], item, subtree); - /* This is still necesary if you want these signals to be called + /* This is still necessary if you want these signals to be called for the subtree's children. Note that selection_change will be signalled for the root tree regardless. */ gtk_signal_connect (GTK_OBJECT(subtree), "select_child", @@ -7309,9 +7725,9 @@ There are three widgets that go into making a menubar and submenus: This is slightly complicated by the fact that menu item widgets are used -for two different things. They are both the widets that are packed into +for two different things. They are both the widgets that are packed into the menu, and the widget that is packed into the menubar, which, -when selected, activiates the menu. +when selected, activates the menu. Let's look at the functions that are used to create menus and menubars. This first function is used to create a new menubar. @@ -7845,7 +8261,7 @@ GtkWidget *gtk_text_new( GtkAdjustment *hadj, 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 it's own. +function to create its own. void gtk_text_set_adjustments( GtkText *text, @@ -7856,7 +8272,7 @@ void gtk_text_set_adjustments( GtkText *text, The above function allows the horizontal and vertical adjustments of a Text widget to be changed at any time. -The text widget will not automatically create it's own scrollbars when +The text widget will not automatically create its own scrollbars when 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. @@ -7892,7 +8308,7 @@ two modes. You can toggle the editable state of the text widget at any time, and can insert text at any time. The text widget wraps lines of text that are too long to -fit onto a single line of the display window. It's default behaviour is +fit onto a single line of the display window. Its default behaviour is to break words across line breaks. This can be changed using the next function: @@ -8000,7 +8416,7 @@ to free it with a call to g_free when you have finished with it. Keyboard Shortcuts

-The text widget has a number of pre-installed keyboard shotcuts for common +The text widget has a number of pre-installed keyboard shortcuts for common editing, motion and selection functions. These are accessed using Control and Alt key combinations. @@ -8008,7 +8424,7 @@ In addition to these, holding down the Control key whilst using cursor key movement will move the cursor by words rather than characters. Holding down Shift whilst using cursor movement will extend the selection. -Motion Shotcuts +Motion Shortcuts

Ctrl-A Beginning of line @@ -8238,16 +8654,13 @@ If you must use one of these widgets that are undocumented, I strongly suggest you take a look at their respective header files in the GTK distribution. GTK's function names are very descriptive. Once you have an understanding of how things work, it's not difficult to figure out how to -use a widget simply by looking at it's function declarations. This, along +use a widget simply by looking at its function declarations. This, along with a few examples from others' code, and it should be no problem. When you do come to understand all the functions of a new undocumented -widget, please consider writing a tutorial on it so others may benifit +widget, please consider writing a tutorial on it so others may benefit from your time. - - Toolbar -

Fixed Container

@@ -8283,19 +8696,19 @@ But there's more. Previews allow for side-by-side pre-previews. In other words, you write a plug-in (e.g. the filterpack simulation) which would have a number of here's-what-it-would-look-like-if-you-were-to-do-this previews. An approach like this acts as a sort of a preview palette and is very -effective fow subtle changes. Let's go previews! +effective for subtle changes. Let's go previews! There's more. For certain plug-ins real-time image-specific human intervention maybe necessary. In the SuperNova plug-in, for example, the user is asked to enter the coordinates of the center of the future supernova. The easiest way to do this, really, is to present the user with a -preview and ask him to intereactively select the spot. Let's go previews! +preview and ask him to interactively select the spot. Let's go previews! Finally, a couple of misc uses. One can use previews even when not working -with big images. For example, they are useful when rendering compicated +with big images. For example, they are useful when rendering complicated patterns. (Just check out the venerable Diffraction plug-in + many other ones!) As another example, take a look at the colormap rotation plug-in -(work in progress). You can also use previews for little logo's inside you +(work in progress). You can also use previews for little logos inside you plug-ins and even for an image of yourself, The Author. Let's go previews! When Not to Use Previews @@ -8314,7 +8727,7 @@ necessary borders. [Image][Image] Previews in many ways are like any other widgets in GTK (whatever that -means) except they possess an addtional feature: they need to be filled with +means) except they possess an additional feature: they need to be filled with some sort of an image! First, we will deal exclusively with the GTK aspect of previews and then we'll discuss how to fill them. @@ -8366,7 +8779,7 @@ this case you may want to pass a pointer to the preview to a One more important note that may one day save you a lot of time. Sometimes it is desirable to label you preview. For example, you may label the preview containing the original image as "Original" and the one containing the -modified image as "Less Original". It might occure to you to pack the +modified image as "Less Original". It might occur to you to pack the preview along with the appropriate label into a vbox. The unexpected caveat is that if the label is wider than the preview (which may happen for a variety of reasons unforseeable to you, from the dynamic decision on the @@ -8377,7 +8790,7 @@ situations as well. [Image] The solution is to place the preview and the label into a 2x1 table and by -attaching them with the following paramters (this is one possible variations +attaching them with the following parameters (this is one possible variations of course. The key is no GTK_FILL in the second attachment): gtk_table_attach(GTK_TABLE(table),label,0,1,0,1, @@ -8453,7 +8866,7 @@ For the GIMP users I have a few pointers to add. Image Preview -It is probably wize to keep a reduced version of the image around with just +It is probably wise to keep a reduced version of the image around with just enough pixels to fill the preview. This is done by selecting every n'th pixel where n is the ratio of the size of the image to the size of the preview. All further operations (including filling in the previews) are then @@ -8473,7 +8886,7 @@ typedef struct { enum { SELECTION_ONLY, - SELCTION_IN_CONTEXT, + SELECTION_IN_CONTEXT, ENTIRE_IMAGE }; @@ -8484,7 +8897,7 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, { /* This function reduced the image down to the the selected preview size */ /* The preview size is determine by LongerSize, i.e. the greater of the */ - /* two dimentions. Works for RGB images only! */ + /* two dimensions. Works for RGB images only! */ gint RH, RW; /* Reduced height and reduced width */ gint width, height; /* Width and Height of the area being reduced */ gint bytes=drawable->bpp; @@ -8515,7 +8928,7 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, y2=drawable->height; } - /* If we want to preview a selection with some surronding area we */ + /* If we want to preview a selection with some surrounding area we */ /* have to expand it a little bit. Consider it a bit of a riddle. */ if (Selection==SELECTION_IN_CONTEXT) { x1=MAX(0, x1-width/2.0); @@ -8542,7 +8955,7 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, RW=(float)width * (float) LongerSize/ (float) height; } - /* The intire image is stretched into a string! */ + /* The entire image is stretched into a string! */ tempRGB = (guchar *) malloc(RW*RH*bytes); tempmask = (guchar *) malloc(RW*RH); @@ -8586,8 +8999,8 @@ ReducedImage *Reduce_The_Image(GDrawable *drawable, } The following is a preview function which used the same ReducedImage type! -Note that it uses fakes transparancy (if one is present by means of -fake_transparancy which is defined as follows: +Note that it uses fakes transparency (if one is present by means of +fake_transparency which is defined as follows: gint fake_transparency(gint i, gint j) { @@ -8645,7 +9058,7 @@ void gtk_preview_size (GtkPreview *preview, gint width, gint height); /* Allows you to resize an existing preview. */ -/* Apparantly there's a bug in GTK which makes */ +/* Apparently there's a bug in GTK which makes */ /* this process messy. A way to clean up a mess */ /* is to manually resize the window containing */ /* the preview after resizing the preview. */ @@ -8702,9 +9115,9 @@ That's all, folks!

Some gtk widgets don't have associated X windows, so they just draw on -their parents. Because of this, they cannot recieve events +their parents. Because of this, they cannot receive events and if they are incorrectly sized, they don't clip so you can get -messy overwritting etc. If you require more from these widgets, the +messy overwriting etc. If you require more from these widgets, the EventBox is for you. At first glance, the EventBox widget might appear to be totally @@ -8714,7 +9127,7 @@ its child widget. This is important as many GTK widgets do not have an associated X window. Not having an X window saves memory and improves performance, but also has some drawbacks. A widget without an X window cannot receive events, and does not perform any clipping on -it's contents. Although the name gdk_atom_intern(), to get the atom corresponding to a string, and gdk_atom_name(), to get the name of an atom. Both -selections and targets are identifed by atoms. +selections and targets are identified by atoms. Retrieving the selection @@ -9226,7 +9639,7 @@ get_targets (GtkWidget *widget, gpointer data) { static GdkAtom targets_atom = GDK_NONE; - /* Get the atom corresonding to the string "TARGETS" */ + /* Get the atom corresponding to the string "TARGETS" */ if (targets_atom == GDK_NONE) targets_atom = gdk_atom_intern ("TARGETS", FALSE); @@ -9520,7 +9933,7 @@ G_MAXLONG 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! Eg, a pointer on an Alpha is 8 bytes, but 4 +pointer if you want to be portable! E.g., a pointer on an Alpha is 8 bytes, but 4 on Intel. @@ -9653,7 +10066,7 @@ gpointer g_malloc( gulong size ); This is a replacement for malloc(). You do not need to check the return -vaule as it is done for you in this function. +value as it is done for you in this function. gpointer g_malloc0( gulong size ); @@ -9679,7 +10092,7 @@ Frees memory. Easy one. void g_mem_profile( void ); -Dumps a profile of used memory, but requries that you add #define +Dumps a profile of used memory, but requires that you add #define MEM_PROFILE to the top of glib/gmem.c and re-make and make install. @@ -9819,7 +10232,7 @@ to document any function, just send me an email! GTK's rc Files

-GTK has it's own way of dealing with application defaults, by using rc +GTK has its own way of dealing with application defaults, by using rc files. These can be used to set the colors of just about any widget, and can also be used to tile pixmaps onto the background of some widgets. @@ -9926,7 +10339,7 @@ doesn't matter if it's not recognized. Unrecognized values are set to 0. bg_pixmap is very similar to the above, except the colors are replaced by a filename. -pixmap_path is a list of paths seperated by ":"'s. These paths will be +pixmap_path is a list of paths separated by ":"'s. These paths will be searched for any pixmap you specify. The font directive is simply: @@ -9940,7 +10353,7 @@ similar utility should help. The "widget_class" sets the style of a class of widgets. These classes are listed in the widget overview on the class hierarchy. -The "widget" directive sets a specificaly named set of widgets to a +The "widget" directive sets a specifically named set of widgets to a given style, overriding any style set for the given widget class. These widgets are registered inside the application using the gtk_widget_set_name() call. This allows you to specify the attributes of a @@ -9949,7 +10362,7 @@ entire widget class. I urge you to document any of these special widgets so users may customize them. When the keyword parent is used as an attribute, the widget will take on -the attributes of it's parent in the application. +the attributes of its parent in the application. When defining a style, you may assign the attributes of a previously defined style to this new one. @@ -10030,7 +10443,7 @@ style "scale" fg[NORMAL] = { 1.0, 0, 0 } - #Sets the background pixmap of this widget to that of it's parent. + #Sets the background pixmap of this widget to that of its parent. bg_pixmap[NORMAL] = "" } @@ -10064,7 +10477,7 @@ style "toggle_button" = "button" fg[NORMAL] = { 1.0, 0, 0 } fg[ACTIVE] = { 1.0, 0, 0 } - # This sets the background pixmap of the toggle_button to that of it's + # This sets the background pixmap of the toggle_button to that of its # parent widget (as defined in the application). bg_pixmap[NORMAL] = "" } @@ -10097,7 +10510,7 @@ widget_class "*Ruler" style "ruler" widget_class "*GtkText" style "text" # This sets all the buttons that are children of the "main window" to -# the main_buton style. These must be documented to be taken advantage of. +# the main_button style. These must be documented to be taken advantage of. widget "main window.*GtkButton*" style "main_button" @@ -10110,7 +10523,7 @@ widget "main window.*GtkButton*" style "main_button"

Although the GTK distribution comes with many types of widgets that should cover most basic needs, there may come a time when you need to -create your own new widget type. Since GTK uses widget inheretence +create your own new widget type. Since GTK uses widget inheritance extensively, and there is already a widget that is close to what you want, it is often possible to make a useful new widget type in just a few lines of code. But before starting work on a new widget, check @@ -10491,7 +10904,7 @@ instead. After creating our signals, we need to tell GTK to associate our signals with the Tictactoe class. We do that by calling @@ -10724,7 +11137,7 @@ an Changes to the Adjustment by external means are communicated to our -widget by the ``changed'' and ``value_changed'' signals. The handlers +widget by the `changed' and `value_changed' signals. The handlers for these functions call @@ -11797,7 +12210,7 @@ void gtk_drawing_area_size (GtkDrawingArea *darea, gint height); -This default size can be overriden, as is true for all widgets, +This default size can be overridden, as is true for all widgets, by calling gtk_widget_set_usize(), and that, in turn, can be overridden if the user manually resizes the the window containing the drawing area. @@ -12269,7 +12682,7 @@ GList *gdk_input_list_devices (void); which returns a GList (a linked list type from the glib library) -of GdkDeviceInfo structures. The GdkDeviceInfo strucure is defined +of GdkDeviceInfo structures. The GdkDeviceInfo structure is defined as: @@ -12326,7 +12739,7 @@ print_button_press (guint32 deviceid) } -That completes the changes to ``XInputize'' our program. As with +That completes the changes to `XInputize' our program. As with the first version, the complete source is available at the location from which you got this tutorial, or from: @@ -12367,7 +12780,7 @@ applications. This probably belongs at a slightly higher level than GTK, perhaps in the GNOME library.

-Another major ommission that we have mentioned above is the lack of +Another major omission that we have mentioned above is the lack of cursor drawing. Platforms other than XFree86 currently do not allow simultaneously using a device as both the core pointer and directly by an application. See the -An application that draws it's own cursor needs to do two things: +An application that draws its own cursor needs to do two things: determine if the current device needs a cursor drawn or not, and determine if the current device is in proximity. (If the current device is a drawing tablet, it's a nice touch to make the cursor @@ -12394,7 +12807,7 @@ found in the 'testinput' program found in the GTK distribution.

This section is simply a gathering of wisdom, general style guidelines and hints to -creating good GTK applications. It is totally useless right now cause it's +creating good GTK applications. It is totally useless right now cause its only a topic sentence :) Use GNU autoconf and automake! They are your friends :) I am planning to @@ -12502,10 +12915,10 @@ versions.

If you are intending to incorporate this document into a published work, please contact the maintainer, and we will make an effort to ensure that you have the most up to date information available. -

There is no guarentee that this document lives up to its intended +

There is no guarantee that this document lives up to its intended purpose. This is simply provided as a free resource. As such, the authors and maintainers of the information provided within can -not make any guarentee that the information is even accurate. +not make any guarantee that the information is even accurate. @@ -13376,7 +13789,7 @@ void gtk_dial_set_adjustment (GtkDial *dial, #define SCROLL_DELAY_LENGTH 300 #define DIAL_DEFAULT_SIZE 100 -/* Forward declararations */ +/* Forward declarations */ static void gtk_dial_class_init (GtkDialClass *klass); static void gtk_dial_init (GtkDial *dial);