TXT pseudo-object  

Purpose

Displays and inputs text on a specially created TEXT WINDOW.  This is similar to a CONSOLE window, with some advantages.  Generally speaking, a Text Window is more attractive.  But, just like a Console Window, only fixed-width text may be displayed.

Syntax

TXT.membername(params)

RetVal = TXT.membername(params)

TXT.membername(params) TO ReturnVariable

Remarks

Text Windows offer a specific, but limited capability.  They are very easy to implement and use, and they offer an excellent means to produce quick and straightforward programs in text mode.

Text Windows offer an excellent path for the beginning programmer, or for anyone who needs a procedural code model.  As the name implies, they display only fixed-width text.  Further, only one Text Window may exist at a time.  If you need snazzy graphics, more specialized fonts, multiple windows, or a GUI interface, you should look to GRAPHIC WINDOWS instead.

Text Window methods are accessed like any other object.  The object name TXT is followed by a period separator, and the name of the method or property:

TXT.Cell = RowValue&, ColumnVal&

Text Window 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:

TXT.Row TO RowVar&

RowVar& = TXT.Row

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.

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).

Text Windows handle text wrapping and auto-scrolling much like a typical Console Window.  When printing exceeds the end of a line, the print position wraps to the first column of the next row.  When printing exceeds the last row, the entire page is scrolled to open a new line at the bottom.

In order to use the TXT object successfully, you must use care to first create a Text Window in your program.  To do this, you can execute the TXT.WINDOW method.

All Text Windows are stable.  They cannot be closed unexpectedly by the user, so there are no surprises when you find you are trying to print to a window which no longer exists.  There is no Close Box, no System Menu, nor is ALT-F4 recognized as a close command.  They can only be closed by executing TXT.END, or by terminating the entire application.

TXT METHODS

TXT.CELL

Syntax

TXT.CELL = RowValue&, ColValue&

TXT.CELL TO RowVar&, ColVar&

TXT.COL TO ColVar&   <or>   ColVar& = TXT.COL

TXT.ROW TO RowVar&   <or>   RowVar& = TXT.ROW

Remarks

TXT.CELL is used to set or retrieve the cursor position, based upon the row and column position of a Text Cell.  That is the row and column position where the next printed text will be displayed. RowValue& specifies the horizontal screen row (starting at 1) at which to position the cursor.  ColValue& specifies the vertical screen column (starting at 1) at which to position the cursor. Since row and column numbers start at one (1), the upper left corner of the Text Window is considered to be cell 1,1.

The first form of TXT.CELL moves the cursor to the desired row and column.  If a value given is zero (0), that parameter is ignored and that position is not changed.  The second form of TXT.CELL retrieves the current cursor position, and assigns the values to the variables specified by RowVar& and ColVar&.

The last two forms allow you to retrieve just a single value, either row or column, and are supported in both statement and function form.

TXT.CLS

Syntax

TXT.CLS

Remarks

The text window is cleared, and the caret (next print position) is moved to the upper left corner (row 1, column 1).

TXT.COLOR

Syntax

TXT.COLOR = RGBColor&

Remarks

TXT.COLOR is used to change the foreground color of new text drawn with TXT.PRINT.  Existing text on the Text Window is not changed. PowerBASIC includes many built-in RGB color equates which may be used here, like %RGB_RED, %RGB_BLUE, etc.

TXT.END

Syntax

TXT.END

Remarks

The Text Window currently attached to your program is destroyed and detached from the process.  No errors are generated, even if no Text Window is currently attached.

TXT.INKEY$

Syntax

TXT.INKEY$ TO InkeyVar$

InkeyVar$ = TXT.INKEY$

Remarks

Reads a keyboard character if one is ready.  TXT.INKEY$ returns a string of 0 or 1 characters that reflects the status of the keyboard buffer for the current text window.  A null string (LEN=0) means that the buffer is empty - no key was pressed.

A string length of one means that a standard key was pressed and the string contains the character.  A value between 1 and 31 indicates a control code.

TXT.INKEY$ only processes standard characters.  Extended keys, like function keys and the insert key, are ignored.

TXT.INSTAT

Syntax

TXT.INSTAT TO InStatVar&

InstatVar& = TXT.INSTAT

Remarks

Determines whether a keyboard character is ready.  The numeric variable receives the keyboard buffer status for the current text window.  The value assigned is TRUE (non-zero) if a keyboard character is ready to be retrieved, or FALSE (zero) if not.

TXT.INSTAT does not remove the character from the buffer, so repeated execution will continue to return TRUE until the character is read with TXT.INKEY$, TXT.LINE.INPUT, etc.

TXT.LINE.INPUT

Syntax

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

Remarks

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 StringVar.

The StringVar may be a fixed-length, nul-terminated, or a 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.

TXT.PRINT

Syntax

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

Remarks

Write text data to the TEXT WINDOW at the current caret location. The TXT.PRINT method has the following parts, which may occur in any order and quantity:

ExprList:  Numeric and/or string expression(s) to be written to the TEXT WINDOW.

; and , are 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 TXT.PRINT is a semicolon or comma, the caret position is maintained at the current location, rather than the default action of moving the print position to the start of the next line.  For example:

TXT.PRINT "Hello";

TXT.PRINT " world!";

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

If you omit all arguments, TXT.PRINT prints a blank line.  Printing always begins at the current caret position.

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

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.

TXT.WAITKEY$

Syntax

TXT.WAITKEY$ [TO WaitVar$]

WaitVar$ = TXT.WAITKEY$

Remarks

Reads a keyboard character, waiting until one is ready.  It removes the character from the keyboard buffer for the Text Window, and optionally assigns it to the string variable.  If the TO clause is omitted, the keyboard character is discarded.

TXT.WAITKEY$ returns a string of 0 or 1 characters that reflects the status of the keyboard buffer for the Text Window.  A null string (LEN=0) means that there was an error, such as the case when no Text Window currently exists.

A string length of one means that a standard key was pressed and the string contains the character.  A value between 1 and 31 indicates a control code.

TXT.INKEY$ only processes standard characters.  Extended keys, like function keys and the insert key, are ignored.

TXT.WINDOW

Syntax

TXT.WINDOW(Cap$, x, y [,Rows, Cols]) TO hWin

Remarks

A new Text Window is created and attached to your program.  The size of the Window is determined by rows and cols, or defaults to 25 rows and 80 columns.  Subsequent TXT Methods will act upon this newly created Text Window.

If the Text Window is created successfully, the handle will be assigned to the variable specified by hWin.  If it fails, the value zero (0) will be assigned instead.  If you try to create a Text Window while another still exists, it will fail.  In this case, you must first destroy the prior Text Window, as only one may exist at a time.

The parameters x and y specify the requested location of the window, relative to the upper left corner of the desktop.  The parameters are always given in pixels.  Rows and columns optionally specify the size of the window, given in the number of characters which will fit within the borders.  If not given, the method defaults to 25 vertical rows by 80 horizontal columns.

See also

GRAPHIC WINDOW