Recent Changes - Search:

WikiDoc

Categories

The [prompt] command

This page documents the [prompt] command whose syntax has been enhanced in version 8.1 of AlphaX.


Introduction

The [prompt] command lets you create a simple dialog to prompt the user to enter a value or a string. Since version 8.1 of AlphaX it has been enhanced to support several switches. The dialog can be displayed as a movable modal dialog or as a sheet window which pops down from the title bar of a window (by default, the current window): it contains a prompt, an edit field and two buttons (Cancel and OK).

This command can also specify a list of predefined proposed values. In that case the edit field takes the aspect of a combo box: the user can select an item from a popup menu and this item is automatically inserted in the field. There is also an automatic completion mechanism which tries to guess what the user is typing by comparing it to the predefined items in the list.

The command returns the contents of the edit field if the user dismisses the dialog with the OK button. It raises an error if the Cancel button is pressed.

This is an application-modal dialog, not just window-modal: while it is running, the user cannot type anything in the window it is attached to, nor switch to other windows inside Alpha. The application is blocked until the user dismisses the dialog.

Synopsis

The formal syntax of the [prompt] command is:

prompt ?-w <win>? ?-width <num>? ?-lines <num>? ?-sheet (0|1)? ?--? ?message? ?default? ?(menu_items)*? The options have the following meaning:

  • the -w option is useful only with sheet windows (see the -sheet option). It lets you specify the window the sheet dialog will be attached to: this window is brought to the front if it is in the background. By default, it is the current window.
  • the -width option lets you specify the total width of the sheet window in pixels. The default value is 300.
  • the -height option lets you specify the total height of the sheet !! !! window in pixels. The default value is 110.
  • the -lines option lets you specify the number of lines of the text input field. The command uses it to calculate the height of this field based on the font size. The default value is 1.
  • the -sheet option specifies the kind of dialog: movable modal dialog if the value is 0 (this is the default), sheet window sliding out of the title bar of the parent window if the value is 1. If this option is set to 1 but either no window is open or the -w option specifies a non existing window, it will be ignored, which means that a modal dialog will be used.
  • the -- option marks the end of the options. This can be useful to avoid ambiguities if the message string starts with a dash.

The message argument is the text used for the prompt: by default it is empty. The default argument is a default text to display in the text input field: by default it is empty. All the remaining arguments (if any) are considered menu items and used to build a list of suggested values displayed in the popup menu of a ''combo box''.

Examples

A large sheet dialog attached to the frontmost window:

 
    prompt -sheet 1 -width 500 -- "enter a string" "default_string"

A dialog with a five lines edit field:

 
    prompt -lines 5 -- "enter a long text spanning 5 lines!"

A movable dialog with a list of five suggested values (foo1,..., bar2):

 
    prompt "enter a value" "" foo1 foo2 foo3 bar1 bar2

A sheet dialog attached to a particular window (supposing this window is open):

 
    prompt -w "Alpha Commands" -sheet 1 "Enter a command name"


(add your comments here...)

cbu writes (14 December 2006):

If the dialog is application-modal, as stated above:

This is an application-modal dialog, not just window-modal: while it is running, the user cannot type anything in the window it is attached to, nor switch to other windows inside Alpha. The application is blocked until the user dismisses the dialog.

then allowing a sheet prompt to be attached to a window that is not in front seems somewhat dangerous. The user cannot see the prompt, nor can that window be brought to the front! In theory, a Return keypress would dismiss the sheet, but with unknown (to the user, at least) consequences.

This would suggest that sheets should only be allowed to attach themselves to the active (and visible) window, in which case the "-w <window>" argument is not required or recommended.

bd (2006-12-15)

No, it is application-modal when it is active: if the window is not frontmost, the sheet is displayed but it is unhilited (like the window it is attached to). So, the user can still click on this window to activate it and bring it to front. In fact I realize that the command should take care itself of bringing the window to the front and activating it. I'll modify it to this effect.


Last updated 2006-12-14 17:16:20

Page last modified on October 27, 2007, at 12:50 AM
Hosted on SourceForge.net Logo