Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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.

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

#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 : 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.


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:

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:

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:

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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6020PRO_005.HTML