# CHAPTER 1: Utilities for Empress GUI Builder

## 1.1 Utilities Available

The utilities available for Empress GUI Builder are the following:

`empginit` | To initialize an Empress database for use with Empress GUI Builder.
`empgui` | To execute Empress GUI Builder applications, or to invoke the Empress GUI Builder development environment, for the creation of GUI applications.
`empguicc` | To compile C programs using the Empress C API to access Empress GUI Builder objects.
`empgprt` | To print the contents of Empress GUI Builder applications and modules.

## 1.2 Initializing a Database for Empress GUI Builder

An Empress database needs to be initialized by `empginit` before it can be used to contain GUI applications and modules. `empginit` is run from the UNIX shell, with the following usage:

    empginit [-xp] database

If the database specified does not exist, it is created.

The system tables related to Empress GUI Builder are created in the database.

Several example applications are also included.

### 1.2.1 Command Line Options

`-x` | The example applications are not imported.
`-p` | Public access. The `SELECT` and `DISPLAY` privileges are granted to `PUBLIC` on all the GUI system tables. This allows any user to run the applications in the database.

## 1.3 Empress GUI Builder Development Environment

The GUI development environment is a X-Window application which provides a set of tools for creating and manipulating objects in a GUI application. It is started by executing the following command from the UNIX shell:

    empgui [-q] database [application [parameter ...]] [-pcm]

or

    empgui -m [-q] database application [-pcm]

or

    empgui -c [-q] database module [module ...]

or

    empgui -l [-q] database application [application ...]

- The database must have been initialized for use with Empress GUI Builder.
- If only a database name is specified, a banner screen is automatically displayed and removed later. Then the Application Manager screen is displayed.
- If an application name is provided, and options other than `-q` are not specified, the application is executed. In this case, parameters (if any) for the application must be specified after the application name. The GUI development environment is not called.
- If the `-m` option is specified, then an application name must be specified, without parameters.
- If the `-c` option is specified, then one or more module name(s) must be specified.
- If the `-l` option is specified, then one or more application name(s) must be specified.

### 1.3.1 Command Line Options

`-c` | Compile the specified modules even if they are already up-to-date.
`-l` | Link the modules of the specified application(s). Modules which are not up-to-date are compiled before linking.
`-m` | Skip the Application Manager screen and go directly to the Application Module Manager screen for the specified application.
`-q` | Quiet mode. If starting the GUI development environment, the banner screen is not displayed. If compiling or linking modules, no message is printed.
`-pcm` | Use private colormap.

## 1.4 Empress GUI Builder Tools

The Empress GUI Builder development environment provides tools to manipulate objects:

Manager screens display lists of entities of the same type, allow creation of new ones and deletion of existing ones.

Property Editor screens allow the attributes of an individual entity to be changed.

Object |  | Manager | Property Editor
Application | Y | Y
Module | Y | Y
Action | Y | Y
Bin | Y | Y
Color | Y | Y
Font | Y | Y
Hypertext | Y | Y
Pixmap | Y | Y
Style | Y | Y
Window | Y | Y
Components | + | +
| Audio field | + | Y
| Cascade button | + | Y
| Field | + | Y
| Hypertext field | + | Y
| Image field | + | Y
| Label | + | Y
| List | + | Y
| Multilist | + | Y
| Option button | + | Y
| Push button | + | Y
| Radio box | + | Y
| Scale | + | Y
| Separator | + | Y
| Toggle button | + | Y
| User-defined object | + | Y

## 1.5 Compiling Empress C API Programs

C programs that use the Empress C API to access GUI objects need to be compiled using `empgcc`.

    empguicc [-esql] [-compilercompiler_name] [cc options] sourcefile.c

             [sourcefile.c ...]

### 1.5.1 Command Line Options

`-esql` | The source files contain embedded SQL statements and have been precompiled by `empesql`, the Empress SQL Precompiler.
`-compiler compiler_name` | Specifies the pathname of the C compiler to use.

`empguicc` will call the default C compiler with the appropriate libraries, and will pass any option that it does not recognize to the C compiler. For example:

    empguicc -o my_exec acttab.c actions.c

The two source files `acttab.c` and `actions.c` are compiled and a GUI executable called `my_exec` is obtained.

For further information on the Empress GUI Builder C API, refer to the Empress GUI Builder: C API manual.

## 1.6 Printing Empress GUI Builder Applications

The utility `empgprt` is used to display the contents of Empress GUI Builder applications.

    empgprt [-w] [-s] database [application [module]]

For each application, `empgprt` prints a tree structure displaying the modules contained in the application, and also the names of actions, bins, hypertext documents, pixmaps and windows contained in the modules.

By default, all the applications and modules contained in the database are printed. To select a specific application, the application's name can be specified after the database name. A specific module can also be specified after the application name.

Both application and module names can be specified by patterns (as used by the Empress SQL `MATCH` operator - see Empress SQL: Reference manual). In this case, they should be quoted to avoid shell expansion.

### 1.6.1 Command Line Options

`-w` | Print the contents of windows. Only the windows contained in the module(s) will be printed, as well as details of the components of the windows.
`-s` | Print the script actions. Only the contents of the script actions contained in the module(s) will be printed.

Examples

Using `empgprt` without any options:

    empgprt database

Output of `empgprt`:
``

`"Example" (application)`
`|- "Example" (shared main module)`
`| |- Actions: Script - "pushbutton_simple"`
`| |- Bins: Menu Bar - "MENU BAR"`
`| | Pulldown - "file"`
`| | Help Menu - "MENU BAR HELP"`
`| |- Hypertexts "example_help"`
`| - Windows "MAINWIN"`
`|- "PUBLIC GENERAL MODULE" (shared external module)`
`|- "PUBLIC HELP MODULE" (external module)`
`- "PUBLIC STYLE MODULE" (shared external module)`
`` ``

`"Images_script" (application)`
`|- "Images_script" (shared main module)`
`| |- Actions: Script - "cleanup"`
`| | "next_pic"`
`| | "prev_pic"`
`| | "select_pic"`
`| |- Bins: Menu Bar - "MENU BAR"`
`| | Pulldown - "file"`
`| | Help Menu - "MENU BAR HELP"`
`| |- Hypertexts "images_help"`
`| - Windows "MAINWIN"`
`|- "PUBLIC GENERAL MODULE" (shared external module)`
`|- "PUBLIC HELP MODULE" (external module)`
`- "PUBLIC STYLE MODULE 4" (shared external module)`

Printing the contents of the windows in modules with name starting with "E", in application "Example":

    empgprt -w database Example "E*"

Output of `empgprt`:

`"Example" (application)`
`|`
`- "Example" (module)`
`|`
`- "MAINWIN" (window)`
`| X: Y: Width: Height:`
`| Initially Hidden: Scroll Bars: Visible Frame:`
`|- Labels`
`| Name: (unnamed) X: 10 Y: 10`
`| Pixmap: "empress_logo"`
`| Name: (unnamed) X: 60 Y: 110`
`| Text: "Do not push button"`
`- Push Buttons`
`Name: (unnamed) X: 110 Y: 210`
`Text: "PUSH HERE"`
`Action: "pushbutton_simple"`

Printing the script actions contained in applications with names starting with "I":

    empgprt -s database "I*"

Output of `empgprt`:

`*** Application: "Images_script" ***`

`Module: "Images_script" Action Name: "cleanup"`
`close "pic";`
`undeclare "pic";`
`close table "pictures";`

`Module: "Images_script" Action Name: "next_pic"`
`fetch next from "pic";`
`if (sqlresult = 0)`
`call empgui_dialog_info ("Next Picture", "No more pictures.");`
`call empgui_objects_set ("MAINWIN", "pic", null);`
`else`
`call empgui_objects_set ("MAINWIN", "pic");`
`end;`

`Module: "Images_script" Action Name: "prev_pic"`
`fetch prior from "pic";`
`if (sqlresult = 0)`
`call empgui_dialog_info ("Previous Picture", "No more pictures.");`
`call empgui_objects_set ("MAINWIN", "pic", null);`
`else`
`call empgui_objects_set ("MAINWIN", "pic");`
`end;`

`Module: "Images_script" Action Name: "select_pic"`
`open table "pictures" read;`
`declare "pic" cursor for select * from "pictures";`
`open "pic";`
`call "next_pic" ();`