Click above to get retro games delivered to your door ever month!

Function:    POPUPPICK()

Purpose:     Generic pop-up pick list handler

Syntax:      POPUPPICK( t, l, b, r, disp_field [, message, [, box_title,;
                        [, rtrn_field [, alias [, color ] ] ] ] ] )

Arguments:   t,l,b,r     - Top, Left, Bottom, Right window coordinates
                           bound checked to be within 0,0 to 24,79.  Also,
                           if the left + width of disp_field would cause
                           the display to overflow the right side of the
                           window, the display is truncated as per
                           PICKREC()

             disp_field  - Character string which is the name of the
                           database field or expression  to display in a
                           PICKREC() box.  This may be any expression that
                           evaluates to a character string.

             message     - Optional message to display on line 24.  If
                           omitted or an invalid or empty character
                           parameter is given, then default message will
                           be: "Choose with .., select with .-+, or
                           press ESCAPE to quit" it will be centered on
                           row 24.  In the Clipper 5.0 version the message
                           is displayed on MAXROW().

             box_title   - Optional character string indicating the title
                           to appear in the pop-up box header area.  If no
                           title is specified, the box will have no header
                           area.

             rtrn_field  - Optional character string indicating the field
                           or expression to return as the selected value.
                           This may be any expression.  If omitted or a
                           non-character parameter is supplied, the
                           default field is [disp_field].

             alias       - Optional character string indicating the name
                           of the database work area to select for the
                           pop-up.  If omitted or a non-character
                           parameter is given, the default is the current
                           work area, ALIAS().

             color       - Optional array of color settings used to govern
                           the colors of various parts of the display.
                           This color array has the same structure as the
                           color array required by PICKREC().  See the
                           table below.

Returns:     Selected <rtrn_field> contents, or a null string if escape
             pressed.

Description: POPUPPICK() is a database function to provide a pop-up
             listing for a database.  It is particularly helpful in
             applications where you need a consistent convention for
             calling help pick lists.  POPUPPICK() is also very useful for
             creating pick lists in data entry validation functions.

Notes:       The first five parameters are required.  If any of the
             remaining parameters are to be skipped, you must pass a dummy
             parameter such as a null in its place.  The message is
             displayed on line 24 (or MAXROW() in the 5.0 version) in the
             current color setting before the color is changed.

             POPUPPICK() assumes the required database(s) is/are already
             opened.  The database need not be SELECTed if the alias name
             parameter is specified.

             <colors>

             Element#  Description                Default               
             color[1]  Normal text display        Standard - SETCOLOR()
             color[2]  Selected or Marked         BRIGHT() Standard
             color[3]  Hi-lited (scroll bar)      Enhanced
             color[4]  Hi-lited & Selected/Marked Enhanced/Bright/Blinking
             color[5]  Color on exit from XITKEYS BRIGHT() Standard
             color[6]  Normal text IF (color[8])  Standard - SETCOLOR()
             color[7]  Hi-lited IF (color[8])     Enhanced
             color[8]  Character condition        (.T.)


Example:     *------------------------------------------------------------
             * Procedure: Help
             * Purpose:   Help facility, called with SET KEY 28 TO Help
             *------------------------------------------------------------
             PROCEDURE Help
             PARAMETERS callproc, linenum, readvar
             PRIVATE htop, hleft, hbottom, hright, houtput, hmessage
             PRIVATE htitle, hfield, halias, hpick


             *-- By default, Clipper starts every application with the F1
             *-- key set to call Help.  This is equivilent to issuing the
             *-- command: SET KEY 28 TO Help.  Since we don't want Help to
             *-- be called recursively while in Help, we need to disable
             *-- the F1 help key with the following command:
             SET KEY 28 TO

             IF readvar == "VENDOR"
                htop     =  1
                hleft    = 78            && will force right alignment
                hbottom  = 22
                hright   = 79
                houtput  = "' '+VENDOR->name"
                hmessage = "Select a vendor from the following list"
                htitle   = "VENDOR LISTING"
                hfield   = "VENDOR->name"
                halias   = "Vendors"
                hpick    = PopUpPick( htop, hleft, hbottom, hright,;
                                      houtput, hmessage, htitle,;
                                      hfield, halias )

                IF LASTKEY() != 27
                   M->vendor = STRETCH( hpick, LEN(M->vendor) )
                ENDIF
             ENDIF

             *-- ok, now turn Help back on
             SET KEY 28 TO help
             RETURN

Source:      RL_POPUP.PRG

See also:    PICKREC(), RH_HEADER(), RH_LINES(), RH_TEXT(), RH_WIDTH()