Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

The following example puts the text from the scratch buffer before the editing point in the main buffer. The text in the scratch buffer is removed; no copy of it is left there.

#2
PROCEDURE user_move_text LOCAL this_mode; ! Save mode of current buffer in this_mode this_mode := GET_INFO (CURRENT_BUFFER, "mode"); ! Set current buffer to insert mode SET (INSERT, CURRENT_BUFFER); ! Move the scratch buffer text to the current buffer MOVE_TEXT (scratch_buffer); ! Reset current buffer to original mode SET (this_mode, CURRENT_BUFFER); ENDPROCEDURE;

Format

MOVE_VERTICAL (integer)

Parameter

integer

The signed integer value that indicates the number of lines that the editing point should be moved. A positive integer specifies movement toward the end of the buffer. A negative integer specifies movement toward the beginning of the buffer.

Description

The MOVE_VERTICAL procedure modifies the editing point in the current buffer by the number of lines you specify. The adjustment that MOVE_VERTICAL makes is tied to text. DECTPU tries to retain the same character offset relative to the beginning of the line when moving vertically. However, if there are tabs in the lines, or the lines have different margins, the editing point does not necessarily retain the same column position on the screen.

By default, DECTPU keeps the cursor at the same offset on each line. However, because DECTPU counts a tab as one character regardless of how wide the tab is, the cursor's column position may vary greatly even though the offset is the same.

To keep the cursor in approximately the same column on each line, use the following statement:

SET (COLUMN_MOVE_VERTICAL, ON)

This statement directs DECTPU to keep the cursor in the same column unless a tab character makes this impossible. If a tab occupies the column position, DECTPU moves the cursor to the beginning of the tab.

You cannot see the adjustment caused by MOVE_VERTICAL unless the current buffer is mapped to a visible window. If it is, DECTPU scrolls text in the window, if necessary, so that the editing point you establish with MOVE_VERTICAL is within the scrolling limits set for the window.

Using MOVE_VERTICAL may cause DECTPU to insert padding spaces or blank lines in the buffer. MOVE_VERTICAL 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 try to move past the beginning or end of a buffer, DECTPU signals a warning message.

Signaled Errors

Examples

The following example moves the editing point in the current buffer down five lines toward the end of the buffer:

MOVE_VERTICAL (+5) 
      

The following example moves the editing point by sections that are eight lines long:

PROCEDURE user_move_8_lines 
 
   IF CURRENT_DIRECTION = FORWARD 
   THEN 
       MOVE_VERTICAL (8); 
   ELSE 
       MOVE_VERTICAL (- 8); 
   ENDIF; 
   MOVE_HORIZONTAL(- CURRENT_OFFSET); 
ENDPROCEDURE; 
      

Format

pattern := NOTANY (

• buffer
• range
• string

[[, integer1 ]])

Parameters

buffer

An expression that evaluates to a buffer. NOTANY matches any character not in the resulting buffer.

range

An expression that evaluates to a range. NOTANY matches any character not in the resulting range.

string

An expression that evaluates to a string. NOTANY matches any character not in the resulting string.

integer1

This integer value indicates how many contiguous characters NOTANY matches. The default value for this integer is 1.

Return Value

Description

The NOTANY procedure returns a pattern that matches a specific number of contiguous characters not in the string, buffer, or range that is used as the first parameter. The second parameter determines the number of characters NOTANY must match. NOTANY does not match across line breaks.

Signaled Errors

Examples

The following example creates a pattern that matches the first character that is not an X, a Y, or a Z. The match fails if no character other than X, Y, or Z is found.

pat1 := NOTANY ("XYZ") 
      

The following example creates a pattern that matches any single character other than one of the characters a, b, c, x, and y:

a_buf := CREATE_BUFFER ("new buffer"); 
POSITION (a_buf); 
COPY_TEXT ("xy"); 
SPLIT_LINE; 
COPY_TEXT ("abc"); 
pat1 := NOTANY (a_buf); 
 
      

The following example starts at the current location and looks for the first nonalphabetic, nonlowercase character. The variable non_alpha_range stores the character that matches these conditions.

! 
! The following procedure returns a marker pointing to 
! the next nonalphabetic character or the integer zero 
! if there are no more nonalphabetic characters.  You 
! call the procedure in the following way: 
! 
!   non_alpha_marker := user_search_for_nonalpha; 
 
PROCEDURE user_search_for_nonalpha 
 
   LOCAL pat, 
         first_non_alpha; 
 
   pat := NOTANY ("abcdefghijklmnopqrstuvwxyz"); 
 
   first_non_alpha := SEARCH_QUIETLY (pat, FORWARD, NO_EXACT); 
 
   IF first_non_alpha <> 0 
   THEN 
       first_non_alpha := BEGINNING_OF (first_non_alpha); 
   ENDIF; 
 
   RETURN first_non_alpha; 
ENDPROCEDURE; 
      

Format

PAGE_BREAK

Parameters

None.

Description

The PAGE_BREAK procedure specifies the form-feed character, ASCII(12), as a portion of a pattern to be matched. This character has an ASCII value of 12.

Although PAGE_BREAK behaves much like a built-in, it is actually a keyword.

If the form-feed character is the only character on a line, PAGE_BREAK matches the whole line. If the form-feed character is not the only character on a line, PAGE_BREAK matches only the form-feed character.

Signaled Error

Example

The following example places the cursor on the next page in the current buffer. If you are already on the last page of a document, it places the cursor at the end of that document.

PROCEDURE user_next_page 
 
   LOCAL next_page; 
 
   next_page := SEARCH_QUIETLY (PAGE_BREAK, FORWARD); 
   IF next_page <> 0 
   THEN 
       POSITION (next_page); 
   ELSE 
       POSITION (end_of (current_buffer)); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

POSITION (

• buffer
• BUFFER_BEGIN
• BUFFER_END
• integer
• LINE_BEGIN
• LINE_END
• marker
• MOUSE
• range
• TEXT
• window

)

Parameters

buffer

The buffer in which you want to establish the editing point.

DECTPU maintains an editing point in each buffer even when the buffer is not the current buffer. When you position to a buffer, the editing point that DECTPU maintains becomes the active editing point. The location at which POSITION establishes the editing point is the last character that the cursor was on when the buffer was most recently current.

BUFFER_BEGIN

A keyword that directs DECTPU to establish the editing point at the beginning of the current buffer. This is more efficient than using POSITION (BEGINNING_OF (CURRENT_BUFFER)).

BUFFER_END

A keyword that directs DECTPU to establish the editing point at the end of the current buffer. This is more efficient than using POSITION (END_OF (CURRENT_BUFFER)).

integer

The number of the record where you want DECTPU to position the editing point.

A record number indicates the location of a record in a buffer. Record numbers are dynamic; as you add or delete records, DECTPU changes the number associated with a particular record, as appropriate. DECTPU counts each record in a buffer, regardless of whether the line is visible in a window, or whether the record contains text.

To position the editing point to a given record, specify the record number. The number can be in the range from 1 to the number of records in the buffer plus 1. For example, the following statement positions the editing point to record number 8 in the current buffer:

POSITION (8);

DECTPU places the editing point on the first character of the record.

Specifying a value of 0 has no effect. Specifying a negative number or a number greater than the number of records in the buffer plus 1 causes DECTPU to signal an error.

LINE_BEGIN

A keyword that directs DECTPU to establish the editing point at the beginning of the current line.

LINE_END

A keyword that directs DECTPU to establish the editing point at the end of the current line.

marker

The marker to which you want to tie the editing point. You can position to either a bound marker or a free marker. (For more information on the distinction between bound and free markers, see the Guide to the DEC Text Processing Utility.) Positioning to a free marker does not cause DECTPU to insert padding blanks between the nearest text and the free marker; such positioning establishes the editing point as free. (For more information on the distinction between free and detached editing points, see Appendix C.)

MOUSE

A keyword that directs DECTPU to associate the editing point with the location of the pointer cursor.

In DECwindows DECTPU, you can use the statement POSITION (MOUSE) at any point after the first keyboard or mouse button event. The statement positions the editing point to the location occupied by the pointer cursor at the time of the most recent keyboard or mouse-button event.

If the pointer cursor is on a window's status line when POSITION (MOUSE) is executed, DECTPU positions the editing point at the line just above the status line.

Note Be sure that you do not have scroll margins active when you execute POSITION (MOUSE). If scroll margins are active, the result can be unpredictable. Use the SET (CROSS_WINDOW_BOUNDS, OFF) command prior to using POSITION (MOUSE).

If the pointer cursor is not located in a DECTPU window at the time of the most recent keyboard or mouse-button event, POSITION (MOUSE) returns the status TPU$_NOWINDOW.

In non-DECwindows DECTPU, POSITION (MOUSE) is valid only during a procedure that is executed as the result of a mouse click. At all other times, the mouse position is not updated.

The statement POSITION (MOUSE) makes the window in which the pointer cursor is located the current window, and the buffer in which the pointer cursor is located the current buffer.

range

The range in which you want to place the editing point. The editing point is established at the beginning of the range. To establish the editing point at the end of the range, use the statement POSITION (END_OF (range)).

TEXT

A keyword that indicates that if the editing point is at a free-cursor location (a portion of the screen where there is no text), the POSITION built-in procedure is to establish the editing point at the nearest location that has a text character in it. The character may be a space or an end of line. If you use POSITION (TEXT) when the editing point is already bound to a character, the built-in has no effect.

window

The window in which you want to establish the editing point. The window must be mapped to the screen.

The location at which POSITION establishes the editing point is the last character that the cursor was on when the window was most recently current. If that character has been deleted, the editing point is the character closest to the last character that the cursor was on when the window was current.

Positioning to a window causes the buffer associated with the window to become the current buffer. This is true whether you directly position to a window, or a new window is mapped as the result of a POSITION (MOUSE) statement.

Description

The POSITION procedure ties the editing point to a specific character in a specific buffer, and moves the editing point to a specified record in the current buffer. The character and buffer in which POSITION establishes the editing point depend on which parameter you pass to POSITION.

The editing point is the location in the current buffer where most editing operations are carried out. DECTPU maintains a marker pointing to an editing point in each buffer, but only the editing point in the current buffer is active. An editing point, whose location is always tied to a character in a buffer, is not necessarily the same as the cursor position, whose location is always tied to a position in a window.

The POSITION built-in procedure synchronizes the editing point and the cursor position if the current buffer is mapped to a visible window. POSITION also moves the editing point to the specified record in the current buffer.

When you pass the MOUSE keyword to POSITION, the built-in establishes the mouse pointer's location as the cursor position. POSITION also establishes the window in which the mouse pointer is located as the current window, and establishes the buffer mapped to that window as the current buffer.

Positioning to a buffer, a marker, or a range does not necessarily move the cursor. DECTPU does not change the cursor position unless the cursor is in a window that is mapped to the buffer specified or implied by the POSITION parameter. For example, if you use POSITION to establish the editing point in a buffer that is not mapped to a window, the cursor is unaffected by the POSITION operation. If you want to do visible editing, you should position to a window rather than a buffer.

If you try to position to an invisible window, DECTPU issues a warning message.

For more information on the relationship between the editing point and the cursor position, see Appendix C.

Signaled Errors

• TPU$_TOOFEW	ERROR	POSITION requires one parameter.
  TPU$_TOOMANY	ERROR	You specified more than one parameter.
  TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.
  TPU$_ARGMISMATCH	ERROR	Wrong type of data sent to the built-in.
  TPU$_BADKEY	WARNING	You specified an invalid keyword.
  TPU$_UNKKEYWORD	ERROR	You specified an unknown keyword.
  TPU$_BADVALUE	ERROR	You specified a record number less than 0 or greater than the length of the buffer plus 1.
  TPU$_MOUSEINV	WARNING	The mouse position is not currently valid.
  TPU$_NOWINDOW	WARNING	The pointer cursor was not located in a DECTPU window at the time of the most recent keyboard or mouse-button event.
  TPU$_WINDNOTMAPPED	WARNING	Window is not mapped to the screen.
  TPU$_WINDNOTVIS	WARNING	Window is totally occluded.

Examples

The following example establishes the editing point in the message window. Your position in the window is the same character position you occupied when you were last positioned in the window.

POSITION (message_window) 
      

The following example toggles the active editing point between two windows:

PROCEDURE user_change_windows 
 
   IF CURRENT_WINDOW = main_window 
   THEN 
       POSITION (extra_window); 
   ELSE 
       POSITION (main_window); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

QUIT [[ (

• ON
• OFF
• 1
• 0

[[, severity ]])]]

Parameters

ON, 1

Either keyword, ON or 1, indicates that DECTPU should prompt you to find out whether you want to quit with modified buffers. This is the default value.

OFF, 0

Either keyword, OFF or 0, indicates that DECTPU should quit without asking you whether to quit with modified buffers.

severity

If present, the least significant two bits of this integer are used as the severity of the status DECTPU returns to whatever invoked it. The following shows the values and their severity:

Value	Severity
0	Warning
1	Success
2	Error
3	Informational

You cannot force DECTPU to return a fatal severity status.

Description

The QUIT procedure leaves the editor without writing to a file. If you modify any buffers that are not set to NO_WRITE and you do not specify OFF as the first parameter to the QUIT built-in procedure, DECTPU tells you that you have modified buffers and asks whether you want to quit. Enter Y (YES) if you want to quit without writing out any modified buffers. Enter N (NO) if you want to retain the modifications you have made and return to the editor. If you specify OFF as the first parameter to QUIT, DECTPU quits without informing you that you have modified buffers. All modifications are lost because DECTPU does not write out buffers when quitting.

Journal files (if any) are deleted upon quitting.

Use the EXIT built-in procedure when you have made changes and want to save them when you leave the editor. (For more information, see the description of EXIT.)

When DECTPU quits, it usually returns a status of TPU$_QUITTING to whatever invoked it. This is a success status.

This feature is useful if you are using DECTPU to create an application in which quitting, especially before the end of a series of statements executing in batch mode, is an error.

A special use of QUIT is at the end of your section file when you are compiling it for the first time. See the Guide to the DEC Text Processing Utility for information on creating section files.

Signaled Errors

• TPU$_CANCELQUIT	WARNING	A NO response was received from the "...continue quitting?" prompt.
  TPU$_TOOMANY	ERROR	QUIT accepts no more than two arguments.
  TPU$_INVPARAM	ERROR	One of the arguments to QUIT has the wrong data type.
  TPU$_BADKEY	WARNING	QUIT accepts only the keywords ON and OFF.
  TPU$_NORETURNVALUE	ERROR	QUIT does not return a value.

Examples

The following example returns control of execution from an editor layered on DECTPU to the program, application, or operating system that called DECTPU:

QUIT; 
      

If you have modified any buffers, you see the following prompt:

Buffer modifications will not be saved, continue quitting (Y or N)?

Enter YES if you want to quit and not save the modifications. Enter NO if you want to return to the editor.

The following example turns off the display of the success message "Editor successfully quitting" when you use QUIT to leave an editing interface:

PROCEDURE user_quit 
 
   SET (SUCCESS, OFF); 
   QUIT; 
 
! Turn message back on in case user answers "No" to the 
! prompt "Buffer modifications will not be saved, continue 
! quitting (Y or N)?" 
 
   SET (SUCCESS, ON); 
ENDPROCEDURE; 
 
      

Format

RAISE_WIDGET (widget)

Parameter

widget

The widget you want DECTPU to raise. The specified widget must be a subclass of WindowObjClass.

Description

The RAISE_WIDGET procedure places the widget at the top of a viewing stack above all sibling widgets. This ensures that the widget window associated with the widget is not obscured by any sibling windows. It calls the XLIB routine XRaiseWindow.

The widget window is mapped if it is not already mapped.

Signaled Errors

• TPU$_INVPARAM	ERROR	The parameter to LOWER_WIDGET has the wrong data type.
  TPU$_NORETURNVALUE	ERROR	This built-in does not return a result.
  TPU$_NOTSUBCLASS	WARNING	The parameter to LOWER_WIDGET is not a widget that has an associated widget window.
  TPU$_TOOFEW	ERROR	You specified too few parameters.
  TPU$_TOOMANY	ERROR	You specified too many parameters.

Format

string := READ_CHAR

Parameters

None.

Return Value

Description

The READ_CHAR procedure stores the next character entered from the keyboard in a string variable. The character read by READ_CHAR is not echoed on the screen; therefore, the cursor position does not move.

---

Previous

Next

Contents

Index

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6020PRO_020.HTML