Document revision date: 30 March 2001

The following example returns the comment associated with a particular key:

#2
PROCEDURE user_get_key_info LOCAL key_to_interpret, key_info; MESSAGE ("Press the key you want information on: "); key_to_interpret := READ_KEY; key_info := LOOKUP_KEY (key_to_interpret, COMMENT); IF key_info <> "" THEN MESSAGE ("Comment: " + key_info); ELSE MESSAGE ("No comment is associated with that key."); ENDIF; ENDPROCEDURE;

The following example implements multiple shift keys:

PROCEDURE shift_key_handler (key_map_list_name); 
 
   LOCAL bound_program; 
 
   bound_program := LOOKUP_KEY (READ_KEY, PROGRAM, "key_map_list_name"); 
 
   IF bound_program <> 0 
   THEN 
      EXECUTE (bound_program); 
   ELSE 
      MESSAGE ("Attempt to execute undefined key"); 
   ENDIF; 
ENDPROCEDURE; 
 
red_keys := CREATE_KEY_MAP ("red_keys"); 
 
red_key_map_list := CREATE_KEY_MAP_LIST ("red_key_map_list", 
                    red_keys); 
DEFINE_KEY ("shift_key_handler (red_key_map_list)", PF3, 
           "RED shift key"); 
      

Format

LOWER_WIDGET (widget)

Parameter

widget

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

Description

The LOWER_WIDGET procedure places the widget at the bottom of a viewing stack. This prevents the widget window associated with the widget from obscuring any sibling windows. LOWER_WIDGET calls the XLIB routine XLowerWindow.

Signaled Errors

Format

MANAGE_WIDGET (widget [[, widget... ]])

Parameter

widget

The widget to be managed.

Description

The MANAGE_WIDGET procedure makes the specified widget or widgets visible, provided that their parent widget is also visible.

MANAGE_WIDGET allows the specified widget's parent to allocate space for the widget by laying out all its children for display. The parent ignores unmanaged children so that they do not take up space on the screen. If the parent widget is realized, and the specified widget's mappedWhenManaged resource is true (the default), then the widget becomes visible on the screen.

If you have multiple children of a single widget that you want to manage, include them in a single call to MANAGE_WIDGET. Managing several widgets at once is more efficient than managing one widget at a time.

All widgets passed in the same MANAGE_WIDGET operation must have the same parent.

Signaled Errors

Example

For a sample procedure using the MANAGE_WIDGET built-in procedure, see Example A-1.

Format

MAP ({window, buffer |widget})

Parameters

window

The window you want to map to the screen.

buffer

The buffer you want to associate with the window.

widget

The widget you want to make visible.

Description

The MAP procedure associates a buffer with a window and causes the window or widget to become visible on the screen. Before using MAP, you must already have created the widget, buffer, and window that you specify as parameters. See CREATE_WIDGET, CREATE_BUFFER, and CREATE_WINDOW.

The window and buffer that you use as parameters become the current window and the current buffer, respectively. The map operation synchronizes the cursor position with the editing point in the buffer. If the window is not already mapped to the buffer when you use MAP, DECTPU puts the cursor back in the last position the cursor occupied the last time the window was the current window.

MAP may cause other windows that are mapped to the screen to be partially or completely occluded. If MAP causes the new window to segment another window into two pieces, only the upper part of the segmented window remains visible and continues to be updated. The lower part of the segmented window is erased on the next screen update. If you remove the window that is segmenting another window, DECTPU repaints the screen so that the window that was segmented regains its original size and position on the screen.

In DECwindows, MAP also maps the DECTPU main widget if it has not already been mapped.

If you execute MAP within a procedure, the screen is not updated to reflect such operations as window repainting, line erasure, or new mapping until the procedure has finished executing and control has returned to the screen manager. If you want the screen to reflect the changes before the entire program is executed, you can force the immediate update of a window by including the following statement in the procedure before any statements containing the MAP built-in:

UPDATE(WINDOW);

Signaled Errors

Examples

The following example associates the main buffer with the main window and maps the main window to the screen. You must have established the main buffer and the main window with CREATE_BUFFER and CREATE_WINDOW before you can use them as parameters for MAP.

MAP (main_window, main_buffer) 
      

The following example creates a message buffer and a message window. It then associates the message buffer with the message window and maps the message window to the screen.

PROCEDURE user_message_window 
 
   message_buffer := CREATE_BUFFER ("message"); 
   SET (EOB_TEXT, message_buffer, ""); 
   SET (NO_WRITE, message_buffer); 
   SET (SYSTEM, message_buffer); 
 
   message_window := CREATE_WINDOW (23, 2, OFF); 
   SET (VIDEO, message_window, NONE); 
   MAP (message_window, message_buffer); 
ENDPROCEDURE; 
 
      

Format

marker := MARK ( {BLINK |BOLD |FREE_CURSOR |REVERSE |UNDERLINE |NONE}) [[, {buffer |window} [[, integer1 [[, integer2 ]] ]] ]]

Parameters

BLINK

A keyword that directs DECTPU to display the marker in blinking rendition.

BOLD

A keyword that directs DECTPU to display the marker in bold rendition.

FREE_CURSOR

A keyword that directs DECTPU to create a free marker (that is, a marker not bound to a character). A free marker has no video attribute.

REVERSE

A keyword that directs DECTPU to display the marker in reverse video.

UNDERLINE

A keyword that directs DECTPU to underline the marker.

NONE

A keyword that directs DECTPU to apply no video attributes to the marker.

buffer

The buffer in which the marker is to be located. By default, DECTPU locates markers in the current buffer.

window

The window that is mapped to the buffer in which the marker is to be located. You can specify a window variable only if the window is mapped to a buffer. By default, DECTPU locates markers in the current buffer.

integer1

An integer for the screen column where the marker is to be located. You can specify an integer from 1 to 32767. However, if you specify an integer smaller than the record's left margin or larger than the end of the record, DECTPU inserts padding spaces between the marker and the nearest text. The default is to locate the marker at the buffer offset that corresponds to the current screen column.

integer2

An integer for the record in the buffer where the marker is to be located. You can specify any integer greater than 1 but less than the maximum number of lines in the buffer, if it has been set with the SET (MAX_LINES) built-in procedure. The default is to locate the marker in the current record.

Return Value

Description

The MARK procedure returns a marker for a specified location in a buffer. You must specify how the marker is to be displayed on the screen (no special video, reverse video, bolded, blinking, or underlined). You can use MARK to establish placeholders or "bookmarks."

A marker can be either bound or free. For more information on how these markers differ, see the Guide to the DEC Text Processing Utility.

To create a bound marker, use the MARK built-in procedure with any of its parameters except FREE_CURSOR. This operation creates a bound marker even if the editing point is beyond the end of a line, before the beginning of a line, in the middle of a tab, or beyond the end of a buffer. To create a bound cursor in a location where there is no character, DECTPU fills the space between the marker and the nearest character with padding space characters.

A bound marker is tied to the character at which it is created. If the character tied to the marker moves, the marker moves also. If the character tied to the marker is deleted, the marker moves to the nearest character position. The nearest character position is determined in the following ways:

• If there is a character position on the same line and to the right, the marker moves to this position, even if the position is at the end of the line.
• If the line on which the marker is located is deleted, the marker moves to the first position on the following line.

You can move one column past the last character in a line and place a marker there. However, the video attribute for the marker is not visible unless a subsequent operation puts a character under the marker.

If you use a marker at the end of a line as part of a range, the end of line is included in the range even though the marker is not positioned on a character.

A marker is free if the following conditions are true:

• You used the FREE_CURSOR keyword to create the marker.
• There was no character in the position where you created the marker.

DECTPU keeps track of the location of a free marker by measuring the distance between the marker and the character nearest to the marker. If you move the character from which DECTPU measures distance to a free marker, the marker moves too. DECTPU preserves a uniform distance between the character and the marker. If you collapse white space that contains one or more free markers (for example, if you delete a tab or use the APPEND_LINE built-in procedure), DECTPU preserves the markers and binds them to the nearest character.

Unless you specify the parameter FREE_CURSOR, using the MARK built-in may result in the insertion of padding spaces or lines into the buffer if the new marker is one of the following:

• Before the beginning of a line
• In the middle of a tab

• Beyond the end of a line
• After the last line in the buffer

Signaled Errors

Examples

The following example places a marker at the editing point. There are no video attributes applied to the marker.

user_mark := MARK (NONE) 
 
      

The following example marks a temporary position at the current character position, and then goes to the paste buffer and creates a range of the contents of the paste buffer. DECTPU then goes to temp_pos and copies the text from the paste buffer at the temporary position.

PROCEDURE user_paste 
 
   temp_pos := MARK (NONE); 
 
   POSITION (END_OF (paste_buffer)); 
   MOVE_HORIZONTAL (-2); 
 
   paste_text := CREATE_RANGE (BEGINNING_OF (paste_buffer), 
                 MARK (NONE), NONE); 
   POSITION (temp_pos); 
   COPY_TEXT (paste_text); 
ENDPROCEDURE; 
      

Format

pattern := MATCH ( {buffer |range |string})

Parameters

buffer

An expression that evaluates to a buffer. MATCH forms a string from the contents of the buffer and stops matching when it finds the resulting string.

range

An expression that evaluates to a range. MATCH forms a string from the contents of the range and stops matching when it finds the resulting string.

string

An expression that evaluates to a string. MATCH stops matching when it finds this string.

Return Value

Description

The MATCH procedure returns a pattern that matches from the editing point up to and including the sequence of characters specified in the parameter. The matched string does not contain line terminators.

Signaled Errors

Examples

The following example stores in pat1 a pattern that matches a string of characters starting with the editing point up to and including the characters "abc":

pat1 := MATCH ("abc") 
 
      

The following example finds text within double parentheses. It moves the editing point to the beginning of the parenthesized text, if it is found.

PROCEDURE user_double_parens 
 
   paren_text    := "((" + MATCH ('))'); 
   found_range   := SEARCH_QUIETLY (paren_text, FORWARD, NO_EXACT); 
 
   IF found_range = 0   ! No match 
   THEN 
       MESSAGE  ("No match found."); 
   ELSE 
       POSITION (found_range); 
   ENDIF; 
ENDPROCEDURE; 
      

Formats

MESSAGE ( {buffer |range} [[, integer1 ]])

MESSAGE ( {integer2 |keyword |string |buffer} [[, integer3
[[, FAO-parameter [[, FAO-parameters... ]] ]] ]])

Parameters

buffer

The buffer that contains the text that you want to include in the message buffer.

range

The range that contains the text that you want to include in the message buffer.

integer1

An integer that indicates the severity of the message placed in the message buffer. If you do not specify this parameter, no severity code is associated with the message. The allowable integer values and their meanings are as follows:

Integer	Meaning
0	Warning
1	Success
2	Error
3	Informational

integer2

The integer that represents the message code associated with the text to be fetched.

keyword

The DECTPU keyword that represents the message code associated with the text to be fetched. DECTPU provides keywords for all of the message codes used by DECTPU and EVE.

string

Either a quoted string or a variable that represents the text you want to include in the message buffer.

integer3

A bit-encoded integer that specifies what fields of the message text associated with the message code from the first parameter are to be fetched. If the message flags are not specified or the value is 0, then the message flags set by the SET (MESSAGE_FLAGS) built-in procedure are used.

Table 2-7 shows the message flags.

Table 2-7 Message Flag Values for MESSAGE

Bit	Constant	Meaning
0	TPU$K_MESSAGE_TEXT	Include text of message.
1	TPU$K_MESSAGE_ID	Include message identifier.
2	TPU$K_MESSAGE_SEVERITY	Include severity level indicator.
3	TPU$K_MESSAGE_FACILITY	Include facility name.

FAO-parameter

One or more expressions that evaluate to an integer or string. The MESSAGE_TEXT built-in procedure uses these integers and strings as arguments to the $FAO system service, substituting the values into the text associated with the message code to form the resultant string.

The FAO directives are listed in the description of $FAO in the OpenVMS System Services Reference Manual.

Description

The MESSAGE procedure, depending on the format you choose, either puts the characters that you specify into the message buffer or else fetches text associated with a message code, formats the text using FAO directives, and puts it in the message buffer.

If you use the first format, MESSAGE inserts the characters in the string, range, or buffer that you specify into the message buffer, if one exists. (By default, DECTPU looks for a buffer variable that is named MESSAGE_BUFFER.) If there is no message buffer, DECTPU displays the message at the current location on the device pointed to by SYS$OUTPUT (usually your terminal).

If you use the first format, MESSAGE provides the user who is writing an editing interface with a method for displaying messages in a way that is consistent with the DECTPU language.

If you use the second format, MESSAGE fetches the text associated with a message code, uses FAO directives to format the text, and displays the formatted message in the message buffer. (If there is no message buffer, DECTPU displays the message on SYS$OUTPUT (usually your terminal).)

If you use the second format, MESSAGE writes a formatted string in the message buffer. The difference between MESSAGE and MESSAGE_TEXT is that MESSAGE_TEXT returns the resulting string while MESSAGE places the resulting string in the message buffer. The string is specified by the message code passed as the first parameter and constructed according to the rules of the $FAO system service. The control string associated with the message code directs the formatting process, and the optional arguments are values to be substituted into the control string.

MESSAGE accepts up to 127 parameters. This built-in can return strings of 65535 characters maximum.

If you have associated a message buffer with a message window, and if the message window is mapped to the screen, the range you specify appears immediately in the message window on the screen.

If you have not associated a message buffer with a message window, messages are written to the buffer but do not appear on the screen.

MESSAGE capitalizes the first character of the string placed in the message buffer. The MESSAGE_TEXT built-in procedure, on the other hand, does not capitalize the first character of the returned string.

You can include the following FAO directives as part of the message text:

!AS	Inserts a string as is
!OL	Converts an integer to octal notation
!XL	Converts an integer to hexadecimal notation
!ZL	Converts an integer to decimal notation
!UL	Converts an integer to decimal notation without adjusting for negative numbers
!SL	Converts an integer to decimal notation with negative numbers converted
!/	Inserts a new line character (carriage return/line feed)
!_	Inserts a tab
!}	Inserts a form feed
!!	Inserts an exclamation point
!%S	Inserts an s if the most recently converted number is not 1
!%T	Inserts the current time if you enter 0 as the parameter (you cannot pass a specific time because DECTPU does not use quadwords)
!%D	Inserts the current date and time if you enter 0 as the parameter (you cannot pass a specific date because DECTPU does not use quadwords)

Signaled Errors

Examples

The following example writes the text "Hello" in the message area:

MESSAGE ("Hello") 
      

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_018.HTML