To create a menu-level toolbar, specify &SMARTBAR after the DEFAULT menu module name in the Form Module property palette. Dynamically hiding the menu using REPLACE_MENU('') in the WHEN_NEW_FORM_INSTANCE trigger will also suppress the display of the associated toolbar.

To create a menu-level toolbar for any customized menu, set either the Visible In Horizontal Menu Toolbar or Visible In Vertical Toolbar property to Yes for each menu item that should appear in the menu toolbar.

Figure 1.1 shows a menu-level toolbar.

Figure 1.1. A menu-level toolbar.

To create a form-level or window-level toolbar, you create a horizontal toolbar canvas view with iconic buttons. Then, specify it as the value for the Form Horizontal Toolbar property or the Window Horizontal Toolbar property. To do so, follow these steps:

A sample toolbar constructed in this way looks like the one shown in Figure 1.2.

Figure 1.2. A form-level toolbar.

In Forms 4.5, you can display ToolTips by creating a display item, TOOLTIP_ITEM, with the following properties:

In addition, the property class PC_ICONIC_BUTTON discussed earlier can have the following two triggers attached to it: WHEN-MOUSE-ENTER and WHEN-MOUSE-LEAVE. The code for these triggers is explained in the steps that follow.

Dynamically populate this item with text equivalent to the Label in the WHEN-MOUSE-ENTER trigger, as follows:

WHEN-MOUSE-ENTER

DECLARE
  tooltip_x_pos NUMBER;
  tooltip_y_pos NUMBER;
  tooltip_text  VARCHAR2(30);
  item_id ITEM;
BEGIN
  tooltip_x_pos := GET_ITEM_PROPERTY(:SYSTEM.MOUSE_ITEM,X_POS);
  tooltip_y_pos := GET_ITEM_PROPERTY(:SYSTEM.MOUSE_ITEM,Y_POS);
  tooltip_text := GET_ITEM_PROPERTY(:SYSTEM.MOUSE_ITEM,LABEL);
  :toolbar.tooltip_item := tooltip_text;
  item_id := FIND_ITEM('TOOLBAR.TOOLTIP_ITEM'),
  IF NOT ID_NULL(item_id) THEN
    SET_ITEM_PROPERTY(item_id, DISPLAYED, PROPERTY_TRUE);
    SET_ITEM_PROPERTY(item_id, POSITION tooltip_x_pos+10, tooltip_y_pos+10);
  ELSE
    MESSAGE('Invalid Tooltip Item'),
    RAISE FORM_TRIGGER_FAILURE;
  END IF;
END;

A WHEN-MOUSE-LEAVE trigger will hide the dynamic ToolTip by setting its DISPLAYED property to FALSE as follows:

WHEN-MOUSE-LEAVE

DECLARE
  item_id ITEM;
BEGIN
  item_id := FIND_ITEM('TOOLBAR.TOOLTIP_ITEM'),
  IF NOT ID_NULL(item_id) THEN
    :toolbar.tooltip_item := NULL;
    SET_ITEM_PROPERTY(item_id, DISPLAYED, PROPERTY_FALSE);
  END IF;
END;

In Forms 5.x and above, the ToolTip appears below the iconic button, whereas in Forms 4.5 it appears on the side. This has been intentionally done because the ToolTip in Forms 4.5 is attached to the MDI horizontal toolbar; there is no way to display it outside the toolbar canvas without making the canvas height more than the icons'height. This leaves a view space on the MDI toolbar.

The following tips provide the tidbits often ignored while developing form-level and window-level toolbars. Also, the points to remember while associating toolbars with forms in multiform applications are highlighted.

Window-Specific Toolbars for Modal Windows

A modal window should have a window-level toolbar associated with it. Form-level toolbar icons are not accessible from a modal window. The same is true with toolbars associated with menu, SDI, or MDI windows. Figure 1.3 shows a form-specific toolbar with a Personal Info. icon. If you click on this icon, you get the window-specific toolbar for a modal window, shown in Figure 1.4.

Figure 1.3. A form-specific toolbar with a Personal Info. icon.

Figure 1.4. A window-level toolbar.

This section discusses the techniques to implement dynamic toolbars. It starts by looking at the various ways a toolbar can be "dynamic."

Dynamic toolbars can be implemented several ways. You can create toolbars that dynamically shrink or expand, based on the current mouse position or the current item, record, block, canvas, or form; you hide, unhide, and resize proportionately the toolbar's iconic buttons, depending on the current cursor position. Examples are as follows:

Other dynamic toolbars are scrollable for forms that require greater functionality to be provided by means of application-specific buttons. Floating toolbars can appear almost anywhere—that is, they "float" in an application or appear where you right-click. You can resize toolbars so that the icons fit proportionately. Finally, you can generate toolbars from a global set of iconic buttons, using point-and-click.

In this section, I will discuss the implementation of a floating toolbar. It has the flexibility of being able to float, or be displayed almost anywhere when initiated by a user action. It can also have dynamic resizing capability. It has the same functionality as a regular toolbar but remains displayed until closed by another user action. For example, the user action initiating the display of the toolbar can be a right mouse click on an empty part of the canvas (that's why it's floating), and the user action closing it can be a left mouse click in an empty area of the can vas.

Follow these steps to create the floating toolbar:

The floating toolbar will look like Figure 1.5.

Figure 1.5. A floating toolbar.

You can initiate the window close in several ways. First, you can set the Hide On Exit property to Yes for this toolbar window. This is not a standard practice because the user might want to perform multiple functions in the form using this toolbar and would therefore want the toolbar to remain floating until explicitly closed. Applications demanding user-specific requests for such a feature are an exception to this rule.

Second, the window can close when the user clicks the upper-right ×. This is the recommended practice, unless a user requirement specifies a different approach. To use this technique, write a WHEN-WINDOW-CLOSED trigger at form level that checks for the currently active window and closes it if it is WINDOW_FLOATING_TOOLBAR:

WHEN-WINDOW-CLOSED

IF NAME_IN('SYSTEM.EVENT_WINDOW') = 'WINDOW_FLOATING_TOOLBAR'THEN
   SET_WINDOW_PEROPERTY('WINDOW_FLOATING_TOOLBAR', VISIBLE, PROPERTY_FALSE);
END IF;

Third, the window can be made to disappear by creating a timer at the time of window initia tion and writing a WHEN-TIMER-EXPIRED trigger to hide it after a certain interval of time. You provide this second way of closing by specifying an appreciably large time interval—a minute, for example. Closing the floating toolbar by means of a timer involves the following steps:

Floating Toolbar Pop-Up Menus

Another convenient way of displaying a floating toolbar is by providing a pop-up menu on a right mouse button click. This pop-up can have at least two menu options: Show Toolbar and Hide Toolbar. This can be achieved by the following steps:

1. Create a pop-up menu in the Object Navigator with two items: SHOW_TOOLBAR (labeled Show Toolbar) and HIDE_TOOLBAR (labeled Hide Toolbar).

2. The WHEN-MOUSE-CLICK trigger is still necessary because the :system.mouse_x_pos for a pop-up menu is 0 when the cursor is in the pop-up. Therefore, you capture the (mouse_x_pos, mouse_y_pos) as soon as the user right-clicks to display the pop-up menu. You can write a WHEN-MOUSE-CLICK trigger , in addition to the menu item code, to capture the current (X,Y) of the cursor on right click before the cursor is positioned on one of the items of the pop-up menu:

   WHEN-MOUSE-CLICK
   
   IF :SYSTEM.MOUSE_BUTTON_PRESSED != '1'THEN
     IF  :SYSTEM.MOUSE_ITEM IS NULL THEN
   
       COPY(NAME_IN('SYSTEM.MOUSE_X_POS'), 'CTRL_BLK.MOUSEXPOS'),
       COPY(NAME_IN('SYSTEM.MOUSE_Y_POS'), 'CTRL_BLK.MOUSEYPOS'),
   
     END IF;
   END IF;
   

   Here, CTRL_BLK.MOUSEXPOS and CTRL_BLK.MOUSEYPOS are two control items to hold the current values of SYSTEM.MOUSE_X_POS and SYSTEM.MOUSE_Y_POS as defined in the preceding code snippet.

3. The menu item code for the SHOW_TOOLBAR item is as follows:

   IF :SYSTEM.MOUSE_ITEM IS NULL THEN
     SET_WINDOW_PROPERTY('window_ft', X_POS,
                 TO_NUMBER(:ctrl_blk.mousexpos));
      SET_WINDOW_PROPERTY('window_ft', Y_POS,
                 TO_NUMBER(:ctrl_blk.mouseypos));
      SET_WINDOW_PROPERTY('window_ft', VISIBLE, PROPERTY_TRUE);
   END IF;
   

4. The menu item code for the HIDE_TOOLBAR item is as follows:

   SET_WINDOW_PROPERTY('window_ft', VISIBLE, PROPERTY_FALSE);
   :ctrl_blk.mousexpos := NULL;
   :ctrl_blk.mouseypos := NULL;
   

The pop-up menu appears somewhat like the one shown in Figure 1.6.

Figure 1.6. A pop-up menu to display a dynamic floating toolbar.

Let's create a display item, CURRENT_TIME, in the horizontal toolbar canvas CANVAS_TOOLBAR created earlier. This item shows the time in HH24:MI:SS format and updates itself every second (the timer duration).

In the WHEN-NEW-FORM-INSTANCE trigger, create a timer named CLOCK_TIMER, which iterates after every one second and populates the CURRENT_TIME item with the system date in HH24:MI:SS format. The code is as follows:

DECLARE
   timer_id TIMER;
   one_second NUMBER := 1000;
BEGIN
   timer_id := FIND_TIMER('CLOCK_TIMER'),
   IF NOT ID_NULL(timer_id) THEN
     DELETE_TIMER(timer_id);
   ELSE
     timer_id := CREATE_TIMER('CLOCK_TIMER',one_second, REPEAT);
   END IF;
     SELECT  TO_CHAR(SYSDATE,'HH24:MI:SS')
     INTO   :toolbar.current_time
     FROM   DUAL;
   EXCEPTION WHEN OTHERS THEN
     MESSAGE(TO_CHAR(SQLCODE)||''||SQLERRM);
END;

Create a WHEN-TIMER-EXPIRED trigger as follows:

DECLARE
   timer_name VARCHAR2(30);
BEGIN
   timer_name := GET_APPLICATION_PROPERTY(TIMER_NAME);
   IF  timer_name = 'CLOCK_TIMER' THEN
      SELECT  TO_CHAR(SYSDATE,'HH24:MI:SS')
      INTO   :toolbar.current_time
      FROM   DUAL;
   END IF;
   EXCEPTION WHEN OTHERS THEN
      MESSAGE(TO_CHAR(SQLCODE)||''||SQLERRM);
END;

List items appear as either drop-down list boxes, T-lists, or combo boxes in Forms. Mostly, list items have static values as their elements, created during design time. However, there arises a need to populate a list item with elements based on runtime criteria or from a database table. For example, one might populate a drop-down list box with all the state codes from a look-up table named STATE_TAB. This can be done either using a query or adding elements one by one at runtime. This way of populating list items programmatically without hard-coding their values at design time is what is termed dynamically populating list items.

This technique involves populating the list with a query or without a query. I will discuss populating by means of a query because it is very powerful and efficient.

One elegant way to populate list items dynamically is to use programmatically created records groups. This record group should have a two-column structure, both being of character data type. The first column should correspond to the label of the list item, and the second column, to the corresponding value.

The code performs these tasks:

The sample code is given here:

DECLARE
   rg_list_id RECORDGROUP;
   rg_name VARCHAR2(20) := 'RG_LIST';
   ret_code       NUMBER;
--The following holds a SELECT query from which the list elements are derived.
   v_select       VARCHAR2(300);
BEGIN
  v_select := 'SELECT state_code, state_code FROM state_tab ORDER BY 2';
  rg_list_id := FIND_GROUP(rg_name);
  IF NOT Id_Null(rg_list_id) THEN
     DELETE_GROUP(rg_list_id);
  END IF;
  rg_list_id := CREATE_GROUP_FROM_QUERY(rg_name, v_select);
  ret_code := POPULATE_GROUP(rg_list_id);
  POPULATE_LIST('LIST_ITEM','RG_LIST'),
  DELETE_GROUP(rg_list_id);
END;

Sometimes, it might be necessary to populate NUMBER and DATE columns as list item element values. Because list items always retain character values only, for both the label and value, it is necessary to perform conversion to VARCHAR2 from NUMBER and DATE.

As an illustration, consider a drop-down list box showing all departments in an organization. You can assume that the DEPT table has the following structure:

CREATE TABLE DEPT
(ID NUMBER(6) PRIMARY KEY,
 NAME VARCHAR2(30) NOT NULl);

The label column has its values derived from the NAME column. The value corresponding to each NAME is derived from the ID column and should be stored in the list item as a character value. This requires the use of TO_CHAR. Therefore, the query text in the preceding example changes to

v_select := 'SELECT name, TO_CHAR(id) FROM dept ORDER BY 1';

After populating the list, the value can be accessed by doing a reconversion to NUMBER using the TO_NUMBER function. The following shows how to access the ith element from the list discussed in the preceding example:

DECLARE
  v_id NUMBER;
  v_id_char VARCHAR2(6);
  item_id ITEM;

BEGIN
  item_id := FIND_ITEM('LIST_ITEM'),
  IF ID_NULL(item_id) THEN
    MESSAGE('Invalid List'),
    RAISE FORM_TRIGGER_FAILURE;
  END IF;
    FOR I IN 1..GET_LIST_ELEMENT_COUNT(item_id) LOOP
      v_id_char = GET_LIST_ELEMENT_VALUE(item_id, i);
      v_id := TO_NUMBER(v_id);
. . . . use this value for further processing
    END LOOP;
END;

How many of you are aware of the fact that in Forms, you can add elements to the beginning of an already populated list item without repopulating it? This seems trivial at first thought but is a very powerful and flexible technique to be used in many demanding situations.

Use ADD_LIST_ELEMENT and specify the constant 1 for the element index. This displaces all the existing elements to one position below and makes room for the new element with index number 1. Do not specify the constant 0 instead of 1.

The code you will use is as follows:

ADD_LIST_ELEMENT(list_id, 1, <label>, <value>);

So far, I have discussed how to add elements dynamically to an empty list, how to access noncharacter list elements, and how to add to the beginning of an existing list. Now I will present a simple method to insert elements in the middle of an existing list and to append elements to the end of an existing list.

Use ADD_LIST_ELEMENT and specify the index number of the new element as

current element index + 1

where current element is the element after which the new element should be added. This displaces all the remaining elements to one position below and makes room for the new element.

To add to the end of the list, specify the constant returned by GET_LIST_ELEMENT_COUNT, which gives the number of existing elements, and then specify the index of the new element as the value of this constant incremented by 1.

The following is the code for this:

DECLARE
   cnt NUMBER := 0;
BEGIN
   cnt := GET_LIST_ELEMENT_COUNT(list_id);
        ADD_LIST_ELEMENT(list_id, (cnt+1), <label>, <value>);

END;

In this example, you take the count of the list elements and increment it by 1. This value serves as the index for the new list element to be added. This works even when the list is wholly empty, because you initialize the count to zero before incrementing it by 1. Therefore, it adds the first element in case of an empty list.

LOV is the Forms acronym for List of Values. It functions in a manner similar to a pick list of choices. Drill-down LOV refers to descending through the LOV to its sublevels, starting from a highlighted element in the LOV.

Drill-down LOVs are very useful for tables involving recursive and/or parent-child relationships. Examples of such relationships are those involving a department and its employees, a manager and employees, or a company and its hierarchical representation.

In each of these cases, a foreign key is involved that is either self-referential or parent- referential. For example, the department-employee relationship involves a parent-referential foreign key from the Department table (the parent table). The manager-employees relationship is self-referential, with the primary and foreign keys being selected from the same table. Also, the information is hierarchical. The company information is another example of a hierarchical representation.

LOVs are a commonly required feature of any application involving this kind of look-ups. The features of LOVs supported by Forms are limited in the sense that

Out of these limitations, the most required functionality in case of parent-child relationships, especially tree-oriented, is the drill-down.

Drill-down functionality can be incorporated in an LOV directly using a Forms-provided LOV or using list items. This section discusses the implementation details of building a drill-down LOV using list items. The same method can be followed when using a Forms-supplied LOV.

You will use a T-list and dynamically populate it using a record group. The drill-down is achieved by dynamic replacement of the same record group query again and again till there is no further drill-down. Double-clicking a parent element will show this parent element and all its children one level below. The user "drills down" the LOV to reach a deeper level. The operation is repeatable until leaf elements are reached. The string '- Parent' is appended to the parent element label to identify it as the parent. This element is always the first element of the list, irrespective of whether it has children.

Double-clicking a parent element will show its parent and all its children, that is, one level above. The user "drills up" the LOV to reach a higher level. The operation is repeatable until the root element is reached. Once at the root, the original list is restored; that is, all EMPNOs that exist as MGRs. The string '- Parent' is still appended to the parent element label until the initial list is restored.

The same T-list and the same record group are reused for the drill-down and drill-up operations.

The selection of an element is done by pressing Shift and double-clicking on the element. The normal double-clicking being reserved for drill-down, the Shift+double-click is used as an alternative for selecting an element from the LOV.

Figures 1.8 through 1.10 depict the drill-down operation on the sample list discussed here. The parent for the second level is suffixed with the phrase '- Parent' to mark it as the parent element for the children displayed below it.

Figure 1.8. Original List before drill-down

Figure 1.9. First Level LOV after drill-down

Figure 1.10. Second Level LOV after drill-down

The Find feature of LOVs enables you to enlarge or reduce the LOV list as the user types in characters of the LOV element value. This feature can be simulated using COMBO BOX and T-LIST type list items in Forms 4.5. Although it doesn't use the exact mechanism offered by LOVs, the method described here imitates the same functionality. You will assume that the list to be displayed is SITE_NAME, based on the SITE_TAB table. The SITE_TAB table has the following structure:

SITE_NO    NUMBER(6) NOT NULL,
SITE_NAME VARCHAR2(20) NOT NULL.

Follow these steps: