Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

## SET (SCREEN_UPDATE)

### Format

> [[ {ON|OFF} := ]] SET (SCREEN_UPDATE, {ON |OFF |1 |0} [[, window_variable ]])

### Parameters

> #### SCREEN_UPDATE

> A keyword that directs DECTPU to set an attribute of screen updating.

> #### ON, 1

> A keyword that indicates that screen updating is enabled.

> #### OFF, 0

> A keyword that indicates that screen updating is disabled.

> #### window_variable

> The window for which you want screen updating turned on or off. Windows are set to update by default.

> If you set a window to "no update," the screen updater ignores the window. Applications that modify part of the screen through some external means may map a "no-update" window to that portion or portions of the screen to prevent DECTPU from overwriting the screen. EVE does not support the use of "no-update" windows.

### Return Value

A variable that contains the keyword value ON or OFF. The keyword specifies whether DECTPU screen updating support was enabled or disabled before the current SET (SCREEN_UPDATE) statement was executed. Using the returned variable, you can enable or disable screen updating and then reset the support to its previous setting without having to make a separate call to fetch the previous setting.

### Description

> The SET (SCREEN_UPDATE) procedure turns on or turns off support for screen updating. When you set SCREEN_UPDATE on, the screen manager is immediately called to update the screen. The extent of the update depends on the built-ins that have been used since the last screen update. The update may range from a complete screen refresh to an updating of the existing text on the screen.

> For more information on screen updating, see the Guide to the DEC Text Processing Utility.

#### Signaled Errors

TPU$_BADKEY | WARNING | The keyword must be ON or OFF.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_TOOFEW | ERROR | SET (SCREEN_UPDATE) requires two parameters.
TPU$_TOOMANY | ERROR | You specified more than two parameters.
TPU$_UNKKEYWORD | ERROR | You have specified an unknown keyword.

### Example

> The following example causes screen updating to be turned off. When you design an editing interface, you can use this statement to prevent some intermediate processing steps from appearing on the screen.

    SET (SCREEN_UPDATE, OFF)

## SET (SCROLL_BAR)

### Format

> [[ {integer|widget} := ]] SET (SCROLL_BAR, window, {HORIZONTAL |VERTICAL}, {ON |OFF |1 |0})

### Parameters

> #### SCROLL_BAR

> A keyword that directs DECTPU to enable or disable a scroll bar in a DECTPU window.

> #### window

> The window in which the scroll bar does or does not appear.

> #### HORIZONTAL

> A keyword that directs DECTPU to enable or disable a horizontal scroll bar.

> #### VERTICAL

> A keyword that directs DECTPU to enable or disable a vertical scroll bar.

> #### ON, 1

> A keyword that indicates that the scroll bar is to be visible in the specified window.

> #### OFF, 0

> A keyword that indicates that the scroll bar is not to be visible in the specified window.

### Return Values

> #### integer

> The value 0 if an error prevents DECTPU from associating a widget with the window.

> #### widget

> The widget that implements the vertical or horizontal scroll bar associated with a window.

### Description

> The SET (SCROLL_BAR) procedure enables a horizontal or vertical scroll bar for the specified window. Scroll bars represent the location of the editing point in the buffer. By dragging the scroll bar's slider, you can reposition the editing point in the buffer mapped to the window.

> Scroll bars are unique among DECTPU widgets in the following respects:

> - Each scroll bar widget is associated with a specific DECTPU window.
> - Instead of handling scroll widgets at the application level, you can direct DECTPU to handle resizing and repositioning of the scroll bar slider. DECTPU always handles sizing and positioning of the scroll bar itself.

> Windows having fewer than four lines of text cannot display a vertical scroll bar. Similarly, a window less than four columns wide cannot display a horizontal scroll bar. When the size of a DECTPU window changes, DECTPU automatically adjusts the scroll bar to fit the new window size. If a window becomes too small to support a scroll bar, DECTPU turns off the scroll bar. However, if the window subsequently becomes larger, DECTPU automatically turns the scroll bar back on.

> SET (SCROLL_BAR) returns the scroll bar widget, or 0 if an error prevents DECTPU from associating a widget with the window.

> By default, DECTPU creates its windows without any scroll bars; using SET (SCROLL_BAR) with the ON keyword overrides the default. To make a scroll bar invisible after it has been placed in a window (for example, to allow the user of a layered application to turn off scroll bars), use SET (SCROLL_BAR) with the OFF keyword.

> The height of a vertical scroll bar represents the total number of lines in the buffer mapped to the window.

> The width of a horizontal scroll bar represents the greater of the following:

> - The width of the widest line in the set of lines visible in the window. "Width" means the distance from the first character on the line to the last character, regardless of whether all characters on the line are visible.
> - The width of the widest line from the first character on the line to the rightmost window column, when none of the lines in the set of lines visible in the window has text extending all the way to the rightmost window column.

> The horizontal scroll bar represents only the lines that are visible in the window, not all the lines in the buffer mapped to the window.

#### Signaled Errors

TPU$_BADKEY | WARNING | You specified an invalid keyword as a parameter.
TPU$_INVPARAM | ERROR | One of the parameters was specified with data of the wrong type.
TPU$_REQUIRESDECW | ERROR | You can use the SET (SCROLL_BAR) built-in only if you are using DECwindows DECTPU.
TPU$_TOOFEW | ERROR | Too few arguments passed to the SET (SCROLL_BAR) built-in.
TPU$_TOOMANY | ERROR | Too many arguments passed to the SET (SCROLL_BAR) built-in.

### Example

> The following example turns on a vertical scroll bar in the current window:

    vertical_bar := SET (SCROLL_BAR, CURRENT_WINDOW, VERTICAL, ON);

## SET (SCROLL_BAR_AUTO_THUMB)

### Format

> SET (SCROLL_BAR_AUTO_THUMB, window, {HORIZONTAL |VERTICAL}, {ON |OFF |1 |0})

### Parameters

> #### SCROLL_BAR_AUTO_THUMB

> A keyword that directs DECTPU to enable or disable automatic adjustment of the scroll bar slider in a DECTPU window.

> #### window

> The window whose scroll bar slider you want DECTPU to adjust.

> #### HORIZONTAL

> A keyword that directs DECTPU to set the slider on a horizontal scroll bar.

> #### VERTICAL

> A keyword that directs DECTPU to set the slider on a vertical scroll bar.

> #### ON, 1

> A keyword that directs DECTPU to enable automatic adjustment of the scroll bar slider.

> #### OFF, 0

> A keyword that directs DECTPU to disable automatic adjustment of the scroll bar slider.

### Description

> The SET (SCROLL_BAR_AUTO_THUMB) procedure enables or disables automatic adjustment of the scroll bar slider. By default, SET (SCROLL_BAR_AUTO_THUMB) is set to ON and DECTPU automatically manages a window's scroll bar slider in the following ways:
> - Adjusts the size of the slider as you add, delete, or move text, so that the slider size represents the amount of visible text in relation to the total amount of text
> - Adjusts the size of the slider whenever the size of the window and the size of the scroll bar change, so that the slider size remains proportional to the scroll bar size
> - Adjusts the position of the slider as you add, delete, or move text, so that the slider shows whether the current buffer or line contains text not visible on the screen and, if so, where the invisible text is in relation to the visible text

> When the scroll bar slider is adjusted automatically, the width of the slider in a horizontal scroll bar represents the width of the window. For example, the size of the slider changes when the window width is changed from 80 to 132 columns or the reverse. The position of the slider changes when the window is shifted left or right. The height of the slider in a vertical scroll bar represents the height of the window.

> If you do not want DECTPU to adjust the scroll bar slider automatically or if you want to change the size or position of the slider, specify the OFF keyword. For more information about calculating the size and position of the slider, see the description of the SET (SCROLL_BAR) built-in procedure.

> You cannot disable DECTPU's automatic adjustment of the scroll bar itself. DECTPU always adjusts the scroll bar to the size of the window.

#### Signaled Errors

TPU$_BADKEY | WARNING | You specified an invalid keyword as a parameter.
TPU$_INVPARAM | ERROR | One of the parameters was specified with data of the wrong type.
TPU$_NORETURNVALUE | ERROR | SET (SCROLL_BAR_AUTO_THUMB) cannot return a value.
TPU$_REQUIRESDECW | ERROR | You can use the SET (SCROLL_BAR_AUTO_THUMB) built-in only if you are using DECwindows DECTPU.
TPU$_TOOFEW | ERROR | Too few arguments passed to the SET (SCROLL_BAR_AUTO_THUMB) built-in.
TPU$_TOOMANY | ERROR | Too many arguments passed to the SET (SCROLL_BAR_AUTO_THUMB) built-in.

### Example

> The following example turns on automatic adjustment of the vertical scroll bar's slider in the current window:

    vertical_bar := SET (SCROLL_BAR_AUTO_THUMB, CURRENT_WINDOW, VERTICAL, ON);

## SET (SCROLLING)

### Format

> SET (SCROLLING, window, {ON |OFF |1 |0}, integer1, integer2, integer3)

> or
> SET (SCROLLING, window, {JUMP|SMOOTH})

### Parameters

> #### SCROLLING

> A keyword that refers to the upward or downward movement of existing lines in a window to make room for new lines at the bottom or top of the window. When a window is scrolled, the cursor position remains in the same column, but the screen line that the cursor is on may change.

> #### window

> The window in which the scrolling limits are being set.

> #### ON, 1

> Causes scrolling of the text in a window to be turned on. This is the default value for the third parameter if the terminal supports scrolling.

> #### OFF, 0

> Causes scrolling of the text in a window to be turned off. The screen is completely repainted each time a scroll would otherwise take place. This is the default value for the third parameter if the terminal does not support scrolling.

> #### integer1

> The offset from the top screen line of a window. The offset identifies the top limit of an area in which the cursor can move as it tracks the editing point. If the cursor is forced to move above this screen line to track the editing point, lines in the window move downward so that the cursor stays within the limits of the scroll margins. If you reach the beginning of the buffer, the text is no longer scrolled.

> The value you specify for this parameter must be greater than or equal to zero and less than or equal to the number of lines in the window.

> #### integer2

> The offset from the bottom screen line of a window. The offset identifies the bottom limit of an area in which the cursor can move as it tracks the editing point. If the cursor is forced to move below this screen line to track the editing point, lines in the window move upward so that the cursor stays within the limits of the scroll margins. If you reach the end of the buffer, the text is no longer scrolled.

> The value you specify for this parameter must be greater than or equal to zero and less than or equal to the number of lines in the window.

> #### integer3

> The number that indicates how many lines from the top or the bottom scroll margin the cursor should be positioned after a window is scrolled. For example, if the bottom scroll margin is screen line 14 and integer3 has a value of 0, the cursor is positioned on screen line 14 after text is scrolled upward. However, if integer3 has a value of 3, the cursor is positioned on screen line 11.

> The value you specify for this parameter must be greater than or equal to zero and less than or equal to the number of lines in the window.

> You cannot specify a value that would position the cursor outside the window. That is, integer1 + integer3 or integer2 + integer3 must be less than the height of the window. For example, if the window is 10 lines long and integer1 is set at 3, you cannot specify a value of 7 or more for integer3. Such a specification would place the cursor outside the window.

> If you use the SET (SCROLLING) built-in procedure from within EVE by way of the TPU command, EVE may override the value you specify for this parameter.

> #### JUMP

> Directs DECTPU to repaint new text instead of scrolling new text into your window. When scrolling is set to jump mode, DECTPU first scrolls the text that will remain in your window, leaving part of the window empty. DECTPU then displays the new text in the empty region in a single repaint operation. Scrolling is faster in jump mode then in smooth mode because only part of your window is scrolled. To determine if the scrolling mode is set to the jump setting, use the GET-INFO (SCREEN, "jump_scroll") built-in procedure. A return value of 1 indicates that the jump setting is in effect.

> #### SMOOTH

> Directs DECTPU to repaint each new line of text as it is brought into the window. When scrolling is set to smooth mode, the text appears to slide smoothly in and out of the window. This setting is the default. To determine if the scrolling mode is set to the smooth setting, use the GET-INFO (SCREEN, "jump_scroll") built-in procedure. A return value of 0 indicates that the smooth setting is in effect.

### Description

> The SET (SCROLLING) procedure modifies the scrolling action of a window.

> If the terminal on which you are running DECTPU supports scrolling, you can use the SET (SCROLLING) built-in procedure to turn scrolling on or off. If the terminal does not support scrolling, scrolling will always be off. If scrolling is off, the window is repainted every time a scroll would otherwise occur.

> The SET (SCROLLING) built-in procedure also defines scroll margins by using integer1 and integer2. If you use CURSOR_VERTICAL, MOVE_HORIZONTAL, MOVE_VERTICAL, POSITION, or a text manipulation built-in to move the cursor above the top scroll margin or below the bottom scroll margin, then SET (SCROLLING) moves the cursor by the number of lines specified in integer3.

> You must provide values for integer1 and integer2 that leave at least one line in the window unaffected by either scroll margin. That is, integer1 + integer2 must be less than the height of the window. For example, if you have a window that is ten lines tall, you cannot specify a value of 5 for the top scroll margin and a value of 5 for the bottom scroll margin. Such a specification leaves no area of the window that is not within a scroll margin.

> You can move the cursor above or below a scroll margin under certain circumstances. If CROSS_WINDOW_BOUNDS is set to off, CURSOR_VERTICAL does not cause scrolling when the cursor reaches a scroll margin. If you are moving backward through the file and the top line of the buffer is already visible on the screen, the top scroll margin is ignored. If you are moving forward through the file and the bottom line of the buffer is already visible on the screen, the bottom scroll margin is ignored.

> If using the ADJUST_WINDOW built-in procedure makes the window so much smaller that the scroll margins overlap, DECTPU automatically reduces the scroll margins proportionally to fit the new window. If you use ADJUST_WINDOW to make a window larger, DECTPU does not adjust the scroll margins.

#### Signaled Errors

TPU$_TOOFEW | ERROR | SET (SCROLLING) requires at least six parameters.
TPU$_TOOMANY | ERROR | You specified more than six parameters.
TPU$_INVPARAM | ERROR | One or more of the specified parameters has the wrong type.
TPU$_UNKKEYWORD | ERROR | You specified an unknown keyword.
TPU$_BADKEY | ERROR | Keyword must be either ON or OFF.
TPU$_BADMARGINS | ERROR | You specified values for the top margin, bottom margin, and cursor movement that exceed the dimensions of the window.
TPU$_BADVALUE | ERROR | Integer values must be from 0 to 255.

### Examples

> The following example turns on scrolling in the window new_window. The statement sets the top and bottom scroll margins to 0. This means that you can move the cursor all the way to the top or bottom of the window before new text is scrolled into the window. Finally, the statement causes DECTPU to place the cursor two lines down from the top or up from the bottom of the window when scrolling is completed.

#1
    SET (SCROLLING, new_window, ON, 0, 0, 2)

> The following example causes DECTPU to repaint new text in your window in one operation instead of scrolling each line of text:

#2
    SET (SCROLLING, JUMP);

## SET (SELF_INSERT)

### Format

> SET (SELF_INSERT, string, {ON |OFF |1 |0})

### Parameters

> #### SELF_INSERT

> A keyword that specifies whether a character is inserted into the buffer when you press a key with the following characteristics:
> - Associated with a printable character
> - Not bound to a procedure or program

> #### string

> A string that specifies the key map list in which the behavior of undefined keys associated with printing characters is to be set.

> #### ON, 1

> Causes the printable characters to be inserted when no procedures are bound to them while the specified key map list is active. This is the default.

> #### OFF, 0

> Causes the UNDEFINED_KEY procedure to be called when you enter these undefined characters. If an undefined key procedure has not been specified, DECTPU displays a warning message when you press an undefined, printable key. You can specify an undefined key procedure by using the SET (UNDEFINED_KEY) built-in procedure.

### Description

> With the SET (SELF_INSERT) procedure, you can control what happens when you press an undefined key associated with a printable character. If SELF_INSERT is set ON and you press an undefined key associated with a printable character, the character is inserted into the current buffer at the current cursor position. If SELF_INSERT is turned off, printable characters whose keys are not defined in any key maps in the key map list bound to the current buffer are considered undefined. These undefined keys cause either the message "key has no definition" to be displayed or some user-defined action to occur.

> The default result for pressing an undefined key associated with a printable character procedure is that the character is inserted. The default condition for SET (SELF_INSERT) is ON. The default behavior, if SET (SELF_INSERT) is OFF, is to call the UNDEFINED_KEY procedure.

> For more information on how to define what happens when SET (SELF_INSERT) is turned off, see the description of the SET (UNDEFINED_KEY) built-in procedure.

#### Signaled Errors

TPU$_NOKEYMAPLIST | WARNING | You attempted to access an undefined key map list.
TPU$_TOOFEW | ERROR | SET (SELF_INSERT) requires three parameters.
TPU$_TOOMANY | ERROR | You specified more than three parameters.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_BADKEY | ERROR | You specified an invalid keyword.

### Example

> The following example toggles the ON and OFF setting of SELF_INSERT for the key map list bound to the current buffer:

    PROCEDURE toggle_self_insert

       LOCAL current_key_map_list;

       current_key_map_list := GET_INFO (CURRENT_BUFFER, "key_map_list");

       IF GET_INFO (current_key_map_list, "self_insert")
       THEN
           SET (SELF_INSERT, current_key_map_list, OFF)
       ELSE
           SET (SELF_INSERT, current_key_map_list, ON)
       ENDIF;
    ENDPROCEDURE;

## SET (SHIFT_KEY)

### Format

> SET (SHIFT_KEY, keyword [[, string ]])

### Parameters

> #### SHIFT_KEY

> A keyword that refers to DECTPU's shift key (by default PF1), not the key marked Shift on the keyboard.

> #### keyword

> A DECTPU key name for a key.

> #### string

> A string that is a key map list name. This optional argument specifies the key map list in which the shift key is used. If the key map list is not specified, the key map list associated with the current buffer is used.

### Description

> With the SET (SHIFT_KEY) procedure, you can assign two commands to one key: one is used when the key is pressed by itself, and the other is used when the key is pressed after the defined shift key. The DECTPU shift key is similar to the GOLD key in Compaq's EDT editor.

> Only one DECTPU shift key can be active at a time. The DECTPU shift key can be any key other than the following keys:

> - Shift
> - Escape
> - SCROLL on the VT100 keyboard
> - F1, F2, F3, F4, and F5 on the LK201 or LK401 keyboards
> - Compose Character on the LK201 or LK401 keyboards

> By default, PF1 is the DECTPU shift key.

> You cannot make DECTPU execute a procedure or learn sequence bound to the shift key. However, designating a defined key as the shift key does not undefine the key; it merely disables the definition when the key is designated as the shift key. If you define another key as the shift key, DECTPU reenables the first key's definition.

> If you want to use PF1 for another purpose, use SET (SHIFT_KEY) to define a key other than PF1 as DECTPU's shift key.

> If you use SET (SHIFT_KEY) to define a GOLD key in EVE, EVE does not undefine the GOLD key correctly. When you use the EVE SET NOGOLD command, EVE returns the error message "There is no user GOLD key currently set." Although this message appears to say that the GOLD key has successfully been undefined, what it really means is that EVE does not recognize that a GOLD key was ever defined.

> To redefine a GOLD key in these circumstances, you can do either of the following:

> - Use the EVE SET GOLD KEY command.
> - Undefine the GOLD key by using the DECTPU statement
>   SET (SHIFT_KEY, KEY_NAME (PF1, SHIFT_KEY)). Then set the GOLD key by using the SET GOLD KEY command.

#### Signaled Errors

TPU$_TOOFEW | ERROR | SET (SHIFT_KEY) requires at least two parameters.
TPU$_TOOMANY | ERROR | You specified more than three parameters.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_BADKEY | ERROR | You specified an invalid keyword.
TPU$_NOKEYMAPLIST | WARNING | You specified an undefined key map list.

### Examples

> The following example causes the keypad key PF4 to be defined as the shift key for the editor. The definition is stored in the default key map list, TPU$KEY_MAP_LIST. PF4 operates as the shift key only in buffers to which TPU$KEY_MAP_LIST is bound.

#1
    SET (SHIFT_KEY, PF4, "tpu$key_map_list")

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 6020PRO_033.HTML