Document revision date: 30 March 2001

The following example shows a portion of a command file that defines the keys for an editing interface that emulates EDT:

#2
! Procedure to define keys to emulate EDT PROCEDURE user_define_edtkey ! Bind the EDT Fndnxt function to PF3 DEFINE_KEY ("edt$search_next", PF3); ! Bind the EDT Find function to SHIFT PF3 DEFINE_KEY ("edt$search", KEY_NAME (PF3, SHIFT_KEY)); ENDPROCEDURE;

Format

keyword := LAST_KEY

Parameters

None.

Return Value

Description

The LAST_KEY procedure returns a DECTPU keyword for the last key that was entered, read, or executed. When DECTPU is replaying a learn sequence or executing the program bound to a key, LAST_KEY returns the last key replayed or processed so far---not the last key that was pressed to invoke the learn sequence or program.

When you invoke DECTPU with the /NODISPLAY qualifier, the value 0 is returned for LAST_KEY, except in the following case: If you precede the LAST_KEY statement with a READ_LINE statement, LAST_KEY can return a key name that represents the last key read by READ_LINE, Ctrl/Z, or the Return key. See the description of READ_LINE for more information on the values that LAST_KEY can return when you use LAST_KEY while running DECTPU in /NO_DISPLAY mode.

Signaled Error

Example

The following example prompts you for input for key definitions:

PROCEDURE user_define_key 
 
   def := READ_LINE ("Definition: "); 
   key := READ_LINE ("Press key to define.",1); 
   IF LENGTH (key) > 0 
   THEN 
       key := KEY_NAME (key) 
   ELSE 
         key := LAST_KEY; 
   ENDIF; 
   DEFINE_KEY (def, key); 
ENDPROCEDURE; 
      

Format

[[integer := ]] LEARN_ABORT

Parameters

None.

Return Value

Description

The LEARN_ABORT procedure causes a learn sequence being replayed to be terminated whether or not the learn sequence has completed. Only the currently executing learn sequence is aborted.

Whenever you write a procedure that can be bound to a key, the procedure should invoke the LEARN_ABORT built-in procedure in case of error. Using LEARN_ABORT prevents a learn sequence from finishing if the learn sequence calls the user-written procedure and the procedure is not executed successfully.

Signaled Error

Example

If an error occurs, the following error handler aborts any executing learn sequence:

ON_ERROR 
   MESSAGE ("Aborting command because of error."); 
   LEARN_ABORT; 
   ABORT; 
ENDON_ERROR 
      

Format

LEARN_BEGIN ({EXACT|NO_EXACT})

.

.

.

learn := LEARN_END

Parameters

EXACT

Causes DECTPU to reuse the input, or learn sequence, that you entered for each READ_LINE, READ_KEY, or READ_CHAR built-in procedure.

NO_EXACT

Causes DECTPU to prompt for new input each time a READ_LINE, READ_KEY, or READ_CHAR built-in procedure is replayed within a learn sequence.

Return Value

Description

The LEARN_BEGIN and LEARN_END procedures saves all keystrokes typed between LEARN_BEGIN and LEARN_END. LEARN_BEGIN starts saving all keystrokes that you type. LEARN_END stops the "learn mode" of DECTPU and returns a learn sequence that consists of all the keystrokes that you entered.

You can use the variable name that you assign to a learn sequence as the parameter for the EXECUTE built-in procedure to replay a learn sequence. You can also use the variable name with the DEFINE_KEY built-in procedure to bind the sequence to a key so that the learn sequence is executed when you press that key.

Learn sequences are different from other DECTPU programs because they are created with keystrokes rather than with DECTPU statements. You create the learn sequence as you are entering text and executing DECTPU commands. Because learn sequences make it easy to collect and execute a sequence of DECTPU commands, they are convenient for creating temporary "programs." You can replay these learn sequences during the editing session in which you create them.

Learn sequences are not flexible enough to use for writing general programs. Learn sequences are best suited for saving a series of editing actions that you perform many times during a single editing session.

You can save learn sequences from session to session so that you can replay them in an editing session other than the one in which you created them. To save a learn sequence, bind it to a key. Before ending your editing session, use the SAVE built-in procedure to do an incremental save to the section file you are using. Using the SAVE built-in procedure causes the new definitions from the current session to be added to the section file with which you invoked DECTPU. For more information, see the SAVE built-in procedure.

Learn sequences cannot be transferred from one version of DECTPU to another.

Note You should not use built-in procedures that can return WARNING or ERROR messages as a part of a learn sequence because learn sequences do not stop on error conditions. Because the learn sequence continues executing after an error or warning condition, the editing actions that are executed after an error or a warning may not take effect at the character position you desire. If, for example, a SEARCH built-in procedure that you use as a part of a learn sequence fails to find the string you specify and issues a warning, the learn sequence does not stop executing. This can cause the rest of the learn sequence to take inappropriate editing actions.

Prekey and postkey procedures interact with learn sequences in the following order:

1. When you press the key or key sequence to which the learn sequence is bound, DECTPU executes the prekey procedure of that key if a prekey procedure has been set.
2. For each key in the learn sequence, DECTPU executes procedures or programs in the following order:
   1. DECTPU executes the prekey procedure of that key if a prekey procedure has been set.
   2. DECTPU executes the code bound to the key itself.
   3. DECTPU executes the postkey procedure of that key if a postkey procedure has been set.
3. When all keys in the learn sequence have been processed, DECTPU executes the postkey procedure, if one has been set, for the key to which the entire learn sequence was bound.

Note If, during the recording of a learn sequence, a margin action route is executed (for example EVE's word wrap), the margin action routine is not executed when the learn sequence is replayed.

Signaled Errors

Example

The following example shows how to combine LEARN_BEGIN and LEARN_END so that all of the keystrokes that you enter between them are saved. The (EXACT) keyword specifies that if you use READ_LINE, READ_CHAR, or READ_KEY within the learn sequence, any input that you enter for these built-in procedures is repeated exactly when you replay the learn sequence.

LEARN_BEGIN (EXACT) 
             . 
             . 
             . 
This represents a typical editing session, 
in which you perform commands that are 
bound to keys. 
             . 
             . 
             . 
do_again := LEARN_END 
 
      

Format

integer := LENGTH ( {buffer |range |string})

Parameters

buffer

The buffer whose length you want to determine. If you specify a buffer, line terminators are not counted as character positions.

range

The range whose length you want to determine. If you specify a range, line terminators are not counted as character positions.

string

The string whose length you want to determine.

Return Value

Description

The LENGTH procedure returns an integer that is the number of character positions in a buffer, range, or string.

Signaled Errors

Examples

The following example stores the number of characters in the string "Don Quixote" in the variable str_len. In this example, the integer value is 11:

str_len := LENGTH ("Don Quixote") 
      

The following example puts a marker without any video attributes at the current position. The marker is assigned to a variable that begins with user_mark_ and ends with the string you pass as a parameter. The procedure writes a message to the message area verifying the mark name that comes from the input parameter.

! Parameters: 
! 
!   mark_parameter is user-supplied string, 
!   which is used as a mark name 
 
PROCEDURE user_mark_ (mark_parameter) 
 
! Local copy of mark_parameter 
 
   LOCAL mark_name; 
 
   ON_ERROR 
       MESSAGE (FAO ("Cannot use !AS as a mark name", mark_name)); 
       RETURN; 
   ENDON_ERROR; 
 
! 132 - length ("user_mark_") 
 
   IF LENGTH (mark_parameter) > 122 
   THEN 
       mark_name := SUBSTR (mark_name, 1, 122); 
   ELSE 
       mark_name := mark_parameter; 
   ENDIF; 
 
   EXECUTE ("user_mark_" + mark_name + " := MARK (NONE)"); 
   MESSAGE (FAO ("Current position marked as !AS", mark_name)); 
ENDPROCEDURE; 
      

Format

LINE_BEGIN

Parameters

None.

Description

The LINE_BEGIN procedure matches the beginning of a line when used as part of a complex pattern or as an argument to SEARCH. Although LINE_BEGIN behaves much like a built-in, it is actually a keyword.

LINE_BEGIN lets you search for complex strings by creating patterns that match certain conditions. For example, if you want to find all occurrences of the exclamation point (!) when it is the first character in the line, use LINE_BEGIN to create the following pattern:

pat1 := LINE_BEGIN + "!";

For more information on patterns, see the Guide to the DEC Text Processing Utility.

Signaled Errors

Examples

The following example stores the beginning-of-line condition in the variable pat1:

pat1 := LINE_BEGIN 
      

The following example removes all lines that start with Compaq Standard Runoff (DSR) commands from a file by searching for a pattern that has a period (.) at the beginning of a line and then removing the lines that match this condition:

PROCEDURE user_remove_dsrlines 
 
   LOCAL s1, 
         pat1; 
 
   pat1 := LINE_BEGIN + "."; 
 
   LOOP 
      s1 := SEARCH_QUIETLY (pat1, FORWARD); 
      EXITIF s1 = 0; 
      POSITION (s1); 
      ERASE_LINE; 
   ENDLOOP; 
ENDPROCEDURE; 
 
      

Format

LINE_END

Parameters

None.

Description

The LINE_END procedure matches the end of a line when used as part of a complex pattern or as an argument to SEARCH. Although LINE_END behaves much like a built-in, it is actually a keyword.

The end-of-line condition is one character position to the right of the last character on a line.

For more information on patterns, see the Guide to the DEC Text Processing Utility.

Signaled Errors

Examples

The following example stores the LINE_END keyword in the variable pat1. You can use Pat1 as an argument to the SEARCH built-in or as part of a complex pattern.

pat1 := LINE_END 
      

In the following example, if you are not already at the end of the current line, the preceding procedure moves the editing point to the end of the line:

PROCEDURE user_end_of_line 
 
   LOCAL eol_range; 
 
   eol_range := SEARCH_QUIETLY (LINE_END, FORWARD); 
 
   IF eol_range <> 0 
   THEN 
      POSITION (eol_range); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

[[ integer := ]] LOCATE_MOUSE (window, x_integer, y_integer)

Parameters

window

Returns the window in which the pointer is located. You can pass any data type except a constant in this parameter. If the pointer is not found, an unspecified data type is returned.

x_integer

Returns the column position of the pointer. You can pass any data type except a constant in this parameter. If the pointer is not found, an unspecified data type is returned. This parameter returns 0 if the pointer is in a vertical scroll bar.

y_integer

Returns the row position of the pointer. You can pass any data type except a constant in this parameter. If the pointer is not found, an unspecified data type is returned. This parameter returns 0 if the pointer is in the status line for a window.

Return Value

Description

The LOCATE_MOUSE procedure locates the window position of the pointer at the time LOCATE_MOUSE is invoked. LOCATE_MOUSE returns the window name and the window position of the pointer and optionally returns a status that indicates whether the pointer was found in a window. When you press a mouse button, DECTPU determines the location of the mouse pointer and makes that information available while the code bound to the mouse button is being processed. Mouse pointer location information is not available at any other time.

In DECwindows DECTPU, you can use the LOCATE_MOUSE built-in procedure anytime after the first keyboard or mouse-button event. The built-in returns the location occupied by the pointer cursor at the time of the most recent keyboard or mouse button event.

If there is no mouse information available (because no mouse button has been pressed or if the mouse has been disabled using SET (MOUSE)), LOCATE_MOUSE signals the status TPU$_MOUSEINV.

Signaled Errors

Examples

The following example statement returns an integer in the variable status that indicates whether the pointer cursor was found in a window; returns the window in the parameter new_window where the mouse was found; returns an integer in the parameter x_value that specifies the pointer cursor's location in the horizontal dimension; and returns an integer in the parameter y_value that specifies the pointer cursor's location in the vertical dimension.

status := LOCATE_MOUSE (new_window, x_value, y_value); 
 
      

In the following example, binding the user_move_to_mouse procedure to a mouse button moves the cursor to the mouse location. The user_move_to_mouse procedure is essentially equivalent to POSITION (MOUSE).

PROCEDURE user_move_to_mouse 
 
   LOCAL my_window, 
         x_1, 
         y1; 
 
   IF (LOCATE_MOUSE (my_window, x_1, Y1) <> 0) 
   THEN 
      IF (CURRENT_WINDOW <> my_window) 
      THEN 
         POSITION (my_window); 
         UPDATE (my_window); 
      ENDIF; 
      CURSOR_VERTICAL (y1 - (CURRENT_ROW - GET_INFO 
                      (my_window,"visible_top") + 1)); 
      CURSOR_HORIZONTAL (CURRENT_COLUMN - x_1); 
   ENDIF; 
ENDPROCEDURE; 
      

CURRENT_ROW and CURRENT_COLUMN return screen-relative location information, while LOCATE_MOUSE returns window-relative location information.

Format

{integer |learn_sequence |program |string3} := LOOKUP_KEY

(key-name, {COMMENT |KEY_MAP |PROGRAM} [[{, string1 |, string2}]])

Parameters

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 LK201, LK401, and VT100-series keyboards.

COMMENT

A keyword that specifies that the LOOKUP_KEY built-in procedure is to return the comment supplied when the key was defined. If no comment was supplied, the LOOKUP_KEY built-in returns the integer zero.

KEY_MAP

A keyword that specifies that the LOOKUP_KEY built-in procedure is to return the key map in which the key's definition is stored. If you specify a key that is not defined in any key map, LOOKUP_KEY returns a null string.

PROGRAM

A keyword that specifies that the LOOKUP_KEY built-in procedure is to return the program or learn sequence bound to the key specified. If the key is not defined, the LOOKUP_KEY built-in returns the integer 0.

string1

The name of the key map from which the LOOKUP_KEY built-in procedure is to get the key definition. Use this optional parameter if the key is defined in more than one key map. If you do not specify a key map or a key map list for the third parameter, the first definition found for the specified key in the key map list bound to the current buffer is returned.

string2

The name of the key map list from which the LOOKUP_KEY built-in procedure is to get the key definition. Use this optional parameter if the key is defined in more than one key map list. If you do not specify a key map or a key map list for the third parameter, the first definition found for the specified key in the key map list bound to the current buffer is returned.

Return Values

integer

The integer 0. This value is returned if the key specified as a parameter has no definition.

learn_sequence

The learn sequence bound to the key specified as a parameter.

program

The program bound to the key specified as a parameter.

string3

If you specified COMMENT as the second parameter, string3 is the comment bound to the key specified as the first parameter. If you specified KEY_MAP as the second parameter, string3 is the string naming the key map in which the key definition was found.

Description

The LOOKUP_KEY procedure returns the executable code or the comment that is associated with the key that you specify. The code can be returned as a program or as a learn sequence. The comment is returned as a string. LOOKUP_KEY can return a program, a learn sequence, a string, or the integer 0 (0 means that the key has no definition).

LOOKUP_KEY is useful when you are defining keys temporarily during an editing session and you want to check the existing definitions of a key.

Signaled Errors

Examples

The following example returns the executable code that is associated with key1. The second keyword, PROGRAM, indicates that the result is returned to a variable of type program or learn.

programx := LOOKUP_KEY (key1, PROGRAM) 
      

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_017.HTML