# Glade Turbo-Start

2000
Compaq Computer Corporation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

This is version 1.0 of Glade Turbo-Start.

## Glade Turbo-Start

This is just enough info to get started. I would also recommend reading the Glade FAQ which comes with the distribution and check out the screenshots.

### Building Glade

If you're a Compaq Alpha Linux user like me, you'll need to build Glade for your platform. The `README` and `INSTALL` files that comes with Glade are pretty good. Read them and follow the directions. The `doc` subdirectory also has some helpful files, especially `manual.txt`.

There was one problem that occured while building Glade v0.5.7 for RedHat Linux 6.1 on Alpha. The build failed while creating the natural language support (NLS) stuff in the `po` subdirectory. When NLS was disabled, Glade built OK.

Look for future Alpha Linux distributions to provide Glade pre-built for Alpha.

### Running Glade

If Glade is on your path (if installed into `/usr/local/bin`, for example), then just type `glade` to start running it from the shell.

Glade displays three windows:

- The main Glade window (file/settings/build)

- The Property Editor

- The Palette

Use the Project window to open an exiting project or to create a new one. I would recommend changing some settings in the Project Options dialog which is found under the File menu. For example, you'll probably want to change the Project Directory and the Project Name on the General tabbed page. Program Name and Project File will change accordingly. The C Options tabbed page controls C code generation including the names of certain specific generated files:

- Interface creation functions — (`interface.c`, `interface.h`)

- Signal handler and callback functions — (`callbacks.c`, `callbacks.h`)

- Support functions — (`support.c`, `support.h`)

As noted in the Glade FAQ, your signal handler functions are in the callbacks source files. You should not have to change anything in the interface and support files.

Clicking on the Build button or choosing Build Source Code from the File menu will ask Glade to generate C code.

### The Palette

The Palette displays the widgets that are available for user interface design. They are divided into three categories:

- GTK+ Basic

- GTK+ Additional

- Gnome

The window icon in the upper left corner is the place to start. Click on it to create a new window. Glade will draw the new window and now you can choose other widgets from the Palette and add them to the window.

Glade uses "boxes" to organize and layout widgets. If you intend to add more than one widget to your window (and you probably will!), choose and place boxes in the window. Your choices are:

- Horizontal box

- Vertical box

- Table

- Fixed positions

- Horizontal button box

- Vertical button box

Boxes can be nested to create complex layout structures. When creating horizontal and vertical boxes, you'll be asked how many rows or columns (subdivisions) to create.

Once boxes have been put down, you can add specific widgets like labels, buttons and other, more complicated widgets into the boxes. Notice that Glade "packs" widgets into the layout which eliminates a lot of tedious work. When you select a widget, the Properties window will display its current properties such as the widget's name. The Signals tabbed page within the Property Editor is the place to attach signal handler functions to the widget.

The example project that I created has one window divided into two parts using the Vertical box layout. The top box contains a menu bar and the bottom box is subdivided into (two) left and right parts using a Horizontal box layout. The menu bar contains a File and Help menu with some menu items beneath each menu. The left part of the Horizontal layout contains a scrolled window which, in turn, contains a viewport with a tree widget inside. The right part contains a Notebook widget with three tabbed pages.

The widget tree can be shown choosing Show Widget Tree under the View menu in the main Glade window. The widget tree for my example application has the overall shape:

- Window

  - Vertical Box

    - Menu Bar

    - Horizontal Box

      - Scrolled Window

        - Viewport

          - Tree

      - Notebook

The Menu Bar and Notebook can be expanded further to view individual menus, menu items, pages, etc. The widget tree is good way to browse and examine the way that widgets nest.

### Menu Editor

After placing a Menu Bar widget, use the left button to select the widget. Click the right button on the Menu Bar to get a pop-up menu of commands. Choose the Edit Menu item and Glade will display the Menu Editor. This is where you can create the menu structure for your application.

Click the Add button to add a new menu or menu item. Change the Label and Name field as desired. Label is the text label that will appear in the menu or menu bar. Name will be used to build a signal handler. The Handler field will update as new Name information is entered. The handler name will begin with "on_" and end with "_activate" as in: `on_open_project_activate`. Use the left and right arrows to create levels of menu items. Indentation denotes menu substructure.

Click the Apply button to make the current menu information appear in the edit window. You can play with the menu items to try them out.

### Generating Code

After the window looks the way you want it, click on the Build button to generate code. Glade also generates information for autoconf making it easy to build the application on your platform. The following files and directories are created for a simple project:

- `AUTHORS` — Empty, needed for GNU compliance

- `NEWS` — Empty, needed for GNU compliance

- `README` — Empty, needed for GNU compliance

- `Makefile.am` — Use automake with this file to produce `Makefile.in`

- `acconfig.h` — Autoconf information

- `autogen.sh` — Run this to build the application

- `configure.in` — Needed by autoconf to produce a configure script

- `macros/` — Build related macros (m4)

- `pm.glade` — The Glade project file for the application

- `po/` — Localization (NLS) support files

- `src/` — Application source files

- `stamp-h.h` — Timestamp

The `src` subdirectory contains the source files for the application. Six of these files were mentioned earlier:

- Interface creation functions — (`interface.c`, `interface.h`)

- Signal handler and callback functions — (`callbacks.c`, `callbacks.h`)

- Support functions — (`support.c`, `support.h`)

Glade also generates `main.c`. Glade does *not* overwrite the following files:

- `main.c`

- `callbacks.h`

- `callbacks.c`

Feel free to edit these files. `callbacks.c` contain the stubbed signal handling functions which respond to user actions. This is where you need to hook in your application code.

To prepare to build the application, just enter `autogen.sh` at the shell prompt. Autoconf will create configuration information and makefiles will be generated. Now just enter `make` to actually build the application. Make will recursively work its way through the build process leaving the final executable program in the `src` subdirectory. Run the program and check out your interface!

### Building Confidence

Here are some things to try in order to build confidence with Glade.

Edit `callbacks.c` and add `printf`'s to the signal handler functions. Remake the application, run it, and watch the messages appear as the signal handling functions are invoked in response to widget actions.

Your application window may have been too small as displayed the first time around. (Mine certainly was.) Open the Glade project and click the icon for the window widget in the main Glade window. Go to the Widget tabbed page in the Property Editor. Change the Default Width and Height fields to adjust the size of the application window. Generate C source code again and make the application. Run the application again and congratulate yourself on a job well done!

### What's Next?

It should be possible to get to this point without knowing a lick of GTK+. The next step is to learn more about GTK (especially the more complicated widgets like trees) and start filling out the stubs.

### Authors

Glade was written by Damon Chaplin (damon@ximian.com). This guide was written by Paul J. Drongowski (paul.drongowski@compaq.com). Conversion to DocBook was done by Dan Mueth (d-mueth@uchicago.edu).