# &app; Manual V&manrevision;

2004 2003 Sun Microsystems
2002 2000 Michael Vance
GNOME Documentation Project &legal;

Feedback Information

To report a bug or make a suggestion regarding this application or this documentation, see the GNOME Feedback Page.

Sun GNOME Documentation Team
Sun Microsystems
Michael Vance
GNOME Documentation Project
GNOME Documentation Project
&app; Manual V&manrevision;
&date;

Sun GNOME Documentation Team

GNOME Documentation Project

&app; User Manual V2.0
25 February 2004

Sun GNOME Documentation Team

GNOME Documentation Project

&app; User Manual V1.2
10 Feb 2004

Sun GNOME Documentation Team

GNOME Documentation Project

&app; User Manual V1.1
30 Mar 2002

Michael Vance

GNOME Documentation Project

&app; User Manual V1.0
11 May 2000

Michael Vance

GNOME Documentation Project

This manual describes version &appversion; of &app;.

## Introduction

The Glade application enables you to create graphical user interfaces (GUIs) from the GTK+ and GNOME libraries. Glade enables you to create source code for your GUIs in the following languages:

- Ada

- C

- C++

Glade generates C code by default. You might have to install additional packages to generate code in the other languages.

You can also use Glade in conjunction with libglade to dynamically create GUIs from the XML description file that Glade creates. For large applications, the use of libglade is recommended rather than C code generation.

The GTK+ and GNOME libraries provide an extensive collection of user interface building blocks such as text boxes, dialog labels, numeric entries, check boxes, and menus. These building blocks are called widgets.

Glade enables you to do the following tasks in a simple manner:

- Place widgets correctly in a GUI.

- Assign functionality to the widgets.

You choose widgets from a palette of available widgets, and place the widgets into your project. You edit the widget properties in the Properties window. You also use the Properties window to add connections between your widgets and externally-written code.

You can obtain Glade from the following locations:

Glade download site

  Links are provided on the following Glade download site for various package formats: http://glade.gnome.org/download.html

GNOME CVS

  For information about how to get Glade from the GNOME CVS server, see the GNOME CVS page at the following location: http://developer.gnome.org/tools/cvs.html

Glade features a GNOME support option. However, to use this feature you need to have a recent version of the GNOME desktop environment. If you do not have a recent version of the GNOME desktop environment, you can disable the support feature when you compile Glade. To disable the support feature, include the following option in the compile command: `--disable-gnome`.

## Getting Started

You can start Glade in the following ways:

Command line

  Execute the following command: `glade-2`

Applications menu

  Choose Applications Programming Glade Interface Designer.

When you start Glade, the following windows appear:

Glade consists of the following windows:

Glade window

  The Glade window contains a menubar and a toolbar. You can use either the menubar or the toolbar to work with projects. This manual documents functionality from the menubar. The Glade window also contains a list of the top-level widgets that are defined for the current project.

Palette window

  The Palette window contains the widgets that you can use to build an interface. You add widgets from the Palette window to your project.

Properties window

  The Properties window enables you to manipulate the properties of widgets, such as their size, color, signal masks, and so on.

Widget Tree window

  All widgets in a user interface are organized into the Widget Tree. You can view the path up the tree from a specific widget to the root widget, or top-level widget.

Clipboard

  The Clipboard enables you to remove items from your project, and paste items back into your project.

Project Windows

  These are the windows of the application that you are designing.

## Viewing Glade Windows

You can use the View menu to perform the following actions:

- Display hidden windows.

- Raise obscured windows to the top of the window stack.

### To View the Palette Window

Choose View Show Palette .

### To View the Properties Window

Choose View Show Property Editor .

### To View the Widget Tree

Choose View Show Widget Tree .

### To View the Clipboard

Choose View Show Clipboard .

## Working With Projects

The typical stages in a Glade project are as follows:

Construct the user interface

  Select the widgets that you require from the Palette window. Insert the widgets into your project. Right-click on a widget to view a popup menu from which you can choose to perform actions on that widget.

  Take care when you perform actions on widgets that have children. If you delete the parent widget, you also delete the children.

Refine the widgets

  While you construct the interface, you use the Properties window to manipulate the various settings and dimensions of the widgets.

Build the source code

  When the interface is finished, you save the project and build the source files that generate the user interface. You can then integrate the source code with your project logic. The default language for source code is C.

### To Create a New Project

Perform the following steps to create a new project:

1. Choose Project New .

2. In the Glade dialog box, click OK.

3. In the New Project dialog box, click on the appropriate button to select a new GTK+ project or a new GNOME project.

4. In the Palette window, click on the window widget.

5. You can now add widgets for your application to the new project window. See for more information about how to use widgets to build your application interface.

### To Open an Existing Project

Choose Project Open . An Open Project dialog appears, in which you specify the filename of the project that you want to open.

### To Save a Project

Choose Project Save . If this is the first time you are saving your project, a Project Options dialog appears, containing default values. See for more information about setting project options.

If you have previously specified the project settings, Glade saves your current project without comment.

### To Generate Source Code For Your Project

Choose Project Build . If this is the first time you are saving your project, a Project Options dialog appears, containing default values. See for more information about setting project options.

If you have previously specified the project settings, Glade outputs code without comment.

### To Set Project Options

Choose Project Options . The Project Options dialog appears, containing default values. If you have previously specified the project settings, those settings appear in the Project Options fields. See for more information about setting project options.

### To Exit Glade

Save your project before you exit the application.

To exit Glade, choose Project Quit . Glade asks you if you want to quit the application, but does not query you to save unsaved project data.

## Setting Your Project Options

Use only ASCII characters for names of files and directories in the Project Options dialog. Other systems might use different character encodings for the names of files and directories, which can cause problems. You can set options in the following functional areas in the Project Options dialog:

- General

- C Options

- LibGlade Options

### General

#### Basic Options

Project Directory

  Enter the location of your project in this field. Click on Browse to select a location directory from your file system.

Project Name

  Type the name of your project in this text box. When you edit this information, the program name and project filename change automatically.

Program Name

  Type the name of the executable for your project in this text box. Glade uses this executable to generate code for your project. When you edit this information, the project file changes automatically.

Project File

  Type the filename for your project in this text box. All of your project information is stored in this file.

#### Subdirectories

Source Directory

  Use the text box to specify where you want Glade to build source code for the project.

Pixmaps Directory

  Use the text box to specify where Glade can find any image files that are used in the project.

#### Language

Pick the programming language that you want Glade to use to build source code for the project.

#### Enable Gnome Support

Select this check box if you want Glade to build source code that uses the GNOME libraries.

### C Options

#### General Options

Gettext Support

  Select this option to create code that supports GNU gettext for internationalization.

Set Widget Names

  Select this option to create code to set the names for all widgets. This feature is useful if you intend to use GTK+ calls such as `gtk_widget_path()`.

Backup Source Files

  Select this option to make a backup of all your source files when you build new files.

Gnome Help Support

  Select this option to create code that supports Help in the GNOME desktop environment.

#### File Output Options

Output `main.c` File

  Select this option to output a file named `main.c`, which contains a simple bootstrap. The function called by `main.c` depends on the status of the Enable Gnome Support option:

  Option Status | Called Function
  --- | ---
  Enabled | `gnome_init()`
  Not Enabled | `gtk_init()`

Output Support Functions

  Select this option to output a file named `support.c`, which contains utility functions for various tasks, for example:

  - Create an image file.

  - Look for a widget by name.

Output Build Files

  Select this option to output files to support configuration of your project through `automake` and `autoconf`. This option creates the following files:

  Filename | Description
  --- | ---
  `AUTHORS` | Authorship file for contributors.
  `autogen.sh` | Script for building a configure script.
  `ChangeLog` | Log of changes you have made in the project.
  `configure.in` | Template for building a configure script.
  `Makefile.am` | Automake template for the project.
  `NEWS` | Announcements for new releases.
  `README` | Contains general information about the project.
  `src/Makefile.am` | Automake template for the `src/` directory.
  `stamp-h.in` | Timestamp file.

#### Interface Creation Functions

Source File

  Use the text box to specify the file where you want Glade to store the code for the user interface.

Header File

  Use the text box to specify the name of the file where you want Glade to store function prototypes for the user interface code.

#### Signal Handler & Callback Functions

Source File

  Use the text box to specify the name of the file where you want Glade to store signal handler code.

Header File

  Use the text box to specify the file where you want Glade to store function prototypes for signal handler code.

#### Support Functions

Source File

  Use the text box to specify the file where you want Glade to store support function code.

Header File

  Use the text box to specify the file where you Glade to store function prototypes for the support function code.

### Libglade Options

#### Save Translatable Strings

This option is deprecated. Use intltool instead when you want to translate interfaces designed in Glade.

## Working With Widgets

### To Select Widgets From the Palette Window

You can work with the widgets in the Palette window in the following ways:

Selection mode

  To use selection mode, click on the Selector arrow. The pointer changes to an arrow to indicate that selection mode is active. In this mode, you use the mouse to select widgets in your project. You can then use the Properties window to edit the properties of the widgets. If you hold down the Shift key and repeatedly select a widget, the selection cycles through the widget and all of its parent widgets.

  You can also use the widget context menu to select a widget. Right-click on a widget to open the widget context menu.

  You can add multiple widgets of a specific type from the Palette to your project by holding down the Control key when you select a widget. You need to click on the Selector arrow or another widget in the Palette to return to normal mode.

Widget placement mode

  To use widget placement mode, select a widget in the Palette window. When you select most widgets, the pointer changes to a pointer-plus-cross. You can then place the widget inside containers, top-level widgets, and so on. After you place a widget, the mode returns to selection mode.

Top-level placement mode

  To use top level placement mode, select a defined top-level widget in the Palette window. When you select a top-level widget in the Palette window, the widget appears immediately on your desktop. You can then edit the widget. After you select a top-level widget, the mode returns to selection mode.

### To Organize Widgets In Your Project

You use widget containers, or boxes, to layout and organize widgets in your project window. You can choose the following widget containers from the Palette window:

- Horizontal Box

- Vertical Box

- Table

- Fixed Positions

- Horizontal Button Box

- Vertical Button Box

- Horizontal Panes

- Vertical Panes

- Notebook

- Frame

- Scrolled Window

- Viewport

You can nest boxes to create complex layout structures. When you create horizontal and vertical boxes, Glade asks you how many rows or columns to create initially, though rows and columns can easily be added or deleted later.

When you have created all the boxes you require, you can add specific widgets like labels, buttons, and more complicated widgets into the boxes. Notice that Glade packs widgets into the layout which eliminates a lot of tedious work. The use of boxes enables windows to change size to accommodate different size labels in different languages when the application is localized.

### To Place a Widget on the Clipboard

To remove a widget from a parent and place the widget on the clipboard, select the widget then choose Edit Cut .

### To Copy a Widget to the Clipboard

To copy a widget to the clipboard, select the widget then choose Edit Copy . The original widget remains attached to the parent.

### To Paste a Widget From the Clipboard Into Your Project

To paste a widget that exists on the clipboard into your project, choose Edit Paste .

All widgets must have a unique name within Glade. If you cut a widget, and then paste the widget into your project, then the widget and all of the children of the widget keep their original names. If you copy a widget, or paste the widget multiple times into your project, then Glade generates new names for the widget copies.

### To Delete a Widget

To delete a widget from the parent without moving the widget to the clipboard, select the widget then choose Edit Clear .

## Finding Out More About Widgets

Widgets are grouped into the following categories in the Palette window:

GTK+ Basic

  This category contains frequently-used GTK+ widgets such as windows and labels.

GTK+ Additional

  This category contains widgets such as GtkAlignment, GtkPacker, and GtkCalendar.

Gnome

  This category includes all of the GNOME widgets that Glade supports.

To find out the purpose of a widget in the Palette window, point to the widget to activate a tooltip. For more information about the widgets that Glade supports, see the GTK+ Reference Manual.

## Preferences

### Settings Menu

Show Grid

  Select this option if you want to show a grid when you place a widget in a GtkFixed or GtkLayout container.

Snap to Grid

  Select this option if you want widgets to snap to the grid in a GtkFixed or GtkLayout container.

Show Widget Tooltips

  Select this option to enable the tooltips you have set in your interface. Tooltip display can be a distraction when you are creating an interface within Glade, so you might like to turn them off.

### Grid Options

Horizontal spacing

  Use the spin box to specify the number of pixels to skip horizontally before drawing a line in the grid.

Vertical spacing

  Use the spin box to specify the number of pixels to skip vertically before drawing a line in the grid.

Grid style

  Use the radio buttons to specify whether to draw the grid with dots or lines.

### Snap Options

Horizontal snapping

  Use the check boxes to specify the snap behavior in the grid of the left and right edges of a widget.

Vertical snapping

  Use the check boxes to specify the snap behavior in the grid of the top and bottom edges of a widget.