Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

DEC Text Processing Utility Reference Manual


Previous Contents Index

The following example removes all parenthesized text from a buffer. The text may span several lines. It does not handle multiple levels of parentheses.
#2

PROCEDURE user_remove_paren_text (paren_buffer) 
 
   LOCAL pat1, 
         paren_text, 
         searched_text; 
 
   pat1 := "(" + UNANCHOR + ")"; 
   searched_text := paren_buffer; 
   LOOP 
      paren_text := SEARCH_QUIETLY (pat1, FORWARD, EXACT, 
                                   searched_text); 
      EXITIF paren_text = 0; 
      ERASE (paren_text); 
      searched_text := CREATE_RANGE (END_OF (paren_text), 
                                    END_OF (paren_buffer), NONE); 
  ENDLOOP; 
ENDPROCEDURE; 
 
      


UNDEFINE_KEY


Format

UNDEFINE_KEY (keyword [[, {key-map-list-name|key-map-name}]])


Parameters

keyword

The name of a key or key combination that you can define. See the Guide to the DEC Text Processing Utility for a list of the valid DECTPU key names.

key-map-list-name

Specifies a key map list in which the key is defined. The first definition of the key in the key maps that make up the key map list is deleted. If neither a key map nor a key map list is specified, the key map list bound to the current buffer is used.

key-map-name

Specifies a key map in which the key is defined. The first definition of the key in the key map is deleted. If neither a key map nor a key map list is specified, the key map list bound to the current buffer is used.

Description

The UNDEFINE_KEY procedure removes the current binding from the key that you specify. After you use UNDEFINE_KEY, the key you specify is no longer defined. DECTPU does not save any previous definitions that you may have associated with the key. However, any definitions of the specified key in key maps or key map lists other than the ones you specified are not removed.

DECTPU writes a message to the message buffer telling you that the key is undefined if you try to use it after you have undefined it.

Signaled Errors

TPU$_NODEFINITION WARNING There is no definition for this key.
TPU$_NOTDEFINABLE WARNING First argument is not a valid reference to a key.
TPU$_NOKEYMAP WARNING Second argument is not a defined key map.
TPU$_NOKEYMAPLIST WARNING Second argument is not a defined key map list.
TPU$_KEYMAPNTFND WARNING The key map listed in the second argument is not found.
TPU$_EMPTYKMLIST WARNING The key map list specified in the second argument contains no key maps.
TPU$_TOOFEW ERROR Too few arguments passed to the UNDEFINE_KEY built-in.
TPU$_TOOMANY ERROR Too many arguments passed to the UNDEFINE_KEY built-in.
TPU$_INVPARAM ERROR Wrong type of data sent to the UNDEFINE_KEY built-in.

Examples

The following example undefines a key. You can use this kind of procedure for keypad initialization procedures.
#1

! Parameters: 
! 
!     Name         Function                   Input or Output? 
!     ----         --------                   ---------------- 
!     which_key    Keyword for key to clear     input 
 
PROCEDURE user_clear_key (which_key) 
 
   IF (LOOKUP_KEY (which_key, PROGRAM) <> 0) 
   THEN 
       UNDEFINE_KEY (which_key); 
   ELSE 
       MESSAGE ("Key not defined"); 
   ENDIF; 
ENDPROCEDURE; 
 
      

The following example deletes all of the key definitions in the key map TPU$KEY_MAP:

#2

PROCEDURE delete_all_definitions 
 
   LOCAL key; 
 
 
   LOOP 
      key := GET_INFO (DEFINED_KEY, "first", "tpu$key_map"); 
      EXITIF key = 0; 
      UNDEFINE_KEY (key, "tpu$key_map"); 
   ENDLOOP; 
ENDPROCEDURE; 
 
      


UNMANAGE_WIDGET


Format

UNMANAGE_WIDGET (widget [[, widget... ]])


Parameter

widget

The widget to be unmanaged.

Description

The UNMANAGE_WIDGET procedure makes the specified widget and all of its children invisible. If you want to unmanage several widgets that are children of the same parent, but you do not want to unmanage the parent, include all the children in a single call to UNMANAGE_WIDGET. Unmanaging several widgets at once is more efficient than unmanaging one widget at a time.

Signaled Errors

TPU$_INVPARAM ERROR You specified a parameter of the wrong type.
TPU$_TOOFEW ERROR Too few arguments passed to the UNMANAGE_WIDGET built-in.
TPU$_NORETURNVALUE ERROR UNMANAGE_WIDGET cannot return a value.
TPU$_REQUIRESDECW ERROR You can use the UNMANAGE_WIDGET built-in only if you are using DECwindows DECTPU.
TPU$_WIDMISMATCH ERROR You have specified a widget whose class is not supported.

Example

The following example removes EVE's FIND dialog box from the screen:

UNMANAGE_WIDGET (eve$x_find_dialog); 
 
      


UNMAP


Format

UNMAP ({widget|window})


Parameters

widget

The widget you want to make invisible.

window

The window you want to remove from the screen.

Description

The UNMAP procedure disassociates a window from its buffer and removes the window or widget from the screen. If you unmap the current window, DECTPU tries to move the cursor position to the window that was most recently the current window. The window in which DECTPU positions the cursor becomes the current window, and the buffer that is associated with this window becomes the current buffer.

The screen area of the window you unmap is either erased or returned to any windows that were occluded by the window you unmapped. DECTPU returns lines to adjacent windows if the size of the windows requires the lines that were used for the window you unmap. The size of a window is determined by the values you specified for the CREATE_WINDOW built-in procedure when you created the window, or by the values you specified for the ADJUST_WINDOW built-in procedure if you changed the size of the window. If adjacent windows do not require the lines that were used by the window you unmap, the lines that the window occupied on the screen remain blank.

The window that you unmap is not deleted from the list of available windows. You can cause the window to appear on the screen again with MAP. UNMAP does not have any effect on the buffer that was associated with the window being unmapped.

Unmapping a widget does not delete the widget. Future MAP operations will make the widget visible again.

Signaled Errors

TPU$_TOOFEW ERROR UNMAP requires one parameter.
TPU$_TOOMANY ERROR UNMAP accepts only one parameter.
TPU$_INVPARAM ERROR One or more of the specified parameters have the wrong type.
TPU$_WINDNOTMAPPED WARNING Window is not mapped to a buffer.

Examples

The following example removes the main window from the screen and disassociates from the main window the buffer that was mapped to it:
#1

UNMAP (main_window) 
 
      

The following example unmaps the current window and puts two new windows in its place. (If the window that you are replacing has a status line, this line is not included in the screen area used by the two new windows. This is because GET_INFO (window, "visible_bottom") does not take the status line into account.)

#2

PROCEDURE user_one_window_to_two 
 
   LOCAL wind_length, 
         wind_half, 
         first_line, 
        last_line; 
 
   cur_wind := CURRENT_WINDOW; 
 
! If it exists 
   IF (cur_wind <> 0) 
   THEN 
       first_line := GET_INFO (cur_wind, "visible_top"); 
       last_line := GET_INFO (cur_wind, "visible_bottom"); 
       wind_buf := GET_INFO (cur_wind, "buffer"); 
       UNMAP (cur_wind); 
   ELSE 
! If there is no current window then create an empty buffer 
 
       first_line := 1; 
       last_line := GET_INFO (SCREEN, "visible_length"); 
       wind_buf := CREATE_BUFFER ("Empty Buffer"); 
    ENDIF; 
 
   wind_length := (last_line - first_line) + 1; 
   wind_half := wind_length/2; 
   new_window_1 := CREATE_WINDOW (first_line, wind_half, OFF); 
 
   SET (VIDEO, new_window_1, UNDERLINE); 
   new_window_2 := CREATE_WINDOW (wind_half+1, 
                   last_line-wind_half, OFF); 
 
! Associate the same buffer with both windows 
! and map the windows to the screen 
 
   MAP (new_window_1, wind_buf); 
   MAP (new_window_2, wind_buf); 
ENDPROCEDURE; 
      


UPDATE


Format

UPDATE ({ALL|window})


Parameters

ALL

A keyword that directs DECTPU to make all visible windows reflect the current state of the buffers mapped to them.

window

The window that you want updated. The window must be mapped to the screen for the update to occur.

Description

The UPDATE procedure causes the screen manager to make a window reflect the current internal state of the buffer that is associated with the window. One important task that UPDATE performs is to move the cursor to the editing point if the cursor and the editing point are not synchronized when the UPDATE built-in procedure is executed.

The screen manager updates windows after each keystroke. However, if a key has a procedure bound to it, DECTPU may execute many statements when that key is pressed. By default, UPDATE does not reflect the result of any statement in a procedure bound to a key until all the statements in the procedure have been executed. As a result, the screen may not reflect the current state of the buffer during execution of a procedure bound to a key. If you want the screen to reflect changes before the entire procedure is executed, you can force an immediate update by adding an UPDATE statement to the procedure.

UPDATE (window) affects a single window that is visible on the screen. If the buffer associated with the window you use as a parameter is associated with other windows that are mapped to the screen, all of these windows may be updated.

UPDATE (ALL) updates all visible windows. The difference between the UPDATE (ALL) built-in procedure and the REFRESH built-in procedure is that UPDATE (ALL) makes whatever changes are necessary on a window-by-window basis. REFRESH clears the screen and repaints everything from scratch, as well as reinitializing scrolling regions and other terminal-dependent settings.

For more information on how the DECTPU screen manager uses the UPDATE built-in in various circumstances, see Appendix C. For more information on the results of the REFRESH built-in, see the description of REFRESH in this chapter.

Signaled Errors

TPU$_TOOFEW ERROR UPDATE requires one parameter.
TPU$_TOOMANY ERROR You specified more than one parameter.
TPU$_INVPCARAM ERROR The specified parameter has the wrong type.
TPU$_BADKEY ERROR The keyword must be ALL.
TPU$_UNKKEYWORD ERROR You specified an unknown keyword.
TPU$_WINDNOTMAPPED WARNING You cannot update a window that is not on the screen.

Examples

The following example causes the screen manager to make new_window reflect the current internal state of the buffer associated with new_window:
#1

UPDATE (new_window) 
 
      

The following example updates the screen to display the new line of text that you are inserting before the top line of the window. (When you insert text in front of the top of a window, the included text is not visible on the screen unless you use a procedure such as this one to ensure that the text is displayed.)

#2

PROCEDURE user_show_first_line 
 
   LOCAL old_position,         ! Marker of position before scroll 
         new_position;         ! Marker of position after scroll 
 
   UPDATE (CURRENT_WINDOW); 
   IF (GET_INFO (CURRENT_WINDOW, "current_row") = 
      GET_INFO (CURRENT_WINDOW, "visible_top")) 
      AND 
         (CURRENT_COLUMN = 1) 
   THEN 
       old_position := MARK (NONE); 
       SCROLL (CURRENT_WINDOW, -1); 
       new_position := MARK (NONE); 
 
! Make sure we scrolled before doing the CURSOR_VERTICAL 
 
      IF new_position <> old_position 
      THEN 
          CURSOR_VERTICAL (1); 
      ENDIF; 
   ENDIF; 
ENDPROCEDURE; 
      


WRITE_CLIPBOARD


Format

WRITE_CLIPBOARD ( clipboard_label, {buffer |range |string})


Parameters

clipboard_label

The label for multiple entries in the clipboard. Because the clipboard does not currently support multiple labels, use any string, including the null string, to specify this parameter.

buffer

The buffer that contains text to be written to the clipboard. DECTPU represents line breaks by a line-feed character (ASCII (10)). If you specify a buffer, DECTPU converts the buffer to a string, replacing line breaks with line feeds and replacing the white space before the left margin with padding blanks.

The buffer must contain at least one character or line break. If it does not, DECTPU signals TPU$_CLIPBOARDZERO.

range

The range that contains text to be written to the clipboard. DECTPU represents line breaks by a line-feed character (ASCII (10)). If you specify a range, DECTPU converts the range to a string, replacing line breaks with line feeds and replacing the white space before the left margin with padding blanks.

The range must contain at least one character or line break. If it does not, DECTPU signals TPU$_CLIPBOARDZERO.

string

The string that contains text to be written to the clipboard. The string must contain at least one character. If it does not, DECTPU signals TPU$_CLIPBOARDZERO.

Description

The WRITE_CLIPBOARD procedure writes string format data to the clipboard. The clipboard_label parameter provides support for multiple entries on the clipboard; at present, however, the clipboard does not support multiple entries.

Signaled Errors

TPU$_CLIPBOARDLOCKED WARNING The clipboard is locked by another process.
TPU$_CLIPBOARDZERO WARNING The data to be written to the clipboard have zero length.
TPU$_TRUNCATE WARNING DECTPU has truncated characters from the data written because you specified a buffer or range that contains more than 65535 characters.
TPU$_INVPARAM ERROR One of the parameters was specified with data of the wrong type.
TPU$_NORETURNVALUE ERROR WRITE_CLIPBOARD cannot return a value.
TPU$_REQUIRESDECW ERROR You can use the WRITE_CLIPBOARD built-in only if you are using DECwindows DECTPU.
TPU$_TOOFEW ERROR Too few arguments passed to the WRITE_CLIPBOARD built-in.
TPU$_TOOMANY ERROR Too many arguments passed to the WRITE_CLIPBOARD built-in.

Example

The following example writes the contents of the range this_range to the clipboard:

WRITE_CLIPBOARD ("", this_range); 
 
      


WRITE_FILE


Format

[[string2 := ]] WRITE_FILE ( {buffer|range} [[,string1 ]] [[, {ON |OFF |1 |0} ]])


Parameters

buffer

The buffer whose contents you want to write to a file.

range

The range whose contents you want to write to a file.

If you use WRITE_FILE on a range that does not start at the left margin of a line, DECTPU does the following:

For example, if you write a range that starts in column 30 of a line whose left margin is 10, WRITE_FILE writes the range in the output file starting at column 10.

string1

A string that specifies the file to which the contents of the buffer are to be written. If you do not specify a full file specification, DECTPU determines the output file specification by using the current device and directory as defaults. The string is case insensitive.

This parameter is optional. If you omit it, DECTPU uses the associated output file name for the buffer. If there is no associated file name, DECTPU prompts you for one. If you do not give a file name at the prompt, DECTPU does not write to a file. In that case, the optional string2 that is returned is a null string.

ON

A keyword specifying that output is padded with spaces to keep the first character of each record at the same column as the text in the buffer. This is the default.

OFF

A keyword specifying that no padding spaces are inserted when writing to the file.

Return Value


A string that represents the file specification of the file created.

Description

The WRITE_FILE procedure writes data to the file that you specify. WRITE_FILE optionally returns a string that is the file specification of the file created. If you specify a result, WRITE_FILE returns a string that is the file specification of the file to which the data was written.

DECTPU uses a flag to mark a buffer as modified or not modified. When you write data from a buffer to an external file, DECTPU clears the modified flag for that buffer. If you do not make any further modifications to that buffer, DECTPU does not consider the buffer as being modified and does not write out the file by default when you exit. If an error occurs while DECTPU is writing a file, DECTPU does not clear the modified flag.

When the contents of a buffer are written to a file, the associated journal file (if any) is closed and deleted and a new journal file is created. The new file contains the name of the file to which the buffer was written.

Deleting the file that has been written out invalidates the buffer-change journal.

Signaled Errors

TPU$_CONTROLC ERROR The execution of the write operation terminated because you pressed Ctrl/C.
TPU$_TOOFEW ERROR WRITE_FILE requires at least one parameter.
TPU$_TOOMANY ERROR WRITE_FILE accepts no more than two parameters.
TPU$_ARGMISMATCH ERROR One of the parameters to WRITE_FILE is of the wrong type.
TPU$_INVPARAM ERROR One of the parameters to WRITE_FILE is of the wrong type.

DECTPU's file I/O routine can signal the following completion codes. You can provide your own file I/O routine by using the DECTPU callable interface. If you do so, WRITE_FILE's completion status depends upon what status you signaled in your file I/O routine.
TPU$_OPENOUT ERROR WRITE_FILE could not create the output file.
TPU$_NOFILEACCESS ERROR WRITE_FILE could not connect to the newly created output file.
TPU$_WRITEERR ERROR WRITE_FILE could not write the text to the file because it encountered a file system error during the operation.
TPU$_CLOSEOUT ERROR WRITE_FILE encountered a file system error when closing the file.

Examples

The following example writes the contents of the paste buffer to the file named MYFILE.TXT:
#1

WRITE_FILE (paste_buffer, "myfile.txt") 
 
      

The following example writes the contents of a buffer called extra_buf to a file. (Because you do not specify a file name, the associated file for the buffer is used.) The procedure then removes the extra window and buffer from your editing context.

#2

PROCEDURE user_write_file 
 
   WRITE_FILE (extra_buf); 
   DELETE (extra_window); 
   DELETE (extra_buf); 
 
! Return the lines from extra_window to the main window 
 
   ADJUST_WINDOW (main_window, -11, 0); 
 
ENDPROCEDURE; 
 
      


WRITE_GLOBAL_SELECT


Format

WRITE_GLOBAL_SELECT ( {array |buffer |integer |range |string |NONE})


Parameters

array

An array that passes information about a global selection whose contents describe information that is not of a data type supported by DECTPU. For example, the array could pass information about a pixmap, an icon, or a span.

DECTPU does not use or alter the information in the array; the application layered on DECTPU is responsible for determining how the information is used, if at all. Because the array is used to pass information to and from other DECwindows applications, all applications that send or receive information whose data type is not supported by DECTPU must agree on how the information is to be sent and used.

The application sending the information is responsible for creating the array and giving it the proper structure. The array's structure is as follows:

buffer

The buffer that contains the information to be sent to the requesting application as the response to the global selection information request. If you specify a buffer, DECTPU converts the buffer to a string, converts line breaks to line feeds, and inserts padding blanks before text to fill any unoccupied space before the left margin.

integer

An integer whose value is to be sent to the requesting application as the response to the global selection information request. DECTPU sends the information in integer format.

range

The range that contains the information to be sent to the requesting application as the response to the global selection information request. If you specify a range, DECTPU converts the buffer to a string, converts line breaks to line feeds, and inserts padding blanks before and after text to fill any unoccupied space before the left margin.

string

The string that contains the information to be sent to the requesting application as the response to the global selection information request. DECTPU sends the information in string format.

NONE

A keyword indicating that no information about the global selection is available.

Description

The WRITE_GLOBAL_SELECT procedure sends requested information about a global selection from the DECTPU layered application to the application that issued the information request. WRITE_GLOBAL_SELECT is valid only inside a routine that responds to requests for information about a global selection.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6020PRO_038.HTML