Reference Manual

Screen handling functions

These are some of the more essential functions in Power-4gl that handle various screen operations.

Helpman

Opens and handles a scrollable help window. This function can be called from any Power-4gl user interface window with the "help" logical key. The help text to be browsed is a concatenation of 3 flat text files, the first two being specified by parameters and the third is the "help.hlp" file containing general help information pertaining to the system as a whole, like standardized function keys and such. If any of the files do not exist, they are simply ignored. However, by supplying "help.hlp", all windows will at least have some help text. The help window appears at the top left corner of the screen and is as narrow and short as the help text permits.

2 parameters:
File1: The name of the first help text file. Typically, this file contains the most specific information about the current function.
File2: The name of the second help text file.

Disptitle

Displays a title line to the current window. This function is used by other Power-4gl user interface functions but may also be used in any window, for example, with input forms so that the window title is displayed with special attributes or colors.

2 parameters:
Name: The title name. This can be the title text itself or a key value to the title text table.
Type: The window type. This is used in conjunction with the name as part of the key value to the title text table. If an entry exists in the title table for the given name and type, then the corresponding title text is used which can be more than one line of text. Otherwise the name is used as the title text.

Winform

Opens a bordered window with a form at a given position. If the window cannot be opened at the given position, the window is adjusted in an attempt to solve the problem.

3 parameters:
Name: The form name.
Row: The screen row position. If the row is 1 then a full screen window is assumed.
Column: The screen column position. If the row is 1 then a full screen window is assumed.

Winopen

Opens a bordered window of a given size at a given position. If the window cannot be opened at the given position, the window is adjusted in an attempt to solve the problem.

5 parameters:
Name: The window name (optional).
Row: The screen row position. If the row is 1 then a full screen window is assumed.
Column: The screen column position. If the row is 1 then a full screen window is assumed.
Rows: The number of screen rows.
Columns: The number of screen columns.

Winclear

Clears a window opened by Winform or Winopen.

Winclose

Clears a window opened by Winform or Winopen.

Msgopen

Opens a message window with text which remains open until closed by Msgclose. This is typically used while the user waits for a lengthy process to complete.

1 parameter:
Code: Text code. This can be the message text itself or a key into the single line message table which contains the message text.

Msgadd

Adds a message to an already opened message window. This is typically used to report to the user the progress of a lengthy process. The added message appears below the main message text overwriting any previously added message.

1 parameter:
Text: Text code. This can be the message text itself or a key into the single line message table which contains the message text.

Msgclose

Closes a message window, indicating the end of a length process.

Pscreen

Opens a window prompting the user for the name of a printer and prints the screen contents to that printer.

Pause

Opens a message box with text and waits for the user to press any key at which point the message box is closed and processing continues.

3 parameters:
Code: Text code. This can be the message text itself or a key into the multiple line message table which contains the message text.
Row: The screen row position.
Column: The screen column position.

Getyn

Opens a message box with given text and prompt line and waits for the user to respond with a yes or no signal. The logical "accept" key is interpreted as a yes while the "exit" key means no. The user can also press the language dependent "y" or "n" keys.

4 parameters:
Tcode: Message text code. This can be the message text itself or a key into the multiple line message table which contains the message text.
Pcode: Prompt text code. This can be the prompt text itself or a key into the single line message table which contains the prompt text.
Row: The screen row position.
Column: The screen column position.

Goahead

Opens a message box with text and waits for the user to respond with a yes or no signal. The logical "accept" key is interpreted as a yes while the "exit" key means no. The user can also press the language dependent "y" or "n" keys. This function is similar to the Getyn function except that the prompt text code is "goahead".

3 parameters:
Tcode: Message text code. This can be the message text itself or a key into the multiple line message table which contains the message text.
Row: The screen row position.
Column: The screen column position.

Sure

Opens a message box with text and waits for the user to respond with a yes or no signal. The logical "accept" key is interpreted as a yes while the "exit" key means no. The user can also press the language dependent "y" or "n" keys. This function is similar to the Getyn function except that the prompt text code is "sure". Here's a short example of usage:

if sure("delete",8,16) then
-- delete something...
end if

3 parameters:
Tcode: Message text code. This can be the message text itself or a key into the multiple line message table which contains the message text.
Pcode: Prompt text code. This can be the prompt text itself or a key into the single line message table which contains the prompt text.
Row: The screen row position.
Column: The screen column position.

Bang

Opens a window where the user can execute operating system commands. This function can be called from any Power-4gl user interface window with the "opsys" logical key.

Checknum

Checks a character string as a valid number. An error message is displayed if the character string cannot be recognized as a valid number. Typical usage is as follows:

if not checknum(mystring) then
next field mystring
end if

1 parameter:
String: The character string to be checked as a number.

1 return value:
Verdict: True if the character string is a valid number, otherwise false.

Similar functions exist for datetime and date values.

Checkx

Checks a character as a check-box value which can have the values "x" or null. An error message is displayed if the character is an invalid check-box value. Typical usage is as follows:

after field mychar
if not checkx(mychar) then
next field mychar
end if

1 parameter:
Char: The character to be validated.

1 return value:
Verdict: True if the character is a valid check-box value, otherwise false.

A similar functions exists for the native language "y" or "n" characters.