|
|
IDL Reference Guide: IDL GUIBuilder Widget Reference |
|
Use text widgets to display text, and optionally, use them to accept textual input from users. The text widgets can have one or more lines, and if necessary, the widget can contain scroll bars to allow for viewing longer text.
When programming in IDL, you create text widgets using the WIDGET_TEXT function. For more information, see WIDGET_TEXT.
| Note Use text widgets for displaying large amounts of text, or when you want the user to be able to edit the text. Use label widgets to display single-line labels that the user cannot edit. |
For text widgets, you can set common attributes and text-specific attributes. For a list of common attributes, see Common Attributes. The following are the attributes specific to text widgets:
The Editable attribute determines if the text widget is editable or not. By default, this value is set to False, which means the text widget is not editable. To make the text widget editable, set this value to True.
In the generated *.pro file, this value is specified with the EDITABLE keyword to the widget creation routine.
The Height attribute specifies the height of the text widget in text lines. Valid values for this attribute are 1 to n. The default value, is 1, or one text line.
Note that the physical height of the text widget depends on the value of the Height attribute and on the size of the font used. The default font size is used, unless you modify your generated code to use a different font, and the default font size is platform specific.
In the generated *.pro file, this value is specified by the YSIZE keyword to the widget creation routine.
The Initial Value attribute specifies the initial array of values that are placed in the text widget. You can enter either a string or an array of strings.
To enter more than one string in the Value field, type in a string, then press Control+Enter (at the end of each line). This moves you to the next line. When you have entered the strings you want, press Enter to set the values.
In the generated *.pro file, this value is specified by the VALUE keyword to the widget creation routine.
| Note Variables returned by the GET_VALUE keyword to WIDGET_CONTROL are always string arrays, even if a scalar string is specified in the call to WIDGET_TEXT. |
The Scroll attribute determines if the text widget displays scroll bars. By default, this value is set to False, which indicates that no scroll bars will be displayed. To have the text widget display scroll bars, set this value to True.
In the generated *.pro file, this value is specified by the SCROLL keyword to the widget creation routine.
The Tab Mode attribute specifies what support the widget has for receiving or losing focus through tabbing. By default, this value is set to Inherit.
| Note It is not possible to tab to disabled (Sensitive = False) or hidden (Visible = False) widgets. |
Allowable values are:
| Note The default tab mode of a widget is Inherit. The tabbing support defined for the parent base, described in Base Widget Attributes, is inherited by widget children unless otherwise specified. |
| Note In widget applications on the UNIX platform, the Motif library controls what widgets are brought into and released from focus using tabbing. The TAB_MODE keyword value is always zero, and any attempt to change it is ignored when running a widget application on the UNIX platform. Tabbing behavior may vary significantly between UNIX platforms; do not rely on a particular behavior being duplicated on all UNIX systems. |
In the generated *.pro file, this value is specified with the TAB_MODE keyword to the widget creation routine. For more information on tabbing among widgets, see Tabbing in Widget Applications.
The Width attribute specifies the width of the text widget in characters. Valid values for this attribute are 0 to n. By default, Width is set to 0, which indicates that default IDL sizing should be used when, as long as default Component Sizing is also set.
Note that the physical width of the text widget depends on the value of the Width attribute and on the size of the font used. The default font size varies according to your windowing system. On Windows, the default size is roughly 20 characters. On Motif, the default size depends on the system default.
In the generated *.pro code, this value is specified with the XSIZE keyword.
The Word Wrapping attribute determines whether scrolling or multi-line text widgets should automatically break lines between words to keep the text from extending past the right edge of the text display area. By default this value is set to False, and carriage returns are not automatically entered; the value of the text widget will remain a single-element array. To have the text widget enter carriage returns at the end of lines, change this value to True.
In the generated *.pro code, this value is specified with the WRAP keyword.
For text widgets, you can set common event properties and text-specific event properties. By default, event values are not set. For a list of events common to all widgets, see Common Events.
You can set the following event values for text widgets:
The OnContextEvent value is the routine name that is called when the user clicks the right-hand mouse button over the text widget. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when the user clicks the right-hand mouse button and is of the following type:
{WIDGET_CONTEXT, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L}
The X and Y fields give the device coordinates at which the event occurred, measured from the upper left corner of the text widget.
The OnDelete value is the routine that is called when text is deleted from the text widget. To set this event value, you must set the Editable attribute to True.
In the generated *_eventcb.pro file, the calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when any amount of text is deleted from a text widget.
The event structure is of the following type:
{ WIDGET_TEXT_DEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:2, OFFSET:0L,
LENGTH:0L }
OFFSET is the (zero-based) character position of the first character to be deleted, and it is also the insertion position that will result when the characters have been deleted. LENGTH gives the number of characters deleted, where 0 (zero) indicates that no characters were deleted.
The OnFocus value is the routine that is called when the keyboard focus changes. In the generated *_eventcb.pro event code, the calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the returned structure, which is of the following type:
{ WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 }
ENTER returns 1 if the text widget is gaining the keyboard focus, or 0 if the text widget is losing the keyboard focus.
The OnInsertCh value is the routine that is called when a single character is inserted in the widget. To set this event value, you must set the Editable attribute to True.
In the generated *_eventcb.pro file, the calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when a single character is typed or pasted into a text widget by a user.
The event structure is of the following type:
{ WIDGET_TEXT_CH, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, OFFSET:0L,
CH:0B }
OFFSET is the (zero-based) insertion position that will result after the character is inserted. CH is the ASCII value of the character.
The OnInsertString value is the routine that is called when a text string is inserted in the text widget. To set this event value, you must set the Editable attribute to True.
In the generated *_eventcb.pro file, the calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when multiple characters are inserted in to text widget. The event structure is of the following type:
{ WIDGET_TEXT_STR, ID:0L, TOP:0L, HANDLER:0L, TYPE:1, OFFSET:0L,
STR:'' }
OFFSET is the (zero-based) insertion position that will result after the text is inserted. STR is the string to be inserted.
The OnTextSelect value is the routine that is called when text is selected in the text widget. To set this event value, you must also set the Editable attribute to True.
In the generated *_eventcb.pro file, the calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when an area of text is selected. The event structure is of the following type:
{ WIDGET_TEXT_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:3, OFFSET:0L,
LENGTH:0L }
This event announces a change in the insertion point. OFFSET is the (zero-based) character position of the first character selected, which can also be the insertion position. LENGTH gives the number of characters involved, where zero indicates that no characters are selected.
| Note Text insertion, text deletion, or any change in the current insertion point causes any current selection to be lost. In such cases, the loss of selection is implied by the text event reporting the insert, delete, or movement event, and a separate zero length selection event is not sent. |
IDL Online Help (March 06, 2007)