Xconvers User Guide: Xconvers project

Next Previous Contents

## 3. Xconvers project

Xconvers is a free software project. One of the things I like about writing free software is the exchange of information between people. When writing xconvers, I can take a look at other code for examples, while other people can also benefit from the work I have done.

Let me tell you something about the tools I have used to develop xconvers. Maybe I can get you interested in free software development because we need a lot more hams who want to write free software.

## 3.1 Glade tutorial

Glade is a user interface builder for GTK and Gnome. It allows you to build a program with a few mouseclicks. You can drag widgets (buttons, text, frames, whatever) to a worksheet. Next you have to define events which will interact with the user (for example: clicking on a button). Once you have saved your projects, your task will be to write code which will respond correctly when such an event occurs. In other words: you will have to write the callback function. Here is how the gtk version of glade looks like:

Figure 7. Glade in action

You can see 4 windows. The left one is called the Palette dialog. It contains all available GTK widgets which you can use. I have created the window in the center marked Tutor, by clicking on the left topmost icon, which looks like a little window. The window on the right is the Properties dialog. It is used to set the properties (appearance) of a widget and to add functions to widget events. As you can see, I have used the properties dialog to set the title of the window by changing the entry called Title. Finally, the small top window called Glade, is the main glade window. It contains a list of windows and dialogs which you have created. You use this window to save your project and build the source.

We want the application to exit nicely if we click on the close button of the tutor window (the button marked X in most window managers). In order to do this, we have to add a callback to the window's destroy event:

Figure 8. Tutor properties

We do this by selecting the Signals page of the properties dialog. Click on the button marked ... next to the Signal entry. You will see a list of signals which can be used to interact with the user. Select destroy from the list under GtkObject signals (the last signal in the list). Next, we need to fill in which function should handle this event. Click on the down arrow next to the Handler entry and select gtk_main_quit. You now have created the simplest program possible with GTK. It shows a window when it is started and exits if we click the close button.

It is time to save our project. When you choose a project name, the name for the executable will be automatically filled in. The project will be saved as project.glade. This file describes your user interface in XML. Next, you should write the source code. This will create all the files which are necessary to build the executable. You should run the autogen.sh script and then type make. Your executable will be in the src directory. If you strip it, it will be as small as 7 kB.

This program does nothing sensible, but it can give you a bit of insight into the working of glade. Normally you will make a more complicated user-interface which generated dozens of signals. You will then modify callback.c in the src directory to handle the signal. The glade source code contains a user guide and a more complex example on how to use glade. On the glade web site you can find links to lots of source code developed with glade. Some of them include the XML .glade file, so you can load the user-interface in glade to see how it is build up.

## 3.2 Xconvers code layout

Xconvers has evolved from just over 1000 lines of code in the 0.5alpha1 version to 3000 lines of code in the current version. In order to keep the code readable I had to organize the .c files into modules. Here is a description of every .c file and the functions it contains.

### callbacks.c

> Contains callbacks generated by glade which connect to a widget signal. Functions included handle selection of the menu, opening and closing of the main window and all the dialogs, keypresses in the main window, clicking on OK and Cancel buttons, toggling of checkbuttons and changing text entries.

### color.c

> All about colors: functions for looking up and displaying messages associated with a particular user in the right color. Also has a function which calculates the right color which is looked up in the xconvers preferences file.

### history.c

> Loads and saves the history of the the one-line transmit window and the comboboxes in the open dialog.

### interface.c

> Generated by glade. Sets the properties for every window, dialog and widget and adds signals to a widget.

### main.c

> Glade generated. Does nothing much except initialize gtk and start the main loop.

### net.c

> Network functions. Lets you transmit and receive text, lookup a hostname and connect and disconnect.

### preferences.c

> Functions that lookup and save settings to the xconvers preferences file. Also checks if the .xconvers directory can be created.

### support.c

> Support function supplied by glade. Most functions are used internally by glade. Contains 1 public function called lookup_widget which is used to find the name of a widget in a dialog or window, in case you want to set properties at run time.

### types.h

> Defines a structure where all the xconvers settings are saved, so they are accessible at runtime.

Next Previous Contents