Screen Reader/2 Profile Access Language Reference

From OS2World.com Wiki
Jump to: navigation, search

By IBM

“Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation”

The Profile Access Language (PAL) is a special programming language developed for Screen Reader working with the DOS operating system. This version of PAL has been enhanced to work with the OS/2 2.1 operating system and its graphical user interface.

Profiles written in PAL are the basis of the Screen Reader/2 screen reading environment. Everything that is spoken by Screen Reader/2, either automatically or as a result of a user pressing a key, happens because of the programming in a profile.

This book provides information about writing or modifying PAL profiles.

Contents

Using Profiles

A profile is an ASCII text file written in PAL. You can use any text editor to write profiles.

When you finish modifying or creating a profile, save it as an ASCII text file. Name your profile using standard OS/2 file-naming conventions, and give the profile the extension .KPD (representing the word keypad).

Then, process the file so that Screen Reader/2 can recognize the new functions. To do this, use the PAL compiler.

Finally, load the profile into memory to make it active.

In Screen Reader/2, profiles are loaded in a tier, which is a stack of profiles. The profile tier can change, depending on the program or process that is running in the foreground. When a new program is started, Screen Reader/2 can switch from one tier to another, depending on whether or not the new program has a Screen Reader/2 Initialize statement associated with it.

The Screen Reader/2 base profile is loaded each time you start Screen Reader/2. Therefore, you have all of the basic key sequences and autospeaks, the edit facility, the pop-up keypad, key sequences for Presentation Manager screens, key sequences for defining viewports and autospeaks, and the mouse, scan, time, and icon functions.

In addition, you can load profiles that correspond to application programs. You can add profiles to the current tier by either:

  1. Pressing the key sequence #A when Screen Reader/2 is active and typing the profile name.
  2. Or, using the Push command within a profile.

NOTE: Screen Reader/2 automatically adds a profile to the tier for most of the base and extended OS/2 applications. In addition, Screen Reader/2 automatically adds OS/2 and Windows application-specific profiles to the profile tier for applications listed in the User's Guide. Profiles for DOS applications must be added to the profile tier using the key sequence #A.

PROFILE STRUCTURE

PAL profiles are free-form. You can place a new line anywhere a space is allowed. PAL profiles are not case-sensitive; you can use any combination of upper and lower case letters.

Profiles are made up of some or all of the following:

Comments. Key Definitions. Declarations. Procedures. System Statements. Compiler Directives

These programming constructs are covered in detail in this book.

COMMENTS

Comments in profiles are designated in either of these ways:

  1. Start a comment with two dashes (--). The PAL compiler assumes that the comment stops at the end of the line.
  2. Start a comment with a forward slash followed by an asterisk (/*) and end it with an asterisk followed by a forward slash (*/). These comments can extend over multiple lines and can be nested.

For example:

--This is a small comment.  It uses the two dashes.

/*This is also a comment.  However it is longer and stretches between two
lines so it requires the asterisk and the slash. */

NOTE: Comments can be placed anywhere except inside the braces that denote key sequences.

KEY DEFINITIONS

A key definition is a series of PAL programming constructs that combine to give a key sequence its function.

All key definitions have the same form: they begin with a key sequence that is enclosed in braces followed by an optional help comment that is surrounded by single quotes. The body of a key definition is a statement sequence.

An example of a key sequence is:

{D9}

A key sequence can also include chords. A chord is produced by pressing and holding one chord key and then pressing the second chord key before releasing the first one.

Place chords in parentheses. An example of a key sequence with a chord is:

{(D9)}

Here are some rules about key sequences:

1. The key names you can use are the keypad key names: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, H (for the Help key), S (for, the Stop key), *, #.

2. Key sequences are not limited in length; you can specify one or more keys or chords to make up a key sequence.

3. Once a key sequence is defined, you cannot use that same key sequence as the beginning of another key sequence in the same profile. For example, if you define {#A} to load a profile, you cannot define {#A1} to read the name of the profile.

4. Key sequences can be made up of key names alone, chords alone, or a combination of the two.

5. Chords must contain two key names, no less than two and no more than two.

6. Screen Reader/2 does not differentiate between a chord and its inverse. For example, chord (A B) is the same as chord (B A). Therefore, you cannot define a chord and its inverse within the same profile.

7. If you define the same key sequence in more than one profile and both of the profiles are active on the profile tier, the key sequence in the profile last pushed onto the tier is the effective one.

After the key sequence is specified, the key definition continues with an optional help comment. A help comment is the text spoken by Screen Reader/2 when a user presses the Help key and a specific key sequence. Place this text next to the key sequence surrounded by single quotes.

The body of the key definition is made up of a statement sequence or a cycle statement.

A statement sequence consists of any number of declarations followed by one or more statements. Each declaration and statement must end with a semicolon.

A statement can be one of the following:

   A PAL command.
   An assignment (variable := expression).
   A compound statement such as If, While, or For.
   A procedure invocation.

This is an example of a key definition:

{C1} 'Reset View' Msg( 'reset view '); View( Focus);

This is an example of a key definition with a chord:

{(C1)} 'Reset View' Msg( 'reset view '); View( Focus);

DECLARATIONS

A declaration statement defines a:

constant. variable. type.

For more information about variable names and types, refer to the section Variables.

Declarations can exist alone or as a part of a key definition. They are terminated by a semicolon.

The declarations are:

CONST A constant can be declared and and its value set as an integer, Boolean, or string. The constant has the type and value of its assignment. For example:

const space_bar = 32;

space_bar is an integer constant with the value 32.

const cathy = 'Cathy'

cathy is a string constant with the value Cathy.

VAR A variable and its type are declared using the var statement. You can declare more than one variable of the same type with one statement. List them any way you like, but separate the variables with commas. For example:

var PMViewWatch, PMSelectorControl, BoxCheck, PMEntryWatch : autohandle;

Variables PMViewWatch, PMSelectorControl, BoxCheck, and PMEntryWatch are declared as autohandles.

EXTERN An external variable is declared in one profile, then referenced in the same and/or another profile.

For example:

extern coreloaded : Boolean;

coreloaded is either true or false, is declared in one profile and used in another profile.

If a specified external variable is not available when the profile is pushed onto a profile tier, an error occurs and the profile is not pushed.

Autohandles can be declared as external for use in the Auto and AutoDelay commands, but not for the Autospeak statement.

STATIC A static variable in a key definition or autospeak is remembered from one processing of the key definition or autospeak to the next.

A static variable declared outside of a key definition or autospeak is shared among all Screen Reader/2 sessions. Because each session has a profile tier, all profile tiers can reference the value of a static variable declared outside of a key definition or autospeak.

TYPE A type definition enables you to define and name your own types for variable declarations later. For example:

type Simple = array [1..10] of integer; var X : Simple;

Type simple is defined as an integer array and X is declared as a variable of type simple.

PROCEDURES

A procedure declaration gives the name of a procedure, the names and types of its arguments (if any), its return type and value (if any), and the statement sequence to be processed when the procedure is called.

PROC identifier [(arguments)] [returning type] IS statementsequence; [return (expression);]

The required parts of the procedure declaration are PROC, the identifier, IS, and a statement sequence.

The identifier is the name of the procedure. You use the identifier to invoke a procedure. A procedure is invoked the same way a PAL command is invoked. State the name, followed by arguments in parentheses, and end with a semicolon. When a procedure is used, the number and types of arguments must match the declaration.

The arguments (if any) with their types are declared in parentheses after the identifier. A semicolon separates each argument declaration. For example:

proc IsDescendant( Descendant : viewhandle; Parent : viewhandle)

In this example, the value of each argument is passed to the procedure when the procedure is invoked.

To pass arguments by reference, place VAR before each variable declaration:

proc IsDescendant( var Descendant : viewhandle; var Parent : viewhandle)

If a variable which is passed by reference is changed by an operation in the called procedure, the value of the changed variable is visible to the caller of the procedure.

If the procedure returns a value to its caller, the type of the variable returned is declared as part of the returning clause.

The body of the procedure follows IS and continues until another PAL construct (declaration, system statement, or key definition) is encountered.

A procedure inherits the environment of its caller. If a setting is saved and changed before calling a procedure, the value of the changed setting is passed to the

procedure. If a setting is changed in the procedure, the caller will see that change.

OPERATIONS

This section describes the PAL operations that can be used in expressions. PAL allows the following types of operations:

Arithmetic. Comparison. Logical. Bitwise. String.

ARITHMETIC OPERATIONS

The arithmetic operations take integer arguments and return integer values.

The arithmetic operations are:

+ Add.

           Subtract.
  • Multiply.

MOD OR % Modulus remainder. DIV OR / Integer division.

COMPARISON OPERATIONS

Comparison operations take integer arguments and return Boolean values.

The comparison operations are:

= Equal to. < Less than. <= Less than or equal to. > Greater than. >= Greater than or equal to. <> Not equal to.

LOGICAL OPERATIONS

Logical operations take Boolean arguments and return Boolean values.

The logical operations are:

AND Conjunction. OR Disjunction. XOR Exclusive or. NOT Negation.

BITWISE OPERATIONS

The bitwise operations take integer arguments and return integer values.

The bitwise operations are:

BITAND Bitwise conjunction. BITEQ Bitwise equivalence. BITNOT Bitwise negation. BITOR Bitwise disjunction. BITXOR Bitwise exclusive or. << Shift left. >> Shift right.

NOTE: PAL's integers are signed values, but for these bitwise operations the integer arguments are treated as unsigned.

STRING OPERATIONS

The string operations take string arguments and return string values.

String operations are:

+ Concatenation of strings. UNION Union of sets of symbols in a string. INTERSECT Intersection of sets of symbols in a string.

          Difference of sets of symbols in a string.

Except for concatenation, these operations return the sorted string corresponding to the set. If a set is ? x, y, a ?, then the sorted string is ? a, x, y ?.

Here is an example of the string operations:

var input1, input2, result3, result4, result5, result6 : string input1 := 'zabc'; input2 := 'aaad'; result3 := input1 union input2; result4 := input1 intersect input2; result5 := input1 - input2; result6 := input1 + input2;

The results are:

result3 = 'abcdz'. result4 = 'a'. result5 = 'bcz'. result6 = 'zabcaaad'.

PRECEDENCE

The following lists the precedence of PAL operators. The operators are presented in order of precedence from highest to lowest. When several operators appear on the same line in the list, they have equal precedence. In a profile, when operations of equal precedence appear together without parentheses, they are evaluated from left to right.

() [] Parentheses, array elements. BITNOT NOT Bit-wise and logical negation. MOD % DIV / * Modulus remainder, division, multiplication. INTERSECT UNION + - String intersection and union, arithmetic addition and subtraction, string difference. BITAND BITOR BITXOR BITEQ << >> Bit-wise operations. > >= < <= Greater or less than (inequality). = <> Equal, not equal. AND Logical conjunction. OR XOR Logical disjunction and exclusive OR.

For example:

10 / 2 + 3

The result is 8 (not 2) because division has a higher precedence than addition.

20 / 2 * 10

The result is 100 (not 1) because multiplication and division have the same precedence, so the expression is evaluated from left to right.

EXPRESSIONS

Expressions are built up starting from constants, variables, and read-only variables, and combined together with functions and operations to give a value.

For example, x, 1, and 'hello' are expressions that can be used as the base. They can be combined with a function:

length( 'hello' )

And further combined with an operation:

1 + length( 'hello' )

CONSTANTS

A PAL constant can be a Boolean, integer, or a string.

The PAL Boolean constants are True and False.

An integer constant is a number between negative 2 (to the power of 31) and positive 2 (to the power of 31). Integers are 32-bit quantities. You can use hex notation (for example, &hF001) and binary notation (for example, &B11011001) for integers.

A string constant is any sequence of characters on a single line surrounded by single quotes.

All ASCII characters except the following are allowed in strings:

0 Null. 9 Tab. 10 Line feed. 12 Form feed. 13 Carriage return. 26 End of file.

To use one of these characters in a string, combine the &caret. symbol with the ASCII representation (a number between 1 and 255). Place the ASCII number within parentheses and precede it with the &caret. symbol. For example, &caret.(9) is the tab character. The null character, however, is never allowed in strings. Do not send strings with characters below ASCII 32 to the synthesizer using the Msg command. The Out command can be used to send these characters, which are often used in codes to control your synthesizer.

To use the &caret. symbol or the single quote in a string, type either character twice. Two examples are:

'wont' 'use the &caret.&caret. symbol this way'

In addition, PAL string constants defined within Screen Reader/2 include:

ALPHABETIC. A string of all alphabetic characters.

NONBLANK. A string of all 253 nonblank characters.

NUMERIC. A string of all numeric characters.

PUNCTUATION. A string of all punctuation characters.

SYMBOL. A string of all symbols.

All other constants are defined in profiles using the const declaration statement. Constants used in the profiles provided with Screen Reader/2 are declared in the file SRD2.INC in the SRD21 directory.

VARIABLES

A variable name is an alphanumeric string. Variable names can be any length for clarity but only the first 16 characters are significant to PAL. The first character must be alphabetic. Case is not important.

The alphanumeric characters allowed in variable names are:

A to Z. a to z. 0 to 9. Underscore (_) and period (.).

The value of a variable depends on its type. All variables in a profile must be declared and given a type.

SIMPLE VARIABLE TYPES

The simple variable types are:

BOOLEAN. A Boolean variable has a value of either True or False. An example of a Boolean variable declaration is:

var Yes : Boolean;

INTEGER. An integer variable is a number between negative 2 (to the power of 31) and positive 2 (to the power of 31). Integers are 32-bit quantities.

An example of an integer variable declaration is:

var StrLen : Integer;

STRING. Strings are limited to 255 characters with a default length of 80. You can also declare a string of length n.

A string with the default length of 80 is declared:

var searchst : string

A string of length n (for example, 20) is declared:

var searchst : string[20]

A single character of a string can be referenced as if the string were an array. The index number into the string is enclosed in brackets after the string identifier. For example, str[3] is the third character of the value of the string variable str.

HANDLE VARIABLE TYPES

The handle variable types are:

AUTOHANDLE. An autohandle variable identifies an autospeak and one must be declared for each autospeak. An example of an autospeak identified by an autohandle is:

var t : autohandle; Autospeak t Watch Display( 25, 1, 3) Do If trigger <> 'F1=' Then Say( Display( 25, 1, 80)); Endif;

FILEHANDLE. A Filehandle variable identifies a file and is returned from the command OpenFile. Then, commands such as BackUpFile, CloseFile, ReadFile and ResetFile use the variable to access the file. An example of a variable declared as the type Filehandle is:

var Tutorial : Filehandle;

VIEWHANDLE. A variable of type viewhandle is used to point to all of the information that Screen Reader/2 needs to calculate new views. Here are some ways Screen Reader/2 uses viewhandles:

1. The View command sets the Screen Reader/2 view to the view identified by a viewhandle.

2. View and FocusView are predefined as read-only viewhandle variables.

3. View.Parent, ViewFromPoint, and ViewFromRowCol return viewhandles.

4. EventCursorChange, EventSelectorChange, and EventViewChange return a viewhandle in the local read-only variable 'trigger.'

Here is an example of a variable of type viewhandle:

var BackView: viewhandle;

ARRAY VARIABLE TYPES

The array variable types are:

ARRAY. An array is a group of elements. The type of the elements in an array is specified in the declaration. You can declare arrays of any type.

This declaration defines an array of integers:

var X : array [1..10] of integer;

The elements of the array are accessed with integer subscripts, such as x[3].

NOTE: You can create a multi-dimensional array by declaring a variable in one of the following ways:

var x: array[1..n] of array[1..n] of integer;

var x: array[1..n], [1..n] of integer;

INTARRAY. An intarray variable is a variation of type array[1..256] of integer used specifically for the Set( Trapkeys ) command. An example of an intarray variable declaration is:

var CharList : intarray; CharList[1] := &h024700; CharList[2] := 0; Set( TrapKeys, CharList);

This example traps the Ctrl+Up Arrow keys.

NOTE: Use intarray variables sparingly because each intarray requires 1 KB of memory.

READ-ONLY VARIABLES

This section lists the PAL read-only variables by category. These read-only variables give information about the display or the Screen Reader/2 state.

Position Data

Cursor and pointer positions are relative to the current viewport. These read-only variables are all integers:

COL. Column of local pointer. ROW. Row of local pointer. CCOL. Column of cursor; 0 if no cursor exists in the current viewport. CROW. Row of cursor; 0 if no cursor exists in the current viewport. PCOL. Column of Screen Reader/2 pointer. PROW. Row of Screen Reader/2 pointer.

View Information

FOCUSVIEW. Viewhandle for the view with the focus (The area where the current application is seeking input).

SELECTORS. Integer indicating the number of selectors in the current view.

File Information

EOF. Boolean variable that designates end of file.

PROFDIR. String that is the directory for profiles. When Screen Reader/2 starts, the value of the environment variable SRDPROFILES is used to initialize this variable.

Program Information

PROGRAM. String that contains the current program name. This name is the file name and extension for the program.

TITLE. String that is the title of the current program (text of the title bar).

Return Code

RC. The Screen Reader/2 return code of the previous command. In most cases, it is set to 0 if a command is successful, and to a number other than 0 if the command is unsuccessful. The one exception to this rule is when the Read command is used to obtain keyboard input. In this case, the return code, (RC), is set to the length of the input string.

The return code values are listed with the Set( Trap ) command.

Autospeak Information

TRIGGER. Variable returned as the result of an autospeak watching an event or an expression. The variable type for trigger depends on the type of the expression or event. Refer to the description of the Autospeak system statement for more information.

Synthesizer Information

MAXPITCH. Integer indicating the number of pitch codes defined in the current synthesizer settings (.TTS) file.

MAXRATE. Integer indicating the number of rate codes defined in the current synthesizer settings (.TTS) file.

MAXSPECIAL. Integer indicating the number of special codes defined in the current synthesizer settings (.TTS) file.

MAXVOLUME. Integer indicating the number of volume codes defined in the current synthesizer settings (.TTS) file.

Settings

All of the keywords for settings used by the Set command can also be used as read-only variables. They can give either Boolean, integer, string, or intarray values.

The Boolean setting read-only variables are:

Blank. Caps. Dictionary. ForceSpell. Graphics. Icons. LockStatus. Noise. Numbering. Onespace. Pause. Stopping. SpellCaps. Trailing. Trap. Wrap.

The integer setting read-only variables are:

Bottom. Format. Left. Mode. Pitch. Rate. RepeatCount. Right. Spaces. Special. Top. Volume.

The string setting read-only variables are:

Device. Ignore. Table. WordDef.

The intarray setting read-only variable is:

TrapKeys.

SYNTAX

In PAL syntax:

1. Keywords are the first word on a line and are shown in all capital letters. Type keywords as they are spelled. However, case is not significant so you can use any combination of upper and lower case letters.

2. Variables, expressions, and statement sequences are shown in italics. You will recognize these because they are identified by words such as:

autohandle. column. commandsequence. event. expression. flag. integer. length. modifier. profilenumber. row. statementsequence. string. viewhandle. x. y.

Replace them with ones you are using.

3. The symbol | separates multiple choices. You can choose only one.

4. All punctuation, such as parentheses and semicolons, must be included.

5. Arguments and punctuation in square brackets are optional.

FUNCTIONS

Functions usually take at least one argument and always return a value, such as a string, a Boolean, an integer, or a viewhandle. Functions are used in expressions in place of a number, constant, or variable.

Most functions take one or more arguments after the function name. Some functions take modifiers instead of, or in combination with, arguments. In these cases, the modifier is added by placing a period and the modifier after the function name.

NOTE: Read-only variables are functions that do not take arguments.

The conventions used to display the syntax of the functions are described in the section Syntax.

ABS

The ABS function returns the absolute value of an integer.

SYNTAX:

ABS ( integer)

EXAMPLE:

var ColumnDiffer : integer; ColumnDiffer := Abs ( ccol - pcol);

RESULT:

In this example, the variable ColumnDiffer is assigned the absolute value of the value determined by the cursor column minus the pointer column.

ASC

The ASC function returns the ASCII value of the first character of a string.

SYNTAX:

ASC ( string)

EXAMPLE:

If ( Char=Asc( '.')) Or ( Char=Asc( '!')) Or ( Char=Asc( '?')) Then Msg( 'end of sentence'); Endif;

RESULT:

In this example, the current character (Char) is compared with three sentence terminators. Because Char returns the ASCII value of the current character, it is necessary to compare Char with the Asc function of the sentence terminators rather than with their string values.

RELATED TOPICS:

Char function. Chr function.

AUTO

The AUTO function returns True if an autospeak is On and False if an autospeak is Off.

SYNTAX:

AUTO (autohandle)

REMARKS:

The autohandle identifies an autospeak (to determine is On or Off). If no autospeak is defined for the autohandle, Auto returns False.

EXAMPLE:

var Myauto: autohandle;

Autospeak Myauto Watch EventKeyPressed Do Continue;

{C4} 'My autospeak on or off' If Auto( MyAuto) Then Msg( 'turning my autospeak off'); Auto( MyAuto, off); Else Msg( 'my autospeak on'); Auto( MyAuto, on); Endif;

RESULT:

In this example, an autospeak with the autohandle MyAuto watches for a key press. The key sequence C 4 is defined to turn the autospeak On and Off by evaluating the status of MyAuto using the Auto function.

RELATED TOPICS:

Autospeak statement. Auto command.

CHAR

The CHAR function returns information for the character at a specified position relative to the current view.

SYNTAX:

CHAR [( row, column)]

CHAR.modifier [( row, column)]

REMARKS:

The Char function with no modifier returns the ASCII value of the character at the row and column you specified.

The Char function with a modifier returns the information for the character at the indicated row and column.

The Char function uses the row and column of the local pointer as the default if you do not specify row and column.

The modifiers valid for this function are:

Bottom Top Left Right Color Font Pitch Style IconID IconText

1. If the modifier is Bottom, Top, Left, or Right, the value returned is relative to the current view. The row and column must be valid for the current view.

2. If the modifier is Color, the value returned is a color index for the character at the specified or default row and column. The color index is a number between 0 and 64. The foreground color is in the lower byte of the value returned and the background color is in the upper byte.

NOTE: FG (foreground) and BG (background) are constants that are defined in the file SRD2.INC in the SRD21 directory.

3. If the modifier is Font, the value returned is the font name for the character at the specified or default row and column.

4. If the modifier is Pitch, the value returned is the font pitch for the character at the specified or default row and column. The font pitch is the point size in decipels (1/10 point).

5. If the modifier is Style, the values returned are:

const FS_Italic = &h0001. const FS_Underscore = &h0002. const FS_Negative = &h0004. const FS_Outline = &h0008. const FS_Strikeout = &h0010. const FS_Bold = &h0020. const FS_Icon = &h1000.

NOTE: For "normal text" the value returned is 0.

6. If the modifier is IconID, the value returned is the icon ID for the icon at the specified or default row and column. If there is no icon at the indicated position, zero is returned. Icon IDs and their associated text that are "pre-recognized" by Screen Reader/2 are listed in the file SRD2.ICN in the SRD21 directory. Any given icon, such as the minimize icon, may have a different numeric icon ID depending on the display (XGA, VGA, etc.) and resolution.

NOTE: You can add icons unknown to Screen Reader/2 using the chord D #. This chord key sequence asks you to enter a text string that identifies the current icon. The current icon ID and the text string you enter will be added to the file SRD2.ICN.

7. If the modifier is IconText, the value returned is the text associated with the ID of the icon at the specified or default row and column. If no text exists in the Screen Reader/2 icon table, or there is no icon at the indicated position, then a zero length string is returned. The icon table is the file SRD2.ICN. The format for each entry in the icon table is the icon ID followed by its associated string.

ERROR CONDITIONS:

If the row and column are not valid for the current view, you hear an error message and the return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE 1:

var num : integer;

{12} 'system ready' num := Char( View.Rows, 11); If num = 32 Then Msg( 'system ready'); Else Msg( 'unknown system state'); EndIf;

RESULT:

In this example, the variable num is set to the ASCII value of the character in column 11 of the bottom row of the current view. Then, i is compared with ASCII 32 (blank). The appropriate message is announced.

EXAMPLE 2:

include 'srd2.inc'

{08} 'color of current character' Save( Table ); Set( Table, 'Color' ); Say( Char.Color bitand FG ); Out( ' On '); Say( ( Char.Color bitand BG) >> 8 );

RESULT:

In this example, the key sequence 0 8 is defined to announce the color of the current character. The spelling table is set to the table containing the color names. Then, the name of the foreground color is announced followed by the background color.

RELATED TOPICS:

Display function. SetIconText command.

CHR

The CHR function returns the character (string of length 1) corresponding to the ASCII integer value.

SYNTAX:

CHR ( integer)

REMARKS:

The integer argument should be between 0 and 255; if it is not, only the low-order byte is considered. Therefore, Chr( &hF496) is the same as Chr( &h96).

EXAMPLE:

var EditKeyHandler : autohandle;

Autospeak EditKeyHandler Watch EventKeyPressed Do Say( Chr( Trigger));

RESULT:

In this example, the autospeak EditKeyHandler watches for a key press. The Chr function enables the autospeak to announce the character corresponding to the key pressed. (Remember that Chr only looks at the low-order byte of its argument.)

RELATED TOPICS:

Asc function.

DATETIME

The DATETIME function returns date and time information.

SYNTAX:

DATETIME ( flag)

REMARKS:

The DateTime function returns the current date and time information indicated by the flag setting. The flag can be one of the following constants which are defined in the file SRD2.INC in the SRD21 directory.

DT_HOUR Returns the hour (0-23). DT_MINUTE Returns the minute (0-59). DT_SECOND Returns the second (0-59). DT_DAY Returns the day of the month (1-31). DT_WEEKDAY Returns the day of the week (0-6, Sunday is 0). DT_MONTH Returns the month (1-12). DT_YEAR Returns the year (as 4 digits). DT_TIMEZONE Returns the time zone in minutes from Greenwich mean time.

EXAMPLE:

include 'srd2.inc' proc SayTime is var hour, minute : integer; minute := DateTime( DT_MINUTE); hour := DateTime( DT_HOUR); Out( 'its '); hour := hour mod 12; If hour = 0 Then hour := 12; Endif; If minute = 0 Then Msg( hour,' oclock '); Else Msg ( hour, ' ', minute, ' o' 'clock '); Endif . . . var mytime : autohandle; Autospeak MyTime Watch DateTime( DT_MINUTE) Do If ( trigger( DT_MINUTE) mod 15) = 0 Then SayTime; Endif;

RESULT:

In this example, a procedure is defined to announce the time. It is then called and performed in the later autospeak to announce the time every 15 minutes. A procedure is used because then a key sequence could be defined to call SayTime at other times.

DIGITS

The DIGITS function converts an integer to a string of digits.

SYNTAX:

DIGITS ( integer)

EXAMPLE:

var Year : Integer;

Year := Int( Display( 1, Col+1, 4));

Proc SayYear is If (month = 1) and (selector.row = 3) and (number > '24') then Year := Year - 1; Elseif (month = 12) and (selector.row > 6) and (number < '13') then Year := Year + 1; Endif; Msg( Digits(Year));

RESULT:

In this example, the variable year is declared as an integer. It is necessary to make year an integer so that it can be manipulated mathematically.

Year is then assigned the integer value of the string at a specific position on the display. The procedure is used in the P M Diary application to check the year. If the month is January but the day is part of the previous month, year is decremented by 1. If the month is December but the day is part of the next month, year is incremented by 1.

To announce the year, the procedure uses the Digits function to turn the integer year back to a string so that it will be more easily read.

RELATED TOPICS:

Int function.

DISPLAY

The DISPLAY function returns a string of characters from the display.

SYNTAX:

DISPLAY ( row, column, length [ , filter [ , direction]])

DISPLAY ( row, column, word [ , filter])

REMARKS:

A string of the specified length, or the word, is returned from the display starting at the position specified by row and column. If the length specified exceeds the right edge of the viewport, the string is returned from the starting position to the right edge of the viewport.

The arguments for filter and direction are Boolean. If the filter is True (the default), the string returned is filtered using the current Screen Reader/2 settings of Graphics, Ignore and the special characters (set up in .TTS file). If the filter is False, Screen Reader/2 settings are ignored and the string is returned as displayed.

If the direction is True (the default), Screen Reader/2 retrieves a string horizontally, from left to right, from the display starting at the specified row and column. If the direction is False, Screen Reader/2 retrieves a string vertically, from top to bottom, from the display starting at the specified row and column.

ERROR CONDITIONS:

If the row is set to greater than View.Rows or the column is set to greater than View.Cols, you hear an error message and the return code, (RC), is set to a number

other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

var ahInsert : autohandle; Autospeak ahInsert watch Display( View.rows, 52, 1) Do If trigger = 'I' Then Msg( 'insert'); Else Msg( 'replace'); Endif;

RESULT:

In this example, the autospeak watches the display at the specified position for a string of one character. The read-only variable trigger contains the value of the expression resulting from this Display function. If trigger is I, Screen Reader/2 says "insert." It says "replace" when that value changes.

RELATED TOPICS:

Char function.

EXISTS

The EXISTS function returns True if a file exists and False if a file does not exist.

SYNTAX:

EXISTS ( string)

REMARKS:

The string specifies the name of a file. True is returned if the file exists; False is returned if the file does not exist. This function can be used before an OpenFile command or an Push command in order to prevent an error from occurring with these commands.

EXAMPLE:

{(AB)} 'Push a profile' Var str : string; Msg( 'Enter profile name.'); Read( str); If Length( str) = 0 then Msg( 'push cancelled'); Exit; EndIf; Stop; If Exists( ProfDir+'\'+str+'.kbj') Then Push( str); Msg( 'The ', str, ' profile is now active'); Else Msg( 'This profile does not exist.'); Endif;

RESULT:

In this example, chord A B is defined to add a profile to the current profile tier. The Exists function is used to check that the specified profile exists.

INT

The INT function converts a string to an integer.

SYNTAX:

INT ( string)

REMARKS:

The string can contain an optional leading minus sign (-) and the numeric characters 0-9 only.

ERROR CONDITIONS:

If the string begins with non-numeric characters, the Int function returns 0. If the string begins with a numeric character but contains non-numeric characters, the Int function converts the string up to the first non-numeric character to an integer. The rest of the string is ignored.

EXAMPLE:

var str : string; var InputNumber : integer; Save( Trap); Set( Trap, Off); Msg( 'Enter a number between 1 and 1000 from the keyboard'); Read( str); InputNumber := Int( str); If InputNumber <= 0 or InputNumber >1000 Then Msg( 'please try again'); Endif;

RESULT:

In this example, the user is asked to input a number from the keyboard. It is read in as a string. The Int function is used to convert that string to an integer.

RELATED TOPICS:

Digits function.

KEYPAD

The KEYPAD function returns a key or chord from the keypad as a string.

SYNTAX:

KEYPAD ( [ timeout])

REMARKS:

The Keypad function stops processing of the statement sequence until a keypad key is pressed. When the key is pressed, the string returned is that key.

If a chord is pressed, Keypad returns the two keys of that chord.

The optional timeout argument is a Boolean value. If the timeout value is True, the Keypad function will fail (and return the empty string) after the key delay specified in the Screen Reader/2 message file. If the timeout value is False (the default), Screen Reader/2 will wait indefinitely for a key sequence to be pressed.

RELATED TOPICS:

KeyVal function. Keypad command.

KEYVAL

The KEYVAL function gets a value from the keypad.

SYNTAX:

KEYVAL ( [ timeout])

REMARKS:

The KeyVal function stops processing of the statement sequence until a keypad key is pressed. When the keypad key is pressed, an integer value is returned. The values of the keypad keys 0-9 are 0-9. The values of the other keypad keys are:

A 10. B 11. C 12. D 13.

  • 14.
  1. 15.

STOP 16. HELP 17.

The optional timeout argument is a Boolean value. If the timeout value is True, the KeyVal function will fail (and return -1) after the key delay specified in the Screen Reader/2 message settings file. If the timeout value is False (the default), Screen Reader/2 will wait indefinitely for a keypad key to be pressed.

EXAMPLE:

{A1} 'set pitch' VAR pitch1 : integer; pitch1 := KeyVal(); While (( pitch1 < 1) or ( pitch1 > 9)) Do Msg( 'enter a number between 1 and 9'); pitch1 := KeyVal(); Endwhile; Set( Pitch, pitch1); Msg( 'pitch ', pitch1);

RESULT:

In this example, the key sequence A 1 is defined to set the pitch of the synthesizer. The KeyVal function is used to assign the value of the keypad key press to the variable pitch1.

RELATED TOPICS:

Keypad function. Keypad command.

LENGTH

The LENGTH function returns the length of a string.

SYNTAX:

LENGTH ( string)

LOWER

The LOWER function converts a string to lowercase.

SYNTAX:

LOWER ( string)

REMARKS:

The LOWER function converts the alphabetic characters in the string argument to lowercase.

RELATED TOPICS:

Upper function.

MODULENAME

The MODULENAME function returns the name of a profile.

SYNTAX:

MODULENAME ( number)

REMARKS:

When a profile is pushed onto a profile tier, the profile number for this new profile is 0. The numbers for the profiles already on the tier are each then incremented by 1. You might use this function to find out the name of the last profile pushed onto the tier or to hear the list of all profiles on the tier.

ERROR CONDITIONS:

If the profile does not exist in the current profile tier, the ModuleName function returns the empty string.

EXAMPLE:

{(AD)} 'Get list of modules loaded' var num : integer; var str : string; num := 0; Save( Trap); Set( Trap, Off); str := Modulename( num); While Length( str) <> 0 Do Say( str); num := num + 1; str := Modulename( num); Endwhile;

RESULT:

In this example, chord A D is defined to announce the list of profiles that are currently active. The ModuleName function is used to initialize the variable str to the name of the last profile pushed on the profile tier. And, it is used in the While loop to repeatedly assign the name of the last profile pushed on the profile tier to the variable str.

RELATED TOPICS:

Push command. Pop command.

MOUSE

The MOUSE function returns information about the location of the mouse pointer.

SYNTAX:

MOUSE.modifier

REMARKS:

The modifiers valid for this function are:

Col Row View X Y

1. If the modifier is Col or Row, and if the mouse pointer is in a character cell, the value returned is the column or row, respectively, of that character relative to the current viewport. If the mouse pointer is not on a character or is outside of the viewport, then the value returned is 0.

2. If the modifier is View, the value returned is the viewhandle for the view containing the mouse pointer.

3. If the modifier is X or Y, the values returned are pixel coordinates of the mouse pointer relative to the Desktop.

For an example using the Mouse function, refer to the Mouse command.

RELATED TOPICS:

Mouse command.

POS

The POS function compares strings and determines the first position where the strings match.

SYNTAX:

POS ( string, string)

REMARKS:

Pos returns an integer indicating the position at which the first string matches the second. If no match is found, Pos returns 0.

EXAMPLE:

var Needle : string; var Haystack : string; var WhereInHay : integer; Needle := 's'; Haystack := 'haystack'; WhereInHay := Pos( Needle, Haystack);

RESULT:

In this example, the Pos function is used to find the first position in the word haystack that is the character s. The function returns the value 4 because the character s is the fourth character in the word haystack.

RELATED TOPICS:

Substring function.

SELECTOR

The SELECTOR function returns information for a specified selector relative to the current view.

SYNTAX:

SELECTOR [( n)]

SELECTOR.modifier [( n)]

REMARKS:

If you use the Selector function without a modifier and no argument, text is returned for the first selector relative to the current view. If you do specify an argument, the text for the selector that is represented by the argument n is returned. This too is relative to the current view.

If you use the Selector function with a modifier and do not specify an argument, information is returned for the first selector. If you include an argument, the information is returned for the selector represented by n.

If the specified selector does not exist or if no selector exists for the current view, 0 is returned if a modifier is used or a zero length string is returned if no modifier is used.

The modifiers valid for this function are:

Top Bottom Left Right Row Col Style

1. If the modifier is Bottom, Left, Right, or Top, the value returned is relative to the current view.

2. If the modifier is Col or Row, the value returned is the column or row, respectively, of the first character of the specified selector relative to the current viewport.

3. If the modifier is Style the value returned is the style of the specified selector. Each selector style is explained below and its value is listed in the file SRD2.INC in the SRD21 directory:

1 Dotted box style. 2 Highlighted style. 4 Special selectors (like the type in Excel and Lotus spreadsheet cells).

RELATED TOPICS:

Selectors read-only variable.

STATUS

The STATUS function returns status information for a view.

SYNTAX:

STATUS ( viewhandle [ , flag])

REMARKS:

The Status function gives specialized information about a view depending on its class.

The class is identified by the viewhandle.

Status information is retrieved for these classes:

Check boxes. Menus. Scroll bars. Radio buttons.

The flag argument is used if the class is scroll bar or menu. The flag values are defined in the file SRD2.INC in the SRD21 directory.

1. If the class is check box or radio button, a 1 is returned if the box or button is checked or selected and a 0 is returned if the box or button is not checked or selected.

2. If the class is menu, the following information is returned depending on the flag:

MS_ATTRIBUTES. The attributes of the currently highlighted menu item are returned as an integer constant. The attribute constants defined in SRD2.INC are:

MIA_FRAMED

NOTE: For a Windows application, this attribute is returned for a system menu.

MIA_CHECKED MIA_DISABLED MIA_HILITED

MS_ALTLETTER The integer returned has the low-order byte set to the character that represents the accelerator key, if one exists. If no accelerator key exists for the current menu item, the low-order byte of the integer returned is set to 0.

NOTE: The character that represents the accelerator key is the one that appears underlined on the display and should work with the Alt key to select that item.

MS_SUBMENU A submenu associated with the currently highlighted menu item is indicated by the low order byte of the integer returned. If that integer returned is not zero, the current menu item has a submenu.

3. If the class is scroll bar, the following information is returned depending on the flag:

SB_FIRST The integer returned is the slider position (SB_cThumb) + 1. SB_LAST The integer returned is the number of data items visible (SB_cVisible) + the slider position (SB_cThumb) if not at the bottom of the scrollable list. Otherwise, for SB_Last, the integer returned is the number of data items available (SB_cTotal). SB_TOTAL The integer returned is the number of data items available if not 0. Otherwise, for SB_Total, the integer returned equals SB_Last + 1. SB_CVISIBLE The integer returned is the number of data items visible. SB_POSFIRST The integer returned is the first boundary of the scroll bar range. SB_POSLAST The integer returned is the last boundary of the scroll bar range. SB_POSTHUMB The integer returned is the slider position. SB_CTOTAL The integer returned is the number of data items available.

NOTE: Scroll bar information is not available for Windows applications.

EXAMPLE:

var BoxView : viewhandle; var BoxCheck : autohandle; var LastStatus : Integer;

Autospeak BoxCheck Watch Status( BoxView) Do If trigger = LastStatus Then Exit; Endif; If trigger = 1 then Msg( 'checked'); Else Msg( 'not checked'); Endif; LastStatus := trigger;

RESULT:

In this example, the Status function is used to determine whether or not a button is checked. An autospeak uses that information to announce the status.

RELATED TOPICS:

View function.

SUBSTRING

The SUBSTRING function returns the part of a string beginning at a specified offset (position within a string) and having a specified length.

SYNTAX:

SUBSTRING ( string, offset, length)

EXAMPLE:

var ErrorlineWatch : autohandle; var errorline : integer;

Autospeak ErrorlineWatch Watch Display( errorline, 1, 8) Do If Substring( trigger, 1, 5) <> '====>' Then Get( errorline, 1); Say( Line); EndIf;

RESULT:

In this example, an autospeak is set up to watch for a change in the error line from column 1 for a length of 8. The SubString function is used to pause the string trigger. If the result of that operation shows that the line is not a command prompt, the local pointer is set to the error line at column 1 and Screen Reader/2 reads the line.

RELATED TOPICS:

Pos function.

SWITCHLIST

The SWITCHLIST function returns the Window List entry for the foreground applications.

SYNTAX:

SWITCHLIST

REMARKS:

The information returned is a string.

EXAMPLE:

static Window_List : array[0..10] of string[20];

{(C9)} 'Get current Window List entry info into numbered entry' var num : integer;

num := KeyVal( True); Window_List[num] := SwitchList; Msg( 'saved ', Window_List[num], ' as entry ', num);

RESULT:

In this example, chord C 9 is defined to save a Window List entry as a specific number. The SwitchList function causes Screen Reader/2 to get the Window List entry information for the current foreground application. That entry information is then stored in the Window_List array as the element with an index number that the user entered from the keypad.

RELATED TOPICS:

FrameList command. SwitchList command.

UPPER

The UPPER function converts a string to uppercase.

SYNTAX:

UPPER ( string)

RELATED TOPICS:

Lower function.

VIEW

The VIEW function returns information for the view indicated by the viewhandle.

SYNTAX:

VIEW

VIEW.modifier [( viewhandle)]

REMARKS:

If you specify a viewhandle argument, information is returned for that view. If you do not specify a viewhandle, information about the current view is returned. Without the modifier, the viewhandle of the current view is returned. Note that View.modifier( View)

and View.modifier return the same results for each modifier.

The valid modifiers for this function are:

Top Bottom Left Right FirstChild NextAVIO NextSibling Parent ID Class Style Type Rows Cols

1. If the modifier is Top, Bottom, Left, or Right, the values returned are relative to the Desktop.

2. If the modifier is Class, the value returned is a string which is the class name of the view.

In general, a class is a name assigned to a window by the application program. Many classes of windows however, are standard P M controls. These standard classes are listed below and in the file SRD2.INC.

'#1' Frame. '#2' Combo (combination box). '#3' Button. '#4' Menu. '#5' StaticText. '#6' Entry. '#7' ListBox. '#8' ScrollBar. '#9' TitleBar. '#10' MLE (multiple line entry field). '#32' SpinB (spin button). '#37' Container. '#40' Notebook.

3. If the modifier is FirstChild, the value returned is the viewhandle for the first child window of the specified view.

4. If the modifier is NextAVIO, the value returned is the viewhandle for the next AVIO (text) window that is a descendant of the specified view.

5. If the modifier is NextSibling, the value returned is the viewhandle of the next sibling of the specified view.

6. If the modifier is Parent, the value returned is the viewhandle of the parent view of the specified view.

7. If the modifier is ID, the value returned is the window ID of the view.

8. If the modifier is Style, the value returned is the P M style for a view. The value returned is a 32-bit value.

The file SRD2.INC in the SRD21 directory lists values of styles for some standard windows.

9. If the modifier is Type, the value returned is the type of the view. Each type value is explained below and is listed in the file SRD2.INC.

FS (1) OS/2 full-screen. DOS (2) DOS full-screen. AVIO (4) OS/2 text window. P M (8) P M window. POPUP (16) Text pop-up window. SEAMLESS (32) Seamless Windows window. DOSWINDOW (64) DOS window.

10. If the modifier is Rows or Cols, the integer returned is the number of rows or columns, respectively, in the specified view.

EXAMPLE 1:

include 'srd2.inc' var PMEntryWatch : autohandle;

Autospeak PMEntryWatch Watch crow Do If crow > 1 Then If View.Type = PM and View.Class( ViewFromRowCol( crow, 1)) = Entry Then Msg( 'entry'); Get( crow, 1); Say( Line); Endif; EndIf;

RESULT:

In this example, an autospeak is set up to announce the text associated with the contents of an entry field when it contains the cursor. The View function is used to determine the type and the class of the view.

EXAMPLE 2:

include 'srd2.inc'

If View.Style bitand WS_MINIMIZED <> 0 Then Msg( 'minimized'); Endif;

RESULT:

In this example, the View function is used to determine the style of the current view. If the style is minimized, then Screen Reader/2 announces "minimized."

EXAMPLE 3:

include 'srd2.inc'

{5} 'find AVIO windows' var v : viewhandle; If View.Type = AVIO Then v := View.Parent( View.Parent); Else v := view; Endif; View( View.NextAVIO (v) );

RESULT:

This example works for the terminal emulation program SOFTERM.EXE. When the first AVIO (text) screen comes up, the current view is the frame window, which is a graphics window. If key sequence 5 is pressed, the view changes to the first AVIO window, which is the main window with 25 rows. Now the current view type is AVIO. If key sequence 5 is pressed again, the parent of the parent of the AVIO window is the frame window again, so View.NextAVIO( v) returns the viewhandle of the next AVIO descendant of that frame, which is a one line status line. Pressing key sequence 5 again changes the view back to the 25 line AVIO view.

RELATED TOPICS:

Status function. ViewFromPoint function. ViewFromRowCol function. View command.

VIEWFROMPOINT

The VIEWFROMPOINT function returns the viewhandle of the window at specified Desktop pixel positions in Presentation Manager.

SYNTAX:

VIEWFROMPOINT ( x, y)

REMARKS:

If the view is a full-screen text view, its viewhandle is returned.

RELATED TOPICS:

View function. ViewFromRolCol function. View command.

VIEWFROMROWCOL

The VIEWFROMROWCOL function returns the viewhandle of the window containing the character at a specified row and column.

SYNTAX:

ViEWFROMROWCOL ( row, column)

REMARKS:

If the view is a full-screen text view, its viewhandle is returned.

EXAMPLE:

/* speak the window containing row r */ Proc Speak( num : integer) is View( ViewFromRowCol( num, 1) ); Save( View, Pointer, Wrap); Set( Wrap, On); Get( 1, 1); Say( Line);

RESULT: In this example, a procedure is defined to read the window that has the row num. The view is set, using the ViewFromRowCol function, and the local pointer is moved to the first row and first column of that view. Then, the information in that entire view is read.

RELATED TOPICS:

View function. ViewFromPoint function. View command.

VIEWPORT

The VIEWPORT function returns information for the current viewport.

SYNTAX:

VIEWPORT.modifier

REMARKS:

The valid modifiers for this function are:

Top. Bottom. Left. Right. Rows. Cols.

1. If the modifier is Top, Bottom, Left, or Right, the values returned are the corresponding pixel position of the viewport relative to the view. If the current view is a text window, these are character coordinates.

2. If the modifier is Cols or Rows, the value returned is the number of columns and rows, respectively, of the current viewport.

EXAMPLE:

Var BoxTop, BoxLeft, BoxBottom, BoxRight : Integer;

{CS} 'toggle view' If (( ViewPort.Top <> 1) Or ( ViewPort.Right <> ViewPort.Cols)) Then ViewPort( FullView); Msg( 'full view'); ElseIf BoxTop <> 0 Then Out( 'view set to box at: '); ViewPort( BoxTop, BoxLeft, BoxBottom, BoxRight); Msg( 'top ', Viewport.Top, ' left ', Viewport.Left, ' bottom ', Viewport.Bottom, ' right ', Viewport.Right); Else Msg( 'no box'); EndIf;

RESULT:

In this example, a procedure called by an autospeak finds the box corners and sets the values for BoxTop, BoxLeft, BoxBottom, and BoxRight. The ViewPort function is used here to determine whether or not the viewport is set to full view. The viewport is set either to the full view or to the box accordingly and appropriate information is spoken.

RELATED TOPICS:

ViewPort command.

SYSTEM STATEMENTS

A system statement is either an Autospeak or an Initialize statement. System statements must be used alone; they are not part of a key definition or declaration. In addition, key definitions are not allowed within a system statement. You can, however, include other PAL constructs such as declarations, commands, functions, and compound statements in the body of a system statement.

The conventions used to display the syntax of the system statements are described in the section Syntax.

AUTOSPEAK

AUTOSPEAK statements either watch expressions or wait for specified events to occur; in which case specified PAL statement sequences are executed.

SYNTAX:

AUTOSPEAK autohandle

WATCH expression

DO statementsequence;

REMARKS:

This syntax shows the autospeak that monitors an expression.

When the expression changes and remains changed for the delay assigned to that autospeak, the statement sequence is executed. The changed value of the expression is in the local read-only variable trigger. It is local to the body of the autospeak and its type is the same as that of the watched expression.

The autohandle names the autospeak and must be declared before it is used. You can also use the autohandle to turn the autospeak On or Off with the Auto command and to change the autospeak delay with the AutoDelay command.

The autohandle can name only one autospeak in a profile tier. You can use a static autohandle to name an autospeak. The advantages of using a static autohandle are:

1. The static autohandle is shared among all profile tiers. Each session has a profile tier. If an

autospeak is turned off in one profile tier, the autospeak is turned off for all profile tiers.

2. If an autospeak with a static autohandle is watching a value that changes from session to session, the autospeak will be triggered from session to session. For example, an autospeak with a nonstatic autohandle watching the title variable may announce the title of a window as the session is started. However, when you return to that session, the title is not announced again because it has not changed. If the autohandle is static for the autospeak watching title, the title is announced each time you switch sessions.

NOTE: Do not use an external autohandle. External variables are declared in other profiles. The nature of the profile tier is such that the profile in which the autohandle is declared could be popped while other active profiles might try to use the autohandle.

EXAMPLE:

var BoxView : viewhandle; var BoxCheck : autohandle;

Autospeak BoxCheck Watch Status( BoxView) Do If trigger = 1 Then Msg( 'checked'); Else Msg( 'not checked'); Endif;

RESULT:

In this example, an autospeak is set up to watch an expression and tell the user whether or not a check box is checked.

SYNTAX:

AUTOSPEAK autohandle

WATCH event

DO statementsequence;

REMARKS:

This syntax shows an autospeak that monitors for an event.

The rules for autohandles are exactly the same as stated previously for autospeaks that watch expressions.

Screen Reader/2 is an event-driven process. It waits for events to occur; then it takes appropriate action.

When an autospeak watches an event, and that event occurs, Screen Reader/2 waits for the specified autodelay, and if the event does not occur during the wait, Screen Reader/2 executes the body of the statement sequence.

The data associated with an event are contained in the read-only variable trigger. It is local to the body of the autospeak and its type is the same as the watched event.

Events are:

EventCursorChange. EventDeviceIn. EventExternal. EventIndexIn. EventKeyPressed. EventMouseMove. EventPointerChange. EventProcessChange. EventSelectorChange. EventShiftChange. EventSpinButton. EventViewChange. IconScan. WordScan.

1. If the autospeak watches for an EventCursorChange, trigger is a viewhandle for the view containing the cursor. A cursor being created, deleted, or moved generates this event.

2. If the autospeak watches for an EventDeviceIn, trigger contains the character that was just sent from the output device (synthesizer or braille display) and the number of the device sending the character.

The first byte is the character and the second byte is the device number.

Device numbers are determined by the order in which .TTS files are loaded into Screen Reader/2 memory. The first file loaded is 0, the second file is 1, and so forth. Refer to the section Changing the Way Screen Reader/2 Starts in the Screen Reader/2 User's Guide for more information on loading multiple synthesizer files into Screen Reader/2 memory.

3. If the autospeak watches for an EventExternal, trigger is an integer that can be interpreted however desired. This event is provided for other processes to communicate with Screen Reader/2.

4. If the autospeak watches for an EventIndexIn, trigger has an integer type but its value is not set by Screen Reader/2. An index marker returned to Screen Reader/2 causes this event.

5. If the autospeak watches for an EventKeyPressed, trigger is an integer that identifies the key pressed on the keyboard.

The key presses are described below:

BYTE 0 ASCII code if a character key is pressed and 0 if any other keyboard key is pressed. BYTE 1 Untranslated scan code returned from BIOS for the key pressed. This scan code does not indicate the shift state of the keyboard. BYTE 2 Flag with bit values defined as: BIT 0 Shift key down. BIT 1 Ctrl key down. BIT 2 Alt key down. BIT 3 Set for the key break; zero for key make. EventKeyPressed is triggered with Bit 3 set (break) only when TrapKeys is on. BIT 4 The key is a stand-alone cursor key on an extended keyboard; it is not a cursor key on the numeric keypad. This bit is useful because the scan code is the same for stand-alone cursor keys and numeric keypad cursor keys in full screen sessions. BITS 5 TO 7 Zero BYTE 3 Not used.

NOTE: For more information about scan codes, ASCII codes, extended keys, and shift states, refer to the hardware technical reference for your system.

6. If the autospeak watches for an EventMouseMove, trigger is an integer indicating transitions of mouse movements. This event occurs when the mouse moves. The values for trigger are:

1 Window change. 2 Character change. 4 Frame window change. 8 Mouse pointer moved at least 10 pixels.

7. If the autospeak watches for an EventPointerChange, trigger is an integer that can be ignored. When an autospeak is monitoring EventPointerChange or EventIndexIn, it does not set a value in trigger.

Whenever the Screen Reader/2 pointer changes, this event occurs.

8. If the autospeak watches for an EventProcessChange, trigger is an integer that is the process ID of the process coming to the foreground. Whenever the current process changes, this event occurs.

9. If the autospeak watches for an EventSelectorChange, trigger is a viewhandle for the view that contains the selector. A selector being created, deleted, or moved causes this event.

10. If the autospeak watches for an EventShiftChange, trigger is a 16-bit integer representing the status of shift keys on the keyboard. A shift key being pressed causes this event.

The bit values of the integer trigger are:

BIT 0 Right shift down. BIT 1 Left shift down. BIT 2 Ctrl key down. BIT 3 Alt key down. BIT 4 Scroll Lock mode on. BIT 5 Num Lock mode on. BIT 6 Caps Lock mode on. BIT 7 Insert mode on. BIT 8 Left Ctrl key down. BIT 9 Left Alt key down. BIT 10 Right Ctrl key down. BIT 11 Right Alt key down. BIT 12 Scroll Lock key down. BIT 13 Num Lock key down. BIT 14 Caps Lock key down. BIT 15 Sys Request key down.

The integer read-only variable lockword also contains the status of shift keys.

11. If the autospeak watches for an EventSpinButton, trigger is a viewhandle for the spin button that has focus. This event occurs whenever a spin button control is used to change a value.

12. If the autospeak watches for an EventViewChange, trigger is a viewhandle for the view that is getting the focus. This event occurs whenever the view changes.

13. If the autospeak watches for an IconScan, trigger is a 32-bit integer that identifies an icon ID that may or may not be in the Screen Reader/2 icon table. This event occurs only if the Icons setting is On. Icon IDs are numeric codes associated with icons. The icon ID in trigger is the ID of the icon

encountered. Icon IDs and their associated text are listed in the file SRD2.ICN in the SRD21 directory.

NOTE: You can add icons unknown to Screen Reader/2 using the chord D #. This chord key sequence asks you to enter a text string that identifies the current icon. The current icon ID and the text string you enter will be added to the file SRD2.ICN.

14. If the autospeak watches for a WordScan, trigger is a 16-bit integer that represents changes detected while scanning a word. This event occurs only during the processing of data from the display if the WordScan setting is On.

The bit settings for trigger are:

BIT 0 LowerCase (No capital letters). BIT 1 UpperCase (All capital letters). BIT 2 MixedCase (At least one capital beyond the first letter). BIT 3 InitialUpper (First letter is a capital, but no other). BIT 4 HasVowel (Has a vowel). BIT 5 AllBlanks (All blanks). BIT 6 AllNumeric (All numeric). BIT 7 ColorChange (Color is different from previous word spoken). BIT 8 ColorMix (Color changes in word). BIT 9 FontChange (Font is different from previous word spoken). BIT 10 StyleChange (Style is different from previous word spoken). BIT 11 TrapWord (Current word is not spoken). BIT 12 SizeChange (Font size is different from previous word spoken). BIT 13 FontMix (Font changes in word). BIT 14 (Reserved). BIT 15 PostScan (Bit 15 is 0 if the word triggering the event has not yet been sent to the output device. Bit 15 is 1 if the word has already been sent to the output device).

EXAMPLE:

include 'srd2.inc' var SayCursorLine : Autohandle;

/* say cursor line if key pressed */ Autospeak SayCursorLine Watch EventKeyPressed Do var scan_code : integer; scan_code := (TRIGGER bitand &h0007ff00) >> 8; If (scan_code = Up_Arrow_Key or scan_code = Down_Arrow_Key or scan_code = Tab_Key or scan_code = BackTab_Key) Then Stop; Save( Viewport, Wrap, Pointer); Viewport( Fullview); Set( Wrap,off); Get( Crow,1); Say( Line); -- say the cursor line Endif;

RESULT:

In this example, an autospeak is set up to watch for any keyboard key being pressed. If the Up Arrow, Down Arrow, Tab or Back Tab keys are pressed, any current speech is stopped and the cursor line in the current view is spoken. The scan codes for the most common keyboard keys are defined in the SRD2.INC file in the SRD21 directory.

RELATED TOPICS:

Auto function. Auto command. AutoDelay command.

INITIALIZE

The INITIALIZE statement processes a statement sequence automatically when the profile is pushed onto the profile tier.

SYNTAX:

INITIALIZE statementsequence;

REMARKS:

The Initialize statement sequence is executed when the profile is pushed onto the profile tier. You can use as many Initialize statements as you want. Initialize statements in included profiles are also executed.

You can use the Initialize statement to set the various Screen Reader/2 states to values other than the defaults and for announcing the name of the profile.

EXAMPLE:

var PMSelectorControl, BoxCheck : autohandle; var NoStop, FirstBox : Boolean; var DefaultSelector : integer;

Initialize AutoDelay( PMSelectorControl, 2); Set( Mode, Pointer); NoStop := False; FirstBox := True; DefaultSelector := 1; Auto( BoxCheck, Off);

RESULT:

In this example, the Initialize statement is used to set the autodelay for an autospeak, the Screen Reader/2 mode, and the initial value of two variables. And, it turns an autospeak off.

SYNTAX:

INITIALIZE string statementsequence;

REMARKS:

The string is a program name. When a new program starts and an active profile has an Initialize statement with a string that matches the new program's name (including the extension .EXE), the statement sequence for that Initialize statement is executed. You can use the key sequence chord 7 8 then 8 to find out the current program name.

The most common use of the Initialize statement is to add an application-specific profile to the current tier. This use of the Initialize statement will not work for DOS applications.

If you want a new profile that you have written to be added to the profile tier when its corresponding application starts, create a MYINIT.KPD profile and add the appropriate Initialize statement. The SRD2.KPD profile has a TryInclude statement for the MYINIT.KPD profile.

After you create or update MYINIT.KPD, recompile the SRD2.KPD profile to include your new Initialize statement. Then restart Screen Reader/2 to make the new SRD2 profile active as the base profile tier.

EXAMPLE:

Initialize 'VIEWDOC.EXE' Push( 'View');

RESULT:

In this example, the Initialize statement is used to load the profile for the help and online book program when it starts.

RELATED TOPICS:

Pop command. Push command. TryInclude statement.

COMPOUND STATEMENTS

PAL has two kinds of compound statements. The Cycle statement combines statement sequences and must be assigned to a key sequence in a key definition. PAL also has the following control statements:

For If While

These statements enable you to write programming loops and conditionals.

The conventions used to display the syntax of the compound statements are described in the section Syntax.

CYCLE

The CYCLE statement defines one key sequence that alternates through several PAL statement sequences as that key sequence is successively pressed.

SYNTAX:

CYCLE statementsequence;

NEXTTIME statementsequence;

[NEXTTIME statementsequence;] ...

REMARKS:

When a Cycle command is assigned to a key sequence, pressing that key sequence the first time causes the first statement sequence to be executed. Pressing the key sequence the second time causes the second statement sequence to be executed, and so on, until the last statement sequence is executed. Then the cycle starts over with the first statement sequence.

The Cycle statement is not allowed in statement sequences.

EXAMPLE:

{B8} 'cycle word def settings' CYCLE Set( WordDef, ALPHABETIC union '); Msg('Alphabetic'); NEXTTIME Set( WordDef, ALPHABETIC union NUMERIC ); Msg('Alpha numeric'); NEXTTIME Set( WordDef, NONBLANK ); Msg('Non Blank');

RESULT:

In this example, the B 8 key sequence is defined to cycle between three different Screen Reader/2 definitions of a word.

FOR

The FOR statement processes a statement sequence until the value of a specified expression is reached.

SYNTAX:

FOR variable := expression1

TO expression2

DO statementsequence;

ENDFOR;

REMARKS:

In the For statement, a variable is initially assigned the value of expression1. If expression1 is equal to or less than expression2, the statement sequence is performed and the variable is incremented by 1.

Next, expression1 is evaluated again. If the new value does not exceed the value of expression2, the statement sequence is performed again. This process continues until the variable exceeds the value of expression2. Then, the command after the EndFor is executed.

Each For statement must close with an EndFor statement. For loops can be nested.

NOTE: Pressing a keypad key does not end a For statement sequence.

EXAMPLE:

var AhComm : array[1..4] of autohandle; var num : integer;

{CA} 'turn off autospeaks' For num := 1 to 4 Do Auto( AhComm[num], Off); EndFor;

RESULT:

In this example, the For statement is used to turn off four different autospeaks.

IF

The IF statement is used to conditionally perform PAL statement sequences.

SYNTAX:

IF expression1

THEN statementsequence1;

[ELSEIF expression2

THEN statementsequence2; ... ]

[ELSE statementsequence3;]

ENDIF;

REMARKS:

If, Then, and EndIf are required. You can use ElseIf and Else optionally. ElseIf can be used more than once, but only one Else is allowed.

When the If statement is executed in a key definition, expression1 is evaluated. If expression1 evaluates to True, statementsequence1 is executed and the command after the EndIf is executed next.

If the value of expression1 is not True, the ElseIf clauses, if any, are treated in the same way. If no expression evaluates to True and there is an Else clause present, its statement sequence is executed.

Nested If statements are allowed. Each If statement must close with an EndIf.

EXAMPLE:

include 'srd2.inc'

{#5} 'current format' If ( Format = Text) Then Msg( 'Text'); Elseif ( Format = Ascii) Then Msg( 'Ascii'); Elseif ( Format = Phonetic) Then Msg( 'Phonetic'); Elseif ( Format = Pronounce) Then Msg( 'Pronounce'); Else Msg( 'Unknown format'); Endif;

RESULT:

In this example, key sequence # 5 is defined to tell the user the active Screen Reader/2 format. The If statement is used to test which of the four formats is active.

WHILE

The WHILE statement is used to repeat a PAL statement sequence.

SYNTAX:

WHILE expression

DO statementsequence;

ENDWHILE;

REMARKS:

The expression is evaluated; if it is True, the statement sequence is performed. Then the expression is evaluated again. If it is still True, the statement sequence is performed again. This procedure is repeated as long as the expression evaluated is True.

Nested While statements are allowed. Each While statement must close with EndWhile.

NOTE: Pressing a keypad key ends a While statement sequence.

EXAMPLE:

{A1} 'set pitch' var pitch1 : integer; const Stop_key = 16; pitch1 := KeyVal(); While (( pitch1 < 1) or ( pitch1 > Stop_key) or (( pitch1 > 9) and ( pitch1 < Stop_key))) Do Msg( 'enter a number between 1 and 9'); Msg( 'or Stop to cancel'); pitch1 := KeyVal(); Endwhile; If Pitch1 = Stop_key Then Msg( 'Set pitch cancelled'); Else Set( pitch, pitch1); Msg( 'pitch ', pitch1); Endif;

RESULT:

In this example, the key sequence A 1 is defined to set the pitch of a synthesizer. The While statement is used to test for inputs outside of the correct range.

COMMANDS

Commands consist of a keyword, followed by arguments in parentheses, and are ended with a semicolon. Commands perform specific Screen Reader/2 tasks.

The conventions used to display the syntax of the commands are described in the section Syntax.

AUTO

The AUTO command turns an autospeak On or Off or specifies the view to use for evaluating the watched expression of an autospeak.

SYNTAX:

AUTO ( autohandle, On | Off);

DEFAULT:

All autospeaks defined in a keypad profile are On unless the Auto command is used to turn them Off.

REMARKS:

The autohandle identifies an autospeak.

EXAMPLE:

var PageWatch : autohandle;

{C4} ' toggle page watch autospeak ' If Auto( PageWatch) then Auto( PageWatch, Off); Out( 'No'); Else Auto( PageWatch, On); Endif; Msg ( 'PageWatch');

RESULT:

In this example, the Auto command is used to toggle an autospeak.

SYNTAX:

AUTO ( autohandle, [ FullView | ViewPort]);

DEFAULT:

FullView.

REMARKS:

The watched expression of the autospeak identified by the autohandle is evaluated relative to the fullview or viewport.

RELATED TOPICS:

Auto function. Autospeak statement. AutoDelay command.

AUTODELAY

The AUTODELAY command sets the length of time that the value of the watched expression of an autospeak must remain the same, ONCE IT HAS CHANGED, before the autospeak body is executed. When an autospeak is watching an event, autodelay sets the length of time that event must not be repeated. If the watched expression changes again or the event occurs again before the specified autodelay, the time starts over.

SYNTAX:

AUTODELAY ( autohandle, integer);

REMARKS:

Generally, autodelays are used to avoid spurious triggering of autospeaks or to cause one autospeak to trigger after another. For performance reasons, autodelays should be used with caution.

The autohandle is a variable that identifies an autospeak.

The integer is the time, in tenths of a second, required before the designated autospeak takes action.

RELATED TOPICS:

Auto function. Autospeak statement. Auto command.

BACKUPFILE

The BACKUPFILE command moves the position of a file pointer back one record.

SYNTAX:

BACKUPFILE ( filehandle);

REMARKS:

A filehandle is created when the file is opened.

RELATED TOPICS:

CloseFile command. OpenFile command. ReadFile command. ResetFile command. WriteFile command.

BEEP

The BEEP command sounds the computer speaker.

SYNTAX:

BEEP ( f, d);

REMARKS:

f is the frequency in hertz and d is the duration in milliseconds. Therefore, Beep( 40, 50) sounds the speaker at 40 hertz for 50 milliseconds.

EXAMPLE:

var ahTN : autohandle; var beeped : Boolean;

Autospeak ahTN Watch Display( View.Rows, 2, 1) Do If Trigger = 'X' Then Beep( 960, 10); beeped := True; Else If beeped Then beeped := False; Beep( 360, 10); Endif; Endif;

RESULT:

In this example, an autospeak is set up to watch the string produced by the Display function. If that value is 'X', then a 960 hertz beep is sounded for ten milliseconds. Otherwise, if a high-pitched beep had been sounded, a 360 hertz beep is sounded for ten milliseconds.

CLOSEFILE

The CLOSEFILE command closes a file.

SYNTAX:

CLOSEFILE (filehandle);

REMARKS:

The filehandle is created when the file is opened.

RELATED TOPICS:

BackupFile command. OpenFile command. ReadFile command. ResetFile command. WriteFile command.

CONTINUE

The CONTINUE command is used when a statement sequence is needed but you do not want Screen Reader/2 to do anything.

SYNTAX:

CONTINUE;

EXIT

The EXIT command ends the processing of a key definition, autospeak, or initialize statement.

SYNTAX:

EXIT;

EXAMPLE:

Refer to the example for the Status function.

FIND

The FIND command searches for a string or icon on the screen.

SYNTAX:

FIND ( string [ ,+|-, filter]);

FIND ( iconID [ ,+|-]);

DEFAULTS:

+ (Direction = Forward) Filter = True.

REMARKS:

The Find command moves the local pointer to a string or an integer icon ID. Refer to the Char.IconID function for more information about icon IDs.

The direction indicator is optional. + (true) is used to search for the string in a forward direction; - (false) is used to search backward.

If the optional filter argument for a string search is True, the string returned is filtered using the current Screen Reader/2 settings, regarding graphics (box characters), ignored characters, and capitalization.

ERROR CONDITIONS:

If the string or icon ID is not found, a message is announced. The return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

include 'srd2.inc' var searchst : string;

{#1} 'search forward from top' Msg( 'enter search string'); Read( searchst); If RC = 0 Then /* null string returned */ Stop; Msg( ' String search cancelled. '); Msg( ' No string input. '); Else Out( 'looking for '); Say(searchst); Save( Wrap, Trap, Caps); Set( Wrap, On); Set( Trap, Off); Set( Caps, Off); Set( Mode, Pointer); Get( 1, 1); Find( searchst, +, True); If RC = 0 Then Msg( 'found ', row, ' ', col); Else Msg( 'not found'); Endif; Endif;

RESULT:

In this example, the key sequence # 1, from OS2CORE.KPD, is defined to search for a string in a forward direction from the top. The Find command is used after a string has been read in with the Read command.

RELATED TOPICS:

Display function. Char.IconId function. Get command.

FRAMELIST

The FRAMELIST command displays a list of the titles of all frame windows in the current Presentation Manager application.

SYNTAX:

FRAMELIST ();

REMARKS:

The FrameList command causes a Presentation Manager window that contains a list of the titles of all main (frame) windows in the current P M application to be displayed.

After you select the window you want, by using the cursor keys and the Enter key, Screen Reader/2 switches focus to that window.

This command is useful if an application has more than one display area and you cannot switch from one window to another except by using the mouse. The VIEW program (for viewing online books) is an example of such an application.

EXAMPLE:

{(C0)} 'Display a list of available frames in the current P M application' FrameList();

RESULT:

In this example, chord C 0 will invoke the FrameList command to display a list of available frame windows in the current application.

RELATED TOPICS:

SwitchList function. SwitchList command.

GET

The Get command sets the position of the local pointer.

SYNTAX:

GET ( expression1, expression2 [ ,RowCol | Desktop]);

DEFAULT:

RowCol

REMARKS:

When a statement sequence begins, the local pointer is set to the Screen Reader/2 pointer if the current mode is pointer. The local pointer is set to the cursor if the current mode is cursor.

When the statement sequence is complete, the Screen Reader/2 pointer is set to the local pointer if the mode is pointer.

If you specify the optional argument RowCol, or you do not specify an optional argument, the Get command places the local pointer at the row and column specified by expression1 and expression2, respectively.

If you specify the optional argument Desktop, Get places the local pointer at the character position corresponding to the pixel coordinates specified by expression1 and expression2 (both relative to the Desktop).

ERROR CONDITIONS:

If either expression evaluates to a position outside the current viewport, you hear an appropriate error message.

If expression2 for the column position is less than the current setting for the left of, or greater than the current setting for the right of the current Screen Reader/2 viewport, you hear an appropriate message.

If either error condition occurs, the return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

{1} 'previous line' Get( row-1, 1); Say( Line);

RESULT:

In this example from OS2CORE.KPD, key 1 is defined to say the previous line. The Get command is used to set the local pointer at the first column of the previous line.

SYNTAX:

GET ( Cursor | Pointer | Mouse) ;

REMARKS:

If you use the Get command with the argument Cursor, Get places the local pointer at the computer's cursor. Get ( Cursor) has the same effect as Get ( crow, ccol).

If you use the Get command with the argument Pointer, Get places the local pointer at the Screen Reader/2 pointer. Get ( Pointer) has the same effect as Get ( prow, pcol).

If you use the Get command with the argument Mouse, Get places the local pointer at the mouse pointer. Get ( Mouse) has the same effect as Get ( Mouse.Row, Mouse.Col, RowCol) and Get ( Mouse.X, Mouse.Y, Desktop).

EXAMPLE:

{##} 'pointer to cursor or selector' Set( Mode, Pointer); If Crow <> 0 Then Get( Cursor); Msg( 'Pointer to cursor at row ', row, ' column ', col); ElseIf Selector.Row <> 0 Then Get( Selector.Row, Selector.Col); Msg( 'Pointer to selector at row ', row, ' column ', col); Else Msg( 'no cursor or selector'); Endif;

RESULT:

In this example, the key sequence # # is defined to move the pointer to the cursor or selector. The Get command is used to set the local pointer position to that of the cursor or selector.

SYNTAX:

GET ( NextWord | Word | PrevWord);

GET ( NextSentence | Sentence | PrevSentence);

REMARKS:

This use of the Get command moves the local pointer to the beginning of a specified word or sentence. The arguments have the following meaning:

1. If you use either NextWord or NextSentence, the Get command sets the local pointer to the word or sentence following the current word or sentence.

2. If you use either Word or Sentence, the Get command sets the local pointer to the beginning of the current word or sentence.

3. If you use either PrevWord or PrevSentence, the Get command sets the local pointer to the beginning of the preceding word or sentence.

To change the definition of a word, use the Set command with the WordDef argument.

ERROR CONDITIONS:

For Get( PrevWord), if no words are to the left of the current word, or with Wrap on, if the current word is the first word on the screen, a message is announced.

For Get ( NextWord), if no words are to the right of the current word, or, with Wrap on, if the current word is the last word on the screen, a message is announced.

If either error condition exists, the return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

{6} 'next word' Get( Nextword); Say( Word);

RESULT:

In this example, key 6 is defined to say the next word.

SYNTAX:

GET (NextField | Field | PrevField [, mask]);

REMARKS:

A field is a sequence of characters that have the same display characteristics, such as color and font. If the Wrap setting is On, a field can span more than one line.

The Get command moves the local pointer to the beginning of a specified field:

1. If you use NextField, the Get command sets the local pointer to the beginning of the field to the right of the current field. If Wrap is on, the search continues down the display.

2. If you use Field, the Get command sets the local pointer to the beginning of the current field.

3. If you use PrevField, the Get command sets the local pointer to the beginning of the field to the left of the current field. If Wrap is on, the search continues up the display.

You can optionally use the following mask values, which can be used alone or ORed together. These values are defined in the file SRD2.INC:

FG The field is defined using only the foreground color.

BG The field is defined using only the background color.

MIX The field is defined using both foreground and background colors (FG BitOr BG).

FONTSTYLE The field definition includes changes in font style.

FONTNAME The field definition includes changes in font names.

FONTSIZE The field definition includes changes in font size.

ANYFONT The field definition includes any type of font change (FontSize BitOr FontName BitOr FontStyle).

ERROR CONDITIONS:

For Get( PrevField) if no fields are to the left of the current field, or, with Wrap on, if the current field is the first field on the screen, a message is announced.

For Get( NextField), if no fields are to the right of the current field, or, with Wrap on, if the current field is the last field on the screen, a message is announced.

If any of these error conditions exists, the return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

{*1} 'previous field' Save( Wrap, Trap); Set( Wrap, On); Set( Trap, Off); Get( PrevField, Mix); If rc = 0 Then Say( Field, Mix); Else Msg( ' first field'); EndIf;

RESULT:

In this example, key sequence * 1 is defined to speak the previous field determined by color.

SYNTAX:

GET ( SameAttr | DiffAttr, expression1, maskexpression, + | -);

REMARKS:

This Get command sets the position of the local pointer depending on attributes associated with each character on the display.

To find changes in color, use this version of the Get command to move the local pointer to the first character to the right (+) or the left (-) that has color attributes which, when masked by the value of the maskexpression, are equal to (SameAttr) or different from (DiffAttr), the value of expression1.

You can use the following mask expressions. These are listed in the file SRD2.INC:

FG Specifies to use only the foreground color.

BG Specifies to use only the background color.

MIX Specifies to use both foreground and background colors (FG BitOr BG).

ERROR CONDITIONS:

If the search is not successful, a message is announced and the return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

include 'srd2.inc'

{(C5)} ' read current highlighted menu option ' Save( Pointer, Trap); Get( 2, 1); Set( Trap, Off); Get( SameAttr, 2560, Mix, +); If RC = 0 Then Say( Field); Else Msg(' no highlighted option '); Endif;

RESULT:

NOTE: This example assumes that the profile writer has studied the application for which chord C 5 is to be used and found that the numeric value of the color of the desired highlight was 2560. He could have used Screen Reader/2's Char.Color function to determine this information.

In this example, chord C 5 is defined to look for a highlighted menu option beginning at row 2 column 1 on a Lotus 1 2 3 full screen. If characters with the 2560 attributes are found on the screen, then that field is spoken. Otherwise, the message "no highlighted option" is spoken.

RELATED TOPICS:

Char.Color function. Mouse function. Selector function.

HELP

The HELP command toggles help mode On or Off.

SYNTAX:

HELP;

REMARKS:

The Help command is a toggle. When the Help command is first executed, pressing subsequent key sequences result in their help text being spoken, rather than having their statement sequences executed. When the Help command is next executed, Screen Reader/2 returns to normal operation.

KEYIN

The KEYIN command causes from one to four keyboard scan codes to be sent to the keyboard controller.

SYNTAX:

KEYIN ( scan codes);

REMARKS:

The scan codes argument is a four-byte integer that can contain one, two, three, or four scan codes. The scan codes are sent directly to the keyboard controller as if the corresponding keys on the keyboard had been pressed. The lowest-order byte contains the first scan code to be sent to the keyboard controller, and the highest-order byte contains the last scan code.

You can find scan codes in the SRD2.INC file under the heading "keyboard scan codes returned for EventKeyPressed." In addition, you can use chord A 1 then 0 to announce the scan code of a character on the display screen.

NOTE: Some scan codes are listed in hexadecimal in the SRD2.INC file and are announced in decimal by chord A 1 then 0. For more information about scan codes, refer to the hardware technical reference book for your system.

For each make scan code sent, it is recommended that you eventually send its break scan code.

This command may not work on non-IBM systems.

EXAMPLE:

{BS} 'bring up desktop pop-up menu' Keyin( &h0819d011d); /* Ctrl+Esc */ Sleep( 500); Keyin( &h08101); /* Esc */ Sleep( 500); Keyin( &h00F2A38); /* Alt+Shift+Tab make

  • /

Keyin( &h0B8AA8F); /* Alt+Shift+Tab break

  • /

Sleep( 1); Keyin( &h0ab9d2b1d); /* Ctrl+\ */ Sleep( 1); Keyin( &h0c4aa442a); /* Shift+F10 */

RESULT:

In this example, the key sequence B Stop displays the Desktop pop-up menu without pressing all of the keyboard keys needed to display that menu. Each KeyIn statement in the sequence causes a keyboard key to be sent to the keyboard controller as if it was pressed.

The comments in this example indicate which keys are being simulated. The Sleep commands between Keyin commands are included because as each key is simulated, time is needed for the system to perform the key press action before doing the next. If the Sleep commands were not included, it is possible that the system would queue all of the key presses up and the actions may or may not be performed.

RELATED TOPICS:

Keypad command.

KEYPAD

The KEYPAD command causes a key sequence to be processed by Screen Reader/2 as if the key sequence had been pressed on the Screen Reader/2 keypad.

SYNTAX:

KEYPAD ( string [,Boolean]);

DEFAULT:

The Boolean argument is True, causing Screen Reader/2 to send a stop control sequence at the time the key sequence is being processed.

REMARKS:

The string is a keypad key sequence without the braces. Refer to the KEYPAD.KPD profile. In that profile, which defines the keys for the pop-up keypad, keyboard input is interpreted as keypad input by using the Keypad command.

If the optional Boolean argument is True and Always Stop is checked in the synthesizer settings notebook, then your device's control code for stopping speech is sent when a key press is simulated. If the Boolean argument is False or Always Stop is not checked, then the stop control code is not sent. This argument should be False for emulated key sequences that process alternate output such as Braille because you do not want to stop normal speech output from being heard.

RELATED TOPICS:

Keypad function. KeyVal function. KeyIn command.

MAP

The MAP command converts a position from one coordinate system to another.

SYNTAX:

MAP ( RowCol | Desktop | View, RowCol | Desktop | View, x, y, xresult, yresult);

REMARKS:

The first argument, (either RowCol, Desktop, or View), specifies the coordinate system of the source (that is, the input) x, y position. The second argument, (either RowCol, Desktop, or View), specifies the target coordinate system; that to which the input position is to be converted.

If the first argument is RowCol, x and y are row and column coordinates. If you specify Desktop or View instead, x and y are pixel coordinates.

x and y are the coordinates you want to convert. The converted coordinates are xresult and yresult.

RELATED TOPICS:

View function. ViewFromPoint function. ViewFromRowCol function.

MOUSE

The MOUSE command can position the mouse pointer or simulate mouse actions. It is also used to control tracking of mouse movements.

SYNTAX:

MOUSE ( x, y [ ,RowCol | Desktop]);

REMARKS:

This version of the Mouse command positions the mouse pointer at row x and column y if you do not specify an optional argument or if you specify RowCol as the optional argument. If you specify Desktop as the optional argument, the mouse pointer is positioned at the specified x and y pixel coordinates (relative to the Desktop).

SYNTAX:

MOUSE ( Button1 | Button2 , ButtonClick | ButtonDoubleClick );

REMARKS:

This Mouse command simulates a single or double click of mouse button 1 or a single click of mouse button 2.

The values for the second argument (ButtonClick, ButtonDoubleClick) are defined in the file SRD2.INC in the SRD21 directory.

EXAMPLE:

include 'srd2.inc' {(CA)} 'double click' Mouse( Row, Col, RowCol); Mouse( Button1, ButtonDoubleClick);

RESULT:

In this example, the chord C A is defined to simulate a mouse button 1 double click. The Mouse command is used in both ways described so far:

1. To move the mouse pointer to a specific row and column. 2. To simulate the double click on mouse button 1.

SYNTAX:

MOUSE ( track, flag);

REMARKS:

This version of the Mouse command tells Screen Reader/2 to generate an EventMouseMove if mouse movement of the type specified by flag is detected.

BIT 0 Window changes. BIT 1 Mouse.Row or Mouse.Col changes. BIT 2 Frame changes. BIT 3 Mouse moved 10 or more pixels.

EXAMPLE:

var MouseAuto : autohandle; var rlast : Integer; var vlast : viewhandle;

Initialize Mouse( Track, &HF );

Autospeak MouseAuto Watch EventMouseMove Do

Save( View); View( Mouse.View); If Trigger = 2 Then -- Row or column change If Mouse.Row <> 0 Then Get( Mouse.Row, 1); If ( row <> rlast) or ( View <> vlast) Then rlast := row; vlast := view; Say( Line); Endif; Endif; Endif;

RESULT:

In this example, an Initialize statement turns on mouse tracking for all types of mouse movement (window changes, mouse.row or mouse.col changes, frame changes, or mouse pointer changes of 10 or more pixels). Then, an autospeak is set up to watch for any of these mouse movements.

RELATED TOPICS:

Autospeak statement. Mouse function. Map command.

MSG

The MSG command specifies text, numbers, or Screen Reader/2 states to be announced.

SYNTAX:

MSG ( string | integer | Boolean);

MSG ( Pointer | Cursor | Format | Mode);

REMARKS:

You can use multiple strings, integers, or Booleans as arguments. Just be sure to separate the arguments with commas.

When the argument is a string, that string is sent to the speech synthesizer. When the argument is an integer or a Boolean, the current value of that integer or Boolean is spoken.

When the argument is a Screen Reader/2 state, the current value of that state is announced. For example, Msg( Format) announces "text" when Screen Reader/2 is in text mode; Msg( Pointer) announces the position of the Screen Reader/2 pointer.

In all cases, the control sequence to begin speaking is sent to the synthesizer after the message. The Out command does not send that commence speaking sequence. The Say command speaks data from the screen, such as lines and words, and sends the commence speaking code. When the Msg command has several arguments, the commence speaking code is only at the end. Thus, Msg( x, y) is the same as Out( x); Msg( y).

EXAMPLE:

{*#} 'spell format' Set( Format, Spell); Set( Table, 'Default' ); Msg( Format, ' format');

{**} 'text format' Set( Format, Text); Set( Table, 'Default' ); Msg( 'Text format');

RESULT:

In this example, the key sequences * # and * * are defined to start spell and text format respectively. The Msg command is used to tell the user the format.

RELATED TOPICS:

Get command. Out command. Say command.

OPENFILE

The OPENFILE command opens a file.

SYNTAX:

OPENFILE ( filehandle, string [,Boolean]);

REMARKS:

The filehandle is returned, which allows later access to the file with other PAL file commands such as BackupFile, CloseFile, ReadFile, ResetFile, and WriteFile. The string specifies the name of the file to open.

If the optional Boolean argument is True, the file is opened with read/write access. If the Boolean argument is not specified or is False, the file is opened with read-only access.

ERROR CONDITIONS:

If a file I/O error occurs when this command is used, the Screen Reader/2 return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

const filename = 'srdpm.tut'; var str : string;

var fhandle : FileHandle;

Initialize Msg( ' tutorial'); OpenFile( fhandle, filename); ReadFile( fhandle, str);

RESULT:

In this example, the OpenFile command is used to open the file srdpm.tut.

RELATED TOPICS:

BackupFile command. CloseFile command. ReadFile command. ResetFile command. WriteFile command.

OUT

The OUT command sends a string or number to the synthesizer without sending the commence speaking control sequence.

SYNTAX:

OUT ( string | integer | Boolean);

OUT ( Pointer | Cursor | Format | Mode);

REMARKS:

You can use multiple strings, integers, or Booleans as arguments. Just be sure to separate the arguments with commas.

When a string, integer, Boolean, or value of a Screen Reader/2 state is sent to the synthesizer by means of the Msg command or Say command, the control string that starts speech is also sent. When the string, integer, Boolean, or value of a Screen Reader/2 state is sent to the synthesizer by using the Out command, it is held until a Msg or Say command is used.

EXAMPLE:

{A4} 'caps on or off' If Caps Then Set( caps, Off); Out( 'no '); Else Set( caps, On); EndIf; Msg( 'caps');

RESULT:

This example toggles the caps switch. The out command is used to put 'no' before 'caps' when the switch is turned off.

RELATED TOPICS:

Msg command. Say command.

POP

The POP command removes the last profile from the current profile tier.

SYNTAX:

POP;

ERROR CONDITIONS:

If no profiles on the current tier can be popped, the Screen Reader/2 return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

RELATED TOPICS:

ModuleName function. Initialize statement. Push command.

PUSH

The PUSH command adds a profile to the current profile tier.

SYNTAX:

PUSH ( string);

REMARKS:

Profiles must be in the directory specified by the SRDPROFILES environment variable.

If a profile that is pushed contains a key sequence already defined in another profile on the tier, the key definition in the new profile is the active one.

ERROR CONDITIONS:

If the profile specified cannot be found or some other I/O error occurs, the Screen Reader/2 return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

include 'srd2.inc' initialize 'epm.exe' push( 'epm' );

RESULT:

In this example, the profile for a program called EPM is added to the current tier when that program is started.

RELATED TOPICS:

Initialize statement. ModuleName function. Pop command.

READ

The READ command gets character input from the keyboard and assigns the characters to a string variable.

SYNTAX:

READ ( string);

REMARKS:

The length of the string read from the keyboard is limited to the declared length of the string variable.

The Screen Reader/2 return code, (RC), is set to the length of the string input. If the return code is set to 0, nothing was entered from the keyboard.

EXAMPLE:

include 'srd2.inc'

{#H} 'start ignoring 1 or more characters' var IgnoreSt : string; Msg( ' enter characters to start ignoring'); Read( IgnoreSt); If RC = 0 Then -- null string entered Msg(' cancelled '); Else Out( ' start ignoring '); Save( Format); Set( format, Spell); Say( IgnoreSt); Set( ignore, ignore union IgnoreSt); EndIf;

RESULT:

In this example, key sequence # H is defined to ignore characters. The Read command is used to assign characters typed on the keyboard to the string variable IgnoreSt.

RELATED TOPICS:

Keypad function. KeyIn command.

READFILE

The READFILE command reads a line from a file and assigns it to a string variable.

SYNTAX:

READFILE ( filehandle, string);

REMARKS:

The filehandle was created when the file was opened.

A line is read from the indicated file and assigned to the string variable. A line is a string of ASCII characters that ends with carriage return/line feed characters.

ERROR CONDITIONS:

The Screen Reader return code, (RC), is set to a number other than 0 if end of file (EOF) is encountered or if some other I/O error occurs. Refer to the Set command

(Trap argument) for the return code setting if this error occurs.

EXAMPLE:

const filename = 'instruct.doc'; var str : string; var fhandle : FileHandle;

proc SpeakFile is OpenFile( fhandle, filename); ReadFile( fhandle, str); While rc = 0 Do If Length( str) <> 0 Then Say( str); Endif; ReadFile( fhandle, str); Endwhile; If rc <> 0 Then Msg( 'end of file'); Endif;

RESULT:

In this example, a procedure is defined to read a file from the beginning to the end.

RELATED TOPICS:

BackupFile command. CloseFile command. OpenFile command. ResetFile command. WriteFile command.

RECALL

The RECALL command resets variables and Screen Reader/2 states to the values assigned to them when they were saved with a Store command.

SYNTAX:

RECALL;

REMARKS:

The Recall command reads a .STO file for the current program to reset variables and Screen Reader/2 settings to the values assigned when they were saved with a Store command. Screen Reader/2 will recall the stored settings and variables for the current program if all of the following conditions are true:

1. A .STO file exists for the current program. 2. The .STO file was saved using Screen Reader/2. 3. The current profile tier matches the profile tier in use when the Store occurred.

4. The time stamp for all profiles in the current profile tier matches the time stamp for the profiles in the tier when the Store occurred.

RELATED TOPICS:

Push command. Store command.

RESETFILE

The RESETFILE command repositions a file to its beginning.

SYNTAX:

RESETFILE ( filehandle);

REMARKS:

A filehandle is created when the file is opened.

RELATED TOPICS:

BackupFile command. CloseFile command. OpenFile command. ReadFile command. WriteFile command.

RESTORE

The RESTORE command sets the values of switches and states to the values saved earlier in the key definition.

SYNTAX:

RESTORE;

REMARKS:

A Restore command restores the values of switches and states saved by the last Save command only. You can nest a Restore command for each Save command (in reverse order). If you use a Restore command that does not have a corresponding Save command, the Restore command does nothing.

The Restore command is not usually needed because Screen Reader/2 includes an automatic restore at the end of any statement sequence.

EXAMPLE:

{*2} 'current field' Save( Wrap, Trap); Set( Wrap, On); Set( Trap, Off); Get( Field ); Say( Field ); Restore;

RESULT:

In this example, the key sequence * 2 is defined to read the current field. Once the reading has occurred, the Restore command is used to return the Screen Reader/2 states to their previously saved settings.

RELATED TOPICS:

Save command.

RETURN

The RETURN command is the last statement of a procedure if a value is returned to the procedure's caller.

SYNTAX:

RETURN expression;

REMARKS:

The type of the value returned must be declared in the Returning component of the procedure declaration. If there is no Returning component in the procedure declaration, then a Return command cannot be at the end of the procedure.

EXAMPLE:

var DefaultSelector : Integer; Proc WhichSelector returning integer is var num : integer;

If selectors >= DefaultSelector Then num := DefaultSelector; Elseif selectors > 0 Then num := 1; Else num := 0; Endif; Return num;

RESULT:

In this example, a procedure is defined to determine a selector number. The Return command is used to return the selector number to the caller.

RELATED TOPICS:

Proc declaration.

RUN

The RUN command starts another program.

SYNTAX:

RUN ( string [ ,True | False]);

REMARKS:

The string is the command that starts a program. If True is specified as the optional argument, Screen Reader/2 starts the program in a new session and regains its own control immediately. If the optional argument is False or omitted, Screen Reader/2 starts the program and waits for it to finish.

ERROR CONDITIONS:

If the command cannot be executed, you hear an appropriate error message. In addition, the Screen Reader/2 return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the RC setting if this error occurs.

EXAMPLE:

{(AB)} 'Compile a profile' var str : string; Save( Trap); Set( Trap, Off); Msg( 'Enter profile name.'); Read( str); If Length( str) = 0 Then Msg( 'compile profile cancelled'); Exit; EndIf; Stop; Run( 'pc c:\srd21\' + str + '.kpd c:\srd21\' + str + '.lst ' + str + '.kbj'); If RC <> 0 Then Msg( 'Could not compile profile'); Endif;

RESULT:

In this example, the chord A B is defined to compile a profile. The Run command is used to start the Screen Reader/2 compile program and wait for it to finish.

SAVE

The SAVE command saves the current value of Screen Reader/2 states, switches, and view information.

SYNTAX:

SAVE ( setting, setting, ... setting);

REMARKS:

A Restore command restores the values of switches and states saved by the last Save command only.

All saved values are automatically restored in Screen Reader/2 at the end of a statement sequence.

A single Save command can have multiple settings separated by commas.

Setting can be any of the following:

Blank. Bottom. Caps. Dictionary. ForceSpell. Format. Graphics. Icons. Ignore. Left. LockStatus. Mode. Noise. Numbering. Pause. Pitch. Pointer. Rate. RepeatCount. Right. Spaces. Stopping. SpellCaps. Table. Top. Trailing. Trap. TrapKeys. View. Viewport. Volume. WordDef. Wrap.

NOTE: You should not save the Icons setting in an autospeak because system performance will be slower due to the repeated access of the icon IDs file.

EXAMPLE:

{*2} 'current field' Save( Wrap, Trap); Set( Wrap, On); Set( Trap, Off); Get( Field); Say( Field);

RESULT:

In this example, key sequence * 2 is defined to say the current field. The state of Wrap and Trap are saved.

RELATED TOPICS:

Set command. Restore command.

SAY

The SAY command speaks data (lines, words, characters, strings, fields, or regions) from the screen.

SYNTAX:

SAY ( Line | Word | Sentence );

REMARKS:

The Say command is often preceded by a Get command that sets the local pointer. Say speaks the rest of the word, line, or sentence starting at the local pointer.

With Word as the argument, if the local pointer is on a character, the word spoken consists of the following consecutive characters and blanks. If the local pointer is on a blank, Screen Reader/2 considers the word all blanks up to the end of the line or the next character.

If the Wrap switch is on, Say( Line) speaks the rest of the screen beginning at the local pointer.

With Sentence as the argument, the sentence spoken consists of the following consecutive characters and up to two blanks preceded by double quotes ("), a single quote ('), a question mark (?), a period (.), or an exclamation point (!).

EXAMPLES:

{1} 'previous line' Get( row-1, 1); Say( Line);

{4} 'previous word' Get( Prevword); Say( Word);

RESULT:

In this example, key 1 is defined to read the previous line and key 4 to read the previous word.

SYNTAX:

SAY ( string);

REMARKS:

Say speaks a string of characters using the current Screen Reader/2 settings.

EXAMPLE:

{#H} 'start ignoring 1 or more characters' var IgnoreSt : string; Msg( ' enter characters to start ignoring'); Read( IgnoreSt); If RC = 0 Then -- null string entered Msg( ' cancelled '); Else Out( ' start ignoring '); Save( Format); Set( Format, Spell); Say( IgnoreSt); Set( Ignore, Ignore union IgnoreSt); EndIf;

RESULT:

In this example, the key sequence # H is defined to start ignoring characters. The Say command is used to spell the new characters to be ignored.

SYNTAX:

SAY ( expression);

REMARKS:

Say uses the current spelling table, usually the Default table, to look up the value of the expression and announce the result.

EXAMPLE:

{8} 'current character' Say( Char);

RESULT:

In this example, key 8 is defined to say the character at the position of the local pointer.

SYNTAX:

SAY ( Field [ , mask]);

REMARKS:

Say announces the current string of characters from the screen that have the same color and font attributes.

You can use the following mask expressions. These are listed in the file SRD2.INC:

FG The field is defined using only the foreground attributes.

BG The field is defined using only the background attributes.

MIX The field is defined using both foreground and background attributes.

FONTSTYLE The field definition includes changes in font style.

FONTNAME The field definition includes changes in font names.

FONTSIZE The field definition includes changes in font size.

ANYFONT The field definition includes any type of font change.

EXAMPLE:

var Field_Mask : integer; Initialize Field_Mask := Mix + AnyFont;

{*1} 'previous field' If View.Type <> PM Then Field_Mask := Field_Mask - AnyFont; EndIf; Save( Wrap, Trap); Set( Wrap, On); Set( Trap, Off); Get( PrevField, Field_Mask); If rc = 0 Then Say( Field, Field_Mask); Else Msg( ' first field'); EndIf;

RESULT:

In this example, key sequence * 1 is defined to speak the previous field. The previous field is defined using both foreground and background attributes. For a P M application, the field definition includes any font changes.

SYNTAX:

SAY ( row1, col1, row2, col2);

REMARKS:

Say announces the contents of the region delineated by the confines of the rows and columns specified.

EXAMPLE:

proc SayBlock is Set( Wrap, On); Set( Trap, Off); Get( View.Top+2, View.Left); Get( SameAttr, &H00, &Hf0, +); Stop; Say( View.Top+2, View.Left, View.Bottom, View.Right);

RESULT:

In this example, a procedure is defined to set up a block on the screen, then read the coordinates.

RELATED TOPICS:

Get command. Msg command. Out command.

SET

The SET command assigns a value to a specified setting of the Screen Reader/2 state. These settings are Booleans, integers, and strings.

SYNTAX:

SET ( setting, expression);

REMARKS:

All of the setting keywords used by the Set command can also be used as read-only variables.

The Boolean settings are:

BLANK. When set to On, blank windows, lines, and words are announced in Text format. The default is Off.

CAPS. When set to Off, all capital letters are converted to lowercase in spell and phonetic formats or when searching for a string. With Set (Caps, On), this translation does not take place. The default is Off.

DICTIONARY. When set to On, in Text or Pronounce format, alphabetic parts of words are looked up in the dictionary. If the words are found, the dictionary replacement is sent. Dictionaries are created and modified by using the Screen Reader/2 Message Settings Notebook. The default is On.

FORCESPELL. When set to On, any word without a vowel is spelled letter by letter. The default is On.

GRAPHICS. When set to Off, all graphic characters are converted to spaces. When set to On, graphic characters are recognized. Graphic characters are characters that form edges and corners of boxes on text screens. The default is Off.

ICONS. When set to Off, Screen Reader/2 ignores icons on the display. When set to On, the existence of an icon is represented by ASCII character 22 (declared as IconChar in SRD2.INC) in Screen Reader/2' model of the display. If IconChar is encountered, then you can use Char.IconID to get the icon ID. If the ID is listed in the SRD2.ICN file, then you can use Char.IconText to get the text associated with the specified icon ID. When Icons is set On but ASCII character 22 is ignored, then all icons will appear as spaces in Screen Reader/2' model of the display. The default is On.

LOCKSTATUS. When set to On, Screen Reader/2 announces the changes in the lock keys (Caps Lock, Num Lock, and Scroll Lock). The default is On.

NOISE. When set to On, the system will generate a static-like noise whenever P M is painting any part of the screen. This setting is useful so you can know when the display is not being updated.

NUMBERING. When set to On, line numbers are announced as the screen is read line by line. The default is Off.

ONESPACE. When set to On, a sentence end can be defined with a single space. Otherwise, two spaces are required. The default is Off.

PAUSE. When set to On, additional silence is provided between characters. The control code for the pause is synthesizer dependent and can be changed by using the

Screen Reader/2 Synthesizer Settings Notebook. The default is Off.

SPELLCAPS. When set to On, any word containing some alphabetic characters, all of which are uppercase, is spelled. The default is Off.

STOPPING. When set Off, the Stop command is ignored. This setting is useful when debugging profiles. The default is On.

TRAILING. When set to On and Spaces is set to more than 0, trailing spaces are announced using the Say command in Pronounce, Spell, and Phonetic formats. When set to Off, trailing spaces are ignored. The default is Off.

WRAP. When set to On, the entire viewport is treated as one line. The default is Off.

TRAP. When set to On, error messages that occur during the processing of PAL commands are announced and the statement sequence is ended. When Off, error announcements are suppressed and statement sequence processing continues after an error occurs. When the Trap switch is off, the return code (RC) is set and can be used by the PAL code. The default is On.

The error codes are:

0 No error. 101 Get SameAttr or DiffAttr failure. 102 Get PrevWord, PrevSentence, PrevField failure. 103 Get NextWord, NextSentence, NextField failure. 111 Set( Table, string) with incorrect table name. 112 Local pointer set to invalid value, like Get( x, y) with x less than top. 113 Local pointer set to invalid value, like Get( x, y) with y greater than bottom. 114 Local pointer set to invalid value, like Get( x, y) with x greater than right. 115 Local pointer set to invalid value, like Get( x, y) with y less than left. 117 A P M view is needed. 118 Could not find specified string in Get( string ... ). 119 Could not open file. 120 Could not set viewport. Some coordinate out of bounds. 121 Error while writing to file. 122 Screen row in P M is out of range. 123 DateTime option is not valid. 124 Filehandle is not valid.

125 String in KeyPad command is incorrect. 126 SwitchList command is unsuccessful. 127 Selector does not exist. 128 Division by zero attempted in an expression. 131 Array variable index outside of range. 134 Module reference does not exist. 135 String argument is empty. 136 Could not set view. 137 Tried to reference an undefined trigger. 138 Could not push the specified profile on the tier. 139 Could not pop a profile off the tier. 141 Bad string argument for KeyIn function. 142 Timeout for KeyPad function.

The integer settings are:

BOTTOM. The viewport bottom edge is set to the value of the expression.

If a viewport is set to FullView and the size of the current view changes, the size of the viewport changes with it. If the viewport is set to specified coordinates instead of FullView, the new viewport size never changes, even if the size of the view changes. To prevent this situation, use the command Save( ViewPort) to save the state of FullView before using the Set command to set the viewport bottom edge.

FORMAT. The format expression can be Text, Pronounce, Spell, Phonetic, or ASCII.

In Text format, Screen Reader/2 reads the words but not the punctuation. In Pronounce format, Screen Reader/2 reads the words and the punctuation. In Spell format, every word is spelled and punctuation is announced. In Phonetic format, every word is spelled using the Phonetic spelling table. In ASCII format, the ASCII value for the character requested is announced.  :lm margin=1.

LEFT. The viewport left edge is set to the value of the expression.

Refer to the previous description of Bottom for a hint on setting the viewport.

MODE. The mode expression is either cursor or pointer.

PITCH. The pitch of the synthesizer is set to the value of the expression.

The value must be within the range of 1 to the number of sequences defined in the specific synthesizer (.TTS) file. These control sequences can be reviewed, created, or modified using the Screen Reader/2 Synthesizer Settings Notebook.

NOTE: Nine pitch sequences are shipped with Screen Reader/2 for each supported synthesizer.

RATE. The rate of the synthesizer is set to the value of the expression.

Refer to the previous description of Pitch for an explanation of the control sequences in the .TTS file.

NOTE: Nine rate sequences are shipped with Screen Reader/2 for each supported synthesizer.

REPEATCOUNT. The RepeatCount is set to the value of the expression, which is the number of repeated characters that forces word spelling and the announcement of spaces.

RIGHT. The viewport right edge is set to the value of the expression.

Refer to the previous description of Bottom for a hint on setting the viewport.

SPACES. When set to an integer (n), in Pronounce, Spell, and Phonetic formats, n spaces between words are announced by Screen Reader/2. If, in addition, the Trailing switch is on, then n or more spaces at the end of lines are also announced. n specifies that Screen Reader/2 will announce n or more spaces. Fewer than n will not be announced. The default is 0.

SPECIAL. A special feature of the synthesizer is set to the value of an expression. The values must be within the range of 1 to 9, which correspond to special control sequences selected for the specific synthesizer. These control sequences can be reviewed, created, or modified by using the Screen Reader/2 Synthesizer Settings Notebook.

TOP. The viewport top edge is set to the value of the expression.

Refer to the previous description of Bottom for a hint on setting the viewport.

TRAPKEYS. TrapKeys is set to the array of keys to trap. This array must be of type intarray. Each element of the array is set to the character code of the key being trapped. The last entry in the array is zero. The pop-up keypad profile defined in KEYPAD.KPD is an example of the use of this setting.

VOLUME. The volume of the synthesizer is set to the value of the expression.

Refer to the previous description of Pitch for an explanation of the control sequences in the .TTS file.

NOTE: Nine volume sequences are shipped with Screen Reader/2 for each supported synthesizer.

The string settings are:

DEVICE. The Device argument enables Screen Reader/2 to support more than one serial device, such as a braille display along with one or two serial synthesizers. For example, if two different synthesizers are connected to two different serial ports and Screen Reader/2 is started using a command such as:

Start Srd /s pss.tts /s portadec.tts os2core

Screen Reader/2 sends output to the Votrax synthesizer after the following PAL command:

Set( Device, 'pss');

Screen Reader/2 sends output to the Portable Dectalk synthesizer after this Set command:

Set( Device, 'portadec');

IGNORE. With Set ( Ignore, string), all characters in the string are converted to blanks when they are encountered by the Say command. If the string is ' ', a space between two single quotes, Screen Reader/2 resets so that no characters are ignored.

TABLE. The expression for the Table argument must be the name of a spelling table. Set ( Table, string) sets the current spelling table to the one named in the string. The table names are Color, Default, Extended Keys, Phonetic, and Standard Keys. You can access these tables by using the Screen Reader/2 Message Settings Notebook.

WORDDEF. In Screen Reader/2, a word is defined as a nonblank string followed by trailing blanks. Whenever Screen Reader/2 speaks words, lines, or the screen, it speaks one word at a time. Set ( WordDef, string) enables this definition of a word to be changed. The strings that can be used to redefine a word in Screen Reader/2 are:

Alphabetic. NonBlank. Numeric. Punctuation. Symbol. Space. User-defined string.

By using the operators Union and Intersect, strings can be combined to create new definitions of a word in Screen Reader/2. For example, Set ( WordDef, Alphabetic Union Numeric) is convenient for reading files such as CONFIG.SYS and some programming languages.

EXAMPLES:

Examples of the Set command can be found in the example section of the following functions, statements, and commands:

Char.Color function. KeyVal function. Cycle statement. Initialize statement. While statement. Find command. Get command. Msg command. Read command. Say command.

RELATED TOPICS:

Char function. Autospeak statement. Initialize statement. Save command. WordScan command.

SETICONTEXT

The SETICONTEXT command associates a text string with an icon ID.

SYNTAX:

SETICONTEXT ( ID, string);

REMARKS:

The icon IDs and their associated text strings are saved in the file SRD2.ICN in the SRD21 directory.

EXAMPLE:

{D2} 'Associate a text string with the current icon' var str : string; var id : integer;

If Char.IconID = 0 Then Msg( ' Invalid icon'); Else id := Char.IconID; Msg( 'Enter text to associate with this icon. '); Read( str); If Length( str) > 0 Then SetIconText( id, str); Else Msg( 'Canceled'); Endif; Endif;

RESULT:

In this example, the key sequence D 2 uses the SetIconText command to associate text with the current icon.

RELATED TOPICS:

Char function. Autospeak statement. Set command.

SLEEP

The SLEEP command pauses Screen Reader/2 during the processing of a statement sequence to allow another program to process.

SYNTAX:

SLEEP ( expression);

REMARKS:

When the Sleep command is processed, all Screen Reader/2 command processing is suspended for a length of time (which is the value of the expression in milliseconds).

EXAMPLE:

var MainView : viewhandle;

Initialize Sleep( 3);

MainView := View;

RESULT:

In this example, the Initialize statement causes Screen Reader/2 to stop processing for 3 milliseconds in order for the main window to be displayed before the viewhandle is retrieved for the new current view.

STOP

The STOP command halts speech.

SYNTAX:

STOP;

REMARKS:

The Stop command sends the stop speaking control sequence to the synthesizer. This control sequence is synthesizer dependent and can be set by using the Screen Reader/2 Synthesizer Settings Notebook.

Stop will, on most synthesizers, stop speech immediately.

If you are in pointer mode and your synthesizer has indexing, the pointer moves to the beginning of the last word that was read completely before the speech stopped.

EXAMPLE:

For examples of the use of the Stop command, refer to the examples for the following:

Exists function. Run command.

STORE

The STORE command creates a .STO file and saves the values of variables and Screen Reader/2 settings for the current profile tier.

SYNTAX:

STORE;

REMARKS:

The Store command saves all Screen Reader/2 settings that you can set by using the Set command, the variables prow and pcol, and the values of all variables for all profiles in the current profile tier.

The file created when the Store command is used has a file name based on the current program name and has the extension .STO. Profiles must be in the directory specified by the SRDPROFILES environment variable.

If a new session is started or if a new profile is pushed onto the profile tier, Screen Reader/2 recalls the stored settings and variables if all of the following conditions are true:

1. A .STO file exists for the current program. 2. The .STO file was saved using Screen Reader/2. 3. The current profile tier matches the profile tier in use when the Store occurred. 4. The time stamp for all profiles in the current profile tier matches the time stamp for the profiles in the tier when the Store occurred. 5. No .STO file has been recalled in this session.

RELATED TOPICS:

Push command. Recall command.

SWITCHLIST

The SWITCHLIST command requests OS/2 to switch focus to a new task.

SYNTAX:

SWITCHLIST ( string);

REMARKS:

SwitchList requests OS/2 to switch focus to the task identified by the string argument, which contains Window List entry information. To obtain this information for the current task, use the SwitchList function.

ERROR CONDITIONS:

If the named task cannot be found in the Window List, you hear an error message and the return code, (RC), is set to a number other than 0. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

type Str1 = string[20];

static Task_List : array[0..10] of str1;

{(12)2} 'Go to numbered task entry' var num : integer;

num := KeyVal(); SwitchList( Task_List[num] );

RESULT:

In this example, the chord 1 2 then 2 is defined to switch to an entry in the Window List that has been given a number by the user.

RELATED TOPICS:

SwitchList function. FrameList command.

VIEW

The VIEW command specifies where Screen Reader/2 accesses screen data.

SYNTAX:

VIEW ( Focus);

VIEW ( Desktop);

VIEW ( viewhandle);

REMARKS:

View ( Focus) causes Screen Reader/2 to follow the focus.

View ( Desktop) tells Screen Reader/2 to access screen data from the OS/2 Desktop.

If the Screen Reader/2 view is set to the viewhandle for a particular view, when the focus changes, the current Screen Reader/2 view does not change.

Some read-only viewhandle variables are already defined (for example, View and FocusView). Functions such as View.Parent, ViewFromPoint, and ViewFromRowCol return viewhandles. Events such as EventCursorChange, EventSelectorChange, and EventViewChange return a viewhandle in the local read-only variable trigger.

EXAMPLE:

/* speak the window containing row r */ Proc Speak( num : integer) is View( ViewFromRowCol( num, 1) ); Get( 1, 1); Save( Pointer, Wrap); Set( Wrap, On); Say( Line); View( Focus); Set( Wrap, Off);

RESULT:

In this example, a procedure is defined to speak the window containing num. The View command is used to specify where on the screen to look for the window.

RELATED TOPICS:

View function. ViewPort function. Save command. ViewPort command.

VIEWPORT

The VIEWPORT command sets reading boundaries for Screen Reader/2 within the current Screen Reader/2 view.

SYNTAX:

VIEWPORT ( FullView);

VIEWPORT ( c1, c2, c3, c4);

REMARKS:

If you use ViewPort ( FullView), the Screen Reader/2 viewport is set to the current Screen Reader/2 view.

If you use ViewPort( c1, c2, c3, c4), the Screen Reader/2 viewport is set for reading within the specified boundaries. The arguments c1, c2, c3, and c4 represent coordinates for defining the viewport relative to the current view. For text screens, these coordinates are specified in the order of top, left, bottom, and right as rows and columns relative to the current view. For a P M view, these coordinates are specified in the order bottom, left, top, and right pixel coordinates relative to the current view.

If a viewport is set to FullView and the size of the current view changes, the size of the viewport changes with it. If the viewport is set to specified coordinates instead of FullView, the new viewport size never changes even if the size of the view changes. To prevent this situation, use the command Save( ViewPort) to save the state of FullView before using the ViewPort command to set specified coordinates.

EXAMPLE:

var BoxTop, BoxLeft, BoxBottom, BoxRight : Integer;

{CS} 'toggle view' If (( ViewPort.Top <> 1) Or ( ViewPort.Right <> ViewPort.Cols)) Then ViewPort( FullView); Msg( 'full view'); ElseIf BoxTop <> 0 Then Out( 'view set to box at: '); ViewPort( BoxTop, BoxLeft, BoxBottom, BoxRight); Msg( 'top ', Viewport.Top, ' left ', Viewport.Left, ' bottom ', Viewport.Bottom, ' right ', Viewport.Right); Else Msg( 'no box'); EndIf;

RESULT:

In this example, a procedure called by an autospeak is defined to toggle the view between the full view and a box view. The ViewPort command is used to set the view first to full view and then to the coordinates of a box.

RELATED TOPICS:

View function. ViewPort function. Save command. View command.

WORDSCAN

The WORDSCAN command sets up Screen Reader/2 to scan for characteristics of text as it is spoken from the display.

SYNTAX:

WORDSCAN ( autohandle, expression);

REMARKS:

This command announces text changes in capitalization, color, font, and style. The advantage is that the changes in text characteristics can be announced as the text is read instead of having a key sequence to get that information.

As each word from the display is processed, its characteristics are analyzed. If the characteristics change, the WordScan event occurs and the changed characteristic is returned in the variable trigger.

The autohandle is a variable that identifies an autospeak.

The characteristics WordScan can monitor and announce are listed below. The bit settings for the expression are described. These settings are defined in in the file SRD2.INC.

BIT 0 LowerCase (No capital letters). BIT 1 UpperCase (All capital letters). BIT 2 MixedCase (At least one capital beyond the first). BIT 3 InitialUpper (First letter is capital, but no other). BIT 4 HasVowel (Has a vowel). BIT 5 AllBlanks (All blanks). BIT 6 AllNumeric (All numeric). BIT 7 ColorChange (Color is different from previous word spoken). BIT 8 ColorMix (Color changes in word). BIT 9 FontChange (Font is different from previous word spoken). BIT 10 StyleChange (Style is different from previous word spoken). BIT 11 TrapWord (Current word is not spoken). BIT 12 SizeChange (Font size is different from previous word spoken). BIT 13 FontMix (Font changes in word). BIT 14 (Reserved). BIT 15 PostScan.

Bit 15 is 0 if the word triggering the event has not yet been sent to the output device. Bit 15 is 1 if the word has already been sent to the output device.

EXAMPLE:

var Scanner : autohandle;

Initialize WordScan( Scanner, UPPERCASE );

AutoSpeak Scanner Watch WordScan Do If trigger BitAnd UPPERCASE then Msg( 'cap cap'); Endif;

RESULT:

In this example, the Initialize statement turns on WordScan for uppercase words. The autospeak than

announces 'cap cap' before any word which consists of all capital letters.

RELATED TOPICS:

Autospeak statement.

WRITEFILE

The WRITEFILE command writes a line to a file.

SYNTAX:

WRITEFILE ( filehandle, string);

REMARKS:

The filehandle was created when the file was opened. A line is written to the file identified by the specified filehandle. The line written is the specified string of ASCII characters followed by carriage return/line feed characters.

NOTE: If a file already exists, the WriteFile command writes over the existing contents of the file without first erasing it. To replace an existing file with predictable results, you should erase the file before using the WriteFile command. Use the PAL Run command and the DOS Erase command to erase a file. You cannot use the WriteFile command to add text to the end of an existing file.

ERROR CONDITIONS:

The Screen Reader/2 return code, (RC), is set to a number other than 0 if the file was opened with read-only access or if some other I/O error occurs. Refer to the Set command (Trap argument) for the return code setting if this error occurs.

EXAMPLE:

const filename = 'instruct.doc'; var str : string; var fhandle : FileHandle;

Proc WriteToFile is str := "Screen Reader/2"; OpenFile( fhandle, filename, True); WriteFile( fhandle, str); If rc <> 0 Then Msg( 'Error writing to file'); Endif; CloseFile( fhandle);

RESULT:

In this example, a procedure is defined to write the words "Screen Reader/2" to the instruct.doc file. If problems occur, the procedure tells the user and ends the process.

RELATED TOPICS:

BackupFile command. CloseFile command. OpenFile command. ReadFile command. ResetFile command.

COMPILER DIRECTIVES

The two statements discussed in this section are compiler directives:

1. Include. 2. TryInclude.

The conventions used to display the syntax of the compiler directives are described in the section Syntax.

INCLUDE

The INCLUDE statement simplifies the structuring and modifying of keypad profiles because it allows profiles or fragments of profiles to be included in other profiles.

SYNTAX:

INCLUDE string

REMARKS:

The string is the file name (with drive and path optional) and extension for the profile to be included. Do not forget the single quotes around the string.

Include statements can be placed wherever comments are allowed.

All Initialize statements in included profiles are processed when the profile is loaded.

The ASCII values for some constants such as Screen Reader/2 formats and modes, view types, view classes, WordScan text characteristics, and P M window and control styles are defined in the include file SRD2.INC in the SRD21 directory. This profile can be included by any application profile you write.

EXAMPLE:

include 'srd2.inc'

RESULT:

The file SRD2.INC is included in the current profile.

TRYINCLUDE

The TRYINCLUDE statement attempts to include a specified profile in another profile. If it fails no error message is generated.

SYNTAX:

TRYINCLUDE string

REMARKS:

The TryInclude statement is similar to the Include statement except that, if the profile does not exist, there is no error message.

In SRD2.KPD, the base profile, there are two TryInclude statements:

TryInclude MYINIT.KPD
TryInclude MYSRD2.KPD

The way you might use these is either:

1. To automatically start profiles that you have written when the corresponding application starts:

a. Create a MYINIT.KPD profile that contains the appropriate Initialize statements. b. Recompile the SRD2.KPD profile. c. Restart Screen Reader/2.

2. To include new autospeaks and key sequences in the base profile tier:

a. Create a MYSRD2.KPD profile that contains these autospeaks and key sequences. b. Recompile the SRD2.KPD profile. c. Restart Screen Reader/2.

COMPILER

You must compile a new or modified profile for it to work. For this step, use the compiler program.

To start the compiler, type the following command and press Enter:

PAL profilename [ listfilename objectfilename]

Profilename is the file name of the source profile.

If a listfilename is not specified, a list file is created with the same file name as the source profile and has the extension .LST.

If an objectfilename is not specified, an object file is created with the same file name as the source profile and has the extension .KBJ.

The compiler creates a list file only if errors occur. Use a text editor to view or edit the list file. Errors are listed in the following manner:

  1. The erroneous line appears in the list file.
  2. The error message appears beneath the erroneous line.
  3. A caret (&caret.) points to the column where the error was detected.

NOTE: Usually, this is the error location, but sometimes an earlier error causes the compiler to list errors incorrectly.

To get more information about the cause of an error and how to correct it, enter the following command:

HELP palxxxx

palxxxx is the error number preceding an error message.

To send the list file to the display instead of to a file, enter the following:

PAL profilename CON objectfilename

SUMMARY OF PAL RESERVED WORDS

The following are PAL reserved words:

NOTE: Reserved words followed by an asterisk are not currently used in PAL statements but should not be used for declaring variables or procedures. Use of any reserved words in declarations may cause a compiler error.

After *.

All *.
AllBlanks *. AllNumeric *. Alphabetic.
And. Array. Asc.
Ascii. Auto. AutoDelay.
Autohandle. Autospeak.
BackupFile. Beep. BitAnd.
BitEq. BitNot. BitOr.
BitXor. Blank. Boolean.
Bottom. Button1. Button2.
By.
Caps. Case. Ccol.
Char. Char.Bottom. Char.Color.
Char.Font. Char.IconID. Char.IconText.
Char.Left. Char.Pitch. Char.Right.
Char.Style. Char.Top. Chr.
CloseFile. Col. ColorChange *.
ColorMix *. Colour *. Const.
Continue. Crow. Cursor *.
Cycle.
DateTime. Desktop. Device.
Dictionary. DiffAttr. Digits.
Display. Div. Do.
DosEcho *.
Else. ElseIf. EndFor.
EndIf. EndWhile. EOF.
EventCursorChange. EventDeviceIn. EventExternal.
EventIndexIn. EventKeyPressed. EventMouseMove.
EventPointerChange. EventProcessChange. EventSelectorChange.
EventShiftChange. EventScroll *. EventSpinButton.
EventViewChange. Exists. Exit.
Extern.
False. Field. FileHandle.
Find. Focus. FocusView.
For. ForceSpell. Format.
FrameList. FullView.
Get. Graphics.
HasVowel *. Help.
Icons. IconScan. If.
Ignore. Include. Initialize.
InitialUpper *. Int. Intarray.
Integer. Intersect. Is.
KeyDelay *. KeyEcho. Keyin.
KeyPad. KeyVal.
Left. Length. Line.
Load. LockStatus. LockWord.
Lower. LowerCase *.
Macro *. Map. MaxPitch.
MaxRate. MaxSpecial. MaxVolume.
MixedCase *. Mod. Mode.
ModuleName. Mouse. Mouse.Col.
Mouse.Row. Mouse.View. Mouse.X.
Mouse.Y. Msg.
NextField. NextSentence. NextTime.
NextWord. Noise. NonBlank.
Not. Numbering. Numeric.
Of. Off. On.
OneSpace. OpenFile. Or.
Out.
Pause. Pitch. Pcol.
Phonetic. Pmfun *. Pointer *.
Pop. Pos. PostScan.
PrevField. PrevSentence. PrevWord.
Proc. ProfDir. Program.
Pronounce. Prow. Punctuation.
Push.
Rate. RC. Read.
ReadFile. Recall. RepeatCount.
ResetFile. Restore. Return.
Returning. Right. Row.
RowCol. Run.
SameAttr. Save. Say.
ScanOutput. Selectors. Selector.
Selector.Bottom. Selector.Col. Selector.Left.
Selector.Right. Selector.Row. Selector.Style.
Selector.Top. Sentence. Set.
SetIconText. Sleep. Space.
Spaces. Special. Spell.
SpellCaps. Static. Status.
Stop. Stopping. Store.
String. StyleChange. Substring.
SwitchList. Symbol.
Table. Text. TTYEcho *.
Then. Title. To.
Top. Trailing. Trap.
TrapKeys. TrapWord. Trigger.
True. TryInclude. Type.
Union. Upper. UpperCase.
Var. View. View.Bottom.
View.Class. View.Cols. View.FirstChild.
View.ID. View.Left. View.NextAVIO.
View.NextSibling. View.Parent. View.Right.
View.Rows. View.Style. View.Top.
View.Type. ViewFromPoint. ViewFromRowCol.
Viewhandle. ViewPort. ViewPort.Bottom.
ViewPort.Cols. ViewPort.Left. ViewPort.Right.
ViewPort.Rows. ViewPort.Top. Volume.
Watch. While. Word.
WordDef. WordScan. Wrap.
WriteFile.
Xor.

GLOSSARY

A

ASCII. Acronym standing for American National Standard Code for Information Interchange. The standard code, using a coded character set consisting of seven-bit coded characters (eight bits including parity check), used for information interchange among data processing systems, data communication systems, and associated equipment. The ASCII set consists of control characters and graphic characters.

NOTE: IBM has defined an extension to the ASCII code (characters 128-255).

ARGUMENT. (1) An independent variable. (2) Any value of an independent variable, for example, a search key; a number identifying the location of an item in a table.

ARRAY. (1) An arrangement of data in one or more dimensions: a list, a table, or a multidimensional arrangement of items. (2) In programming languages, an aggregate that consists of data objects, with identical attributes, each of which may be uniquely referenced by subscripting.

ARRAY VARIABLE. A name used to represent one of the data items in an array, whose value can change while the profile is running.

ATTRIBUTE. Used here as a display attribute, a number that determines the color of a character on the display.

AUTOSPEAK. A unique feature of Screen Reader/2 and the Profile Access Language, an autospeak monitors values or areas of the screen for change and then announces the change.

AVIO. Advanced Video Input/Output. For P M, a text window in the graphics environment.

B

BIT-WISE OPERATIONS. The bit-wise operations take integer arguments and operate on each bit, returning integer results.

BUTTON. (1) A mechanism on a pointing device, such as a mouse, used to request or initiate an action. (2) A control window, such as a pushbutton, radio button, or check box.

C

CHECK BOX. A control window, shaped like a square button on the screen, that can be in a checked or unchecked state. It is used to select one or more items from a list. Contrast with radio button.

CHILD WINDOW. A window that is positioned relative to another window (either a main window or another child window). Contrast with parent window.

CHORD. A key sequence that consists of two keypad keys that are pressed at the same time and can be combined with other key presses. An example of a key sequence that includes a chord is CHORD 1 2 THEN B.

CLASS. Types of standard and user-defined P M controls. Classes include frames, combination boxes, spin buttons, entry fields, menus, static text, scroll bars, notebooks, containers, buttons, list boxes, title bars, containers, and multiple line entry fields. Class names can be found in the file SRD2.INC in the SRD21 directory.

COMMAND SEQUENCE. One or more PAL commands working together in one key definition.

CONTROL WINDOW. A class of window used to handle a specific kind of user interaction. Radio buttons and check boxes are examples.

CURSOR. A symbol displayed on the screen and associated with an input device. The cursor indicates where input from the device will be placed. Types of cursors include text, cursors, graphics cursors, and selection cursors. Contrast with pointer and focus.

D

DEFAULT VALUE. A value used when no value is explicitly specified by the user. For example, the default value for the Caps setting is Off.

DESKTOP. (1) In P M, a window that displays a list of groups of programs, each of which can be started or stopped. (2) The window, corresponding to the physical device, against which all other types of windows are established.

DICTIONARY. A list of words and replacement strings. Screen Reader/2 uses the dictionary to know what to send to the synthesizer for different text words.

E

EVENT. In autospeaks, Screen Reader/2 can watch for an event to occur. Events include cursor changes, index markers received, key presses, mouse movements, selector changes, spin button changes, view changes, and several other types of system and screen changes.

EXPRESSION. In PAL, expressions are built up from constants, variables, and read-only variables, and combined together with functions and operations to give a value.

F

FIELD. In Screen Reader/2, a contiguous area of the display with the same attribute or color. It can be one character, several characters, a line, several lines, or an entire screen.

FLAG. An indicator or argument for a command or function that shows the setting of a switch.

FOCUS. In OS/2, the focus is the area of the screen that will receive input from an input device (typically the keyboard).

FONT. A particular size and style of typeface that contains definitions of character sets, marker sets, and pattern sets.

FORMAT. In Screen Reader/2, any one of five methods of reading information on the screen. These methods are text, pronounce, spell, phonetic, and ASCII.

FRAME. The part of a window that can contain several different visual elements specified by the application, but drawn and controlled by P M. The frame encloses the area in the center of a window that contains the main information of the window.

FULL-SCREEN APPLICATION. An application program that occupies the whole screen.

G

GRAPHIC CHARACTER. In Screen Reader/2, a set of characters with ASCII values from 176 to 223 that are "box" characters - corners, vertical and horizontal lines, tees, crosses, and full rectangles.

H

HANDLE. An identifier that represents an object, such as a file, an autospeak, or a Screen Reader/2 view, to PAL.

I

ICON. A pictorial representation of an item the user can select. Icons can represent items (such as a document file) that the user wants to work on, and actions that the user wants to perform. In P M, icons are used for data objects, system actions, and minimized programs.

INDEXING. The capability of some synthesizers to send markers back through the asynchronous communications channel after each word is spoken. This capability allows the Screen Reader/2 pointer to move to the beginning of each word as it is spoken.

K

KEYPAD. A rectangular piece of equipment with 18 keys that directs Screen Reader/2 to speak text from the screen.

L

LIST BOX. A control window containing a vertical list of selectable descriptions.

LOCAL POINTER. A temporary screen pointer used during the execution of a PAL command sequence. Refer to cursor and pointer.

M

MAP. (1) A set of values having a defined correspondence with the quantities or values of another set. (2) To establish a set of values having a defined correspondence with the quantities or values of another set.

P

PAL. Profile Access Language. A computer language that enables you to create or modify profiles for use with Screen Reader/2.

PARENT WINDOW. The window relative to which one or more child windows are positioned. Contrast with child window.

PHONETIC ALPHABET. An alphabet that represents each character by a word beginning with the same letter. The phonetic alphabet is: Alpha, Bravo, Charlie, Delta, Echo, Fox trot, Golf, Hotel, India, Juliet, Kiio, Lima, Mike, November, Oscar, Papa, Quebec, Romeo, Sierra, Tango, Uniform, Victor, Whiskey, X ray, Yankee, Zulu.

PITCH. The Set command argument that adjusts the frequency; that is, the high or low tone of the synthesizer's voice.

PIXEL. The smallest area of a display screen capable of being addressed and switched between visible and invisible states.

POINTER. (1) A Screen Reader/2-unique marking device that is invisible on the screen and moves along as speech commences. It provides a way to move around the screen that is not dependent on cursor movement, thereby allowing full access to the screen. (2) The symbol displayed on the screen that is moved by a pointing device, such as a mouse. The pointer is used to point at items that users can select. Contrast with cursor.

POP. To retrieve an item from a last-in-first-out stack of items, such as profiles. Contrast with push.

POP-UP WINDOW. A window that appears on top of another window in a dialog. Each pop-up window must be completed before returning to the underlying window.

PRESENTATION MANAGER (P M). The visual component of O S/2 that presents, in windows, a graphics-based interface to applications and files installed and running in O S/2.

PROFILE. An ASCII text file used to control the key definitions and autospeaks for Screen Reader/2. Processing of a profile includes creating, compiling, and loading.

PROFILE TIER. A stack of profiles. The profile tier can change depending on which program or process is running in the foreground.

PUSH. To add an item to a last-in-first-out stack of items, such as profiles. Contrast with pop.

PUSHBUTTON. A control window, shaped like a round-cornered rectangle and containing text, that invokes an immediate action, such as 'enter' or 'cancel'.

R

RADIO BUTTON. A control window, shaped like a round button on the screen, that can be in a checked or unchecked state. It is used to select a single item from a list. Contrast with check box.

RATE. The speed at which your speech synthesizer speaks.

RETURN CODE. (1) A code used to influence the execution of succeeding instructions. (2) A value returned by a PAL command or procedure to indicate the results of an operation performed by that command or procedure.

S

SCREEN READER/2 FORMATS. Five methods of reading information from the screen:

TEXT. Reads words without speaking punctuation or announcing blank lines. PRONOUNCE. Reads words, speaks punctuation, and announces blank lines. SPELL. Spells words, speaks punctuation, and announces blank lines.

PHONETIC. Represents each letter of a word with a word of the same first letter, speaks punctuation, and announces blank lines. ASCII. Announces the ASCII value for the character requested.

SCROLL BAR. A control window, horizontally or vertically aligned, that allows the user to scroll additional data into an associated panel area.

SELECTOR. A type of cursor used to indicate the choice or entry field with which a user wants to interact. It is represented by highlighting the item on which it is currently positioned.

SIBLING WINDOWS. Child windows that have the same parent window.

SLIDER. An area on the scroll bar that indicates the size and position of the visible information in a panel area in relation to the information available. Also known as thumb mark.

STATIC TEXT Text associated with an OS/2 P M control or group of controls that describes what the control does.

STRING VARIABLE. A string variable is any sequence of characters on a single line surrounded by single quotes.

STYLE. In OS/2 P M, the characteristics of a window or control. For example, some of the styles for a window include minimized, maximized, and visible.

SWITCH. An action that moves input focus from one area to another. This can be within the same window or from one window to another.

T

TEXT WINDOW. Also known as the VIO window.

TIER. See profile tier.

TITLE BAR. The area at the top of a window that contains the window title. The title bar is highlighted when that window has the input focus.

V

VARIABLE. In the PAL, a name used to represent a data item whose value can be changed while the profile is running. Refer to array variable and string variable.

VOLUME. The loudness with which your speech synthesizer speaks.

VIEW. In OS/2 P M, a Screen Reader/2 view is a P M window or a text window. In full screen, the Screen Reader/2 view is the screen. In P M, the coordinates of a view are relative to the OS/2 Desktop.

VIEWPORT. A rectangular portion of a Screen Reader/2 view. A viewport's coordinates are relative to the current view.

VIO. Video Input/Output.

VOLUME. The loudness with which your speech synthesizer speaks.

W

WINDOW. A rectangular area of the screen with visible boundaries within which information is displayed. A window can be smaller than or the same size as the screen. Windows can appear to overlap on the screen.

WINDOW LIST. In P M, the list of programs that are active. The list can be used to switch to a program and to stop programs.