Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

Arrays and string/value pairs may be interspersed. Each array index and its corresponding element value, or each string and its corresponding value, must be valid widget arguments for the class of widget you are creating.

#### resource_manager_name

A case-sensitive string that is the name assigned to the widget in the UIL file defining the widget.

#### hierarchy_id

The hierarchy identifier returned by the SET (UID) built-in procedure. This identifier is passed to the Motif Resource Manager, which uses the identifier to find the resource name in the database.

### Return Value

The newly created widget.

### Description

> The CREATE_WIDGET procedure creates a widget. The widget name that you specify in the User Interface Definition (UID) file must match the case of the widget name that you specify as a parameter to CREATE_WIDGET. If you specify case-sensitive widget names in your User Interface Language (UIL) file, you must use the same widget name case with CREATE_WIDGET as you used in the UIL file. If you specify case-insensitive widget names in your UIL file, the UIL compiler translates all widget names to uppercase, so in this instance you must use uppercase widget names with CREATE_WIDGET. Example 1 in the Examples section specifies case-insensitive widget names in the UIL file and specifies an uppercase name for the widget with the CREATE_WIDGET built-in procedure.

> If you specify one or more callback arguments in your UIL file, specify either the routine TPU$WIDGET_INTEGER_CALLBACK or the routine TPU$WIDGET_STRING_CALLBACK. For more information about specifying callbacks, see the Guide to the DEC Text Processing Utility. For more information about UIL files, see the VMS DECwindows Guide to Application Programming. DECTPU uses the Motif Version 1.1-3 compatibility libraries and requires that UID files are produced using the 1.1-3 UIL compiler and not the version 1.2 UIL compiler provided with new releases of DECwindows. Procedures for using the 1.1-3 UIL compiler are described in the DECwindows release notes.

#### Signaled Errors

TPU$_BADKEY | WARNING | You specified an invalid keyword as a parameter.
TPU$_UNDWIDCLA | WARNING | You specified a widget class integer that is not known to DECTPU.
TPU$_INVPARAM | ERROR | You specified one of the parameters with data of the wrong type.
TPU$_NEEDTOASSIGN | ERROR | CREATE_WIDGET must return a value.
TPU$_REQUIRESDECW | ERROR | You can use CREATE_WIDGET only if you are using DECwindows DECTPU.
TPU$_TOOFEW | ERROR | Too few arguments passed to CREATE_WIDGET.
TPU$_TOOMANY | ERROR | Too many arguments passed to CREATE_WIDGET.
TPU$_WIDMISMATCH | ERROR | You specified a widget whose class is not supported.
TPU$_ARGMISMATCH | ERROR | A widget argument was not an array or a string/value pair.
TPU$_COMPILEFAIL | WARNING | Compilation of the widget interface callback routine failed due to syntax errors.
TPU$_NONAMES | WARNING | A widget argument is not supported by the specified widget.
TPU$_EXTRANEOUSARGS | ERROR | You specified one or more extraneous widget arguments.
TPU$_BADHIERARCHY | ERROR | You specified an invalid hierarchy identifier.

###

#### Examples

> The following example, eve_display_example, creates a modal dialog box widget and maps the widget to the DECTPU screen.

> The example shows how to use the variant of CREATE_WIDGET that returns an entire widget hierarchy. To use this variant to create a widget or widget hierarchy, you must have available the compiled form of a User Interface Language (UIL) file specifying the characteristics of the widgets you want to create. Compaq recommends that you use one or more UIL files and the corresponding variant of CREATE_WIDGET whenever possible. UIL is efficient and UIL files make it easy to translate your application into other languages.

#1
    PROCEDURE eve_display_example

    LOCAL   example_widget,              ! Variable assigned to the created widget.
            example_widget_name,         ! The name of the widget assigned
                                         ! to this variable must be uppercase
                                         ! if you specified case insensitive
                                         ! widget names in the UIL file.

            example_hierarchy;           ! Resource Manager
                                         ! hierarchy for this example.

    ON_ERROR
        [OTHERWISE]:                     ! Traps errors.
    ENDON_ERROR;

    ! Set the widget hierarchy. The default file spec is "SYS$LIBRARY: .UID"

    example_hierarchy := SET (UID, "mynode$dua0:[smith]example");

    ! The DECTPU CREATE_WIDGET built-in needs the name of the widget
    ! defined in the UIL file.

    example_widget_name := "EXAMPLE_BOX";   ! The widget EXAMPLE_BOX is
                                            ! defined in the file EXAMPLE.UIL.

    ! Create the widget if it has not already been created.

    IF GET_INFO (example_widget, "type") <> WIDGET
    THEN
        example_widget := CREATE_WIDGET (example_widget_name, example_hierarchy,
                                          SCREEN, eve$kt_callback_routine);

       ! EVE defines eve$callback_dispatch to be EVE's callback routine.
       ! You do not need to define it again if you are extending EVE.

    ENDIF;

    ! Map "example_widget" to the screen using MANAGE_WIDGET.

    MANAGE_WIDGET (example_widget);

    RETURN (TRUE);

    ENDPROCEDURE;

> The following example shows a sample UIL file describing the modal dialog box called example_box. The UIL file specifies where the widget appears on the screen, what label appears on the box's OK button, and what message the widget displays.

#2
    module    example
    version = 'V00-000'

    ! This is a sample UIL file that creates a message box containing
    ! the message "Hello World".

    names = case_insensitive

    value
            example_ok              : compound_string ("OK");
            example_message         : compound_string ("Hello World");

    object
            example_box : XmMessageBox {

                arguments {
                    XmNdefaultPosition = true;   ! puts box in center work area
                    XmNokLabelString = example_ok;
                    XmNmessageString = example_message;
                };
            };

    end module;

> For an example showing how to use the variant of CREATE_WIDGET that calls the Toolkit low-level creation routine, see Example A-1.

## CREATE_WINDOW

### Format

> [[window := ]]

> CREATE_WINDOW (integer1, integer2,
> {ON|OFF|1|0})

### Parameters

> #### integer1

> The screen line number at which the window starts.

> #### integer2

> The number of rows in the window.

> #### ON, 1

> A keyword that directs DECTPU to display a status line in the new window. The status line occupies the last row of a window. By default, the status line is displayed in reverse video and contains the following information about the buffer that is currently mapped to the window:
> - The name of the buffer that is associated with the window
> - The name of the file that is associated with the buffer, if one exists

> See SET (STATUS_LINE) for information on changing the video attributes of the status line, the information displayed on the status line, or both.

> #### OFF, 0

> Suppresses the display of the status line.

### Return Value

The window created by CREATE_WINDOW.

### Description

> The CREATE_WINDOW procedure defines a screen area called a window. You must specify the screen line number at which the window starts, the length of the window, and whether the status line is to be displayed. CREATE_WINDOW optionally returns the newly created window. If you want to use the window that you create as a parameter for any other built-in procedure, then you should specify a variable into which the window is returned.

> You can create multiple windows on the screen, but only one window can be the current window. The cursor is positioned in the current window. The current window and the current buffer are not necessarily the same.

> To make a window visible, you must associate a buffer with the window and then map the window to the screen. The following command maps main_window to the screen:

>     MAP (main_window, main_buffer)

> See the MAP built-in procedure for more information.

> The following keywords used with the SET built-in procedure let you establish attributes for windows. This list shows the defaults for the attributes:

> - SET (PAD, window, keyword)---By default, there is no blank padding on the right.
> - SET (SCROLL_BAR)---By default, DECTPU does not create vertical and horizontal scroll bars for a window in the DECwindows environment.
> - SET (SCROLL_BAR_AUTO_THUMB)---By default, DECTPU controls the slider in any scroll bars in a window.
> - SET (SCROLLING, window, keyword, integer1, integer2, integer3)---The default cursor limit for scrolling at the top of the screen is the first line of the window; the default cursor limit for scrolling at the bottom of the screen is the bottom line of the window. If the terminal type you are using does not let you set scrolling regions, the window is repainted.
> - SET (STATUS_LINE, window, keyword, string)---The status line may be ON or OFF according to the keyword specified for the CREATE_WINDOW built-in procedure. See the preceding description of the ON keyword for information about the default attributes of a status line.
> - SET (TEXT, window, keyword)---By default, the text is set to BLANK_TABS (tabs are displayed as blank spaces).
> - SET (VIDEO, window, keyword)---There are no video attributes by default.
> - SET (WIDTH, window, integer)---By default, the width is the same as the physical width of the terminal screen when the window is created.

> See the SET built-in procedure for more information on these keywords.

> Use the SHIFT built-in procedure to display text that lies to the right of the window's right edge in an unshifted window. For more information, see the description of the SHIFT built-in in this chapter.

#### Signaled Errors

TPU$_TOOFEW | ERROR | The CREATE_WINDOW built-in requires exactly three parameters.
TPU$_TOOMANY | ERROR | The CREATE_WINDOW built-in accepts exactly three parameters.
TPU$_BADKEY | ERROR | The keyword must be either ON or OFF.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_BADWINDLEN | WARNING | Invalid window length.
TPU$_BADFIRSTLINE | WARNING | Invalid first line for window.

### Examples

> The following example creates a window that starts at screen line 11 and is 10 rows long, and assigns the window to the variable new_window:

#1
    new_window := CREATE_WINDOW (11, 10, ON)

> A status line is displayed as the last line of the window. To make this window visible, you must associate an existing buffer with it and map the window to the screen with the following command:

#2
    MAP (new_window, buffer_variable)

> The following example creates a window called new_window that starts at screen line 1 and is 21 lines long. No status line is displayed. Tabs are displayed as special graphic characters. The buffer new_buffer, which is set to NO_WRITE, is associated with the window and the window is mapped to the screen.

#3
    PROCEDURE user_make_window
            new_window := CREATE_WINDOW(1, 21, OFF);
            SET (TEXT, new_window, GRAPHIC_TABS);
            new_buffer := CREATE_BUFFER ("user_buffer_name");
            SET (NO_WRITE, new_buffer);
            MAP (new_window, new_buffer);
    ENDPROCEDURE;

## CURRENT_BUFFER

### Format

> buffer := CURRENT_BUFFER

### Parameters

> None.

### Return Value

The buffer in which you are currently positioned.

### Description

> The CURRENT_BUFFER procedure returns the buffer in which you are currently positioned. The current buffer is the work space in which any DECTPU statements you execute take effect. The editing point is in the current buffer. The editing point is not necessarily the same as the cursor position.

#### Signaled Errors

TPU$_TOOMANY | ERROR | CURRENT_BUFFER takes no parameters.
TPU$_NEEDTOASSIGN | ERROR | The CURRENT_BUFFER built-in must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF | WARNING | You are not positioned in a buffer.

### Examples

> The following example stores a pointer to the current buffer in the variable my_cur_buf:

#1
    my_cur_buf := CURRENT_BUFFER

> The following example reverses the direction of the current buffer:

#2
    PROCEDURE user_toggle_direction
            IF CURRENT_DIRECTION = FORWARD
            THEN
                SET (REVERSE, CURRENT_BUFFER);
            ELSE
                SET (FORWARD, CURRENT_BUFFER);
            ENDIF;
    ENDPROCEDURE;

## CURRENT_CHARACTER

### Format

> string := CURRENT_CHARACTER

### Parameters

> None.

### Return Value

A string that consists of the character at the editing point in the current buffer.

### Description

> The CURRENT_CHARACTER procedure returns the character at the editing point in the current buffer at which most editing operations are carried out. Each buffer maintains its own editing point, but only the editing point in the current buffer is the active editing point. An editing point, which always refers to a character position in a buffer, is not necessarily the same as the cursor position, which always refers to a location in a window. For more information on the distinction between the editing point and the cursor position, see Appendix C.

> If the editing point is at the end of a line, CURRENT_CHARACTER returns a null string. If the editing point is at the end of a buffer, CURRENT_CHARACTER returns a null string and also signals a warning.

> Using CURRENT_CHARACTER may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_CHARACTER 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.

#### Signaled Errors

TPU$_TOOMANY | ERROR | CURRENT_CHARACTER takes no parameters.
TPU$_NEEDTOASSIGN | ERROR | The CURRENT_CHARACTER built-in must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF | WARNING | You are not positioned in a buffer.
TPU$_NOEOBSTR | WARNING | You are positioned at the EOB (end-of-buffer) mark.

### Examples

> The following example stores the string that represents the editing point in the variable my_cur_char:

#1
    my_cur_char := CURRENT_CHARACTER

> The following example writes the character that is at the current character position into the message area:

#2
    PROCEDURE user_display_current_character

    ! This procedure returns the ASCII character in the editing point.

       ascii_char := CURRENT_CHARACTER;
       IF ascii_char <> ""
          THEN
             MESSAGE ("The current character is '" + ascii_char + "'");
          ELSE
             MESSAGE ("There is no current character.");
       ENDIF;
    ENDPROCEDURE;

## CURRENT_COLUMN

### Format

> integer := CURRENT_COLUMN

### Parameters

> None.

### Return Value

An integer that is the column number of the current cursor position on the screen.

### Description

> The CURRENT_COLUMN procedure returns an integer that is the current column number of the cursor position on the screen. The column numbers range from 1 on the extreme left of the screen to the maximum value allowed for the terminal type you are using on the extreme right of the screen.

> The value returned by CURRENT_COLUMN and the value returned by GET_INFO (SCREEN, "current_column") are equivalent.

> When used in a procedure, CURRENT_COLUMN does not necessarily return the position where the cursor has been placed by other statements in the procedure. DECTPU generally does not update the screen until all statements in a procedure are executed. If you want the cursor position to reflect the actual editing location, put an UPDATE statement in your procedure immediately before any statements containing CURRENT_COLUMN, as follows:

>     UPDATE (CURRENT_WINDOW);

> If you do not want to update a window to get the current value for CURRENT_COLUMN, you can use the GET_INFO built-in procedure (buffer_variable, "offset_column"). This built-in returns the column number that the current offset in the buffer would have if it were mapped to a window, and if you were to force a screen update. This built-in returns an accurate value only if both of the following conditions are true:

> - You are using bound cursor movement (MOVE_VERTICAL, MOVE_HORIZONTAL) or other built-in procedures that cause cursor movement because of character movement within a buffer.
> - The window is not shifted.

> GET_INFO (window_variable, "current_column") does not necessarily return the column number that the cursor would occupy if you caused an explicit screen update.

> If a window is shifted, CURRENT_COLUMN still returns the current column number of the cursor on the screen. However, the value returned by x := GET_INFO (buffer, "offset_column") includes the number of columns by which the window is shifted. For example, if a window is shifted to the left by eight columns, CURRENT_COLUMN returns the value 1, while x := GET_INFO (buffer, "offset_column") returns the value 9.

#### Signaled Errors

TPU$_TOOMANY | ERROR | CURRENT_COLUMN takes no parameters.
TPU$_NEEDTOASSIGN | ERROR | The CURRENT_COLUMN built-in must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF | WARNING | You are not positioned in a buffer.

### Examples

> The following example combines three DECTPU built-in procedures. CURRENT_COLUMN returns the integer that is the current column position, STR converts the integer to a string, and MESSAGE writes this string to the message buffer.

#1
    MESSAGE (STR (CURRENT_COLUMN))

> The following example splits a line at the editing point. If the editing point is row 1, column 1, the procedure causes the screen to scroll.

#2
    PROCEDURE user_split_line
       LOCAL old_position, new_position;

       SPLIT_LINE;
       IF (CURRENT_ROW = 1) AND (CURRENT_COLUMN = 1)
       THEN
           old_position := MARK (NONE);
           SCROLL (CURRENT_WINDOW, -1);
           new_position := MARK (NONE);
           !Make sure we scrolled before doing CURSOR_VERTICAL
              IF new_position <> old_position
              THEN
                  CURSOR_VERTICAL (1);
              ENDIF;
       ENDIF;
    ENDPROCEDURE;

## CURRENT_DIRECTION

### Format

> keyword := CURRENT_DIRECTION

### Parameters

> None.

### Return Value

A keyword (FORWARD or REVERSE) that indicates the current direction of the current buffer.

### Description

> The CURRENT_DIRECTION procedure returns a keyword (FORWARD or REVERSE) that indicates the current direction of the current buffer. See also the descriptions of the SET (FORWARD) and SET (REVERSE) built-in procedures. If the FORWARD keyword is returned, the current direction is toward the end of the buffer. If the REVERSE keyword is returned, the current direction is toward the beginning of the buffer.

#### Signaled Errors

TPU$_TOOMANY | ERROR | CURRENT_DIRECTION takes no parameters.
TPU$_NEEDTOASSIGN | ERROR | The CURRENT_DIRECTION built-in must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF | WARNING | You are not positioned in a buffer.

### Examples

> The following example stores in the variable my_cur_dir the keyword that indicates whether the current direction setting for the buffer is FORWARD or REVERSE:

#1

    my_cur_dir := CURRENT_DIRECTION

> The following example writes to the message buffer a message indicating the current direction of character movement in the buffer:

#2
    PROCEDURE user_show_direction

        IF CURRENT_DIRECTION = FORWARD
        THEN
            my_message1 := MESSAGE ("Forward");
        ELSE
            my_message2 := MESSAGE ("Reverse");
        ENDIF;
    ENDPROCEDURE;

## CURRENT_LINE

### Format

> string := CURRENT_LINE

### Parameters

> None.

### Return Value

A string that represents the current line.

### Description

> The CURRENT_LINE procedure returns a string that represents the current line. The current line is the line that contains the editing point. If you are positioned on a line that has a length of 0, CURRENT_LINE returns a null string. If you are positioned at the end of the buffer, CURRENT_LINE returns a null string and also signals a warning.

> Previous | Next | Contents | Index

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