Document revision date: 19 July 1999

Using CURRENT_LINE may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_LINE causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

Examples

The following example stores in the variable my_cur_lin the string that represents the current line. The current line is the line in the current buffer that contains the editing point.

my_cur_lin := CURRENT_LINE 
      

The following example returns true if the current line has the format of a DSR command (starts with a period followed by an alphabetic character, a semicolon, or an exclamation point). If not, the procedure returns false. The procedure assumes that the cursor was at the beginning of the line and moves it back to the beginning of the line when done.

PROCEDURE user_runoff_line 
 
IF LENGTH (CURRENT_LINE) < 2 
THEN 
   user_runoff_line := 0; 
ELSE 
   IF CURRENT_CHARACTER <> "." 
   THEN 
      user_runoff_line := 0; 
   ELSE 
      MOVE_HORIZONTAL (1); 
      IF INDEX 
         ("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!;", 
         CURRENT_CHARACTER) = 0 
      THEN 
         user_runoff_line := 0; 
      ELSE 
         user_runoff_line := 1; 
      ENDIF; 
      MOVE_HORIZONTAL (-1); 
   ENDIF; 
ENDIF; 
ENDPROCEDURE; 
      

Format

integer := CURRENT_OFFSET

Parameters

None.

Return Value

Description

The CURRENT_OFFSET procedure returns an integer for the offset of the editing point within the current line. The current offset is the number of positions a character is located from the first character position in the current line (offset 0). In DECTPU, the leftmost character position is offset 0, and this offset is increased by 1 for each character position (including the tab character) to the right. DECTPU numbers columns starting with the leftmost position on the screen where a character could be placed, regardless of where the margin is. This leftmost position is numbered 1.

Note The current offset value is not the same as the position of the cursor on the screen. See the CURRENT_COLUMN built-in procedure if you want to determine where the cursor is. For example, if you have a line with a left margin of 10 and if the cursor is on the first character in that line, then CURRENT_OFFSET returns 0 while CURRENT_COLUMN returns 10.

Using CURRENT_OFFSET may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_OFFSET causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

If you are using an interface with free cursor motion, when you move beyond the end of a line CURRENT_OFFSET makes the current cursor position the new end-of-line.

If the current offset equals the length of the current line, you are positioned at the end of the line.

Signaled Errors

Examples

The following example stores the integer that is the offset position of the current character in the variable my_cur_off:

my_cur_off := CURRENT_OFFSET 
      

The following example uses the CURRENT_OFFSET built-in procedure to determine whether the editing position is at the beginning of a line. If the position is at the beginning, the procedure appends the current line to the previous line; otherwise, it deletes the previous character. Compare this procedure with the procedure used as an example for the APPEND_LINE built-in procedure.

PROCEDURE user_delete 
 
   IF CURRENT_OFFSET = 0 
   THEN 
       APPEND_LINE; 
   ELSE 
       ERASE_CHARACTER (-1); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

integer := CURRENT_ROW

Parameters

None.

Return Value

Description

The CURRENT_ROW procedure returns an integer that is the screen line on which the cursor is located. The screen lines are numbered from 1 at the top of the screen to the maximum number of lines available on the terminal. You can get the value of the current row by using the GET_INFO (SCREEN, "current_row") built-in procedure.

When used in a procedure, CURRENT_ROW does not necessarily return the position where the cursor has been placed by other statements in the procedure. The value returned by CURRENT_ROW may not be the current value because DECTPU generally does not update the screen until all statements in a procedure are executed. If you want the cursor position to reflect the actual editing location, put an UPDATE statement in your procedure immediately before any statements containing CURRENT_ROW, as follows:

UPDATE (CURRENT_WINDOW);

Signaled Errors

Examples

The following example causes the cursor to move up the screen:

PROCEDURE user_go_up 
   IF CURRENT_ROW = GET_INFO (CURRENT_WINDOW, "visible_top") 
   THEN 
       SCROLL (CURRENT_WINDOW, -1); 
   ELSE 
         CURSOR_VERTICAL (-1); 
   ENDIF; 
ENDPROCEDURE; 
      

The following example causes the cursor to move down the screen. Because CURSOR_VERTICAL crosses window boundaries, you must use the SCROLL built-in procedure to keep the cursor motion within a single window if you are using free cursor motion. See CURSOR_HORIZONTAL and CURSOR_VERTICAL for more information.

If the movement of the cursor would take it outside the window, the preceding procedures scroll text into the window to keep the cursor visible. You can bind these procedures to a key so that the cursor motion can be accomplished with a single keystroke.

PROCEDURE user_go_down 
   IF CURRENT_ROW = GET_INFO (CURRENT_WINDOW, "visible_bottom") 
   THEN 
       SCROLL (CURRENT_WINDOW, 1); 
   ELSE 
         CURSOR_VERTICAL (1); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

window := CURRENT_WINDOW

Parameters

None.

Return Value

Description

The CURRENT_WINDOW procedure returns the window in which the cursor is visible. The current window is the window on which you have most recently performed one of the following operations:

• Selection by using the POSITION built-in
• Mapping to the screen by using the MAP built-in
• Adjustment by using the ADJUST_WINDOW built-in

The current window contains the cursor at the screen coordinates current_row and current_column. The current buffer is not necessarily associated with the current window.

Signaled Errors

Examples

The following example stores the window that holds the cursor in the variable my_cur_win:

my_cur_win := CURRENT_WINDOW 
 

 
 
      

The following example determines the length of the current window and then uses that value as a parameter for the SCROLL built-in procedure.

PROCEDURE user_next_screen 
 
   LOCAL how_much_scroll; 
 
   how_much_scroll := GET_INFO (CURRENT_WINDOW, "visible_length"); 
   
   SCROLL (CURRENT_WINDOW, how_much_scroll); 
ENDPROCEDURE; 
      

Format

[[ integer2 :=]] CURSOR_HORIZONTAL (integer1)

Parameter

integer1

The signed plus or minus integer value that specifies the number of screen columns to move the cursor position. A positive value directs DECTPU to move the cursor to the right; a negative value directs DECTPU to move the cursor to the left. The value 0 causes DECTPU to synchronize the active editing point with the cursor position.

Return Value

Description

The CURSOR_HORIZONTAL procedure moves the cursor position across the screen and optionally returns the cursor movement status. You can use CURSOR_HORIZONTAL to provide free cursor movement in a horizontal direction. Free cursor movement means that the cursor is not tied to text, but can move across all available columns in a screen line.

If you move before the beginning of a line, after the end of a line, in the middle of a tab, or beyond the end-of-file mark, other built-ins may cause padding lines or spaces to be added to the buffer.

If you use the CURSOR_HORIZONTAL built-in within a procedure, screen updating occurs in the following manner:

• When you execute a built-in that modifies the buffer or the editing point before you issue the call to CURSOR_HORIZONTAL, the screen is updated before CURSOR_HORIZONTAL is executed. This action ensures that the horizontal movement of the cursor starts at the correct character position. Otherwise, the screen manager does not update the screen until the procedure has finished executing and control is returned to the screen manager.
• CURSOR_HORIZONTAL does not move the cursor beyond the left or right edge of the window in which it is located. You cannot move the cursor outside the bounds of a window.
• CURSOR_HORIZONTAL has no effect if you use any input device other than a video terminal supported by DECTPU.

Signaled Errors

Examples

The following example moves the cursor position one screen column to the right:

int_x := CURSOR_HORIZONTAL (1) 
      

The following example provides for free cursor motion to the left. You can bind these procedures to keys (for example, the arrow keys) so that the movement can be accomplished with a single keystroke.

PROCEDURE user_free_cursor_left 
   move_left := CURSOR_HORIZONTAL (-1); 
ENDPROCEDURE; 
      

Format

[[integer2 :=]] CURSOR_VERTICAL (integer1)

Parameter

integer1

The signed integer value that specifies how many screen lines to move the cursor position. A positive value for integer1 moves the cursor position down. A negative integer moves the cursor position up.

Return Value

If CROSS_WINDOW_BOUNDS is set to ON, CURSOR_VERTICAL may position the cursor to another window. In this case, CURSOR_VERTICAL returns the negative of the number of rows the cursor moved. A negative return value does not denote that the cursor moved upward.

If the cursor did not move, integer2 has the value 0. If the CURSOR_VERTICAL built-in procedure produced an error, the value of integer2 is indeterminate.

Description

The CURSOR_VERTICAL procedure moves the cursor position up or down the screen and optionally returns the cursor movement status. You can use CURSOR_VERTICAL to provide free cursor movement in a vertical direction. Free cursor movement means that the cursor is not tied to text, but that it can move up and down to all lines on the screen that can be edited, whether or not there is text at that column in the new line.

The cursor does not move beyond the top or the bottom edges of the screen. However, CURSOR_VERTICAL can cross window boundaries, depending upon the current setting of the CROSS_WINDOW_BOUNDS flag. See SET (CROSS_WINDOW_BOUNDS) for information on how to set this flag. (Use the POSITION built-in to move the cursor to a different window on the screen.)

When CROSS_WINDOW_BOUNDS is set to ON, CURSOR_VERTICAL can move the cursor position to a new window. The new window in which the cursor is positioned becomes the current window. The column position of the cursor remains unchanged unless vertical movement would position the cursor outside the bounds of a window narrower than the previous window. In this instance, the cursor moves to the left until it is positioned within the right boundary of the narrower window.

When CROSS_WINDOW_BOUNDS is set to OFF, CURSOR_VERTICAL does not move the cursor outside the current window. If the SET (SCROLLING) built-in has been used to set scrolling margins, CURSOR_VERTICAL also attempts to keep the cursor within the scroll margins.

CURSOR_VERTICAL positions the cursor only in screen areas in which editing can occur. For example, CURSOR_VERTICAL does not position the cursor on the status line of a window, in the prompt area, or in an area of the screen that is not part of a window. The blank portion of a segmented window is not considered part of a window for this purpose.

If you use CURSOR_VERTICAL within a procedure, screen updating occurs in the following manner:

• When you execute a built-in that modifies the buffer or the current character position before you issue the call to CURSOR_VERTICAL, the screen is updated before CURSOR_VERTICAL is executed. This action ensures that the vertical movement of the cursor starts at the correct character position. Otherwise, the screen manager does not update the screen until the procedure has finished executing and control is returned to the screen manager.
• CURSOR_VERTICAL has no effect if you use an input device other than a video terminal supported by DECTPU.

Signaled Errors

Examples

The following example moves the cursor position five lines toward the bottom of the screen:

int_y := CURSOR_VERTICAL (5) 
      

The following example provides for free cursor motion up and down the screen. These procedures can be bound to keys (for example, the arrow keys) so that you can make the movement with a single keystroke.

PROCEDURE user_free_cursor_down 
 
   IF GET_INFO (CURRENT_WINDOW, "CURRENT_ROW") = 
               GET_INFO (CURRENT_WINDOW, "VISIBLE_BOTTOM") 
   THEN 
       SCROLL (CURRENT_WINDOW, 1); 
   ELSE 
       right_x := CURSOR_VERTICAL (1); 
   ENDIF; 
ENDPROCEDURE; 
      

These examples work regardless of the setting of CROSS_WINDOW_BOUNDS because the SCROLL built-in procedure keeps the cursor motion within a single window.

Format

integer := DEBUG_LINE

Parameters

None.

Return Value

Description

The DEBUG_LINE procedure returns the line number of the current breakpoint. Use DEBUG_LINE when writing your own DECTPU debugger.

DIGITAL recommends that you use the debugger provided in SYS$SHARE:TPU$DEBUG.TPU.

Signaled Error

Example

In the following example, the code fragment first uses GET_INFO to request the line number of the breakpoint in the current procedure. If the line number is 0, meaning that the breakpoint is not in a procedure, the code uses DEBUG_LINE to determine the breakpoint's line number relative to the buffer.

the_line := GET_INFO (DEBUG, "line_number"); 
IF the_line = 0 
    THEN the_line := DEBUG_LINE; 
ENDIF; 
      

Format

DEFINE_KEY ({buffer|learn|program|range|string1}, key-name
[[ ,string2 [[ ,string3]] ]])

Parameters

buffer

A buffer that contains the DECTPU statements to be associated with a key.

learn

A learn sequence that specifies the executable code associated with a key.

program

A program that contains the executable code to be associated with a key.

range

A range that contains the DECTPU statements to be associated with a key.

string1

A string that specifies the DECTPU statements to be associated with a key.

key-name

A DECTPU key name for a key or a combination of keys. See the Guide to the DEC Text Processing Utility for a list of the DECTPU key names for the LK0201 and LK0401 series of keyboards. You can also use the SHOW (KEYWORDS) built-in procedure to display all the DECTPU keywords.

See the Description section of this built-in procedure for information on keys that you cannot define.

To define a key for which there is no DECTPU key name, use the KEY_NAME built-in procedure to create your own key name for the key. For example, KEY_NAME ("A", SHIFT_KEY) creates a key name for the combination of PF1, the default shift key for DECTPU, and the keyboard character A. For more information, see the description of the KEY_NAME built-in procedure.

string2

An optional string associated with a key that you define. The string is treated as a comment that you can retrieve with the LOOKUP_KEY built-in procedure. You might want to use the comment if you are creating a help procedure for keys that you have defined.

string3

A key map or a key map list in which the key is to be defined. If a key map list is specified, the key is defined in the first key map in the key map list. If neither a key map nor a key map list is specified, the key is defined in the first key map in the key map list bound to the current buffer. See the descriptions of the CREATE_KEY_MAP, CREATE_KEY_MAP_LIST, and SET (KEY_MAP_LIST) built-in procedures for more information on key maps and key map lists.

Description

The DEFINE_KEY procedure associates executable DECTPU code with a key or a combination of keys. DEFINE_KEY compiles the first parameter if it is a string, buffer, or range.

If you use DEFINE_KEY to change the definition of a key that was previously defined, DECTPU does not save the previous definition.

You can define all the keys on the LK201 and LK401 keyboards and keypads with the following exceptions:

• The Compose Character key and Alt function key
• The Shift keys
• The Escape key
• The keys F1 through F5

There are some keys that you can define but that DIGITAL strongly recommends you avoid defining. DECTPU does not signal an error when you use them as keyword parameters. However, on character-cell terminals the definitions you assign to these key combinations are not executed unless you set your terminal in special ways at the DCL level. DIGITAL recommends that you do not use the following special terminal settings. The settings may cause unpredictable results if you do not understand all the implications of changing the default settings:

• Ctrl/C, Ctrl/O, Ctrl/X, and F6---To execute programs that you bind to these keys, you must first enter the DCL SET TERMINAL/PASTHRU command.
• Ctrl/T, Ctrl/Y---To execute programs that you bind to these keys, you must first enter the DCL SET TERMINAL/PASTHRU command, the DCL SET NOCONTROL command, or both.
• Ctrl/S, Ctrl/Q---To execute programs that you bind to these keys, you must first enter the DCL SET TERMINAL/NOTTSYNC command.

The PF1 key is the default shift key for the editor. You cannot define PF1 unless you use either the SET (SHIFT_KEY, keyword) built-in procedure or the EVE SET GOLD KEY command to define a different key as the shift key for the editor.

Whenever you extend EVE by writing a procedure that can be bound to a key, the procedure must return true or false, as needed, to indicate whether execution of the procedure completed successfully. EVE's REPEAT command relies on this return value to determine whether to halt repetition of a command, a procedure bound to a key, or a learn sequence.

Signaled Errors

Examples

The following example associates the DECTPU statement POSITION (main_window) with the key combination Ctrl/B. You must use quotation marks around the DECTPU statement.

DEFINE_KEY ("POSITION (main_window)", Ctrl_B_KEY) 
      

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_006.HTML