HP OpenVMS Systems Documentation

Format

{string3|integer} := GET_DEFAULT (string1, string2 )

Parameters

string1

The name of the resource whose value you want GET_DEFAULT to fetch. Resource names are case sensitive.

string2

The class of the resource. Resource class names are case sensitive.

Return Value

Description

The GET_DEFAULT procedure returns the value of an X resource from the X resources database. GET_DEFAULT is useful for initializing a layered application that uses an X defaults file. You can use GET_DEFAULT only in the DECwindows environment.

If you use the SET (DEFAULT_FILE) built-in to merge a new X resource database into the display's database, this affects the values returned by GET_DEFAULT.

Signaled Errors

Example

The following example shows the portion of a module_init procedure directing DECTPU to fetch the value of a resource from the X resources database. For more information on module_init procedures, see the Extensible Versatile Editor Reference Manual.

If you want to create an extension of EVE that enables use of an X defaults file to choose a keypad setting, you can use a GET_DEFAULT statement in a module_init procedure.

PROCEDURE application_module_init

LOCAL
    keypad_name;

    :
    :
    :

keypad_name := GET_DEFAULT ("user.keypad", "User.Keypad");

EDIT (keypad_name, UPPER); ! Convert the returned string to uppercase.

IF keypad_name <> '0'
THEN

   CASE keypad_name

      "EDT"      :  eve_set_keypad_edt ();
      "NOEDT"    :  eve_set_keypad_noedt ();
      "WPS"      :  eve_set_keypad_wps ();
      "NOWPS"    :  eve_set_keypad_nowps ();
      "NUMERIC"  :  eve_set_keypad_numeric ();
      "VT100"    :  eve_set_keypad_vt100 ();
      [INRANGE, OUTRANGE]  :  eve_set_keypad_numeric; ! If you have
                                                      ! used invalid value,
                                                      ! set the keypad to
                                                      ! NUMERIC setting.

   ENDCASE;

ENDIF;

    :
    :
    :

ENDPROCEDURE;
      

To provide a value for the GET_DEFAULT statement to fetch, an X defaults file would contain an entry similar to the following:

User.Keypad : EDT
      

Format

{array|integer|string|unspecified}:= GET_GLOBAL_SELECT ({PRIMARY|SECONDARY|selection_name} , selection_property_name)

Parameters

PRIMARY

A keyword indicating that the layered application is requesting information about a property of the primary global selection.

SECONDARY

A keyword indicating that the layered application is requesting information about a property of the secondary global selection.

selection_name

A string identifying the global selection whose property is the subject of the layered application's information request. Specify the selection name as a string if the layered application needs information about a selection other than the primary or secondary global selection.

selection_property_name

A string specifying the property whose value the layered application is requesting.

Return Values

array

An array that passes information about a global selection whose contents describe information that is not of a data type supported by DECTPU.

DECTPU does not use or alter the information in the array; the application layered on DECTPU is responsible for determining how the information is used, if at all. Because the array is used to receive information from other DECwindows applications, all applications that exchange information whose data type is not supported by DECTPU must adopt a convention on how the information is to be used.

The element array {0} contains a string that names the data type of the information being passed. For example, if the information being passed is a span, the element contains the string "SPAN". The element array {1} contains either the integer 8, indicating that the information is passed as a series of bytes, or the integer 32, indicating that the information is passed as a series of longwords. If array {1} contains the value 8, the element array {2} contains a string and there are no array elements after array {2}. The string does not name anything, but rather is a series of bytes of information. As mentioned, the meaning and use of the information is agreed upon by convention among the DECwindows applications. To interpret this string, the application can use the SUBSTR built-in procedure to obtain substrings one at a time, and the ASCII built-in procedure to convert the data to integer format if necessary. For more information about using these DECTPU elements, see the description of the SUBSTR and ASCII built-in procedures.

If array {1} contains the value 32, the element array {2} and any subsequent elements contain integers. The number of integers in the array is determined by the application that responded to the request for information about the global selection. The interpretation of the data is a convention that must be agreed upon by the cooperating application. To determine how many longwords are being passed, an application can determine the length of the array and subtract 2 to allow for elements array {0} and array {1}.)

integer

The value of the specified global selection property. The return value is of type integer if the value of the specified global selection property is of type integer.

string

The value of the specified global selection property. The return value is of type string if the value of the specified global selection property is of type string.

unspecified

A data type that indicates that the information requested by the layered application was not available.

Description

The GET_GLOBAL_SELECT procedure supplies information about a global selection. If an owner for the global selection exists, and if the owner provides the information requested in a format that DECTPU can recognize, GET_GLOBAL_SELECT returns the information.

Signaled Errors

Example

The following example fetches the text in the primary global selection and assigns it to the variable string_to_paste:

string_to_paste := GET_GLOBAL_SELECT (PRIMARY, "STRING");
      

For another example of how to use the GET_GLOBAL_SELECT built-in procedure, see Example A-3.

Description

The GET_INFO procedure returns information about the current status of the editor.

For information on how to get a screen display of the status of your editor, see the description of the SHOW built-in procedure.

This description provides general information on the GET_INFO built-in procedures. Included are descriptions of individual GET_INFO built-ins. The individual GET_INFO built-ins are grouped according to the value of their first parameter. For a list of the groups of GET_INFO built-ins, see Table 2-3.

All GET_INFO built-in procedures have the following two characteristics in common:

• They return a value that is the piece of information you have requested.
• They consist of the GET_INFO statement followed by at least two parameters, as follows:
  • The first parameter specifies the general topic about which you want information. If you want the GET_INFO built-in to return information on a given variable, use that variable as the first parameter. For example, if you want to know what row contains the cursor in a window stored in the variable command_window, you would specify the variable command_window as the first parameter. For example:

    the_row := GET_INFO (command_window, "current_row");

    
    Otherwise, the first parameter is a keyword specifying the general subject about which GET_INFO is to return information. The valid keywords for the first parameter are as follows:

    ARRAY
    BUFFER
    COMMAND_LINE
    DEBUG
    DEFINED_KEY
    KEY_MAP
    KEY_MAP_LIST
    mouse_event_keyword
    PROCEDURES
    PROCESS
    SCREEN
    SYSTEM
    WIDGET
    WINDOW

    
    For a list of valid mouse event keywords, see Table 2-4.
    Do not confuse a GET_INFO built-in whose first parameter is a keyword (such as ARRAY) with a GET_INFO built-in whose first parameter is a variable of a given data type, such as array_variable. For example, the GET_INFO (array_variable) built-in procedure shows what string constants can be used when the first parameter is an array variable; the GET_INFO (ARRAY) built-in shows what can be used when the first parameter is the ARRAY keyword.
  • The second parameter (a DECTPU string) specifies the exact piece of information you want.
  • The third and subsequent parameters, if necessary, provide additional information that DECTPU uses to identify and return the requested value or structure.

Each GET_INFO built-in procedure in this section shows the possible return values for a given combination of the first and second parameters. For example, the GET_INFO (any_variable) built-in shows that when you use any variable as the first parameter and the string "type" as the second parameter, GET_INFO returns a keyword for the data type of the variable.

Depending upon the kind of information requested, GET_INFO returns any one of the following:

• An array
• A buffer
• An integer
• A keyword
• A marker
• A process
• A range
• A string
• A window

DECTPU maintains internal lists of the following items:

• Arrays
• Array elements
• Breakpoints
• Buffers
• Defined keys
• Key maps
• Key map lists
• Processes
• Windows

You can step through an internally maintained list by using "first", "next", "previous", or "last" as the second parameter to GET_INFO. The order in which DECTPU maintains these lists is private and may change in a future version. Do not write code that depends on a list being maintained in a particular order. When you write code to search a list, remember that DECTPU keeps only one pointer for each list. If you create nested loops that attempt to search the same list, the results are unpredictable.

For example, suppose that a program intended to search two key map lists for common key maps sets up a loop within a loop. The outer loop might contain the following statement:

GET_INFO (KEY_MAP, "previous", name_of_second_key_map)

The inner loop might contain the following statement:

GET_INFO (KEY_MAP, "next", name_of_first_key_map)

In DECTPU, the behavior of such a nested loop is unpredictable.

Unless documented otherwise, the order of the internal list is not defined.

The syntax of GET_INFO depends on the kind of information you are trying to get. For more information on specific GET_INFO built-in procedures, see the descriptions in this section. GET_INFO built-ins whose first parameter is a keyword are grouped separately from GET_INFO built-ins whose first parameter is a variable.

Table 2-3 GET_INFO Built-In Procedures by First Parameter

Variable	Keyword	Any Keyword or Key Name
GET_INFO (any_variable)	GET_INFO (ARRAY)	GET_INFO (any_keyname)
GET_INFO (array_variable)	GET_INFO (BUFFER)	GET_INFO (any_keyword)
GET_INFO (buffer_variable)	GET_INFO (COMMAND_LINE)
GET_INFO (integer_variable)	GET_INFO (DEBUG)
GET_INFO (marker_variable)	GET_INFO (DEFINED_KEY)
GET_INFO (process_variable)	GET_INFO (KEY_MAP)
GET_INFO (range_variable)	GET_INFO (KEY_MAP_LIST)
GET_INFO (string_variable)	GET_INFO (mouse_event_keyword)
GET_INFO (widget_variable)	GET_INFO (PROCEDURES)
GET_INFO (window_variable)	GET_INFO (PROCESS)
	GET_INFO (SCREEN)
	GET_INFO (SYSTEM)
	GET_INFO (WIDGET)
	GET_INFO (WINDOW)

Signaled Errors

Examples

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

my_buffer := GET_INFO (BUFFERS, "current");

      

The following example stores the integer 1 or 0 in the variable is_buf_mod. A value of 1 means the current buffer has been modified. A value of 0 means the current buffer has not been modified.

is_buf_mod := GET_INFO (CURRENT_BUFFER, "modified");

      

The following example uses GET_INFO to find the top of the current window. It then removes the top five lines and replaces them with an example window.

PROCEDURE user_getinfo

   top_of_window := GET_INFO (CURRENT_WINDOW, "top", visible_window);

       ! Remove the top five lines from the main window
   ADJUST_WINDOW (CURRENT_WINDOW, +5, 0);

       ! Replace removed lines with an example window
   example_window := CREATE_WINDOW (top_of_window, 5, ON);
   example_buffer := CREATE_BUFFER ("EXAMPLE",
                                    "sys$login:template.txt");
   MAP (example_window, example_buffer);
ENDPROCEDURE;




      

The following example shows whether the key map list associated with the current buffer inserts undefined printable characters:

PROCEDURE show_self_insert

   LOCAL key_map_list_name;

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

   IF GET_INFO (key_map_list_name, "self_insert")
   THEN
      MESSAGE ("Undefined printable characters will be inserted");
   ELSE
      MESSAGE ("Undefined printable characters will cause an error");
   ENDIF;
ENDPROCEDURE;
      

Format

{integer|keyword} := GET_INFO (any_keyname, {"key_modifiers"|"key_type"| "unmodified"})

Parameters

"key_modifiers"

Returns a bit-encoded integer that indicates what key modifier or modifiers were used to create the DECTPU key name specified by the parameter any_keyname. For more information about the meaning and possible values of key modifiers, see the description of the KEY_NAME built-in procedure.

DECTPU defines four constants to be used when referring to or testing the numerical value of key modifiers. The correspondence between key modifiers, defined constants, and bit-encoded integers is as follows:

Key Modifier	Constant	Bit-Encoded Integer
SHIFT_MODIFIED	TPU$K_SHIFT_MODIFIED	1
CTRL_MODIFIED	TPU$K_CTRL_MODIFIED	2
HELP_MODIFIED	TPU$K_HELP_MODIFIED	4
ALT_MODIFIED	TPU$K_ALT_MODIFIED	8

You may have used the SHIFT_KEY keyword to create a DECTPU key name. SHIFT_KEY is not a modifier; it is a prefix. The Shift key is also called the GOLD key by the EVE editor. To use the Shift key, press and release it before you press any other key.

In DECwindows, to use modifying keys (such as Ctrl), press and hold the modifying key while you press the modified key.

If you use more than one key modifier with the KEY_NAME built-in procedure, the value of the returned integer is the sum of the integer representations of the key modifiers. For example, if you create a key name by using the modifiers HELP_MODIFIED and ALT_MODIFIED, the GET_INFO (any_keyname, "key_modifiers") built-in returns the integer 12.

"key_type"

Returns a keyword that describes the type of key named by any_keyname. The keywords that can be returned are PRINTING, KEYPAD, FUNCTION, CONTROL, SHIFT_PRINTING, SHIFT_KEYPAD, SHIFT_FUNCTION, and SHIFT_CONTROL. Returns 0 if parameter1 is not a valid key name. There are cases in which GET_INFO (any_keyname, "name") returns the PRINTING keyword but the key described by the key name is not associated with a printable character. For example, if you use the KEY_NAME built-in to define a key name as the combination of the character A and the ALT modifier, and if you then use GET_INFO (any_keyname, "name") to find out how DECTPU classifies the key, the GET_INFO built-in returns the PRINTING keyword. However, if you use the ASCII built-in to obtain the string representation of the key, the ASCII built-in returns a null string because ALT/A is not printable.

"unmodified"

Returns a keyword that describes the key name specified by any_keyname without any modifiers. For example, if you create a key name for the F20 key with the ALT_MODIFIED modifier, the GET_INFO (any_keyname, "unmodified") built-in returns the F20 keyword.

Return Values

integer

Returns requested information about the integer you specify.

keyword

Returns requested information about the keyword you specify.

Description

The GET_INFO (any_keyname) procedure returns a keyword that describes the type of key named by any_keyname.

For general information about using all forms of GET_INFO built-in procedures, see the description of GET_INFO.

Example

In the following example, the first statement creates a DECTPU key name for the key sequence produced by pressing the Ctrl key, the Shift key, and the 4 key on the keypad all at once. The new key name is assigned to the variable new_key. The second statement fetches the integer equivalent of this combination of key modifiers. The third statement displays the integer 3 in the message buffer. The IF clause of the fourth statement shows how to test whether a key name was created using a modifier. (This statement does not detect whether a key name was created using the SHIFT_KEY keyword.) The THEN clause shows how to fetch the key modifier keyword or keywords used to create a key name. The final statement displays the string KEY_NAME (KP4, SHIFT_MODIFIED, CTRL_MODIFIED) in the message buffer.

new_key := KEY_NAME (KP4, SHIFT_MODIFIED, CTRL_MODIFIED);
modifier_value := GET_INFO (new_key, "key_modifiers");
MESSAGE (STR (modifier_value));
IF GET_INFO (new_key, "key_modifiers")
THEN
    the_name := GET_INFO (new_key, "name")
    MESSAGE (STR (the_name));
ENDIF;