4D Doc Center : Pop up menu

4D v13.4

Pop up menu


Pop up menu ( contents {; default {; xCoord ; yCoord}} ) -> Function result

Parameter	Type	Description
contents	Text	Menu text definition
default	Longint	Number of menu item selected by default
xCoord	Longint	X coordinate of upper left corner
yCoord	Longint	Y coordinate of upper left corner
Function result	Longint	Selected menu item number

Description

The Pop up menu command displays a pop-up menu at the current location of the mouse.

In order to follow user interface rules, you usually call this command in response to a mouse click and if the mouse button is still down.

You define the items of the pop-up menu with the parameter contents as follows:

Separate each item from the next one with a semi-colon (;). For example, "ItemText1;ItemText2;ItemText3".
To disable an item, place an opening parenthesis (() in the item text.
To specify a separation line, pass "-" or "(-" as item text.
To specify a font style for a line, place in the item text a less than sign (<) followed by one of these characters:
<B Bold
<I Italic
<U Underline
<O Outline (Macintosh only)
<S Shadow (Macintosh only)

To add a check mark to an item, place in the item text an exclamation mark (!) followed by the character you want as a check mark.
- On Macintosh, the character is displayed directly. To display the standard check mark whatever the system version or language, use the following statement: Char(18).
- On Windows, a check mark is displayed, no matter what character you passed.
To add an icon to an item, place in the item text a circumflex accent (^) followed by a character whose code plus 208 is the resource ID of a Mac OS-based icon resource.
To add a shortcut to an item, place in the item text a slash (/) followed by the shortcut character for the item. Note that this last option is purely informative; no shortcut will activate the pop-up menu. However, you may want to include a shortcut if the pop-up menu item has an equivalent in the main menu bar of your application.

Tip: It is possible to disable the mechanism for interpreting special characters (!, /, etc.) in the pop up menu in order, for example, to have these characters included in the wording. To do this, simply have the contents parameter begin with the statement Char(1) then use this statement as a separator:

contents:=Char(1)+"1/4"+Char(1)+"1/2"+Char(1)+"3/4")

Note that once this statement has been executed, it is no longer possible to assign styles or shortcuts to the pop up menu.

The optional default parameter specifies the default menu item selected when the pop-up menu is displayed. Pass a value between 1 and the number of menu items. If you omit this parameter, the command selects the first menu item as the default.

The optional xCoord and yCoord parameters designate the location of the pop-up menu to be displayed. In xCoord and yCoord, pass respectively the horizontal and vertical coordinates of the upper left corner of the menu. These coordinates must be expressed in pixels in the local coordinate system of the current form. These two parameters must be passed together; if only one is passed, it will be ignored.

If you use the xCoord and yCoord parameters, the default parameter is ignored. In this case, the mouse is not necessarily located at the level of the pop-up menu.

These parameters are particularly useful for managing 3D buttons with an associated pop-up menu.

If you select a menu item, the command returns its number; otherwise, it returns zero (0).

Note: Use pop-up menus that have a reasonable number of items. If you want to display more than 50 items, you might think about a using scrollable area in a form instead of a pop-up menu.

Example

The project method MY SPEED MENU pulls down a navigation speed menu:

  // MY SPEED MENU project method

 GET MOUSE($vlMouseX;$vlMouseY;$vlButton)

 If(Macintosh control down|($vlButton=2))

    $vtItems:="About this database...<I;(-;!-Other Options;(-"

    For($vlTable;1;Get last table number)

       If(Is table number valid($vlTable))

          $vtItems:=$vtItems+";"+Table name($vlTable)

       End if

    End for

    $vlUserChoice:=Pop up menu($vtItems)

    Case of

       :($vlUserChoice=1)

  // Display Information

       :($vlUserChoice=2)

  // Display options

       Else

          If($vlUserChoice>0)

  // Go to table whose number is $vlUserChoice-4

          End if

    End case

 End if

This project method can be called from:

The method of a form object that reacts to a mouse click without waiting for the mouse button to be released (i.e., an invisible button)
A process that “spies” events and communicate with the other processes
An event-handling method installed using ON ERR CALL.

In the last two cases, the click does not need to occur in any form object. This is one of the advantages of the Pop up menu command. Generally, you use form objects to display pop-up menus. Using Pop up menu, you can display the menu anywhere.

The pop-up menu is displayed on Windows by pressing the right mouse button; it is displayed on Macintosh by pressing Control-Click. Note, however, that the method does not actually check whether or not there was a mouse click; the caller method tests that.

The following is the pop-up menu as it appears on Windows (left) and Macintosh (right). Note the standard check mark for the Windows version.