WwCommand Function

Reference Guide > W Routines > WwCommand Function

WwCommand Function

Creates a command window.

Usage

command = WwCommand(parent, enteredCallback, doneCallback)

Input Parameters

parent — The parent widget’s ID.

enteredCallback — A string containing the name of the callback routine that is executed when a command is entered and confirmed (the user presses <Return>).

doneCallback — A string containing the name of the callback routine that is executed when the command window is destroyed.

Returned Value

command — The widget ID of the command window.

Keywords

Maximum — Specifies the maximum number of items that can be placed in the command history list.

Name — A string specifying the command widget name. This string is a part of a resource specification for the command window prompt. The Name keyword can be used in place of the Prompt keyword, although Prompt will take precedence if both are used. (Default: command.)

Position — Specifies the position of the upper-left corner of the command window on the screen.

Prompt — A string containing the prompt for the WwCommand widget.

Shell_name — String specifying the name of top-level widget, or TopLevelShell as part of the resource specification. (Default: commandshell.)

Title — Specifies a string containing the command window title.

Visible — Specifies maximum number of visible command history items.

Width — Specifies the width of the command window.

Color/Font Keywords

Background — Specifies the background color name.

Font — Specifies the name of the font used for text.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Get/Set Value

getvalue — Gets a string array containing the list of commands entered, from the oldest to newest command.

setvalue — Sets a new command in the text input field.

Callback Parameters

Any command widget callback procedure must have the following two parameters:

container — Container widget ID.

wid — Popup window widget ID.

Discussion

A command window is a popup window. This means that it cannot be the child of the top-level shell or the layout widget. Usually, a command widget is activated by a pushbutton or menu button, as in the example below.

A command window provides:

A text input field where the user can enter text, such as a command or a label.

A scrolling command-history list. Whenever the user enters a command in the text input field and presses <Return>, a callback is executed and the command text is placed on the history list. The user can re-enter a previously entered command by clicking on it in the command history list.

If the user double-clicks on a command in the command history list, the callback is automatically executed and appended to the end of the list.

A label for the text input field.

If Prompt is not used, the function looks for a command window prompt in a resource specification. Part of the resource specification can be specified using the Name keyword, otherwise the default is the *.command.promptString resource (where promptString is the attribute).

note

The Prompt keyword provides a method for “hard-coding” the command window prompt in the application. For greater flexibility, create your resource file using a text editor, and load the resource containing the prompt string using WtResource. The Name keyword can then be used in the WwCommand calling sequence to specify the command widget name in the resource specification.

Example 1

This example creates a button labeled Command. When this button is selected, the CbuttonCB callback is activated and a command window is created. When a user enters text in the text input field and presses <Return>, the callback CommandOK is executed. When the user exits the command box, the CommandDone callback is executed.

Enter the callback procedures and main procedure into a file, and compile the procedures with the .RUN command. To run the example, enter testcommand at the WAVE> prompt. To dismiss the widgets, select the appropriate function (such as Close) from the window manager menu of the Command button (the parent widget).

PRO CommandOK, container, wid

   value = WwGetValue(wid)

   PRINT, value

END

PRO CommandDone, container, wid

   Print, 'Done...'

END

PRO CButtonCB, wid, index

   command=WwCommand(wid, 'CommandOK', 'CommandDone', $

      Position=[300,300], Title='Command Entry Window')

END

PRO testcommand

   top=WwInit('WwCommand', 'appclass_name', layout)

   bbox=WwButtonBox(layout, ['Command'], 'CButtonCB')

   status=WwSetValue(top, /Display)

   WwLoop

END

Example 2

A typical resource specification for the command window prompt used in WwCommand is:

myapp.commandshell.command.promptString: Enter a command: