0866-0869

Previous Table of Contents Next

Page 866

Using Timers for Event Control

You can use timers in Oracle Forms to trigger events that are dependent on a specific time interval. These timers can be iterative (repeating) or one-time only. Examples of iterative timers are a report queue manager that looks for requests every 15 seconds or a database status form that "refreshes" the screen every 2 minutes. Uses for a one-time only trigger might be as a delay timer for button help or as a timeout trigger. To create a timer, you issue the following command:

 TIMER_ID := CREATE_TIMER (timer_name, interval, REPEATNO REPEAT); 

TIMER_ID is a PL/SQL variable of type TIMER, timer_name is the name given to the timer by the programmer, and interval is the duration of the timer in milliseconds .

Oracle Forms supports multiple timers; however, you can include only one WHEN_TIMER_EXPIRED trigger at the form level. To determine which timer has expired , the trigger should use the GET_APPLICATION_PROPERTY (TIMER_NAME) built-in function. Then by checking against the various timer names , you can execute the appropriate program sequence. You can use the SET_TIMER built-in (same syntax as the CREATE_TIMER built-in) to restart an existing timer or to change its interval or repeat parameters. Finally, you can use the DELETE_TIMER built-in to remove a timer.

The example shown in Figure 35.22 shows how to implement multiple timers in a form using an iconic button bar. The WHEN_NEW_FORM_INSTANCE trigger creates two triggers that are used in the form, and the WHEN_TIMER_EXPIRED trigger executes the logic necessary when a timer expires . The first trigger is used to create an animated button in a form button bar by toggling the icon file used based on a time interval. The second timer is used to validate that the user enters a valid name within 30 seconds or the form terminates. Finally, the WHEN_MOUSE_ENTER and WHEN_MOUSE_LEAVE triggers are set up to create a timer that displays button help after the mouse has been "resting" on a button for at least one half second.

Figure 35.22.
Timer demo form.

Page 867

First, create a canvas called DESKTOP and a non-database block called control. The desktop and associated window should be defined as 300 points wide by 200 high. Create the USER_NAME field as shown on the desktop with the appropriate valid condition. Now, create an alert called TIMEOUT_ALERT as an informational alert with one button. The message text for this alert should be

 R E M I N D E R      This form will terminate unless a valid user name      is entered within 30 seconds after startup. 

This alert will be displayed whenever the Show Note button is clicked.

Now, to create the iconic button bar, create a second canvas called BUTTON_BAR. The Canvas Type property for this canvas should be Horizontal Button Bar, and it should be 300 points wide by 30 points high. Create a button for the exit function. Properties for this button are shown in Table 35.6.

Table 35.6. Button bar iconic button properties.

Property	Value
Name	EXIT_BUTTON
Canvas	BUTTON_BAR
X Position
Y Position
Width	30
Height	30
Navigable	False
Mouse Navigable	False
Label	Exit Form
Iconic	True
Icon Name	Exit

Additionally, create a second button, SHOW_NOTE, adjacent to the EXIT_BUTTON that will use the light-on iconic file. (Note that the icon file will change to "blink" the light at runtime.) Now, the button bar must be defined as such to the form. To do this, change the Horiz.MDI toolbar to point to the BUTTON_BAR canvas. This causes the button bar to appear outside the frame of the form window when the form is executed.

Page 868

NOTE

At any one time, only one MDI (Multiple Document Interface) button bar will appear in a Windows application. This prevents confusion when multiple documents or forms are open at the same time. Only one document can be active at any time and the MDI button bar shows the buttons associated with the active document. This is especially useful when working with multiple forms or OLE applications.

Create triggers that execute the proper commands when the button is clicked. The trigger for the EXIT_BUTTON item should be DO_KEY (`EXIT_FORM'), and you should create the following WHEN-BUTTON-PRESSED trigger for the SHOW_NOTE button:

 declare    bno      NUMBER; begin    bno := show_alert (`TIMEOUT_ALERT'); -- -- Note additional logic may be placed here based on the button pressed -- by the user. -- end; 

Now, you can add the timer triggers to the form. First, you set up the timeout and blink timers for the form in the WHEN-NEW-FORM-INSTANCE trigger. (This trigger replaces the KEY-STARTUP trigger in Forms 3.0.) This trigger is coded as follows :

 declare    timeout_id          TIMER;    blink_id               TIMER; begin    timeout_id := CREATE_TIMER (`TIMEOUT', 30000, NO_REPEAT);    blink_id := CREATE_TIMER (`BLINK', 500, REPEAT); end; 

Additionally, you need to add triggers to provide button help as needed. This help text, which is a standard in many Windows applications, displays the value that was entered for the button label directly below the iconic button. To add this functionality, attach the HINT.PLL library to the form and create a WHEN-MOUSE-ENTER trigger and a WHEN-MOUSE-LEAVE trigger for the form as follows:

 begin -- WHEN-MOUSE-ENTER trigger    HINT.ShowButtonHelp; end; begin -- WHEN-MOUSE-LEAVE trigger    HINT.HideButtonHelp; end; 

If the user enters a valid name in the username field, the timeout timer should be canceled . To do this, create a WHEN-VALIDATE-ITEM trigger for the USER_NAME field:

 begin -- WHEN-VALIDATE-ITEM trigger    if :control.user_name is not null then 

Page 869

 delete_timer (`TIMEOUT');    end if; end; 

To complete this form, you must write a WHEN-TIMER-EXPIRED trigger for all timers in the form. This trigger determines the timer that caused the trigger that fired and processes the logic associated with the trigger:

 declare -- WHEN-TIMER-EXPIRED trigger    which_timer     VARCHAR2(50); begin    which_timer := get_application_property (TIMER_NAME);    if which_timer := `BLINK' then       :control.message_switch := mod (:control.message_switch +1, 2);       if :control.message_switch = 0 then          set_item_property (`CONTROL.SHOW_NOTE', ICON_FILE, `lightoff');       else          set_item_property (`CONTROL.SHOW_NOTE', ICON_FILE, `lighton');       end if;    elsif which_timer = `TIMEOUT' then       message (`Timeout Occurred.  Form Canceled.');       do_key (`EXIT_FORM');    else       HINT.ShowButtonHelpHandler;    end if; end; 

You should note a couple of important points when working with timers:

• The WHEN-TIMER-EXPIRED trigger can handle only one timer at a time. If a second timer expires while this trigger is handling the first, it is placed on the stack until the trigger is completed.
• The WHEN-TIMER-EXPIRED trigger fires during transaction processing, navigation, and so on. If a second form is called by the form containing the trigger, the timer is deferred until the user returns to the calling form.
• A repeating trigger does not repeat until it is taken off the queue. In other words, the interval does not start up again until the first iteration is handled.
• Any existing timers are deleted when the form is exited. If any timed activity is pending or on the queue, it does not complete if the form is exited.
• Finally, do not use timers where precise timing is essential. Because the preceding conditions can delay the actual execution time of the trigger logic, you cannot use the Oracle timer for industrial fail-safe operations.

Considerations for Multiple Form Applications

Oracle Forms provides three built-in procedures that enable the user to access other forms from an original calling form. These procedures are NEW_FORM, CALL_FORM, and OPEN_FORM.

NEW_FORM terminates execution of the original form and starts the next form. If any changes are made to database data, the user is asked if he wants to commit the data. If he chooses not to

Previous Table of Contents Next