Issuing a prompt to the user

prompt

Issue a prompt to the user


SYNTAX

prompt text_expression [,text_expression]… \
          button = text_expression[,label]] … [at x, y]

Issues a prompt to the user. The standard predefined window winprompt is opened for this purpose. The prompt window consists of one or more lines of text, which normally advise the user how to proceed, or issue a warning. Beneath the text are the buttons representing the choices available to the user. When the user has selected a button, the prompt window closes and control passes to the line indicated by the label of the button chosen. If no label was attached to the button, control passes to the next statement. Sculptor calculates an intelligent window size for the text and buttons specified.

text_expression

The prompt message text to be displayed in the window. Each text_expression represents a single line of text. At least one line of text must be provided for the prompt. It may be a variable or a string constant, or a combination of both.

If more than one line of prompt text is provided, the text_expressions should be separated by commas.

If a prompt with no text is required, assign an empty string to text_expression. This technique also enables blank lines to be created within the prompt text.

[button = text_expression[,label]]

Each button = clause specifies a button to appear in the prompt window. The buttons are centred in the window beneath the text. The button’s text_expression defines the text that appears on it.

The label clause indicates the line to which control is to be passed if the button is pressed. If no label clause is present, control passes to the next statement.

The button = clause is optional. If no buttons are defined, then a single standard prompt button with the label Confirm is displayed. When the button is pressed control passes to the next statement.

The first button defined is highlighted as the default button.

[at x, y]

The prompt window may optionally be allocated x and y co-ordinates. The window is opened with its top left corner at the position specified. If this clause is omitted the prompt window appears in the centre of the screen. The default position of the prompt window may be changed using the forms:

winprompt->xcreate = value

winprompt->ycreate = value


The winprompt window

The standard prompt window winprompt is opened for the display of prompts, and closed as soon as the user has selected from the options offered. The window appears centred on the screen, its size being dependent on the length and number of text lines and buttons specified. The pen used to display prompt text is PEN_NORMAL (21) in the winprompt window palette, normally PAL_PROMPT_WINDOW (25).

The winprompt window has its properties pre-defined, but it may be redefined within a program and assigned window clauses in the same way as a user-defined window, as follows:

+window winprompt at x, y {
      clauses
  }

Note however that the size of the prompt window cannot be changed. It is calculated automatically at run time The width can be increased by padding the text lines with spaces.


The prompt command and event functions

Care must be taken when interactive commands such as prompt are placed within event functions. A double click of the mouse causes Windows to generate a single click event followed by a double click event. If a prompt is executed, the double click event is lost. Therefore interactive code should never be placed in the function for any event which is triggered by a single mouse click if a double click is also required.

An example of this occurs in tables, where a single click on a line generates the EV_SELECT event, while a double click generates EV_SELECT followed by EV_DOUBLE_CLICK. A prompt executed in the EV_SELECT function will use the second click of a double click, and so the event is lost.


NOTES

  • The prompt statement used alone without any parameters or clauses displays nothing, but awaits a keypress before continuing with the next statement.

  • Multiple text lines and /or button clauses can cause a prompt statement to become much too long to fit on one line. In order to continue a statement over more than one physical line, place a backslash character ( \ ) at the end of each line which is to be continued. Separating button clauses in this way improves program legibility.


EXAMPLES

Here are some examples of prompts together with the window they produce:

  1. A prompt with a two-line message. No action need be taken if the user selects YES, so no label is attached to that button.

image0


     prompt \
     "   Select YES to continue    ",\
     "   Select NO to abandon      " \
          button = "  YES  " \
          button = "  NO   ",  FINISH
          ....

FINISH:
     return

  1. A multi-button prompt used for the purposes of selecting a search index.

image1


Prompt "Search by" \
     button = "   &Ref   ", S_REF \
     button = "   &Name  ", S_NAME \
     button = " &Address ", S_ADDRESS \
     button = "   &Tel   ", S_TEL
  1. The same prompt as in 2, but with the prompt window redefined to add a title and change the font.

image2


-window winprompt at 5,5 {
     title = "HOW DO YOU WISH TO PROCEED?"
     data_font = "arial"
}

RELATED TOPICS

Buttons