CONSOLE pseudo-object

Purpose

Displays text and generally manages and interacts with the Console Window. The Console Window is the text mode window commonly known as the DOS BOX. All of the following examples use the shortened object name CON. However, you may freely substitute the full name CONSOLE, if you find it more readable or intuitive (CONSOLE.PRINT instead of CON.PRINT).

Syntax

CON.membername(params)

ReturnVariable = CON.membername(params)

CON.membername(params) TO ReturnVariable

Remarks

Some of the functionality of Console Methods was available in prior versions of PowerBASIC, and other versions of BASIC as well. These took the form of standard statements and functions, rather than the preferred CONSOLE OBJECT syntax. Where applicable, this legacy syntax is documented, and may be used as a direct replacement for the newer object form.

Console Methods which return a value may be used in two forms, a statement with a TO clause, or a function which may be used as a term in an expression:

CON.CAPTION$ TO WinName$

WinName$ = CON.CAPTION$

The two examples above are functionally identical. The choice is simply a matter of your personal preference. If you use the second form (as a function which returns a value), it can be a term in any expression of any complexity.

Some Console Methods take the form of a PROPERTY, which may get or set console property values. These are marked with <GET> or <SET>.

Most PowerBASIC functions specify graphic and pixel positions as x,y (the horizontal term first, then the vertical term). However, for compatibility with most current and prior versions of BASIC (PowerBASIC included), the functions which reference text rows and columns name the vertical term first (rows, columns).

In order to use the CONSOLE object successfully, you must use care to first attach a Console Window to your program. To do this, you can either use #CONSOLE ON to automatically attach it at the program start, or execute CONSOLE.NEW to create a new Console Window.

CON Methods

CON.CAPTION$ <Get>

Syntax

variable$ = CON.CAPTION$

CON.CAPTION$ TO variable$

Legacy Syntax

variable$ = CONSNAME$

Purpose

Retrieves the text which is currently displayed as the caption of the CONSOLE window. This area is also called the "title bar".

CON.CAPTION$ <Set>

Syntax

CON.CAPTION$ = StrgExpr

Legacy Syntax

CONSOLE NAME StrgExpr

Purpose

The text displayed as the caption of the CONSOLE window is changed to the contents of the string expression.

CON.CELL <Get>

Syntax

RowVar& = CON.CELL.ROW

ColVar& = CON.CELL.COL

CON.CELL TO RowVar&, ColVar&

Alt. Syntax

RowVar& = CON.LOCATE.ROW

ColVar& = CON.LOCATE.COL

CON.LOCATE TO RowVar&, ColVar&

Legacy Syntax

RowVar& = CURSORY

ColVar& = CURSORX

Purpose

Retrieves the cursor (caret) position for the Console Window. That is the row and column position where the next CON.PRINT will be displayed. RowVar& specifies the horizontal screen row (starting at 1) and ColVar& specifies the vertical screen column.

CON.CELL <Set>

Syntax

CON.CELL = RowValue&, ColValue&

Alt. Syntax

CON.LOCATE = RowValue&, ColValue&

Legacy Syntax

LOCATE RowValue&, ColValue&

Purpose

Sets the cursor (caret) position on the Console Window. That is the row and column position where the next CON.PRINT will be displayed. RowValue& specifies the horizontal screen row (starting at 1) at which to position the caret. ColValue& specifies the vertical screen column (starting at 1) at which to position the caret. Cursor visibility and size can be adjusted with the CON.CURSOR method.

CON.CLS

Syntax

CON.CLS

Legacy Syntax

CLS

Purpose

The active console page is cleared to the current background color, The caret is moved to the upper left corner (row 1, column 1).

CON.COLOR

Syntax

CON.COLOR(ForeGround, BackGround [,Count])

Legacy Syntax

COLOR ForeGround, BackGround [,Count]

Purpose

Establishes the foreground and background colors which will be used to display text on the Console Window. Foreground is a value from 0 to 15, which specifies the character color. Background is a value from 0 to 15, which specifies the background color. If either is specified as -1, that color is left unchanged.

Count is optional, and if included, causes the color attribute to be applied immediately to that number of character cells, starting at the current caret location. The caret is not moved, and the underlying characters are not changed.

0 = Black	8 = Gray
1 = Blue	9 = Light Blue
2 = Green	10 = Light Green
3 = Cyan	11 = Light Cyan
4 = Red	12 = Light Red
5 = Magenta	13 = Light Magenta
6 = Brown	14 = Yellow
7 = White	15 = Intense White

CON.CURSOR <GET>

Syntax

variable& = CON.CURSOR

CON.CURSOR TO variable&

Legacy Syntax

variable& = CURSOR

Purpose

Retrieves the size of the cursor (caret). If the cursor is visible, it is returned as a numeric value in the range of 1 to 100, and represents the percentage of the height of a full cursor. If the cursor is not visible, the value zero (0) is returned. Cursor visibility is controlled by CON.CURSOR.OFF and CON.CURSOR.ON

CON.CURSOR <SET>

Syntax

CON.CURSOR = NumrExpr

Legacy Syntax

CURSOR OFF|ON [,NumrExpr]

Purpose

Establishes the size of the cursor (caret), based upon the value of the numeric expression. It must be in the range of 1 to 100, and represents the percentage of the height of a full cursor. Cursor visibility is controlled by CON.CURSOR.OFF and CON.CURSOR.ON

CON.CURSOR.OFF

Syntax

CON.CURSOR.OFF

Legacy Syntax

CURSOR OFF

Purpose

Makes the cursor invisible, but remembers the cursor size for the next time visibility is enabled with the CON.CURSOR.ON method.

CON.CURSOR.ON

Syntax

CON.CURSOR.ON

Legacy Syntax

CURSOR ON

Purpose

Makes the cursor visible, and remembers the cursor size.

CON.END

Syntax

CON.END

Purpose

The Console Window currently attached to your program is released and detached from the process. If the Console Window was created with CON.NEW, it is destroyed. No errors are generated, even if no Console Window is currently attached.

CON.FOCUS

Syntax

CON.FOCUS

Legacy Syntax

CONSOLE SET FOCUS

Purpose

Brings the Console Window to the foreground and directs the focus to it. Execution of the CON.FOCUS method directs all keyboard input to the console, so that other console methods (like CON.INPUT, CON.INSTAT, etc.) can function correctly.

CON.GETSTDERR

Syntax

variable& = CON.GETSTDERR

CON.GETSTDERR TO variable&

Legacy Syntax

variable& = GETSTDERR

Purpose

Retrieves the handle of the standard error device, which is used with some functions of the Windows API.

CON.GETSTDIN

Syntax

variable& = CON.GETSTDIN

CON.GETSTDIN TO variable&

Legacy Syntax

variable& = GETSTDIN

Purpose

Retrieves the handle of the standard input device, which is used with some functions of the Windows API. It can also be used with the OPEN HANDLE statement, if you wish to treat the keyboard as a file. You can use CON.IN to determine if file or device redirection is in effect.

CON.GETSTDKBD

Syntax

variable& = CON.GETSTDKBD

CON.GETSTDKBD TO variable&

Legacy Syntax

variable& = GETSTDKBD

Purpose

Retrieves the handle of the standard keyboard device, which is used with some functions of the Windows API. Redirection can cause the standard keyboard handle to be different from the standard input handle. CON.GETSTDKBD always returns the handle of the keyboard regardless of any redirection state.

CON.GETSTDOUT

Syntax

variable& = CON.GETSTDOUT

CON.GETSTDOUT TO variable&

Legacy Syntax

variable& = GETSTDOUT

Purpose

Retrieves the handle of the standard output device, which is used with some functions of the Windows API. It can also be used with the OPEN HANDLE statement, if you wish to treat the screen as a file. You can use CON.OUT to determine if file or device redirection is in effect.

CON.GETSTDVID

Syntax

variable& = CON.GETSTDVID(PageNum&)

CON.GETSTDVID(PageNum&) TO variable&

Legacy Syntax

variable& = GETSTDVID(PageNum&)

Purpose

Retrieves the handle of the standard console video page given by the parameter PageNum&. PageNum& must be in the range of 1 through 8. If PageNum& is omitted, or it is equal to zero, the handle of the current active page is returned.

CON.HANDLE

Syntax

variable& = CON.HANDLE

CON.HANDLE TO variable&

Legacy Syntax

variable& = CONSHNDL

Purpose

Retrieves the handle of the Console Window. The console window handle can be used with some Win32 API functions, and can assist when associating GUI windows with the console window.

CON.IN

Syntax

variable& = CON.IN

CON.IN TO variable&

Legacy Syntax

variable& = CONSIN

Purpose

Determines whether Standard Input is being redirected. CON.IN returns TRUE (non-zero) if standard input is originating at the console keyboard, or FALSE (zero) if it is redirected from a file or device.

CON.INKEY$

Syntax

variable$ = CON.INKEY$

CON.INKEY$ TO variable$

Legacy Syntax

variable$ = INKEY$

Purpose

Reads a keyboard character or mouse event from the console input buffer, without echoing it to the screen. INKEY$ will return immediately, even if there are no character or mouse events to retrieve.

INKEY$ returns a string of 0, 1, or 2 characters that reflects the status of the keyboard buffer. It can also return a string of four characters if mouse event trapping is enabled. INKEY$ will always read keys from the keyboard, regardless of redirection status.

A null string (LEN(i$) = 0) means that the buffer is empty (no key or mouse event is available).

A string length of one (LEN(i$) = 1) means that an character key was pressed and the string contains the character. Values between 1 and 31 indicate a control code.

A string length of two (LEN(i$) = 2) means that an extended key was pressed. In this case, the first character in the string has a value of zero, and the second is the extended keyboard code. For example, pressing the F1 key will return CHR$(0,59).

A string length of four (LEN(i$) = 4) means that a mouse event was retrieved. In this case, the first two characters in the string have a value of 255. The third character is an event code, while the fourth character defines the button that was pressed.

Event code:

1 = movement	4 = button press
2 = double-click	8 = button release

Button code:

0 = no button	4 = second left button
1 = left button	8 = third left button
2 = right button	16 = fourth left button

For example, moving the mouse with the left button pressed will return CHR$(255, 255, 1, 1). Button presses can be combined. For example pressing the left and right mouse buttons together will return CHR$(255, 255, 4, 3). The Mouse must be enabled with the CON.MOUSE method in order to receive mouse events.

If you are converting DOS code, you are likely to come across the following type of loop:

WHILE NOT INSTAT : WEND

a$ = INKEY$

or:

a$ = INKEY$

LOOP UNTIL LEN(a$)

While both of these loops work fine in PowerBASIC, they take as much CPU attention as possible. As a result, this type of loop is very wasteful and can cause other applications to work sluggishly, even when the PowerBASIC app is running in the background. The solution is to add a SLEEP 0 statement within the loop (to release the current CPU time-slice to other tasks) or, better, use the CON.WAITKEY$ method instead.

CON.INPUT

Syntax

CON.INPUT(["prompt",] VariableList)

Legacy Syntax

INPUT ["prompt",] VariableList

Purpose

Reads a line from the keyboard, assigning data to one or more variables. The prompt is an optional string constant or string equate. Upon execution, the prompt is displayed and the program waits for keyboard input. Keys are accepted until the user presses ENTER, at which time the resulting data is parsed and stored into the variables which comprise VariableList.

VariableList is a comma-delimited sequence of one or more variables. They may be of any numeric or string type, but not special variable types like Object, GUID, etc. Data between commas is extracted, leading spaces are removed, and the result is assigned to each variable in succession.

If a single INPUT statement requests more than one variable, the user must enter the proper number of values on a single line, each separated by a comma. If not enough values are entered, remaining variables are set to zero (if numeric) or empty (if string).

If a particular variable is a fixed-length string or a nul-terminated string, keyboard input longer than the string is truncated to fit. Dynamic strings receive the complete keyboard input without truncation. This method always returns keyboard input; it is not subject to input redirection.

CON.INPUT.FLUSH

Syntax

CON.INPUT.FLUSH

Legacy Syntax

INPUT FLUSH

Purpose

Removes all pending keyboard and mouse events from the console input buffer.

CON.INSHIFT

Syntax

variable& = CON.INSHIFT

CON.INSHIFT TO variable&

Legacy Syntax

variable& = INSHIFT

Purpose

Returns a numeric value to tell you the state of the keyboard Shift, Ctrl and Alt keys, as of the last keystroke or mouse event retrieved by CON.INKEY$ or CON.WAITKEY$.

The value returned is a bitmask with the shift status: Shift code:

1 = Right-Alt	32 = Num Lock
2 = Left-Alt	64 = Scroll Lock
4 = Right-Ctrl	128 = Caps Lock
8 = Left-Ctrl	256 = Enhanced Key
16 = Shift

Values can be combined. For example, a return value of 17 would indicate that the right-alt and shift keys were both pressed.

CON.INSTAT

Syntax

variable& = CON.INSTAT

CON.INSTAT TO variable&

Legacy Syntax

variable& = INSTAT

Purpose

Determines whether a keyboard or mouse event is ready to be retrieved from the console input buffer. CON.INSTAT returns a logical TRUE value (non-zero) if a keyboard or mouse event is available, or FALSE (zero) if no events are ready.

INSTAT does not remove the keyboard or mouse event from the buffer. So, if INSTAT ever returns TRUE, it will always return TRUE until the event is removed from the buffer using CON.INKEY$ or CON.WAITKEY$. Mouse support must be enabled in order to test for mouse events. INSTAT is not subject to redirection.

CON.KEY

Syntax

CON.KEY(KeyNum&, KeyExpr$)

Legacy Syntax

KEY KeyNum&, KeyExpr$

Purpose

Assigns the string expression KeyExpr$ (up to 15 characters) to a function key (F1 to F12) specified by KeyNum& (a number from 1 to 12). For compatibility with DOS compilers, a KeyNum& of 30 or 31 is automatically translated to 11 or 12 respectively.

When the designated function key is pressed, the string expression is sent to the console keyboard input stream.

CON.KEY$

Syntax

variable$ = CON.KEY$(KeyNum&)

CON.KEY$(KeyNum&) TO variable$

Legacy Syntax

variable$ = KEY$(KeyNum&)

Purpose

Retrieves and returns the string expression assigned to a function key with the KEY statement. The parameter KeyNum& defines the function key to reference (from 1 to 12). For compatibility with DOS compilers, a KeyNum& of 30 or 31 is translated to 11 or 12 respectively.

CON.LINE.INPUT

Syntax

CON.LINE.INPUT(["prompt",] StringVar)

Legacy Syntax

LINE INPUT ["prompt",] StringVar

Purpose

Reads an entire line from the keyboard into a string variable, ignoring any delimiters which may be embedded. The prompt is an optional string constant or string equate. Upon execution, the prompt is displayed and the program waits for keyboard input. Keystrokes are accepted until the user presses ENTER, at which time the resulting string is stored into the string variable.

The StringVar may be a fixed-length, nul-terminated, or dynamic string. For fixed-length and nul-terminated strings, keyboard input longer than the string is truncated to fit. Dynamic strings receive the complete keyboard input without truncation. StringVar may not be a UDT variable, although fixed-length and nul-terminated UDT member variables are allowed. This method always returns keyboard input; it is not subject to input redirection.

CON.LOC <GET>

Syntax

HorizontalVariable& = CON.LOC.X

VerticalVariable& = CON.LOC.Y

CON.LOC TO XVariable&, YVariable&

Legacy Syntax

CONSOLE GET LOC TO XVariable&, YVariable&

Purpose

Retrieves the location of the console window on the screen. The location is a pixel coordinate relative to the upper left corner of the screen. This statement can be particularly useful in conjunction with CON.SIZE and GRAPHIC WINDOW, for exact positioning of graphic windows with respect to the console window.

CON.LOC <SET>

Syntax

CON.LOC = x&, y&

Legacy Syntax

CONSOLE SET LOC x&, y&

Purpose

Moves the Console Window to a new location on the screen. The target destination of the move is always expressed in pixels, relative to the upper left corner of the screen.

CON.MOUSE

Syntax

CON.MOUSE(EventCode, ButtonCode)

Legacy Syntax

MOUSE [,DOUBLE] [,MOVE] [,DOWN] [,UP]

Purpose

Defines which console mouse events and buttons should be trapped. The parameters EventCode and ButtonCode are numeric expressions made up from one or more of the following values:

Event code:

1 = movement	4 = button press
2 = double-click	8 = button release

Button code:

0 = no button	4 = second left button
1 = left button	8 = third left button
2 = right button	16 = fourth left button

You must first execute CON.MOUSE to define the events you wish to trap. Then, CON.MOUSE.ON enables mouse trapping. Finally, you will use CON.INKEY$ or CON.WAITKET$ to retrieve the mouse event reports. Due to limitations imposed by the Microsoft Windows operating system, it is not possible to trap mouse wheel events in a console application.

CON.MOUSE.BUTTONS

Syntax

variable& = CON.MOUSE.BUTTONS

CON.MOUSE.BUTTONS TO variable&

Legacy Syntax

variable& = MOUSEBUTTONS

Purpose

Returns the number of buttons on the system mouse.

CON.MOUSE.COL

Syntax

variable& = CON.MOUSE.COL

Legacy Syntax

variable& = MOUSEX

Purpose

Returns the column position of the mouse cursor, as of the most recent mouse event retrieved by CON.INKEY$() or CON.WAITKEY$().

CON.MOUSE.OFF

Syntax

CON.MOUSE.OFF

Legacy Syntax

MOUSE OFF

Purpose

CON.MOUSE.OFF disables mouse event trapping and the mouse cursor.

CON.MOUSE.ON

Syntax

CON.MOUSE.ON

Legacy Syntax

MOUSE ON

Purpose

CON.MOUSE.ON enables mouse event trapping and the mouse cursor.

CON.MOUSE.ROW

Syntax

variable& = CON.MOUSE.ROW

Legacy Syntax

variable& = MOUSEY

Purpose

Returns the row position of the mouse cursor, as of the most recent mouse event retrieved by CON.INKEY$() or CON.WAITKEY$().

CON.MOUSE.STAT

Syntax

variable& = CON.MOUSE.STAT

Legacy Syntax

variable& = MOUSESTAT

Purpose

Determines whether a mouse event is ready to be retrieved from the console input buffer. CON.MOUSE.STAT returns a logical TRUE value (non-zero) if a mouse event is available, or FALSE (zero) if no events are ready.

CON.MOUSE.STAT does not remove the mouse event from the buffer. So, if it ever returns TRUE, it will always return TRUE until the event is removed using CON.INKEY$ or CON.WAITKEY$. Mouse support must be enabled before you test the mouse status.

CON.NEW

Syntax

CON.NEW

Purpose

A new Console Window is created and attached to your program. The size of the Console Window is the default size established by the host operating system. Subsequent CONSOLE methods and Properties will act upon this newly created Console Window. Only one Console Window may be attached to a program at a time. Therefore, if you attempt to add a second console, without first executing CON.END, an error 5 (Illegal Function Call) is generated.

CON.OUT

Syntax

variable& = CON.OUT

CON.OUT TO variable&

Legacy Syntax

variable& = CONSOUT

Purpose

Determines whether Standard Output is being redirected. CON.OUT returns TRUE (non-zero) if standard output is displayed on the console screen, or FALSE (zero) if it is redirected to a file or device.

CON.PAGE.ACTIVE <GET>

Syntax

variable& = CON.PAGE.ACTIVE

CON.PAGE.ACTIVE TO variable&

Legacy Syntax

variable& = PAGEACTIVE

Purpose

Retrieves the page number of the active console page, in the range of 1 to 8 inclusive. The active page is the one which receives text from CON.PRINT methods, regardless of whether it is the page currently visible.

CON.PAGE.ACTIVE <SET>

Syntax

CON.PAGE.ACTIVE = NumrExpr

Legacy Syntax

PAGE NumrExpr

Purpose

The active page is the one which receives console output from CON.PRINT, CON.CELL, CON.CLS, etc. There are eight console pages, numbered from 1 to 8. You may use this method to select the active page, regardless of whether it is the page which is currently visible.

Using separate active and visible pages provides a mechanism for application screens to be constructed in the background for later visibility. Using two or more console pages is a particularly effective technique for accelerating screen display on slower operating systems like Win95, Win98, and WinME.

CON.PAGE.VISIBLE <GET>

Syntax

variable& = CON.PAGE.VISIBLE

CON.PAGE.VISIBLE TO variable&

Legacy Syntax

variable& = PAGEVISIBLE

Purpose

Retrieves the page number of the visible console page, in the range of 1 to 8 inclusive. The visible page is the one which is currently shown in the console window, regardless of whether it is also the active page (receiving text from CON.PRINT).

CON.PAGE.VISIBLE <SET>

Syntax

CON.PAGE.VISIBLE = NumrExpr

Legacy Syntax

PAGE , NumrExpr

Purpose

The visible page is the one which is currently shown in the console window, regardless of whether it is also the active page (receiving text from CON.PRINT). There are eight console pages, numbered from 1 to 8. You may use this method to select the page you wish to be visible, regardless of whether it is also the active page.

CON.PCOPY

Syntax

CON.PCOPY(SourcePage&, DestinationPage&)

Legacy Syntax

PCOPY SourcePage&, DestinationPage&

Purpose

Copies all text from one console text page to another. SourcePage is an integral value from 1 to 8 that specifies the number of the screen page to be copied. Likewise, DestinationPage specifies the screen page to which the source page is copied. Text and color attributes on the destination page are replaced by the text and color attributes on the source page. Use the CON.PAGE method to alter the active and visible screen pages. If either parameter is invalid, the entire operation is ignored.

Using two or more console pages is a particularly effective technique for accelerating screen display on slower operating systems like Win95, Win98, and WinME.

CON.PRINT

Syntax

CON.PRINT([ExprList] [SPC(n)] [TAB(n)] [,] [;]...)

Legacy Syntax

PRINT [ExprList] [SPC(n)] [TAB(n)] [,] [;]...

Purpose

Write text data to the current console text page (screen) at the current caret location. The CON.PRINT method has the following parts, which may occur in any order and quantity, within a single CON.PRINT statement:

ExprList	Numeric and/or string expression(s) to be written to the console screen.
SPC(n)	An optional function used to insert n spaces into the printed output. Multiple use of the SPC argument is permitted in the CON.PRINT statement, such as points between expressions. Values of n less than 1 are ignored.
TAB(n)	An optional function used to tab to the nth column before printing ExprList. Multiple use of the TAB argument is permitted in the CON.PRINT statement, such as points between expressions. Values of n less than 1 are ignored.
[;\|,]	Special characters that determine the position of the next text item printed. A semicolon (;) means the next text item is printed immediately; a comma (,) means the next text item is printed at the start of the next print zone. Print zones begin every 14 columns.

If the final argument of a CON.PRINT method is a semicolon or comma, the caret position is maintained at the current location, rather than the default action of scrolling the print position to the start of the next line. For example:

CON.PRINT "Hello";

CON.PRINT " world!";

...produces the contiguous result "Hello world!"

If you omit all arguments, the CON.PRINT method prints a blank line. Printing always begins at the current caret position. Output cannot be redirected to a file or device, it always goes to the current active console screen. For redirectable output, use CON.STDOUT instead.

Any control codes, such as Carriage Return, Line-Feed and Backspace are not interpreted. They will display on the screen as symbols in the current selected font.

A question mark may be used as an abbreviation for CON.PRINT. CON.PRINT USING is not one statement here, as it was in DOS. USING$ is a separate function, which may be included in the ExprList. See the USING$() function for more information.

It is not possible to print a User-Defined Type (UDT), a Variant, an object variable, or an entire array. Individual member values must be extracted with the appropriate function before they can be displayed.

CON.SCREEN <GET>

Syntax

RowValue& = CON.SCREEN.ROW

ColValue& = CON.SCREEN.COL

CON.SCREEN TO RowVariable&, ColVariable&

Legacy Syntax

CONSOLE GET SCREEN TO RowVariable&, ColVariable&

Purpose

Retrieves the size of the visible part of the Console Window, in text rows and columns.

CON.SCREEN <SET>

Syntax

CON.SCREEN = RowValue&, ColValue&

Legacy Syntax

CONSOLE SET SCREEN RowValue&, ColValue&

Purpose

Changes the size of the visible Console Window, and its associated screen buffers. The size of the Console Window (and the buffer for each active page) is changed to the rows and columns specified. It should be noted that, when using Windows 95/98/ME, a change in the number of rows to a non-standard value (other than 25, 43, 60) will substantially increase the execution speed of CON.PRINT methods. Once the console size has been altered, the new size can be retrieved with the CON.SCREEN Get Property.

If CON.SCREEN Set Property does not succeed, an error 5 (Illegal Function Call) is generated. This is most likely caused by one or more parameters that are too large or too small for the operating system in use.

If a non-standard screen size is used, switching the console to full screen mode may cause the console to be resized by Windows to the closest standard size. The precise course of action taken by Windows in this case is version-dependent. The default console size depends on the Windows version and on the user's local settings.

This property was designed for use with the WinNT family of operating systems (WinNT, Win2000, WinXP, WinVista, and Win7). It may not be possible to use all the features under Win95/98/ME, due to faults in the Windows subsystems. At a minimum, under Win95/98/ME, you must disable FONT AUTO-SIZE, and choose a specific fixed font for the console.

CON.SCREEN.ATTR

Syntax

variable& = CON.SCREEN.ATTR(row&, column&)

CON.SCREEN.ATTR(row&, column&) TO variable&

Legacy Syntax

variable& = SCREENATTR(row&, column&)

Purpose

Returns the attribute (color) of a character on the current console page (screen). The attribute is a composite byte value in the range of 0 through 255 (&hFF). The lowest 4-bits (low-order nibble) contains the foreground color attribute, in the range of 0-15, and the next 4-bits (high-order nibble) contains the background color attribute, in the range of 0-15.

If the coordinates are specified as 0,0, the default screen attribute (that which will be used for subsequent CON.PRINT methods) is returned.

CON.SCREEN.CHAR

Syntax

variable& = CON.SCREEN.CHAR(row&, column&)

CON.SCREEN.CHAR(row&, column&) TO variable&

Legacy Syntax

variable& = SCREEN(row&, column&)

Purpose

Returns the numeric code of a character on the current console page (screen) at the specified location.

CON.SCROLL.{UP|DOWN|LEFT|RIGHT}

Syntax

CON.SCROLL.UP([Lines [,row1, col1 [,row2, col2]]])

CON.SCROLL.DOWN([Lines [,row1, col1 [,row2, col2]]])

CON.SCROLL.LEFT([Lines [,row1, col1 [,row2, col2]]])

CON.SCROLL.RIGHT([Lines [,row1, col1 [,row2, col2]]])

Legacy Syntax

SCROLL <dir> [Lines [,row1, col1 [, row2, col2]]]

Purpose

Scrolls all or part of the current console page. The Lines parameter specifies the number of rows/columns to scroll, with a default value of one. Row1 and Col1 define the upper left corner of the region to scroll, while Row2 and Col2 define the lower right corner. If neither are specified, the entire page is scrolled.

The direction specifier (UP/DOWN/LEFT/RIGHT) is considered to be the "source" of the scrolling. For example, SCROLL DOWN means that a blank space is opened at the bottom of the scroll region, with remaining text moved up. SCROLL LEFT means that a blank space is opened at the left of the scroll region, with remaining text moved towards the right.

CON.SIZE

Syntax

HorizontalValue& = CON.SIZE.X

VerticalValue& = CON.SIZE.Y

CON.SIZE TO XVariable&, YVariable&

Legacy Syntax

CONSOLE GET SIZE TO XVariable&, YVariable&

Purpose

Retrieves the size of the Console Window, in pixels. This can be particularly useful together with CON.LOC and GRAPHIC WINDOW to precisely position a graphic window relative to the position and size of the console window.

CON.STDEOF

Syntax

variable& = CON.STDEOF

CON.STDEOF TO variable&

Legacy Syntax

variable& = STDEOF

Purpose

CON.EOF is used to determin whether the end of STANDARD INPUT has been reached. It returns a numeric TRUE (non-zero) if the next use of CON.STDIN.LINE will attempt to read past the logical end-of-file (Ctrl-Z for keyboard input), or FALSE (zero) otherwise.

CON.STDERR

Syntax

CON.STDERR StrgExpr [;]

Legacy Syntax

STDERR StrgExpr [;]

Purpose

Outputs a string expression to the standard error device. This is normally the console screen, unless it has been redirected. If the optional trailing semi-colon is omitted, a carriage return and line-feed ($CRLF) is sent immediately after the StrgExpr.

CON.STDIN.LINE

Syntax

CONSOLE.STDIN.LINE TO variable$

Legacy Syntax

STDIN LINE variable$

Purpose

Reads one line of text from the Standard Input Device. If data is available, it is placed in the variable$ variable; otherwise, an empty string is returned. You can keep reading data from STDIN, until the STDEOF function returns TRUE (non-zero). If input redirection is not in effect, CON.STDIN.LINE reads data from the keyboard until a CTRL+Z keystroke is detected.

CON.STDOUT

Syntax

CON.STDOUT(StrgExpr [;])

Legacy Syntax

STDOUT StrgExpr [;]

Purpose

Outputs a string expression to the standard output device, which defaults to the console screen. STDOUT can be redirected to a file or a device. If redirection is not in effect, output is sent to the current active console page. If a CON.PAGE.ACTIVE is not in effect, STDOUT will write to console page 1. If a trailing semi-colon is not present, a carriage return and linefeed ($CRLF) are sent immediately after the StrgExpr.

Any control codes such as Carriage Return, Line Feed and Backspace embedded in StrgExpr will be interpreted appropriately if standard output is not redirected. That is, CR ($CR) causes the cursor (caret) to move back to the beginning of the current line; LF ($LF) causes the caret to the next line; and Backspace ($BS) causes the caret to move back one character position.

If non-redirectable output is required, use CON.PRINT instead.

CON.VIEW <GET>

Syntax

RowValue& = CON.VIEW.ROW

ColValue& = CON.VIEW.COL

CON.VIEW TO RowVariable&, ColVariable&

Legacy Syntax

CONSOLE GET VIEW TO RowVariable&, ColVariable&

Purpose

Retrieves the position of the viewable part of a virtual screen. PowerBASIC allows you to specify a virtual console screen that may optionally be larger than the visible part of the console window. If you create a virtual screen with CONSOLE.VIRTUAL, scroll bars are automatically added to the visible screen to allow the user to examine the entire screen buffer.

PowerBASIC initially positions the viewable part at the upper left corner (position 1,1). The viewable part can be moved to various parts of the virtual screen by the user (with console scroll bars), or by the programmer (with the CON.VIEW set statement). CON.VIEW retrieves the view position of the visible page, regardless of whether it is also the active page.

CON.VIEW <SET>

Syntax

CON.VIEW = RowValue&, ColValue&

Legacy Syntax

CONSOLE SET VIEW RowValue&, ColValue&

Purpose

Sets the position of the viewable part of a virtual screen. PowerBASIC allows you to specify a virtual console screen that may optionally be larger than the visible part of the console window. If you create a virtual screen with CON.VIRTUAL, scroll bars are automatically added to the visible screen to allow the user to examine the entire screen buffer.

If you create a virtual screen that is larger than the visible screen, PowerBASIC initially positions the viewable part at the upper left corner (position 1,1). You may change the upper left corner of the view port within the virtual screen with CON.VIEW. If you specify a position which is outside the limits of the virtual screen, PowerBASIC will select a location at the maximum limit in that direction.

CON.VIEW affects only the visible console page, regardless of whether it is also the active page. You can retrieve the current VIEW position with the CON.VIEW Get Property.

This statement was designed for use with the WinNT family of operating systems (WinNT, Win2000, WinXP, WinVista, and Win7). It may not be possible to use all the features under Win95/98/ME, due to faults in the Windows subsystems. At a minimum, under Win95/98/ME, you must disable FONT AUTO-SIZE, and choose a specific fixed font for the console.

CON.VIRTUAL <GET>

Syntax

RowValue& = CON.VIRTUAL.ROW

ColValue& = CON.VIRTUAL.COL

CON.VIRTUAL TO RowVariable&, ColVariable&

Legacy Syntax

CONSOLE GET VIRTUAL TO RowVariable&, ColVariable&

ColVariable& = SCREENX

RowVariable& = SCREENY

Purpose

Retrieves the size of the screen buffers associated with the console window. PowerBASIC allows you to specify a virtual console screen that may optionally be larger than the visible screen. If you create a virtual screen with CON.VIRTUAL, scroll bars are automatically added to the visible screen to allow the user to examine the entire screen buffer.

CON.VIRTUAL <SET>

Syntax

CON.VIRTUAL = RowValue&, ColValue&

Legacy Syntax

CONSOLE SET VIRTUAL RowValue&, ColValue&

Purpose

Change the size of the screen buffer associated with the console window. PowerBASIC allows you to specify a virtual console screen that may optionally be larger than the visible console. If you create a virtual screen with CON.VIRTUAL, scroll bars are automatically added to the visible screen to allow the user to examine the entire screen buffer.

When you execute CON.VIRTUAL, the size of the console screen buffer for each active page is changed to the rows and columns specified. Each dimension must be larger or equal to the corresponding dimension of the current CON.SCREEN size.

Once the console buffer size has been altered, the new size can be retrieved using the CON.VIRTUAL Get Property.

If CON.VIRTUAL cannot be successfully executed, an error 5 (Illegal Function Call) is generated. This would most likely be caused by one or more parameters which are too large for available memory, or smaller than the visible console screen size.

CON.WAITKEY$

Syntax

StringVar$ = CON.WAITKEY$

StringVar$ = CON.WAITKEY$([KeyMask$] [,TimeOut&])

CON.WAITKEY$ [TO StringVar$]

CON.WAITKEY$([KeyMask$] [,TimeOut&]) [TO StringVar$]

Legacy Syntax

WAITKEY$

variable$ = WAITKEY$

Purpose

Reads a character, extended key, or mouse event from the console without echoing anything to the screen. If no data is available, CON.WAITKEY$ will wait for an event to occur. It is very similar to CON.INKEY$, except that it waits for input to be available. While waiting, time slices are released to the operating system to reduce CPU load.

CON.WAITKEY$ returns a string of one or two characters if a key was pressed. It returns a string of four characters for a mouse event, but only if mouse event trapping is enabled. CON.WAITKEY$ will always read keys from the keyboard, regardless of STDIN redirection status.

If the optional KeyMask$ expression is included, it tells CON.WAITKEY$ to recognize only a limited set of key or mouse events. KeyMask$ may include any number of Sub-Masks, one for each key or mouse event to observe. For example, CON.WAITKEY$("YyNn") will recognize upper-case or lower-case Y or N (for yes/no answers), while any other key or mouse event will be ignored. If KeyMask$ is omitted, or evaluates to a zero-length string, any key event or mouse event will be recognized.

If the optional TimeOut& expression is included, it tells CON.WAITKEY$ the maximum number of milliseconds to wait for a key or mouse event. CON.WAITKEY$(5000) will wait a maximum of 5 seconds. The specified TimeOut period will only be approximate, so you should not rely upon precision accuracy. If the TimeOut period is exceeded, a zero-length string is returned. If the TimeOut& parameter is omitted, or evaluates to zero (0), it will wait an infinite length of time.

A string length of one (LEN(i$) = 1) means that a standard character key was pressed. The result string contains the character. An ASC() value between 1 and 31 indicates a control code.

A string length of two (LEN(i$) = 2) means that an extended key was pressed. In this case, the first character in the result string has an ASC() value of zero (0), and the second is the extended keyboard scan code. For example, pressing the F1 key will return CHR$(0, 59).

A string length of four (LEN(i$) = 4) means that a mouse event has occurred while mouse trapping was enabled. In this case, the first two characters in the string have an ASC() value of 255. The third character is an event code, while the fourth is a button code:

Value	Event Code	Value	Button Code
1	movement	0	no button
2	double-click	1	left
4	button press	2	right
8	button release	4	second left button
		8	third left button
		16	fourth left button

For example, moving the mouse with the left button pressed will return CHR$(255, 255, 1, 1). Button presses can be combined, for example pressing the left and right mouse buttons together will return CHR$(255, 255, 4, 3). The Mouse must be enabled with the MOUSE statement in order to receive mouse events.

CON.WAITSTAT

Syntax

CON.WAITSTAT

Legacy Syntax

WAITSTAT

Purpose

Waits until a key is pressed or a mouse event occurs. The key/mouse event is not removed from the console input buffer. While waiting, time slices are released back to the operating system in order to reduce CPU load.