Share via

DEFINE POPUP Command

  • Article

Creates a menu.

DEFINE POPUP MenuName [FROM nRow1, nColumn1] [TO nRow2, nColumn2]
   [IN [WINDOW] WindowName | IN SCREEN] [FONT cFontName [, nFontSize]]
   [STYLE cFontStyle] [FOOTER cFooterText] [KEY KeyLabel] [MARGIN]
   [MARK cMarkCharacter] [MESSAGE cMessageText] [MOVER] [MULTISELECT] 
   [PROMPT FIELD FieldName | PROMPT FILES [LIKE FileSkeleton] 
      | PROMPT STRUCTURE] [RELATIVE] [SCROLL] [SHORTCUT]
   [TITLE cMenuTitleText] 
   [COLOR SCHEME nSchemeNumber | COLOR ColorPairList]

Parameters

  • MenuName
    Specifies the name of the menu to create.

  • FROM nRow1, nColumn1 TO nRow2, nColumn2
    Specifies where the menu is placed. nRow1, nColumn1 specifies coordinates for the upper-left corner of the menu. If you omit the FROM clause, Visual FoxPro places the upper-left corner of the menu in the first row and first column of the main Visual FoxPro window or a user-defined window.

    To create a menu with a specific size, you can also include TO nRow2, nColumn2 to specify the location of the lower-right corner of the menu. If you include FROM nRow1, nColumn1 and omit TO nRow2, nColumn2, Visual FoxPro automatically sizes the menu. The menu is as wide as the longest menu item in it (if the items are created with DEFINE BAR) and as long as needed to display all of the menu items. The menu length is limited by the size of the main Visual FoxPro window or user-defined window in which the menu is placed. If a menu isn't large enough to contain all of the menu items, a scroll bar appears so that you can scroll through the menu items.

  • IN [WINDOW] WindowName
    Places a menu in a user-defined window you specify with WindowName. If you omit this clause, the menu is placed on the main Visual FoxPro window by default unless there is an active user-defined window. If there is an active user-defined window, the menu is placed in the active window.

  • IN SCREEN
    Explicitly places a menu in the main Visual FoxPro window.

  • FONT cFontName [, nFontSize]
    Specifies a default font for the menu. You can override the default font for an individual menu item by including the FONT clause in DEFINE BAR.

    cFontName specifies the name of the font, and nFontSize specifies the point size. For example, the following command creates a menu in 12-point Courier font:

    DEFINE POPUP popMyPopup FONT 'Courier', 12

    If the font you specify is not available, a font with similar font characteristics is substituted. If you include the FONT clause but omit the point size nFontSize, a 10-point font is used.

  • STYLE cFontStyle
    Specifies a default font style for the menu. You can override the default style for an individual menu item by including the FONT clause in DEFINE BAR.

    If you omit the STYLE clause, or if the font style you specify is not available, the Normal font style is used.

    The font styles you can specify with cFontStyle are listed in the following table:

    Character Font style
    B Bold
    I Italic
    N Normal
    Q Opaque
    - Strikeout
    T Transparent
    U Underline

    You can include more than one character to specify a combination of font styles. For example, the following command specifies Bold Italic:

    DEFINE MENU popMyPopup STYLE 'BI'

  • FOOTER cFooterText
    Creates a footer with the text specified with cFooterText centered in the bottom border of the menu.

  • KEY KeyLabel
    Specifies an access key or key combination for a menu. For a list of available keys and key combinations and their key label names, see ON KEY LABEL.

    Including KEY is equivalent to issuing the following command:

    ON KEY LABEL KeyLabel ACTIVATE POPUP MenuName

    Note   If a keyboard macro is already defined with the same key label, the keyboard macro takes precedence, and the menu cannot be activated with the specified key or key combination.

  • MARGIN
    Places an extra space to the left and right of each menu item. Mark characters are displayed in the space to the left of an item, and arrows indicating additional cascading submenus are available and are displayed to the right of menu items. If you omit MARGIN, the mark characters overwrite the first character of the menu item names; hierarchical arrows overwrite the last character of the menu items.

    Note   You must include this clause if you want to use the DEFINE BAR ... PICTURE or PICTRES clauses.

  • MARK cMarkCharacter
    Specifies a character that appears to the left of an item on the menu. The default mark character is a check mark. The MARK clause is ignored and the default mark character is used if the menu is integrated into the Visual FoxPro system menu. Also, the MARK clause is ignored if FoxFont isn't the font for the main FoxPro window or the user-defined window in which the menu is placed.

    MARK can be included to change the default mark character to a character specified with cMarkCharacter. If cMarkCharacter includes more than one character, only the first character is used as the mark character.

    Note   Specifying a mark character doesn't mark a menu item. Use SET MARK OF to mark a menu item.

    The MARK clause sets the mark character for all items on the menu. Mark characters specified with DEFINE BAR commands take precedence over mark characters specified with the MARK clause in DEFINE POPUP. SET MARK OF is used to toggle mark characters on or off and can also be used to specify a mark character for an individual menu item or for all menu items.

  • MESSAGE cMessageText
    Displays a message when you select a menu item. The message is placed in the graphical status bar. If the character-based status bar is turned on with SET STATUS ON, the message is centered on the last line of the main Visual FoxPro window.

  • MOVER
    Places a double-headed arrow in the Mover box to the left of the selected item in the menu. You can drag the double-headed arrow to move an item to another position on the menu. GETBAR( ) can be used to determine where each item is positioned on the menu.

    You cannot rearrange items in a menu created with a PROMPT clause.

  • MULTISELECT
    Allows the user to select multiple items from a menu at the same time. When the user chooses an item from a menu, the mark character is placed to the left of the item.

    You cannot make multiple selections from a menu created with a PROMPT clause.

    MRKBAR( ) can be used to determine which items are chosen from the menu.

    If you include MULTISELECT in DEFINE POPUP, you can include MARGIN to reserve space in each item for the mark character.

    In the following example, a menu named popFruits is created. MULTISELECT is included to create a menu that allows multiple items to be chosen.

    Each of the four items has a different mark character. When a user chooses items from the menu, the items are marked and a routine named yourchoice displays the chosen items.

    CLEAR
IF NOT _DOS
   MODIFY WINDOW SCREEN FONT 'foxfont', 12
ENDIF
ACTIVATE SCREEN
DEFINE POPUP popFruits FROM 5,5 ;
   MULTISELECT MARGIN            && Create multi-choice menu
DEFINE BAR 1 OF popFruits ;
   PROMPT '\<Apples'  MARK CHR(3)    && First item
DEFINE BAR 2 OF popFruits ;
   PROMPT '\<Bananas' MARK CHR(4)    && Second item
DEFINE BAR 3 OF popFruits ;
   PROMPT '\<Grapes'  MARK CHR(5) && Third item
DEFINE BAR 4 OF popFruits ;
   PROMPT '\<Lemons'  MARK CHR(6)    && Fourth item
@ 12,5 SAY 'Your choices:'
ON SELECTION POPUP popFruits DO yourchoice    && Choice routine
ACTIVATE POPUP popFruits 
PROCEDURE yourchoice            && Executed when choice is made
@ 13,5 CLEAR
FOR gnCount = 1 TO CNTBAR('popFruits')      && Loop for # of items
   IF MRKBAR('popFruits', gnCount) = .T.      && Option is marked,
      ? PRMBAR('popFruits', gnCount) AT 5      && display caption
   ENDIF
NEXT

  • PROMPT FIELD FieldName
    Specifies the field name from an open table whose records become the items on the menu. The menu contains an item for each record in the table. When the menu is activated, the tables' work area is selected.

    Tip   You can take advantage of Rushmore Query Optimization if you set a filter on the field specified with PROMPT FIELD used in the menu. For more information on Rushmore Query Optimization, see SET OPTIMIZE and Using Rushmore Query Optimization to Speed Data Access in Optimizing Applications.

    FieldName can also contain multiple field names and expressions concatenated with the addition operator (+). FieldName can also be the name of the field in a table open in another work area or a user-defined function.

    There is no limit to the number of entries that can appear in a menu created with PROMPT FIELD.

  • PROMPT FILES [LIKE FileSkeleton]
    Creates a menu that displays the names of files available in the current directory.

    LIKE FileSkeleton allows you to specify the files that are displayed in the menu using wildcards. For example, to create a menu that displays the names of tables in the default drive and directory, include the following command:

    PROMPT FILES LIKE *.DBF

    You can create a menu that displays the names of files on other drives and in other directories or folders by including a drive or volume specification, a directory specification, or both. For example, to create a menu that displays the names of program files in a directory called PROGRAMS on drive C, include the following command:

    PROMPT FILES LIKE C:\PROGRAMS\*.PRG

  • PROMPT STRUCTURE
    Displays the names of the fields in the current table on the menu according to the table's field structure. When the menu is activated, the table's work area is selected.

  • RELATIVE
    Specifies the order in which items are placed on a menu. If you create a menu without the RELATIVE clause, an item is positioned on a menu in an order dictated by the item's bar number. Space on the menu is reserved for undefined items. For example, if the first and third items are defined and the menu is activated, a blank line reserved for the second item is placed on the menu.

    If you create a menu with RELATIVE, the items appear on the menu in the order in which they are defined. Space in the menu isn't reserved for undefined items.

    Defining a menu with RELATIVE also lets you make use of BEFORE and AFTER clauses in DEFINE BAR to position items on a menu relative to other items. If a menu is created without RELATIVE, including BEFORE or AFTER in DEFINE BAR generates an error.

    Run the following two program examples and compare the placement of the items on each menu.

** RELATIVE Example ** DEFINE POPUP popRelatYes RELATIVE FROM 1,1 DEFINE BAR 4 OF popRelatYes PROMPT '4444' DEFINE BAR 3 OF popRelatYes PROMPT '3333' DEFINE BAR 2 OF popRelatYes PROMPT '2222' DEFINE BAR 1 OF popRelatYes PROMPT '1111' DEFINE BAR 6 OF popRelatYes PROMPT '6666' BEFORE 4 ACTIVATE POPUP popRelatYes ** NON-RELATIVE Example ** DEFINE POPUP popRelatNo FROM 1,1 DEFINE BAR 4 OF popRelatNo PROMPT '4444' DEFINE BAR 3 OF popRelatNo PROMPT '3333' DEFINE BAR 2 OF popRelatNo PROMPT '2222' DEFINE BAR 1 OF popRelatNo PROMPT '1111' DEFINE BAR 6 OF popRelatNo PROMPT '6666' ACTIVATE POPUP popRelatNo

  • SCROLL
    Places a scroll bar to the right of the menu you create. The scroll bar is displayed only when there are more items than can fit on the menu, or if the menu is too long to fit in the main Visual FoxPro window or the user-defined window in which it is placed.

  • SHORTCUT
    Creates a shortcut menu. A shortcut menu typically appears when a selection, toolbar, or taskbar button is clicked with the right mouse button. The shortcut menu lists commands that pertain to the screen region on which the mouse was right-clicked.

    You can include MROW( ) and MCOL( ) in the FROM clause to activate the popup at the location where the mouse is clicked.

  • TITLE cMenuTitleText
    Displays a title in the center of the top border of the menu. cTitleText specifies the menu title.

  • COLOR SCHEME nSchemeNumber
    Specifies the colors for all elements of a menu. By default, the colors of menus created with DEFINE POPUP are controlled by color scheme 2.

  • COLOR ColorPairList
    Specifies the colors for all elements of a menu.

Remarks

To place a set of menu items that you define on a menu, use a series of DEFINE BAR commands. To place records, files, or fields in a menu, use the PROMPT FIELD, PROMPT FILES, or PROMPT STRUCTURE options of DEFINE POPUP.

When the menu is displayed and activated with ACTIVATE POPUP, you can choose one of the items on the menu. Depending on the item chosen, a routine can be executed or another menu can be displayed and activated. A menu that displays another menu when an item is chosen is called a cascading submenu. For more information on creating submenus, see ON BAR.

If you use the Menu Designer to create your menu, you may not have to use these commands at all. The Menu Designer automatically creates the commands for your menu. The Menu Designer uses the Visual FoxPro system menu, which you can then modify by adding your own menu items.

For more information on creating menus, see Menu System Creation.

Example

The following example uses DEFINE POPUP to create menus that are activated when a menu title in the menu bar is chosen. The current system menu bar is first saved to memory with SET SYSMENU SAVE, and then all system menu titles are removed with SET SYSMENU TO.

Two new system menu titles are created with DEFINE PAD, and DEFINE POPUP creates a drop-down menu for each menu title. DEFINE BAR creates items on each of the menus. When a menu title is chosen, ON PAD uses ACTIVATE POPUP to activate the corresponding menu.

When an item is chosen from a menu, ON SELECTION POPUP uses PROMPT( ) and POPUP( ) to pass the item number and menu name to the CHOICE procedure. CHOICE displays the text of the chosen item and the name of the menu containing the item. If the Exit item is chosen from the Card Info menu, the original Visual FoxPro system menu is restored.

** Name this program DEFINPOP.PRG ** CLEAR SET SYSMENU SAVE SET SYSMENU TO DEFINE PAD convpad OF _MSYSMENU PROMPT '<Conversions' COLOR SCHEME 3 ; KEY ALT+C, '' DEFINE PAD cardpad OF _MSYSMENU PROMPT 'Card <Info' COLOR SCHEME 3 ; KEY ALT+I, '' ON PAD convpad OF _MSYSMENU ACTIVATE POPUP conversion ON PAD cardpad OF _MSYSMENU ACTIVATE POPUP cardinfo DEFINE POPUP conversion MARGIN RELATIVE COLOR SCHEME 4 DEFINE BAR 1 OF conversion PROMPT 'Ar<ea' KEY CTRL+E, '^E' DEFINE BAR 2 OF conversion PROMPT '<Length' ; KEY CTRL+L, '^L' DEFINE BAR 3 OF conversion PROMPT 'Ma<ss' ; KEY CTRL+S, '^S' DEFINE BAR 4 OF conversion PROMPT 'Spee<d' ; KEY CTRL+D, '^D' DEFINE BAR 5 OF conversion PROMPT '<Temperature' ; KEY CTRL+T, '^T' DEFINE BAR 6 OF conversion PROMPT 'T<ime' ; KEY CTRL+I, '^I' DEFINE BAR 7 OF conversion PROMPT 'Volu<me' ; KEY CTRL+M, '^M' ON SELECTION POPUP conversion; DO choice IN definpop WITH PROMPT( ), POPUP( ) DEFINE POPUP cardinfo MARGIN RELATIVE COLOR SCHEME 4 DEFINE BAR 1 OF cardinfo PROMPT '<View Charges' ; KEY ALT+V, '' DEFINE BAR 2 OF cardinfo PROMPT 'View <Payments' ; KEY ALT+P, '' DEFINE BAR 3 OF cardinfo PROMPT 'Vie<w Users' ; KEY ALT+W, '' DEFINE BAR 4 OF cardinfo PROMPT '-' DEFINE BAR 5 OF cardinfo PROMPT '<Charges ' DEFINE BAR 6 OF cardinfo PROMPT '-' DEFINE BAR 7 OF cardinfo PROMPT 'E<xit ' ON SELECTION POPUP cardinfo; DO choice IN definpop WITH PROMPT( ), POPUP( ) PROCEDURE choice PARAMETERS mprompt, mpopup WAIT WINDOW 'You chose ' + mprompt + ; ' from popup ' + mpopup NOWAIT IF mprompt = 'Exit' SET SYSMENU TO DEFAULT ENDIF

See Also

ACTIVATE POPUP | CNTBAR( ) | CREATE MENU | DEFINE BAR | GETBAR( ) | HIDE POPUP | MOVE POPUP | MRKBAR( ) | ON BAR | ON SELECTION BAR | POPUP( ) | PRMBAR( ) | PROMPT( ) | RELEASE POPUPS | SET MARK OF | SET MESSAGE | SIZE POPUP | SHOW POPUP