Document revision date: 19 July 1999

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

hierarchy_id

Return Value

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.

Signaled Errors

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

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.

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 : Xmmessage_box { 
            
            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.

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

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

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:

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:

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.

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; 
      

Format

buffer := CURRENT_BUFFER

Parameters

None.

Return Value

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

Examples

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

my_cur_buf := CURRENT_BUFFER 
      

The following example reverses the direction of the current buffer:

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

Format

string := CURRENT_CHARACTER

Parameters

None.

Return Value

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

Examples

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

my_cur_char := CURRENT_CHARACTER 
      

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

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; 
      

Format

integer := CURRENT_COLUMN

Parameters

None.

Return Value

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

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.

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.

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; 
      

Format

keyword := CURRENT_DIRECTION

Parameters

None.

Return Value

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

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:

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:

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

Format

string := CURRENT_LINE

Parameters

None.

Return Value

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