# Glade Turbo-Start

Copyright © 2000 by Compaq Computer Corporation

# 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>`).