%ISOnum; Gtk--"> Gtk"> GNU"> C++"> C"> %examplelist; ]> Studrer nat MarcusBrinkmann Marcus studies mathematic and collects experiences with Linux since early 1996. TeroPulkkinen Tero maintains and develops >kmm;. A comprehensive and easy understandable guide to the upcoming graphical user interface >kmm;. 0.1 June 1998 M.B. Initial release. 1998Marcus Brinkmann Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to process this file through TeX and other text processing systems (for example DSSSL engines) and print the results, provided the printed document carries copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the copyright holder. The example program files are in the Public Domain. The following address is for your information only.

Free Software Foundation, Inc. 59 Temple Place - Suite 330 Boston, MA 02111-1307 USA

With Linux, a great variety of applications are accesible at no for low costs, and many of them are of high quality. Unfortunately, the lack of documentation is in high contrast to this. The reasons are easy to see: For most developers, programming is a lot more fun than explaining the apparently obvious. For me, programming in &cxx; using the >kmm; environment is new and far from obvious, and I hope that laying down the basic principles I understood along the way will help me to clear my mind and help others to understand it more easily. If you have corrections, remarks, answers or questions about this document, please feel free to contact me. My address is:

Marcus Brinkmann Marcus.Brinkmann@ruhr-uni-bochum.de

Today, software can interact in many ways with the user, and it is not an easy task for the programmer to make a decision which input and output devices he should support and which not. Standards and abstract interfaces can help a lot to make this decision less important, because many devices can be used in a unique way, at least from the programmers point of view. Under Linux, for example, there is no need to bother about data storage devices, because the kernel provides a filesystem as an abstract interface and a library provides a clean wy to access the file system. However, there are still enough forms of output that differ in a more fundamental way. For example, it is likely to be of some importance if the output consists only of text (and with text I mean a stream of characters encoded by a standard like ANSI), or if the output is graphical (when it consists of pixel). The situation becomes even more confusing when the programmer has to write a user interface for interactive communication with the user. There are a lot of input devices available, beginning with a variety of keyboards, mices, pads and not ending with speak recognition. Also the programmer can make use of different ways to present the possibilities, in which the user can control the application. There are standard protocols for input and output devices, and programmers can make use of them to be independent of the actual situation of input and output devices. However, there are several libraries available that provide a consistent graphical user interface (GUI). It is desirable that every program uses the same user interface, to make the situation less confusing for the user, but the current situation is far from this ideal situation. To write a extensible, portable and consistent user interface of high quality, that can be used to write X applications in a comfortable way, is the goal of the >k; project. It is written in and for &c;, and many features known from object oriented programming languages had to be reimplemented in &c;. >kmm; provides a wrapper around the >k; to be used in &cxx; and has the advantages of a typesafe environment (even for signals) and integrated object oriented capabilities like inheritance to extend the capabilities of >k;. There are some things you need before you can even start to work with >kmm;, but there are also some things you will need to learn side by side with >kmm; if you don't already know them, or you will hardly succeed writing good software, regardless what tools or libraries you use. But be careful and don't take the words in this chapter too literally. It is unlikely that I really know what exactly the requirements are. Free software is evolving fast at the moment, and facts are outdated after a short time. For this reason, some requirements will not spelled out precise, but intentionally be kept vague. Please check the latest documentation that comes with the software package for newest information. You need a platform that is supported by Gtk, a complete Gtk installation and >kmm;. Probably the distribution you use will provide binary packages. Then all you have to do is to install the appropriate packages for development with >k; and >kmm;. If you have to build the package by yourself for some reason, get the latest source packages per anonymous ftp. Thanks to autoconf, building and installing should be easy. After building and installing the libraries, you can link them in applications that make use of >kmm;. Note that the name of the >kmm; library will be libgtkmm, because dashes in library names may be confusing to the system tools. Furthermore, you need a working &cxx; compiler. A good compiler is gcc, the &gnu; &c;/&cxx; compiler. You need to know how you can compile and link a program you have written in your environment. On a Linux platform, for example, you can compile and link a program stardust.cc with gcc with one command: $ g++ -o stardust startdust.cc -lgtkmm `gtk-config --cflags` `gtk-config libs` However, the last part is only necessary if your system does not handle inter-dependencies between shared libraries correctly. On some systems, you can live without the call for gtk-config libs`. I need more informations here. ZippyKids, the seven basic food groups are GUM, PUFF PASTRY, PIZZA, PESTICIDES, ANTIBIOTICS, NUTRA-SWEET and MILK DUDS!! There is a smallest possible &cxx; program that uses >kmm;. Please consider the following code: We can already change some properties of the helloWorldWindow, for example the title string or the minimum size. For example, the following body will change both at once: Gtk_Window helloWorldWindow; helloWorldWindow.set_title("Hello, world!"); helloWorldWindow.set_usize(200,20); helloWorldWindow.show(); The Gtk_Window class provides a method set_title(char *) to change the title of the window. But if you check the header file or documentation, you will find out that Gtk_Window does not provide a method set_usize(gint width, gint height), that sets the size of the widget. set_usize is provided by Gtk_Widget, and Gtk_Window is a class derived from Gtk_Widget. You should always remember that you can also use member methods from parent classes to change the proberties of your >kmm; objects. The way your window instance is handled by the window manager can be changed by a variable of type GtkWindowType given to the constructor of Gtk_Window. There are three possible values, GTK_WINDOW_TOPLEVEL (the default), GTK_WINDOW_DIALOG and GTK_WINDOW_POPUP. To find out what they are doing, change line 7 in the example to something similar to: Gtk_Window helloWorldWindow(GTK_WINDOW_TOPLEVEL); and then replace GTK_WINDOW_TOPLEVEL with one of the other two possibilities. You will see, that windows of the type GTK_WINDOW_TOPLEVEL are fully handled by the window manager. Further more you will see that windows of type GTK_WINDOW_DIALOG are missing some handles (resizing and closing buttons for example) and that windows of type GTK_WINDOW_POPUP are not handled by the window manager at all (no border, no buttons). Now let's come to another >kmm; object, the widget class Gtk_Label. The constructor requests a const char* that contains the text of the label. Consider this example program: &label-widget; Most parts of this program are already explained, only lines 7, 8 and 11 are new. If you compile and run this example, you won't see a window that is set to the default size of 200x200, but a window that has exactly the size needed to contain the text "Hello, world!". Normally, a Widget will have a default size to fit exactly the child widget it contains. A widget can be added to the window with the member method add(Gtk_Widget*). Because this requires a pointer to the widget to be added, we give the pointer of the Gtk_Label widget as parameter. Note that add() is a member method of class Gtk_Container, from which Gtk_Window is derived, not from Gtk_Window itself. You can use this procedure to add a widget to every container, not only to a window, as you will see later. As already said, we have to make the label visible with the show() member method. Note that we can first show() the label, and then the window. If you change the order, you will first see the empty window and you can watch how the label will be drawn. In most cases it is preferable to draw the widget internally, and then as the last step make the window visible. The class Gtk_Label has two member methods, set(const gchar* str) and get(gchar** str), so you can change the label and see what it reads. Please remember that the Gtk_Label is derived from other classes, and you can use member methods from parent classes to change further properties of Gtk_Label. For example, you can change the minimum size of the label with the set_usize(gint, gint) member method of the Gtk_Widget class. Labels are quite boring, because they are passive. If you want to interact with the user, you most certainly want to provide buttons in your application. For this purpose, a Gtk_Button widget class is available similar to Gtk_Label. But the Gtk_Button class is more complex, because it is a container (it is derived from the Gtk_Container class), so you can add a label to it or a small graphic or whatever you want. Widgets are added to a button in the same way they are added to a window, with the member method add(Gtk_Widget *). If you just want to add a label to a Gtk_Button container, you can give the text string to the Gtk_Button constructor. This is a convenient and common abbreviation. This means, the following pieces of code are aequivalent: Gtk_Label someLabel("Hello, world!"); someLabel.show(); Gtk_Button someButton; someButton.add(&someLabel); someButton.show(); is the hard way to achieve: Gtk_Button someButton("Hello, world!"); someButton.show(); There is currently no way to access the label created by Gtk_Button(const gchar*), so you have to use the more verbose form if you want to work with it, for example, if you want to change the text of the button. Change the "Hello, world!" example to use a button instead of a label and try to run it. You will see that the color of button changes if you move the mouse pointer to the button and if you click the button. But nothing else happens. It is possible to make something happen, and this is the purpose of signals. Signals are emitted by >kmm; whenever something interesting happens, for example when a window was resized or a button was pressed. You can connect to those signals, this means, you can attach a function to the queue of functions which will be called whenever a signal is emitted. You can attach several functions to one and the same signal, and you can attach the same functions to multiple signals. However, the return value and the arguments of the function have to match the arguments and return value of the signal. Consider the following program that is a long version of the exercise in the previous section: &signal-1; Note the absence of the show() call for the Gtk_Label, Gtk_Button and Gtk_Window element. They are replaced by a single call of the member method show_all() of the Gtk_Window instance helloWorldWindow. show_all() is a useful and common abbreviation, it calls show() for the widget itself and all elements it contains. show() and show_all() will be discussed more thoroughly later in this tutorial, when we speak about containers. We want to make something happen whenever the button is pressed. For example, we want to change the text of the label (and this is the reason why we didn't gave the text to the constructor of the button). To be able to do this, >kmm; has to notice us when the button is pressed. It does so by making a function call. Well, it is a bit more complex in reality, but for now it is sufficient to think of signals as function calls that are done by >kmm; as reaction to an event. There is only one thing left to do for our program, it has to tell >kmm; what function should be called when which action is taken on which element. This is done by connect_to_function. To try it, please add the following function to the example above, and also add the connect_to_function call to the main function. 2a static void changeLabel(Gtk_Label& theLabel) 2b { 2c static bool flag=true; 2d 2e flag = !flag; 2f flag ? theLabel.set("Bye, bye!") 2g : theLabel.set("Hello, World!"); 2h } 11a connect_to_function(helloWorldButton.clicked, &changeLabel, helloWorldLabel); changeLabel uses a static variable of type boolean to store the current status of the label (we could also query it with the get member method of Gtk_Label, but this would require a string comparison, a useless complication in this small example) and toggles the text of the label when called. The connect_to_function call requires some explanation. Usually, connect_to_function takes two arguments, the first is the signal you want connect to, and the second is the function you want connect to the signal. An optional third argument will be passed on to the connected function whenever the signal is emitted. In our example, the signal helloWorldButton->clicked is emitted whenever the button is clicked (i.e. pressed and released) and changeLabel(helloWorldLabel) is called. If the third argument of connect_to_function is omitted, no argument will be passed on. You can connect as many function calls to a signal as you like, they are called one after another. In addition, you can not nly connect function calls to a signal, but also member methods of class instances and even other signals. Signals control the flow of an interactive program. Until now, every Gtk_Container instance only had one Gtk_Widget instance inside (for example, a window with one label in it). Obviously, this is not sufficient for most cases. The naive way to add a second label probably would be something like the following: &packaging-1; Please try to compile and run this example. Are you surprised? You will see exactly the same output as if the lines 9 and 13 would not be there. Swapping lines 12 and 13 will only show the other text "Bye, world!", but not "Hello, world!". Although this does not make sense at the first glance, you will soon find out why there is a strong reason for this behaviour. It is all about placement. There is a sensible default for the placement of a single widget inside a container (it is centered), there is no obvious preference for the placement of more than one widget. They could be placed vertically or horizontally, left or right bounded or centered. The placement could also be different for every widget, for example some at the top of the container and others on the right. As placement of widgets is such a complex task, there are many different ways to do it. Therefore it is forbidden to place more than one object in a container, and >k; will complain with an error message at run time. The easiest way to place widgets is to place them in a row (horizontally) or in a column (vertically). For this purpose there are two classes provided by >kmm;, the Gtk_HBox and Gtk_VBox. As both classes provide a very similar functionality, they are derived from a common base, the Gtk_Box class, which is never directly used. For the following explanations, the Gtk_HBox is used as an example, but the same facts are true for the Gtk_VBox as well, because the interface is provided by the Gtk_Box class, not by one of the specializations. The main idea is to add a box to the container, and then to add the widgets to the box. For this purpose, two methods are provided by Gtk_Box, pack_start(Gtk_Widget*) and pack_end(Gtk_Widget*). pack_start will add widgets starting at the beginning of the box in direction to the end of it, whereas pack_end will add widgets starting at the end of the box in direction to the beginning. Therefore the order in which the methods are called is important. A simple example shows both ways to add widgets to a box. &packaging-2; If you try this example, you should resize the window to force a different placement. As a Gtk_HBox has a default size to match the sum of the default sizes of the widgets it contains, you will not see the different placement of the widgets until resizing. Please note the different order of the pack_start and pack_end calls in lines 14 to 17. A Gtk_Box is an unvisible box, that means, it does not add anything visible to the container it is added to. But nevertheless you have to call show() to make the widgets visible it contains. show() makes a widget only visible to its direct parent. If it should show up in the window, all widgets on the way down to it have to be visible, too. This is an excellent example why show_all() is indeed a great convenience for the programmer. You can nest multiple horizontal and vertical boxes to achieve a finer control on placement. You can also add other widgets to a box than labels. You can adjust the placement of the elements in a box, but this is subject of a later section in this tutorial. Menus are an essential part of every user application. They provide fast access to the main functionalities of the program. Menus are organized in submenus, which are accessed by a menu bar, usually placed at the top of the window. Menu items are connected to functions by signals: If a user selects an item in a menu, an event occures and the appropriate signal is emitted. You can connect one or more functions to this signal to make something happen through the menu. A common way to respond to a menu selection is to open a dialog window, but also direct actions may be appropriate. You can build menus directly from the >kmm; widgets, but this is inconvenient as a lot of overhead is involved in implementing the necessary objects. For the special case of menus, >kmm; provides a better way to realize the set of widgets needed. This system is called MenuFactory. EMPTY