CHAPTER 6: User-Defined Objects

Empress GUI Builder provides a component called the user object to the application developer. This object is a drawing area widget which the developer can manipulate and customize using X and Motif function calls.

This user object is useful for expanding the functionality of Empress GUI Builder, and it allows the X developer to incorporate custom widgets into Empress GUI Builder applications. It could be used to draw pie-charts, to display images stored in a custom format, to act as a parent widget to other widgets, etc.

The C API function call to get the widget of a user-defined object is as follows:

gui_status empgui_c_user_get_widget (userobj, &widget)

Once a drawing area widget has been accessed through the C API function call, it could be used for anything the application developer chooses to. One important thing to remember, while using the widget, is that all the initialization of X has already been performed by Empress GUI Builder. If the application tries to re-initialize X, it would fail.

Empress GUI Builder user-defined object has the following two actions associated with it: init and clean action.

This action could be used to get the drawing area widget of the user object, allocate memory for the data structures and perform other one-time operations, such as, adding appropriate call backs and creating children of the drawing area widget. The init action is called when the object is created, before the enter action of the module is executed and before the drawing area widget is realized.

This action could be used to free allocated memory and perform other clean-up actions associated with the drawing area widget, such as, destroying the children of the drawing area widget. The drawing area widget, however, should not be destroyed by the application.

The following are guidelines for using the drawing area widget in an Empress GUI Builder application:

1. Empress GUI Builder will open the display for an application. Use the following X function to get the display:

Display *XtDisplay (widget)

2. Some X functions need to access the window of the widget. The following is the function to get the window of the drawing area widget which can be used to draw or display anything in the drawing area widget:

Window XtWindow (widget)

Note that this function cannot be used in the init action of the object, because at the moment that the init action is executed, the widget is not realized, and its window does not exist yet.
 
3. The application should create its own graphics context if it needs to draw on the drawing area widget. The values of a graphics context must be set before it is created. Values which are not set will be assigned defaults in the newly created graphics context. The functions to create a new graphics context are:

XCreateGC (display, window, mask, &gcvalues);

XtGetGC (widget, mask, &gcvalues);

These functions create a graphics context for a given screen with the depth of the specified drawable. For drawing purposes, one would normally want to set the background, foreground, and line-width.

If the drawing area is used for displaying text, the font must be set as a component of the relevant graphics context.
 

4. The drawing area widget defines the following three callback resources:

XmNexposeCallback
XmNinputCallback
XmNresizeCallback

The developer should define the appropriate callback functions for the above mentioned callback resources. This should normally be done in the init action of the object.

The user-defined object has a property called PROP_USER_DATA. It is a pointer to any data structure that the developer wants to associate with that object. This property is very useful when an application has several user-defined objects used in a similar way, but with different data.

For example, an application would have two user-defined objects used as histograms. Since they perform the same function, they will use the same init and clean action. They can also use the same callbacks to draw the histograms, and handle the various X-events. These actions and callbacks can access the data associated with the objects by getting and setting PROP_USER_DATA.