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]

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

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

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)

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" ();