1 <!doctype linuxdoc system>
3 <!-- This is the tutorial marked up in SGML
4 (just to show how to write a comment)
9 <author>Ian Main <tt><htmlurl url="mailto:imain@gtk.org"
10 name="<imain@gtk.org>"></tt>,
11 Tony Gale <tt><htmlurl url="mailto:gale@gtk.org"
12 name="<gale@gtk.org>"></tt
13 <date>March 29th, 1998
15 <!-- ***************************************************************** -->
17 <!-- ***************************************************************** -->
19 GTK (GIMP Toolkit) was originally developed as a toolkit for the GIMP
20 (General Image Manipulation Program). GTK is built on top of GDK (GIMP
21 Drawing Kit) which is basically wrapper around the Xlib functions. It's
22 called the GIMP toolkit because it was original written for developing
23 the GIMP, but has now been used in several free software projects. The
26 <item> Peter Mattis <tt><htmlurl url="mailto:petm@xcf.berkeley.edu"
27 name="petm@xcf.berkeley.edu"></tt>
28 <item> Spencer Kimball <tt><htmlurl url="mailto:spencer@xcf.berkeley.edu"
29 name="spencer@xcf.berkeley.edu"></tt>
30 <item> Josh MacDonald <tt><htmlurl url="mailto:jmacd@xcf.berkeley.edu"
31 name="jmacd@xcf.berkeley.edu"></tt>
35 GTK is essentially an object oriented application programmers interface (API).
36 Although written completely in
37 C, it is implemented using the idea of classes and callback functions
38 (pointers to functions).
40 There is also a third component called glib which contains a few
41 replacements for some standard calls, as well as some additional functions
42 for handling linked lists etc. The replacement functions are used to
43 increase GTK's portability, as some of the functions implemented
44 here are not available or are nonstandard on other unicies such as
45 g_strerror(). Some also contain enhancements to the libc versions, such as
46 g_malloc that has enhanced debugging utilities.
48 This tutorial is an attempt to document as much as possible of GTK, it is by
49 no means complete. This
50 tutorial assumes a good understanding of C, and how to create C programs.
51 It would be a great benefit for the reader to have previous X programming
52 experience, but it shouldn't be necessary. If you are learning GTK as your
53 first widget set, please comment on how you found this tutorial, and what
55 Note that there is also a C++ API for GTK (GTK--) in the works, so if you
56 prefer to use C++, you should look into this instead. There's also an
57 Objective C wrapper, and guile bindings available, but I don't follow these.
59 I would very much like to hear any problems you have learning GTK from this
60 document, and would appreciate input as to how it may be improved.
62 <!-- ***************************************************************** -->
64 <!-- ***************************************************************** -->
67 The first thing to do of course, is download the GTK source and install
68 it. You can always get the latest version from ftp.gtk.org in /pub/gtk.
69 You can also view other sources of GTK information on http://www.gtk.org/
70 <htmlurl url="http://www.gtk.org/" name="http://www.gtk.org/">.
71 GTK uses GNU autoconf for
72 configuration. Once untar'd, type ./configure --help to see a list of options.
74 To begin our introduction to GTK, we'll start with the simplest program
75 possible. This program will
76 create a 200x200 pixel window and has no way of exiting except to be
77 killed using the shell.
82 int main (int argc, char *argv[])
86 gtk_init (&argc, &argv);
88 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
89 gtk_widget_show (window);
97 All programs will of course include the gtk/gtk.h which declares the
98 variables, functions, structures etc. that will be used in your GTK
104 gtk_init (&argc, &argv);
107 calls the function gtk_init(gint *argc, gchar ***argv) which will be
108 called in all GTK applications. This sets up a few things for us such
109 as the default visual and color map and then proceeds to call
110 gdk_init(gint *argc, gchar ***argv). This function initializes the
111 library for use, sets up default signal handlers, and checks the
112 arguments passed to your application on the command line, looking for one
116 <item> <tt/--display/
117 <item> <tt/--debug-level/
118 <item> <tt/--no-xshm/
120 <item> <tt/--show-events/
121 <item> <tt/--no-show-events/
124 It removes these from the argument list, leaving anything it does
125 not recognize for your application to parse or ignore. This creates a set
126 of standard arguments accepted by all GTK applications.
128 The next two lines of code create and display a window.
131 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
132 gtk_widget_show (window);
135 The GTK_WINDOW_TOPLEVEL argument specifies that we want the window to
136 undergo window manager decoration and placement. Rather than create a
137 window of 0x0 size, a window without children is set to 200x200 by default
138 so you can still manipulate it.
140 The gtk_widget_show() function, lets GTK know that we are done setting the
141 attributes of this widget, and it can display it.
143 The last line enters the GTK main processing loop.
149 gtk_main() is another call you will see in every GTK application. When
150 control reaches this point, GTK will sleep waiting for X events (such as
151 button or key presses), timeouts, or file IO notifications to occur.
152 In our simple example however, events are ignored.
154 <!-- ----------------------------------------------------------------- -->
155 <sect1>Hello World in GTK
157 OK, now for a program with a widget (a button). It's the classic hello
165 /* this is a callback function. the data arguments are ignored in this example..
166 * More on callbacks below. */
167 void hello (GtkWidget *widget, gpointer data)
169 g_print ("Hello World\n");
172 gint delete_event(GtkWidget *widget, gpointer data)
174 g_print ("delete event occured\n");
175 /* if you return TRUE in the "delete_event" signal handler,
176 * GTK will emit the "destroy" signal. Returning FALSE means
177 * you don't want the window to be destroyed.
178 * This is useful for popping up 'are you sure you want to quit ?'
181 /* Change FALSE to TRUE and the main window will be destroyed with
182 * a "delete_event". */
187 /* another callback */
188 void destroy (GtkWidget *widget, gpointer data)
193 int main (int argc, char *argv[])
195 /* GtkWidget is the storage type for widgets */
199 /* this is called in all GTK applications. arguments are parsed from
200 * the command line and are returned to the application. */
201 gtk_init (&argc, &argv);
203 /* create a new window */
204 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
206 /* when the window is given the "delete_event" signal (this is given
207 * by the window manager (usually the 'close' option, or on the
208 * titlebar), we ask it to call the delete_event () function
209 * as defined above. The data passed to the callback
210 * function is NULL and is ignored in the callback. */
211 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
212 GTK_SIGNAL_FUNC (delete_event), NULL);
214 /* here we connect the "destroy" event to a signal handler.
215 * This event occurs when we call gtk_widget_destroy() on the window,
216 * or if we return 'TRUE' in the "delete_event" callback. */
217 gtk_signal_connect (GTK_OBJECT (window), "destroy",
218 GTK_SIGNAL_FUNC (destroy), NULL);
220 /* sets the border width of the window. */
221 gtk_container_border_width (GTK_CONTAINER (window), 10);
223 /* creates a new button with the label "Hello World". */
224 button = gtk_button_new_with_label ("Hello World");
226 /* When the button receives the "clicked" signal, it will call the
227 * function hello() passing it NULL as it's argument. The hello() function is
229 gtk_signal_connect (GTK_OBJECT (button), "clicked",
230 GTK_SIGNAL_FUNC (hello), NULL);
232 /* This will cause the window to be destroyed by calling
233 * gtk_widget_destroy(window) when "clicked". Again, the destroy
234 * signal could come from here, or the window manager. */
235 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
236 GTK_SIGNAL_FUNC (gtk_widget_destroy),
237 GTK_OBJECT (window));
239 /* this packs the button into the window (a gtk container). */
240 gtk_container_add (GTK_CONTAINER (window), button);
242 /* the final step is to display this newly created widget... */
243 gtk_widget_show (button);
246 gtk_widget_show (window);
248 /* all GTK applications must have a gtk_main(). Control ends here
249 * and waits for an event to occur (like a key press or mouse event). */
256 <!-- ----------------------------------------------------------------- -->
257 <sect1>Compiling Hello World
262 gcc -Wall -g helloworld.c -o hello_world `gtk-config --cflags` \
267 This uses the program <tt>gtk-config</>, which comes with gtk. This
268 program 'knows' what compiler switches are needed to compile programs
269 that use gtk. <tt>gtk-config --cflags</> will output a list of include
270 directories for the compiler to look in, and <tt>gtk-config --libs</>
271 will output the list of libraries for the compiler to link with and
272 the directories to find them in.
275 The libraries that are usually linked in are:
277 <item>The GTK library (-lgtk), the widget library, based on top of GDK.
278 <item>The GDK library (-lgdk), the Xlib wrapper.
279 <item>The glib library (-lglib), containing miscellaneous functions, only
280 g_print() is used in this particular example. GTK is built on top
281 of glib so you will always require this library. See the section on
282 <ref id="sec_glib" name="glib"> for details.
283 <item>The Xlib library (-lX11) which is used by GDK.
284 <item>The Xext library (-lXext). This contains code for shared memory
285 pixmaps and other X extensions.
286 <item>The math library (-lm). This is used by GTK for various purposes.
289 <!-- ----------------------------------------------------------------- -->
290 <sect1>Theory of Signals and Callbacks
292 Before we look in detail at hello world, we'll discuss events and callbacks.
293 GTK is an event driven toolkit, which means it will sleep in
294 gtk_main until an event occurs and control is passed to the appropriate
297 This passing of control is done using the idea of "signals". When an
298 event occurs, such as the press of a mouse button, the
299 appropriate signal will be "emitted" by the widget that was pressed.
301 most of its useful work. To make a button perform an action,
302 we set up a signal handler to catch these
303 signals and call the appropriate function. This is done by using a
307 gint gtk_signal_connect (GtkObject *object,
313 Where the first argument is the widget which will be emitting the signal, and
314 the second, the name of the signal you wish to catch. The third is the function
315 you wish to be called when it is caught, and the fourth, the data you wish
316 to have passed to this function.
318 The function specified in the third argument is called a "callback
319 function", and should be of the form:
322 void callback_func(GtkWidget *widget, gpointer *callback_data);
325 Where the first argument will be a pointer to the widget that emitted the signal, and
326 the second, a pointer to the data given as the last argument to the
327 gtk_signal_connect() function as shown above.
329 Another call used in the hello world example, is:
332 gint gtk_signal_connect_object (GtkObject *object,
335 GtkObject *slot_object);
338 gtk_signal_connect_object() is the same as gtk_signal_connect() except that
339 the callback function only uses one argument, a
341 object. So when using this function to connect signals, the callback should be of
345 void callback_func (GtkObject *object);
348 Where the object is usually a widget. We usually don't setup callbacks for
349 gtk_signal_connect_object however. They are usually used
350 to call a GTK function that accept a single widget or object as an
351 argument, as is the case in our hello world example.
353 The purpose of having two functions to connect signals is simply to allow
354 the callbacks to have a different number of arguments. Many functions in
355 the GTK library accept only a single GtkWidget pointer as an argument, so you
356 want to use the gtk_signal_connect_object() for these, whereas for your
357 functions, you may need to have additional data supplied to the callbacks.
359 <!-- ----------------------------------------------------------------- -->
360 <sect1>Stepping Through Hello World
362 Now that we know the theory behind this, lets clarify by walking through
363 the example hello world program.
365 Here is the callback function that will be called when the button is
366 "clicked". We ignore both the widget and the data in this example, but it
367 is not hard to do things with them. The next example will use the data
368 argument to tell us which button was pressed.
371 void hello (GtkWidget *widget, gpointer *data)
373 g_print ("Hello World\n");
378 This callback is a bit special. The "delete_event" occurs when the
379 window manager sends this event to the application. We have a choice here
380 as to what to do about these events. We can ignore them, make some sort of
381 response, or simply quit the application.
383 The value you return in this callback lets GTK know what action to take.
384 By returning FALSE, we let it know that we don't want to have the "destroy"
385 signal emitted, keeping our application running. By returning TRUE, we
386 ask that "destroy" is emitted, which in turn will call our "destroy"
390 gint delete_event(GtkWidget *widget, gpointer data)
392 g_print ("delete event occured\n");
399 Here is another callback function which just quits by calling
400 gtk_main_quit(). Not really much to say about this, it is pretty self
403 void destroy (GtkWidget *widget, gpointer *data)
409 I assume you know about the main() function... yes, as with other
410 applications, all GTK applications will also have one of these.
412 int main (int argc, char *argv[])
416 This next part, declares a pointer to a structure of type GtkWidget. These
417 are used below to create a window and a button.
423 Here is our gtk_init again. As before, this initializes the toolkit, and
424 parses the arguments found on the command line. Any argument it
425 recognizes from the command line, it removes from the list, and modifies
426 argc and argv to make it look like they never existed, allowing your
427 application to parse the remaining arguments.
429 gtk_init (&argc, &argv);
432 Create a new window. This is fairly straight forward. Memory is allocated
433 for the GtkWidget *window structure so it now points to a valid structure.
434 It sets up a new window, but it is not displayed until below where we call
435 gtk_widget_show(window) near the end of our program.
437 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
440 Here is an example of connecting a signal handler to an object, in this case, the
441 window. Here, the "destroy" signal is caught. This is emitted when we use
442 the window manager to kill the window (and we return TRUE in the
443 "delete_event" handler), or when we use the
444 gtk_widget_destroy() call passing in the window widget as the object to
445 destroy. By setting this up, we handle both cases with a single call.
446 Here, it just calls the destroy() function defined above with a NULL
447 argument, which quits GTK for us.
449 The GTK_OBJECT and GTK_SIGNAL_FUNC are macros that perform type casting and
450 checking for us, as well as aid the readability of the code.
452 gtk_signal_connect (GTK_OBJECT (window), "destroy",
453 GTK_SIGNAL_FUNC (destroy), NULL);
456 This next function is used to set an attribute of a container object.
457 This just sets the window
458 so it has a blank area along the inside of it 10 pixels wide where no
459 widgets will go. There are other similar functions which we will look at
461 <ref id="sec_setting_widget_attributes" name="Setting Widget Attributes">
463 And again, GTK_CONTAINER is a macro to perform type casting.
465 gtk_container_border_width (GTK_CONTAINER (window), 10);
468 This call creates a new button. It allocates space for a new GtkWidget
469 structure in memory, initializes it, and makes the button pointer point to
470 it. It will have the label "Hello World" on it when displayed.
472 button = gtk_button_new_with_label ("Hello World");
475 Here, we take this button, and make it do something useful. We attach a
476 signal handler to it so when it emits the "clicked" signal, our hello()
477 function is called. The data is ignored, so we simply pass in NULL to the
478 hello() callback function. Obviously, the "clicked" signal is emitted when
479 we click the button with our mouse pointer.
482 gtk_signal_connect (GTK_OBJECT (button), "clicked",
483 GTK_SIGNAL_FUNC (hello), NULL);
486 We are also going to use this button to exit our program. This will
487 illustrate how the "destroy"
488 signal may come from either the window manager, or our program. When the
489 button is "clicked", same as above, it calls the first hello() callback function,
490 and then this one in the order they are set up. You may have as many
491 callback function as you need, and all will be executed in the order you
492 connected them. Because the gtk_widget_destroy() function accepts only a
493 GtkWidget *widget as an argument, we use the gtk_signal_connect_object()
494 function here instead of straight gtk_signal_connect().
497 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
498 GTK_SIGNAL_FUNC (gtk_widget_destroy),
499 GTK_OBJECT (window));
502 This is a packing call, which will be explained in depth later on. But it
503 is fairly easy to understand. It simply tells GTK that the button is to be
504 placed in the window where it will be displayed.
506 gtk_container_add (GTK_CONTAINER (window), button);
509 Now that we have everything setup the way we want it to be. With all the
510 signal handlers in place, and the button placed in the window where it
511 should be, we ask GTK to "show" the widgets on the screen. The window
512 widget is shown last so the whole window will pop up at once rather than
513 seeing the window pop up, and then the button form inside of it. Although
514 with such simple example, you'd never notice.
516 gtk_widget_show (button);
518 gtk_widget_show (window);
521 And of course, we call gtk_main() which waits for events to come from the X
522 server and will call on the widgets to emit signals when these events come.
526 And the final return. Control returns here after gtk_quit() is called.
531 Now, when we click the mouse button on a GTK button, the
532 widget emits a "clicked" signal. In order for us to use this information, our
533 program sets up a signal handler to catch that signal, which dispatches the function
534 of our choice. In our example, when the button we created is "clicked", the
535 hello() function is called with a NULL
536 argument, and then the next handler for this signal is called. This calls
537 the gtk_widget_destroy() function, passing it the window widget as it's
538 argument, destroying the window widget. This causes the window to emit the
539 "destroy" signal, which is
540 caught, and calls our destroy() callback function, which simply exits GTK.
542 Another course of events, is to use the window manager to kill the window.
543 This will cause the "delete_event" to be emitted. This will call our
544 "delete_event" handler. If we return FALSE here, the window will be left as
545 is and nothing will happen. Returning TRUE will cause GTK to emit the
546 "destroy" signal which of course, calls the "destroy" callback, exiting GTK.
548 Note that these signals are not the same as the Unix system
549 signals, and are not implemented using them, although the terminology is
552 <!-- ***************************************************************** -->
554 <!-- ***************************************************************** -->
556 <!-- ----------------------------------------------------------------- -->
559 There are a few things you probably noticed in the previous examples that
561 gint, gchar etc. that you see are typedefs to int and char respectively. This is done
562 to get around that nasty dependency on the size of simple data types when doing calculations.
563 A good example is "gint32" which will be
564 typedef'd to a 32 bit integer for any given platform, whether it be the 64 bit
565 alpha, or the 32 bit i386. The
566 typedefs are very straight forward and intuitive. They are all defined in
567 glib/glib.h (which gets included from gtk.h).
569 You'll also notice the ability to use GtkWidget when the function calls for a GtkObject.
570 GTK is an object oriented design, and a widget is an object.
572 <!-- ----------------------------------------------------------------- -->
573 <sect1>More on Signal Handlers
575 Lets take another look at the gtk_signal_connect declaration.
578 gint gtk_signal_connect (GtkObject *object, gchar *name,
579 GtkSignalFunc func, gpointer func_data);
582 Notice the gint return value ? This is a tag that identifies your callback
583 function. As said above, you may have as many callbacks per signal and per
584 object as you need, and each will be executed in turn, in the order they were attached.
585 This tag allows you to remove this callback from the list by using:
587 void gtk_signal_disconnect (GtkObject *object,
590 So, by passing in the widget you wish to remove the handler from, and the
591 tag or id returned by one of the signal_connect functions, you can
592 disconnect a signal handler.
594 Another function to remove all the signal handers from an object is:
596 gtk_signal_handlers_destroy (GtkObject *object);
599 This call is fairly self explanatory. It simply removes all the current
600 signal handlers from the object passed in as the first argument.
602 <!-- ----------------------------------------------------------------- -->
603 <sect1>An Upgraded Hello World
605 Let's take a look at a slightly improved hello world with better examples
606 of callbacks. This will also introduce us to our next topic, packing
614 /* Our new improved callback. The data passed to this function is printed
616 void callback (GtkWidget *widget, gpointer *data)
618 g_print ("Hello again - %s was pressed\n", (char *) data);
621 /* another callback */
622 void delete_event (GtkWidget *widget, gpointer *data)
627 int main (int argc, char *argv[])
629 /* GtkWidget is the storage type for widgets */
634 /* this is called in all GTK applications. arguments are parsed from
635 * the command line and are returned to the application. */
636 gtk_init (&argc, &argv);
638 /* create a new window */
639 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
641 /* this is a new call, this just sets the title of our
642 * new window to "Hello Buttons!" */
643 gtk_window_set_title (GTK_WINDOW (window), "Hello Buttons!");
645 /* Here we just set a handler for delete_event that immediately
647 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
648 GTK_SIGNAL_FUNC (delete_event), NULL);
651 /* sets the border width of the window. */
652 gtk_container_border_width (GTK_CONTAINER (window), 10);
654 /* we create a box to pack widgets into. this is described in detail
655 * in the "packing" section below. The box is not really visible, it
656 * is just used as a tool to arrange widgets. */
657 box1 = gtk_hbox_new(FALSE, 0);
659 /* put the box into the main window. */
660 gtk_container_add (GTK_CONTAINER (window), box1);
662 /* creates a new button with the label "Button 1". */
663 button = gtk_button_new_with_label ("Button 1");
665 /* Now when the button is clicked, we call the "callback" function
666 * with a pointer to "button 1" as it's argument */
667 gtk_signal_connect (GTK_OBJECT (button), "clicked",
668 GTK_SIGNAL_FUNC (callback), (gpointer) "button 1");
670 /* instead of gtk_container_add, we pack this button into the invisible
671 * box, which has been packed into the window. */
672 gtk_box_pack_start(GTK_BOX(box1), button, TRUE, TRUE, 0);
674 /* always remember this step, this tells GTK that our preparation for
675 * this button is complete, and it can be displayed now. */
676 gtk_widget_show(button);
678 /* do these same steps again to create a second button */
679 button = gtk_button_new_with_label ("Button 2");
681 /* call the same callback function with a different argument,
682 * passing a pointer to "button 2" instead. */
683 gtk_signal_connect (GTK_OBJECT (button), "clicked",
684 GTK_SIGNAL_FUNC (callback), (gpointer) "button 2");
686 gtk_box_pack_start(GTK_BOX(box1), button, TRUE, TRUE, 0);
688 /* The order in which we show the buttons is not really important, but I
689 * recommend showing the window last, so it all pops up at once. */
690 gtk_widget_show(button);
692 gtk_widget_show(box1);
694 gtk_widget_show (window);
696 /* rest in gtk_main and wait for the fun to begin! */
703 Compile this program using the same linking arguments as our first example.
704 You'll notice this time there is no easy way to exit the program, you have to use
705 your window manager or command line to kill it. A good exercise for the
706 reader would be to insert a third "Quit" button that will exit the
707 program. You may also wish to play with the options to
708 gtk_box_pack_start() while reading the next section.
709 Try resizing the window, and observe the behavior.
711 Just as a side note, there is another useful define for gtk_window_new() -
712 GTK_WINDOW_DIALOG. This interacts with the window manager a little
713 differently and should be used for transient windows.
715 <!-- ***************************************************************** -->
716 <sect>Packing Widgets
717 <!-- ***************************************************************** -->
720 When creating an application, you'll want to put more than one button
721 inside a window. Our first hello world example only used one widget so we
722 could simply use a gtk_container_add call to "pack" the widget into the
723 window. But when you want to put more than one widget into a window, how
724 do you control where that widget is positioned ? This is where packing
727 <!-- ----------------------------------------------------------------- -->
728 <sect1>Theory of Packing Boxes
730 Most packing is done by creating boxes as in the example above. These are
731 invisible widget containers that we can pack our widgets into and come in
732 two forms, a horizontal box, and a vertical box. When packing widgets
733 into a horizontal box, the objects are inserted horizontally from left to
734 right or right to left depending on the call used. In a vertical box,
735 widgets are packed from top to bottom or vice versa. You may use any
736 combination of boxes inside or beside other boxes to create the desired
739 To create a new horizontal box, we use a call to gtk_hbox_new(), and for
740 vertical boxes, gtk_vbox_new(). The gtk_box_pack_start() and
741 gtk_box_pack_end() functions are used to place objects inside of these
742 containers. The gtk_box_pack_start() function will start at the top and
743 work its way down in a vbox, and pack left to right in an hbox.
744 gtk_box_pack_end() will do the opposite, packing from bottom to top in a
745 vbox, and right to left in an hbox. Using these functions allow us to
746 right justify or left justify our widgets and may be mixed in any way to
747 achieve the desired effect. We will use gtk_box_pack_start() in most of
748 our examples. An object may be another container or a widget. And in
749 fact, many widgets are actually containers themselves including the
750 button, but we usually only use a label inside a button.
752 By using these calls, GTK knows where you want to place your widgets so it
753 can do automatic resizing and other nifty things. there's also a number
754 of options as to how your widgets should be packed. As you can imagine,
755 this method gives us a quite a bit of flexibility when placing and
758 <!-- ----------------------------------------------------------------- -->
759 <sect1>Details of Boxes
761 Because of this flexibility, packing boxes in GTK can be confusing at
762 first. There are a lot of options, and it's not immediately obvious how
763 they all fit together. In the end however, there are basically five
764 different styles you can get.
769 <IMG SRC="gtk_tut_packbox1.gif" VSPACE="15" HSPACE="10" WIDTH="528" HEIGHT="235"
770 ALT="Box Packing Example Image">
774 Each line contains one horizontal box (hbox) with several buttons. The
775 call to gtk_box_pack is shorthand for the call to pack each of the buttons
776 into the hbox. Each of the buttons is packed into the hbox the same way
777 (i.e. same arguments to the gtk_box_pack_start () function).
779 This is the declaration of the gtk_box_pack_start function.
782 void gtk_box_pack_start (GtkBox *box,
789 The first argument is the box you are packing the object into, the second
790 is this object. The objects will all be buttons for now, so we'll be
791 packing buttons into boxes.
793 The expand argument to gtk_box_pack_start() or gtk_box_pack_end() controls
794 whether the widgets are laid out in the box to fill in all the extra space
795 in the box so the box is expanded to fill the area alloted to it (TRUE).
796 Or the box is shrunk to just fit the widgets (FALSE). Setting expand to
797 FALSE will allow you to do right and left
798 justifying of your widgets. Otherwise, they will all expand to fit in the
799 box, and the same effect could be achieved by using only one of
800 gtk_box_pack_start or pack_end functions.
802 The fill argument to the gtk_box_pack functions control whether the extra
803 space is allocated to the objects themselves (TRUE), or as extra padding
804 in the box around these objects (FALSE). It only has an effect if the
805 expand argument is also TRUE.
807 When creating a new box, the function looks like this:
810 GtkWidget * gtk_hbox_new (gint homogeneous,
814 The homogeneous argument to gtk_hbox_new (and the same for gtk_vbox_new)
815 controls whether each object in the box has the same size (i.e. the same
816 width in an hbox, or the same height in a vbox). If it is set, the expand
817 argument to the gtk_box_pack routines is always turned on.
819 What's the difference between spacing (set when the box is created) and
820 padding (set when elements are packed)? Spacing is added between objects,
821 and padding is added on either side of an object. The following figure
822 should make it clearer:
826 <IMG ALIGN="center" SRC="gtk_tut_packbox2.gif" WIDTH="509" HEIGHT="213"
827 VSPACE="15" HSPACE="10" ALT="Box Packing Example Image">
831 Here is the code used to create the above images. I've commented it fairly
832 heavily so hopefully you won't have any problems following it. Compile it yourself
835 <!-- ----------------------------------------------------------------- -->
836 <sect1>Packing Demonstration Program
844 delete_event (GtkWidget *widget, gpointer *data)
849 /* Make a new hbox filled with button-labels. Arguments for the
850 * variables we're interested are passed in to this function.
851 * We do not show the box, but do show everything inside. */
852 GtkWidget *make_box (gint homogeneous, gint spacing,
853 gint expand, gint fill, gint padding)
859 /* create a new hbox with the appropriate homogeneous and spacing
861 box = gtk_hbox_new (homogeneous, spacing);
863 /* create a series of buttons with the appropriate settings */
864 button = gtk_button_new_with_label ("gtk_box_pack");
865 gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding);
866 gtk_widget_show (button);
868 button = gtk_button_new_with_label ("(box,");
869 gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding);
870 gtk_widget_show (button);
872 button = gtk_button_new_with_label ("button,");
873 gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding);
874 gtk_widget_show (button);
876 /* create a button with the label depending on the value of
879 button = gtk_button_new_with_label ("TRUE,");
881 button = gtk_button_new_with_label ("FALSE,");
883 gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding);
884 gtk_widget_show (button);
886 /* This is the same as the button creation for "expand"
887 * above, but uses the shorthand form. */
888 button = gtk_button_new_with_label (fill ? "TRUE," : "FALSE,");
889 gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding);
890 gtk_widget_show (button);
892 sprintf (padstr, "%d);", padding);
894 button = gtk_button_new_with_label (padstr);
895 gtk_box_pack_start (GTK_BOX (box), button, expand, fill, padding);
896 gtk_widget_show (button);
902 main (int argc, char *argv[])
908 GtkWidget *separator;
913 /* Our init, don't forget this! :) */
914 gtk_init (&argc, &argv);
917 fprintf (stderr, "usage: packbox num, where num is 1, 2, or 3.\n");
918 /* this just does cleanup in GTK, and exits with an exit status of 1. */
922 which = atoi (argv[1]);
924 /* Create our window */
925 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
927 /* You should always remember to connect the destroy signal to the
928 * main window. This is very important for proper intuitive
930 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
931 GTK_SIGNAL_FUNC (delete_event), NULL);
932 gtk_container_border_width (GTK_CONTAINER (window), 10);
934 /* We create a vertical box (vbox) to pack the horizontal boxes into.
935 * This allows us to stack the horizontal boxes filled with buttons one
936 * on top of the other in this vbox. */
937 box1 = gtk_vbox_new (FALSE, 0);
939 /* which example to show. These correspond to the pictures above. */
942 /* create a new label. */
943 label = gtk_label_new ("gtk_hbox_new (FALSE, 0);");
945 /* Align the label to the left side. We'll discuss this function and
946 * others in the section on Widget Attributes. */
947 gtk_misc_set_alignment (GTK_MISC (label), 0, 0);
949 /* Pack the label into the vertical box (vbox box1). Remember that
950 * widgets added to a vbox will be packed one on top of the other in
952 gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0);
955 gtk_widget_show (label);
957 /* call our make box function - homogeneous = FALSE, spacing = 0,
958 * expand = FALSE, fill = FALSE, padding = 0 */
959 box2 = make_box (FALSE, 0, FALSE, FALSE, 0);
960 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
961 gtk_widget_show (box2);
963 /* call our make box function - homogeneous = FALSE, spacing = 0,
964 * expand = FALSE, fill = FALSE, padding = 0 */
965 box2 = make_box (FALSE, 0, TRUE, FALSE, 0);
966 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
967 gtk_widget_show (box2);
969 /* Args are: homogeneous, spacing, expand, fill, padding */
970 box2 = make_box (FALSE, 0, TRUE, TRUE, 0);
971 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
972 gtk_widget_show (box2);
974 /* creates a separator, we'll learn more about these later,
975 * but they are quite simple. */
976 separator = gtk_hseparator_new ();
978 /* pack the separator into the vbox. Remember each of these
979 * widgets are being packed into a vbox, so they'll be stacked
981 gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5);
982 gtk_widget_show (separator);
984 /* create another new label, and show it. */
985 label = gtk_label_new ("gtk_hbox_new (TRUE, 0);");
986 gtk_misc_set_alignment (GTK_MISC (label), 0, 0);
987 gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0);
988 gtk_widget_show (label);
990 /* Args are: homogeneous, spacing, expand, fill, padding */
991 box2 = make_box (TRUE, 0, TRUE, FALSE, 0);
992 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
993 gtk_widget_show (box2);
995 /* Args are: homogeneous, spacing, expand, fill, padding */
996 box2 = make_box (TRUE, 0, TRUE, TRUE, 0);
997 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
998 gtk_widget_show (box2);
1000 /* another new separator. */
1001 separator = gtk_hseparator_new ();
1002 /* The last 3 arguments to gtk_box_pack_start are: expand, fill, padding. */
1003 gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5);
1004 gtk_widget_show (separator);
1010 /* create a new label, remember box1 is a vbox as created
1011 * near the beginning of main() */
1012 label = gtk_label_new ("gtk_hbox_new (FALSE, 10);");
1013 gtk_misc_set_alignment (GTK_MISC (label), 0, 0);
1014 gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0);
1015 gtk_widget_show (label);
1017 /* Args are: homogeneous, spacing, expand, fill, padding */
1018 box2 = make_box (FALSE, 10, TRUE, FALSE, 0);
1019 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
1020 gtk_widget_show (box2);
1022 /* Args are: homogeneous, spacing, expand, fill, padding */
1023 box2 = make_box (FALSE, 10, TRUE, TRUE, 0);
1024 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
1025 gtk_widget_show (box2);
1027 separator = gtk_hseparator_new ();
1028 /* The last 3 arguments to gtk_box_pack_start are: expand, fill, padding. */
1029 gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5);
1030 gtk_widget_show (separator);
1032 label = gtk_label_new ("gtk_hbox_new (FALSE, 0);");
1033 gtk_misc_set_alignment (GTK_MISC (label), 0, 0);
1034 gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 0);
1035 gtk_widget_show (label);
1037 /* Args are: homogeneous, spacing, expand, fill, padding */
1038 box2 = make_box (FALSE, 0, TRUE, FALSE, 10);
1039 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
1040 gtk_widget_show (box2);
1042 /* Args are: homogeneous, spacing, expand, fill, padding */
1043 box2 = make_box (FALSE, 0, TRUE, TRUE, 10);
1044 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
1045 gtk_widget_show (box2);
1047 separator = gtk_hseparator_new ();
1048 /* The last 3 arguments to gtk_box_pack_start are: expand, fill, padding. */
1049 gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5);
1050 gtk_widget_show (separator);
1055 /* This demonstrates the ability to use gtk_box_pack_end() to
1056 * right justify widgets. First, we create a new box as before. */
1057 box2 = make_box (FALSE, 0, FALSE, FALSE, 0);
1058 /* create the label that will be put at the end. */
1059 label = gtk_label_new ("end");
1060 /* pack it using gtk_box_pack_end(), so it is put on the right side
1061 * of the hbox created in the make_box() call. */
1062 gtk_box_pack_end (GTK_BOX (box2), label, FALSE, FALSE, 0);
1063 /* show the label. */
1064 gtk_widget_show (label);
1066 /* pack box2 into box1 (the vbox remember ? :) */
1067 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, FALSE, 0);
1068 gtk_widget_show (box2);
1070 /* a separator for the bottom. */
1071 separator = gtk_hseparator_new ();
1072 /* this explicitly sets the separator to 400 pixels wide by 5 pixels
1073 * high. This is so the hbox we created will also be 400 pixels wide,
1074 * and the "end" label will be separated from the other labels in the
1075 * hbox. Otherwise, all the widgets in the hbox would be packed as
1076 * close together as possible. */
1077 gtk_widget_set_usize (separator, 400, 5);
1078 /* pack the separator into the vbox (box1) created near the start
1080 gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 5);
1081 gtk_widget_show (separator);
1084 /* Create another new hbox.. remember we can use as many as we need! */
1085 quitbox = gtk_hbox_new (FALSE, 0);
1087 /* Our quit button. */
1088 button = gtk_button_new_with_label ("Quit");
1090 /* setup the signal to destroy the window. Remember that this will send
1091 * the "destroy" signal to the window which will be caught by our signal
1092 * handler as defined above. */
1093 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
1094 GTK_SIGNAL_FUNC (gtk_main_quit),
1095 GTK_OBJECT (window));
1096 /* pack the button into the quitbox.
1097 * The last 3 arguments to gtk_box_pack_start are: expand, fill, padding. */
1098 gtk_box_pack_start (GTK_BOX (quitbox), button, TRUE, FALSE, 0);
1099 /* pack the quitbox into the vbox (box1) */
1100 gtk_box_pack_start (GTK_BOX (box1), quitbox, FALSE, FALSE, 0);
1102 /* pack the vbox (box1) which now contains all our widgets, into the
1104 gtk_container_add (GTK_CONTAINER (window), box1);
1106 /* and show everything left */
1107 gtk_widget_show (button);
1108 gtk_widget_show (quitbox);
1110 gtk_widget_show (box1);
1111 /* Showing the window last so everything pops up at once. */
1112 gtk_widget_show (window);
1114 /* And of course, our main function. */
1117 /* control returns here when gtk_main_quit() is called, but not when
1118 * gtk_exit is used. */
1124 <!-- ----------------------------------------------------------------- -->
1125 <sect1>Packing Using Tables
1127 Let's take a look at another way of packing - Tables. These can be
1128 extremely useful in certain situations.
1130 Using tables, we create a grid that we can place widgets in. The widgets
1131 may take up as many spaces as we specify.
1133 The first thing to look at of course, is the gtk_table_new function:
1136 GtkWidget* gtk_table_new (gint rows,
1141 The first argument is the number of rows to make in the table, while the
1142 second, obviously, the number of columns.
1144 The homogeneous argument has to do with how the table's boxes are sized. If homogeneous
1145 is TRUE, the table boxes are resized to the size of the largest widget in the table.
1146 If homogeneous is FALSE, the size of a table boxes is dictated by the tallest widget
1147 in its same row, and the widest widget in its column.
1149 The rows and columnts are laid out starting with 0 to n, where n was the
1150 number specified in the call to gtk_table_new. So, if you specify rows = 2 and
1151 columns = 2, the layout would look something like this:
1155 0+----------+----------+
1157 1+----------+----------+
1159 2+----------+----------+
1162 Note that the coordinate system starts in the upper left hand corner. To place a
1163 widget into a box, use the following function:
1166 void gtk_table_attach (GtkTable *table,
1178 Where the first argument ("table") is the table you've created and the second
1179 ("child") the widget you wish to place in the table.
1181 The left and right attach
1182 arguments specify where to place the widget, and how many boxes to use. If you want
1183 a button in the lower right table entry
1184 of our 2x2 table, and want it to fill that entry ONLY. left_attach would be = 1,
1185 right_attach = 2, top_attach = 1, bottom_attach = 2.
1187 Now, if you wanted a widget to take up the whole
1188 top row of our 2x2 table, you'd use left_attach = 0, right_attach =2, top_attach = 0,
1191 The xoptions and yoptions are used to specify packing options and may be OR'ed
1192 together to allow multiple options.
1196 <item>GTK_FILL - If the table box is larger than the widget, and GTK_FILL is
1197 specified, the widget will expand to use all the room available.
1199 <item>GTK_SHRINK - If the table widget was allocated less space then was
1200 requested (usually by the user resizing the window), then the widgets would
1201 normally just be pushed off the bottom of
1202 the window and disappear. If GTK_SHRINK is specified, the widgets will
1203 shrink with the table.
1205 <item>GTK_EXPAND - This will cause the table to expand to use up any remaining
1206 space in the window.
1209 Padding is just like in boxes, creating a clear area around the widget
1210 specified in pixels.
1212 gtk_table_attach() has a LOT of options. So, there's a shortcut:
1215 void gtk_table_attach_defaults (GtkTable *table,
1220 gint bottom_attach);
1223 The X and Y options default to GTK_FILL | GTK_EXPAND, and X and Y padding
1224 are set to 0. The rest of the arguments are identical to the previous
1227 We also have gtk_table_set_row_spacing() and gtk_table_set_col_spacing(). This places
1228 spacing between the rows at the specified row or column.
1231 void gtk_table_set_row_spacing (GtkTable *table,
1237 void gtk_table_set_col_spacing (GtkTable *table,
1242 Note that for columns, the space goes to the right of the column, and for rows,
1243 the space goes below the row.
1245 You can also set a consistent spacing of all rows and/or columns with:
1248 void gtk_table_set_row_spacings (GtkTable *table,
1254 void gtk_table_set_col_spacings (GtkTable *table,
1258 Note that with these calls, the last row and last column do not get any spacing
1260 <!-- ----------------------------------------------------------------- -->
1261 <sect1>Table Packing Example
1263 Here we make a window with three buttons in a 2x2 table.
1264 The first two buttons will be placed in the upper row.
1265 A third, quit button, is placed in the lower row, spanning both columns.
1266 Which means it should look something like this:
1270 <IMG SRC="gtk_tut_table.gif" VSPACE="15" HSPACE="10"
1271 ALT="Table Packing Example Image" WIDTH="180" HEIGHT="120">
1275 Here's the source code:
1279 #include <gtk/gtk.h>
1282 * the data passed to this function is printed to stdout */
1283 void callback (GtkWidget *widget, gpointer *data)
1285 g_print ("Hello again - %s was pressed\n", (char *) data);
1288 /* this callback quits the program */
1289 void delete_event (GtkWidget *widget, gpointer *data)
1294 int main (int argc, char *argv[])
1300 gtk_init (&argc, &argv);
1302 /* create a new window */
1303 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
1305 /* set the window title */
1306 gtk_window_set_title (GTK_WINDOW (window), "Table");
1308 /* set a handler for delete_event that immediately
1310 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
1311 GTK_SIGNAL_FUNC (delete_event), NULL);
1313 /* sets the border width of the window. */
1314 gtk_container_border_width (GTK_CONTAINER (window), 20);
1316 /* create a 2x2 table */
1317 table = gtk_table_new (2, 2, TRUE);
1319 /* put the table in the main window */
1320 gtk_container_add (GTK_CONTAINER (window), table);
1322 /* create first button */
1323 button = gtk_button_new_with_label ("button 1");
1325 /* when the button is clicked, we call the "callback" function
1326 * with a pointer to "button 1" as it's argument */
1327 gtk_signal_connect (GTK_OBJECT (button), "clicked",
1328 GTK_SIGNAL_FUNC (callback), (gpointer) "button 1");
1331 /* insert button 1 into the upper left quadrant of the table */
1332 gtk_table_attach_defaults (GTK_TABLE(table), button, 0, 1, 0, 1);
1334 gtk_widget_show (button);
1336 /* create second button */
1338 button = gtk_button_new_with_label ("button 2");
1340 /* when the button is clicked, we call the "callback" function
1341 * with a pointer to "button 2" as it's argument */
1342 gtk_signal_connect (GTK_OBJECT (button), "clicked",
1343 GTK_SIGNAL_FUNC (callback), (gpointer) "button 2");
1344 /* insert button 2 into the upper right quadrant of the table */
1345 gtk_table_attach_defaults (GTK_TABLE(table), button, 1, 2, 0, 1);
1347 gtk_widget_show (button);
1349 /* create "Quit" button */
1350 button = gtk_button_new_with_label ("Quit");
1352 /* when the button is clicked, we call the "delete_event" function
1353 * and the program exits */
1354 gtk_signal_connect (GTK_OBJECT (button), "clicked",
1355 GTK_SIGNAL_FUNC (delete_event), NULL);
1357 /* insert the quit button into the both
1358 * lower quadrants of the table */
1359 gtk_table_attach_defaults (GTK_TABLE(table), button, 0, 2, 1, 2);
1361 gtk_widget_show (button);
1363 gtk_widget_show (table);
1364 gtk_widget_show (window);
1372 You can compile this program with something like:
1375 gcc -g -Wall -ansi -o table table.c -L/usr/X11R6/lib \
1376 -lgdk -lgtk -lglib -lX11 -lXext -lm
1379 <!-- ***************************************************************** -->
1380 <sect>Widget Overview
1381 <!-- ***************************************************************** -->
1384 The general steps to creating a widget in GTK are:
1386 <item> gtk_*_new - one of various functions to create a new widget. These
1387 are all detailed in this section.
1389 <item> Connect all signals we wish to use to the appropriate handlers.
1391 <item> Set the attributes of the widget.
1393 <item> Pack the widget into a container using the appropriate call such as
1394 gtk_container_add() or gtk_box_pack_start().
1396 <item> gtk_widget_show() the widget.
1399 gtk_widget_show() lets GTK know that we are done setting the attributes
1400 of the widget, and it is ready to be displayed. You may also use
1401 gtk_widget_hide to make it disappear again. The order in which you
1402 show the widgets is not important, but I suggest showing the window
1403 last so the whole window pops up at once rather than seeing the individual
1404 widgets come up on the screen as they're formed. The children of a widget
1405 (a window is a widget too)
1406 will not be displayed until the window itself is shown using the
1407 gtk_widget_show() function.
1409 <!-- ----------------------------------------------------------------- -->
1412 You'll notice as you go on, that GTK uses a type casting system. This is
1413 always done using macros that both test the ability to cast the given item,
1414 and perform the cast. Some common ones you will see are:
1417 <item> GTK_WIDGET(widget)
1418 <item> GTK_OBJECT(object)
1419 <item> GTK_SIGNAL_FUNC(function)
1420 <item> GTK_CONTAINER(container)
1421 <item> GTK_WINDOW(window)
1425 These are all used to cast arguments in functions. You'll see them in the
1426 examples, and can usually tell when to use them simply by looking at the
1427 function's declaration.
1429 As you can see below in the class hierarchy, all GtkWidgets are derived from
1430 the GtkObject base class. This means you can use an widget in any place the
1431 function asks for an object - simply use the GTK_OBJECT() macro.
1436 gtk_signal_connect(GTK_OBJECT(button), "clicked",
1437 GTK_SIGNAL_FUNC(callback_function), callback_data);
1440 This casts the button into an object, and provides a cast for the function
1441 pointer to the callback.
1443 Many widgets are also containers. If you look in the class hierarchy below,
1444 you'll notice that many widgets drive from the GtkContainer class. Any one
1445 of those widgets may use with the GTK_CONTAINER macro to
1446 pass them to functions that ask for containers.
1448 Unfortunately, these macros are not extensively covered in the tutorial, but I
1449 recomend taking a look through the GTK header files. It can be very
1450 educational. In fact, it's not difficult to learn how a widget works just
1451 by looking at the function declarations.
1453 <!-- ----------------------------------------------------------------- -->
1454 <sect1>Widget Hierarchy
1456 For your reference, here is the class hierarchy tree used to implement widgets.
1469 | | | `GtkAspectFrame
1474 | | | | `GtkCheckMenuItem
1475 | | | | `GtkRadioMenuItem
1479 | | +GtkColorSelectionDialog
1481 | | | `GtkInputDialog
1482 | | `GtkFileSelection
1485 | | | +GtkHButtonBox
1486 | | | `GtkVButtonBox
1491 | | +GtkColorSelection
1495 | | `GtkToggleButton
1508 | +GtkScrolledWindow
1541 <!-- ----------------------------------------------------------------- -->
1542 <sect1>Widgets Without Windows
1544 The following widgets do not have an associated window. If you want to
1545 capture events, you'll have to use the GtkEventBox. See the section on
1546 <ref id="sec_The_EventBox_Widget" name="The EventBox Widget">
1568 We'll further our exploration of GTK by examining each widget in turn,
1569 creating a few simple functions to display them. Another good source is
1570 the testgtk.c program that comes with GTK. It can be found in
1573 <!-- ***************************************************************** -->
1574 <sect>The Button Widget
1575 <!-- ***************************************************************** -->
1577 <!-- ----------------------------------------------------------------- -->
1578 <sect1>Normal Buttons
1580 We've almost seen all there is to see of the button widget. It's pretty
1581 simple. There is however two ways to create a button. You can use the
1582 gtk_button_new_with_label() to create a button with a label, or use
1583 gtk_button_new() to create a blank button. It's then up to you to pack a
1584 label or pixmap into this new button. To do this, create a new box, and
1585 then pack your objects into this box using the usual gtk_box_pack_start,
1586 and then use gtk_container_add to pack the box into the button.
1588 Here's an example of using gtk_button_new to create a button with a
1589 picture and a label in it. I've broken the code to create a box up from
1590 the rest so you can use it in your programs.
1595 #include <gtk/gtk.h>
1597 /* create a new hbox with an image and a label packed into it
1598 * and return the box.. */
1600 GtkWidget *xpm_label_box (GtkWidget *parent, gchar *xpm_filename, gchar *label_text)
1604 GtkWidget *pixmapwid;
1609 /* create box for xpm and label */
1610 box1 = gtk_hbox_new (FALSE, 0);
1611 gtk_container_border_width (GTK_CONTAINER (box1), 2);
1613 /* get style of button.. I assume it's to get the background color.
1614 * if someone knows the real reason, please enlighten me. */
1615 style = gtk_widget_get_style(parent);
1617 /* now on to the xpm stuff.. load xpm */
1618 pixmap = gdk_pixmap_create_from_xpm (parent->window, &mask,
1619 &style->bg[GTK_STATE_NORMAL],
1621 pixmapwid = gtk_pixmap_new (pixmap, mask);
1623 /* create label for button */
1624 label = gtk_label_new (label_text);
1626 /* pack the pixmap and label into the box */
1627 gtk_box_pack_start (GTK_BOX (box1),
1628 pixmapwid, FALSE, FALSE, 3);
1630 gtk_box_pack_start (GTK_BOX (box1), label, FALSE, FALSE, 3);
1632 gtk_widget_show(pixmapwid);
1633 gtk_widget_show(label);
1638 /* our usual callback function */
1639 void callback (GtkWidget *widget, gpointer *data)
1641 g_print ("Hello again - %s was pressed\n", (char *) data);
1645 int main (int argc, char *argv[])
1647 /* GtkWidget is the storage type for widgets */
1652 gtk_init (&argc, &argv);
1654 /* create a new window */
1655 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
1657 gtk_window_set_title (GTK_WINDOW (window), "Pixmap'd Buttons!");
1659 /* It's a good idea to do this for all windows. */
1660 gtk_signal_connect (GTK_OBJECT (window), "destroy",
1661 GTK_SIGNAL_FUNC (gtk_exit), NULL);
1663 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
1664 GTK_SIGNAL_FUNC (gtk_exit), NULL);
1667 /* sets the border width of the window. */
1668 gtk_container_border_width (GTK_CONTAINER (window), 10);
1669 gtk_widget_realize(window);
1671 /* create a new button */
1672 button = gtk_button_new ();
1674 /* You should be getting used to seeing most of these functions by now */
1675 gtk_signal_connect (GTK_OBJECT (button), "clicked",
1676 GTK_SIGNAL_FUNC (callback), (gpointer) "cool button");
1678 /* this calls our box creating function */
1679 box1 = xpm_label_box(window, "info.xpm", "cool button");
1681 /* pack and show all our widgets */
1682 gtk_widget_show(box1);
1684 gtk_container_add (GTK_CONTAINER (button), box1);
1686 gtk_widget_show(button);
1688 gtk_container_add (GTK_CONTAINER (window), button);
1690 gtk_widget_show (window);
1692 /* rest in gtk_main and wait for the fun to begin! */
1699 The xpm_label_box function could be used to pack xpm's and labels into any
1700 widget that can be a container.
1702 <!-- ----------------------------------------------------------------- -->
1703 <sect1> Toggle Buttons
1705 Toggle buttons are very similar to normal buttons, except they will always
1706 be in one of two states, alternated by a click. They may be depressed, and
1707 when you click again, they will pop back up. Click again, and they will pop
1710 Toggle buttons are the basis for check buttons and radio buttons, as such,
1711 many of the calls used for toggle buttons are inherited by radio and check
1712 buttons. I will point these out when we come to them.
1714 Creating a new toggle button:
1717 GtkWidget* gtk_toggle_button_new (void);
1719 GtkWidget* gtk_toggle_button_new_with_label (gchar *label);
1722 As you can imagine, these work identically to the normal button widget
1723 calls. The first creates a blank toggle button, and the second, a button
1724 with a label widget already packed into it.
1726 To retrieve the state of the toggle widget, including radio and check
1727 buttons, we use a macro as shown in our example below. This tests the state
1728 of the toggle in a callback. The signal of interest emitted to us by toggle
1729 buttons (the toggle button, check button, and radio button widgets), is the
1730 "toggled" signal. To check the state of these buttons, set up a signal
1731 handler to catch the toggled signal, and use the macro to determine it's
1732 state. The callback will look something like:
1735 void toggle_button_callback (GtkWidget *widget, gpointer data)
1737 if (GTK_TOGGLE_BUTTON (widget)->active)
1739 /* If control reaches here, the toggle button is down */
1743 /* If control reaches here, the toggle button is up */
1753 guint gtk_toggle_button_get_type (void);
1756 No idea... they all have this, but I dunno what it is :)
1760 void gtk_toggle_button_set_mode (GtkToggleButton *toggle_button,
1761 gint draw_indicator);
1768 void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
1772 The above call can be used to set the state of the toggle button, and it's
1773 children the radio and check buttons. Passing
1774 in your created button as the first argument, and a TRUE or FALSE
1775 for the second state argument to specify whether it should be up (released) or
1776 down (depressed). Default is up, or FALSE.
1778 Note that when you use the gtk_toggle_button_set_state() function, and the
1779 state is actually changed, it causes
1780 the "clicked" signal to be emitted from the button.
1783 void gtk_toggle_button_toggled (GtkToggleButton *toggle_button);
1786 This simply toggles the button, and emits the "toggled" signal.
1788 <!-- ----------------------------------------------------------------- -->
1789 <sect1> Check Buttons
1791 Check buttons inherent many properties and functions from the the toggle buttons above,
1793 different. Rather than being buttons with text inside them, they are small
1794 squares with the text to the right of them. These are often seen for
1795 toggling options on and off in applications.
1797 The two creation functions are the same as for the normal button.
1800 GtkWidget* gtk_check_button_new (void);
1802 GtkWidget* gtk_check_button_new_with_label (gchar *label);
1805 The new_with_label function creates a check button with a label beside it.
1807 Checking the state of the check button is identical to that of the toggle
1810 <!-- ----------------------------------------------------------------- -->
1811 <sect1> Radio Buttons
1813 Radio buttons are similar to check buttons except they are grouped so that
1814 only one may be selected/depressed at a time. This is good for places in
1815 your application where you need to select from a short list of options.
1817 Creating a new radio button is done with one of these calls:
1820 GtkWidget* gtk_radio_button_new (GSList *group);
1822 GtkWidget* gtk_radio_button_new_with_label (GSList *group,
1826 You'll notice the extra argument to these calls. They require a group to
1827 perform they're duty properly. The first call should pass NULL as the first
1828 argument. Then create a group using:
1831 GSList* gtk_radio_button_group (GtkRadioButton *radio_button);
1835 The important thing to remember is that gtk_radio_button_group must be
1836 called for each new button added to the group, with the previous button
1837 passed in as an argument. The result is then passed into the call to
1838 gtk_radio_button_new or gtk_radio_button_new_with_label. This allows a
1839 chain of buttons to be established. The example below should make this
1842 It is also a good idea to explicitly set which button should be the
1843 default depressed button with:
1846 void gtk_toggle_button_set_state (GtkToggleButton *toggle_button,
1850 This is described in the section on toggle buttons, and works in exactly the
1853 The following example creates a radio button group with three buttons.
1856 /* radiobuttons.c */
1858 #include <gtk/gtk.h>
1861 void close_application( GtkWidget *widget, gpointer *data ) {
1865 main(int argc,char *argv[])
1867 static GtkWidget *window = NULL;
1871 GtkWidget *separator;
1874 gtk_init(&argc,&argv);
1875 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
1877 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
1878 GTK_SIGNAL_FUNC(close_application),
1881 gtk_window_set_title (GTK_WINDOW (window), "radio buttons");
1882 gtk_container_border_width (GTK_CONTAINER (window), 0);
1884 box1 = gtk_vbox_new (FALSE, 0);
1885 gtk_container_add (GTK_CONTAINER (window), box1);
1886 gtk_widget_show (box1);
1888 box2 = gtk_vbox_new (FALSE, 10);
1889 gtk_container_border_width (GTK_CONTAINER (box2), 10);
1890 gtk_box_pack_start (GTK_BOX (box1), box2, TRUE, TRUE, 0);
1891 gtk_widget_show (box2);
1893 button = gtk_radio_button_new_with_label (NULL, "button1");
1894 gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0);
1895 gtk_widget_show (button);
1897 group = gtk_radio_button_group (GTK_RADIO_BUTTON (button));
1898 button = gtk_radio_button_new_with_label(group, "button2");
1899 gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON (button), TRUE);
1900 gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0);
1901 gtk_widget_show (button);
1903 group = gtk_radio_button_group (GTK_RADIO_BUTTON (button));
1904 button = gtk_radio_button_new_with_label(group, "button3");
1905 gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0);
1906 gtk_widget_show (button);
1908 separator = gtk_hseparator_new ();
1909 gtk_box_pack_start (GTK_BOX (box1), separator, FALSE, TRUE, 0);
1910 gtk_widget_show (separator);
1912 box2 = gtk_vbox_new (FALSE, 10);
1913 gtk_container_border_width (GTK_CONTAINER (box2), 10);
1914 gtk_box_pack_start (GTK_BOX (box1), box2, FALSE, TRUE, 0);
1915 gtk_widget_show (box2);
1917 button = gtk_button_new_with_label ("close");
1918 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
1919 GTK_SIGNAL_FUNC(close_application),
1920 GTK_OBJECT (window));
1921 gtk_box_pack_start (GTK_BOX (box2), button, TRUE, TRUE, 0);
1922 GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT);
1923 gtk_widget_grab_default (button);
1924 gtk_widget_show (button);
1925 gtk_widget_show (window);
1932 You can shorten this slightly by using the following syntax, which
1933 removes the need for a variable to hold the list of buttons:
1936 button2 = gtk_radio_button_new_with_label(
1937 gtk_radio_button_group (GTK_RADIO_BUTTON (button1)),
1941 <!-- ***************************************************************** -->
1942 <sect> Miscallaneous Widgets
1943 <!-- ***************************************************************** -->
1945 <!-- ----------------------------------------------------------------- -->
1948 Labels are used a lot in GTK, and are relatively simple. Labels emit no
1949 signals as they do not have an associated X window. If you need to catch
1950 signals, or do clipping, use the EventBox widget.
1952 To create a new label, use:
1955 GtkWidget* gtk_label_new (char *str);
1958 Where the sole argument is the string you wish the label to display.
1960 To change the label's text after creation, use the function:
1963 void gtk_label_set (GtkLabel *label,
1967 Where the first argument is the label you created previously (casted using
1968 the GTK_LABEL() macro), and the second is the new string.
1970 The space needed for the new string will be automatically adjusted if needed.
1972 To retrieve the current string, use:
1975 void gtk_label_get (GtkLabel *label,
1979 Where the first arguement is the label you've created, and the second, the
1980 return for the string.
1982 <!-- ----------------------------------------------------------------- -->
1983 <sect1>The Tooltips Widget
1985 These are the little text strings that pop up when you leave your pointer
1986 over a button or other widget for a few seconds. They are easy to use, so I
1987 will just explain them without giving an example. If you want to see some
1988 code, take a look at the testgtk.c program distributed with GDK.
1990 Some widgets (such as the label) will not work with tooltips.
1992 The first call you will use to create a new tooltip. You only need to do
1993 this once in a given function. The GtkTooltip this function returns can be
1994 used to create multiple tooltips.
1997 GtkTooltips *gtk_tooltips_new (void);
2000 Once you have created a new tooltip, and the widget you wish to use it on,
2001 simply use this call to set it.
2004 void gtk_tooltips_set_tips (GtkTooltips *tooltips,
2009 The first argument is the tooltip you've already created, followed by the
2010 widget you wish to have this tooltip pop up for, and the text you wish it to
2013 Here's a short example:
2016 GtkTooltips *tooltips;
2019 tooltips = gtk_tooltips_new ();
2020 button = gtk_button_new_with_label ("button 1");
2022 gtk_tooltips_set_tips (tooltips, button, "This is button 1");
2026 There are other calls used with tooltips. I will just list them with a
2027 brief description of what they do.
2030 void gtk_tooltips_destroy (GtkTooltips *tooltips);
2033 Destroy the created tooltips.
2036 void gtk_tooltips_enable (GtkTooltips *tooltips);
2039 Enable a disabled set of tooltips.
2042 void gtk_tooltips_disable (GtkTooltips *tooltips);
2045 Disable an enabled set of tooltips.
2048 void gtk_tooltips_set_delay (GtkTooltips *tooltips,
2052 Sets how many milliseconds you have to hold you pointer over the widget before the
2053 tooltip will pop up. The default is 1000 milliseconds or 1 second.
2056 void gtk_tooltips_set_tips (GtkTooltips *tooltips,
2061 Change the tooltip text of an already created tooltip.
2064 void gtk_tooltips_set_colors (GtkTooltips *tooltips,
2065 GdkColor *background,
2066 GdkColor *foreground);
2069 Set the foreground and background color of the tooltips. Again, I have no
2070 idea how to specify the colors.
2072 And that's all the functions associated with tooltips. More than you'll
2073 ever want to know :)
2075 <!-- ----------------------------------------------------------------- -->
2076 <sect1> Progress Bars
2078 Progress bars are used to show the status of an operation. They are pretty
2079 easy to use, as you will see with the code below. But first lets start out
2080 with the call to create a new progress bar.
2083 GtkWidget *gtk_progress_bar_new (void);
2086 Now that the progress bar has been created we can use it.
2089 void gtk_progress_bar_update (GtkProgressBar *pbar, gfloat percentage);
2092 The first argument is the progress bar you wish to operate on, and the second
2093 argument is the amount 'completed', meaning the amount the progress bar has
2094 been filled from 0-100% (a real number between 0 and 1).
2096 Progress Bars are usually used with timeouts or other such functions (see
2097 section on <ref id="sec_timeouts" name="Timeouts, I/O and Idle Functions">)
2098 to give the illusion of multitasking. All will employ
2099 the gtk_progress_bar_update function in the same manner.
2101 Here is an example of the progress bar, updated using timeouts. This
2102 code also shows you how to reset the Progress Bar.
2107 #include <gtk/gtk.h>
2109 static int ptimer = 0;
2112 /* This function increments and updates the progress bar, it also resets
2113 the progress bar if pstat is FALSE */
2114 gint progress (gpointer data)
2118 /* get the current value of the progress bar */
2119 pvalue = GTK_PROGRESS_BAR (data)->percentage;
2121 if ((pvalue >= 1.0) || (pstat == FALSE)) {
2127 gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
2132 /* This function signals a reset of the progress bar */
2133 void progress_r (void)
2138 void destroy (GtkWidget *widget, gpointer *data)
2143 int main (int argc, char *argv[])
2151 gtk_init (&argc, &argv);
2153 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
2155 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
2156 GTK_SIGNAL_FUNC (destroy), NULL);
2158 gtk_container_border_width (GTK_CONTAINER (window), 10);
2160 table = gtk_table_new(3,2,TRUE);
2161 gtk_container_add (GTK_CONTAINER (window), table);
2163 label = gtk_label_new ("Progress Bar Example");
2164 gtk_table_attach_defaults(GTK_TABLE(table), label, 0,2,0,1);
2165 gtk_widget_show(label);
2167 /* Create a new progress bar, pack it into the table, and show it */
2168 pbar = gtk_progress_bar_new ();
2169 gtk_table_attach_defaults(GTK_TABLE(table), pbar, 0,2,1,2);
2170 gtk_widget_show (pbar);
2172 /* Set the timeout to handle automatic updating of the progress bar */
2173 ptimer = gtk_timeout_add (100, progress, pbar);
2175 /* This button signals the progress bar to be reset */
2176 button = gtk_button_new_with_label ("Reset");
2177 gtk_signal_connect (GTK_OBJECT (button), "clicked",
2178 GTK_SIGNAL_FUNC (progress_r), NULL);
2179 gtk_table_attach_defaults(GTK_TABLE(table), button, 0,1,2,3);
2180 gtk_widget_show(button);
2182 button = gtk_button_new_with_label ("Cancel");
2183 gtk_signal_connect (GTK_OBJECT (button), "clicked",
2184 GTK_SIGNAL_FUNC (destroy), NULL);
2186 gtk_table_attach_defaults(GTK_TABLE(table), button, 1,2,2,3);
2187 gtk_widget_show (button);
2189 gtk_widget_show(table);
2190 gtk_widget_show(window);
2198 In this small program there are four areas that concern the general operation
2199 of Progress Bars, we will look at them in the order they are called.
2202 pbar = gtk_progress_bar_new ();
2205 This code creates a new progress bar, called pbar.
2208 ptimer = gtk_timeout_add (100, progress, pbar);
2211 This code, uses timeouts to enable a constant time interval, timeouts are
2212 not necessary in the use of Progress Bars.
2215 pvalue = GTK_PROGRESS_BAR (data)->percentage;
2218 This code assigns the current value of the percentage bar to pvalue.
2221 gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
2224 Finally, this code updates the progress bar with the value of pvalue
2226 And that is all there is to know about Progress Bars, enjoy.
2228 <!-- ----------------------------------------------------------------- -->
2232 The Dialog widget is very simple, and is actually just a window with a few
2233 things pre-packed into it for you. The structure for a Dialog is:
2241 GtkWidget *action_area;
2245 So you see, it simple creates a window, and then packs a vbox into the top,
2246 then a seperator, and then an hbox for the "action_area".
2248 The Dialog widget can be used for pop-up messages to the user, and
2249 other similar tasks. It is really basic, and there is only one
2250 function for the dialog box, which is:
2253 GtkWidget* gtk_dialog_new (void);
2256 So to create a new dialog box, use,
2260 window = gtk_dialog_new ();
2263 This will create the dialog box, and it is now up to you to use it.
2264 you could pack a button in the action_area by doing something like so:
2268 gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button,
2270 gtk_widget_show (button);
2273 And you could add to the vbox area by packing, for instance, a label
2274 in it, try something like this:
2277 label = gtk_label_new ("Dialogs are groovy");
2278 gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->vbox), label, TRUE,
2280 gtk_widget_show (label);
2283 As an example in using the dialog box, you could put two buttons in
2284 the action_area, a Cancel button and an Ok button, and a label in the vbox
2285 area, asking the user a question or giving an error etc. Then you could
2286 attach a different signal to each of the buttons and perform the
2287 operation the user selects.
2289 <!-- ----------------------------------------------------------------- -->
2292 Pixmaps are data structures that contain pictures. These pictures can be
2293 used in various places, but most visibly as icons on the X-Windows desktop,
2294 or as cursors. A bitmap is a 2-color pixmap.
2296 To use pixmaps in GTK, we must first build a GdkPixmap structure using
2297 routines from the GDK layer. Pixmaps can either be created from in-memory
2298 data, or from data read from a file. We'll go through each of the calls
2302 GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window,
2308 This routine is used to create a single-plane pixmap (2 colors) from data in
2309 memory. Each bit of the data represents whether that pixel is off or on.
2310 Width and height are in pixels. The GdkWindow pointer is to the current
2311 window, since a pixmap resources are meaningful only in the context of the
2312 screen where it is to be displayed.
2315 GdkPixmap* gdk_pixmap_create_from_data( GdkWindow *window,
2324 This is used to create a pixmap of the given depth (number of colors) from
2325 the bitmap data specified. fg and bg are the foreground and background
2329 GdkPixmap* gdk_pixmap_create_from_xpm( GdkWindow *window,
2331 GdkColor *transparent_color,
2332 const gchar *filename );
2335 XPM format is a readable pixmap representation for the X Window System. It
2336 is widely used and many different utilities are available for creating image
2337 files in this format. The file specified by filename must contain an image
2338 in that format and it is loaded into the pixmap structure. The mask specifies
2339 what bits of the pixmap are opaque. All other bits are colored using the
2340 color specified by transparent_color. An example using this follows below.
2343 GdkPixmap* gdk_pixmap_create_from_xpm_d (GdkWindow *window,
2345 GdkColor *transparent_color,
2349 Small images can be incorporated into a program as data in the XPM format.
2350 A pixmap is created using this data, instead of reading it from a file.
2351 An example of such data is
2355 static const char * xpm_data[] = {
2358 ". c #000000000000",
2359 "X c #FFFFFFFFFFFF",
2379 void gdk_pixmap_destroy( GdkPixmap *pixmap );
2382 When we're done using a pixmap and not likely to reuse it again soon,
2383 it is a good idea to release the resource using gdk_pixmap_destroy. Pixmaps
2384 should be considered a precious resource.
2387 Once we've created a pixmap, we can display it as a GTK widget. We must
2388 create a pixmap widget to contain the GDK pixmap. This is done using
2391 GtkWidget* gtk_pixmap_new( GdkPixmap *pixmap,
2395 The other pixmap widget calls are
2398 guint gtk_pixmap_get_type( void );
2399 void gtk_pixmap_set( GtkPixmap *pixmap,
2402 void gtk_pixmap_get( GtkPixmap *pixmap,
2407 gtk_pixmap_set is used to change the pixmap that the widget is currently
2408 managing. Val is the pixmap created using GDK.
2410 The following is an example of using a pixmap in a button.
2415 #include <gtk/gtk.h>
2418 /* XPM data of Open-File icon */
2419 static const char * xpm_data[] = {
2422 ". c #000000000000",
2423 "X c #FFFFFFFFFFFF",
2442 /* when invoked (via signal delete_event), terminates the application.
2444 void close_application( GtkWidget *widget, gpointer *data ) {
2449 /* is invoked when the button is clicked. It just prints a message.
2451 void button_clicked( GtkWidget *widget, gpointer *data ) {
2452 printf( "button clicked\n" );
2455 int main( int argc, char *argv[] )
2457 /* GtkWidget is the storage type for widgets */
2458 GtkWidget *window, *pixmapwid, *button;
2463 /* create the main window, and attach delete_event signal to terminating
2465 gtk_init( &argc, &argv );
2466 window = gtk_window_new( GTK_WINDOW_TOPLEVEL );
2467 gtk_signal_connect( GTK_OBJECT (window), "delete_event",
2468 GTK_SIGNAL_FUNC (close_application), NULL );
2469 gtk_container_border_width( GTK_CONTAINER (window), 10 );
2470 gtk_widget_show( window );
2472 /* now for the pixmap from gdk */
2473 style = gtk_widget_get_style( window );
2474 pixmap = gdk_pixmap_create_from_xpm_d( window->window, &mask,
2475 &style->bg[GTK_STATE_NORMAL],
2476 (gchar **)xpm_data );
2478 /* a pixmap widget to contain the pixmap */
2479 pixmapwid = gtk_pixmap_new( pixmap, mask );
2480 gtk_widget_show( pixmapwid );
2482 /* a button to contain the pixmap widget */
2483 button = gtk_button_new();
2484 gtk_container_add( GTK_CONTAINER(button), pixmapwid );
2485 gtk_container_add( GTK_CONTAINER(window), button );
2486 gtk_widget_show( button );
2488 gtk_signal_connect( GTK_OBJECT(button), "clicked",
2489 GTK_SIGNAL_FUNC(button_clicked), NULL );
2491 /* show the window */
2499 To load a file from an XPM data file called icon0.xpm in the current
2500 directory, we would have created the pixmap thus
2503 /* load a pixmap from a file */
2504 pixmap = gdk_pixmap_create_from_xpm( window->window, &mask,
2505 &style->bg[GTK_STATE_NORMAL],
2507 pixmapwid = gtk_pixmap_new( pixmap, mask );
2508 gtk_widget_show( pixmapwid );
2509 gtk_container_add( GTK_CONTAINER(window), pixmapwid );
2516 A disadvantage of using pixmaps is that the displayed object is always
2517 rectangular, regardless of the image. We would like to create desktops
2518 and applications with icons that have more natural shapes. For example,
2519 for a game interface, we would like to have round buttons to push. The
2520 way to do this is using shaped windows.
2522 A shaped window is simply a pixmap where the background pixels are
2523 transparent. This way, when the background image is multi-colored, we
2524 don't overwrite it with a rectangular, non-matching border around our
2525 icon. The following example displays a full wheelbarrow image on the
2531 #include <gtk/gtk.h>
2534 static char * WheelbarrowFull_xpm[] = {
2537 ". c #DF7DCF3CC71B",
2538 "X c #965875D669A6",
2539 "o c #71C671C671C6",
2540 "O c #A699A289A699",
2541 "+ c #965892489658",
2542 "@ c #8E38410330C2",
2543 "# c #D75C7DF769A6",
2544 "$ c #F7DECF3CC71B",
2545 "% c #96588A288E38",
2546 "& c #A69992489E79",
2547 "* c #8E3886178E38",
2548 "= c #104008200820",
2549 "- c #596510401040",
2550 "; c #C71B30C230C2",
2551 ": c #C71B9A699658",
2552 "> c #618561856185",
2553 ", c #20811C712081",
2554 "< c #104000000000",
2555 "1 c #861720812081",
2556 "2 c #DF7D4D344103",
2557 "3 c #79E769A671C6",
2558 "4 c #861782078617",
2559 "5 c #41033CF34103",
2560 "6 c #000000000000",
2561 "7 c #49241C711040",
2562 "8 c #492445144924",
2563 "9 c #082008200820",
2564 "0 c #69A618611861",
2565 "q c #B6DA71C65144",
2566 "w c #410330C238E3",
2567 "e c #CF3CBAEAB6DA",
2568 "r c #71C6451430C2",
2569 "t c #EFBEDB6CD75C",
2570 "y c #28A208200820",
2571 "u c #186110401040",
2572 "i c #596528A21861",
2573 "p c #71C661855965",
2574 "a c #A69996589658",
2575 "s c #30C228A230C2",
2576 "d c #BEFBA289AEBA",
2577 "f c #596545145144",
2578 "g c #30C230C230C2",
2579 "h c #8E3882078617",
2580 "j c #208118612081",
2581 "k c #38E30C300820",
2582 "l c #30C2208128A2",
2583 "z c #38E328A238E3",
2584 "x c #514438E34924",
2585 "c c #618555555965",
2586 "v c #30C2208130C2",
2587 "b c #38E328A230C2",
2588 "n c #28A228A228A2",
2589 "m c #41032CB228A2",
2590 "M c #104010401040",
2591 "N c #492438E34103",
2592 "B c #28A2208128A2",
2593 "V c #A699596538E3",
2594 "C c #30C21C711040",
2595 "Z c #30C218611040",
2596 "A c #965865955965",
2597 "S c #618534D32081",
2598 "D c #38E31C711040",
2599 "F c #082000000820",
2608 "ty> 459@>+&& ",
2610 "%$;=* *3:.Xa.dfg> ",
2611 "Oh$;ya *3d.a8j,Xe.d3g8+ ",
2612 " Oh$;ka *3d$a8lz,,xxc:.e3g54 ",
2613 " Oh$;kO *pd$%svbzz,sxxxxfX..&wn> ",
2614 " Oh$@mO *3dthwlsslszjzxxxxxxx3:td8M4 ",
2615 " Oh$@g& *3d$XNlvvvlllm,mNwxxxxxxxfa.:,B* ",
2616 " Oh$@,Od.czlllllzlmmqV@V#V@fxxxxxxxf:%j5& ",
2617 " Oh$1hd5lllslllCCZrV#r#:#2AxxxxxxxxxcdwM* ",
2618 " OXq6c.%8vvvllZZiqqApA:mq:Xxcpcxxxxxfdc9* ",
2619 " 2r<6gde3bllZZrVi7S@SV77A::qApxxxxxxfdcM ",
2620 " :,q-6MN.dfmZZrrSS:#riirDSAX@Af5xxxxxfevo",
2621 " +A26jguXtAZZZC7iDiCCrVVii7Cmmmxxxxxx%3g",
2622 " *#16jszN..3DZZZZrCVSA2rZrV7Dmmwxxxx&en",
2623 " p2yFvzssXe:fCZZCiiD7iiZDiDSSZwwxx8e*>",
2624 " OA1<jzxwwc:$d%NDZZZZCCCZCCZZCmxxfd.B ",
2625 " 3206Bwxxszx%et.eaAp77m77mmmf3&eeeg* ",
2626 " @26MvzxNzvlbwfpdettttttttttt.c,n& ",
2627 " *;16=lsNwwNwgsvslbwwvccc3pcfu<o ",
2628 " p;<69BvwwsszslllbBlllllllu<5+ ",
2629 " OS0y6FBlvvvzvzss,u=Blllj=54 ",
2630 " c1-699Blvlllllu7k96MMMg4 ",
2631 " *10y8n6FjvllllB<166668 ",
2632 " S-kg+>666<M<996-y6n<8* ",
2633 " p71=4 m69996kD8Z-66698&& ",
2634 " &i0ycm6n4 ogk17,0<6666g ",
2635 " N-k-<> >=01-kuu666> ",
2636 " ,6ky& &46-10ul,66, ",
2637 " Ou0<> o66y<ulw<66& ",
2638 " *kk5 >66By7=xu664 ",
2639 " <<M4 466lj<Mxu66o ",
2640 " *>> +66uv,zN666* ",
2650 /* when invoked (via signal delete_event), terminates the application.
2652 void close_application( GtkWidget *widget, gpointer *data ) {
2656 int main (int argc, char *argv[])
2658 /* GtkWidget is the storage type for widgets */
2659 GtkWidget *window, *pixmap, *fixed;
2660 GdkPixmap *gdk_pixmap;
2665 /* create the main window, and attach delete_event signal to terminate
2666 the application. Note that the main window will not have a titlebar
2667 since we're making it a popup. */
2668 gtk_init (&argc, &argv);
2669 window = gtk_window_new( GTK_WINDOW_POPUP );
2670 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
2671 GTK_SIGNAL_FUNC (close_application), NULL);
2672 gtk_widget_show (window);
2674 /* now for the pixmap and the pixmap widget */
2675 style = gtk_widget_get_default_style();
2676 gc = style->black_gc;
2677 gdk_pixmap = gdk_pixmap_create_from_xpm_d( window->window, &mask,
2678 &style->bg[GTK_STATE_NORMAL],
2679 WheelbarrowFull_xpm );
2680 pixmap = gtk_pixmap_new( gdk_pixmap, mask );
2681 gtk_widget_show( pixmap );
2683 /* To display the pixmap, we use a fixed widget to place the pixmap */
2684 fixed = gtk_fixed_new();
2685 gtk_widget_set_usize( fixed, 200, 200 );
2686 gtk_fixed_put( GTK_FIXED(fixed), pixmap, 0, 0 );
2687 gtk_container_add( GTK_CONTAINER(window), fixed );
2688 gtk_widget_show( fixed );
2690 /* This masks out everything except for the image itself */
2691 gtk_widget_shape_combine_mask( window, mask, 0, 0 );
2693 /* show the window */
2694 gtk_widget_set_uposition( window, 20, 400 );
2695 gtk_widget_show( window );
2702 To make the wheelbarrow image sensitive, we could attach the button press
2703 event signal to make it do something. The following few lines would make
2704 the picture sensitive to a mouse button being pressed which makes the
2705 application terminate.
2708 gtk_widget_set_events( window,
2709 gtk_widget_get_events( window ) |
2710 GDK_BUTTON_PRESS_MASK );
2712 gtk_signal_connect( GTK_OBJECT(window), "button_press_event",
2713 GTK_SIGNAL_FUNC(close_application), NULL );
2716 <!-- ----------------------------------------------------------------- -->
2719 Ruler widgets are used to indicate the location of the mouse pointer
2720 in a given window. A window can have a vertical ruler spanning across
2721 the width and a horizontal ruler spanning down the height. A small
2722 triangular indicator on the ruler shows the exact location of the
2723 pointer relative to the ruler.
2725 A ruler must first be created. Horizontal and vertical rulers are
2729 GtkWidget *gtk_hruler_new(void); /* horizontal ruler */
2730 GtkWidget *gtk_vruler_new(void); /* vertical ruler */
2733 Once a ruler is created, we can define the unit of measurement. Units
2734 of measure for rulers can be GTK_PIXELS, GTK_INCHES or
2735 GTK_CENTIMETERS. This is set using
2738 void gtk_ruler_set_metric( GtkRuler *ruler,
2739 GtkMetricType metric );
2742 The default measure is GTK_PIXELS.
2745 gtk_ruler_set_metric( GTK_RULER(ruler), GTK_PIXELS );
2748 Other important characteristics of a ruler are how to mark the units
2749 of scale and where the position indicator is initially placed. These
2750 are set for a ruler using
2753 void gtk_ruler_set_range (GtkRuler *ruler,
2760 The lower and upper arguments define the extents of the ruler, and
2761 max_size is the largest possible number that will be displayed.
2762 Position defines the initial position of the pointer indicator within
2765 A vertical ruler can span an 800 pixel wide window thus
2768 gtk_ruler_set_range( GTK_RULER(vruler), 0, 800, 0, 800);
2771 The markings displayed on the ruler will be from 0 to 800, with
2772 a number for every 100 pixels. If instead we wanted the ruler to
2773 range from 7 to 16, we would code
2776 gtk_ruler_set_range( GTK_RULER(vruler), 7, 16, 0, 20);
2779 The indicator on the ruler is a small triangular mark that indicates
2780 the position of the pointer relative to the ruler. If the ruler is
2781 used to follow the mouse pointer, the motion_notify_event signal
2782 should be connected to the motion_notify_event method of the ruler.
2783 To follow all mouse movements within a window area, we would use
2786 #define EVENT_METHOD(i, x) GTK_WIDGET_CLASS(GTK_OBJECT(i)->klass)->x
2788 gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event",
2789 (GtkSignalFunc)EVENT_METHOD(ruler, motion_notify_event),
2790 GTK_OBJECT(ruler) );
2793 The following example creates a drawing area with a horizontal ruler
2794 above it and a vertical ruler to the left of it. The size of the
2795 drawing area is 600 pixels wide by 400 pixels high. The horizontal
2796 ruler spans from 7 to 13 with a mark every 100 pixels, while the
2797 vertical ruler spans from 0 to 400 with a mark every 100 pixels.
2798 Placement of the drawing area and the rulers are done using a table.
2803 #include <gtk/gtk.h>
2805 #define EVENT_METHOD(i, x) GTK_WIDGET_CLASS(GTK_OBJECT(i)->klass)->x
2810 /* this routine gets control when the close button is clicked
2812 void close_application( GtkWidget *widget, gpointer *data ) {
2819 int main( int argc, char *argv[] ) {
2820 GtkWidget *window, *table, *area, *hrule, *vrule;
2822 /* initialize gtk and create the main window */
2823 gtk_init( &argc, &argv );
2825 window = gtk_window_new( GTK_WINDOW_TOPLEVEL );
2826 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
2827 GTK_SIGNAL_FUNC( close_application ), NULL);
2828 gtk_container_border_width (GTK_CONTAINER (window), 10);
2830 /* create a table for placing the ruler and the drawing area */
2831 table = gtk_table_new( 3, 2, FALSE );
2832 gtk_container_add( GTK_CONTAINER(window), table );
2834 area = gtk_drawing_area_new();
2835 gtk_drawing_area_size( (GtkDrawingArea *)area, XSIZE, YSIZE );
2836 gtk_table_attach( GTK_TABLE(table), area, 1, 2, 1, 2,
2837 GTK_EXPAND|GTK_FILL, GTK_FILL, 0, 0 );
2838 gtk_widget_set_events( area, GDK_POINTER_MOTION_MASK | GDK_POINTER_MOTION_HINT_MASK );
2840 /* The horizontal ruler goes on top. As the mouse moves across the drawing area,
2841 a motion_notify_event is passed to the appropriate event handler for the ruler. */
2842 hrule = gtk_hruler_new();
2843 gtk_ruler_set_metric( GTK_RULER(hrule), GTK_PIXELS );
2844 gtk_ruler_set_range( GTK_RULER(hrule), 7, 13, 0, 20 );
2845 gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event",
2846 (GtkSignalFunc)EVENT_METHOD(hrule, motion_notify_event),
2847 GTK_OBJECT(hrule) );
2848 /* GTK_WIDGET_CLASS(GTK_OBJECT(hrule)->klass)->motion_notify_event, */
2849 gtk_table_attach( GTK_TABLE(table), hrule, 1, 2, 0, 1,
2850 GTK_EXPAND|GTK_SHRINK|GTK_FILL, GTK_FILL, 0, 0 );
2852 /* The vertical ruler goes on the left. As the mouse moves across the drawing area,
2853 a motion_notify_event is passed to the appropriate event handler for the ruler. */
2854 vrule = gtk_vruler_new();
2855 gtk_ruler_set_metric( GTK_RULER(vrule), GTK_PIXELS );
2856 gtk_ruler_set_range( GTK_RULER(vrule), 0, YSIZE, 10, YSIZE );
2857 gtk_signal_connect_object( GTK_OBJECT(area), "motion_notify_event",
2859 GTK_WIDGET_CLASS(GTK_OBJECT(vrule)->klass)->motion_notify_event,
2860 GTK_OBJECT(vrule) );
2861 gtk_table_attach( GTK_TABLE(table), vrule, 0, 1, 1, 2,
2862 GTK_FILL, GTK_EXPAND|GTK_SHRINK|GTK_FILL, 0, 0 );
2864 /* now show everything */
2865 gtk_widget_show( area );
2866 gtk_widget_show( hrule );
2867 gtk_widget_show( vrule );
2868 gtk_widget_show( table );
2869 gtk_widget_show( window );
2876 <!-- ----------------------------------------------------------------- -->
2879 Statusbars are simple widgets used to display a text message. They keep a stack
2880 of the messages pushed onto them, so that popping the current message
2881 will re-display the previous text message.
2883 In order to allow different parts of an application to use the same statusbar to display
2884 messages, the statusbar widget issues Context Identifiers which are used to identify
2885 different 'users'. The message on top of the stack is the one displayed, no matter what context
2886 it is in. Messages are stacked in last-in-first-out order, not context identifier order.
2888 A statusbar is created with a call to:
2890 GtkWidget* gtk_statusbar_new (void);
2893 A new Context Identifier is requested using a call to the following function with a short
2894 textual description of the context:
2896 guint gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
2897 const gchar *context_description);
2900 There are three functions that can operate on statusbars.
2902 guint gtk_statusbar_push (GtkStatusbar *statusbar,
2906 void gtk_statusbar_pop (GtkStatusbar *statusbar)
2908 void gtk_statusbar_remove (GtkStatusbar *statusbar,
2913 The first, gtk_statusbar_push, is used to add a new message to the statusbar.
2914 It returns a Message Identifier, which can be passed later to the function gtk_statusbar_remove
2915 to remove the message with the given Message and Context Identifiers from the statusbar's stack.
2917 The function gtk_statusbar_pop removes the message highest in the stack with the given
2920 The following example creates a statusbar and two buttons, one for pushing items
2921 onto the statusbar, and one for popping the last item back off.
2926 #include <gtk/gtk.h>
2929 GtkWidget *status_bar;
2931 void push_item (GtkWidget *widget, gpointer *data)
2933 static int count = 1;
2936 g_snprintf(buff, 20, "Item %d", count++);
2937 gtk_statusbar_push( GTK_STATUSBAR(status_bar), (guint) &data, buff);
2942 void pop_item (GtkWidget *widget, gpointer *data)
2944 gtk_statusbar_pop( GTK_STATUSBAR(status_bar), (guint) &data );
2948 int main (int argc, char *argv[])
2957 gtk_init (&argc, &argv);
2959 /* create a new window */
2960 window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
2961 gtk_widget_set_usize( GTK_WIDGET (window), 200, 100);
2962 gtk_window_set_title(GTK_WINDOW (window), "GTK Statusbar Example");
2963 gtk_signal_connect(GTK_OBJECT (window), "delete_event",
2964 (GtkSignalFunc) gtk_exit, NULL);
2966 vbox = gtk_vbox_new(FALSE, 1);
2967 gtk_container_add(GTK_CONTAINER(window), vbox);
2968 gtk_widget_show(vbox);
2970 status_bar = gtk_statusbar_new();
2971 gtk_box_pack_start (GTK_BOX (vbox), status_bar, TRUE, TRUE, 0);
2972 gtk_widget_show (status_bar);
2974 context_id = gtk_statusbar_get_context_id( GTK_STATUSBAR(status_bar), "Statusbar example");
2976 button = gtk_button_new_with_label("push item");
2977 gtk_signal_connect(GTK_OBJECT(button), "clicked",
2978 GTK_SIGNAL_FUNC (push_item), &context_id);
2979 gtk_box_pack_start(GTK_BOX(vbox), button, TRUE, TRUE, 2);
2980 gtk_widget_show(button);
2982 button = gtk_button_new_with_label("pop last item");
2983 gtk_signal_connect(GTK_OBJECT(button), "clicked",
2984 GTK_SIGNAL_FUNC (pop_item), &context_id);
2985 gtk_box_pack_start(GTK_BOX(vbox), button, TRUE, TRUE, 2);
2986 gtk_widget_show(button);
2988 /* always display the window as the last step so it all splashes on
2989 * the screen at once. */
2990 gtk_widget_show(window);
2998 <!-- ----------------------------------------------------------------- -->
3001 The Entry widget allows text to be typed and displayed in a single line text box.
3002 The text may be set with functions calls that allow new text to replace,
3003 prepend or append the current contents of the Entry widget.
3005 There are two functions for creating Entry widgets:
3007 GtkWidget* gtk_entry_new (void);
3009 GtkWidget* gtk_entry_new_with_max_length (guint16 max);
3012 The first just creates a new Entry widget, whilst the second creates a new Entry and
3013 sets a limit on the length of the text within the Entry..
3015 There are several functions for altering the text which is currently within the Entry widget.
3017 void gtk_entry_set_text (GtkEntry *entry,
3019 void gtk_entry_append_text (GtkEntry *entry,
3021 void gtk_entry_prepend_text (GtkEntry *entry,
3025 The function gtk_entry_set_text sets the contents of the Entry widget, replacing the
3026 current contents. The functions gtk_entry_append_text and gtk_entry_prepend_text allow
3027 the current contents to be appended and prepended to.
3029 The next function allows the current insertion point to be set.
3031 void gtk_entry_set_position (GtkEntry *entry,
3035 The contents of the Entry can be retrieved by using a call to the following function. This
3036 is useful in the callback functions described below.
3038 gchar* gtk_entry_get_text (GtkEntry *entry);
3041 If we don't want the contents of the Entry to be changed by someone typing into it, we
3042 can change it's edittable state.
3044 void gtk_entry_set_editable (GtkEntry *entry,
3048 This function allows us to toggle the edittable state of the Entry widget by passing in
3049 TRUE or FALSE values for the editable argument.
3051 If we are using the Entry where we don't want the text entered to be visible, for
3052 example when a password is being entered, we can use the following function, which
3053 also takes a boolean flag.
3055 void gtk_entry_set_visibility (GtkEntry *entry,
3059 A region of the text may be set as selected by using the following function. This would
3060 most often be used after setting some default text in an Entry, making it easy for the user
3063 void gtk_entry_select_region (GtkEntry *entry,
3068 If we want to catch when the user has entered text, we can connect to the
3069 <tt/activate/ or <tt/changed/ signal. Activate is raised when the user hits
3070 the enter key within the Entry widget. Changed is raised when the text changes at all,
3071 e.g. for every character entered or removed.
3073 The following code is an example of using an Entry widget.
3077 #include <gtk/gtk.h>
3079 void enter_callback(GtkWidget *widget, GtkWidget *entry)
3082 entry_text = gtk_entry_get_text(GTK_ENTRY(entry));
3083 printf("Entry contents: %s\n", entry_text);
3086 void entry_toggle_editable (GtkWidget *checkbutton,
3089 gtk_entry_set_editable(GTK_ENTRY(entry),
3090 GTK_TOGGLE_BUTTON(checkbutton)->active);
3093 void entry_toggle_visibility (GtkWidget *checkbutton,
3096 gtk_entry_set_visibility(GTK_ENTRY(entry),
3097 GTK_TOGGLE_BUTTON(checkbutton)->active);
3100 int main (int argc, char *argv[])
3104 GtkWidget *vbox, *hbox;
3109 gtk_init (&argc, &argv);
3111 /* create a new window */
3112 window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
3113 gtk_widget_set_usize( GTK_WIDGET (window), 200, 100);
3114 gtk_window_set_title(GTK_WINDOW (window), "GTK Entry");
3115 gtk_signal_connect(GTK_OBJECT (window), "delete_event",
3116 (GtkSignalFunc) gtk_exit, NULL);
3118 vbox = gtk_vbox_new (FALSE, 0);
3119 gtk_container_add (GTK_CONTAINER (window), vbox);
3120 gtk_widget_show (vbox);
3122 entry = gtk_entry_new_with_max_length (50);
3123 gtk_signal_connect(GTK_OBJECT(entry), "activate",
3124 GTK_SIGNAL_FUNC(enter_callback),
3126 gtk_entry_set_text (GTK_ENTRY (entry), "hello");
3127 gtk_entry_append_text (GTK_ENTRY (entry), " world");
3128 gtk_entry_select_region (GTK_ENTRY (entry),
3129 0, GTK_ENTRY(entry)->text_length);
3130 gtk_box_pack_start (GTK_BOX (vbox), entry, TRUE, TRUE, 0);
3131 gtk_widget_show (entry);
3133 hbox = gtk_hbox_new (FALSE, 0);
3134 gtk_container_add (GTK_CONTAINER (vbox), hbox);
3135 gtk_widget_show (hbox);
3137 check = gtk_check_button_new_with_label("Editable");
3138 gtk_box_pack_start (GTK_BOX (hbox), check, TRUE, TRUE, 0);
3139 gtk_signal_connect (GTK_OBJECT(check), "toggled",
3140 GTK_SIGNAL_FUNC(entry_toggle_editable), entry);
3141 gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(check), TRUE);
3142 gtk_widget_show (check);
3144 check = gtk_check_button_new_with_label("Visible");
3145 gtk_box_pack_start (GTK_BOX (hbox), check, TRUE, TRUE, 0);
3146 gtk_signal_connect (GTK_OBJECT(check), "toggled",
3147 GTK_SIGNAL_FUNC(entry_toggle_visibility), entry);
3148 gtk_toggle_button_set_state(GTK_TOGGLE_BUTTON(check), TRUE);
3149 gtk_widget_show (check);
3151 button = gtk_button_new_with_label ("Close");
3152 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3153 GTK_SIGNAL_FUNC(gtk_exit),
3154 GTK_OBJECT (window));
3155 gtk_box_pack_start (GTK_BOX (vbox), button, TRUE, TRUE, 0);
3156 GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT);
3157 gtk_widget_grab_default (button);
3158 gtk_widget_show (button);
3160 gtk_widget_show(window);
3167 <!-- ----------------------------------------------------------------- -->
3168 <sect1> Color Selection
3170 The color selection widget is, not surprisingly, a widget for interactive
3171 selection of colors. This composite widget lets the user select a color by manipulating
3172 RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done
3173 either by adjusting single values with sliders or entries, or by picking the desired
3174 color from a hue-saturation wheel/value bar. Optionally, the opacity of the color can also
3177 The color selection widget currently emits only one signal, "color_changed", which is emitted
3178 whenever the current color in the widget changes, either when the user changes it or if
3179 it's set explicitly through gtk_color_selection_set_color().
3181 Lets have a look at what the color selection widget has to offer us. The widget comes
3182 in two flavours; gtk_color_selection and gtk_color_selection_dialog:
3185 GtkWidget *gtk_color_selection_new(void);
3188 You'll probably not be using this constructor directly. It creates an orphan
3189 GtkColorSelection widget which you'll have to parent yourself. The GtkColorSelection widget
3190 inherits from the GtkVBox widget.
3193 GtkWidget *gtk_color_selection_dialog_new(const gchar *title);
3196 This is the most common color selection constructor. It creates a GtkColorSelectionDialog, which
3197 inherits from a GtkDialog. It consists of a GtkFrame containing a GtkColorSelection widget, a
3198 GtkHSeparator and a GtkHBox with three buttons, "Ok", "Cancel" and "Help". You can reach these
3199 buttons by accessing the "ok_button", "cancel_button" and "help_button" widgets in the
3200 GtkColorSelectionDialog structure, (i.e. GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button).
3203 void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel,
3204 GtkUpdateType policy);
3207 This function sets the update policy. The default policy is GTK_UPDATE_CONTINOUS which means that
3208 the current color is updated continously when the user drags the sliders or presses the mouse and drags
3209 in the hue-saturation wheel or value bar. If you experience performance problems, you may
3210 want to set the policy to GTK_UPDATE_DISCONTINOUS or GTK_UPDATE_DELAYED.
3213 void gtk_color_selection_set_opacity(GtkColorSelection *colorsel,
3217 The color selection widget supports adjusting the opacity of a color (also known as the alpha channel).
3218 This is disabled by default. Calling this function with use_opacity set to TRUE enables opacity.
3219 Likewise, use_opacity set to FALSE will disable opacity.
3222 void gtk_color_selection_set_color(GtkColorSelection *colorsel,
3226 You can set the current color explicitly by calling this function with a pointer to an array
3227 of colors (gdouble). The length of the array depends on whether opacity is enabled or not.
3228 Position 0 contains the red component, 1 is green, 2 is blue and opacity is at position 3 (only if
3229 opacity is enabled, see gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0.
3232 void gtk_color_selection_get_color(GtkColorSelection *colorsel,
3236 When you need to query the current color, typically when you've received a "color_changed" signal,
3237 you use this function. Color is a pointer to the array of colors to fill in. See the
3238 gtk_color_selection_set_color() function for the description of this array.
3240 <!-- Need to do a whole section on DnD - TRG
3244 The color sample areas (right under the hue-saturation wheel) supports drag and drop. The type of
3245 drag and drop is "application/x-color". The message data consists of an array of 4
3246 (or 5 if opacity is enabled) gdouble values, where the value at position 0 is 0.0 (opacity
3247 on) or 1.0 (opacity off) followed by the red, green and blue values at positions 1,2 and 3 respectively.
3248 If opacity is enabled, the opacity is passed in the value at position 4.
3251 Here's a simple example demonstrating the use of the GtkColorSelectionDialog. The program displays a window
3252 containing a drawing area. Clicking on it opens a color selection dialog, and changing the color in the
3253 color selection dialog changes the background color.
3257 #include <gdk/gdk.h>
3258 #include <gtk/gtk.h>
3260 GtkWidget *colorseldlg = NULL;
3261 GtkWidget *drawingarea = NULL;
3263 /* Color changed handler */
3265 void color_changed_cb (GtkWidget *widget, GtkColorSelection *colorsel)
3269 GdkColormap *colormap;
3271 /* Get drawingarea colormap */
3273 colormap = gdk_window_get_colormap (drawingarea->window);
3275 /* Get current color */
3277 gtk_color_selection_get_color (colorsel,color);
3279 /* Fit to a unsigned 16 bit integer (0..65535) and insert into the GdkColor structure */
3281 gdk_color.red = (guint16)(color[0]*65535.0);
3282 gdk_color.green = (guint16)(color[1]*65535.0);
3283 gdk_color.blue = (guint16)(color[2]*65535.0);
3285 /* Allocate color */
3287 gdk_color_alloc (colormap, &gdk_color);
3289 /* Set window background color */
3291 gdk_window_set_background (drawingarea->window, &gdk_color);
3295 gdk_window_clear (drawingarea->window);
3298 /* Drawingarea event handler */
3300 gint area_event (GtkWidget *widget, GdkEvent *event, gpointer client_data)
3302 gint handled = FALSE;
3303 GtkWidget *colorsel;
3305 /* Check if we've received a button pressed event */
3307 if (event->type == GDK_BUTTON_PRESS && colorseldlg == NULL)
3309 /* Yes, we have an event and there's no colorseldlg yet! */
3313 /* Create color selection dialog */
3315 colorseldlg = gtk_color_selection_dialog_new("Select background color");
3317 /* Get the GtkColorSelection widget */
3319 colorsel = GTK_COLOR_SELECTION_DIALOG(colorseldlg)->colorsel;
3321 /* Connect to the "color_changed" signal, set the client-data to the colorsel widget */
3323 gtk_signal_connect(GTK_OBJECT(colorsel), "color_changed",
3324 (GtkSignalFunc)color_changed_cb, (gpointer)colorsel);
3326 /* Show the dialog */
3328 gtk_widget_show(colorseldlg);
3334 /* Close down and exit handler */
3336 void destroy_window (GtkWidget *widget, gpointer client_data)
3343 gint main (gint argc, gchar *argv[])
3347 /* Initialize the toolkit, remove gtk-related commandline stuff */
3349 gtk_init (&argc,&argv);
3351 /* Create toplevel window, set title and policies */
3353 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
3354 gtk_window_set_title (GTK_WINDOW(window), "Color selection test");
3355 gtk_window_set_policy (GTK_WINDOW(window), TRUE, TRUE, TRUE);
3357 /* Attach to the "delete" and "destroy" events so we can exit */
3359 gtk_signal_connect (GTK_OBJECT(window), "delete_event",
3360 (GtkSignalFunc)destroy_window, (gpointer)window);
3362 gtk_signal_connect (GTK_OBJECT(window), "destroy",
3363 (GtkSignalFunc)destroy_window, (gpointer)window);
3365 /* Create drawingarea, set size and catch button events */
3367 drawingarea = gtk_drawing_area_new ();
3369 gtk_drawing_area_size (GTK_DRAWING_AREA(drawingarea), 200, 200);
3371 gtk_widget_set_events (drawingarea, GDK_BUTTON_PRESS_MASK);
3373 gtk_signal_connect (GTK_OBJECT(drawingarea), "event",
3374 (GtkSignalFunc)area_event, (gpointer)drawingarea);
3376 /* Add drawingarea to window, then show them both */
3378 gtk_container_add (GTK_CONTAINER(window), drawingarea);
3380 gtk_widget_show (drawingarea);
3381 gtk_widget_show (window);
3383 /* Enter the gtk main loop (this never returns) */
3387 /* Satisfy grumpy compilers */
3392 <!-- ----------------------------------------------------------------- -->
3393 <sect1> File Selections
3395 The file selection widget is a quick and simple way to display a File
3396 dialog box. It comes complete with Ok, Cancel, and Help buttons, a great way
3397 to cut down on programming time.
3399 To create a new file selection box use:
3402 GtkWidget* gtk_file_selection_new (gchar *title);
3405 To set the filename, for example to bring up a specific directory, or
3406 give a default filename, use this function:
3409 void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename);
3412 To grab the text that the user has entered or clicked on, use this
3416 gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel);
3419 There are also pointers to the widgets contained within the file
3420 selection widget. These are:
3425 <item>selection_entry
3426 <item>selection_text
3433 Most likely you will want to use the ok_button, cancel_button, and
3434 help_button pointers in signaling their use.
3436 Included here is an example stolen from testgtk.c, modified to run
3437 on it's own. As you will see, there is nothing much to creating a file
3438 selection widget. While, in this example, the Help button appears on the
3439 screen, it does nothing as there is not a signal attached to it.
3444 #include <gtk/gtk.h>
3446 /* Get the selected filename and print it to the console */
3447 void file_ok_sel (GtkWidget *w, GtkFileSelection *fs)
3449 g_print ("%s\n", gtk_file_selection_get_filename (GTK_FILE_SELECTION (fs)));
3452 void destroy (GtkWidget *widget, gpointer *data)
3457 int main (int argc, char *argv[])
3461 gtk_init (&argc, &argv);
3463 /* Create a new file selection widget */
3464 filew = gtk_file_selection_new ("File selection");
3466 gtk_signal_connect (GTK_OBJECT (filew), "destroy",
3467 (GtkSignalFunc) destroy, &filew);
3468 /* Connect the ok_button to file_ok_sel function */
3469 gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION (filew)->ok_button),
3470 "clicked", (GtkSignalFunc) file_ok_sel, filew );
3472 /* Connect the cancel_button to destroy the widget */
3473 gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (filew)->cancel_button),
3474 "clicked", (GtkSignalFunc) gtk_widget_destroy,
3475 GTK_OBJECT (filew));
3477 /* Lets set the filename, as if this were a save dialog, and we are giving
3478 a default filename */
3479 gtk_file_selection_set_filename (GTK_FILE_SELECTION(filew),
3482 gtk_widget_show(filew);
3488 <!-- ***************************************************************** -->
3489 <sect> Container Widgets
3490 <!-- ***************************************************************** -->
3492 <!-- ----------------------------------------------------------------- -->
3495 The NoteBook Widget is a collection of 'pages' that overlap each other,
3496 each page contains different information. This widget has become more common
3497 lately in GUI programming, and it is a good way to show blocks similar
3498 information that warrant separation in their display.
3500 The first function call you will need to know, as you can probably
3501 guess by now, is used to create a new notebook widget.
3504 GtkWidget* gtk_notebook_new (void);
3507 Once the notebook has been created, there are 12 functions that
3508 operate on the notebook widget. Let's look at them individually.
3510 The first one we will look at is how to position the page indicators.
3511 These page indicators or 'tabs' as they are referred to, can be positioned
3512 in four ways; top, bottom, left, or right.
3515 void gtk_notebook_set_tab_pos (GtkNotebook *notebook, GtkPositionType pos);
3518 GtkPostionType will be one of the following, and they are pretty self explanatory.
3521 <item> GTK_POS_RIGHT
3523 <item> GTK_POS_BOTTOM
3526 GTK_POS_TOP is the default.
3528 Next we will look at how to add pages to the notebook. There are three
3529 ways to add pages to the NoteBook. Let's look at the first two together as
3530 they are quite similar.
3533 void gtk_notebook_append_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);
3535 void gtk_notebook_prepend_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label);
3538 These functions add pages to the notebook by inserting them from the
3539 back of the notebook (append), or the front of the notebook (prepend).
3540 *child is the widget that is placed within the notebook page, and *tab_label is
3541 the label for the page being added.
3543 The final function for adding a page to the notebook contains all of
3544 the properties of the previous two, but it allows you to specify what position
3545 you want the page to be in the notebook.
3548 void gtk_notebook_insert_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget *tab_label, gint position);
3551 The parameters are the same as _append_ and _prepend_ except it
3552 contains an extra parameter, position. This parameter is used to specify what
3553 place this page will inserted to.
3555 Now that we know how to add a page, lets see how we can remove a page
3559 void gtk_notebook_remove_page (GtkNotebook *notebook, gint page_num);
3562 This function takes the page specified by page_num and removes it from
3563 the widget *notebook.
3565 To find out what the current page is in a notebook use the function:
3568 gint gtk_notebook_current_page (GtkNotebook *notebook);
3571 These next two functions are simple calls to move the notebook page
3572 forward or backward. Simply provide the respective function call with the
3573 notebook widget you wish to operate on. Note: When the NoteBook is currently
3574 on the last page, and gtk_notebook_next_page is called, the notebook will
3575 wrap back to the first page. Likewise, if the NoteBook is on the first page,
3576 and gtk_notebook_prev_page is called, the notebook will wrap to the last page.
3579 void gtk_notebook_next_page (GtkNoteBook *notebook);
3580 void gtk_notebook_prev_page (GtkNoteBook *notebook);
3583 This next function sets the 'active' page. If you wish the
3584 notebook to be opened to page 5 for example, you would use this function.
3585 Without using this function, the notebook defaults to the first page.
3588 void gtk_notebook_set_page (GtkNotebook *notebook, gint page_num);
3591 The next two functions add or remove the notebook page tabs and the
3592 notebook border respectively.
3595 void gtk_notebook_set_show_tabs (GtkNotebook *notebook, gint show_tabs);
3596 void gtk_notebook_set_show_border (GtkNotebook *notebook, gint show_border);
3599 show_tabs and show_border can both be either TRUE or FALSE (0 or 1).
3601 Now lets look at an example, it is expanded from the testgtk.c code
3602 that comes with the GTK distribution, and it shows all 13 functions. This
3603 small program, creates a window with a notebook and six buttons. The notebook
3604 contains 11 pages, added in three different ways, appended, inserted, and
3605 prepended. The buttons allow you rotate the tab positions, add/remove the tabs
3606 and border, remove a page, change pages in both a forward and backward manner,
3607 and exit the program.
3612 #include <gtk/gtk.h>
3614 /* This function rotates the position of the tabs */
3615 void rotate_book (GtkButton *button, GtkNotebook *notebook)
3617 gtk_notebook_set_tab_pos (notebook, (notebook->tab_pos +1) %4);
3620 /* Add/Remove the page tabs and the borders */
3621 void tabsborder_book (GtkButton *button, GtkNotebook *notebook)
3625 if (notebook->show_tabs == 0)
3627 if (notebook->show_border == 0)
3630 gtk_notebook_set_show_tabs (notebook, tval);
3631 gtk_notebook_set_show_border (notebook, bval);
3634 /* Remove a page from the notebook */
3635 void remove_book (GtkButton *button, GtkNotebook *notebook)
3639 page = gtk_notebook_current_page(notebook);
3640 gtk_notebook_remove_page (notebook, page);
3641 /* Need to refresh the widget --
3642 This forces the widget to redraw itself. */
3643 gtk_widget_draw(GTK_WIDGET(notebook), NULL);
3646 void delete (GtkWidget *widget, gpointer *data)
3651 int main (int argc, char *argv[])
3656 GtkWidget *notebook;
3659 GtkWidget *checkbutton;
3664 gtk_init (&argc, &argv);
3666 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
3668 gtk_signal_connect (GTK_OBJECT (window), "delete_event",
3669 GTK_SIGNAL_FUNC (delete), NULL);
3671 gtk_container_border_width (GTK_CONTAINER (window), 10);
3673 table = gtk_table_new(2,6,TRUE);
3674 gtk_container_add (GTK_CONTAINER (window), table);
3676 /* Create a new notebook, place the position of the tabs */
3677 notebook = gtk_notebook_new ();
3678 gtk_notebook_set_tab_pos (GTK_NOTEBOOK (notebook), GTK_POS_TOP);
3679 gtk_table_attach_defaults(GTK_TABLE(table), notebook, 0,6,0,1);
3680 gtk_widget_show(notebook);
3682 /* lets append a bunch of pages to the notebook */
3683 for (i=0; i < 5; i++) {
3684 sprintf(bufferf, "Append Frame %d", i+1);
3685 sprintf(bufferl, "Page %d", i+1);
3687 frame = gtk_frame_new (bufferf);
3688 gtk_container_border_width (GTK_CONTAINER (frame), 10);
3689 gtk_widget_set_usize (frame, 100, 75);
3690 gtk_widget_show (frame);
3692 label = gtk_label_new (bufferf);
3693 gtk_container_add (GTK_CONTAINER (frame), label);
3694 gtk_widget_show (label);
3696 label = gtk_label_new (bufferl);
3697 gtk_notebook_append_page (GTK_NOTEBOOK (notebook), frame, label);
3701 /* now lets add a page to a specific spot */
3702 checkbutton = gtk_check_button_new_with_label ("Check me please!");
3703 gtk_widget_set_usize(checkbutton, 100, 75);
3704 gtk_widget_show (checkbutton);
3706 label = gtk_label_new ("Add spot");
3707 gtk_container_add (GTK_CONTAINER (checkbutton), label);
3708 gtk_widget_show (label);
3709 label = gtk_label_new ("Add page");
3710 gtk_notebook_insert_page (GTK_NOTEBOOK (notebook), checkbutton, label, 2);
3712 /* Now finally lets prepend pages to the notebook */
3713 for (i=0; i < 5; i++) {
3714 sprintf(bufferf, "Prepend Frame %d", i+1);
3715 sprintf(bufferl, "PPage %d", i+1);
3717 frame = gtk_frame_new (bufferf);
3718 gtk_container_border_width (GTK_CONTAINER (frame), 10);
3719 gtk_widget_set_usize (frame, 100, 75);
3720 gtk_widget_show (frame);
3722 label = gtk_label_new (bufferf);
3723 gtk_container_add (GTK_CONTAINER (frame), label);
3724 gtk_widget_show (label);
3726 label = gtk_label_new (bufferl);
3727 gtk_notebook_prepend_page (GTK_NOTEBOOK(notebook), frame, label);
3730 /* Set what page to start at (page 4) */
3731 gtk_notebook_set_page (GTK_NOTEBOOK(notebook), 3);
3734 /* create a bunch of buttons */
3735 button = gtk_button_new_with_label ("close");
3736 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3737 GTK_SIGNAL_FUNC (delete), NULL);
3738 gtk_table_attach_defaults(GTK_TABLE(table), button, 0,1,1,2);
3739 gtk_widget_show(button);
3741 button = gtk_button_new_with_label ("next page");
3742 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3743 (GtkSignalFunc) gtk_notebook_next_page,
3744 GTK_OBJECT (notebook));
3745 gtk_table_attach_defaults(GTK_TABLE(table), button, 1,2,1,2);
3746 gtk_widget_show(button);
3748 button = gtk_button_new_with_label ("prev page");
3749 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3750 (GtkSignalFunc) gtk_notebook_prev_page,
3751 GTK_OBJECT (notebook));
3752 gtk_table_attach_defaults(GTK_TABLE(table), button, 2,3,1,2);
3753 gtk_widget_show(button);
3755 button = gtk_button_new_with_label ("tab position");
3756 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3757 (GtkSignalFunc) rotate_book, GTK_OBJECT(notebook));
3758 gtk_table_attach_defaults(GTK_TABLE(table), button, 3,4,1,2);
3759 gtk_widget_show(button);
3761 button = gtk_button_new_with_label ("tabs/border on/off");
3762 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3763 (GtkSignalFunc) tabsborder_book,
3764 GTK_OBJECT (notebook));
3765 gtk_table_attach_defaults(GTK_TABLE(table), button, 4,5,1,2);
3766 gtk_widget_show(button);
3768 button = gtk_button_new_with_label ("remove page");
3769 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3770 (GtkSignalFunc) remove_book,
3771 GTK_OBJECT(notebook));
3772 gtk_table_attach_defaults(GTK_TABLE(table), button, 5,6,1,2);
3773 gtk_widget_show(button);
3775 gtk_widget_show(table);
3776 gtk_widget_show(window);
3784 Hopefully this helps you on your way with creating notebooks for your
3787 <!-- ----------------------------------------------------------------- -->
3788 <sect1> Scrolled Windows
3790 Scrolled windows are used to create a scrollable area inside a real window.
3791 You may insert any types of widgets to these scrolled windows, and they will
3792 all be accessable regardless of the size by using the scrollbars.
3794 The following function is used to create a new scolled window.
3797 GtkWidget* gtk_scrolled_window_new (GtkAdjustment *hadjustment,
3798 GtkAdjustment *vadjustment);
3801 Where the first argument is the adjustment for the horizontal
3802 direction, and the second, the adjustment for the vertical direction.
3803 These are almost always set to NULL.
3806 void gtk_scrolled_window_set_policy (GtkScrolledWindow *scrolled_window,
3807 GtkPolicyType hscrollbar_policy,
3808 GtkPolicyType vscrollbar_policy);
3811 This sets the policy to be used with respect to the scrollbars.
3812 The first arguement is the scrolled window you wish to change. The second
3813 sets the policiy for the horizontal scrollbar, and the third,
3814 the vertical scrollbar.
3816 The policy may be one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS.
3817 GTK_POLICY_AUTOMATIC will automatically decide whether you need
3818 scrollbars, wheras GTK_POLICY_ALWAYS will always leave the scrollbars
3821 Here is a simple example that packs 100 toggle buttons into a scrolled window.
3822 I've only commented on the parts that may be new to you.
3827 #include <gtk/gtk.h>
3829 void destroy(GtkWidget *widget, gpointer *data)
3834 int main (int argc, char *argv[])
3836 static GtkWidget *window;
3837 GtkWidget *scrolled_window;
3843 gtk_init (&argc, &argv);
3845 /* Create a new dialog window for the scrolled window to be
3846 * packed into. A dialog is just like a normal window except it has a
3847 * vbox and a horizontal seperator packed into it. It's just a shortcut
3848 * for creating dialogs */
3849 window = gtk_dialog_new ();
3850 gtk_signal_connect (GTK_OBJECT (window), "destroy",
3851 (GtkSignalFunc) destroy, NULL);
3852 gtk_window_set_title (GTK_WINDOW (window), "dialog");
3853 gtk_container_border_width (GTK_CONTAINER (window), 0);
3854 gtk_widget_set_usize(window, 300, 300);
3856 /* create a new scrolled window. */
3857 scrolled_window = gtk_scrolled_window_new (NULL, NULL);
3859 gtk_container_border_width (GTK_CONTAINER (scrolled_window), 10);
3861 /* the policy is one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS.
3862 * GTK_POLICY_AUTOMATIC will automatically decide whether you need
3863 * scrollbars, wheras GTK_POLICY_ALWAYS will always leave the scrollbars
3864 * there. The first one is the horizontal scrollbar, the second,
3866 gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window),
3867 GTK_POLICY_AUTOMATIC, GTK_POLICY_ALWAYS);
3868 /* The dialog window is created with a vbox packed into it. */
3869 gtk_box_pack_start (GTK_BOX (GTK_DIALOG(window)->vbox), scrolled_window,
3871 gtk_widget_show (scrolled_window);
3873 /* create a table of 10 by 10 squares. */
3874 table = gtk_table_new (10, 10, FALSE);
3876 /* set the spacing to 10 on x and 10 on y */
3877 gtk_table_set_row_spacings (GTK_TABLE (table), 10);
3878 gtk_table_set_col_spacings (GTK_TABLE (table), 10);
3880 /* pack the table into the scrolled window */
3881 gtk_container_add (GTK_CONTAINER (scrolled_window), table);
3882 gtk_widget_show (table);
3884 /* this simply creates a grid of toggle buttons on the table
3885 * to demonstrate the scrolled window. */
3886 for (i = 0; i < 10; i++)
3887 for (j = 0; j < 10; j++) {
3888 sprintf (buffer, "button (%d,%d)\n", i, j);
3889 button = gtk_toggle_button_new_with_label (buffer);
3890 gtk_table_attach_defaults (GTK_TABLE (table), button,
3892 gtk_widget_show (button);
3895 /* Add a "close" button to the bottom of the dialog */
3896 button = gtk_button_new_with_label ("close");
3897 gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
3898 (GtkSignalFunc) gtk_widget_destroy,
3899 GTK_OBJECT (window));
3901 /* this makes it so the button is the default. */
3903 GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT);
3904 gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button, TRUE, TRUE, 0);
3906 /* This grabs this button to be the default button. Simply hitting
3907 * the "Enter" key will cause this button to activate. */
3908 gtk_widget_grab_default (button);
3909 gtk_widget_show (button);
3911 gtk_widget_show (window);
3919 Try playing with resizing the window. You'll notice how the scrollbars
3920 react. You may also wish to use the gtk_widget_set_usize() call to set the default
3921 size of the window or other widgets.
3923 <!-- ***************************************************************** -->
3925 <!-- ***************************************************************** -->
3928 The GtkList widget is designed to act as a vertical container for widgets
3929 that should be of the type GtkListItem.
3931 A GtkList widget has its own window to receive events and it's own
3932 background color which is usualy white. As it is directly derived from a
3933 GtkContainer it can be treated as such by using the GTK_CONTAINER(List)
3934 macro, see the GtkContainer widget for more on this.
3935 One should already be familar whith the usage of a GList and its
3936 related functions g_list_*() to be able to use the GtkList widget to
3939 There is one field inside the structure definition of the GtkList widget
3940 that will be of greater interest to us, this is:
3947 guint selection_mode;
3952 The selection field of a GtkList points to a linked list of all items
3953 that are cureently selected, or `NULL' if the selection is empty.
3954 So to learn about the current selection we read the GTK_LIST()->selection
3955 field, but do not modify it since the internal fields are maintained by
3956 the gtk_list_*() functions.
3958 The selection_mode of the GtkList determines the selection facilities
3959 of a GtkList and therefore the contents of the GTK_LIST()->selection
3962 The selection_mode may be one of the following:
3964 <item> GTK_SELECTION_SINGLE - The selection is either `NULL'
3965 or contains a GList* pointer
3966 for a single selected item.
3968 <item> GTK_SELECTION_BROWSE - The selection is `NULL' if the list
3969 contains no widgets or insensitive
3970 ones only, otherwise it contains
3971 a GList pointer for one GList
3972 structure, and therefore exactly
3975 <item> GTK_SELECTION_MULTIPLE - The selection is `NULL' if no list
3976 items are selected or a GList pointer
3977 for the first selected item. That
3978 in turn points to a GList structure
3979 for the second selected item and so
3982 <item> GTK_SELECTION_EXTENDED - The selection is always `NULL'.
3985 The default is GTK_SELECTION_MULTIPLE.
3987 <!-- ----------------------------------------------------------------- -->
3991 void selection_changed (GtkList *LIST)
3994 This signal will be invoked whenever a the selection field
3995 of a GtkList has changed. This happens when a child of
3996 the GtkList got selected or unselected.
3999 void select_child (GtkList *LIST, GtkWidget *CHILD)
4002 This signal is invoked when a child of the GtkList is about
4003 to get selected. This happens mainly on calls to
4004 gtk_list_select_item(), gtk_list_select_child(), button presses
4005 and sometimes indirectly triggered on some else occasions where
4006 children get added to or removed from the GtkList.
4009 void unselect_child (GtkList *LIST, GtkWidget *CHILD)
4012 This signal is invoked when a child of the GtkList is about
4013 to get unselected. This happens mainly on calls to
4014 gtk_list_unselect_item(), gtk_list_unselect_child(), button presses
4015 and sometimes indirectly triggered on some else occasions where
4016 children get added to or removed from the GtkList.
4018 <!-- ----------------------------------------------------------------- -->
4022 guint gtk_list_get_type (void)
4025 Returns the `GtkList' type identifier.
4028 GtkWidget* gtk_list_new (void)
4031 Create a new `GtkList' object. The new widget is
4032 returned as a pointer to a `GtkWidget' object.
4033 `NULL' is returned on failure.
4036 void gtk_list_insert_items (GtkList *LIST, GList *ITEMS, gint POSITION)
4039 Insert list items into the LIST, starting at POSITION.
4040 ITEMS is a doubly linked list where each nodes data
4041 pointer is expected to point to a newly created GtkListItem.
4042 The GList nodes of ITEMS are taken over by the LIST.
4045 void gtk_list_append_items (GtkList *LIST, GList *ITEMS)
4048 Insert list items just like gtk_list_insert_items() at the end
4049 of the LIST. The GList nodes of ITEMS are taken over by the LIST.
4052 void gtk_list_prepend_items (GtkList *LIST, GList *ITEMS)
4055 Insert list items just like gtk_list_insert_items() at the very
4056 beginning of the LIST. The GList nodes of ITEMS are taken over
4060 void gtk_list_remove_items (GtkList *LIST, GList *ITEMS)
4063 Remove list items from the LIST. ITEMS is a doubly linked
4064 list where each nodes data pointer is expected to point to a
4065 direct child of LIST. It is the callers responsibility to make a
4066 call to g_list_free(ITEMS) afterwards. Also the caller has to
4067 destroy the list items himself.
4070 void gtk_list_clear_items (GtkList *LIST, gint START, gint END)
4073 Remove and destroy list items from the LIST. a widget is affected if
4074 its current position within LIST is in the range specified by START
4078 void gtk_list_select_item (GtkList *LIST, gint ITEM)
4081 Invoke the select_child signal for a list item
4082 specified through its current position within LIST.
4085 void gtk_list_unselect_item (GtkList *LIST, gint ITEM)
4088 Invoke the unselect_child signal for a list item
4089 specified through its current position within LIST.
4092 void gtk_list_select_child (GtkList *LIST, GtkWidget *CHILD)
4095 Invoke the select_child signal for the specified CHILD.
4098 void gtk_list_unselect_child (GtkList *LIST, GtkWidget *CHILD)
4101 Invoke the unselect_child signal for the specified CHILD.
4104 gint gtk_list_child_position (GtkList *LIST, GtkWidget *CHILD)
4107 Return the position of CHILD within LIST. `-1' is returned on failure.
4110 void gtk_list_set_selection_mode (GtkList *LIST, GtkSelectionMode MODE)
4113 Set LIST to the selection mode MODE wich can be of GTK_SELECTION_SINGLE,
4114 GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE or GTK_SELECTION_EXTENDED.
4117 GtkList* GTK_LIST (gpointer OBJ)
4120 Cast a generic pointer to `GtkList*'. *Note Standard Macros::, for
4124 GtkListClass* GTK_LIST_CLASS (gpointer CLASS)
4127 Cast a generic pointer to `GtkListClass*'. *Note Standard Macros::,
4131 gint GTK_IS_LIST (gpointer OBJ)
4134 Determine if a generic pointer refers to a `GtkList' object. *Note
4135 Standard Macros::, for more info.
4137 <!-- ----------------------------------------------------------------- -->
4140 Following is an example program that will print out the changes
4141 of the selection of a GtkList, and lets you "arrest" list items
4142 into a prison by selecting them with the rightmost mouse button:
4147 /* include the gtk+ header files
4148 * include stdio.h, we need that for the printf() function
4150 #include <gtk/gtk.h>
4153 /* this is our data identification string to store
4154 * data in list items
4156 const gchar *list_item_data_key="list_item_data";
4159 /* prototypes for signal handler that we are going to connect
4160 * to the GtkList widget
4162 static void sigh_print_selection (GtkWidget *gtklist,
4163 gpointer func_data);
4164 static void sigh_button_event (GtkWidget *gtklist,
4165 GdkEventButton *event,
4169 /* main function to set up the user interface */
4171 gint main (int argc, gchar *argv[])
4173 GtkWidget *separator;
4176 GtkWidget *scrolled_window;
4180 GtkWidget *list_item;
4186 /* initialize gtk+ (and subsequently gdk) */
4188 gtk_init(&argc, &argv);
4191 /* create a window to put all the widgets in
4192 * connect gtk_main_quit() to the "destroy" event of
4193 * the window to handle window manager close-window-events
4195 window=gtk_window_new(GTK_WINDOW_TOPLEVEL);
4196 gtk_window_set_title(GTK_WINDOW(window), "GtkList Example");
4197 gtk_signal_connect(GTK_OBJECT(window),
4199 GTK_SIGNAL_FUNC(gtk_main_quit),
4203 /* inside the window we need a box to arrange the widgets
4205 vbox=gtk_vbox_new(FALSE, 5);
4206 gtk_container_border_width(GTK_CONTAINER(vbox), 5);
4207 gtk_container_add(GTK_CONTAINER(window), vbox);
4208 gtk_widget_show(vbox);
4210 /* this is the scolled window to put the GtkList widget inside */
4211 scrolled_window=gtk_scrolled_window_new(NULL, NULL);
4212 gtk_widget_set_usize(scrolled_window, 250, 150);
4213 gtk_container_add(GTK_CONTAINER(vbox), scrolled_window);
4214 gtk_widget_show(scrolled_window);
4216 /* create the GtkList widget
4217 * connect the sigh_print_selection() signal handler
4218 * function to the "selection_changed" signal of the GtkList
4219 * to print out the selected items each time the selection
4221 gtklist=gtk_list_new();
4222 gtk_container_add(GTK_CONTAINER(scrolled_window), gtklist);
4223 gtk_widget_show(gtklist);
4224 gtk_signal_connect(GTK_OBJECT(gtklist),
4225 "selection_changed",
4226 GTK_SIGNAL_FUNC(sigh_print_selection),
4229 /* we create a "Prison" to put a list item in ;)
4231 frame=gtk_frame_new("Prison");
4232 gtk_widget_set_usize(frame, 200, 50);
4233 gtk_container_border_width(GTK_CONTAINER(frame), 5);
4234 gtk_frame_set_shadow_type(GTK_FRAME(frame), GTK_SHADOW_OUT);
4235 gtk_container_add(GTK_CONTAINER(vbox), frame);
4236 gtk_widget_show(frame);
4238 /* connect the sigh_button_event() signal handler to the GtkList
4239 * wich will handle the "arresting" of list items
4241 gtk_signal_connect(GTK_OBJECT(gtklist),
4242 "button_release_event",
4243 GTK_SIGNAL_FUNC(sigh_button_event),
4246 /* create a separator
4248 separator=gtk_hseparator_new();
4249 gtk_container_add(GTK_CONTAINER(vbox), separator);
4250 gtk_widget_show(separator);
4252 /* finaly create a button and connect it´s "clicked" signal
4253 * to the destroyment of the window
4255 button=gtk_button_new_with_label("Close");
4256 gtk_container_add(GTK_CONTAINER(vbox), button);
4257 gtk_widget_show(button);
4258 gtk_signal_connect_object(GTK_OBJECT(button),
4260 GTK_SIGNAL_FUNC(gtk_widget_destroy),
4261 GTK_OBJECT(window));
4264 /* now we create 5 list items, each having it´s own
4265 * label and add them to the GtkList using gtk_container_add()
4266 * also we query the text string from the label and
4267 * associate it with the list_item_data_key for each list item
4269 for (i=0; i<5; i++) {
4273 sprintf(buffer, "ListItemContainer with Label #%d", i);
4274 label=gtk_label_new(buffer);
4275 list_item=gtk_list_item_new();
4276 gtk_container_add(GTK_CONTAINER(list_item), label);
4277 gtk_widget_show(label);
4278 gtk_container_add(GTK_CONTAINER(gtklist), list_item);
4279 gtk_widget_show(list_item);
4280 gtk_label_get(GTK_LABEL(label), &string);
4281 gtk_object_set_data(GTK_OBJECT(list_item),
4285 /* here, we are creating another 5 labels, this time
4286 * we use gtk_list_item_new_with_label() for the creation
4287 * we can´t query the text string from the label because
4288 * we don´t have the labels pointer and therefore
4289 * we just associate the list_item_data_key of each
4290 * list item with the same text string
4291 * for adding of the list items we put them all into a doubly
4292 * linked list (GList), and then add them by a single call to
4293 * gtk_list_append_items()
4294 * because we use g_list_prepend() to put the items into the
4295 * doubly linked list, their order will be descending (instead
4296 * of ascending when using g_list_append())
4300 sprintf(buffer, "List Item with Label %d", i);
4301 list_item=gtk_list_item_new_with_label(buffer);
4302 dlist=g_list_prepend(dlist, list_item);
4303 gtk_widget_show(list_item);
4304 gtk_object_set_data(GTK_OBJECT(list_item),
4306 "ListItem with integrated Label");
4308 gtk_list_append_items(GTK_LIST(gtklist), dlist);
4310 /* finaly we want to see the window, don´t we? ;)
4312 gtk_widget_show(window);
4314 /* fire up the main event loop of gtk
4318 /* we get here after gtk_main_quit() has been called which
4319 * happens if the main window gets destroyed
4324 /* this is the signal handler that got connected to button
4325 * press/release events of the GtkList
4328 sigh_button_event (GtkWidget *gtklist,
4329 GdkEventButton *event,
4332 /* we only do something if the third (rightmost mouse button
4335 if (event->type==GDK_BUTTON_RELEASE &&
4337 GList *dlist, *free_list;
4338 GtkWidget *new_prisoner;
4340 /* fetch the currently selected list item which
4341 * will be our next prisoner ;)
4343 dlist=GTK_LIST(gtklist)->selection;
4345 new_prisoner=GTK_WIDGET(dlist->data);
4349 /* look for already prisoned list items, we
4350 * will put them back into the list
4351 * remember to free the doubly linked list that
4352 * gtk_container_children() returns
4354 dlist=gtk_container_children(GTK_CONTAINER(frame));
4357 GtkWidget *list_item;
4359 list_item=dlist->data;
4361 gtk_widget_reparent(list_item, gtklist);
4365 g_list_free(free_list);
4367 /* if we have a new prisoner, remove him from the
4368 * GtkList and put him into the frame "Prison"
4369 * we need to unselect the item before
4374 static_dlist.data=new_prisoner;
4375 static_dlist.next=NULL;
4376 static_dlist.prev=NULL;
4378 gtk_list_unselect_child(GTK_LIST(gtklist),
4380 gtk_widget_reparent(new_prisoner, frame);
4385 /* this is the signal handler that gets called if GtkList
4386 * emits the "selection_changed" signal
4389 sigh_print_selection (GtkWidget *gtklist,
4394 /* fetch the doubly linked list of selected items
4395 * of the GtkList, remember to treat this as read-only!
4397 dlist=GTK_LIST(gtklist)->selection;
4399 /* if there are no selected items there is nothing more
4400 * to do than just telling the user so
4403 g_print("Selection cleared\n");
4406 /* ok, we got a selection and so we print it
4408 g_print("The selection is a ");
4410 /* get the list item from the doubly linked list
4411 * and then query the data associated with list_item_data_key
4412 * we then just print it
4415 GtkObject *list_item;
4416 gchar *item_data_string;
4418 list_item=GTK_OBJECT(dlist->data);
4419 item_data_string=gtk_object_get_data(list_item,
4420 list_item_data_key);
4421 g_print("%s ", item_data_string);
4429 <!-- ----------------------------------------------------------------- -->
4430 <sect1> List Item Widget
4432 The GtkListItem widget is designed to act as a container holding up
4433 to one child, providing functions for selection/deselection just like
4434 the GtkList widget requires them for its children.
4436 A GtkListItem has its own window to receive events and has its own
4437 background color which is usualy white.
4439 As it is directly derived from a
4440 GtkItem it can be treated as such by using the GTK_ITEM(ListItem)
4441 macro, see the GtkItem widget for more on this.
4442 Usualy a GtkListItem just holds a label to identify e.g. a filename
4443 within a GtkList -- therefore the convenient function
4444 gtk_list_item_new_with_label() is provided. The same effect can be
4445 achieved by creating a GtkLabel on its own, setting its alignment
4446 to xalign=0 and yalign=0.5 with a subsequent container addition
4449 As one is not forced to add a GtkLabel to a GtkListItem, you could
4450 also add a GtkVBox or a GtkArrow etc. to the GtkListItem.
4452 <!-- ----------------------------------------------------------------- -->
4455 A GtkListItem does not create new signals on its own, but inherits
4456 the signals of a GtkItem. *Note GtkItem::, for more info.
4458 <!-- ----------------------------------------------------------------- -->
4463 guint gtk_list_item_get_type (void)
4466 Returns the `GtkListItem' type identifier.
4469 GtkWidget* gtk_list_item_new (void)
4472 Create a new `GtkListItem' object. The new widget is
4473 returned as a pointer to a `GtkWidget' object.
4474 `NULL' is returned on failure.
4477 GtkWidget* gtk_list_item_new_with_label (gchar *LABEL)
4480 Create a new `GtkListItem' object, having a single GtkLabel as
4481 the sole child. The new widget is returned as a pointer to a
4483 `NULL' is returned on failure.
4486 void gtk_list_item_select (GtkListItem *LIST_ITEM)
4489 This function is basicaly a wrapper around a call to
4490 gtk_item_select (GTK_ITEM (list_item)) which will emit the
4492 *Note GtkItem::, for more info.
4495 void gtk_list_item_deselect (GtkListItem *LIST_ITEM)
4498 This function is basicaly a wrapper around a call to
4499 gtk_item_deselect (GTK_ITEM (list_item)) which will emit the
4501 *Note GtkItem::, for more info.
4504 GtkListItem* GTK_LIST_ITEM (gpointer OBJ)
4507 Cast a generic pointer to `GtkListItem*'. *Note Standard Macros::,
4511 GtkListItemClass* GTK_LIST_ITEM_CLASS (gpointer CLASS)
4514 Cast a generic pointer to `GtkListItemClass*'. *Note Standard
4515 Macros::, for more info.
4518 gint GTK_IS_LIST_ITEM (gpointer OBJ)
4521 Determine if a generic pointer refers to a `GtkListItem' object.
4522 *Note Standard Macros::, for more info.
4524 <!-- ----------------------------------------------------------------- -->
4527 Please see the GtkList example on this, which covers the usage of a
4528 GtkListItem as well.
4530 <!-- ***************************************************************** -->
4532 <!-- ***************************************************************** -->
4535 There are two ways to create menus, there's the easy way, and there's the
4536 hard way. Both have their uses, but you can usually use the menufactory
4537 (the easy way). The "hard" way is to create all the menus using the calls
4538 directly. The easy way is to use the gtk_menu_factory calls. This is
4539 much simpler, but there are advantages and disadvantages to each approach.
4541 The menufactory is much easier to use, and to add new menus to, although
4542 writing a few wrapper functions to create menus using the manual method
4543 could go a long way towards usability. With the menufactory, it is not
4544 possible to add images or the character '/' to the menus.
4546 <!-- ----------------------------------------------------------------- -->
4547 <sect1>Manual Menu Creation
4549 In the true tradition of teaching, we'll show you the hard
4550 way first. <tt>:)</>
4552 There are three widgets that go into making a menubar and submenus:
4554 <item>a menu item, which is what the user wants to select, e.g. 'Save'
4555 <item>a menu, which acts as a container for the menu items, and
4556 <item>a menubar, which is a container for each of the individual menus,
4559 This is slightly complicated by the fact that menu item widgets are used for two different things. They are
4560 both the widets that are packed into the menu, and the widget that is packed into the menubar, which,
4561 when selected, activiates the menu.
4563 Let's look at the functions that are used to create menus and menubars.
4564 This first function is used to create a new menubar.
4567 GtkWidget *gtk_menu_bar_new(void);
4570 This rather self explanatory function creates a new menubar. You use
4571 gtk_container_add to pack this into a window, or the box_pack functions to
4572 pack it into a box - the same as buttons.
4575 GtkWidget *gtk_menu_new();
4578 This function returns a pointer to a new menu, it is never actually shown
4579 (with gtk_widget_show), it is just a container for the menu items. Hopefully this will
4580 become more clear when you look at the example below.
4582 The next two calls are used to create menu items that are packed into
4583 the menu (and menubar).
4586 GtkWidget *gtk_menu_item_new();
4592 GtkWidget *gtk_menu_item_new_with_label(const char *label);
4595 These calls are used to create the menu items that are to be displayed.
4596 Remember to differentiate between a "menu" as created with gtk_menu_new
4597 and a "menu item" as created by the gtk_menu_item_new functions. The
4598 menu item will be an actual button with an associated action,
4599 whereas a menu will be a container holding menu items.
4601 The gtk_menu_new_with_label and gtk_menu_new functions are just as you'd expect after
4602 reading about the buttons. One creates a new menu item with a label
4603 already packed into it, and the other just creates a blank menu item.
4605 Once you've created a menu item you have to put it into a menu. This is done using the function
4606 gtk_menu_append. In order to capture when the item is selected by the user, we need to connect
4607 to the <tt/activate/ signal in the usual way.
4608 So, if we wanted to create a standard <tt/File/ menu, with the options <tt/Open/,
4609 <tt/Save/ and <tt/Quit/ the code would look something like
4612 file_menu = gtk_menu_new(); /* Don't need to show menus */
4614 /* Create the menu items */
4615 open_item = gtk_menu_item_new_with_label("Open");
4616 save_item = gtk_menu_item_new_with_label("Save");
4617 quit_item = gtk_menu_item_new_with_label("Quit");
4619 /* Add them to the menu */
4620 gtk_menu_append( GTK_MENU(file_menu), open_item);
4621 gtk_menu_append( GTK_MENU(file_menu), save_item);
4622 gtk_menu_append( GTK_MENU(file_menu), quit_item);
4624 /* Attach the callback functions to the activate signal */
4625 gtk_signal_connect_object( GTK_OBJECT(open_items), "activate",
4626 GTK_SIGNAL_FUNC(menuitem_response), (gpointer) "file.open");
4627 gtk_signal_connect_object( GTK_OBJECT(save_items), "activate",
4628 GTK_SIGNAL_FUNC(menuitem_response), (gpointer) "file.save");
4630 /* We can attach the Quit menu item to our exit function */
4631 gtk_signal_connect_object( GTK_OBJECT(quit_items), "activate",
4632 GTK_SIGNAL_FUNC(destroy), (gpointer) "file.quit");
4634 /* We do need to show menu items */
4635 gtk_widget_show( open_item );
4636 gtk_widget_show( save_item );
4637 gtk_widget_show( quit_item );
4640 At this point we have our menu. Now we need to create a menubar and a menu item for the <tt/File/ entry,
4641 to which we add our menu. The code looks like this
4644 menu_bar = gtk_menu_bar_new();
4645 gtk_container_add( GTK_CONTAINER(window), menu_bar);
4646 gtk_widget_show( menu_bar );
4648 file_item = gtk_menu_item_new_with_label("File");
4649 gtk_widget_show(file_item);
4652 Now we need to associate the menu with <tt/file_item/. This is done with the function
4655 void gtk_menu_item_set_submenu( GtkMenuItem *menu_item,
4656 GtkWidget *submenu);
4659 So, our example would continue with
4662 gtk_menu_item_set_submenu( GTK_MENU_ITEM(file_item), file_menu);
4665 All that is left to do is to add the menu to the menubar, which is accomplished using the function
4668 void gtk_menu_bar_append( GtkMenuBar *menu_bar, GtkWidget *menu_item);
4671 which in our case looks like this:
4674 gtk_menu_bar_append( menu_bar, file_item );
4677 If we wanted the menu right justified on the menubar, such as help menus often are, we can
4678 use the following function (again on <tt/file_item/ in the current example) before attaching
4681 void gtk_menu_item_right_justify (GtkMenuItem *menu_item);
4684 Here is a summary of the steps needed to create a menu bar with menus attached:
4686 <item> Create a new menu using gtk_menu_new()
4687 <item> Use multiple calls to gtk_menu_item_new() for each item you wish to have on
4688 your menu. And use gtk_menu_append() to put each of these new items on
4690 <item> Create a menu item using gtk_menu_item_new(). This will be the root of
4691 the menu, the text appearing here will be on the menubar itself.
4692 <item> Use gtk_menu_item_set_submenu() to attach the menu to
4693 the root menu item (The one created in the above step).
4694 <item> Create a new menubar using gtk_menu_bar_new. This step only needs
4695 to be done once when creating a series of menus on one menu bar.
4696 <item> Use gtk_menu_bar_append to put the root menu onto the menubar.
4699 Creating a popup menu is nearly the same. The difference is that the
4700 menu is not posted `automatically' by a menubar, but explicitly
4701 by calling the function gtk_menu_popup() from a button-press event, for example.
4704 <item>Create an event handling function. It needs to have the prototype
4706 static gint handler(GtkWidget *widget, GdkEvent *event);
4708 and it will use the event to find out where to pop up the menu.
4709 <item>In the event handler, if event is a mouse button press, treat
4710 <tt>event</tt> as a button event (which it is) and use it as
4711 shown in the sample code to pass information to gtk_menu_popup().
4712 <item>Bind that event handler to a widget with
4714 gtk_signal_connect_object(GTK_OBJECT(widget), "event",
4715 GTK_SIGNAL_FUNC (handler), GTK_OBJECT(menu));
4717 where <tt>widget</tt> is the widget you are binding to, <tt>handler</tt>
4718 is the handling function, and <tt>menu</tt> is a menu created with
4719 gtk_menu_new(). This can be a menu which is also posted by a menu bar,
4720 as shown in the sample code.
4723 <!-- ----------------------------------------------------------------- -->
4724 <sect1>Manual Menu Example
4726 That should about do it. Let's take a look at an example to help clarify.
4731 #include <gtk/gtk.h>
4733 static gint button_press (GtkWidget *, GdkEvent *);
4734 static void menuitem_response (gchar *);
4736 int main (int argc, char *argv[])
4741 GtkWidget *menu_bar;
4742 GtkWidget *root_menu;
4743 GtkWidget *menu_items;
4749 gtk_init (&argc, &argv);
4751 /* create a new window */
4752 window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
4753 gtk_widget_set_usize( GTK_WIDGET (window), 200, 100);
4754 gtk_window_set_title(GTK_WINDOW (window), "GTK Menu Test");
4755 gtk_signal_connect(GTK_OBJECT (window), "delete_event",
4756 (GtkSignalFunc) gtk_exit, NULL);
4758 /* Init the menu-widget, and remember -- never
4759 * gtk_show_widget() the menu widget!!
4760 * This is the menu that holds the menu items, the one that
4761 * will pop up when you click on the "Root Menu" in the app */
4762 menu = gtk_menu_new();
4764 /* Next we make a little loop that makes three menu-entries for "test-menu".
4765 * Notice the call to gtk_menu_append. Here we are adding a list of
4766 * menu items to our menu. Normally, we'd also catch the "clicked"
4767 * signal on each of the menu items and setup a callback for it,
4768 * but it's omitted here to save space. */
4770 for(i = 0; i < 3; i++)
4772 /* Copy the names to the buf. */
4773 sprintf(buf, "Test-undermenu - %d", i);
4775 /* Create a new menu-item with a name... */
4776 menu_items = gtk_menu_item_new_with_label(buf);
4778 /* ...and add it to the menu. */
4779 gtk_menu_append(GTK_MENU (menu), menu_items);
4781 /* Do something interesting when the menuitem is selected */
4782 gtk_signal_connect_object(GTK_OBJECT(menu_items), "activate",
4783 GTK_SIGNAL_FUNC(menuitem_response), (gpointer) g_strdup(buf));
4785 /* Show the widget */
4786 gtk_widget_show(menu_items);
4789 /* This is the root menu, and will be the label
4790 * displayed on the menu bar. There won't be a signal handler attached,
4791 * as it only pops up the rest of the menu when pressed. */
4792 root_menu = gtk_menu_item_new_with_label("Root Menu");
4794 gtk_widget_show(root_menu);
4796 /* Now we specify that we want our newly created "menu" to be the menu
4797 * for the "root menu" */
4798 gtk_menu_item_set_submenu(GTK_MENU_ITEM (root_menu), menu);
4800 /* A vbox to put a menu and a button in: */
4801 vbox = gtk_vbox_new(FALSE, 0);
4802 gtk_container_add(GTK_CONTAINER(window), vbox);
4803 gtk_widget_show(vbox);
4805 /* Create a menu-bar to hold the menus and add it to our main window */
4806 menu_bar = gtk_menu_bar_new();
4807 gtk_box_pack_start(GTK_BOX(vbox), menu_bar, FALSE, FALSE, 2);
4808 gtk_widget_show(menu_bar);
4810 /* Create a button to which to attach menu as a popup */
4811 button = gtk_button_new_with_label("press me");
4812 gtk_signal_connect_object(GTK_OBJECT(button), "event",
4813 GTK_SIGNAL_FUNC (button_press), GTK_OBJECT(menu));
4814 gtk_box_pack_end(GTK_BOX(vbox), button, TRUE, TRUE, 2);
4815 gtk_widget_show(button);
4817 /* And finally we append the menu-item to the menu-bar -- this is the
4818 * "root" menu-item I have been raving about =) */
4819 gtk_menu_bar_append(GTK_MENU_BAR (menu_bar), root_menu);
4821 /* always display the window as the last step so it all splashes on
4822 * the screen at once. */
4823 gtk_widget_show(window);
4832 /* Respond to a button-press by posting a menu passed in as widget.
4834 * Note that the "widget" argument is the menu being posted, NOT
4835 * the button that was pressed.
4838 static gint button_press (GtkWidget *widget, GdkEvent *event)
4841 if (event->type == GDK_BUTTON_PRESS) {
4842 GdkEventButton *bevent = (GdkEventButton *) event;
4843 gtk_menu_popup (GTK_MENU(widget), NULL, NULL, NULL, NULL,
4844 bevent->button, bevent->time);
4845 /* Tell calling code that we have handled this event; the buck
4850 /* Tell calling code that we have not handled this event; pass it on. */
4855 /* Print a string when a menu item is selected */
4857 static void menuitem_response (gchar *string)
4859 printf("%s\n", string);
4863 You may also set a menu item to be insensitive and, using an accelerator
4864 table, bind keys to menu functions.
4866 <!-- ----------------------------------------------------------------- -->
4867 <sect1>Using GtkMenuFactory
4869 Now that we've shown you the hard way, here's how you do it using the
4870 gtk_menu_factory calls.
4872 <!-- ----------------------------------------------------------------- -->
4873 <sect1>Menu Factory Example
4875 Here is an example using the GTK menu factory. This is the first file,
4876 menufactory.h. We keep a separate menufactory.c and mfmain.c because of the global variables used
4877 in the menufactory.c file.
4882 #ifndef __MENUFACTORY_H__
4883 #define __MENUFACTORY_H__
4887 #endif /* __cplusplus */
4889 void get_main_menu (GtkWidget **menubar, GtkAcceleratorTable **table);
4890 void menus_create(GtkMenuEntry *entries, int nmenu_entries);
4894 #endif /* __cplusplus */
4896 #endif /* __MENUFACTORY_H__ */
4899 And here is the menufactory.c file.
4904 #include <gtk/gtk.h>
4905 #include <strings.h>
4910 static void menus_remove_accel(GtkWidget * widget, gchar * signal_name, gchar * path);
4911 static gint menus_install_accel(GtkWidget * widget, gchar * signal_name, gchar key, gchar modifiers, gchar * path);
4912 void menus_init(void);
4913 void menus_create(GtkMenuEntry * entries, int nmenu_entries);
4916 /* this is the GtkMenuEntry structure used to create new menus. The
4917 * first member is the menu definition string. The second, the
4918 * default accelerator key used to access this menu function with
4919 * the keyboard. The third is the callback function to call when
4920 * this menu item is selected (by the accelerator key, or with the
4921 * mouse.) The last member is the data to pass to your callback function.
4924 static GtkMenuEntry menu_items[] =
4926 {"<Main>/File/New", "<control>N", NULL, NULL},
4927 {"<Main>/File/Open", "<control>O", NULL, NULL},
4928 {"<Main>/File/Save", "<control>S", NULL, NULL},
4929 {"<Main>/File/Save as", NULL, NULL, NULL},
4930 {"<Main>/File/<separator>", NULL, NULL, NULL},
4931 {"<Main>/File/Quit", "<control>Q", file_quit_cmd_callback, "OK, I'll quit"},
4932 {"<Main>/Options/Test", NULL, NULL, NULL}
4935 /* calculate the number of menu_item's */
4936 static int nmenu_items = sizeof(menu_items) / sizeof(menu_items[0]);
4938 static int initialize = TRUE;
4939 static GtkMenuFactory *factory = NULL;
4940 static GtkMenuFactory *subfactory[1];
4941 static GHashTable *entry_ht = NULL;
4943 void get_main_menu(GtkWidget ** menubar, GtkAcceleratorTable ** table)
4949 *menubar = subfactory[0]->widget;
4951 *table = subfactory[0]->table;
4954 void menus_init(void)
4959 factory = gtk_menu_factory_new(GTK_MENU_FACTORY_MENU_BAR);
4960 subfactory[0] = gtk_menu_factory_new(GTK_MENU_FACTORY_MENU_BAR);
4962 gtk_menu_factory_add_subfactory(factory, subfactory[0], "<Main>");
4963 menus_create(menu_items, nmenu_items);
4967 void menus_create(GtkMenuEntry * entries, int nmenu_entries)
4976 for (i = 0; i < nmenu_entries; i++) {
4977 accelerator = g_hash_table_lookup(entry_ht, entries[i].path);
4979 if (accelerator[0] == '\0')
4980 entries[i].accelerator = NULL;
4982 entries[i].accelerator = accelerator;
4985 gtk_menu_factory_add_entries(factory, entries, nmenu_entries);
4987 for (i = 0; i < nmenu_entries; i++)
4988 if (entries[i].widget) {
4989 gtk_signal_connect(GTK_OBJECT(entries[i].widget), "install_accelerator",
4990 (GtkSignalFunc) menus_install_accel,
4992 gtk_signal_connect(GTK_OBJECT(entries[i].widget), "remove_accelerator",
4993 (GtkSignalFunc) menus_remove_accel,
4998 static gint menus_install_accel(GtkWidget * widget, gchar * signal_name, gchar key, gchar modifiers, gchar * path)
5004 if (modifiers & GDK_CONTROL_MASK)
5005 strcat(accel, "<control>");
5006 if (modifiers & GDK_SHIFT_MASK)
5007 strcat(accel, "<shift>");
5008 if (modifiers & GDK_MOD1_MASK)
5009 strcat(accel, "<alt>");
5016 t1 = g_hash_table_lookup(entry_ht, path);
5019 entry_ht = g_hash_table_new(g_str_hash, g_str_equal);
5021 g_hash_table_insert(entry_ht, path, g_strdup(accel));
5026 static void menus_remove_accel(GtkWidget * widget, gchar * signal_name, gchar * path)
5031 t = g_hash_table_lookup(entry_ht, path);
5034 g_hash_table_insert(entry_ht, path, g_strdup(""));
5038 void menus_set_sensitive(char *path, int sensitive)
5040 GtkMenuPath *menu_path;
5045 menu_path = gtk_menu_factory_find(factory, path);
5047 gtk_widget_set_sensitive(menu_path->widget, sensitive);
5049 g_warning("Unable to set sensitivity for menu which doesn't exist: %s", path);
5054 And here's the mfmain.h
5059 #ifndef __MFMAIN_H__
5060 #define __MFMAIN_H__
5065 #endif /* __cplusplus */
5067 void file_quit_cmd_callback(GtkWidget *widget, gpointer data);
5071 #endif /* __cplusplus */
5073 #endif /* __MFMAIN_H__ */
5081 #include <gtk/gtk.h>
5084 #include "menufactory.h"
5087 int main(int argc, char *argv[])
5090 GtkWidget *main_vbox;
5093 GtkAcceleratorTable *accel;
5095 gtk_init(&argc, &argv);
5097 window = gtk_window_new(GTK_WINDOW_TOPLEVEL);
5098 gtk_signal_connect(GTK_OBJECT(window), "destroy",
5099 GTK_SIGNAL_FUNC(file_quit_cmd_callback),
5101 gtk_window_set_title(GTK_WINDOW(window), "Menu Factory");
5102 gtk_widget_set_usize(GTK_WIDGET(window), 300, 200);
5104 main_vbox = gtk_vbox_new(FALSE, 1);
5105 gtk_container_border_width(GTK_CONTAINER(main_vbox), 1);
5106 gtk_container_add(GTK_CONTAINER(window), main_vbox);
5107 gtk_widget_show(main_vbox);
5109 get_main_menu(&menubar, &accel);
5110 gtk_window_add_accelerator_table(GTK_WINDOW(window), accel);
5111 gtk_box_pack_start(GTK_BOX(main_vbox), menubar, FALSE, TRUE, 0);
5112 gtk_widget_show(menubar);
5114 gtk_widget_show(window);
5120 /* This is just to demonstrate how callbacks work when using the
5121 * menufactory. Often, people put all the callbacks from the menus
5122 * in a separate file, and then have them call the appropriate functions
5123 * from there. Keeps it more organized. */
5124 void file_quit_cmd_callback (GtkWidget *widget, gpointer data)
5126 g_print ("%s\n", (char *) data);
5131 And a makefile so it'll be easier to compile it.
5138 C_FLAGS = -Wall $(PROF) -L/usr/local/include -DDEBUG
5139 L_FLAGS = $(PROF) -L/usr/X11R6/lib -L/usr/local/lib
5140 L_POSTFLAGS = -lgtk -lgdk -lglib -lXext -lX11 -lm
5141 PROGNAME = menufactory
5143 O_FILES = menufactory.o mfmain.o
5145 $(PROGNAME): $(O_FILES)
5147 $(CC) $(L_FLAGS) -o $(PROGNAME) $(O_FILES) $(L_POSTFLAGS)
5150 $(CC) -c $(C_FLAGS) $<
5153 rm -f core *.o $(PROGNAME) nohup.out
5158 For now, there's only this example. An explanation and lots 'o' comments
5161 <!-- ***************************************************************** -->
5163 <!-- ***************************************************************** -->
5165 The Text widget allows multiple lines of text to be displayed and edited. It supports both
5166 multi-colored and multi-font text, allowing them to be mixed in any way we wish. It also has
5167 a wide set of key based text editing commands, which are compatible with Emacs.
5169 The text widget supports full cut-and-paste facilities, including the use of double- and
5170 triple-click to select a word and a whole line, respectively.
5172 <!-- ----------------------------------------------------------------- -->
5173 <sect1>Creating and Configuring a Text box
5175 There is only one function for creating a new Text widget.
5177 GtkWidget* gtk_text_new (GtkAdjustment *hadj,
5178 GtkAdjustment *vadj);
5181 The arguments allow us to give the Text widget pointers to Adjustments that can be used
5182 to track the viewing position of the widget. Passing NULL values to either or both of
5183 these arguments will cause the gtk_text_new function to create it's own.
5186 void gtk_text_set_adjustments (GtkText *text,
5187 GtkAdjustment *hadj,
5188 GtkAdjustment *vadj);
5191 The above function allows the horizontal and vertical adjustments of a Text widget to be
5192 changed at any time.
5194 The text widget will not automatically create it's own scrollbars when the amount of text
5195 to be displayed is too long for the display window. We therefore have to create and add
5196 them to the display layout ourselves.
5199 vscrollbar = gtk_vscrollbar_new (GTK_TEXT(text)->vadj);
5200 gtk_box_pack_start(GTK_BOX(hbox), vscrollbar, FALSE, FALSE, 0);
5201 gtk_widget_show (vscrollbar);
5204 The above code snippet creates a new vertical scrollbar, and attaches it to the vertical
5205 adjustment of the text widget, <tt/text/. It then packs it into a box in the normal way.
5207 There are two main ways in which a Text widget can be used: to allow the user to edit a
5208 body of text, or to allow us to display multiple lines of text to the user. In order for
5209 us to switch between these modes of operation, the text widget has the following function:
5212 void gtk_text_set_editable (GtkText *text,
5216 The <tt/editable/ argument is a TRUE or FALSE value that specifies whether the user is
5217 permitted to edit the contents of the Text widget. When the text widget is editable, it
5218 will display a cursor at the current insertion point.
5220 You are not, however, restricted to just using the text widget in these two modes. You can
5221 toggle the editable state of the text widget at any time, and can insert text at any time.
5223 The text widget is capable of wrapping lines of text that are too long to fit onto a single
5224 line of the display window. It's default behaviour is to break words across line breaks. This
5225 can be changed using the next function:
5228 void gtk_text_set_word_wrap (GtkText *text,
5232 Using this function allows us to specify that the text widget should wrap long lines on word
5233 boundaries. The <tt/word_wrap/ argument is a TRUE or FALSE value.
5235 <!-- ----------------------------------------------------------------- -->
5236 <sect1>Text Manipulation
5238 The current insertion point of a Text widget can be set using
5240 void gtk_text_set_point (GtkText *text,
5243 where <tt/index/ is the position to set the insertion point.
5245 Analogous to this is the function for getting the current insertion point:
5247 guint gtk_text_get_point (GtkText *text);
5250 A function that is useful in combination with the above two functions is
5252 guint gtk_text_get_length (GtkText *text);
5254 which returns the current length of the Text widget. The length is the number of characters
5255 that are within the text block of the widget, including characters such as carriage-return,
5256 which marks the end of lines.
5258 In order to insert text at the current insertion point of a Text widget, the function
5259 gtk_text_insert is used, which also allows us to specify background and foreground colors and a
5263 void gtk_text_insert (GtkText *text,
5271 Passing a value of <tt/NULL/ in as the value for the foreground color, background colour or
5272 font will result in the values set within the widget style to be used. Using a value of <tt/-1/ for
5273 the length parameter will result in the whole of the text string given being inserted.
5275 The text widget is one of the few within GTK that redraws itself dynamically, outside of the gtk_main
5276 function. This means that all changes to the contents of the text widget take effect immediately. This
5277 may be undesirable when performing multiple changes to the text widget. In order to allow us to perform
5278 multiple updates to the text widget without it continuously redrawing, we can freeze the widget, which
5279 temporarily stops it from automatically redrawing itself every time it is changed. We can then thaw the
5280 widget after our updates are complete.
5282 The following two functions perform this freeze and thaw action:
5285 void gtk_text_freeze (GtkText *text);
5286 void gtk_text_thaw (GtkText *text);
5289 Text is deleted from the text widget relative to the current insertion point by the following
5293 gint gtk_text_backward_delete (GtkText *text,
5295 gint gtk_text_forward_delete (GtkText *text,
5299 If you want to retrieve the contents of the text widget, then the macro
5300 <tt/GTK_TEXT_INDEX(t, index)/ allows you to retrieve the character at position
5301 <tt/index/ within the text widget <tt/t/.
5303 To retrieve larger blocks of text, we can use the function
5306 gchar *gtk_editable_get_chars (GtkEditable *editable,
5311 This is a function of the parent class of the text widget. A value of -1 as
5312 <tt/end_pos/ signifies the end of the text. The index of the text starts at 0.
5314 The function allocates a new chunk of memory for the text block, so don't forget
5315 to free it with a call to g_free when you have finished with it.
5317 <!-- ----------------------------------------------------------------- -->
5318 <sect1>Keyboard Shortcuts
5320 The text widget has a number of pre-installed keyboard shotcuts for common
5321 editing, motion and selection functions. These are accessed using Control and Alt
5324 In addition to these, holding down the Control key whilst using cursor key movement
5325 will move the cursor by words rather than characters. Holding down Shift whilst using
5326 cursor movement will extend the selection.
5328 <sect2>Motion Shotcuts
5331 <item> Ctrl-A Beginning of line
5332 <item> Ctrl-E End of line
5333 <item> Ctrl-N Next Line
5334 <item> Ctrl-P Previous Line
5335 <item> Ctrl-B Backward one character
5336 <item> Ctrl-F Forward one character
5337 <item> Alt-B Backward one word
5338 <item> Alt-F Forward one word
5341 <sect2>Editing Shortcuts
5344 <item> Ctrl-H Delete Backward Character (Backspace)
5345 <item> Ctrl-D Delete Forward Character (Delete)
5346 <item> Ctrl-W Delete Backward Word
5347 <item> Alt-D Delete Forward Word
5348 <item> Ctrl-K Delete to end of line
5349 <item> Ctrl-U Delete line
5352 <sect2>Selection Shortcuts
5355 <item> Ctrl-X Cut to clipboard
5356 <item> Ctrl-C Copy to clipboard
5357 <item> Ctrl-V Paste from clipboard
5360 <!-- ***************************************************************** -->
5361 <sect> Undocumented Widgets
5362 <!-- ***************************************************************** -->
5365 These all require authors! :) Please consider contributing to our tutorial.
5367 If you must use one of these widgets that are undocumented, I strongly
5368 suggest you take a look at their respective header files in the GTK distro.
5369 GTK's function names are very descriptive. Once you have an understanding
5370 of how things work, it's not easy to figure out how to use a widget simply
5371 by looking at it's function declarations. This, along with a few examples
5372 from others' code, and it should be no problem.
5374 When you do come to understand all the functions of a new undocumented
5375 widget, please consider writing a tutorial on it so others may benifit from
5378 <!-- ----------------------------------------------------------------- -->
5379 <sect1> Range Controls
5381 <!-- ----------------------------------------------------------------- -->
5385 (This may need to be rewritten to follow the style of the rest of the tutorial)
5389 Previews serve a number of purposes in GIMP/GTK. The most important one is
5390 this. High quality images may take up to tens of megabytes of memory - easy!
5391 Any operation on an image that big is bound to take a long time. If it takes
5392 you 5-10 trial-and-errors (i.e. 10-20 steps, since you have to revert after
5393 you make an error) to choose the desired modification, it make take you
5394 literally hours to make the right one - if you don't run out of memory
5395 first. People who have spent hours in color darkrooms know the feeling.
5396 Previews to the rescue!
5398 But the annoyance of the delay is not the only issue. Oftentimes it is
5399 helpful to compare the Before and After versions side-by-side or at least
5400 back-to-back. If you're working with big images and 10 second delays,
5401 obtaining the Before and After impressions is, to say the least, difficult.
5402 For 30M images (4"x6", 600dpi, 24 bit) the side-by-side comparison is right
5403 out for most people, while back-to-back is more like back-to-1001, 1002,
5404 ..., 1010-back! Previews to the rescue!
5406 But there's more. Previews allow for side-by-side pre-previews. In other
5407 words, you write a plug-in (e.g. the filterpack simulation) which would have
5408 a number of here's-what-it-would-look-like-if-you-were-to-do-this previews.
5409 An approach like this acts as a sort of a preview palette and is very
5410 effective fow subtle changes. Let's go previews!
5412 There's more. For certain plug-ins real-time image-specific human
5413 intervention maybe necessary. In the SuperNova plug-in, for example, the
5414 user is asked to enter the coordinates of the center of the future
5415 supernova. The easiest way to do this, really, is to present the user with a
5416 preview and ask him to intereactively select the spot. Let's go previews!
5418 Finally, a couple of misc uses. One can use previews even when not working
5419 with big images. For example, they are useful when rendering compicated
5420 patterns. (Just check out the venerable Diffraction plug-in + many other
5421 ones!) As another example, take a look at the colormap rotation plug-in
5422 (work in progress). You can also use previews for little logo's inside you
5423 plug-ins and even for an image of yourself, The Author. Let's go previews!
5425 When Not to Use Previews
5427 Don't use previews for graphs, drawing etc. GDK is much faster for that. Use
5428 previews only for rendered images!
5432 You can stick a preview into just about anything. In a vbox, an hbox, a
5433 table, a button, etc. But they look their best in tight frames around them.
5434 Previews by themselves do not have borders and look flat without them. (Of
5435 course, if the flat look is what you want...) Tight frames provide the
5440 Previews in many ways are like any other widgets in GTK (whatever that
5441 means) except they possess an addtional feature: they need to be filled with
5442 some sort of an image! First, we will deal exclusively with the GTK aspect
5443 of previews and then we'll discuss how to fill them.
5449 /* Create a preview widget,
5450 set its size, an show it */
5452 preview=gtk_preview_new(GTK_PREVIEW_COLOR)
5454 GTK_PREVIEW_GRAYSCALE);*/
5455 gtk_preview_size (GTK_PREVIEW (preview), WIDTH, HEIGHT);
5456 gtk_widget_show(preview);
5457 my_preview_rendering_function(preview);
5459 Oh yeah, like I said, previews look good inside frames, so how about:
5461 GtkWidget *create_a_preview(int Width,
5468 frame = gtk_frame_new(NULL);
5469 gtk_frame_set_shadow_type (GTK_FRAME (frame), GTK_SHADOW_IN);
5470 gtk_container_border_width (GTK_CONTAINER(frame),0);
5471 gtk_widget_show(frame);
5473 preview=gtk_preview_new (Colorfulness?GTK_PREVIEW_COLOR
5474 :GTK_PREVIEW_GRAYSCALE);
5475 gtk_preview_size (GTK_PREVIEW (preview), Width, Height);
5476 gtk_container_add(GTK_CONTAINER(frame),preview);
5477 gtk_widget_show(preview);
5479 my_preview_rendering_function(preview);
5483 That's my basic preview. This routine returns the "parent" frame so you can
5484 place it somewhere else in your interface. Of course, you can pass the
5485 parent frame to this routine as a parameter. In many situations, however,
5486 the contents of the preview are changed continually by your application. In
5487 this case you may want to pass a pointer to the preview to a
5488 "create_a_preview()" and thus have control of it later.
5490 One more important note that may one day save you a lot of time. Sometimes
5491 it is desirable to label you preview. For example, you may label the preview
5492 containing the original image as "Original" and the one containing the
5493 modified image as "Less Original". It might occure to you to pack the
5494 preview along with the appropriate label into a vbox. The unexpected caveat
5495 is that if the label is wider than the preview (which may happen for a
5496 variety of reasons unforseeable to you, from the dynamic decision on the
5497 size of the preview to the size of the font) the frame expands and no longer
5498 fits tightly over the preview. The same problem can probably arise in other
5503 The solution is to place the preview and the label into a 2x1 table and by
5504 attaching them with the following paramters (this is one possible variations
5505 of course. The key is no GTK_FILL in the second attachment):
5507 gtk_table_attach(GTK_TABLE(table),label,0,1,0,1,
5509 GTK_EXPAND|GTK_FILL,
5511 gtk_table_attach(GTK_TABLE(table),frame,0,1,1,2,
5517 And here's the result:
5523 Making a preview clickable is achieved most easily by placing it in a
5524 button. It also adds a nice border around the preview and you may not even
5525 need to place it in a frame. See the Filter Pack Simulation plug-in for an
5528 This is pretty much it as far as GTK is concerned.
5530 Filling In a Preview
5532 In order to familiarize ourselves with the basics of filling in previews,
5533 let's create the following pattern (contrived by trial and error):
5538 my_preview_rendering_function(GtkWidget *preview)
5541 #define HALF (SIZE/2)
5543 guchar *row=(guchar *) malloc(3*SIZE); /* 3 bits per dot */
5544 gint i, j; /* Coordinates */
5545 double r, alpha, x, y;
5547 if (preview==NULL) return; /* I usually add this when I want */
5548 /* to avoid silly crashes. You */
5549 /* should probably make sure that */
5550 /* everything has been nicely */
5552 for (j=0; j < ABS(cos(2*alpha)) ) { /* Are we inside the shape? */
5553 /* glib.h contains ABS(x). */
5554 row[i*3+0] = sqrt(1-r)*255; /* Define Red */
5555 row[i*3+1] = 128; /* Define Green */
5556 row[i*3+2] = 224; /* Define Blue */
5557 } /* "+0" is for alignment! */
5560 row[i*3+1] = ABS(sin((float)i/SIZE*2*PI))*255;
5561 row[i*3+2] = ABS(sin((float)j/SIZE*2*PI))*255;
5564 gtk_preview_draw_row( GTK_PREVIEW(preview),row,0,j,SIZE);
5565 /* Insert "row" into "preview" starting at the point with */
5566 /* coordinates (0,j) first column, j_th row extending SIZE */
5567 /* pixels to the right */
5570 free(row); /* save some space */
5571 gtk_widget_draw(preview,NULL); /* what does this do? */
5572 gdk_flush(); /* or this? */
5575 Non-GIMP users can have probably seen enough to do a lot of things already.
5576 For the GIMP users I have a few pointers to add.
5580 It is probably wize to keep a reduced version of the image around with just
5581 enough pixels to fill the preview. This is done by selecting every n'th
5582 pixel where n is the ratio of the size of the image to the size of the
5583 preview. All further operations (including filling in the previews) are then
5584 performed on the reduced number of pixels only. The following is my
5585 implementation of reducing the image. (Keep in mind that I've had only basic
5588 (UNTESTED CODE ALERT!!!)
5600 SELCTION_IN_CONTEXT,
5604 ReducedImage *Reduce_The_Image(GDrawable *drawable,
5609 /* This function reduced the image down to the the selected preview size */
5610 /* The preview size is determine by LongerSize, i.e. the greater of the */
5611 /* two dimentions. Works for RGB images only! */
5612 gint RH, RW; /* Reduced height and reduced width */
5613 gint width, height; /* Width and Height of the area being reduced */
5614 gint bytes=drawable->bpp;
5615 ReducedImage *temp=(ReducedImage *)malloc(sizeof(ReducedImage));
5617 guchar *tempRGB, *src_row, *tempmask, *src_mask_row,R,G,B;
5618 gint i, j, whichcol, whichrow, x1, x2, y1, y2;
5619 GPixelRgn srcPR, srcMask;
5620 gint NoSelectionMade=TRUE; /* Assume that we're dealing with the entire */
5623 gimp_drawable_mask_bounds (drawable->id, &x1, &y1, &x2, &y2);
5626 /* If there's a SELECTION, we got its bounds!)
5628 if (width != drawable->width && height != drawable->height)
5629 NoSelectionMade=FALSE;
5630 /* Become aware of whether the user has made an active selection */
5631 /* This will become important later, when creating a reduced mask. */
5633 /* If we want to preview the entire image, overrule the above! */
5634 /* Of course, if no selection has been made, this does nothing! */
5635 if (Selection==ENTIRE_IMAGE) {
5639 y2=drawable->height;
5642 /* If we want to preview a selection with some surronding area we */
5643 /* have to expand it a little bit. Consider it a bit of a riddle. */
5644 if (Selection==SELECTION_IN_CONTEXT) {
5645 x1=MAX(0, x1-width/2.0);
5646 x2=MIN(drawable->width, x2+width/2.0);
5647 y1=MAX(0, y1-height/2.0);
5648 y2=MIN(drawable->height, y2+height/2.0);
5651 /* How we can determine the width and the height of the area being */
5656 /* The lines below determine which dimension is to be the longer */
5657 /* side. The idea borrowed from the supernova plug-in. I suspect I */
5658 /* could've thought of it myself, but the truth must be told. */
5659 /* Plagiarism stinks! */
5662 RH=(float) height * (float) LongerSize/ (float) width;
5666 RW=(float)width * (float) LongerSize/ (float) height;
5669 /* The intire image is stretched into a string! */
5670 tempRGB = (guchar *) malloc(RW*RH*bytes);
5671 tempmask = (guchar *) malloc(RW*RH);
5673 gimp_pixel_rgn_init (&srcPR, drawable, x1, y1, width, height, FALSE, FALSE);
5674 gimp_pixel_rgn_init (&srcMask, mask, x1, y1, width, height, FALSE, FALSE);
5676 /* Grab enough to save a row of image and a row of mask. */
5677 src_row = (guchar *) malloc (width*bytes);
5678 src_mask_row = (guchar *) malloc (width);
5680 for (i=0; i < RH; i++) {
5681 whichrow=(float)i*(float)height/(float)RH;
5682 gimp_pixel_rgn_get_row (&srcPR, src_row, x1, y1+whichrow, width);
5683 gimp_pixel_rgn_get_row (&srcMask, src_mask_row, x1, y1+whichrow, width);
5685 for (j=0; j < RW; j++) {
5686 whichcol=(float)j*(float)width/(float)RW;
5688 /* No selection made = each point is completely selected! */
5689 if (NoSelectionMade)
5690 tempmask[i*RW+j]=255;
5692 tempmask[i*RW+j]=src_mask_row[whichcol];
5694 /* Add the row to the one long string which now contains the image! */
5695 tempRGB[i*RW*bytes+j*bytes+0]=src_row[whichcol*bytes+0];
5696 tempRGB[i*RW*bytes+j*bytes+1]=src_row[whichcol*bytes+1];
5697 tempRGB[i*RW*bytes+j*bytes+2]=src_row[whichcol*bytes+2];
5699 /* Hold on to the alpha as well */
5701 tempRGB[i*RW*bytes+j*bytes+3]=src_row[whichcol*bytes+3];
5708 temp->mask=tempmask;
5712 The following is a preview function which used the same ReducedImage type!
5713 Note that it uses fakes transparancy (if one is present by means of
5714 fake_transparancy which is defined as follows:
5716 gint fake_transparency(gint i, gint j)
5718 if ( ((i%20)- 10) * ((j%20)- 10)>0 )
5724 Now here's the preview function:
5727 my_preview_render_function(GtkWidget *preview,
5731 gint Inten, bytes=drawable->bpp;
5734 gint RW=reduced->width;
5735 gint RH=reduced->height;
5736 guchar *row=malloc(bytes*RW);;
5739 for (i=0; i < RH; i++) {
5740 for (j=0; j < RW; j++) {
5742 row[j*3+0] = reduced->rgb[i*RW*bytes + j*bytes + 0];
5743 row[j*3+1] = reduced->rgb[i*RW*bytes + j*bytes + 1];
5744 row[j*3+2] = reduced->rgb[i*RW*bytes + j*bytes + 2];
5747 for (k=0; k<3; k++) {
5748 float transp=reduced->rgb[i*RW*bytes+j*bytes+3]/255.0;
5749 row[3*j+k]=transp*a[3*j+k]+(1-transp)*fake_transparency(i,j);
5752 gtk_preview_draw_row( GTK_PREVIEW(preview),row,0,i,RW);
5756 gtk_widget_draw(preview,NULL);
5762 guint gtk_preview_get_type (void);
5764 void gtk_preview_uninit (void);
5766 GtkWidget* gtk_preview_new (GtkPreviewType type);
5767 /* Described above */
5768 void gtk_preview_size (GtkPreview *preview,
5771 /* Allows you to resize an existing preview. */
5772 /* Apparantly there's a bug in GTK which makes */
5773 /* this process messy. A way to clean up a mess */
5774 /* is to manually resize the window containing */
5775 /* the preview after resizing the preview. */
5777 void gtk_preview_put (GtkPreview *preview,
5788 void gtk_preview_put_row (GtkPreview *preview,
5796 void gtk_preview_draw_row (GtkPreview *preview,
5801 /* Described in the text */
5803 void gtk_preview_set_expand (GtkPreview *preview,
5807 /* No clue for any of the below but */
5808 /* should be standard for most widgets */
5809 void gtk_preview_set_gamma (double gamma);
5810 void gtk_preview_set_color_cube (guint nred_shades,
5811 guint ngreen_shades,
5813 guint ngray_shades);
5814 void gtk_preview_set_install_cmap (gint install_cmap);
5815 void gtk_preview_set_reserved (gint nreserved);
5816 GdkVisual* gtk_preview_get_visual (void);
5817 GdkColormap* gtk_preview_get_cmap (void);
5818 GtkPreviewInfo* gtk_preview_get_info (void);
5824 <!-- ----------------------------------------------------------------- -->
5828 <!-- ***************************************************************** -->
5829 <sect>The EventBox Widget<label id="sec_The_EventBox_Widget">
5830 <!-- ***************************************************************** -->
5833 Some gtk widgets don't have associated X windows, so they just draw on
5834 thier parents. Because of this, they cannot recieve events
5835 and if they are incorrectly sized, they don't clip so you can get
5836 messy overwritting etc. If you require more from these widgets, the
5837 EventBox is for you.
5839 At first glance, the EventBox widget might appear to be totally
5840 useless. It draws nothing on the screen and responds to no
5841 events. However, it does serve a function - it provides an X window for
5842 its child widget. This is important as many GTK widgets do not
5843 have an associated X window. Not having an X window saves memory and
5844 improves performance, but also has some drawbacks. A widget without an
5845 X window cannot receive events, and does not perform any clipping on
5846 it's contents. Although the name ``EventBox'' emphasizes the
5847 event-handling function, the widget also can be used for clipping.
5848 (And more ... see the example below.)
5851 To create a new EventBox widget, use:
5854 GtkWidget* gtk_event_box_new (void);
5858 A child widget can then be added to this EventBox:
5861 gtk_container_add (GTK_CONTAINER(event_box), widget);
5865 The following example demonstrates both uses of an EventBox - a label
5866 is created that clipped to a small box, and set up so that a
5867 mouse-click on the label causes the program to exit.
5872 #include <gtk/gtk.h>
5875 main (int argc, char *argv[])
5878 GtkWidget *event_box;
5881 gtk_init (&argc, &argv);
5883 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
5885 gtk_window_set_title (GTK_WINDOW (window), "Event Box");
5887 gtk_signal_connect (GTK_OBJECT (window), "destroy",
5888 GTK_SIGNAL_FUNC (gtk_exit), NULL);
5890 gtk_container_border_width (GTK_CONTAINER (window), 10);
5892 /* Create an EventBox and add it to our toplevel window */
5894 event_box = gtk_event_box_new ();
5895 gtk_container_add (GTK_CONTAINER(window), event_box);
5896 gtk_widget_show (event_box);
5898 /* Create a long label */
5900 label = gtk_label_new ("Click here to quit, quit, quit, quit, quit");
5901 gtk_container_add (GTK_CONTAINER (event_box), label);
5902 gtk_widget_show (label);
5904 /* Clip it short. */
5905 gtk_widget_set_usize (label, 110, 20);
5907 /* And bind an action to it */
5908 gtk_widget_set_events (event_box, GDK_BUTTON_PRESS_MASK);
5909 gtk_signal_connect (GTK_OBJECT(event_box), "button_press_event",
5910 GTK_SIGNAL_FUNC (gtk_exit), NULL);
5912 /* Yet one more thing you need an X window for ... */
5914 gtk_widget_realize (event_box);
5915 gdk_window_set_cursor (event_box->window, gdk_cursor_new (GDK_HAND1));
5917 gtk_widget_show (window);
5925 <!-- ***************************************************************** -->
5926 <sect>Setting Widget Attributes<label id="sec_setting_widget_attributes">
5927 <!-- ***************************************************************** -->
5930 This describes the functions used to operate on widgets. These can be used
5931 to set style, padding, size etc.
5933 (Maybe I should make a whole section on accelerators.)
5936 void gtk_widget_install_accelerator (GtkWidget *widget,
5937 GtkAcceleratorTable *table,
5942 void gtk_widget_remove_accelerator (GtkWidget *widget,
5943 GtkAcceleratorTable *table,
5944 gchar *signal_name);
5946 void gtk_widget_activate (GtkWidget *widget);
5948 void gtk_widget_set_name (GtkWidget *widget,
5950 gchar* gtk_widget_get_name (GtkWidget *widget);
5952 void gtk_widget_set_sensitive (GtkWidget *widget,
5955 void gtk_widget_set_style (GtkWidget *widget,
5958 GtkStyle* gtk_widget_get_style (GtkWidget *widget);
5960 GtkStyle* gtk_widget_get_default_style (void);
5962 void gtk_widget_set_uposition (GtkWidget *widget,
5965 void gtk_widget_set_usize (GtkWidget *widget,
5969 void gtk_widget_grab_focus (GtkWidget *widget);
5971 void gtk_widget_show (GtkWidget *widget);
5973 void gtk_widget_hide (GtkWidget *widget);
5976 <!-- ***************************************************************** -->
5977 <sect>Timeouts, IO and Idle Functions<label id="sec_timeouts">
5978 <!-- ***************************************************************** -->
5980 <!-- ----------------------------------------------------------------- -->
5983 You may be wondering how you make GTK do useful work when in gtk_main.
5984 Well, you have several options. Using the following functions you can
5985 create a timeout function that will be called every "interval" milliseconds.
5988 gint gtk_timeout_add (guint32 interval,
5989 GtkFunction function,
5993 The first argument is the number of milliseconds
5994 between calls to your function. The second argument is the function
5995 you wish to have called, and
5996 the third, the data passed to this callback function. The return value is
5997 an integer "tag" which may be used to stop the timeout by calling:
6000 void gtk_timeout_remove (gint tag);
6003 You may also stop the timeout function by returning zero or FALSE from
6004 your callback function. Obviously this means if you want your function to
6005 continue to be called, it should return a non-zero value, ie TRUE.
6007 The declaration of your callback should look something like this:
6010 gint timeout_callback (gpointer data);
6013 <!-- ----------------------------------------------------------------- -->
6014 <sect1>Monitoring IO
6016 Another nifty feature of GTK, is the ability to have it check for data on a
6017 file descriptor for you (as returned by open(2) or socket(2)). This is
6018 especially useful for networking applications. The function:
6021 gint gdk_input_add (gint source,
6022 GdkInputCondition condition,
6023 GdkInputFunction function,
6027 Where the first argument is the file descriptor you wish to have watched,
6028 and the second specifies what you want GDK to look for. This may be one of:
6030 GDK_INPUT_READ - Call your function when there is data ready for reading on
6031 your file descriptor.
6033 GDK_INPUT_WRITE - Call your function when the file descriptor is ready for
6036 As I'm sure you've figured out already, the third argument is the function
6037 you wish to have called when the above conditions are satisfied, and the
6038 fourth is the data to pass to this function.
6040 The return value is a tag that may be used to stop GDK from monitoring this
6041 file descriptor using the following function.
6044 void gdk_input_remove (gint tag);
6047 The callback function should be declared:
6050 void input_callback (gpointer data, gint source,
6051 GdkInputCondition condition);
6055 <!-- ----------------------------------------------------------------- -->
6056 <sect1>Idle Functions
6058 What if you have a function you want called when nothing else is
6062 gint gtk_idle_add (GtkFunction function,
6066 This causes GTK to call the specified function whenever nothing else is
6070 void gtk_idle_remove (gint tag);
6073 I won't explain the meaning of the arguments as they follow very much like
6074 the ones above. The function pointed to by the first argument to
6075 gtk_idle_add will be called whenever the opportunity arises. As with the
6076 others, returning FALSE will stop the idle function from being called.
6078 <!-- ***************************************************************** -->
6079 <sect>Managing Selections
6080 <!-- ***************************************************************** -->
6082 <!-- ----------------------------------------------------------------- -->
6087 One type of interprocess communication supported by GTK is
6088 <em>selections</em>. A selection identifies a chunk of data, for
6089 instance, a portion of text, selected by the user in some fashion, for
6090 instance, by dragging with the mouse. Only one application on a
6091 display, (he <em>owner</em>_ can own a particular selection at one
6092 time, so when a selection is claimed by one application, the previous
6093 owner must indicate to the user that selection has been
6094 relinquished. Other applications can request the contents of a
6095 selection in different forms, called <em>targets</em>. There can be
6096 any number of selections, but most X applications only handle one, the
6097 <em>primary selection</em>.
6100 In most cases, it isn't necessary for a GTK application to deal with
6101 selections itself. The standard widgets, such as the Entry widget,
6102 already have the capability to claim the selection when appropriate
6103 (e.g., when the user drags over text), and to retrieve the contents of
6104 the selection owned by another widget, or another application (e.g.,
6105 when the user clicks the second mouse button). However, there may be
6106 cases in which you want to give other widgets the ability to supply
6107 the selection, or you wish to retrieve targets not supported by
6111 A fundamental concept needed to understand selection handling is that
6112 of the <em>atom</em>. An atom is an integer that uniquely identifies a
6113 string (on a certain display). Certain atoms are predefined by the X
6114 server, and in some cases there are constants in in <tt>gtk.h</tt>
6115 corresponding to these atoms. For instance the constant
6116 <tt>GDK_PRIMARY_SELECTION</tt> corresponds to the string "PRIMARY".
6117 In other cases, you should use the functions
6118 <tt>gdk_atom_intern()</tt>, to get the atom corresponding to a string,
6119 and <tt>gdk_atom_name()</tt>, to get the name of an atom. Both
6120 selections and targets are identifed by atoms.
6122 <!-- ----------------------------------------------------------------- -->
6123 <sect1> Retrieving the selection
6127 Retrieving the selection is an asynchronous process. To start the
6131 gint gtk_selection_convert (GtkWidget *widget,
6137 This <em>converts</em> the selection into the form specified by
6138 <tt/target/. If it all possible, the time field should be the time
6139 from the event that triggered the selection. This helps make sure that
6140 events occur in the order that the user requested them.
6141 However, if it is not available (for instance, if the conversion was
6142 triggered by a "clicked" signal), then you can use the constant
6143 <tt>GDK_CURRENT_TIME</tt>.
6146 When the selection owner responds to the request, a
6147 "selection_received" signal is sent to your application. The handler
6148 for this signal receives a pointer to a <tt>GtkSelectionData</tt>
6149 structure, which is defined as:
6152 struct _GtkSelectionData
6163 <tt>selection</tt> and <tt>target</tt> are the values you gave in your
6164 <tt>gtk_selection_convert()</tt> call. <tt>type</tt> is an atom that
6165 identifies the type of data returned by the selection owner. Some
6166 possible values are "STRING", a string of latin-1 characters, "ATOM",
6167 a series of atoms, "INTEGER", an integer, etc. Most targets can only
6168 return one type. <tt/format/ gives the length of the units (for
6169 instance characters) in bits. Usually, you don't care about this when
6170 receiving data. <tt>data</tt> is a pointer to the returned data, and
6171 <tt>length</tt> gives the length of the returned data, in bytes. If
6172 <tt>length</tt> is negative, then an error occurred and the selection
6173 could not be retrieved. This might happen if no application owned the
6174 selection, or if you requested a target that the application didn't
6175 support. The buffer is actually guaranteed to be one byte longer than
6176 <tt>length</tt>; the extra byte will always be zero, so it isn't
6177 necessary to make a copy of strings just to null terminate them.
6180 In the following example, we retrieve the special target "TARGETS",
6181 which is a list of all targets into which the selection can be
6187 #include <gtk/gtk.h>
6189 void selection_received (GtkWidget *widget,
6190 GtkSelectionData *selection_data,
6193 /* Signal handler invoked when user clicks on the "Get Targets" button */
6195 get_targets (GtkWidget *widget, gpointer data)
6197 static GdkAtom targets_atom = GDK_NONE;
6199 /* Get the atom corresonding to the string "TARGETS" */
6200 if (targets_atom == GDK_NONE)
6201 targets_atom = gdk_atom_intern ("TARGETS", FALSE);
6203 /* And request the "TARGETS" target for the primary selection */
6204 gtk_selection_convert (widget, GDK_SELECTION_PRIMARY, targets_atom,
6208 /* Signal handler called when the selections owner returns the data */
6210 selection_received (GtkWidget *widget, GtkSelectionData *selection_data,
6217 /* **** IMPORTANT **** Check to see if retrieval succeeded */
6218 if (selection_data->length < 0)
6220 g_print ("Selection retrieval failed\n");
6223 /* Make sure we got the data in the expected form */
6224 if (selection_data->type != GDK_SELECTION_TYPE_ATOM)
6226 g_print ("Selection \"TARGETS\" was not returned as atoms!\n");
6230 /* Print out the atoms we received */
6231 atoms = (GdkAtom *)selection_data->data;
6234 for (i=0; i<selection_data->length/sizeof(GdkAtom); i++)
6237 name = gdk_atom_name (atoms[i]);
6239 g_print ("%s\n",name);
6241 g_print ("(bad atom)\n");
6248 main (int argc, char *argv[])
6253 gtk_init (&argc, &argv);
6255 /* Create the toplevel window */
6257 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
6258 gtk_window_set_title (GTK_WINDOW (window), "Event Box");
6259 gtk_container_border_width (GTK_CONTAINER (window), 10);
6261 gtk_signal_connect (GTK_OBJECT (window), "destroy",
6262 GTK_SIGNAL_FUNC (gtk_exit), NULL);
6264 /* Create a button the user can click to get targets */
6266 button = gtk_button_new_with_label ("Get Targets");
6267 gtk_container_add (GTK_CONTAINER (window), button);
6269 gtk_signal_connect (GTK_OBJECT(button), "clicked",
6270 GTK_SIGNAL_FUNC (get_targets), NULL);
6271 gtk_signal_connect (GTK_OBJECT(button), "selection_received",
6272 GTK_SIGNAL_FUNC (selection_received), NULL);
6274 gtk_widget_show (button);
6275 gtk_widget_show (window);
6283 <!-- ----------------------------------------------------------------- -->
6284 <sect1> Supplying the selection
6288 Supplying the selection is a bit more complicated. You must register
6289 handlers that will be called when your selection is requested. For
6290 each selection/target pair you will handle, you make a call to:
6293 void gtk_selection_add_handler (GtkWidget *widget,
6296 GtkSelectionFunction function,
6297 GtkRemoveFunction remove_func,
6301 <tt/widget/, <tt/selection/, and <tt/target/ identify the requests
6302 this handler will manage. <tt/remove_func/ if not
6303 NULL, will be called when the signal handler is removed. This is
6304 useful, for instance, for interpreted languages which need to
6305 keep track of a reference count for <tt/data/.
6308 The callback function has the signature:
6311 typedef void (*GtkSelectionFunction) (GtkWidget *widget,
6312 GtkSelectionData *selection_data,
6317 The GtkSelectionData is the same as above, but this time, we're
6318 responsible for filling in the fields <tt/type/, <tt/format/,
6319 <tt/data/, and <tt/length/. (The <tt/format/ field is actually
6320 important here - the X server uses it to figure out whether the data
6321 needs to be byte-swapped or not. Usually it will be 8 - <em/i.e./ a
6322 character - or 32 - <em/i.e./ a. integer.) This is done by calling the
6326 void gtk_selection_data_set (GtkSelectionData *selection_data,
6333 This function takes care of properly making a copy of the data so that
6334 you don't have to worry about keeping it around. (You should not fill
6335 in the fields of the GtkSelectionData structure by hand.)
6338 When prompted by the user, you claim ownership of the selection by
6342 gint gtk_selection_owner_set (GtkWidget *widget,
6347 If another application claims ownership of the selection, you will
6348 receive a "selection_clear_event".
6350 As an example of supplying the selection, the following program adds
6351 selection functionality to a toggle button. When the toggle button is
6352 depressed, the program claims the primary selection. The only target
6353 supported (aside from certain targets like "TARGETS" supplied by GTK
6354 itself), is the "STRING" target. When this target is requested, a
6355 string representation of the time is returned.
6358 /* setselection.c */
6360 #include <gtk/gtk.h>
6363 /* Callback when the user toggles the selection */
6365 selection_toggled (GtkWidget *widget, gint *have_selection)
6367 if (GTK_TOGGLE_BUTTON(widget)->active)
6369 *have_selection = gtk_selection_owner_set (widget,
6370 GDK_SELECTION_PRIMARY,
6372 /* if claiming the selection failed, we return the button to
6374 if (!*have_selection)
6375 gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON(widget), FALSE);
6379 if (*have_selection)
6381 /* Before clearing the selection by setting the owner to NULL,
6382 we check if we are the actual owner */
6383 if (gdk_selection_owner_get (GDK_SELECTION_PRIMARY) == widget->window)
6384 gtk_selection_owner_set (NULL, GDK_SELECTION_PRIMARY,
6386 *have_selection = FALSE;
6391 /* Called when another application claims the selection */
6393 selection_clear (GtkWidget *widget, GdkEventSelection *event,
6394 gint *have_selection)
6396 *have_selection = FALSE;
6397 gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON(widget), FALSE);
6402 /* Supplies the current time as the selection. */
6404 selection_handle (GtkWidget *widget,
6405 GtkSelectionData *selection_data,
6409 time_t current_time;
6411 current_time = time (NULL);
6412 timestr = asctime (localtime(&current_time));
6413 /* When we return a single string, it should not be null terminated.
6414 That will be done for us */
6416 gtk_selection_data_set (selection_data, GDK_SELECTION_TYPE_STRING,
6417 8, timestr, strlen(timestr));
6421 main (int argc, char *argv[])
6425 GtkWidget *selection_button;
6427 static int have_selection = FALSE;
6429 gtk_init (&argc, &argv);
6431 /* Create the toplevel window */
6433 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
6434 gtk_window_set_title (GTK_WINDOW (window), "Event Box");
6435 gtk_container_border_width (GTK_CONTAINER (window), 10);
6437 gtk_signal_connect (GTK_OBJECT (window), "destroy",
6438 GTK_SIGNAL_FUNC (gtk_exit), NULL);
6440 /* Create a toggle button to act as the selection */
6442 selection_button = gtk_toggle_button_new_with_label ("Claim Selection");
6443 gtk_container_add (GTK_CONTAINER (window), selection_button);
6444 gtk_widget_show (selection_button);
6446 gtk_signal_connect (GTK_OBJECT(selection_button), "toggled",
6447 GTK_SIGNAL_FUNC (selection_toggled), &have_selection);
6448 gtk_signal_connect (GTK_OBJECT(selection_button), "selection_clear_event",
6449 GTK_SIGNAL_FUNC (selection_clear), &have_selection);
6451 gtk_selection_add_handler (selection_button, GDK_SELECTION_PRIMARY,
6452 GDK_SELECTION_TYPE_STRING,
6453 selection_handle, NULL);
6455 gtk_widget_show (selection_button);
6456 gtk_widget_show (window);
6465 <!-- ***************************************************************** -->
6466 <sect>glib<label id="sec_glib">
6467 <!-- ***************************************************************** -->
6470 glib provides many useful functions and definitions available for use
6472 and GTK applications. I will list them all here with a brief explanation.
6473 Many are duplicates of standard libc functions so I won't go into
6474 detail on those. This is mostly to be used as a reference, so you know what is
6477 <!-- ----------------------------------------------------------------- -->
6480 Definitions for the extremes of many of the standard types are:
6495 Also, the following typedefs. The ones left unspecified are dynamically set
6496 depending on the architecture. Remember to avoid counting on the size of a
6497 pointer if you want to be portable! Eg, a pointer on an Alpha is 8 bytes, but 4
6507 unsigned char guchar;
6508 unsigned short gushort;
6509 unsigned long gulong;
6514 long double gldouble;
6526 <!-- ----------------------------------------------------------------- -->
6527 <sect1>Doubly Linked Lists
6529 The following functions are used to create, manage, and destroy doubly
6530 linked lists. I assume you know what linked lists are, as it is beyond the scope
6531 of this document to explain them. Of course, it's not required that you
6532 know these for general use of GTK, but they are nice to know.
6535 GList* g_list_alloc (void);
6537 void g_list_free (GList *list);
6539 void g_list_free_1 (GList *list);
6541 GList* g_list_append (GList *list,
6544 GList* g_list_prepend (GList *list,
6547 GList* g_list_insert (GList *list,
6551 GList* g_list_remove (GList *list,
6554 GList* g_list_remove_link (GList *list,
6557 GList* g_list_reverse (GList *list);
6559 GList* g_list_nth (GList *list,
6562 GList* g_list_find (GList *list,
6565 GList* g_list_last (GList *list);
6567 GList* g_list_first (GList *list);
6569 gint g_list_length (GList *list);
6571 void g_list_foreach (GList *list,
6573 gpointer user_data);
6576 <!-- ----------------------------------------------------------------- -->
6577 <sect1>Singly Linked Lists
6579 Many of the above functions for singly linked lists are identical to the
6580 above. Here is a complete list:
6582 GSList* g_slist_alloc (void);
6584 void g_slist_free (GSList *list);
6586 void g_slist_free_1 (GSList *list);
6588 GSList* g_slist_append (GSList *list,
6591 GSList* g_slist_prepend (GSList *list,
6594 GSList* g_slist_insert (GSList *list,
6598 GSList* g_slist_remove (GSList *list,
6601 GSList* g_slist_remove_link (GSList *list,
6604 GSList* g_slist_reverse (GSList *list);
6606 GSList* g_slist_nth (GSList *list,
6609 GSList* g_slist_find (GSList *list,
6612 GSList* g_slist_last (GSList *list);
6614 gint g_slist_length (GSList *list);
6616 void g_slist_foreach (GSList *list,
6618 gpointer user_data);
6622 <!-- ----------------------------------------------------------------- -->
6623 <sect1>Memory Management
6626 gpointer g_malloc (gulong size);
6629 This is a replacement for malloc(). You do not need to check the return
6630 vaule as it is done for you in this function.
6633 gpointer g_malloc0 (gulong size);
6636 Same as above, but zeroes the memory before returning a pointer to it.
6639 gpointer g_realloc (gpointer mem,
6643 Relocates "size" bytes of memory starting at "mem". Obviously, the memory should have been
6644 previously allocated.
6647 void g_free (gpointer mem);
6650 Frees memory. Easy one.
6653 void g_mem_profile (void);
6656 Dumps a profile of used memory, but requries that you add #define
6657 MEM_PROFILE to the top of glib/gmem.c and re-make and make install.
6660 void g_mem_check (gpointer mem);
6663 Checks that a memory location is valid. Requires you add #define
6664 MEM_CHECK to the top of gmem.c and re-make and make install.
6666 <!-- ----------------------------------------------------------------- -->
6672 GTimer* g_timer_new (void);
6674 void g_timer_destroy (GTimer *timer);
6676 void g_timer_start (GTimer *timer);
6678 void g_timer_stop (GTimer *timer);
6680 void g_timer_reset (GTimer *timer);
6682 gdouble g_timer_elapsed (GTimer *timer,
6683 gulong *microseconds);
6686 <!-- ----------------------------------------------------------------- -->
6687 <sect1>String Handling
6689 A whole mess of string handling functions. They all look very interesting, and
6690 probably better for many purposes than the standard C string functions, but
6691 require documentation.
6694 GString* g_string_new (gchar *init);
6695 void g_string_free (GString *string,
6698 GString* g_string_assign (GString *lval,
6701 GString* g_string_truncate (GString *string,
6704 GString* g_string_append (GString *string,
6707 GString* g_string_append_c (GString *string,
6710 GString* g_string_prepend (GString *string,
6713 GString* g_string_prepend_c (GString *string,
6716 void g_string_sprintf (GString *string,
6720 void g_string_sprintfa (GString *string,
6725 <!-- ----------------------------------------------------------------- -->
6726 <sect1>Utility and Error Functions
6729 gchar* g_strdup (const gchar *str);
6732 Replacement strdup function. Copies the
6733 original strings contents to newly allocated memory, and returns a pointer to it.
6736 gchar* g_strerror (gint errnum);
6739 I recommend using this for all error messages. It's much nicer, and more
6740 portable than perror() or others. The output is usually of the form:
6743 program name:function that failed:file or further description:strerror
6746 Here's an example of one such call used in our hello_world program:
6749 g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno));
6753 void g_error (gchar *format, ...);
6756 Prints an error message. The format is just like printf, but it
6757 prepends "** ERROR **: " to your message, and exits the program.
6758 Use only for fatal errors.
6761 void g_warning (gchar *format, ...);
6764 Same as above, but prepends "** WARNING **: ", and does not exit the
6768 void g_message (gchar *format, ...);
6771 Prints "message: " prepended to the string you pass in.
6774 void g_print (gchar *format, ...);
6777 Replacement for printf().
6779 And our last function:
6782 gchar* g_strsignal (gint signum);
6785 Prints out the name of the Unix system signal given the signal number.
6786 Useful in generic signal handling functions.
6788 All of the above are more or less just stolen from glib.h. If anyone cares
6789 to document any function, just send me an email!
6791 <!-- ***************************************************************** -->
6792 <sect>GTK's rc Files
6793 <!-- ***************************************************************** -->
6796 GTK has it's own way of dealing with application defaults, by using rc
6797 files. These can be used to set the colors of just about any widget, and
6798 can also be used to tile pixmaps onto the background of some widgets.
6800 <!-- ----------------------------------------------------------------- -->
6801 <sect1>Functions For rc Files
6803 When your application starts, you should include a call to:
6805 void gtk_rc_parse (char *filename);
6808 Passing in the filename of your rc file. This will cause GTK to parse this
6809 file, and use the style settings for the widget types defined there.
6811 If you wish to have a special set of widgets that can take on a different
6812 style from others, or any other logical division of widgets, use a call to:
6814 void gtk_widget_set_name (GtkWidget *widget,
6818 Passing your newly created widget as the first argument, and the name
6819 you wish to give it as the second. This will allow you to change the
6820 attributes of this widget by name through the rc file.
6822 If we use a call something like this:
6825 button = gtk_button_new_with_label ("Special Button");
6826 gtk_widget_set_name (button, "special button");
6829 Then this button is given the name "special button" and may be addressed by
6830 name in the rc file as "special button.GtkButton". [<--- Verify ME!]
6832 The example rc file below, sets the properties of the main window, and lets
6833 all children of that main window inherit the style described by the "main
6834 button" style. The code used in the application is:
6837 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
6838 gtk_widget_set_name (window, "main window");
6841 And then the style is defined in the rc file using:
6844 widget "main window.*GtkButton*" style "main_button"
6847 Which sets all the GtkButton widgets in the "main window" to the
6848 "main_buttons" style as defined in the rc file.
6850 As you can see, this is a fairly powerful and flexible system. Use your
6851 imagination as to how best to take advantage of this.
6853 <!-- ----------------------------------------------------------------- -->
6854 <sect1>GTK's rc File Format
6856 The format of the GTK file is illustrated in the example below. This is
6857 the testgtkrc file from the GTK distribution, but I've added a
6858 few comments and things. You may wish to include this explanation
6859 your application to allow the user to fine tune his application.
6861 There are several directives to change the attributes of a widget.
6863 <item>fg - Sets the foreground color of a widget.
6864 <item>bg - Sets the background color of a widget.
6865 <item>bg_pixmap - Sets the background of a widget to a tiled pixmap.
6866 <item>font - Sets the font to be used with the given widget.
6869 In addition to this, there are several states a widget can be in, and you
6870 can set different colors, pixmaps and fonts for each state. These states are:
6872 <item>NORMAL - The normal state of a widget, without the mouse over top of
6873 it, and not being pressed etc.
6874 <item>PRELIGHT - When the mouse is over top of the widget, colors defined
6875 using this state will be in effect.
6876 <item>ACTIVE - When the widget is pressed or clicked it will be active, and
6877 the attributes assigned by this tag will be in effect.
6878 <item>INSENSITIVE - When a widget is set insensitive, and cannot be
6879 activated, it will take these attributes.
6880 <item>SELECTED - When an object is selected, it takes these attributes.
6883 When using the "fg" and "bg" keywords to set the colors of widgets, the
6886 fg[<STATE>] = { Red, Green, Blue }
6889 Where STATE is one of the above states (PRELIGHT, ACTIVE etc), and the Red,
6890 Green and Blue are values in the range of 0 - 1.0, { 1.0, 1.0, 1.0 } being
6892 They must be in float form, or they will register as 0, so a straight
6893 "1" will not work, it must
6894 be "1.0". A straight "0" is fine because it doesn't matter if it's not
6895 recognized. Unrecognized values are set to 0.
6897 bg_pixmap is very similar to the above, except the colors are replaced by a
6900 pixmap_path is a list of paths seperated by ":"'s. These paths will be
6901 searched for any pixmap you specify.
6904 The font directive is simply:
6906 font = "<font name>"
6909 Where the only hard part is figuring out the font string. Using xfontsel or
6910 similar utility should help.
6912 The "widget_class" sets the style of a class of widgets. These classes are
6913 listed in the widget overview on the class hierarchy.
6915 The "widget" directive sets a specificaly named set of widgets to a
6916 given style, overriding any style set for the given widget class.
6917 These widgets are registered inside the application using the
6918 gtk_widget_set_name() call. This allows you to specify the attributes of a
6919 widget on a per widget basis, rather than setting the attributes of an
6920 entire widget class. I urge you to document any of these special widgets so
6921 users may customize them.
6923 When the keyword "<tt>parent</>" is used as an attribute, the widget will take on
6924 the attributes of it's parent in the application.
6926 When defining a style, you may assign the attributes of a previously defined
6927 style to this new one.
6929 style "main_button" = "button"
6931 font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
6932 bg[PRELIGHT] = { 0.75, 0, 0 }
6936 This example takes the "button" style, and creates a new "main_button" style
6937 simply by changing the font and prelight background color of the "button"
6940 Of course, many of these attributes don't apply to all widgets. It's a
6941 simple matter of common sense really. Anything that could apply, should.
6943 <!-- ----------------------------------------------------------------- -->
6944 <sect1>Example rc file
6948 # pixmap_path "<dir 1>:<dir 2>:<dir 3>:..."
6950 pixmap_path "/usr/include/X11R6/pixmaps:/home/imain/pixmaps"
6952 # style <name> [= <name>]
6957 # widget <widget_set> style <style_name>
6958 # widget_class <widget_class_set> style <style_name>
6961 # Here is a list of all the possible states. Note that some do not apply to
6964 # NORMAL - The normal state of a widget, without the mouse over top of
6965 # it, and not being pressed etc.
6967 # PRELIGHT - When the mouse is over top of the widget, colors defined
6968 # using this state will be in effect.
6970 # ACTIVE - When the widget is pressed or clicked it will be active, and
6971 # the attributes assigned by this tag will be in effect.
6973 # INSENSITIVE - When a widget is set insensitive, and cannot be
6974 # activated, it will take these attributes.
6976 # SELECTED - When an object is selected, it takes these attributes.
6978 # Given these states, we can set the attributes of the widgets in each of
6979 # these states using the following directives.
6981 # fg - Sets the foreground color of a widget.
6982 # fg - Sets the background color of a widget.
6983 # bg_pixmap - Sets the background of a widget to a tiled pixmap.
6984 # font - Sets the font to be used with the given widget.
6987 # This sets a style called "button". The name is not really important, as
6988 # it is assigned to the actual widgets at the bottom of the file.
6992 #This sets the padding around the window to the pixmap specified.
6993 #bg_pixmap[<STATE>] = "<pixmap filename>"
6994 bg_pixmap[NORMAL] = "warning.xpm"
6999 #Sets the foreground color (font color) to red when in the "NORMAL"
7002 fg[NORMAL] = { 1.0, 0, 0 }
7004 #Sets the background pixmap of this widget to that of it's parent.
7005 bg_pixmap[NORMAL] = "<parent>"
7010 # This shows all the possible states for a button. The only one that
7011 # doesn't apply is the SELECTED state.
7013 fg[PRELIGHT] = { 0, 1.0, 1.0 }
7014 bg[PRELIGHT] = { 0, 0, 1.0 }
7015 bg[ACTIVE] = { 1.0, 0, 0 }
7016 fg[ACTIVE] = { 0, 1.0, 0 }
7017 bg[NORMAL] = { 1.0, 1.0, 0 }
7018 fg[NORMAL] = { .99, 0, .99 }
7019 bg[INSENSITIVE] = { 1.0, 1.0, 1.0 }
7020 fg[INSENSITIVE] = { 1.0, 0, 1.0 }
7023 # In this example, we inherit the attributes of the "button" style and then
7024 # override the font and background color when prelit to create a new
7025 # "main_button" style.
7027 style "main_button" = "button"
7029 font = "-adobe-helvetica-medium-r-normal--*-100-*-*-*-*-*-*"
7030 bg[PRELIGHT] = { 0.75, 0, 0 }
7033 style "toggle_button" = "button"
7035 fg[NORMAL] = { 1.0, 0, 0 }
7036 fg[ACTIVE] = { 1.0, 0, 0 }
7038 # This sets the background pixmap of the toggle_button to that of it's
7039 # parent widget (as defined in the application).
7040 bg_pixmap[NORMAL] = "<parent>"
7045 bg_pixmap[NORMAL] = "marble.xpm"
7046 fg[NORMAL] = { 1.0, 1.0, 1.0 }
7051 font = "-adobe-helvetica-medium-r-normal--*-80-*-*-*-*-*-*"
7054 # pixmap_path "~/.pixmaps"
7056 # These set the widget types to use the styles defined above.
7057 # The widget types are listed in the class hierarchy, but could probably be
7058 # just listed in this document for the users reference.
7060 widget_class "GtkWindow" style "window"
7061 widget_class "GtkDialog" style "window"
7062 widget_class "GtkFileSelection" style "window"
7063 widget_class "*Gtk*Scale" style "scale"
7064 widget_class "*GtkCheckButton*" style "toggle_button"
7065 widget_class "*GtkRadioButton*" style "toggle_button"
7066 widget_class "*GtkButton*" style "button"
7067 widget_class "*Ruler" style "ruler"
7068 widget_class "*GtkText" style "text"
7070 # This sets all the buttons that are children of the "main window" to
7071 # the main_buton style. These must be documented to be taken advantage of.
7072 widget "main window.*GtkButton*" style "main_button"
7075 <!-- ***************************************************************** -->
7076 <sect>Writing Your Own Widgets
7077 <!-- ***************************************************************** -->
7079 <!-- ----------------------------------------------------------------- -->
7082 Although the GTK distribution comes with many types of widgets that
7083 should cover most basic needs, there may come a time when you need to
7084 create your own new widget type. Since GTK uses widget inheretence
7085 extensively, and there is already a widget that
7086 is close to what you want, it is often possible to make a useful new widget type in
7087 just a few lines of code. But before starting work on a new widget, check
7088 around first to make sure that someone has not already written
7089 it. This will prevent duplication of effort and keep the number of
7090 GTK widgets out there to a minimum, which will help keep both the code
7091 and the interface of different applications consistent. As a flip side
7092 to this, once you finish your widget, announce it to the world so
7093 other people can benefit. The best place to do this is probably the
7096 Complete sources for the example widgets are available at the place you
7097 got this tutorial, or from:
7099 <htmlurl url="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial"
7100 name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial">
7103 <!-- ----------------------------------------------------------------- -->
7104 <sect1> The Anatomy Of A Widget
7107 In order to create a new widget, it is important to have an
7108 understanding of how GTK objects work. This section is just meant as a
7109 brief overview. See the reference documentation for the details.
7112 GTK widgets are implemented in an object oriented fashion. However,
7113 they are implemented in standard C. This greatly improves portability
7114 and stability over using current generation C++ compilers; however,
7115 it does mean that the widget writer has to pay attention to some of
7116 the implementation details. The information common to all instances of
7117 one class of widgets (e.g., to all Button widgets) is stored in the
7118 <em>class structure</em>. There is only one copy of this in
7119 which is stored information about the class's signals
7120 (which act like virtual functions in C). To support inheritance, the
7121 first field in the class structure must be a copy of the parent's
7122 class structure. The declaration of the class structure of GtkButtton
7126 struct _GtkButtonClass
7128 GtkContainerClass parent_class;
7130 void (* pressed) (GtkButton *button);
7131 void (* released) (GtkButton *button);
7132 void (* clicked) (GtkButton *button);
7133 void (* enter) (GtkButton *button);
7134 void (* leave) (GtkButton *button);
7139 When a button is treated as a container (for instance, when it is
7140 resized), its class structure can be cast to GtkContainerClass, and
7141 the relevant fields used to handle the signals.
7144 There is also a structure for each widget that is created on a
7145 per-instance basis. This structure has fields to store information that
7146 is different for each instance of the widget. We'll call this
7147 structure the <em>object structure</em>. For the Button class, it looks
7153 GtkContainer container;
7157 guint in_button : 1;
7158 guint button_down : 1;
7163 Note that, similar to the class structure, the first field is the
7164 object structure of the parent class, so that this structure can be
7165 cast to the parent class's object structure as needed.
7167 <!-- ----------------------------------------------------------------- -->
7168 <sect1> Creating a Composite widget
7170 <!-- ----------------------------------------------------------------- -->
7171 <sect2> Introduction
7174 One type of widget that you may be interested in creating is a
7175 widget that is merely an aggregate of other GTK widgets. This type of
7176 widget does nothing that couldn't be done without creating new
7177 widgets, but provides a convenient way of packaging user interface
7178 elements for reuse. The FileSelection and ColorSelection widgets in
7179 the standard distribution are examples of this type of widget.
7182 The example widget that we'll create in this section is the Tictactoe
7183 widget, a 3x3 array of toggle buttons which triggers a signal when all
7184 three buttons in a row, column, or on one of the diagonals are
7187 <!-- ----------------------------------------------------------------- -->
7188 <sect2> Choosing a parent class
7191 The parent class for a composite widget is typically the container
7192 class that holds all of the elements of the composite widget. For
7193 example, the parent class of the FileSelection widget is the
7194 Dialog class. Since our buttons will be arranged in a table, it
7195 might seem natural to make our parent class the GtkTable
7196 class. Unfortunately, this turns out not to work. The creation of a
7197 widget is divided among two functions - a <tt/WIDGETNAME_new()/
7198 function that the user calls, and a <tt/WIDGETNAME_init()/ function
7199 which does the basic work of initializing the widget which is
7200 independent of the arguments passed to the <tt/_new()/
7201 function. Descendent widgets only call the <tt/_init/ function of
7202 their parent widget. But this division of labor doesn't work well for
7203 tables, which when created, need to know the number of rows and
7204 columns in the table. Unless we want to duplicate most of the
7205 functionality of <tt/gtk_table_new()/ in our Tictactoe widget, we had
7206 best avoid deriving it from GtkTable. For that reason, we derive it
7207 from GtkVBox instead, and stick our table inside the VBox.
7209 <!-- ----------------------------------------------------------------- -->
7210 <sect2> The header file
7213 Each widget class has a header file which declares the object and
7214 class structures for that widget, along with public functions.
7215 A couple of features are worth pointing out. To prevent duplicate
7216 definitions, we wrap the entire header file in:
7219 #ifndef __TICTACTOE_H__
7220 #define __TICTACTOE_H__
7224 #endif /* __TICTACTOE_H__ */
7227 And to keep C++ programs that include the header file happy, in:
7232 #endif /* __cplusplus */
7238 #endif /* __cplusplus */
7241 Along with the functions and structures, we declare three standard
7242 macros in our header file, <tt/TICTACTOE(obj)/,
7243 <tt/TICTACTOE_CLASS(klass)/, and <tt/IS_TICTACTOE(obj)/, which cast a
7244 pointer into a pointer to the object or class structure, and check
7245 if an object is a Tictactoe widget respectively.
7248 Here is the complete header file:
7253 #ifndef __TICTACTOE_H__
7254 #define __TICTACTOE_H__
7256 #include <gdk/gdk.h>
7257 #include <gtk/gtkvbox.h>
7261 #endif /* __cplusplus */
7263 #define TICTACTOE(obj) GTK_CHECK_CAST (obj, tictactoe_get_type (), Tictactoe)
7264 #define TICTACTOE_CLASS(klass) GTK_CHECK_CLASS_CAST (klass, tictactoe_get_type (), TictactoeClass)
7265 #define IS_TICTACTOE(obj) GTK_CHECK_TYPE (obj, tictactoe_get_type ())
7268 typedef struct _Tictactoe Tictactoe;
7269 typedef struct _TictactoeClass TictactoeClass;
7275 GtkWidget *buttons[3][3];
7278 struct _TictactoeClass
7280 GtkVBoxClass parent_class;
7282 void (* tictactoe) (Tictactoe *ttt);
7285 guint tictactoe_get_type (void);
7286 GtkWidget* tictactoe_new (void);
7287 void tictactoe_clear (Tictactoe *ttt);
7291 #endif /* __cplusplus */
7293 #endif /* __TICTACTOE_H__ */
7297 <!-- ----------------------------------------------------------------- -->
7298 <sect2> The <tt/_get_type()/ function.
7301 We now continue on to the implementation of our widget. A core
7302 function for every widget is the function
7303 <tt/WIDGETNAME_get_type()/. This function, when first called, tells
7304 GTK about the widget class, and gets an ID that uniquely identifies
7305 the widget class. Upon subsequent calls, it just returns the ID.
7309 tictactoe_get_type ()
7311 static guint ttt_type = 0;
7315 GtkTypeInfo ttt_info =
7319 sizeof (TictactoeClass),
7320 (GtkClassInitFunc) tictactoe_class_init,
7321 (GtkObjectInitFunc) tictactoe_init,
7322 (GtkArgSetFunc) NULL,
7323 (GtkArgGetFunc) NULL
7326 ttt_type = gtk_type_unique (gtk_vbox_get_type (), &ttt_info);
7334 The GtkTypeInfo structure has the following definition:
7342 GtkClassInitFunc class_init_func;
7343 GtkObjectInitFunc object_init_func;
7344 GtkArgSetFunc arg_set_func;
7345 GtkArgGetFunc arg_get_func;
7350 The fields of this structure are pretty self-explanatory. We'll ignore
7351 the <tt/arg_set_func/ and <tt/arg_get_func/ fields here: they have an important,
7353 unimplemented, role in allowing widget options to be conveniently set
7354 from interpreted languages. Once GTK has a correctly filled in copy of
7355 this structure, it knows how to create objects of a particular widget
7358 <!-- ----------------------------------------------------------------- -->
7359 <sect2> The <tt/_class_init()/ function
7362 The <tt/WIDGETNAME_class_init()/ function initializes the fields of
7363 the widget's class structure, and sets up any signals for the
7364 class. For our Tictactoe widget it looks like:
7373 static gint tictactoe_signals[LAST_SIGNAL] = { 0 };
7376 tictactoe_class_init (TictactoeClass *class)
7378 GtkObjectClass *object_class;
7380 object_class = (GtkObjectClass*) class;
7382 tictactoe_signals[TICTACTOE_SIGNAL] = gtk_signal_new ("tictactoe",
7385 GTK_SIGNAL_OFFSET (TictactoeClass, tictactoe),
7386 gtk_signal_default_marshaller, GTK_TYPE_NONE, 0);
7389 gtk_object_class_add_signals (object_class, tictactoe_signals, LAST_SIGNAL);
7391 class->tictactoe = NULL;
7396 Our widget has just one signal, the ``tictactoe'' signal that is
7397 invoked when a row, column, or diagonal is completely filled in. Not
7398 every composite widget needs signals, so if you are reading this for
7399 the first time, you may want to skip to the next section now, as
7400 things are going to get a bit complicated.
7405 gint gtk_signal_new (const gchar *name,
7406 GtkSignalRunType run_type,
7407 GtkType object_type,
7408 gint function_offset,
7409 GtkSignalMarshaller marshaller,
7415 Creates a new signal. The parameters are:
7418 <item> <tt/name/: The name of the signal.
7419 <item> <tt/run_type/: Whether the default handler runs before or after
7420 user handlers. Usually this will be <tt/GTK_RUN_FIRST/, or <tt/GTK_RUN_LAST/,
7421 although there are other possibilities.
7422 <item> <tt/object_type/: The ID of the object that this signal applies
7423 to. (It will also apply to that objects descendents)
7424 <item> <tt/function_offset/: The offset within the class structure of
7425 a pointer to the default handler.
7426 <item> <tt/marshaller/: A function that is used to invoke the signal
7427 handler. For signal handlers that have no arguments other than the
7428 object that emitted the signal and user data, we can use the
7429 pre-supplied marshaller function <tt/gtk_signal_default_marshaller/.
7430 <item> <tt/return_val/: The type of the return val.
7431 <item> <tt/nparams/: The number of parameters of the signal handler
7432 (other than the two default ones mentioned above)
7433 <item> <tt/.../: The types of the parameters.
7436 When specifying types, the <tt/GtkType/ enumeration is used:
7461 /* it'd be great if the next two could be removed eventually */
7463 GTK_TYPE_C_CALLBACK,
7467 } GtkFundamentalType;
7471 <tt/gtk_signal_new()/ returns a unique integer identifier for the
7472 signal, that we store in the <tt/tictactoe_signals/ array, which we
7473 index using an enumeration. (Conventionally, the enumeration elements
7474 are the signal name, uppercased, but here there would be a conflict
7475 with the <tt/TICTACTOE()/ macro, so we called it <tt/TICTACTOE_SIGNAL/
7478 After creating our signals, we need to tell GTK to associate our
7479 signals with the Tictactoe class. We do that by calling
7480 <tt/gtk_object_class_add_signals()/. We then set the pointer which
7481 points to the default handler for the ``tictactoe'' signal to NULL,
7482 indicating that there is no default action.
7484 <!-- ----------------------------------------------------------------- -->
7485 <sect2> The <tt/_init()/ function.
7489 Each widget class also needs a function to initialize the object
7490 structure. Usually, this function has the fairly limited role of
7491 setting the fields of the structure to default values. For composite
7492 widgets, however, this function also creates the component widgets.
7496 tictactoe_init (Tictactoe *ttt)
7501 table = gtk_table_new (3, 3, TRUE);
7502 gtk_container_add (GTK_CONTAINER(ttt), table);
7503 gtk_widget_show (table);
7508 ttt->buttons[i][j] = gtk_toggle_button_new ();
7509 gtk_table_attach_defaults (GTK_TABLE(table), ttt->buttons[i][j],
7511 gtk_signal_connect (GTK_OBJECT (ttt->buttons[i][j]), "toggled",
7512 GTK_SIGNAL_FUNC (tictactoe_toggle), ttt);
7513 gtk_widget_set_usize (ttt->buttons[i][j], 20, 20);
7514 gtk_widget_show (ttt->buttons[i][j]);
7519 <!-- ----------------------------------------------------------------- -->
7520 <sect2> And the rest...
7524 There is one more function that every widget (except for base widget
7525 types like GtkBin that cannot be instantiated) needs to have - the
7526 function that the user calls to create an object of that type. This is
7527 conventionally called <tt/WIDGETNAME_new()/. In some
7528 widgets, though not for the Tictactoe widgets, this function takes
7529 arguments, and does some setup based on the arguments. The other two
7530 functions are specific to the Tictactoe widget.
7533 <tt/tictactoe_clear()/ is a public function that resets all the
7534 buttons in the widget to the up position. Note the use of
7535 <tt/gtk_signal_handler_block_by_data()/ to keep our signal handler for
7536 button toggles from being triggered unnecessarily.
7539 <tt/tictactoe_toggle()/ is the signal handler that is invoked when the
7540 user clicks on a button. It checks to see if there are any winning
7541 combinations that involve the toggled button, and if so, emits
7542 the "tictactoe" signal.
7548 return GTK_WIDGET ( gtk_type_new (tictactoe_get_type ()));
7552 tictactoe_clear (Tictactoe *ttt)
7559 gtk_signal_handler_block_by_data (GTK_OBJECT(ttt->buttons[i][j]), ttt);
7560 gtk_toggle_button_set_state (GTK_TOGGLE_BUTTON (ttt->buttons[i][j]),
7562 gtk_signal_handler_unblock_by_data (GTK_OBJECT(ttt->buttons[i][j]), ttt);
7567 tictactoe_toggle (GtkWidget *widget, Tictactoe *ttt)
7571 static int rwins[8][3] = { { 0, 0, 0 }, { 1, 1, 1 }, { 2, 2, 2 },
7572 { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 },
7573 { 0, 1, 2 }, { 0, 1, 2 } };
7574 static int cwins[8][3] = { { 0, 1, 2 }, { 0, 1, 2 }, { 0, 1, 2 },
7575 { 0, 0, 0 }, { 1, 1, 1 }, { 2, 2, 2 },
7576 { 0, 1, 2 }, { 2, 1, 0 } };
7587 success = success &&
7588 GTK_TOGGLE_BUTTON(ttt->buttons[rwins[k][i]][cwins[k][i]])->active;
7590 ttt->buttons[rwins[k][i]][cwins[k][i]] == widget;
7593 if (success && found)
7595 gtk_signal_emit (GTK_OBJECT (ttt),
7596 tictactoe_signals[TICTACTOE_SIGNAL]);
7605 And finally, an example program using our Tictactoe widget:
7608 #include <gtk/gtk.h>
7609 #include "tictactoe.h"
7611 /* Invoked when a row, column or diagonal is completed */
7613 win (GtkWidget *widget, gpointer data)
7616 tictactoe_clear (TICTACTOE (widget));
7620 main (int argc, char *argv[])
7625 gtk_init (&argc, &argv);
7627 window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
7629 gtk_window_set_title (GTK_WINDOW (window), "Aspect Frame");
7631 gtk_signal_connect (GTK_OBJECT (window), "destroy",
7632 GTK_SIGNAL_FUNC (gtk_exit), NULL);
7634 gtk_container_border_width (GTK_CONTAINER (window), 10);
7636 /* Create a new Tictactoe widget */
7637 ttt = tictactoe_new ();
7638 gtk_container_add (GTK_CONTAINER (window), ttt);
7639 gtk_widget_show (ttt);
7641 /* And attach to its "tictactoe" signal */
7642 gtk_signal_connect (GTK_OBJECT (ttt), "tictactoe",
7643 GTK_SIGNAL_FUNC (win), NULL);
7645 gtk_widget_show (window);
7654 <!-- ----------------------------------------------------------------- -->
7655 <sect1> Creating a widget from scratch.
7657 <!-- ----------------------------------------------------------------- -->
7658 <sect2> Introduction
7662 In this section, we'll learn more about how widgets display themselves
7663 on the screen and interact with events. As an example of this, we'll
7664 create an analog dial widget with a pointer that the user can drag to
7667 <!-- ----------------------------------------------------------------- -->
7668 <sect2> Displaying a widget on the screen
7671 There are several steps that are involved in displaying on the screen.
7672 After the widget is created with a call to <tt/WIDGETNAME_new()/,
7673 several more functions are needed:
7676 <item> <tt/WIDGETNAME_realize()/ is responsible for creating an X
7677 window for the widget if it has one.
7678 <item> <tt/WIDGETNAME_map()/ is invoked after the user calls
7679 <tt/gtk_widget_show()/. It is responsible for making sure the widget
7680 is actually drawn on the screen (<em/mapped/). For a container class,
7681 it must also make calls to <tt/map()/> functions of any child widgets.
7682 <item> <tt/WIDGETNAME_draw()/ is invoked when <tt/gtk_widget_draw()/
7683 is called for the widget or one of its ancestors. It makes the actual
7684 calls to the drawing functions to draw the widget on the screen. For
7685 container widgets, this function must make calls to
7686 <tt/gtk_widget_draw()/ for its child widgets.
7687 <item> <tt/WIDGETNAME_expose()/ is a handler for expose events for the
7688 widget. It makes the necessary calls to the drawing functions to draw
7689 the exposed portion on the screen. For container widgets, this
7690 function must generate expose events for its child widgets which don't
7691 have their own windows. (If they have their own windows, then X will
7692 generate the necessary expose events)
7696 You might notice that the last two functions are quite similar - each
7697 is responsible for drawing the widget on the screen. In fact many
7698 types of widgets don't really care about the difference between the
7699 two. The default <tt/draw()/ function in the widget class simply
7700 generates a synthetic expose event for the redrawn area. However, some
7701 types of widgets can save work by distinguishing between the two
7702 functions. For instance, if a widget has multiple X windows, then
7703 since expose events identify the exposed window, it can redraw only
7704 the affected window, which is not possible for calls to <tt/draw()/.
7707 Container widgets, even if they don't care about the difference for
7708 themselves, can't simply use the default <tt/draw()/ function because
7709 their child widgets might care about the difference. However,
7710 it would be wasteful to duplicate the drawing code between the two
7711 functions. The convention is that such widgets have a function called
7712 <tt/WIDGETNAME_paint()/ that does the actual work of drawing the
7713 widget, that is then called by the <tt/draw()/ and <tt/expose()/
7717 In our example approach, since the dial widget is not a container
7718 widget, and only has a single window, we can take the simplest
7719 approach and use the default <tt/draw()/ function and only implement
7720 an <tt/expose()/ function.
7722 <!-- ----------------------------------------------------------------- -->
7723 <sect2> The origins of the Dial Widget
7726 Just as all land animals are just variants on the first amphibian that
7727 crawled up out of the mud, Gtk widgets tend to start off as variants
7728 of some other, previously written widget. Thus, although this section
7729 is entilted ``Creating a Widget from Scratch'', the Dial widget really
7730 began with the source code for the Range widget. This was picked as a
7731 starting point because it would be nice if our Dial had the same
7732 interface as the Scale widgets which are just specialized descendents
7733 of the Range widget. So, though the source code is presented below in
7734 finished form, it should not be implied that it was written, <em>deus
7735 ex machina</em> in this fashion. Also, if you aren't yet familiar with
7736 how scale widgets work from the application writer's point of view, it
7737 would be a good idea to look them over before continuing.
7739 <!-- ----------------------------------------------------------------- -->
7743 Quite a bit of our widget should look pretty familiar from the
7744 Tictactoe widget. First, we have a header file:
7747 /* GTK - The GIMP Toolkit
7748 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
7750 * This library is free software; you can redistribute it and/or
7751 * modify it under the terms of the GNU Library General Public
7752 * License as published by the Free Software Foundation; either
7753 * version 2 of the License, or (at your option) any later version.
7755 * This library is distributed in the hope that it will be useful,
7756 * but WITHOUT ANY WARRANTY; without even the implied warranty of
7757 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7758 * Library General Public License for more details.
7760 * You should have received a copy of the GNU Library General Public
7761 * License along with this library; if not, write to the Free
7762 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
7765 #ifndef __GTK_DIAL_H__
7766 #define __GTK_DIAL_H__
7768 #include <gdk/gdk.h>
7769 #include <gtk/gtkadjustment.h>
7770 #include <gtk/gtkwidget.h>
7775 #endif /* __cplusplus */
7778 #define GTK_DIAL(obj) GTK_CHECK_CAST (obj, gtk_dial_get_type (), GtkDial)
7779 #define GTK_DIAL_CLASS(klass) GTK_CHECK_CLASS_CAST (klass, gtk_dial_get_type (), GtkDialClass)
7780 #define GTK_IS_DIAL(obj) GTK_CHECK_TYPE (obj, gtk_dial_get_type ())
7783 typedef struct _GtkDial GtkDial;
7784 typedef struct _GtkDialClass GtkDialClass;
7790 /* update policy (GTK_UPDATE_[CONTINUOUS/DELAYED/DISCONTINUOUS]) */
7793 /* Button currently pressed or 0 if none */
7796 /* Dimensions of dial components */
7800 /* ID of update timer, or 0 if none */
7806 /* Old values from adjustment stored so we know when something changes */
7811 /* The adjustment object that stores the data for this dial */
7812 GtkAdjustment *adjustment;
7815 struct _GtkDialClass
7817 GtkWidgetClass parent_class;
7821 GtkWidget* gtk_dial_new (GtkAdjustment *adjustment);
7822 guint gtk_dial_get_type (void);
7823 GtkAdjustment* gtk_dial_get_adjustment (GtkDial *dial);
7824 void gtk_dial_set_update_policy (GtkDial *dial,
7825 GtkUpdateType policy);
7827 void gtk_dial_set_adjustment (GtkDial *dial,
7828 GtkAdjustment *adjustment);
7831 #endif /* __cplusplus */
7834 #endif /* __GTK_DIAL_H__ */
7837 Since there is quite a bit more going on in this widget, than the last
7838 one, we have more fields in the data structure, but otherwise things
7841 Next, after including header files, and declaring a few constants,
7842 we have some functions to provide information about the widget
7848 #include <gtk/gtkmain.h>
7849 #include <gtk/gtksignal.h>
7851 #include "gtkdial.h"
7853 #define SCROLL_DELAY_LENGTH 300
7854 #define DIAL_DEFAULT_SIZE 100
7856 /* Forward declararations */
7858 [ omitted to save space ]
7862 static GtkWidgetClass *parent_class = NULL;
7865 gtk_dial_get_type ()
7867 static guint dial_type = 0;
7871 GtkTypeInfo dial_info =
7875 sizeof (GtkDialClass),
7876 (GtkClassInitFunc) gtk_dial_class_init,
7877 (GtkObjectInitFunc) gtk_dial_init,
7878 (GtkArgSetFunc) NULL,
7879 (GtkArgGetFunc) NULL,
7882 dial_type = gtk_type_unique (gtk_widget_get_type (), &dial_info);
7889 gtk_dial_class_init (GtkDialClass *class)
7891 GtkObjectClass *object_class;
7892 GtkWidgetClass *widget_class;
7894 object_class = (GtkObjectClass*) class;
7895 widget_class = (GtkWidgetClass*) class;
7897 parent_class = gtk_type_class (gtk_widget_get_type ());
7899 object_class->destroy = gtk_dial_destroy;
7901 widget_class->realize = gtk_dial_realize;
7902 widget_class->expose_event = gtk_dial_expose;
7903 widget_class->size_request = gtk_dial_size_request;
7904 widget_class->size_allocate = gtk_dial_size_allocate;
7905 widget_class->button_press_event = gtk_dial_button_press;
7906 widget_class->button_release_event = gtk_dial_button_release;
7907 widget_class->motion_notify_event = gtk_dial_motion_notify;
7911 gtk_dial_init (GtkDial *dial)
7914 dial->policy = GTK_UPDATE_CONTINUOUS;
7917 dial->pointer_width = 0;
7919 dial->old_value = 0.0;
7920 dial->old_lower = 0.0;
7921 dial->old_upper = 0.0;
7922 dial->adjustment = NULL;
7926 gtk_dial_new (GtkAdjustment *adjustment)
7930 dial = gtk_type_new (gtk_dial_get_type ());
7933 adjustment = (GtkAdjustment*) gtk_adjustment_new (0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
7935 gtk_dial_set_adjustment (dial, adjustment);
7937 return GTK_WIDGET (dial);
7941 gtk_dial_destroy (GtkObject *object)
7945 g_return_if_fail (object != NULL);
7946 g_return_if_fail (GTK_IS_DIAL (object));
7948 dial = GTK_DIAL (object);
7950 if (dial->adjustment)
7951 gtk_object_unref (GTK_OBJECT (dial->adjustment));
7953 if (GTK_OBJECT_CLASS (parent_class)->destroy)
7954 (* GTK_OBJECT_CLASS (parent_class)->destroy) (object);
7958 Note that this <tt/init()/ function does less than for the Tictactoe
7959 widget, since this is not a composite widget, and the <tt/new()/
7960 function does more, since it now has an argument. Also, note that when
7961 we store a pointer to the Adjustment object, we increment its
7962 reference count, (and correspondingly decrement when we no longer use
7963 it) so that GTK can keep track of when it can be safely destroyed.
7966 Also, there are a few function to manipulate the widget's options:
7970 gtk_dial_get_adjustment (GtkDial *dial)
7972 g_return_val_if_fail (dial != NULL, NULL);
7973 g_return_val_if_fail (GTK_IS_DIAL (dial), NULL);
7975 return dial->adjustment;
7979 gtk_dial_set_update_policy (GtkDial *dial,
7980 GtkUpdateType policy)
7982 g_return_if_fail (dial != NULL);
7983 g_return_if_fail (GTK_IS_DIAL (dial));
7985 dial->policy = policy;
7989 gtk_dial_set_adjustment (GtkDial *dial,
7990 GtkAdjustment *adjustment)
7992 g_return_if_fail (dial != NULL);
7993 g_return_if_fail (GTK_IS_DIAL (dial));
7995 if (dial->adjustment)
7997 gtk_signal_disconnect_by_data (GTK_OBJECT (dial->adjustment), (gpointer) dial);
7998 gtk_object_unref (GTK_OBJECT (dial->adjustment));
8001 dial->adjustment = adjustment;
8002 gtk_object_ref (GTK_OBJECT (dial->adjustment));
8004 gtk_signal_connect (GTK_OBJECT (adjustment), "changed",
8005 (GtkSignalFunc) gtk_dial_adjustment_changed,
8007 gtk_signal_connect (GTK_OBJECT (adjustment), "value_changed",
8008 (GtkSignalFunc) gtk_dial_adjustment_value_changed,
8011 dial->old_value = adjustment->value;
8012 dial->old_lower = adjustment->lower;
8013 dial->old_upper = adjustment->upper;
8015 gtk_dial_update (dial);
8019 <sect2> <tt/gtk_dial_realize()/
8022 Now we come to some new types of functions. First, we have a function
8023 that does the work of creating the X window. Notice that a mask is
8024 passed to the function <tt/gdk_window_new()/ which specifies which fields of
8025 the GdkWindowAttr structure actually have data in them (the remaining
8026 fields wll be given default values). Also worth noting is the way the
8027 event mask of the widget is created. We call
8028 <tt/gtk_widget_get_events()/ to retrieve the event mask that the user
8029 has specified for this widget (with <tt/gtk_widget_set_events()/, and
8030 add the events that we are interested in ourselves.
8033 After creating the window, we set its style and background, and put a
8034 pointer to the widget in the user data field of the GdkWindow. This
8035 last step allows GTK to dispatch events for this window to the correct
8040 gtk_dial_realize (GtkWidget *widget)
8043 GdkWindowAttr attributes;
8044 gint attributes_mask;
8046 g_return_if_fail (widget != NULL);
8047 g_return_if_fail (GTK_IS_DIAL (widget));
8049 GTK_WIDGET_SET_FLAGS (widget, GTK_REALIZED);
8050 dial = GTK_DIAL (widget);
8052 attributes.x = widget->allocation.x;
8053 attributes.y = widget->allocation.y;
8054 attributes.width = widget->allocation.width;
8055 attributes.height = widget->allocation.height;
8056 attributes.wclass = GDK_INPUT_OUTPUT;
8057 attributes.window_type = GDK_WINDOW_CHILD;
8058 attributes.event_mask = gtk_widget_get_events (widget) |
8059 GDK_EXPOSURE_MASK | GDK_BUTTON_PRESS_MASK |
8060 GDK_BUTTON_RELEASE_MASK | GDK_POINTER_MOTION_MASK |
8061 GDK_POINTER_MOTION_HINT_MASK;
8062 attributes.visual = gtk_widget_get_visual (widget);
8063 attributes.colormap = gtk_widget_get_colormap (widget);
8065 attributes_mask = GDK_WA_X | GDK_WA_Y | GDK_WA_VISUAL | GDK_WA_COLORMAP;
8066 widget->window = gdk_window_new (widget->parent->window, &attributes, attributes_mask);
8068 widget->style = gtk_style_attach (widget->style, widget->window);
8070 gdk_window_set_user_data (widget->window, widget);
8072 gtk_style_set_background (widget->style, widget->window, GTK_STATE_ACTIVE);
8076 <sect2> Size negotiation
8079 Before the first time that the window containing a widget is
8080 displayed, and whenever the layout of the window changes, GTK asks
8081 each child widget for its desired size. This request is handled by the
8082 function, <tt/gtk_dial_size_request()/. Since our widget isn't a
8083 container widget, and has no real constraints on its size, we just
8084 return a reasonable default value.
8088 gtk_dial_size_request (GtkWidget *widget,
8089 GtkRequisition *requisition)
8091 requisition->width = DIAL_DEFAULT_SIZE;
8092 requisition->height = DIAL_DEFAULT_SIZE;
8097 After all the widgets have requested an ideal size, the layout of the
8098 window is computed and each child widget is notified of its actual
8099 size. Usually, this will at least as large as the requested size, but
8100 if for instance, the user has resized the window, it may occasionally
8101 be smaller than the requested size. The size notification is handled
8102 by the function <tt/gtk_dial_size_allocate()/. Notice that as well as
8103 computing the sizes of some component pieces for future use, this
8104 routine also does the grunt work of moving the widgets X window into
8105 the new position and size.
8109 gtk_dial_size_allocate (GtkWidget *widget,
8110 GtkAllocation *allocation)
8114 g_return_if_fail (widget != NULL);
8115 g_return_if_fail (GTK_IS_DIAL (widget));
8116 g_return_if_fail (allocation != NULL);
8118 widget->allocation = *allocation;
8119 if (GTK_WIDGET_REALIZED (widget))
8121 dial = GTK_DIAL (widget);
8123 gdk_window_move_resize (widget->window,
8124 allocation->x, allocation->y,
8125 allocation->width, allocation->height);
8127 dial->radius = MAX(allocation->width,allocation->height) * 0.45;
8128 dial->pointer_width = dial->radius / 5;
8133 <!-- ----------------------------------------------------------------- -->
8134 <sect2> <tt/gtk_dial_expose()/
8137 As mentioned above, all the drawing of this widget is done in the
8138 handler for expose events. There's not much to remark on here except
8139 the use of the function <tt/gtk_draw_polygon/ to draw the pointer with
8140 three dimensional shading according to the colors stored in the
8145 gtk_dial_expose (GtkWidget *widget,
8146 GdkEventExpose *event)
8156 g_return_val_if_fail (widget != NULL, FALSE);
8157 g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE);
8158 g_return_val_if_fail (event != NULL, FALSE);
8160 if (event->count > 0)
8163 dial = GTK_DIAL (widget);
8165 gdk_window_clear_area (widget->window,
8167 widget->allocation.width,
8168 widget->allocation.height);
8170 xc = widget->allocation.width/2;
8171 yc = widget->allocation.height/2;
8175 for (i=0; i<25; i++)
8177 theta = (i*M_PI/18. - M_PI/6.);
8181 tick_length = (i%6 == 0) ? dial->pointer_width : dial->pointer_width/2;
8183 gdk_draw_line (widget->window,
8184 widget->style->fg_gc[widget->state],
8185 xc + c*(dial->radius - tick_length),
8186 yc - s*(dial->radius - tick_length),
8187 xc + c*dial->radius,
8188 yc - s*dial->radius);
8193 s = sin(dial->angle);
8194 c = cos(dial->angle);
8197 points[0].x = xc + s*dial->pointer_width/2;
8198 points[0].y = yc + c*dial->pointer_width/2;
8199 points[1].x = xc + c*dial->radius;
8200 points[1].y = yc - s*dial->radius;
8201 points[2].x = xc - s*dial->pointer_width/2;
8202 points[2].y = yc - c*dial->pointer_width/2;
8204 gtk_draw_polygon (widget->style,
8215 <!-- ----------------------------------------------------------------- -->
8216 <sect2> Event handling
8220 The rest of the widget's code handles various types of events, and
8221 isn't too different from what would be found in many GTK
8222 applications. Two types of events can occur - either the user can
8223 click on the widget with the mouse and drag to move the pointer, or
8224 the value of the Adjustment object can change due to some external
8228 When the user clicks on the widget, we check to see if the click was
8229 appropriately near the pointer, and if so, store then button that the
8230 user clicked with in the <tt/button/ field of the widget
8231 structure, and grab all mouse events with a call to
8232 <tt/gtk_grab_add()/. Subsequent motion of the mouse causes the
8233 value of the control to be recomputed (by the function
8234 <tt/gtk_dial_update_mouse/). Depending on the policy that has been
8235 set, "value_changed" events are either generated instantly
8236 (<tt/GTK_UPDATE_CONTINUOUS/), after a delay in a timer added with
8237 <tt/gtk_timeout_add()/ (<tt/GTK_UPDATE_DELAYED/), or only when the
8238 button is released (<tt/GTK_UPDATE_DISCONTINUOUS/).
8242 gtk_dial_button_press (GtkWidget *widget,
8243 GdkEventButton *event)
8249 double d_perpendicular;
8251 g_return_val_if_fail (widget != NULL, FALSE);
8252 g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE);
8253 g_return_val_if_fail (event != NULL, FALSE);
8255 dial = GTK_DIAL (widget);
8257 /* Determine if button press was within pointer region - we
8258 do this by computing the parallel and perpendicular distance of
8259 the point where the mouse was pressed from the line passing through
8262 dx = event->x - widget->allocation.width / 2;
8263 dy = widget->allocation.height / 2 - event->y;
8265 s = sin(dial->angle);
8266 c = cos(dial->angle);
8268 d_parallel = s*dy + c*dx;
8269 d_perpendicular = fabs(s*dx - c*dy);
8271 if (!dial->button &&
8272 (d_perpendicular < dial->pointer_width/2) &&
8273 (d_parallel > - dial->pointer_width))
8275 gtk_grab_add (widget);
8277 dial->button = event->button;
8279 gtk_dial_update_mouse (dial, event->x, event->y);
8286 gtk_dial_button_release (GtkWidget *widget,
8287 GdkEventButton *event)
8291 g_return_val_if_fail (widget != NULL, FALSE);
8292 g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE);
8293 g_return_val_if_fail (event != NULL, FALSE);
8295 dial = GTK_DIAL (widget);
8297 if (dial->button == event->button)
8299 gtk_grab_remove (widget);
8303 if (dial->policy == GTK_UPDATE_DELAYED)
8304 gtk_timeout_remove (dial->timer);
8306 if ((dial->policy != GTK_UPDATE_CONTINUOUS) &&
8307 (dial->old_value != dial->adjustment->value))
8308 gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed");
8315 gtk_dial_motion_notify (GtkWidget *widget,
8316 GdkEventMotion *event)
8319 GdkModifierType mods;
8322 g_return_val_if_fail (widget != NULL, FALSE);
8323 g_return_val_if_fail (GTK_IS_DIAL (widget), FALSE);
8324 g_return_val_if_fail (event != NULL, FALSE);
8326 dial = GTK_DIAL (widget);
8328 if (dial->button != 0)
8333 if (event->is_hint || (event->window != widget->window))
8334 gdk_window_get_pointer (widget->window, &x, &y, &mods);
8336 switch (dial->button)
8339 mask = GDK_BUTTON1_MASK;
8342 mask = GDK_BUTTON2_MASK;
8345 mask = GDK_BUTTON3_MASK;
8353 gtk_dial_update_mouse (dial, x,y);
8360 gtk_dial_timer (GtkDial *dial)
8362 g_return_val_if_fail (dial != NULL, FALSE);
8363 g_return_val_if_fail (GTK_IS_DIAL (dial), FALSE);
8365 if (dial->policy == GTK_UPDATE_DELAYED)
8366 gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed");
8372 gtk_dial_update_mouse (GtkDial *dial, gint x, gint y)
8377 g_return_if_fail (dial != NULL);
8378 g_return_if_fail (GTK_IS_DIAL (dial));
8380 xc = GTK_WIDGET(dial)->allocation.width / 2;
8381 yc = GTK_WIDGET(dial)->allocation.height / 2;
8383 old_value = dial->adjustment->value;
8384 dial->angle = atan2(yc-y, x-xc);
8386 if (dial->angle < -M_PI/2.)
8387 dial->angle += 2*M_PI;
8389 if (dial->angle < -M_PI/6)
8390 dial->angle = -M_PI/6;
8392 if (dial->angle > 7.*M_PI/6.)
8393 dial->angle = 7.*M_PI/6.;
8395 dial->adjustment->value = dial->adjustment->lower + (7.*M_PI/6 - dial->angle) *
8396 (dial->adjustment->upper - dial->adjustment->lower) / (4.*M_PI/3.);
8398 if (dial->adjustment->value != old_value)
8400 if (dial->policy == GTK_UPDATE_CONTINUOUS)
8402 gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed");
8406 gtk_widget_draw (GTK_WIDGET(dial), NULL);
8408 if (dial->policy == GTK_UPDATE_DELAYED)
8411 gtk_timeout_remove (dial->timer);
8413 dial->timer = gtk_timeout_add (SCROLL_DELAY_LENGTH,
8414 (GtkFunction) gtk_dial_timer,
8423 Changes to the Adjustment by external means are communicated to our
8424 widget by the ``changed'' and ``value_changed'' signals. The handlers
8425 for these functions call <tt/gtk_dial_update()/ to validate the
8426 arguments, compute the new pointer angle, and redraw the widget (by
8427 calling <tt/gtk_widget_draw()/).
8431 gtk_dial_update (GtkDial *dial)
8435 g_return_if_fail (dial != NULL);
8436 g_return_if_fail (GTK_IS_DIAL (dial));
8438 new_value = dial->adjustment->value;
8440 if (new_value < dial->adjustment->lower)
8441 new_value = dial->adjustment->lower;
8443 if (new_value > dial->adjustment->upper)
8444 new_value = dial->adjustment->upper;
8446 if (new_value != dial->adjustment->value)
8448 dial->adjustment->value = new_value;
8449 gtk_signal_emit_by_name (GTK_OBJECT (dial->adjustment), "value_changed");
8452 dial->angle = 7.*M_PI/6. - (new_value - dial->adjustment->lower) * 4.*M_PI/3. /
8453 (dial->adjustment->upper - dial->adjustment->lower);
8455 gtk_widget_draw (GTK_WIDGET(dial), NULL);
8459 gtk_dial_adjustment_changed (GtkAdjustment *adjustment,
8464 g_return_if_fail (adjustment != NULL);
8465 g_return_if_fail (data != NULL);
8467 dial = GTK_DIAL (data);
8469 if ((dial->old_value != adjustment->value) ||
8470 (dial->old_lower != adjustment->lower) ||
8471 (dial->old_upper != adjustment->upper))
8473 gtk_dial_update (dial);
8475 dial->old_value = adjustment->value;
8476 dial->old_lower = adjustment->lower;
8477 dial->old_upper = adjustment->upper;
8482 gtk_dial_adjustment_value_changed (GtkAdjustment *adjustment,
8487 g_return_if_fail (adjustment != NULL);
8488 g_return_if_fail (data != NULL);
8490 dial = GTK_DIAL (data);
8492 if (dial->old_value != adjustment->value)
8494 gtk_dial_update (dial);
8496 dial->old_value = adjustment->value;
8501 <!-- ----------------------------------------------------------------- -->
8502 <sect2> Possible Enhancements
8505 The Dial widget as we've described it so far runs about 670 lines of
8506 code. Although that might sound like a fair bit, we've really
8507 accomplished quite a bit with that much code, especially since much of
8508 that length is headers and boilerplate. However, there are quite a few
8509 more enhancements that could be made to this widget:
8512 <item> If you try this widget out, you'll find that there is some
8513 flashing as the pointer is dragged around. This is because the entire
8514 widget is erased every time the pointer is moved before being
8515 redrawn. Often, the best way to handle this problem is to draw to an
8516 offscreen pixmap, then copy the final results onto the screen in one
8517 step. (The ProgressBar widget draws itself in this fashion.)
8519 <item> The user should be able to use the up and down arrow keys to
8520 increase and decrease the value.
8522 <item> It would be nice if the widget had buttons to increase and
8523 decrease the value in small or large steps. Although it would be
8524 possible to use embedded Button widgets for this, we would also like
8525 the buttons to auto-repeat when held down, as the arrows on a
8526 scrollbar do. Most of the code to implement this type of behavior can
8527 be found in the GtkRange widget.
8529 <item> The Dial widget could be made into a container widget with a
8530 single child widget positioned at the bottom between the buttons
8531 mentioned above. The user could then add their choice of a label or
8532 entry widget to display the current value of the dial.
8536 <!-- ----------------------------------------------------------------- -->
8537 <sect1> Learning More
8540 Only a small part of the many details involved in creating widgets
8541 could be described above. If you want to write your own widgets, the
8542 best source of examples is the GTK source itself. Ask yourself some
8543 questions about the widget you want to write: is it a Container
8544 widget? does it have its own window? is it a modification of an
8545 existing widget? Then find a similar widget, and start making changes.
8548 <!-- ***************************************************************** -->
8549 <sect>Scribble, A Simple Example Drawing Program
8550 <!-- ***************************************************************** -->
8552 <!-- ----------------------------------------------------------------- -->
8556 In this section, we will build a simple drawing program. In the
8557 process, we will examine how to handle mouse events, how to draw in a
8558 window, and how to do drawing better by using a backing pixmap. After
8559 creating the simple drawing program, we will extend it by adding
8560 support for XInput devices, such as drawing tablets. GTK provides
8561 support routines which makes getting extended information, such as
8562 pressure and tilt, from such devices quite easy.
8564 <!-- ----------------------------------------------------------------- -->
8565 <sect1> Event Handling
8568 The GTK signals we have already discussed are for high-level actions,
8569 such as a menu item being selected. However, sometimes it is useful to
8570 learn about lower-level occurrences, such as the mouse being moved, or
8571 a key being pressed. There are also GTK signals corresponding to these
8572 low-level <em>events</em>. The handlers for these signals have an
8573 extra parameter which is a pointer to a structure containing
8574 information about the event. For instance, motion events handlers are
8575 passed a pointer to a GdkEventMotion structure which looks (in part)
8579 struct _GdkEventMotion
8592 <tt/type/ will be set to the event type, in this case
8593 <tt/GDK_MOTION_NOTIFY/, window is the window in which the event
8594 occured. <tt/x/ and <tt/y/ give the coordinates of the event,
8595 and <tt/state/ specifies the modifier state when the event
8596 occurred (that is, it specifies which modifier keys and mouse buttons
8597 were pressed.) It is the bitwise OR of some of the following:
8616 As for other signals, to determine what happens when an event occurs
8617 we call <tt>gtk_signal_connect()</tt>. But we also need let GTK
8618 know which events we want to be notified about. To do this, we call
8622 void gtk_widget_set_events (GtkWidget *widget,
8626 The second field specifies the events we are interested in. It
8627 is the bitwise OR of constants that specify different types
8628 of events. For future reference the event types are:
8632 GDK_POINTER_MOTION_MASK
8633 GDK_POINTER_MOTION_HINT_MASK
8634 GDK_BUTTON_MOTION_MASK
8635 GDK_BUTTON1_MOTION_MASK
8636 GDK_BUTTON2_MOTION_MASK
8637 GDK_BUTTON3_MOTION_MASK
8638 GDK_BUTTON_PRESS_MASK
8639 GDK_BUTTON_RELEASE_MASK
8641 GDK_KEY_RELEASE_MASK
8642 GDK_ENTER_NOTIFY_MASK
8643 GDK_LEAVE_NOTIFY_MASK
8644 GDK_FOCUS_CHANGE_MASK
8646 GDK_PROPERTY_CHANGE_MASK
8647 GDK_PROXIMITY_IN_MASK
8648 GDK_PROXIMITY_OUT_MASK
8651 There are a few subtle points that have to be observed when calling
8652 <tt/gtk_widget_set_events()/. First, it must be called before the X window
8653 for a GTK widget is created. In practical terms, this means you
8654 should call it immediately after creating the widget. Second, the
8655 widget must have an associated X window. For efficiency, many widget
8656 types do not have their own window, but draw in their parent's window.
8679 To capture events for these widgets, you need to use an EventBox
8680 widget. See the section on
8681 <ref id="sec_The_EventBox_Widget" name="The EventBox Widget"> for
8685 For our drawing program, we want to know when the mouse button is
8686 pressed and when the mouse is moved, so we specify
8687 <tt/GDK_POINTER_MOTION_MASK/ and <tt/GDK_BUTTON_PRESS_MASK/. We also
8688 want to know when we need to redraw our window, so we specify
8689 <tt/GDK_EXPOSURE_MASK/. Although we want to be notified via a
8690 Configure event when our window size changes, we don't have to specify
8691 the corresponding <tt/GDK_STRUCTURE_MASK/ flag, because it is
8692 automatically specified for all windows.
8695 It turns out, however, that there is a problem with just specifying
8696 <tt/GDK_POINTER_MOTION_MASK/. This will cause the server to add a new
8697 motion event to the event queue every time the user moves the mouse.
8698 Imagine that it takes us 0.1 seconds to handle a motion event, but the
8699 X server queues a new motion event every 0.05 seconds. We will soon
8700 get way behind the users drawing. If the user draws for 5 seconds,
8701 it will take us another 5 seconds to catch up after they release
8702 the mouse button! What we would like is to only get one motion
8703 event for each event we process. The way to do this is to
8704 specify <tt/GDK_POINTER_MOTION_HINT_MASK/.
8707 When we specify <tt/GDK_POINTER_MOTION_HINT_MASK/, the server sends
8708 us a motion event the first time the pointer moves after entering
8709 our window, or after a button press or release event. Subsequent
8710 motion events will be suppressed until we explicitely ask for
8711 the position of the pointer using the function:
8714 GdkWindow* gdk_window_get_pointer (GdkWindow *window,
8717 GdkModifierType *mask);
8720 (There is another function, <tt>gtk_widget_get_pointer()</tt> which
8721 has a simpler interface, but turns out not to be very useful, since
8722 it only retrieves the position of the mouse, not whether the buttons
8726 The code to set the events for our window then looks like:
8729 gtk_signal_connect (GTK_OBJECT (drawing_area), "expose_event",
8730 (GtkSignalFunc) expose_event, NULL);
8731 gtk_signal_connect (GTK_OBJECT(drawing_area),"configure_event",
8732 (GtkSignalFunc) configure_event, NULL);
8733 gtk_signal_connect (GTK_OBJECT (drawing_area), "motion_notify_event",
8734 (GtkSignalFunc) motion_notify_event, NULL);
8735 gtk_signal_connect (GTK_OBJECT (drawing_area), "button_press_event",
8736 (GtkSignalFunc) button_press_event, NULL);
8738 gtk_widget_set_events (drawing_area, GDK_EXPOSURE_MASK
8739 | GDK_LEAVE_NOTIFY_MASK
8740 | GDK_BUTTON_PRESS_MASK
8741 | GDK_POINTER_MOTION_MASK
8742 | GDK_POINTER_MOTION_HINT_MASK);
8745 We'll save the "expose_event" and "configure_event" handlers for
8746 later. The "motion_notify_event" and "button_press_event" handlers
8751 button_press_event (GtkWidget *widget, GdkEventButton *event)
8753 if (event->button == 1 && pixmap != NULL)
8754 draw_brush (widget, event->x, event->y);
8760 motion_notify_event (GtkWidget *widget, GdkEventMotion *event)
8763 GdkModifierType state;
8766 gdk_window_get_pointer (event->window, &x, &y, &state);
8771 state = event->state;
8774 if (state & GDK_BUTTON1_MASK && pixmap != NULL)
8775 draw_brush (widget, x, y);
8781 <!-- ----------------------------------------------------------------- -->
8782 <sect1> The DrawingArea Widget, And Drawing
8785 We know turn to the process of drawing on the screen. The
8786 widget we use for this is the DrawingArea widget. A drawing area
8787 widget is essentially an X window and nothing more. It is a blank
8788 canvas in which we can draw whatever we like. A drawing area
8789 is created using the call:
8792 GtkWidget* gtk_drawing_area_new (void);
8795 A default size for the widget can be specified by calling:
8798 void gtk_drawing_area_size (GtkDrawingArea *darea,
8803 This default size can be overriden, as is true for all widgets,
8804 by calling <tt>gtk_widget_set_usize()</tt>, and that, in turn, can
8805 be overridden if the user manually resizes the the window containing
8809 It should be noted that when we create a DrawingArea widget, we are,
8810 <em>completely</em> responsible for drawing the contents. If our
8811 window is obscured then uncovered, we get an exposure event and must
8812 redraw what was previously hidden.
8815 Having to remember everything that was drawn on the screen so we
8816 can properly redraw it can, to say the least, be a nuisance. In
8817 addition, it can be visually distracting if portions of the
8818 window are cleared, then redrawn step by step. The solution to
8819 this problem is to use an offscreen <em>backing pixmap</em>.
8820 Instead of drawing directly to the screen, we draw to an image
8821 stored in server memory but not displayed, then when the image
8822 changes or new portions of the image are displayed, we copy the
8823 relevant portions onto the screen.
8826 To create an offscreen pixmap, we call the function:
8829 GdkPixmap* gdk_pixmap_new (GdkWindow *window,
8835 The <tt>window</tt> parameter specifies a GDK window that this pixmap
8836 takes some of its properties from. <tt>width</tt> and <tt>height</tt>
8837 specify the size of the pixmap. <tt>depth</tt> specifies the <em>color
8838 depth</em>, that is the number of bits per pixel, for the new window.
8839 If the depth is specified as <tt>-1</tt>, it will match the depth
8843 We create the pixmap in our "configure_event" handler. This event
8844 is generated whenever the window changes size, including when it
8845 is originally created.
8848 /* Backing pixmap for drawing area */
8849 static GdkPixmap *pixmap = NULL;
8851 /* Create a new backing pixmap of the appropriate size */
8853 configure_event (GtkWidget *widget, GdkEventConfigure *event)
8857 gdk_pixmap_destroy(pixmap);
8859 pixmap = gdk_pixmap_new(widget->window,
8860 widget->allocation.width,
8861 widget->allocation.height,
8863 gdk_draw_rectangle (pixmap,
8864 widget->style->white_gc,
8867 widget->allocation.width,
8868 widget->allocation.height);
8874 The call to <tt>gdk_draw_rectangle()</tt> clears the pixmap
8875 initially to white. We'll say more about that in a moment.
8878 Our exposure event handler then simply copies the relevant portion
8879 of the pixmap onto the screen (we determine the area we need
8880 to redraw by using the event->area field of the exposure event):
8883 /* Refill the screen from the backing pixmap */
8885 expose_event (GtkWidget *widget, GdkEventExpose *event)
8887 gdk_draw_pixmap(widget->window,
8888 widget->style->fg_gc[GTK_WIDGET_STATE (widget)],
8890 event->area.x, event->area.y,
8891 event->area.x, event->area.y,
8892 event->area.width, event->area.height);
8898 We've now seen how to keep the screen up to date with our pixmap, but
8899 how do we actually draw interesting stuff on our pixmap? There are a
8900 large number of calls in GTK's GDK library for drawing on
8901 <em>drawables</em>. A drawable is simply something that can be drawn
8902 upon. It can be a window, a pixmap, or a bitmap (a black and white
8903 image). We've already seen two such calls above,
8904 <tt>gdk_draw_rectangle()</tt> and <tt>gdk_draw_pixmap()</tt>. The
8909 gdk_draw_rectangle ()
8918 gdk_draw_segments ()
8921 See the reference documentation or the header file
8922 <tt><gdk/gdk.h></tt> for further details on these functions.
8923 These functions all share the same first two arguments. The first
8924 argument is the drawable to draw upon, the second argument is a
8925 <em>graphics context</em> (GC).
8928 A graphics context encapsulates information about things such as
8929 foreground and background color and line width. GDK has a full set of
8930 functions for creating and modifying graphics contexts, but to keep
8931 things simple we'll just use predefined graphics contexts. Each widget
8932 has an associated style. (Which can be modified in a gtkrc file, see
8933 the section GTK's rc file.) This, among other things, stores a number
8934 of graphics contexts. Some examples of accessing these graphics
8938 widget->style->white_gc
8939 widget->style->black_gc
8940 widget->style->fg_gc[GTK_STATE_NORMAL]
8941 widget->style->bg_gc[GTK_WIDGET_STATE(widget)]
8944 The fields <tt>fg_gc</tt>, <tt>bg_gc</tt>, <tt>dark_gc</tt>, and
8945 <tt>light_gc</tt> are indexed by a parameter of type
8946 <tt>GtkStateType</tt> which can take on the values:
8953 GTK_STATE_INSENSITIVE
8956 For instance, the for <tt/GTK_STATE_SELECTED/ the default foreground
8957 color is white and the default background color, dark blue.
8960 Our function <tt>draw_brush()</tt>, which does the actual drawing
8961 on the screen, is then:
8964 /* Draw a rectangle on the screen */
8966 draw_brush (GtkWidget *widget, gdouble x, gdouble y)
8968 GdkRectangle update_rect;
8970 update_rect.x = x - 5;
8971 update_rect.y = y - 5;
8972 update_rect.width = 10;
8973 update_rect.height = 10;
8974 gdk_draw_rectangle (pixmap,
8975 widget->style->black_gc,
8977 update_rect.x, update_rect.y,
8978 update_rect.width, update_rect.height);
8979 gtk_widget_draw (widget, &update_rect);
8983 After we draw the rectangle representing the brush onto the pixmap,
8984 we call the function:
8987 void gtk_widget_draw (GtkWidget *widget,
8988 GdkRectangle *area);
8991 which notifies X that the area given by the <tt>area</tt> parameter
8992 needs to be updated. X will eventually generate an expose event
8993 (possibly combining the areas passed in several calls to
8994 <tt>gtk_widget_draw()</tt>) which will cause our expose event handler
8995 to copy the relevant portions to the screen.
8998 We have now covered the entire drawing program except for a few
8999 mundane details like creating the main window. The complete
9000 source code is available from the location from which you got
9001 this tutorial, or from:
9003 <htmlurl url="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial"
9004 name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial">
9007 <!-- ----------------------------------------------------------------- -->
9008 <sect1> Adding XInput support
9012 It is now possible to buy quite inexpensive input devices such
9013 as drawing tablets, which allow drawing with a much greater
9014 ease of artistic expression than does a mouse. The simplest way
9015 to use such devices is simply as a replacement for the mouse,
9016 but that misses out many of the advantages of these devices,
9020 <item> Pressure sensitivity
9021 <item> Tilt reporting
9022 <item> Sub-pixel positioning
9023 <item> Multiple inputs (for example, a stylus with a point and eraser)
9026 For information about the XInput extension, see the <htmlurl
9027 url="http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html"
9028 name="XInput-HOWTO">.
9031 If we examine the full definition of, for example, the GdkEventMotion
9032 structure, we see that it has fields to support extended device
9036 struct _GdkEventMotion
9048 GdkInputSource source;
9053 <tt/pressure/ gives the pressure as a floating point number between
9054 0 and 1. <tt/xtilt/ and <tt/ytilt/ can take on values between
9055 -1 and 1, corresponding to the degree of tilt in each direction.
9056 <tt/source/ and <tt/deviceid/ specify the device for which the
9057 event occurred in two different ways. <tt/source/ gives some simple
9058 information about the type of device. It can take the enumeration
9068 <tt/deviceid/ specifies a unique numeric ID for the device. This can
9069 be used to find out further information about the device using the
9070 <tt/gdk_input_list_devices()/ call (see below). The special value
9071 <tt/GDK_CORE_POINTER/ is used for the core pointer device. (Usually
9074 <sect2> Enabling extended device information
9077 To let GTK know about our interest in the extended device information,
9078 we merely have to add a single line to our program:
9081 gtk_widget_set_extension_events (drawing_area, GDK_EXTENSION_EVENTS_CURSOR);
9084 By giving the value <tt/GDK_EXTENSION_EVENTS_CURSOR/ we say that
9085 we are interested in extension events, but only if we don't have
9086 to draw our own cursor. See the section <ref
9087 id="sec_Further_Sophistications" name="Further Sophistications"> below
9088 for more information about drawing the cursor. We could also
9089 give the values <tt/GDK_EXTENSION_EVENTS_ALL/ if we were willing
9090 to draw our own cursor, or <tt/GDK_EXTENSION_EVENTS_NONE/ to revert
9091 back to the default condition.
9094 This is not completely the end of the story however. By default,
9095 no extension devices are enabled. We need a mechanism to allow
9096 users to enable and configure their extension devices. GTK provides
9097 the InputDialog widget to automate this process. The following
9098 procedure manages an InputDialog widget. It creates the dialog if
9099 it isn't present, and raises it to the top otherwise.
9103 input_dialog_destroy (GtkWidget *w, gpointer data)
9105 *((GtkWidget **)data) = NULL;
9109 create_input_dialog ()
9111 static GtkWidget *inputd = NULL;
9115 inputd = gtk_input_dialog_new();
9117 gtk_signal_connect (GTK_OBJECT(inputd), "destroy",
9118 (GtkSignalFunc)input_dialog_destroy, &inputd);
9119 gtk_signal_connect_object (GTK_OBJECT(GTK_INPUT_DIALOG(inputd)->close_button),
9121 (GtkSignalFunc)gtk_widget_hide,
9122 GTK_OBJECT(inputd));
9123 gtk_widget_hide ( GTK_INPUT_DIALOG(inputd)->save_button);
9125 gtk_widget_show (inputd);
9129 if (!GTK_WIDGET_MAPPED(inputd))
9130 gtk_widget_show(inputd);
9132 gdk_window_raise(inputd->window);
9137 (You might want to take note of the way we handle this dialog. By
9138 connecting to the "destroy" signal, we make sure that we don't keep a
9139 pointer to dialog around after it is destroyed - that could lead to a
9143 The InputDialog has two buttons "Close" and "Save", which by default
9144 have no actions assigned to them. In the above function we make
9145 "Close" hide the dialog, hide the "Save" button, since we don't
9146 implement saving of XInput options in this program.
9148 <sect2> Using extended device information
9151 Once we've enabled the device, we can just use the extended
9152 device information in the extra fields of the event structures.
9153 In fact, it is always safe to use this information since these
9154 fields will have reasonable default values even when extended
9155 events are not enabled.
9158 Once change we do have to make is to call
9159 <tt/gdk_input_window_get_pointer()/ instead of
9160 <tt/gdk_window_get_pointer/. This is necessary because
9161 <tt/gdk_window_get_pointer/ doesn't return the extended device
9165 void gdk_input_window_get_pointer (GdkWindow *window,
9172 GdkModifierType *mask);
9175 When calling this function, we need to specify the device ID as
9176 well as the window. Usually, we'll get the device ID from the
9177 <tt/deviceid/ field of an event structure. Again, this function
9178 will return reasonable values when extension events are not
9179 enabled. (In this case, <tt/event->deviceid/ will have the value
9180 <tt/GDK_CORE_POINTER/).
9182 So the basic structure of our button-press and motion event handlers,
9183 doesn't change much - we just need to add code to deal with the
9184 extended information.
9188 button_press_event (GtkWidget *widget, GdkEventButton *event)
9190 print_button_press (event->deviceid);
9192 if (event->button == 1 && pixmap != NULL)
9193 draw_brush (widget, event->source, event->x, event->y, event->pressure);
9199 motion_notify_event (GtkWidget *widget, GdkEventMotion *event)
9203 GdkModifierType state;
9206 gdk_input_window_get_pointer (event->window, event->deviceid,
9207 &x, &y, &pressure, NULL, NULL, &state);
9212 pressure = event->pressure;
9213 state = event->state;
9216 if (state & GDK_BUTTON1_MASK && pixmap != NULL)
9217 draw_brush (widget, event->source, x, y, pressure);
9223 We also need to do something with the new information. Our new
9224 <tt/draw_brush()/ function draws with a different color for
9225 each <tt/event->source/ and changes the brush size depending
9229 /* Draw a rectangle on the screen, size depending on pressure,
9230 and color on the type of device */
9232 draw_brush (GtkWidget *widget, GdkInputSource source,
9233 gdouble x, gdouble y, gdouble pressure)
9236 GdkRectangle update_rect;
9240 case GDK_SOURCE_MOUSE:
9241 gc = widget->style->dark_gc[GTK_WIDGET_STATE (widget)];
9243 case GDK_SOURCE_PEN:
9244 gc = widget->style->black_gc;
9246 case GDK_SOURCE_ERASER:
9247 gc = widget->style->white_gc;
9250 gc = widget->style->light_gc[GTK_WIDGET_STATE (widget)];
9253 update_rect.x = x - 10 * pressure;
9254 update_rect.y = y - 10 * pressure;
9255 update_rect.width = 20 * pressure;
9256 update_rect.height = 20 * pressure;
9257 gdk_draw_rectangle (pixmap, gc, TRUE,
9258 update_rect.x, update_rect.y,
9259 update_rect.width, update_rect.height);
9260 gtk_widget_draw (widget, &update_rect);
9264 <sect2> Finding out more about a device
9267 As an example of how to find out more about a device, our program
9268 will print the name of the device that generates each button
9269 press. To find out the name of a device, we call the function:
9272 GList *gdk_input_list_devices (void);
9275 which returns a GList (a linked list type from the glib library)
9276 of GdkDeviceInfo structures. The GdkDeviceInfo strucure is defined
9280 struct _GdkDeviceInfo
9284 GdkInputSource source;
9294 Most of these fields are configuration information that you
9295 can ignore unless you are implemented XInput configuration
9296 saving. The we are interested in here is <tt/name/ which is
9297 simply the name that X assigns to the device. The other field
9298 that isn't configuration information is <tt/has_cursor/. If
9299 <tt/has_cursor/ is false, then we we need to draw our own
9300 cursor. But since we've specified <tt/GDK_EXTENSION_EVENTS_CURSOR/,
9301 we don't have to worry about this.
9304 Our <tt/print_button_press()/ function simply iterates through
9305 the returned list until it finds a match, then prints out
9306 the name of the device.
9310 print_button_press (guint32 deviceid)
9314 /* gdk_input_list_devices returns an internal list, so we shouldn't
9315 free it afterwards */
9316 tmp_list = gdk_input_list_devices();
9320 GdkDeviceInfo *info = (GdkDeviceInfo *)tmp_list->data;
9322 if (info->deviceid == deviceid)
9324 printf("Button press on device '%s'\n", info->name);
9328 tmp_list = tmp_list->next;
9333 That completes the changes to ``XInputize'' our program. As with
9334 the first version, the complete source is available at the location
9335 from which you got this tutorial, or from:
9337 <htmlurl url="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial"
9338 name="http://www.msc.cornell.edu/~otaylor/gtk-gimp/tutorial">
9341 <sect2> Further sophistications <label id="sec_Further_Sophistications">
9344 Although our program now supports XInput quite well, it lacks some
9345 features we would want in a full-featured application. First, the user
9346 probably doesn't want to have to configure their device each time they
9347 run the program, so we should allow them to save the device
9348 configuration. This is done by iterating through the return of
9349 <tt/gdk_input_list_devices()/ and writing out the configuration to a
9353 To restore the state next time the program is run, GDK provides
9354 functions to change device configuration:
9357 gdk_input_set_extension_events()
9358 gdk_input_set_source()
9359 gdk_input_set_mode()
9360 gdk_input_set_axes()
9364 (The list returned from <tt/gdk_input_list_devices()/ should not be
9365 modified directly.) An example of doing this can be found in the
9366 drawing program gsumi. (Available from <htmlurl
9367 url="http://www.msc.cornell.edu/~otaylor/gsumi/"
9368 name="http://www.msc.cornell.edu/~otaylor/gsumi/">) Eventually, it
9369 would be nice to have a standard way of doing this for all
9370 applications. This probably belongs at a slightly higher level than
9371 GTK, perhaps in the GNOME library.
9374 Another major ommission that we have mentioned above is the lack of
9375 cursor drawing. Platforms other than XFree86 currently do not allow
9376 simultaneously using a device as both the core pointer and directly by
9377 an application. See the <url
9378 url="http://www.msc.cornell.edu/~otaylor/xinput/XInput-HOWTO.html"
9379 name="XInput-HOWTO"> for more information about this. This means that
9380 applications that want to support the widest audience need to draw
9384 An application that draws it's own cursor needs to do two things:
9385 determine if the current device needs a cursor drawn or not, and
9386 determine if the current device is in proximity. (If the current
9387 device is a drawing tablet, it's a nice touch to make the cursor
9388 disappear when the stylus is lifted from the tablet. When the
9389 device is touching the stylus, that is called "in proximity.")
9390 The first is done by searching the device list, as we did
9391 to find out the device name. The second is achieved by selecting
9392 "proximity_out" events. An example of drawing one's own cursor is
9393 found in the 'testinput' program found in the GTK distribution.
9395 <!-- ***************************************************************** -->
9396 <sect>Tips For Writing GTK Applications
9397 <!-- ***************************************************************** -->
9400 This section is simply a gathering of wisdom, general style guidelines and hints to
9401 creating good GTK applications. It is totally useless right now cause it's
9402 only a topic sentence :)
9404 Use GNU autoconf and automake! They are your friends :) I am planning to
9405 make a quick intro on them here.
9407 <!-- ***************************************************************** -->
9409 <!-- ***************************************************************** -->
9412 This document, like so much other great software out there, was created for
9413 free by volunteers. If you are at all knowledgeable about any aspect of GTK
9414 that does not already have documentation, please consider contributing to
9417 If you do decide to contribute, please mail your text to Tony Gale,
9418 <tt><htmlurl url="mailto:gale@gtk.org"
9419 name="gale@gtk.org"></tt>. Also, be aware that the entirety of this
9420 document is free, and any addition by yourself must also be free. That is,
9421 people may use any portion of your examples in their programs, and copies
9422 of this document may be distributed at will etc.
9426 <!-- ***************************************************************** -->
9428 <!-- ***************************************************************** -->
9430 I would like to thank the following for their contributions to this text.
9433 <item>Bawer Dagdeviren, <tt><htmlurl url="mailto:chamele0n@geocities.com"
9434 name="chamele0n@geocities.com"></tt> for the menus tutorial.
9436 <item>Raph Levien, <tt><htmlurl url="mailto:raph@acm.org"
9437 name="raph@acm.org"></tt>
9438 for hello world ala GTK, widget packing, and general all around wisdom.
9439 He's also generously donated a home for this tutorial.
9441 <item>Peter Mattis, <tt><htmlurl url="mailto:petm@xcf.berkeley.edu"
9442 name="petm@xcf.berkeley.edu"></tt> for the simplest GTK program..
9443 and the ability to make it :)
9445 <item>Werner Koch <tt><htmlurl url="mailto:werner.koch@guug.de"
9446 name="werner.koch@guug.de"></tt> for converting the original plain text to
9447 SGML, and the widget class hierarchy.
9449 <item>Mark Crichton <tt><htmlurl url="mailto:crichton@expert.cc.purdue.edu"
9450 name="crichton@expert.cc.purdue.edu"></tt> for the menu factory code, and
9451 the table packing tutorial.
9453 <item>Owen Taylor <tt><htmlurl url="mailto:owt1@cornell.edu"
9454 name="owt1@cornell.edu"></tt> for the EventBox widget section (and
9455 the patch to the distro). He's also responsible for the selections code and
9456 tutorial, as well as the sections on writing your own GTK widgets, and the
9457 example application. Thanks a lot Owen for all you help!
9459 <item>Mark VanderBoom <tt><htmlurl url="mailto:mvboom42@calvin.edu"
9460 name="mvboom42@calvin.edu"></tt> for his wonderful work on the Notebook,
9461 Progress Bar, Dialogs, and File selection widgets. Thanks a lot Mark!
9462 You've been a great help.
9464 <item>Tim Janik <tt><htmlurl url="mailto:timj@psynet.net"
9465 name="timj@psynet.net"></tt> for his great job on the Lists Widget.
9468 <item>Rajat Datta <tt><htmlurl url="mailto:rajat@ix.netcom.com"
9469 name="rajat@ix.netcom.com"</tt> for the excellent job on the Pixmap tutorial.
9471 <item>Michael K. Johnson <tt><htmlurl url="mailto:johnsonm@redhat.com"
9472 name="johnsonm@redhat.com"></tt> for info and code for popup menus.
9476 And to all of you who commented and helped refine this document.
9480 <!-- ***************************************************************** -->
9481 <sect> Tutorial Copyright and Permissions Notice
9482 <!-- ***************************************************************** -->
9485 The GTK Tutorial is Copyright (C) 1997 Ian Main.
9487 Copyright (C) 1998 Tony Gale.
9489 Permission is granted to make and distribute verbatim copies of this
9490 manual provided the copyright notice and this permission notice are
9491 preserved on all copies.
9492 <P>Permission is granted to copy and distribute modified versions of
9493 this document under the conditions for verbatim copying, provided that
9494 this copyright notice is included exactly as in the original,
9495 and that the entire resulting derived work is distributed under
9496 the terms of a permission notice identical to this one.
9497 <P>Permission is granted to copy and distribute translations of this
9498 document into another language, under the above conditions for modified
9500 <P>If you are intending to incorporate this document into a published
9501 work, please contact the maintainer, and we will make an effort
9502 to ensure that you have the most up to date information available.
9503 <P>There is no guarentee that this document lives up to its intended
9504 purpose. This is simply provided as a free resource. As such,
9505 the authors and maintainers of the information provided within can
9506 not make any guarentee that the information is even accurate.