UpPreviousNext

Using Timers, Event Handlers, and Translations

You can register and use timer procedures, work procedures, event handlers, and translations using special editors provided by Builder Xcessory. These elements are managed similarly within Builder Xcessory.

Timer Procedures

A timer procedure is a procedure invoked when a specified interval of time elapses. When a timeout event occurs, the timer callback procedure is invoked, and the callback is removed. Consequently, timeout events are invoked only once.

In ViewKit code generation, specifying a timer procedure causes Builder Xcessory to create an instance of the VkPeriodic class. This class calls the timer procedure repeatedly until your application stops it. For more information on this class, refer to the VkPeriodic manpage.

Using timer procedures

Use a timer procedure for an event that you want to happen after a specific time interval. When the timer procedure is registered, Xt first waits for at least the interval you specified, and then calls the timer procedure. Builder Xcessory generates code to register the timeout in the main program.

Refer to O'Reilly & Associates, Definitive Guides to the X Window System, Volumes 4 and 5 for a full description of timer procedures and the XtAppAddTimeOut call.

Adding timer procedures

To add a timer procedure, follow these steps:

1. Select Application from the Browser Managers menu to display the Application Manager.

2. Click on the (...) button next to the Timer Procedures input field in the Application Manager to display the Application Timer Procedures Editor:

 

Application Timer Procedures Editor

3. Click on New.

4. Enter the name of the timer procedure to be called after the interval expires, along with the interval, the parameter type, and the parameter (data) in their associated fields.

Interval specifies the number of milliseconds that should elapse before this function is invoked. After this period elapses, the procedure's callback is invoked by the Xt Intrinsics. The Parameter field specifies client data to pass to the procedure XtAppAddTimeOut.

5. Click on Apply to register the timer procedure.

All current timer procedures are displayed in the window above these fields.

Removing timer procedures

To remove a timer procedure, follow these steps:

1. Select the procedure from the list displayed in the Application Timer Procedures Editor

2. Click Delete.

The procedure is removed from the list and from your application.

Work Procedures

A work procedure is a callback that provides a limited form of background processing. The Xt Intrinsics invoke a work procedure whenever there are no events pending. Thus whenever the application is not drawing to the display or responding to user actions, the work procedure is called.


Note: Although you can define multiple work procedures, only the most recently registered is called.

Using work procedures

Use a work procedure to specify a function to call when no other events are pending. Once a work procedure is called, the program cannot process any events until the procedure returns. Therefore, any work procedure should be a function that executes quickly.

Example

To perform a long calculation with work procedures, set the calculation as an iterative process so that a small portion of the calculation can be done each time the work procedure is called. This approach avoids freezing the interface.

When you specify work procedures and generate code for ViewKit, Builder Xcessory creates a subclass of the VkBackground component for each work procedure you have specified. Each work procedure class is instantiated and started in the main() routine, before the call to VkApp::run().

Refer to O'Reilly & Associates, Definitive Guides to the X Window System, Volumes Four and Five for a full description of work procedures and the XtAppAddWorkProc call.

Adding work procedures

To add a work procedure, follow these steps:

1. Select Application from the Browser Managers menu to display the Application Manager.

2. Click on the (...) button next to the Work Procedures input field in the Application Manager to display the Application Work Procedures Editor:

:

Application Work Procedures Editor

3. Click on New.

4. Enter the name of the WorkProcedure, the Parameter Type, and the Parameter Value in their associated fields.

5. Click on Apply to register the work procedure.

All current work procedures are displayed in the scrolled window above these fields.

Registering a work procedure causes a call to XtAppAddWorkProc to be inserted in the main program.

For ViewKit code generation, a VkBackground subclass is instantiated.

 

Removing work procedures

To remove a work procedure, follow these steps:

1. Select Application from the Browser Managers menu to display the Application Manager.

2. Select the work procedure from the list displayed in the Application Work Procedures Editor.

3. Click on Delete.

The work procedure is removed from the list and from your application.

Event Handlers

An event handler specifies functions called when an X/Motif event is received by the window associated with the object for which the event handler is set.

Example

Sometimes an object does not provide a callback for an X event that you want to respond to in your application. For example, the XmDrawingArea widget does not have a callback for when the user moves the mouse with a mouse button held down. You must add an event handler to the eventHandler resource on the XmDrawingArea object.

Refer to O'Reilly & Associates, Definitive Guides to the X Window System, Volumes Four and Five for a full description of event handlers and the XtAddEventHandler call.

Adding event handlers

To add an event handler, follow these steps:

1. Click on the (...) button next to the eventHandler resource on the Resource Editor to display the Event Handler Editor:

 

Event Handler Editor

2. Click on New.

3. Enter the Handler Name, the Event Mask, the value of Non-Maskable, and the Parameter Type and Value in their associated fields. The Event Mask specifies the events that trigger the event handler. Non-Maskable is True if the handler is to be triggered on non-maskable events (that is, events that cannot be specified by the Event Mask, for example, GraphicsExpose, SelectionNotify, or ClientMessage), and is otherwise False. The Parameter specifies client data to pass to the procedure XtAppAddTimeOut.

4. Click on Apply to register the event handler.

Builder Xcessory inserts a call to XtAddEventHandler in the file in which the widget is created. All current event handlers are displayed in the scrolled window above these fields.

Removing event handlers

To remove an event handler, follow these steps:

1. Select the event handler from the list displayed in the Event Handler Editor.

2. Click Delete.

The event handler is removed from the list and from your application.

Translations

A translation links a sequence of one or more events to an action, the function called when these events are received. You can add translations that include actions already registered for the object, or you can add a translation based on additional actions that you must register in your code before creating any object that references them.

Using translations

Most objects provide a large number of actions that are triggered by key presses, mouse actions, and so forth. In most cases, you only add translations to an object to augment its behavior.

Example

Support for Motif drag and drop is added to objects with an action. You must modify a new object's translation table to add drag and drop support.

Adding translations

To add a translation to an object, use one of the following methods:

· Enter the translation in the translations resource text field on the Resource Editor.

· Click the (...) button to the right of the translations resource's text field to display the Translation Table Editor ( Translation Table Editor ), and enter the translation.

 

Translation Table Editor

When you apply the contents of the Translation Table Editor to an object's translations resource, Builder Xcessory replaces the object's Translation Table with the translations you have provided.


Note: Builder Xcessory displays a warning if you modify an object's Translation Table and reference an action that you plan to add. However, the action works correctly in your code, provided that the action is registered before you create the object whose translation table references it.
UpPreviousNext