Document revision date: 30 March 2001
[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

GET_INFO (widget_variable)

Format

{array |integer |learn_sequence |program |string |widget} := GET_INFO (widget_variable,


{"callback_routine" |"class" |"input_focus" |"insertion_position" |"is_managed" |"is_subclass", widget_class |"name" |"parent" |"resources" |"text" |"widget_info", {array |arg_pair [[, arg_pair... ]]}})

Parameters

"callback_routine"

Returns the program or learn sequence designated as the application's callback routine for the specified widget. This is the program or learn sequence that DECTPU should execute when a widget callback occurs for the specified widget. For more information about callbacks, see the Guide to the DEC Text Processing Utility.

"class"

Returns the name of the class to which the specified widget belongs.

"input_focus"

Returns 1 if the specified widget has input focus; otherwise, it returns 0.

You cannot set or get the input_focus state of a widget unless that widget is a shell widget that has a resource named XtNinput.

"insertion_position"

Returns the location of the insertion position in the specified text widget. The insertion position is between characters in a text widget and starts at position 0 when to the left of the first character. Returns the NONE keyword if the specified widget is not a text widget.

"is_managed"

Returns 1 if the specified widget is managed; otherwise, it returns 0.

"is_subclass"

Returns 1 if the specified widget belongs to the class referred to by the specified integer or belongs to a subclass of that class. A 1 value indicates only that the widget is equal to or is a subclass of the specified class. The value does not indicate how far down the class hierarchy the widget's class or subclass is. If the widget is not in the class, or one of its subclasses, this GET_INFO call returns 0.
widget_class The integer specifying the widget class to use in the subclass test. This value is returned from the DEFINE_WIDGET_CLASS built-in procedure.

"name"

Returns a string that is the name of the specified widget.

"parent"

Returns the parent of the specified widget. If the widget has no parent, the call returns 0.

"resources"

Returns a string-indexed array in which each index is a valid resource name for the specified widget. The corresponding array element is a string that contains the resource's data type and class, separated by a line feed (ASCII (10)).

"text"

Returns a string that is the value of the specified simple text widget. (The value of a text widget is the text you enter into the text widget in response to a prompt in a dialog box.)

If the specified widget is not a text widget, DECTPU returns the NONE keyword.

"widget_info"

Returns the current values for one or more resources of the specified widget. The values are returned in the array or series of argument pairs that is passed as the third parameter. The integer on the left side of the assignment operator indicates whether the built-in executed successfully.

The third parameter is either an array or a series of paired arguments, specified as follows:
array Each array index must be a string that names a valid resource for the specified widget. Resource names are case sensitive. The corresponding array element contains the value of the resource. The array can contain any number of elements.
arg_pair A string that names a valid resource for the widget followed by a variable to store the value of the resource. Separate the resource name string from the variable with a comma and a space, as follows: resource_name_string, resource_value

  You can fetch as many resources as you want by using multiple pairs of arguments.

If you specify the name of a resource that the widget does not support, DECTPU signals the error TPU$_ARGMISMATCH.

If the requested resource is a list of items and the list contains no entries, the GET_INFO call uses either the element of the array parameter or the value parameter to return an array that has no elements.

For more information about specifying resources, see the Guide to the DEC Text Processing Utility.

Return Values


array

Returns requested information about the array you specify.

integer

Returns requested information about the integer you specify.

learn_sequence

Returns requested information about the learn sequence you specify.

program

Returns requested information about the program you specify.

string

Returns requested information about the string you specify.

widget

Returns requested information about the widget you specify.

Description

The GET_INFO (widget_variable) procedure returns information about a specified widget variable.

Use the GET_INFO (widget_variable) built-in procedure with DECwindows only.

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

Examples

The following example executes the callback routine for the widget eve$x_replace_dialog. The statement is valid only after the Replace dialog box has been used at least once because EVE does not create any dialog box until you have invoked it.
#1 

EXECUTE (GET_INFO (eve$x_replace_dialog, 
                    "callback_routine"));

The following example displays the name of the widget specified by the variable eve$x_replace_dialog. To confirm that the widget has been created as expected, the procedure also displays a message that identifies the data type of the variable's contents. The procedure is valid only after the Replace dialog box has been used at least once because EVE does not create any dialog box until you have invoked it.

A statement that contains the GET_INFO (widget, "name") built-in procedure is useful in code implementing a debugging command that evaluates DECTPU statements, expressions, and variables.

#2 

PROCEDURE sample_return_name 
 
LOCAL status; 
 
status := GET_INFO (eve$x_replace_dialog, 
                    "name"); 
 
MESSAGE ("The data type of status is: "); 
MESSAGE (STR (GET_INFO(status, "type"))); 
MESSAGE ("The value of status is: "); 
MESSAGE (STR (status)); 
 
ENDPROCEDURE;

The following example creates an EVE file name dialog box widget and assigns the widget to the variable eve$x_needfilename_dialog. Next, the fragment assigns to the variable the_value a string that prompts you for the name of a file to which the buffer's contents should be written. The fragment uses the GET_INFO (WIDGET, "widget_id") built-in procedure to assign the dialog box's label widget to the variable child_of_box. Finally, the fragment assigns to the label widget's "labelString" resource the string contained in the_value.

#3 

eve$x_needfilename_dialog := CREATE_WIDGET ("NEEDFILENAME_DIALOG", 
                                             eve$X_widget_hierarchy, 
                                             SCREEN, 
                                             eve$kt_callback_routine); 
 
the_value := "Type filename for writing buffer " + 
                            get_info (the_buffer, "name"); 
 
 
child_of_box := get_info (WIDGET, "widget_id", 
                          eve$x_needfilename_dialog, 
                          "NEEDFILENAME_DIALOG.NEEDFILENAME_LABEL"); 
 
status := set (WIDGET, child_of_box, "labelString", the_value);

GET_INFO (WINDOW)

Format

window := GET_INFO (WINDOW[[S]], {"current" |"first" |"last" |"next" |"previous"})

Parameters

"current"

Returns the current window on the screen; returns 0 if there is none. GET_INFO (WINDOW[[S]], "current") always returns the current window, regardless of whether you have first used GET_INFO (WINDOW[[S]], "first") or GET_INFO (WINDOW[[S]], "last").

"first"

Returns the first window in DECTPU's internal list of windows; returns 0 if there is none.

"last"

Returns the last window in DECTPU's internal list of windows; returns 0 if there is none.

"next"

Returns the next window in DECTPU's internal list of windows; returns 0 if there are no more windows in the list. Use "current" or "first" before "next".

"previous"

Returns the preceding window in DECTPU's internal list of windows; returns 0 if there are no previous windows in the list. Use "current" or "last" before "previous".

Return Value


Returns the requested information about the window you specify.

Description

The GET_INFO (WINDOW) procedure returns a window from DECTPU's internal list of windows or the current window on the screen.

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

GET_INFO (window_variable)

Format

{buffer |integer |keyword |string |widget |window} := GET_INFO (window_variable,


{"before_bol" |"beyond_eob" |"beyond_eol" |"blink_status" |"blink_video" |"bold_status" |"bold_video" |"bound" |"bottom" [[, WINDOW |, TEXT |, VISIBLE_WINDOW |, VISIBLE_TEXT]] |"buffer" |"current_column" |"current_row" |"display_value" |"key_map_list" |"left" [[, WINDOW |, TEXT |, VISIBLE_WINDOW |, VISIBLE_TEXT]] |"length" [[, WINDOW |, TEXT |, VISIBLE_WINDOW |, VISIBLE_TEXT]] |"middle_of_tab" |"next" |"no_video" |"no_video_status" |"original_bottom" |"original_length" |"original_top"}

{"pad" |"previous" |"reverse_status" |"reverse_video" |"right" [[, WINDOW |, TEXT |, VISIBLE_WINDOW |, VISIBLE_TEXT]] |"screen_update" |"scroll" |"scroll_amount" |"scroll_bar", [[HORIZONTAL |VERTICAL]] |"scroll_bar_auto_thumb", [[HORIZONTAL |VERTICAL]] |"scroll_bottom" |"scroll_top" |"shift_amount" |"special_graphics_status" |"status_line" |"status_video" |"text" |"top" [[, WINDOW |, TEXT |, VISIBLE_WINDOW |, VISIBLE_TEXT]] |"underline_status" |"underline_video" |"video" |"visible" |"visible_bottom" |"visible_length" |"visible_top" |"width" [[, WINDOW |, TEXT |, VISIBLE_WINDOW |, VISIBLE_TEXT]]})

Parameters

"before_bol"

Returns an integer (1 or 0) that indicates whether the cursor is to the left of the current line's left margin. The return value has no meaning if "beyond_eob" is true. Returns 0 if the window you specified is not mapped.

"beyond_eob"

Returns an integer (1 or 0) that indicates whether the cursor is below the bottom of the buffer. Returns 0 if the window you specified is not mapped.

"beyond_eol"

Returns an integer (1 or 0) that indicates whether the cursor is beyond the end of the current line. The return value has no meaning if "beyond_eob" is true. Returns 0 if the window you specified is not mapped.

"blink_status"

Returns an integer (1 or 0) that indicates whether BLINK is one of the video attributes of the window's status line. Use the SET (STATUS_LINE) built-in procedure to establish or change this parameter.

"blink_video"

Returns an integer (1 or 0) that indicates whether BLINK is one of the video attributes of the window. Use the SET (VIDEO) built-in procedure to establish or change this parameter.

"bold_status"

Returns an integer (1 or 0) that indicates whether BOLD is one of the video attributes of the window's status line. Use the SET (STATUS) built-in procedure to establish or change this parameter.

"bold_video"

Returns an integer (1 or 0) that indicates whether BOLD is one of the video attributes of the window. Use the SET (VIDEO) built-in procedure to establish or change this parameter.

"bound"

Returns an integer (1 or 0) that indicates whether the cursor is located on a character.

"bottom"

Returns an integer that is the number of the last row or last visible row of the specified window, or the specified window's text area. The window row whose number is returned depends on the keyword you specify as the third parameter. If you do not specify a keyword, the default is TEXT. Valid keywords for the third parameter when the second parameter is "bottom", "left", "length", "right", "top", or "width" are listed in Table 2-6.

Table 2-6 GET_INFO (Window_Variable): Valid Keywords for the Third Parameter
Keyword Definition
TEXT A keyword that directs the built-in to return the specified (left, right, top, or bottom) window row or column or the number of window rows or columns on which text can be displayed. By specifying TEXT instead of VISIBLE_TEXT, you obtain information about a window's rows and columns even if they are invisible because the window is occluded. If the window is not occluded, the value returned is the same as the value returned with VISIBLE_TEXT.
VISIBLE_TEXT A keyword that directs the built-in to return the specified (left, right, top, or bottom) visible window row or column or the number of visible window rows or columns on which text can be displayed. When DECTPU determines a window's last visible text row, DECTPU does not consider the status line or the bottom scroll bar to be a text row.
VISIBLE_WINDOW A keyword that directs the built-in to return the specified (left, right, top, or bottom) visible window row or column or the number of visible window rows or columns in the window.
WINDOW A keyword that directs the built-in to return the specified (left, right, top, or bottom) window row or column or the number of window rows or columns in the window. By specifying WINDOW instead of TEXT, you get the window's last row or column, even if it cannot contain text because it contains a scroll bar or status line.

By specifying WINDOW instead of VISIBLE_WINDOW, you get information about a window's rows and columns even if they are invisible because the window is occluded. If the window is not occluded, the value returned is the same as the value returned with VISIBLE_WINDOW.

GET_INFO (window_variable, "bottom", TEXT) is a synonym for GET_INFO (window_variable, "original_bottom"). The call GET_INFO (window_variable, "bottom", VISIBLE_TEXT) is a synonym for GET_INFO (window_variable, "visible_bottom").

"buffer"

Returns the buffer that is associated with the window; returns 0 if there is none.

"current_column"

Returns an integer that is the column in which the cursor was most recently located.

"current_row"

Returns an integer that is the row in which the cursor was most recently located.

"display_value"

Returns the display value of the specified window.

"key_map_list"

Returns the string that is the name of the key map list associated with the window you specify.

"left"

Returns an integer that is the number of the leftmost column or leftmost visible column of the specified window, or the specified window's text area. The column whose number is returned depends on the keyword you specify as the third parameter. If you do not specify a keyword, the default is TEXT. Valid keywords are shown in Table 2-6.

"length"

Returns an integer that is the number of rows or visible rows in the specified window or the specified window's text area. The number of rows returned depends on the keyword you specify as the third parameter. If you do not specify a keyword, the default is TEXT. Valid keywords are shown in Table 2-6.

"middle_of_tab"

Returns an integer (1 or 0) that indicates whether the cursor is in the middle of a tab. The return value has no meaning if "beyond_eob" is true. This call returns 0 if the window you specified is not mapped.

"next"

Returns the next window in DECTPU's internal list of windows; returns 0 if there are no more windows in the list.

"no_video"

Returns an integer (1 or 0) that indicates whether the video attribute of the window is NONE. Use the SET (VIDEO) built-in procedure to establish or change this parameter.

"no_video_status"

Returns an integer (1 or 0) that indicates whether the video attribute of the window's status line is NONE. Use the SET (STATUS) built-in procedure to establish or change this parameter.

"original_bottom"

Returns an integer that is the screen line number of the bottom of the window when it was created or last adjusted (does not include status line or scroll bar). Compaq recommends that you use GET_INFO (window, "bottom", text) to retrieve this information.

"original_length"

Returns an integer that is the number of lines in the window when it was created. The value returned includes the status line. Compaq recommends that you use GET_INFO (window, "length", window) to retrieve this information.

"original_top"

Returns an integer that is the screen line number of the top of the window when it was created.

"pad"

Returns an integer (1 or 0) that indicates whether padding blanks have been displayed from column 1 to the left margin (if the left margin is greater than 1) and from the ends of lines to the right margin. Use the SET (PAD) built-in procedure to establish or change this parameter.

"previous"

Returns the previous window in DECTPU's internal list of windows; returns 0 if there are no previous windows in the list.

"reverse_status"

Returns an integer (1 or 0) that indicates whether REVERSE is one of the video attributes of the window's status line. Use the SET (STATUS) built-in procedure to establish or change this parameter.

"reverse_video"

Returns an integer (1 or 0) that indicates whether REVERSE is one of the video attributes of the window. Use the SET (VIDEO) built-in procedure to establish or change this parameter.

"right"

Returns an integer that is the number of the last column or last visible column of the specified window or the specified window's text area. The window column whose number is returned depends on the keyword you specify as the third parameter. If you do not specify a keyword, the default is TEXT. Valid keywords are shown in Table 2-6.

"screen_update"

Returns the update status of a window. A 0 indicates that updates are off. A 1 indicates that the window is updated normally. See the SET (SCREEN_UPDATE) built-in procedure in this chapter for more information.

"scroll"

Returns an integer (1 or 0) that indicates whether scrolling is enabled for the window. Use the SET (SCROLLING) built-in procedure to establish or change this parameter.

"scroll_amount"

Returns an integer that is the number of lines to scroll. Use the SET built-in procedure to establish or change this parameter.

"scroll_bar"

Use with DECwindows only.

Returns the specified scroll bar widget that implements the scroll bar associated with a window if it exists; otherwise it returns 0.

You must specify the HORIZONTAL or VERTICAL keyword as the third parameter to GET_INFO (window_variable, "scroll_bar"). HORIZONTAL directs DECTPU to return the window's horizontal scroll bar; VERTICAL directs DECTPU to return the window's vertical scroll bar.

"scroll_bar_auto_thumb"

Use with DECwindows only.

Returns an integer (1 or 0) that indicates whether automatic adjustment of the specified scroll bar slider is enabled. Returns 1 if automatic adjustment is enabled and 0 if it is disabled.

You must specify the HORIZONTAL or VERTICAL keyword as the third parameter to GET_INFO (window_variable, "scroll_bar_auto_thumb"). HORIZONTAL directs DECTPU to return information about the window's horizontal scroll bar; VERTICAL directs DECTPU to return information about the window's vertical scroll bar.

"scroll_bottom"

Returns an integer that is the bottom of the scrolling area, an offset from the bottom screen line. Use the SET (SCROLLING) built-in procedure to establish or change this parameter.

"scroll_top"

Returns an integer that is the top of the scrolling area, an offset from the top screen line. Use the SET (SCROLLING) built-in procedure to establish or change this parameter.

"shift_amount"

Returns an integer that is the number of columns the window is shifted to the left.

"special_graphics_status"

Returns an integer (1 or 0) that indicates whether SPECIAL_GRAPHICS is one of the video attributes of the window's status line. Use the SET (STATUS_LINE) built-in procedure to establish or change this parameter.

"status_line"

Returns a string that is the text of the status line; returns 0 if there is none. Use the SET (STATUS_LINE) built-in procedure to establish or change this parameter.

"status_video"

If there is no video attribute or only one video attribute for the window's status line, the appropriate video keyword (NONE, BLINK, BOLD, REVERSE, UNDERLINE, or SPECIAL_GRAPHICS) is returned. If there are multiple video attributes for the window's status line, the integer 1 is returned. If there is no status line for the window, the integer 0 is returned. Use the SET (STATUS_LINE) built-in procedure to establish or change this parameter.

"text"

Returns a keyword that indicates which keyword was used with SET (TEXT). SET (TEXT) controls text display in a window. Valid keywords are as follows: BLANK_TABS, GRAPHIC_TABS, or NO_TRANSLATE.

"top"

Returns an integer that is the number of the first row or first visible row of the specified window or the specified window's text area. The window row whose number is returned depends on the keyword you specify as the third parameter. If you do not specify a keyword, the default is TEXT. Valid keywords are shown in Table 2-6.

"underline_status"

Returns an integer (1 or 0) that indicates whether UNDERLINE is one of the video attributes of the window's status line. Use the SET (STATUS_LINE) built-in procedure to establish or change this parameter.

"underline_video"

Returns an integer (1 or 0) that indicates whether UNDERLINE is one of the video attributes of the window. Use the SET (VIDEO) built-in procedure to establish or change this parameter.

"video"

If there is no video attribute or only one video attribute for the window, the appropriate video keyword (NONE, BLINK, BOLD, REVERSE, or UNDERLINE) is returned. If there are multiple video attributes for the window, the integer 1 is returned. If you get the return value 1 and you want to know more about the window's video attributes, use the specific parameters, such as "underline_video" and "reverse_video".

Use the SET (VIDEO) built-in procedure to establish or change this parameter.

"visible"

Returns an integer (1 or 0) that indicates whether the window is mapped to the screen and whether it is occluded.

"visible_bottom"

Returns an integer that is the screen line number of the visible bottom of the window (does not include status line). Use the ADJUST_WINDOW built-in procedure, create other windows, or map a window to change this value.

Compaq recommends that you use GET_INFO (window, "bottom", visible_text) to retrieve this information.

"visible_length"

Returns an integer that is the visible length of the window (includes status line). This value differs from the value returned by GET_INFO (window_variable, "original_length") in that the value returned by "visible_length" is the original length minus the number of window lines (if any) hidden by occluding windows. Use the ADJUST_WINDOW built-in procedure, create other windows, or map a window to change this value.

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