Rexx/Curses

A Rexx interface to curses

Version 2.0

3 February 2015

Table of Contents

Introduction
Hello World with Rexx/Curses
Rexx/Curses Usage
Attributes
Colors
Alternate Character Set
Key Names
Functions
CurAddch
CurAddstr
CurAttroff
CurAttributes
CurAttron
CurAttrset
CurBox
CurCbreak
CurChartext
CurClear
CurClearok
CurClrtobot
CurClrtoeol
CurCursSet
CurDelch
CurDeleteln
CurDelwin
CurEcho
CurEndwin
CurErase
CurGetch
CurGetstr
CurGetyx
CurHasAcs
CurHasColors
CurInch
CurInitPair
CurInitscr
CurInsch
CurInsertln
CurKeypad
CurNodelay
CurMove
CurWmove
CurMvdelch
CurMvwdelch
CurLeaveok
CurNapms
CurNewwin
CurNl
CurNocbreak
CurNoecho
CurNonl
CurNoraw
CurRaw
CurRefresh
CurStandout
CurStandout
CurStartColor
CurTouchline
CurTouchwin
CurWaddch
CurWaddstr
CurWattroff
CurWattron
CurWattrset
CurWclear
CurWclrtobot
CurWclrtoeol
CurWdelch
CurWdeleteln
CurWerase
CurGetch
Curgetstr
CurWinch
CurWinsertln
CurWrefresh
CurWnoutrefresh
CurDoupdate
CurGetMouseInfo
CurDropFuncs
CurLoadFuncs
CurQueryFunction
CurVariable

Introduction

This document describes the Rexx/Curses external function library and how to use it. It assumes a general knowledge of the C programming language curses library. If you aren't familiar with curses from a C programming perspective, see the ncurses introduction.

Hello World with Rexx/Curses

Most introductions to programming languages start off with sample code that shows how to display the string "Hello World". This is how you do this with Rexx/Curses. 
/*  1 */ Call RxFuncAdd 'CurLoadFuncs','rxcurses','CurLoadFuncs'
/*  2 */ Call CurLoadFuncs
/*  3 */ Call CurInitscr
/*  4 */ Call CurCbreak
/*  5 */ /* display "Hello World" in the middle of the screen */
/*  6 */ row = LINES / 2
/*  7 */ col = COLS / 2 - 6
/*  8 */ Call CurMove row, col
/*  9 */ Call CurAddstr "Hello World"
/* 10 */ Call CurMove LINES-1, 0
/* 11 */ Call CurAddstr "Press any key to continue..."
/* 12 */ Call CurRefresh
/* 13 */ key = CurGetch()
/* 14 */ Call CurEndwin
/* 15 */ Return

Rexx/Curses Usage

This section describes those usability issues that are not possible to implement in Rexx in the same manner they are implemented in C. In particular, the method that C uses for attaching display attributes with a character are not able to be implemented in the same manner as C.

Attributes

Each character displayed in a Curses window can have attributes. These attributes distinguish characters displayed on the screen from other characters. In Rexx/Curses, these attributes are specified as character strings which represent the equivalent curses attribute macros. Not all attributes mentioned below will necessarily be available in a Rexx/Curses program due to limitations of the underlying curses library.
A_NORMAL A_STANDOUT A_BOLD
A_UNDERLINEA_REVERSE A_BLINK
A_DIM A_INVIS A_PROTECT

These attributes are generally specifed in Rexx/Curses functions as optional parameters. In functions that allow the attributes to be specified there is generally an imposed limit of 5 individual arguments. However, attributes may also be specified as space-separated words in each argument. ie 

CurAttroff('A_BOLD', 'COLOR_PAIR(1)')
is equivalent to 
CurAttroff('A_BOLD COLOR_PAIR(1)').
The option of specifying multiple attributes in the one argument is to allow the returned value from a call to CurAttributes() to be used directly in subsequent function calls.

Colors

If your curses library has color capability (CurHascolors() = 1), the above attributes can also be supplemented with color attributes. Colors are specified by user-defined color pairs. These are created using the CurInitpair() function call, and specified as attributes using the COLOR_PAIR(n) pseudo macro. As an example, suppose you wanted to display a '$' character in the default window with a bright red foreground and a blue background, you would call the following: 
If CurHasColors() Then
   Do
      Call CurInitPair(1,'COLOR_RED','COLOR_BLUE')
      Call CurAddch('$','A_BOLD','COLOR_PAIR(1)')
   End
The COLOR_PAIR() pseudo macro, is syntactically similar to the curses macro of the same name. It must be specified in capital letters, with no spaces anywhere in the string.

Colors available in Rexx/Curses are:

COLOR_BLACK COLOR_BLUE
COLOR_RED COLOR_CYAN
COLOR_MAGENTACOLOR_GREEN
COLOR_YELLOW COLOR_WHITE

Alternate Character Set

Rexx/Curses programs normally display characters from the ASCII character set. Curses libraries define an alternate set of characters that can be used in place of the normal ASCII characters. These alternate characters can be specified in place of ASCII characters in functions that specify single characters as parameters. These alternate characters are all prefixed with "ACS" as the table below shows:
ACS_ULCORNER ACS_LLCORNER ACS_URCORNER ACS_LRCORNER
ACS_RTEE ACS_LTEE ACS_BTEE ACS_TTEE
ACS_HLINE ACS_VLINE ACS_PLUS ACS_S1
ACS_S9 ACS_DIAMOND ACS_CKBOARD ACS_DEGREE
ACS_PLMINUS ACS_BULLET ACS_LARROW ACS_RARROW
ACS_DARROW ACS_UARROW ACS_BOARD ACS_LANTERN
ACS_BLOCK ACS_S3 ACS_S7 ACS_LEQUAL
ACS_GEQUAL ACS_PI ACS_NEQUAL ACS_STERLING

Not all curses libraries implement these alternate characters. If the particular alternate character is not supported, it will be replaced by the '#' character.

Key Names

The return value from CurGetch() will be one of the following strings.
KEY_BREAK,KEY_DOWN,KEY_UP,KEY_LEFT,KEY_RIGHT,KEY_HOME,KEY_BACKSPACE, KEY_F(0),KEY_F(1),KEY_F(2),KEY_F(3),KEY_F(4),KEY_F(5),KEY_F(6),KEY_F(7), KEY_F(8),KEY_F(9),KEY_F(10),KEY_F(11),KEY_F(12),KEY_F(13),KEY_F(14),KEY_F(15), KEY_F(16),KEY_F(17),KEY_F(18),KEY_F(19),KEY_F(20),KEY_F(21),KEY_F(22),KEY_F(23), KEY_F(24),KEY_F(25),KEY_F(26),KEY_F(27),KEY_F(28),KEY_F(29),KEY_F(30),KEY_F(31), KEY_F(32),KEY_F(33),KEY_F(34),KEY_F(35),KEY_F(36),KEY_F(37),KEY_F(38),KEY_F(39), KEY_F(40),KEY_F(41),KEY_F(42),KEY_F(43),KEY_F(44),KEY_F(45),KEY_F(46),KEY_F(47), KEY_F(48),KEY_F(49),KEY_F(50),KEY_F(51),KEY_F(52),KEY_F(53),KEY_F(54),KEY_F(55), KEY_F(56),KEY_F(57),KEY_F(58),KEY_F(59),KEY_F(60),KEY_F(61),KEY_F(62),KEY_F(63), KEY_DL,KEY_IL,KEY_DC,KEY_IC,KEY_EIC,KEY_CLEAR,KEY_EOS,KEY_EOL,KEY_SF,KEY_SR, KEY_NPAGE,KEY_PPAGE,KEY_STAB,KEY_CTAB,KEY_CATAB,KEY_ENTER,KEY_SRESET,KEY_RESET, KEY_PRINT,KEY_LL,KEY_A1,KEY_A3,KEY_B2,KEY_C1,KEY_C3,KEY_BTAB,KEY_MOUSE

Note that because of different terminal mapping mechanisms used by different terminals under Un*x, the same key name may not be returned by the same key press. This is, unfortunately, the way things are.

Functions

CurAddch( ch [,attr1[,attr2[...[,attr5]]]] )

This function inserts the character ch into the default window at the current cursor position and the window cursor is advanced. The character ch, can be either a single character or one of the Alternate Character Set characters. Up to 5 optional attributes may be specified.

Returns: OK on success, ERR on error

CurAddstr( str )

This function writes all the characters of the string str to the default window. The functionality is equivalent to calling CurAddch() once for each character in the string. The string will be shown with the default attributes of the default window.

Returns: OK on success, ERR on error

CurAttroff( attr1[,attr2[...[,attr5]]] )

This function turns off the specified attributes without affecting other attributes already set. Up to 5 attributes may be specified.

Returns: OK on success, ERR on error

CurAttributes( char/attr )

This function returns a string representing the attributes portion of the supplied char/attr argument. char/attr is a value returned from the CurInch and CurWinch functions.

Returns: The attribute portion of char/attr

CurAttron( attr1[,attr2[...[,attr5]]] )

This function turns on the specified attributes without affecting other attributes already set. Up to 5 attributes may be specified.

Returns: OK on success, ERR on error

CurAttrset( attr1[,attr2[...[,attr5]]] )

This function sets the default attributes for the default window to the specified attributes, overriding any attributes that may have been set previously. Up to 5 attributes may be specified.

Returns: OK on success, ERR on error

CurBox( window, verch, horch )

This function draws a border around the default window. The window parameter is the window name specified in a previous call to CurNewwin() or the default window; stdscr. verch and horch specify the characters to be used for the vertical and horizontal lines of the border. If either of these values is specified as 0, a default alternate character is used; ACS_VLINE and ACS_HLINE respectively.

Returns: OK on success, ERR on error

CurCbreak( )

This function puts the terminal into cbreak mode. In cbreak mode, characters typed by the user are immediately available to the program and erase/kill character processing is not performed. When out of cbreak mode, the terminal driver will buffer characters typed until a newline or carriage return is typed. Interrupt and flow control characters are unaffected by this mode. Initially the terminal may or may not need be in cbreak mode.

Returns: OK

CurChartext( char/attr )

This function returns the character portion of the supplied char/attr argument. char/attr is a value returned from the CurInch and CurWinch functions.

Returns: The character portion of char/attr

CurClear( )

This function is similar to CurErase() except they also call CurClearok() to ensure that the the screen is cleared on the next call to CurWrefresh() for that window.

Returns: OK on success, ERR on error

CurClearok( window, bool )

This function, determines if the next call to CurWrefresh() with the specified window will clear the screen completely and redraw the entire screen. If bool is 1, the screen will clear. If bool is 0, the screen will not clear.

Returns: OK on success, ERR on error

CurClrtobot( )

This function clears the screen from the current cursor position in the default window to the end of the current line and all remaining lines in the window.

Returns: OK on success, ERR on error

CurClrtoeol( )

This function clears the screen from the current cursor position in the default window to the end of the current line only.

Returns: OK on success, ERR on error

CurCursSet( visibility )

This function enables the appearance of the text cursor to be altered. A value of 0 for visibility makes the cursor disappear; a value of 1 makes the cursor appear "normal" (usually an underline) and 2 makes the cursor "highly visible"; a block.

Returns: the previous value for visibility, or ERR if the function not supported

CurDelch( )

The character under the cursor in the default window is deleted. All characters to the right on the same line are moved to the left one position and the last character on the line is filled with a blank.

Returns: OK on success, ERR on error

CurDeleteln( )

The line under the cursor in the default window is deleted. All lines below the current line are moved up one line. The bottom line of the window is cleared. The cursor position does not change.

Returns: OK on success, ERR on error

CurDelwin( window )

This function deletes the specified window, freeing all memory associated with it. In the case of overlapping windows, subwindows should be deleted before the main window.

Returns: OK on success, ERR on error

CurEcho( )

This function causes input typed by the user to be displayed in the window. Initially, input characters are echoed. Subsequent calls to echo() and noecho() do not flush typeahead.

Returns: OK

CurEndwin( )

A program should always call CurEndwin() before exiting or escaping from curses mode temporarily. This routine will restore tty modes, move the cursor to the lower left corner of the screen and reset the terminal into the proper non-visual mode. To resume curses after a temporary escape, CurRefresh() or CurDoupdate() should be called.

Returns: OK on success, ERR on error

CurErase( )

This function copies blanks to every position of the default window.

Returns: OK on success, ERR on error

CurGetch( )

This function reads a character from the terminal associated with the default window. If CurNodelay() is enabled for the default window, and there is no input waiting, the value ERR is returned. If CurNodelay() is disabled for the default window, the program will block until the system passes text through to the program. Depending on the setting of CurCbreak(), this will be after one character or after the first newline. Unless CurNoecho() has been set, the character will also be echoed into the default window. If CurKeypad() is enabled for the default window, and a function key is pressed, the token for that function key will be returned instead of the raw characters. Possible function keys are defined in Key Names with names beginning with KEY_. If a character is received that could be the beginning of a function key (such as escape), a timer is set. If the remainder of the sequence does not come in within the designated time, the character will be passed through, otherwise the function key value will be returned. For this reason, on many terminals, there will be a delay after a user presses the escape key before the escape is returned to the program. (Use by a programmer of the escape key for a single character function is discouraged.)

Returns: See above

CurGetstr( )

The effect of this function is as though a series of calls to CurGetch() were made, until a newline or carriage return is received. The resulting value is returned to the caller. The user's erase and kill characters are interpreted, as well as any special keys; such as function keys.

Returns: See above

CurGetyx( window )

This function returns the position of the cursor within the specified cursor. The curses function call, getyx(), takes pointers to integer variables as functions. As this is not possible in Rexx the returned string consists of two words, the first containing the line, and the second containing the column.

Returns: "y x" on success or ERR on error

CurHasAcs( )

This function determines if the underlying curses library supports an Alternate Character Set .

Returns: 1 if ACS support is present, 0 otherwise

CurHasColors( )

This function indicates if the terminal supports, and can maniplulate color attributes.

Returns: 1 if color support is present, 0 otherwise

CurInch( )

Returns the character and attributes under the window cursor position of the default window. This returned value cannot be used in its returned form without conversion into its component parts by using CurAttributes() and CurChartext().

Returns: see above

CurInitPair( pairnum, fore, back )

This function changes the definitions of a color-pair. The function takes three arguments: the number of the color-pair to be redefined (pairnum) , and the new values of the foreground (fore) and background(back) colors. The value of pairnum must be between 1 and COLOR_PAIRS-1. The values of fore and back must be as defined in Colors. If the color pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition.

Returns: OK on success, ERR on error

CurInitscr( )

The first Rexx/Curses function called should be CurInitscr(). This function determines the terminal type and initializes all curses data structures. It also sets the Rexx variables, LINES, COLS, COLORS and COLOR_PAIRS (if color is supported), and sets unique identifier values for the default window STDSCR. The CurInitscr() function also arranges that the first call to CurRefresh() will clear the screen. If errors occur, CurInitscr() will write an appropriate error message to standard error and exit.

Returns: value of STDSCR window if success or "" if an error

CurInsch( ch [,attr1[,attr2[...[,attr5]]]] )

This function inserts the character ch into the default window at the current cursor position and the window cursor is advanced. All characters to the right of the window cursor are shifted right; the last character on the line disappearing. Up to 5 optional attributes may be specified.

Returns: OK on success, ERR on error

CurInsertln( )

This function inserts a blank line above the current line in the default window. The bottom line of the default window is lost.

Returns: OK on success, ERR on error

CurKeypad( window, bool )

This function changes the keypad option of the user's terminal. If enabled (bool is 1), the user can press a function key (such as the left arrow key) and CurGetch() will return a single value that represents the KEY_LEFT function key. If disabled (bool is 0), curses will not treat function keys as special keys and the program has to interpret the escape sequences itself.

Returns: OK if function supported, ERR otherwise

CurNodelay( window, bool )

This function controls whether CurWgetch() is a blocking or non-blocking call. If bool is 1, and no input is ready, CurWgetch() will return ERR. If bool is 0, CurWgetch() will block until input is ready.

Returns: OK if function supported, ERR otherwise

CurMove( y, x )

The cursor associated with the default window is moved to the given location. This does not move the physical cursor of the terminal until CurRefresh() is called. The position specified is relative to the upper left corner of the window, which is (0,0).

Returns: OK if function supported, ERR otherwise

CurWmove( window, y, x )

The cursor associated with the specified window is moved to the given location. This does not move the physical cursor of the terminal until CurRefresh() is called. The position specified is relative to the upper left corner of the window, which is (0,0).

Returns: OK if function supported, ERR otherwise

CurMvdelch( y, x )

The window cursor is moved to the position specified and then the character under the cursor in the default window is deleted. All characters to the right on the same line are moved to the left one position and the last character on the line is filled with a blank.

Returns: OK on success, ERR on error

CurMvwdelch( window, y, x )

The window cursor is moved to the position specified and then the character under the cursor in the specified window is deleted. All characters to the right on the same line are moved to the left one position and the last character on the line is filled with a blank.

Returns: OK on success, ERR on error

CurLeaveok( window, bool )

Normally, the hardware cursor is left at the location of the window being refreshed. Curleaveok() with a value of 1 for bool allows the cursor to be left wherever the update happens to leave it. It is useful for applications where the cursor is not used, since it reduces the need for cursor motions. If possible, the cursor is made invisible when this option is enabled.

Returns: OK on success, ERR on error

CurNapms( milliseconds )

This function suspends the program for the specified number of milliseconds.

Returns: OK on success, ERR if function not supported

CurNewwin( lines, columns, y, x )

This function creates a new window with the given number of lines, and columns. The upper left corner of the window is at line y, column x. If either lines or columns is zero, they will be defaulted to LINES - y and COLS - x. A new full-screen window is created by calling CurNewwin(0, 0, 0, 0).

Returns: If unsuccessful, an empty string is returned. If successful, a unique number that represents the new window created. This value must be used on subsequent calls to Rexx/Curses functions that take a window argument.

CurNl( )

This function enables the translation of newline into a carriage return and a line-feed on output, and a carriage return is translated into a newline on input. Initially, the translations do occur. By disabling these translations, curses is able to make better use of the line-feed capability, resulting in faster cursor motion.

Returns: OK

CurNocbreak( )

This function puts the terminal out of cbreak mode. In cbreak mode, characters typed by the user are immediately available to the program and erase/kill character processing is not performed. When out of cbreak mode, the terminal driver will buffer characters typed until a newline or carriage return is typed. Interrupt and flow control characters are unaffected by this mode. Initially the terminal may or may not need be in cbreak mode.

Returns: OK

CurNoecho( )

This function causes input typed by the user to not be displayed in the window. Initially, input characters are echoed. Subsequent calls to echo() and noecho() do not flush typeahead.

Returns: OK

CurNonl( )

This function disables the translation of newline into a carriage return and a line-feed on output, and a carriage return is translated into a newline on input. Initially, the translations do occur. By disabling these translations, curses is able to make better use of the line-feed capability, resulting in faster cursor motion.

Returns: OK

CurNoraw( )

This function places the terminal out of raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences are that in raw mode, the INTR, QUIT, SUSP, and STOP characters are passed through without being interpreted, and without generating a signal. The behaviour of the BREAK key depends on other parameters of the terminal drive that are not set by curses.

Returns: OK

CurRaw( )

This function places the terminal into raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences are that in raw mode, the INTR, QUIT, SUSP, and STOP characters are passed through without being interpreted, and without generating a signal. The behaviour of the BREAK key depends on other parameters of the terminal drive that are not set by curses.

Returns: OK

CurRefresh( )

This function copies the contents of the default window to the physical terminal screen, taking into account what is already there in order to optimize cursor movement. This function must be called to get any output on the terminal, as other routines only manipulate data structures. Unless Curleaveok() has been enabled, the physical cursor of the terminal is left at the location of the window's cursor.

Returns: OK on success, ERR on error

CurStandout( )

This function is the same as CurAttrset('A_NORMAL').

Returns: OK on success, ERR on error

CurStandout( )

This function is the same as CurAttrset('A_STANDOUT').

Returns: OK on success, ERR on error

CurStartColor( )

This function initializes eight basic colors (black,red,green,yellow, blue,magenta,cyan, and white), and two global variables; COLORS and COLOR_PAIRS (respectively defining the maximum number of colors and color-pairs the terminal is capable of displaying).

Returns: OK on success, ERR on error or if color is not supported

CurTouchline( window, y, n )

This function touches all lines starting at line y for n lines in the window so that the next call to CurWrefresh() will cause all characters on the specified lines to be redrawn.

Returns: OK on success, ERR on error

CurTouchwin( window )

This function touches all lines in the window so that the next call to CurWrefresh() will cause all characters in the window to be redrawn.

Returns: OK on success, ERR on error

CurWaddch( window, ch [,attr1[,attr2[...[,attr5]]]] )

This function inserts the character ch into the specified window at the current cursor position and the window cursor is advanced. The character ch, can be either a single character or one of the Alternate Character Set characters, specified in ACS. Up to 5 optional attributes may be specified.

Returns: OK on success, ERR on error

CurWaddstr( window, str )

This function writes all the characters of the string str to the specified window. The functionality is equivalent to calling WcurAddch() once for each character in the string. The string will be shown with the default attributes of the specified window.

Returns: OK on success, ERR on error

CurWattroff( window, attr1[,attr2[...[,attr5]]] )

This function turns off the specified attributes without affecting other attributes already set. Up to 5 attributes may be specified.

Returns: OK on success, ERR on error

CurWattron( window, attr1[,attr2[...[,attr5]]] )

This function turns on the specified attributes without affecting other attributes already set. Up to 5 attributes may be specified.

Returns: OK on success, ERR on error

CurWattrset( window, attr1[,attr2[...[,attr5]]] )

This function sets the default attributes for the specified window to the specified attributes, overriding any attributes that may have been set previously. Up to 5 attributes may be specified.

Returns: OK on success, ERR on error

CurWclear( window )

This function is similar to CurWerase() except they also call CurClearok() to ensure that the the screen is cleared on the next call to CurWrefresh() for the default window.

Returns: OK on success, ERR on error

CurWclrtobot( window )

This function clears the screen from the current cursor position in the specified window to the end of the current line and all remaining lines in the window.

Returns: OK on success, ERR on error

CurWclrtoeol( window )

This function clears the screen from the current cursor position in the specified window to the end of the current line only.

Returns: OK on success, ERR on error

CurWdelch( window )

The character under the cursor in the specified window is deleted. All characters to the right on the same line are moved to the left one position and the last character on the line is filled with a blank.

Returns: OK on success, ERR on error

CurWdeleteln( window )

The line under the cursor in the specified window is deleted. All lines below the current line are moved up one line. The bottom line of the window is cleared. The cursor position does not change.

Returns: OK on success, ERR on error

CurWerase( window )

This function copies blanks to every position of the specified window.

Returns: OK on success, ERR on error

CurGetch( window )

This function reads a character from the terminal associated with the specifie window. If CurNodelay() is enabled for the specified window, and there is no input waiting, the value ERR is returned. If CurNodelay() is disabled for the specified window, the program will block until the system passes text through to the program. Depending on the setting of CurCbreak(), this will be after one character or after the first newline. Unless CurNoecho() has been set, the character will also be echoed into the specified window. If CurKeypad() is enabled for the specified window, and a function key is pressed, the token for that function key will be returned instead of the raw characters. Possible function keys are defined in with names beginning with KEY_. If a character is received that could be the beginning of a function key (such as escape), a timer is set. If the remainder of the sequence does not come in within the designated time, the character will be passed through, otherwise the function key value will be returned. For this reason, on many terminals, there will be a delay after a user presses the escape key before the escape is returned to the program. (Use by a programmer of the escape key for a single character function is discouraged.)

Returns: See above

Curgetstr( window )

The effect of this function is as though a series of calls to CurWgetch() were made, until a newline or carriage return is received. The resulting value is returned to the caller. The user's erase and kill characters are interpreted, as well as any special keys; such as function keys.

Returns: See above

CurWinch( window )

Returns the character and attributes under the window cursor position of the specified window. This returned value cannot be used in its returned form without conversion into its component parts by using CurAttributes() and CurChartext().

Returns: see above

CurWinsertln( window )

This function inserts a blank line above the current line in the specified window. The bottom line of the specified window is lost.

Returns: OK on success, ERR on error

CurWrefresh( window )

This function is equivalent to a call to CurWnoutrefresh() followed by a call to CurDoupdate().

Returns: OK on success, ERR on error

CurWnoutrefresh( window )

This function copies the contents of the specified window to the internal representation of the screen. This function enables several windows to be refreshed in preparation for actual displaying by CurDoupdate(), but reduces the number of physical refreshes that occur.

Returns: OK on success, ERR on error

CurDoupdate( )

This function refreshes the screen, taking into account what is already there in order to optimize cursor movement. This function must be called to get any output on the terminal, as other routines only manipulate data structures. Unless CurLeaveok() has been enabled, the physical cursor of the terminal is left at the location of the window's cursor.

Returns: OK on success, ERR on error

CurGetMouseInfo( stem. )

This function returns information about the most recent mouse activity. It is meant to be called after CurGetch() returns "KEY_MOUSE". A Rexx stem variable; stem. (including trailing period) is passed and this stem is populated with the following:
   stem.0     5
   stem.1     x coordinate where the mouse action occurred
   stem.2     y coordinate where the mouse action occurred
   stem.3     number of the mouse button number
   stem.4     the action that occurred with the button
   stem.5     any modifier to the button action
The x and y coordinates returned are expressed in characters; 0,0 being the top-left corner of the screen.
The button number returned can be one of 1, 2 or 3.
The button actions returned can be one of:
   R          button released
   P          button pressed
   C          button clicked
   2          button double-clicked
   3          button triple-clicked
   D          button dragged (ie mouse moved with button pressed)
The button modifiers returned can be one of:
   S          shift key down
   C          control key down
   A          alt key down
   ?          some other modifier key down

Returns: OK on success, ERR on error

CurDropFuncs( )

This function is used to terminate Rexx/Curses and free up all resources that have been used.

It should be called at the end of every Rexx/Curses program. In particular, this function should be called after a syntax error has been caught with SIGNAL ON SYNTAX.

Returns: 0

CurLoadFuncs( )

This function is used to load all the Rexx/Curses external functions. This function is called after the function has been loaded with the Rexx builtin function rxfuncadd().

Although this function is useful only for dynamic library implementations of Rexx/Curses, it can be called by the executable version of Rexx/Curses. In this case it does nothing.

Returns: 0

CurQueryFunction( function|stem. [,option] )

(Not available in v1.3)
Allows the user to determine what Rexx/Curses functions are implemented and available for execution. option can be the default of R(registered and able to be executed) orA(available in package). If a stem variable is passed as the first option, then this stem will be populated with all function names in Rexx/Curses that are "available" or "registered". If a Rexx/Curses function name is passed as the first option, CurQueryFunction returns 0 if the function is "available" or "registered" depending on option, or 1 if the function name is not present depending on option.

Example: 

call rxfuncadd 'CurQueryFunction', 'rexxcurses', 'CurQueryFunction'
call rxfuncadd 'CurVariable', 'rexxcurses', 'CurVariable'

say curqueryfunction( 'stem.', 'A' ) /* returns 0 */
do i = 1 to stem.0                  /* 112 items displayed */
   say 'stem/A' stem.i
end

drop stem.
say curqueryfunction( 'stem.', 'R' ) /* returns 0 */
do i = 1 to stem.0                  /* 2 items displayed */
   say 'stem/R' stem.i
end

drop stem.
say curqueryfunction( 'curvariable', 'A' ) /* returns 0 */

drop stem.
say curqueryfunction( 'curvariable' )      /* returns 0 */

drop stem.
say curqueryfunction( 'curdropfuncs', 'A' ) /* returns 0 */

drop stem.
say curqueryfunction( 'curdropfuncs', 'R' ) /* returns 1 */

CurVariable( variable[, newvalue])

Set or get the value for the specified variable.
If newvalue is specified, the setable variable is set to newvalue. The following variables are available:
Copyright © Mark Hessling 1997-2015 <mark@rexx.org>

Last updated 3 February 2015