|
|
IDL Reference Guide: IDL GUIBuilder Widget Reference |
|
Draw widgets are rectangular regions that IDL treats as standard graphics windows. Use draw widgets to display either IDL Direct graphics or IDL Object graphics, depending on the value of the Graphics Type attribute. You can direct any graphical output that can be produced by IDL to one of these widgets, either by using the WSET function or by using the object reference of a draw widget's IDLgrWindow object.
Draw widgets can contain scroll bars that allow for viewing of a graphical region larger than the area containing the widget.
When programming in IDL, you create draw area widgets using the WIDGET_DRAW function. For more information, see WIDGET_CONTROL.
For a draw area widget, you can set common attributes and draw area-specific attributes. For a list of common attributes, see Common Attributes. These are the draw area-specific attributes:
The Color Model attribute specifies the color model that should be used for displaying information on the draw widget. This attribute value is used only when the Graphics Type attribute is set to Object, for IDL Object Graphics. These are the possible values for the Color Model attribute:
In the generated *.pro file, this value is specified by the COLOR_MODEL keyword to the widget creation routine.
The Colors attribute specifies the number of colors that the drawable should attempt to use from the system color table. This attribute is only valid with the Graphics Type attribute is set to Direct, for IDL Direct Graphics. By default, the Color attribute is set to 0, which indicates that IDL will attempt to get all available colors. That is, all or most of the available color indices are allocated, based on the window system in use. You can set the Colors attribute to any integer, but most values will be in the range of -256 < n < 256.
This attribute has effect only if it is supplied when the first IDL graphics window is created. To use monochrome windows on a color display, set the Colors attribute to 2 for the first window. One color table is maintained for all running IDL windows.
In the generated *.pro file, this value is specified by the COLORS keyword to the widget creation routine.
The Graphics Type attribute specifies the type of graphics that the draw widget will support. These are the possible values:
In the generated *.pro file, this value is specified with the GRAPHICS_LEVEL keyword to the widget creation routine.
The Renderer attribute specifies which graphics renderer to use with IDL Object Graphics. That is, for this attribute to be used, the Graphics Type attribute should be set to Object. These are the possible values for the Renderer attribute:
In the generated *.pro file, this value is specified by the RENDERER keyword to the widget creation routine.
For more information, see Hardware vs. Software Rendering.
| Note The renderer selection can also affect the maximum size of a draw widget. |
The Retain attribute specifies how backing store is performed in the draw area. These are the possible values:
In the generated *.pro file, this value is specified with the RETAIN keyword to the widget creation routine.
For information on the use of the Retain attribute with Direct Graphics, see Backing Store in IDL Direct Graphics Devices. For more information on this attribute with IDL Object Graphics, see IDLgrWindow::Init.
The Scroll attribute specifies if the draw area widget will support scrolling, and will have scroll bars. By default, this value is set to False, which indicates there are no scroll bars. To display scroll bars, and enable scrolling, set this value to True. If you do so, set the size of the scrollable area with the X Scroll and Y Scroll properties.
In the generated *.pro file, this value is specified with the SCROLL keyword to the widget creation routine.
The Tooltip attribute specifies a short text string that will be displayed when the mouse cursor is positioned over the draw area. The length of the tooltip is not explicitly limited, but since tooltips are displayed in a single line, it is best to keep the text short.
The X Scroll attribute specifies the width in pixels of the drawing area. This width includes the exposed and virtual area. By default, this value is not set. You can set X Scroll to any width from 0 to n. If you set this value, also set the Scroll and Y Scroll attribute values.
In the generated *.pro file, this value is specified with the XSIZE keyword to the widget creation routine.
| Note To set the width of the displayed widget, use the X Size common attribute. |
The Y Scroll attribute specifies the height in pixels of the drawing area. This height includes the exposed and virtual area. By default, this value is not set. You can set Y Scroll to any height in pixels from 0 to n. If you set this value, also set the Scroll and X Scroll properties.
In the generated *.pro file, this value is specified with the YSIZE keyword to the widget creation routine.
| Note To set the height of the displayed widget, use the Y Size common attribute. |
For draw area widgets, you can set common event properties and draw area-specific event properties. By default, event values are not set. For a list of events common to all widgets, see Common Events.
These are the draw area event properties:
The OnButton value is the routine that is called when a mouse button event is detected. 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 returned event structure, which is of the following type:
{ WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0L, Y:0L,
PRESS:0B, RELEASE:0B, CLICKS:0, MODIFIERS:0L, CH:0, KEY:0L }
Note that this is the same event structure returned for all draw area events; OnButton, OnExpose, OnMotion, and OnViewportMoved events all return the same structure. Therefore the following paragraphs describe all these events.
TYPE returns a value that describes the type of draw widget interaction that generated an event. If there is a button press, it returns 0, and if there is a button release, it returns 1. If there is motion, it returns 2 (for an OnMotion event). If the viewport moved with the scroll bars, it returns 3 (for an OnViewportMoved event). If the visibility changes, it returns 4 (for an OnExpose event).
The X and Y fields give the device coordinates at which the event occurred, measured from the lower left corner of the drawing area.
PRESS and RELEASE are bitmasks in which the least significant bit represents the left-most mouse button. The corresponding bit of PRESS is set when a mouse button is pressed, and in RELEASE when the button is released. If the event is a motion event, both PRESS and RELEASE returns zero.
CLICKS returns either 1 or 2. If the time interval between button-press events is greater than the time interval for a double-click event for the system, the CLICKS field returns 1. If the time interval between two button-press events is less than the time interval for a double-click event for the platform, the CLICKS field returns 2.
The MODIFIERS field is valid for button press, button release, motion, and keyboard events. It is a bitmask which returns the current state of several keyboard modifier keys at the time the event was generated. If a bit is zero, the key is up. If the bit is set, the key is depressed. See Widget Events Returned by Draw Widgets for complete details.
Keyboard events are generated with the value of the TYPE field equal to 5 or 6. If the event was generated by an ASCII keyboard character, the TYPE field will be set to 5 and the ASCII value of the key will be returned in the CH field. (Note that ASCII values can be converted to the string representing the character using the IDL STRING routine.) If the event was generated due to a non-ASCII keyboard character, the type of the event will be set to 6 and a numeric value representing the key will be returned in the KEY field. See Widget Events Returned by Draw Widgets for complete details.
The OnExpose value is the routine that is called when the visibility of any portion of the draw window (or viewport) changes or is exposed. 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 returned event structure, which is of the following type:
{ WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0L, Y:0L,
PRESS:0B, RELEASE:0B, CLICKS:0, MODIFIERS:0L, CH:0, KEY:0L }
Note that this is the same event structure returned for all draw area events; OnButton, OnExpose, OnKeyboard, OnMotion, and OnViewportMoved events all return the same structure. For information on this structure, see OnButton.
The OnKeyboard value is the routine that is called when the user presses a key on the keyboard while the draw window has focus. 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 returned event structure, which is of the following type:
{ WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0L, Y:0L,
PRESS:0B, RELEASE:0B, CLICKS:0, MODIFIERS:0L, CH:0, KEY:0L }
Note that this is the same event structure returned for all draw area events; OnButton, OnExpose, OnKeyboard, OnMotion, and OnViewportMoved events all return the same structure. For information on this structure, see OnButton.
The OnMotion value is the routine that is called when a mouse motion event is detected. 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 returned event structure, which is of the following type:
{ WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0L, Y:0L,
PRESS:0B, RELEASE:0B, CLICKS:0, MODIFIERS:0L, CH:0, KEY:0L }
Note that this is the same event structure returned for all draw area events; OnButton, OnExpose, OnKeyboard, OnMotion, and OnViewportMoved events all return the same structure. For information on this structure, see OnButton.
The OnViewportMoved value is the routine that is called when the viewport of a scrolling draw widget is moved, using the scroll bars. 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 returned event structure, which is of the following type:
{ WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0L, Y:0L,
PRESS:0B, RELEASE:0B, CLICKS:0, MODIFIERS:0L, CH:0, KEY:0L }
Note that this is the same event structure returned for all draw area events; OnButton, OnExpose, OnKeyboard, OnMotion, and OnViewportMoved events all return the same structure. For information on this structure, see OnButton.
IDL Online Help (March 06, 2007)