HB_Alert

HB_Alert

Displays a text-mode dialog box with a message.

Syntax

      HB_Alert( <xMessage>, [<aOptions>], [<cColor>], [<nDelay>] ) --> nChoice

Arguments

<xMessage> : The message to display. May be any data type. Character string may be divided display lines by the semicolon

<aOptions> : An array with available response as character strings. Default is { “Ok” }.

<cColor> : A string as color codes. Default color is “W+/R”.

<nDelay> : Number of seconds to wait to user response before abort. Default value is 0, that wait forever.

Returns

A numeric value indicating the ordinal position within <aOption> selected by the user. Zero value means that user pressed escape key.

If <nDelay> is specified and this number of seconds has elapsed without a key press, the return value is 1.

Description

HB_Alert() displays a dialog box and lets the user select an option. The user can move a highlight bar using arrow keys or the TAB key. To select an option, the user can press ENTER, SPACE or the first letter of an option.

HB_Alert() is extended version of Alert() to support all variables types (not just strings) is passed as first parameter.

Example

      // This example displays a message with two line : file name and 'not found' message.
      // After 15 seconds without user response, assumed 'Abort' selected.

      FUNCTION FNFMessage( cFileName )

         LOCAL cMessage, aOptions, nChoice

         aMessage := { cFileName, 'Not found !' }
         aOptions :=  { 'Abort', 'Retry', 'Skip' }

         nChoice := HB_Alert( aMessage, aOptions, , 15 )

      RETURN nChoice // FNFMessage()

Seealso

@…PROMPT, AChoice(), Alert(), DispBox(), DispOut(), MENU TO

WAIT

WAIT*

Suspend program processing until a key is pressed

Syntax

      WAIT [<expPrompt>] [TO <idVar>]

Arguments

<expPrompt> is an expression of any data type displayed as a prompt. If no <expPrompt> is specified, the default prompt displayed is: “Press any key to continue…”

TO <idVar> is the variable, of any storage class, that holds the value of the key pressed as a character value. If <idVar> does not exist or is not visible, it is created as a private variable and then assigned the character value.

Description

WAIT is a console command and wait state that displays a prompt after sending a carriage return/line feed to the screen. It then waits for the user to press a key. If the TO clause is specified, <idVar> is assigned the keystroke as a character value. If an Alt or Ctrl key is pressed, WAIT assigns CHR(0) to <idVar>. Non-alphanumeric values entered by pressing an Alt-keypad combination assign the specified character. If the character can be displayed, it is echoed to the screen. Function keys are ignored unless assigned with SET FUNCTION or SET KEY.

WAIT is a compatibility command and, therefore, is not recommended for general usage. It is superseded by both @…GET/READ and INKEY() for getting single character input.

Notes

. WAITing without a prompt: To pause execution without displaying a prompt, specify WAIT, null string (“”), or INKEY(0). The latter is recommended since it does not disturb the current screen cursor position.

Examples

      .  This example illustrates how to store the WAIT keystroke as an
         array element:

      aVar := ARRAY(6)

      WAIT "Press a key..." TO aVar[1]
      ? aVar[1]                  // Result: key pressed in
                                 // response to WAIT
      ? aVar[2]                  // Result: NIL
      ? VALTYPE(aVar)            // Result: A
      ? VALTYPE(aVar[1])         // Result: C

Seealso

@…GET, ACCEPT*, INKEY(), INPUT*, MENU TO

ReadVar()

READVAR()

Return variable name of current GET or MENU

Syntax

      READVAR( [<cVarName>] ) --> cOldVarName

Arguments

<cVarName> is a new variable name to set.

Returns

READVAR() return the old variable name. If no variable previously was set, READVAR() return “”.

Description

READVAR() is set inside a READ or MENU TO command to hold the uppercase name of the GET / MENU TO variable, and re-set back to old value when those commands finished. You should not normally set a variable name but rather use it to retrieve the name of a GET variable when executing a VALID or WHEN clause, or during SET KEY execution and you are inside a READ or MENU TO.

Examples

      // display a menu, press F1 to view the MENU TO variable name
      CLS
      @ 1, 10 PROMPT "blood sucking insect that infect beds   "
      @ 2, 10 PROMPT "germ; virus infection                   "
      @ 3, 10 PROMPT "defect; snag; (source of) malfunctioning"
      @ 4, 10 PROMPT "small hidden microphone                 "
      @ 6, 10 SAY "(Press F1 for a hint)"
      SET KEY 28 TO ShowVar
      MENU TO What_Is_Bug

      PROCEDURE ShowVar
         Alert( ReadVar() )     // WHAT_IS_BUG in red ALERT() box

Compliance

READVAR() works exactly like CA-Cl*pper’s READKEY().

Note however, that the <cVarName> parameter is not documented and used internally by CA-Cl*pper.

Platforms

All

Files

Library is rtl

Seealso

@…GET, @…PROMPT, MENU TO, READ, SET KEY, __AtPrompt(), __MenuTo()

SET WRAP

SET WRAP

Toggle wrapping the PROMPTs in a menu.

Syntax

      SET WRAP on | OFF | (<lWrap>

Arguments

<lWrap> Logical expression for toggle

Description

This command toggles the highlighted bars in a @…PROMPT command to wrap around in a bottom-to-top and top-to-bottom manner. If the value of the logical expression <lWrap> is a logical false (.F.), the wrapping mode is set OFF; otherwise, it is set ON.

Examples

      See tests/menutest.prg

Compliance

Clipper

Seealso

@…PROMPT, MENU TO

SET MESSAGE

SET MESSAGE

Establishes a message row for @…PROMPT command

Syntax

      SET MESSAGE TO [<nRow> [CENTER]]

Arguments

<nRow> Row number to display the message

Description

This command is designed to work in conjunction with the MENU TO and @…PROMPT commands. With this command, a row number between 0 and MaxRow() may be specified in <nRow>. This establishes the row on witch any message associated with an @…PROMPT command will appear.

If the value of <nRow> is 0, all messages will be suppressed. All messaged will be left-justifies unless the CENTER clause is used. In this case, the individual messages in each @…PROMPT command will be centered at the designated row (unless <nRow> is 0). All messages are independent; therefore, the screen area is cleared out by the centered message will vary based on the length of each individual message.

Specifying no parameters with this command set the row value to 0, witch suppresses all messages output. The British spelling of CENTRE is also supported.

Examples

      See tests/menutest.prg

Compliance

Clipper

Seealso

Set(), SET WRAP, @…PROMPT, MENU TO

MENU TO

MENU TO

Invoked a menu defined by set of @…PROMPT

Syntax

      MENU TO <cVariable>

Arguments

<cVariable> is a character string that contain the name of the variable to hold the menu choices, if this variable does not exist a PRIVATE variable with the name <cVariable> would be created to hold the result.

Description

Menu To() invoked the menu define by previous __AtPrompt() call and display a highlight bar that the user can move to select an option from the menu. If <cVariable> does not exist or not visible, a PRIVATE variable named <cVariable> is created and hold the current menu selection. If there is a variable named <cVariable>, its value is used to select the first highlighted item.

Menu prompts and messages are displayed in current Standard color, highlighted bar is displayed using current Enhanced color.

Pressing the arrow keys move the highlighted bar. When a menu item is highlighted the message associated with it is displayed on the line specified with SET MESSAGE. If SET WRAP is ON and the user press UP arrow while on the first selection the last menu item is highlighted, if the user press Down arrow while on the last item, the first item is highlighted.

Following are active keys that handled by Menu To:

       key            Meaning
       -------------- ---------------------------------
       Up             Move to previous item
       Down           Move to next item
       Left           Move to previous item
       Right          Move to next item
       Home           Move to the first item
       End            Move to the last item
       Page-Up        Select menu item, return position
       Page-Down      Select menu item, return position
       Enter          Select menu item, return position
       Esc            Abort selection, return 0
       First letter   Select next menu with the same first letter,
                      return this item position.

Upon exit the cursor is placed at MaxRow()-1, 0 Menu To can be nested without loosing the previous prompts.

MENU TO command is preprocessed into __MenuTo() function during compile time.

Examples

      // display menu item on each screen corner and let user select one
      CLS
      SET MESSAGE TO MaxRow() / 2 CENTER
      SET WRAP ON
      @ 0           , 0             PROMPT "1. Upper left"   MESSAGE " One "
      @ 0           , MaxCol() - 16 PROMPT "2. Upper right"  MESSAGE " Two "
      @ MaxRow() - 1, MaxCol() - 16 PROMPT "3. Bottom right" MESSAGE "Three"
      @ MaxRow() - 1, 0             PROMPT "4. Bottom left"  MESSAGE "Four "
      MENU TO nChoice
      SetPos( MaxRow() / 2, MaxCol() / 2 - 10 )
      IF nChoice == 0
         ?? "Esc was pressed"
      ELSE
         ?? "Selected option is", nChoice
      ENDIF

Compliance

Clipper

Seealso

@…PROMPT, ACHOICE(), SET MESSAGE, SET INTENSITY, SET WRAP, __ATPROMPT()

AChoice()

 

ACHOICE()

Allows selection of an element from an array

Syntax

      ACHOICE(<nTop>, <nLeft>, <nBottom>, <nRight>,;
              <acMenuItems>, [<alSelableItems> | <lSelableItems>],;
              [<cUserFunction> | <bUserBlock>], [<nInitialItem>],;
              [<nWindowRow>]) --> nPosition

Arguments

<nTop> – topmost row used to display array (default 0)

<nLeft> – leftmost row used to display array (default 0)

<nBottom> – bottommost row used to display array (default MaxRow())

<nRight> – rightmost row used to display array (default MaxCol())

<acMenuItems> – the character array of items from which to select

<alSelableItems> – an array of items, either logical or character, which is used to determine if a particular item may be selected. If the type of a given item is character, it is macro evaluated, and the result is expected to be a logical. A value of .T. means that the item may be selected, .F. that it may not. (See next argument: lSelectableItems)

<lSelableItems> – a logical value which is used to apply to all items in acMenuItems. If .T., all items may be selected; if .F., none may be selected. (See previous argument: alSelectableItems) Default .T.

<cUserFunction> – the name of a function to be called which may affect special processing of keystrokes. It is specified without parentheses or parameters. When it is called, it will be supplied with the parameters: nMode, nCurElement, and nRowPos. Default NIL.

<bUserBlock> – a codeblock to be called which may affect special processing of keystrokes. It should be specified in the form {| nMode, nCurElemenet, nRowPos | ; MyFunc( nMode, nCurElemenet, nRowPos ) }. Default NIL.

<nInitialItem> – the number of the element to be highlighted as the current item when the array is initially displayed. 1 origin. Default 1.

<nWindowRow> – the number of the window row on which the initial item is to be displayed. 0 origin. Default 0.

Returns

<nPosition> – the number of the item to be selected, or 0 if the selection was aborted.

Description

Allows selection of an element from an array. Please see standard CA-Cl*pper documentation for ACHOICE for additional detail.

Examples

      aItems := { "One", "Two", "Three" }
      nChoice := AChoice( 10, 10, 20, 20, aItems )
      IF nChoice == 0
         ? "You did not choose an item"
      ELSE
         ? "You chose element " + hb_ntos( nChoice )
         ?? " which has a value of " + aItems[ nChoice ]
      ENDIF

Files

Library is rtl

Compliance

Clipper

Seealso

MENU TO