Controlling the Toolbar and the Default Menu

Pulldown Menus and the Toolbar

The Oracle E-Business Suite pulldown menus (the default menu) allow the user to invoke standard Oracle Forms functions, such as "Clear Record" as well as application-specific functions.

Both the menu and the toolbar are included in the TEMPLATE form. Entries on the menu and the toolbar are disabled and enabled automatically based on the current context.

For details on each pulldown menu and iconic button on the Toolbar,, see the Oracle E-Business Suite User Interface Standards for Forms-Based Products.

Menu and Toolbar Entries

Your menu and toolbar should react consistently to changes within your forms. Unless specified otherwise, the following behaviors come automatically from the form-level triggers embedded in your forms. The triggers that control the behavior appear with each entry (if applicable).

Both Menu and Toolbar Entries

In order as they appear on the toolbar:

Menu-Only Entries

In order as shown on the pulldown menu, from File to Help:

Dynamic Menu Control

You can use the APP_SPECIAL.ENABLE procedure to dynamically control menu items, if the behavior you need is not provided automatically. First, determine if the default menu control handles the menu item in question, and ensure that there really is a need to override the default behaviors.

If the menu item is not controlled by the default menu control, use any appropriate trigger (typically PRE-BLOCK or WHEN-NEW-BLOCK-INSTANCE), adding the code:

 app_special.enable('the menu item', PROPERTY_OFF|ON);

Turn the menu item back on when you leave (typically POST-BLOCK) by calling:

 app_special.enable('the menu item', PROPERTY_ON|OFF);

Include the full name of the menu item in this call, for example:

 app_special.enable('CLEAR.FIELD', PROPERTY_OFF);

You can determine the full names of the menu items by copying FNDMENU from the AU_TOP/resource/<language> area and opening the copy to examine the menu items.

If the menu item is controlled by the default menu control and you want to modify its behavior (enable or disable it), create the field- or block-level trigger listed (either WHEN-NEW-BLOCK-INSTANCE, WHEN-NEW-RECORD- INSTANCE, or WHEN-NEW-ITEM- INSTANCE). Set the trigger Execution Hierarchy to "Override" and add the following code:

 app_standard.event('TRIGGER_NAME');
 app_special.enable('Menu_item', PROPERTY_OFF|ON);

The item will be correctly reset in other blocks by the default menu control, so it is not necessary to reset it when leaving the block, record, or item.

See: APP_SPECIAL: Menu and Toolbar Control

Common Coding Mistakes That Affect the Menu

The most common sources of problems with menu include the following coding mistakes:

Blocks Where Only One Record Is Possible

You may want to disable some menu options for blocks in which only one record is possible. The Single Record Blocks section discusses when and how to do this.

See: Single Record Blocks

Save and Proceed

By default, this function performs a Save, then moves to the First Navigation Data Block of the form and proceeds to the next record. You can override this behavior.

Replace the code within the form-level ACCEPT trigger, or create a block-level ACCEPT trigger with Execution Hierarchy set to Override that calls any of the following:

Synchronizing

The toolbar and menu are automatically updated by the standard form-level WHEN-NEW-RECORD-INSTANCE, WHEN-NEW- BLOCK-INSTANCE, and WHEN-NEW-ITEM-INSTANCE triggers. If you change a property of a block or an item, the menu and toolbar do not reflect this change until the appropriate trigger fires.

For example, if you turn the block property Insert Allowed off on a block while the cursor is already in that block, you must explicitly call the routine below to synchronize the menu and the toolbar:

APP_STANDARD.SYNCHRONIZE;

See: APP_STANDARD Package.

Application-Specific Entries: Special Menus

You can customize the menu to display application-specific values. The menu supports up to forty-five application-specific entries under three top-level special menu entries (usually called Tools, Reports, and Actions). The toolbar supports corresponding iconic buttons for any of the forty-five special menu entries.

Any icon placed on the toolbar must be approved by the User Interface Standards group, and will be maintained with all the other icons.

See: APP_SPECIAL: Menu and Toolbar Control

Example Special Menu Entry

Suppose you have a special function called 'Book Order' that you want to add to the menu and the toolbar. To add 'Book Order' as the first entry on the first special menu (Tools) and as an icon on the toolbar, such that they are only available in the 'Header' block of a form, do the following:

  1. Modify the form level PRE-FORM trigger:

    PRE-FORM


    app_special.instantiate('SPECIAL1', '&Book Order', 'bkord');

    If you plan to translate your form, you should use Message Dictionary, a parameter, or a static record group cell to store the Special Menu entry. You then retrieve the value (which is translated when the application is translated) into a variable and pass the variable to the APP_SPECIAL routine. For example:

    app_special.instantiate('SPECIAL1', my_menu_entry, 'bkord');

  2. Add a form-level PRE-BLOCK trigger:

    PRE-BLOCK
app_special.enable('SPECIAL1',PROPERTY_OFF);

  3. Add a block level PRE-BLOCK trigger to the block in which you want to enable your special menu entries:

    PRE-BLOCK in HEADER block
app_special.enable('SPECIAL1',PROPERTY_ON);

  4. Add a block level SPECIAL1 user-named trigger that contains code to actually perform your 'Book Order' function. It executes when the user chooses this menu entry.

Custom Toolbar Icons for Custom Forms

For custom forms, custom icon files must be separate standard .gif files located in the directory designated by the OA_MEDIA virtual directory (see your web server administrator for this information). Note that retrieving the icon file for a custom icon requires a round trip to the forms server, so you should limit the number of icons you retrieve if performance becomes an issue.

Disabling the Special Menu

To disable all special menu entries (for example, when entering query-mode), call APP_SPECIAL.ENABLE('SPECIAL', PROPERTY_OFF);

Customizing Right-Mouse Menus (Popup Menus)

Oracle E-Business Suite provides default right-mouse menu functionality for all text items. When a user presses the right mouse button (or equivalent "secondary" button) while holding the mouse pointer over the text item that currently has cursor focus, Oracle E-Business Suite displays a context-sensitive popup menu. The default menu entries are:

Cut
Copy
Paste
------
Folder
------
Help

You can customize the right-mouse menus to display application-specific entries in addition to the default entries. The right-mouse menu supports up to ten application-specific entries. Application-specific entries appear between the Folder and Help Entries (and separator lines). You can include separator lines among your entries. For example:

Cut
Copy
Paste
------------
Folder  
------------
First Entry
Second Entry
------------
Third Entry
------------
Help

APP_POPUP: Right-Mouse Menu Control

Adding Entries to Right-Mouse Menus

Adding entries to right-mouse menus requires at least two triggers in your form for each entry. The first trigger is the PRE-POPUP-MENU, which can be at block or item level depending on the desired behavior. The PRE-POPUP-MENU trigger calls the APP_POPUP.INSTANTIATE routine to set up the menu entry. This call includes the name, POPUP1 through POPUP10, of the menu entry function. Set the Execution Hierarchy of your trigger to After so your trigger fires after the form-level PRE-POPUP-MENU trigger (which must fire first to check that the user clicked over the field that currently has focus and to set the menu to its default state).

The second trigger is a corresponding user-named trigger called POPUP1 through POPUP10, typically at the block or item level, that contains the functionality you want to execute when a user selects your menu entry. Note that the popup menu entries appear, and if chosen will execute, even if the field is currently disabled, so if your logic should not execute when the field is disabled, you must test for that in your code.

Example Right-Mouse Menu Entry

Suppose you have a special function called "Approve" that you want to add to the right-mouse menu. To add Approve as the first custom entry on the right-mouse menu, such that it is only available in the Requisition Number field of a form, do the following:

  1. Modify the item-level PRE-POPUP-MENU trigger on the Requisition Number field. Be sure to set the trigger Execution Hierarchy to After.

    app_popup.instantiate('POPUP1', 'Approve');

    If you plan to translate your form, you should use Message Dictionary, a parameter, or a static record group cell to store the Special Menu entry. You then retrieve the value (which is translated when the application is translated) into a variable and pass the variable to the APP_SPECIAL routine. For example:

    app_special.instantiate('POPUP1', my_menu_entry);

  2. Add a field level POPUP1 user-named trigger that contains code to actually perform your "Approve" function. It executes when the user chooses this menu entry.

APP_POPUP: Right-Mouse Menu Control

Use the APP_POPUP package to add entries on the right-mouse menus. Entries you add using this package appear between the Folder and the Help entries of the default right-mouse menu for text items.

See: Customizing Right-Mouse Menus (Popup Menus)

APP_POPUP.INSTANTIATE

Summary

procedure APP_SPECIAL.INSTANTIATE(
          option_name        varchar2,
          txt                varchar2,
          initially_enabled  boolean  default true,
          separator          varchar2 default null);

Description

This procedure allows you to add up to 10 custom entries to the default right-mouse menu on a text item.

Call this procedure in a block- or item-level PRE-POPUP-MENU trigger. Set the Execution Hierarchy of the trigger to After so your trigger fires after the form-level PRE-POPUP-MENU trigger (which must fire first to check that the user clicked over the field that currently has focus and to set the menu to its default state).

Arguments (input)

Variable Description
option_name POPUP1 to POPUP10, where POPUP1 is the topmost entry of the ten customizable entries (just below the Folder entry), and POPUP10 is at the bottom (just above the Help entry).
txt Your menu item label. Pass a translated string (if your form is to be translated, you should define a message in Message Dictionary, retrieve the message first, and pass the retrieved message string to APP_POPUP).
initially_enabled A boolean value that lets you set the status of the menu item. If you do not want to enable the item, pass FALSE.
separator Pass 'LINE' to display a menu separator line above your menu entry. Note that the separator line above the first custom entry (just below the Folder entry) is displayed automatically.

Example

APP_POPUP.INSTANTIATE('POPUP1','First Entry'); 
APP_POPUP.INSTANTIATE('POPUP2','Second Entry', TRUE,
                      'LINE'); 
APP_POPUP.INSTANTIATE('POPUP3','Third Entry', FALSE);

results in a menu that looks like the following:

  ------------
        Cut
        Copy
        Paste
        ------------
        Folder
        ------------
        First Entry
        ------------
        Second Entry
        Third Entry   (disabled, so greyed out)
        ------------
        Help
        ------------

APP_SPECIAL: Menu and Toolbar Control

Use the APP_SPECIAL package to enable and customize menu entries and buttons on the toolbar.

See: Application-Specific Entries: Special Menus

APP_SPECIAL.INSTANTIATE

Summary

procedure APP_SPECIAL.INSTANTIATE(
          option_name       varchar2,
          hint varchar2     default null,
          icon varchar2     default null,
          initially_enabled boolean default true,
          separator         varchar2 default null);

Description

This call constructs the special menu according to your specifications. Call this function in the PRE-FORM trigger, after the call to APP_STANDARD.EVENT('PRE-FORM'). When the user chooses an entry on the special menus or presses a corresponding toolbar button, a user-named trigger with the same name as the function is executed.

Arguments (input)

Variable Description
option_name Pass SPECIAL1 to SPECIAL45 to indicate the slot on the special menus in which you want to put your function. SPECIAL1 is at the top of the first of the three special menus, and SPECIAL15 is at the bottom of the first special menu. SPECIAL16 is at the top of the second of the three special menus, and SPECIAL30 is at the bottom of the second special menu. SPECIAL31 is at the top of the third of the three special menus, and SPECIAL45 is at the bottom of the third special menu. When you instantiate any menu entry, the top level menu for the corresponding special menu is enabled.
Check boxes are available on the first special menu only. The check box entries provide a menu entry that includes a check box. Pass SPECIAL1_CHECKBOX to SPECIAL15_CHECKBOX (instead of the corresponding SPECIALn entry) to indicate the slot on the special menu in which you want to put your function. If you use the check box entries, you must also use the APP_SPECIAL.SET_CHECKBOX routine to set the initial value of the check box for the corresponding menu entry.
Pass SPECIAL, SPECIAL_B, or SPECIAL_C to explicitly control one of the three top-level special menus. SPECIAL is at the top of the first of the three special menus, SPECIAL_B is at the top of the second special menu, and SPECIAL_C is at the top of the third special menu. This is typically used to explicitly enable or disable a top-level entry.
hint Your menu item label. Pass a translated string (if your form is to be translated, you should define a message in Message Dictionary, retrieve the message first, and pass the retrieved message string to APP_SPECIAL). Include an '&' in the string to define which character becomes the shortcut key for that item (this is the same as the behavior in the Oracle Forms Form Builder. For example, '&Book Orders'). You can change the label for SPECIAL_B (Reports) or SPECIAL_C (Actions), but you cannot change the label of the SPECIAL menu (Tools). In addition, you cannot specify an access key for SPECIAL_B or SPECIAL_C.
icon If you want to include an iconic button on the toolbar for the function, give the name of the icon. Any of the SPECIAL1 through SPECIAL45 functions can include a corresponding toolbar button (though you should limit the number of extra icons on the toolbar for aesthetic reasons). If there is no corresponding toolbar button, pass NULL. SPECIALn_CHECKBOX entries cannot have icons on the toolbar.
For custom forms, the icon file must be a .gif file located in the directory designated by the OA_MEDIA virtual directory (see your web server administrator for this information). Note that retrieving the icon file for a custom icon requires a round trip to the forms server, so you should limit the number of icons you retrieve if performance becomes an issue.
For Oracle E-Business Suite products, icon files are included in a .jar file included in the Oracle E-Business Suite installation.
initially_enabled A boolean value that lets you set the initial status of the menu item. If you do not want to enable the item when your application starts, pass FALSE. The default value is TRUE.
separator Pass 'LINE' to display a menu separator line above your menu entry. The LINE argument is ignored for SPECIAL1(_CHECKBOX), SPECIAL16, or SPECIAL31. The default is no line.

Example 1

APP_SPECIAL.INSTANTIATE('SPECIAL3','&Book Order', 'POBKORD', TRUE, 'LINE');

Example 2

app_special.instantiate('SPECIAL12_CHECKBOX',
                        'Specia&l 12 Check Box with Line',
                         separator=>'LINE'); 
app_special.set_checkbox('SPECIAL12_CHECKBOX','TRUE');

results in a menu entry that looks like the following:

-----------------------------------
[x] Speciall 12 Check Box with Line

APP_SPECIAL.ENABLE

Summary

procedure APP_SPECIAL.ENABLE(
          option_name varchar2, 
                          state number);

Description

This call controls the enabling and disabling of the items in the menu, including the Special menu (and their corresponding toolbar buttons), allowing you to customize your menus for each block.

If a special function is available for most of the blocks in a form, create a form level PRE-BLOCK trigger that enables the function. For any block where this is not a valid function, code a block level PRE-BLOCK trigger with Execution Hierarchy set to Override that disables the function.

See: Menu and Toolbar Entries

Enable and disable SAVE to control the 'File->Save' and 'File->Save and Enter Next' menu entries. Save is automatically disabled when you call APP_FORM.QUERY_ONLY MODE.

Before entering a modal window that allows access to the menu, call APP_SPECIAL.ENABLE('MODAL', PROPERTY_OFF). When you leave the block, call ENABLE again with PROPERTY_ON. PROPERTY_OFF disables the menu items that are disallowed in a modal block.

You can control the availability of the ATTACHMENTS, TRANSLATION, SUMMARY/DETAIL, and SELECT_ALL menu entries.

Use the SINGLE option to disable the first record, last record, previous record, and next record options on the Go menu in a block with only one available record.

See: Single Record Blocks

Use the ABOUT option to disable the Help->Record History menu option.

Arguments (input)

Variable Description
option_name The name of the option to be enabled. Possible values include: ABOUT, ATTACHMENTS, MODAL, SAVE, SELECT_ALL, SINGLE, SPECIAL1, ...through SPECIAL45 (or SPECIALn_CHECKBOX entries), SPECIAL, SPECIAL_B, SPECIAL_C, SUMMARY/DETAIL, TRANSLATION, or the full name of any menu item. Setting SPECIAL to PROPERTY_OFF disables all special menu items.
state Either PROPERTY_ON or PROPERTY_OFF

Example

 APP_SPECIAL.ENABLE('SPECIAL3',PROPERTY_ON);

APP_SPECIAL.GET_CHECKBOX

Summary

function APP_SPECIAL.GET_CHECKBOX
         (option_name varchar2)
                          RETURN       varchar2;

Description

Use this procedure to get the current value of a check box in one of the special menus. Call this procedure within the trigger that gets executed by the check box entry on the first special menu. This function returns the state of the checkbox menu item as either the string 'TRUE' if the check box is checked or 'FALSE' if the check box is not checked. This call will result in an error if the menu entry does not exist.

Arguments (input)

Variable Description
option_name Pass SPECIAL1_CHECKBOX to SPECIAL45_CHECKBOX to indicate the special menu entry for which you want to get the value.

Example

 if (app_special.get_checkbox('SPECIAL3_CHECKBOX')='TRUE') then
            fnd_message.debug('Special 3 is True!'); 
    else
            fnd_message.debug('Special 3 is False!'); end if;

APP_SPECIAL.SET_CHECKBOX

Summary

procedure APP_SPECIAL.SET_CHECKBOX(
                     option_name varchar2,
          new_value varchar2);

Description

Use this procedure to set the initial value of a check box in one of the special menus. Call this procedure after instantiating the corresponding check box menu entry on a special menu.

Arguments (input)

Variable Description
option_name Pass SPECIAL1_CHECKBOX to SPECIAL15_CHECKBOX to indicate the special menu entry for which you want to set the value.
new_value Pass the character string 'TRUE' to set the check box to checked or 'FALSE' to set the check box to unchecked.

Example

app_special.instantiate('SPECIAL3_CHECKBOX',
                         'Spe&cial 3 Box with Line',
                         '',TRUE,'LINE'); 
app_special.set_checkbox('SPECIAL3_CHECKBOX','TRUE'); 
app_special.instantiate('SPECIAL4_CHECKBOX',
                        'Special &4 Box'); 
app_special.set_checkbox('SPECIAL4_CHECKBOX','TRUE');