Document revision date: 19 July 1999

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;

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

Examples

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

! 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:

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; 
 
      

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

Example

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

UNMANAGE_WIDGET (eve$x_find_dialog); 
 
      

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

Examples

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

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.)

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; 
      

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

Examples

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

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.)

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; 
      

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

Example

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

WRITE_CLIPBOARD ("", this_range); 
 
      

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:

• Determines the left margin of the line in which the range starts
• Writes the range to the output file starting at the same left margin as the margin of the line where the range starts

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

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

Examples

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

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.

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; 
 
      

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:

• The element array {0} contains a string naming the data type of the information being passed. For example, if the information being passed is a span, the element contains the string "SPAN".
• The element array {1} contains either the integer 8, indicating that the information is passed as a series of bytes, or the integer 32, indicating that the information is passed as a series of longwords.
• If array {1} contains the value 8, the element array {2} contains a string, and there are no array elements after array {2}. The string does not name anything; rather it is a series of bytes. The meaning and use of the information is agreed upon by convention among the DECwindows applications.
• If array {1} contains the value 32, the remaining elements of the array contain integer data. In this case, the array can have any number of elements after array {2}. These elements must be numbered sequentially, starting at array {3}. All the elements contain integers. Each integer represents a longword of data. To determine how many longwords are being passed, an application can determine the length of the array and subtract 2 to allow for elements array {0} and array {1}.

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

	privacy and legal statement
6020PRO_038.HTML