Document revision date: 30 March 2001

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

Signaled Errors

Examples

The following example creates a buffer called NEW_BUFFER and stores a pointer to the buffer in the variable nb. Use the variable nb when you want to specify this buffer as a parameter for DECTPU built-in procedures. The file specification "login.com" reads the input file for NEW_BUFFER from LOGIN.COM.

nb := CREATE_BUFFER ("new_buffer", "login.com") 
 
      

The first statement in the following example creates a buffer called DEFAULTS and stores a pointer to the buffer in the variable default_buffer. The second statement sets the direction of default_buffer to reverse. The third statement creates a buffer called BUFFER_B and stores a pointer to the buffer in the variable b. This statement takes default information from default_buffer. Buffer b does not receive any text, marks, or ranges from the buffer default_buffer.

default_buffer := CREATE_BUFFER ("defaults"); 
SET (REVERSE, default_buffer); 
b := CREATE_BUFFER ("buffer_b", "", default_buffer); 
 

 
 
      

The following example creates the help buffer:

PROCEDURE user_help_buffer 
   help_buf := CREATE_BUFFER("help_buf"); 
   SET (EOB_TEXT, help_buf, "[End of HELP]"); 
   SET (NO_WRITE, help_buf); 
   SET (SYSTEM, help_buf); 
ENDPROCEDURE; 
 
      

The following example creates a buffer named scratch. It directs DECTPU to name the associated buffer-change journal file SCRATCH_JL.JL. You must use commas as placeholders for the two unspecified optional parameters. Also, by default DECTPU puts journal files in the directory defined by the logical name TPU$JOURNAL. TPU$JOURNAL points to the same directory that SYS$SCRATCH points to. You can reassign TPU$JOURNAL to point to a different directory.

buf1 := CREATE_BUFFER ("Scratch",,,"Scratch_jl.jl"); 
 
 
      

The following example creates a template buffer called DEFAULTS, changes the end-of-buffer text for the template buffer, and then creates a user buffer. The user buffer is created with the same end-of-buffer text that the defaults buffer has.

defaults_buffer := CREATE_BUFFER ("Defaults"); 
 
SET (EOB_TEXT, defaults_buffer, "[That's all, folks!]"); 
 
user_buffer := CREATE_BUFFER ("User1.txt", "", defaults_buffer); 
      

Format

[[string2 := ]] CREATE_KEY_MAP (string1)

Parameter

string1

A string that specifies the name of the key map you create.

Return Value

Description

The CREATE_KEY_MAP procedure creates and names a key map. CREATE_KEY_MAP optionally returns a string that is the name of the key map created. A key map is a set of key definitions. Key maps let you manipulate key definitions as a group. Key maps and their key definitions are saved in section files. The default key map for DECTPU is TPU$KEY_MAP, contained in the default key map list TPU$KEY_MAP_LIST. See the description on key map lists in CREATE_KEY_MAP_LIST.

The EVE editor does not use the default key map TPU$KEY_MAP. In EVE, the name of a key map is not the same as the variable that contains the key map. For example, the EVE variable EVE$X_USER_KEYS contains the key map named EVE$USER_KEYS, which stores your key definitions. EVE stores all its key maps in the default key map list TPU$KEY_MAP_LIST. However, the default key map, TPU$KEY_MAP, is removed from the default key map list by the standard EVE section file.

When you create a key map, its keys are undefined. Each key map can hold definitions for all characters in the DEC Multinational Character Set and all the keypad keys and the function keys, in both their shifted and unshifted forms. Each key map has its own name (a string). This name cannot be the same as that of either another key map or a key map list.

Signaled Errors

Example

The following example creates a key map and defines two keys in the key map. The name of the key map is stored in the variable sample_key_map.

PROCEDURE init_sample_key_map 
 
sample_key_map := CREATE_KEY_MAP ("sample_key_map"); 
 
DEFINE_KEY ("EXIT", Ctrl_Z_KEY, "Exit application", sample_key_map); 
DEFINE_KEY ("COPY_TEXT ('XYZZY')", Ctrl_B_KEY, "Magic Word", sample_key_map); 
 
ENDPROCEDURE; 
      

Format

[[string3 := ]]

CREATE_KEY_MAP_LIST (string1, string2 [[,...]])

Parameters

string1

A string that specifies the name of the key map list that you create.

string2

A string that specifies the names of the initial key maps within the key map list you create.

Return Value

Description

The CREATE_KEY_MAP_LIST procedure creates and names a key map list, and also specifies the initial key maps in the key map list it creates. CREATE_KEY_MAP_LIST optionally returns a string that is the name of the key map list created. A key map list is an ordered set of key maps. Key map lists let you change the procedures bound to your keys. To find the definition of a given key, DECTPU searches through the key maps in the specified or default key map list until DECTPU either finds a definition for the key or reaches the end of the last key map in the list.

DECTPU provides the default key map list TPU$KEY_MAP_LIST, which contains the default key map TPU$KEY_MAP. See the description of the CREATE_KEY_MAP built-in procedure for more information on key maps.

The CREATE_KEY_MAP_LIST built-in procedure creates a new key map list, names the key map list, and specifies the initial key maps contained in the list.

Key map lists store directions on what DECTPU is to do when you press an undefined key associated with a printable character. By default, a key map list directs DECTPU to insert undefined printable characters into the current buffer. To change the default, use the SET (SELF_INSERT) built-in procedure.

A newly created key map list is not bound to any buffer. To bind a key map list to a buffer, use the SET (KEY_MAP_LIST) built-in procedure. When you use the POSITION built-in to select a current buffer, the key map list that is bound to the buffer is automatically activated.

A newly created key map list has no procedure defined to be called when an undefined key is referenced. You can define such a procedure with the SET (UNDEFINED_KEY) built-in procedure. The default is to display the message "key has no definition."

Key map lists are saved in section files, along with any undefined key procedures and the SELF_INSERT settings.

Signaled Errors

Example

The following example creates two key maps and groups them into a key map list:

PROCEDURE init_help_key_map_list 
 
help_user_keys := CREATE_KEY_MAP ("help_user_keys"); 
help_keys := CREATE_KEY_MAP ("help_keys"); 
help_key_list := CREATE_KEY_MAP_LIST ("help_key_list", help_user_keys, 
                 help_keys); 
ENDPROCEDURE; 
      

Format

process := CREATE_PROCESS (buffer [[,string]])

Parameters

buffer

The buffer in which DECTPU stores output from the subprocess.

string

A string that represents the first command that you want to send to the subprocess. If you do not want to include the first command when you use the CREATE_PROCESS built-in procedure, see the SEND built-in procedure for a description of how to send the first or subsequent commands to a subprocess.

Return Value

Description

The CREATE_PROCESS procedure starts a subprocess and associates a buffer with it. You can optionally specify an initial command to send to the subprocess. You can create multiple subprocesses. When you exit from DECTPU, any subprocesses you have created with CREATE_PROCESS are deleted. If you want to remove a subprocess before exiting, use the DELETE built-in procedure with the process as a parameter (DELETE (proc1)), or set the variable to integer zero, as follows:

proc1 := 0

CREATE_PROCESS creates a subprocess of a DECTPU session and all of the output from the subprocess goes into a DECTPU buffer. You cannot run a program or utility that takes over control of the screen from a process created with this built-in procedure. You can, however, use the SPAWN built-in procedure to create a subprocess that suspends your DECTPU process and places you directly at the system command prompt. You can then run programs that control the whole screen.

See the Guide to the DEC Text Processing Utility for a list of subprocess restrictions.

Signaled Errors

Example

The following example creates a buffer to hold the output from the DCL commands executed by the OpenVMS subprocess:

! Create a buffer to hold the output from the DCL commands 
! "SET NOON" and "DIRECTORY". 
 
PROCEDURE user_dcl_process 
   dcl_buffer := CREATE_BUFFER ("dcl_buffer"); 
   MAP (main_window, dcl_buffer); 
   my_dcl_process := CREATE_PROCESS (dcl_buffer, "SET NOON"); 
   MESSAGE ("Creating DCL subprocess..."); 
   SEND ("DIRECTORY", my_dcl_process); 
ENDPROCEDURE; 
      

Format

range := CREATE_RANGE ({marker1|keyword1}, {marker2|keyword1}
[[, keyword2 ]])

Parameters

marker1

The marker that indicates the point in the buffer where the range begins.

marker2

The marker that indicates the point in the buffer where the range ends.

keyword1

A keyword that indicates the point in the buffer where you want the range to begin or end. Table 2-1 shows the valid keywords and their meanings.

Table 2-1 CREATE_RANGE Keyword Parameters

Keyword	Meaning
LINE_BEGIN	The beginning of the current buffer's current line.
LINE_END	The end of the current buffer's current line.
BUFFER_BEGIN	Line 1, offset 0 in the current buffer. This is the first position where a character could be inserted, regardless of whether there is a character there. This is the same as the point referred to by BEGINNING_OF (CURRENT_BUFFER).
BUFFER_END	The last position in the buffer where a character could be inserted. This is the same as the point referred to by END_OF (CURRENT_BUFFER).

keyword2

The video attribute for the range: BLINK, BOLD, NONE, REVERSE, or UNDERLINE. If you omit the parameter, the default is NONE.

Return Value

Description

The CREATE_RANGE procedure returns a range that includes two delimiters and all the characters between them, and sets the video attributes for displaying the characters when they are visible on the screen. A range delimiter can be a marker, the beginning or end of a line, or the beginning or end of a buffer. The beginning and ending delimiters do not have to be of the same type but must be in the same buffer.

CREATE_RANGE establishes a range that is delimited by the markers you specify. You can create multiple ranges in a buffer. When you apply video attributes to a range, you can see the range if it is in a visible buffer. A range may overlap another range.

If you clear the contents of a range with the ERASE built-in procedure, the range structure still exists. The range and its video attributes, if any, move to the next character or position beyond where the range ended before the range was erased.

To remove the range structure, use the DELETE built-in procedure or set the variable to which the range is assigned to zero (r1 := 0).

In portions of a range that either are associated with nonprintable characters or are not associated with characters at all, DECTPU does not display any of the video attributes of the range. However, if you insert new characters into portions of a range where the video attributes have not been displayed, the new characters do display the video attributes that apply to the range.

CREATE_RANGE checks whether the markers you specify as parameters are free markers. A free marker is a marker not bound to a character. For more information on free markers, see the description of the MARK built-in procedure.

If a marker defining a range is a free marker, DECTPU ties the range to the character or end-of-line nearest to the free marker to use as the range delimiter. An end-of-line is not a character but is a point to which a marker can be bound.

Signaled Errors

Examples

The following example creates a range starting at start_mark and ending at end_mark. When this range is visible on the screen, the characters in the range are bolded.

my_range := CREATE_RANGE (start_mark, end_mark, BOLD) 
 

 
 
      

The following example erases the text in the current buffer, starting at the editing point and erasing text until the end of the buffer is reached:

PROCEDURE user_erase_to_eob 
 
   LOCAL start_of_range, 
         here_to_eob; 
 
   start_of_range := MARK (NONE); 
   here_to_EOB    := CREATE_RANGE (start_of_range, 
                                  END_OF (CURRENT_BUFFER), 
                                  NONE); 
   ERASE (here_to_eob); 
ENDPROCEDURE; 
      

The following example creates a range starting at the first point in the buffer where a character can be inserted and ending at the point marked by mark2. If the range is visible on the screen, the characters in it are highlighted with the reverse video attribute.

the_range := CREATE_RANGE (BUFFER_BEGIN, mark2, REVERSE); 
      

The CREATE_WIDGET built-in procedure has two variants with separate syntaxes.

Format

widget := CREATE_WIDGET (widget_class,widget_name, {parent_widget|SCREEN}
[[, {buffer|learn_sequence|program|range|string}
[[, closure
[[, widget_args... ]] ]] ]])

Low-Level Variant

This variant uses the Intrinsics or Motif Toolkit low-level creation routine to create and return a widget. Although it has been created, the returned widget is not managed and therefore not visible. The application must call the MANAGE_WIDGET built-in procedure to make the widget visible.

Format

widget := CREATE_WIDGET (resource_manager_name,hierarchy_id,{parent_widget|SCREEN}
[[, {buffer|learn_sequence|program|range|string}
[[, closure ]] ]])

Hierarchy Variant

This variant creates and returns an entire hierarchy of widgets (as defined in a Motif Resource Manager database) and returns the topmost widget. All children of the returned widget are also created and managed. The topmost widget is not managed, so none of the widgets created is visible.

Parameters

widget_class

The integer returned by DEFINE_WIDGET_CLASS that specifies the class of widget to be created.

widget_name

A string that is the name to be given to the widget.

parent_widget

The widget that is to be the parent of the newly created widget.

SCREEN

A keyword indicating that the newly created widget is to be the child of DECTPU's main window widget.

buffer

The buffer that contains the interface callback routine. This code is executed when the widget performs a callback to DECTPU; all widgets created with a single CREATE_WIDGET call use the same callback code. If you do not specify this parameter, DECTPU does not execute any callback code when the widget performs a callback to DECTPU.

learn_sequence

The learn sequence that is the interface callback routine. This is executed when the widget performs a callback to DECTPU; all widgets created with a single CREATE_WIDGET call use the same callback code. If you do not specify this parameter, DECTPU does not execute any callback code when the widget performs a callback to DECTPU.

program

The program that is the interface callback routine. This is executed when the widget performs a callback to DECTPU; all widgets created with a single CREATE_WIDGET call use the same callback code. If you do not specify this parameter, DECTPU does not execute any callback code when the widget performs a callback to DECTPU.

range

The range that contains the interface callback routine. This is executed when the widget performs a callback to DECTPU; all widgets created with a single CREATE_WIDGET call use the same callback code. If you do not specify this parameter, DECTPU does not execute any callback code when the widget performs a callback to DECTPU.

string

The string that contains the interface callback routine. This is executed when the widget performs a callback to DECTPU; all widgets created with a single CREATE_WIDGET call use the same callback code. If you do not specify this parameter, DECTPU does not execute any callback code when the widget performs a callback to DECTPU.

closure

A string or integer. DECTPU passes the value to the application when the widget performs a callback to DECTPU. For more information about using closures, see the Guide to the DEC Text Processing Utility.

If you do not specify this parameter, DECTPU passes the closure value (if any) given to the widget in the User Interface Language (UIL) file defining the widget. If you specify the closure value with CREATE_WIDGET instead of in the UIL file, all widgets created with the same CREATE_WIDGET call have the same closure value.

widget_args

One or more pairs of resource names and resource values. You can specify a pair in an array or as a pair of separate parameters. If you use an array, you index the array with a string that is the name of the resource you want to set. Resource names are case sensitive. The corresponding array element contains the value you want to assign to that resource. The array can contain any number of elements. If you use a pair of separate parameters, use the following format:

resource_name_string, resource_value

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_004.HTML