The WIDGET_WINDOW function creates a graphics widget.
Example
The following lines create a simple widget application. For a more complete example, see the end of this topic.
wBase = WIDGET_BASE(/COLUMN)
wDraw = WIDGET_WINDOW(wBase, X_SCROLL_SIZE=400, Y_SCROLL_SIZE=400)
WIDGET_CONTROL, wBase, /REALIZE
WIDGET_CONTROL, wDraw, GET_VALUE=oWin
oWin.Select
p = PLOT(/TEST, /CURRENT, /FILL_BACKGROUND)
Syntax
Result = WIDGET_WINDOW(Parent [, DRAG_NOTIFY=string] [, /DROP_EVENTS] [, EVENT_FUNC=string] [, EVENT_HANDLER=objref] [, FRAME=integer] [, GROUP_LEADER=widget ID] [, IGNORE_ACCELERATORS=value] [, KEYBOARD_HANDLER=function] [, KILL_NOTIFY=string] [, MOUSE_DOWN_HANDLER=function] [, MOUSE_MOTION_HANDLER=function] [, MOUSE_UP_HANDLER=function] [, MOUSE_WHEEL_HANDLER=function] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, RENDERER={0|1}] [, RESOURCE_NAME=string] [, SELECTION_CHANGE_HANDLER=function] [, SENSITIVE=0] [, TOOLTIP=string] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0|1|2}] [, UVALUE=variable] [, X_SCROLL_SIZE=value] [, Y_SCROLL_SIZE=value] [, XSIZE=value] [, YSIZE=value] [, XOFFSET=value] [, YOFFSET=value])
Return Value
The returned value of this function is the widget ID of the newly-created widget.
Arguments
Parent
The widget ID of the parent widget.
Keywords
Keywords are applied only during the initial creation of the graphic.
DRAG_NOTIFY
Set this keyword equal to a string containing the name of a function that will be automatically called as the end-user drags over the widget. Alternatively, set this keyword equal to the string <default> (including the < and > characters) to use the system default callback. See the WIDGET_DRAW routine for details on using this keyword.
DROP_EVENTS
Use this keyword to specify whether or not the widget will generate drop events when the user drags an item onto the draw area with the mouse cursor and releases the mouse button. A value of 1 (one) causes the widget to generate drop events and a value of 0 (zero) causes the widget to not generate drop events. The default is to not generate drop events. Specifying a DRAG_NOTIFY callback does not affect a widget’s ability to generate drop events. See the WIDGET_DRAW routine for details on using this keyword.
EVENT_FUNC
A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget.
EVENT_HANDLER
Set this property to an object reference to be used when events are received by the window. The object must be a subclass of GraphicsEventAdapter. See Creating an Event Handler Class to Control Events for details on how to write this object class.
Note: The EVENT_HANDLER class is intended to be a convenient alternative to the procedural event handlers. If you specify both the EVENT_HANDLER property and an event handler function (MOUSE_DOWN_HANDLER for example), then the object method will be called first. If the object method returns a value of 1, then execution will continue and the handler function will then be called. If the object method returns 0, then the handler function will not be called and the default event handling will also be skipped.
FRAME
The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a hint to the toolkit, and may be ignored in some instances.
GROUP_LEADER
The widget ID of an existing widget that serves as “group leader” for the newly-created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed.
A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group.
IGNORE_ACCELERATORS
Set this keyword to specify what WIDGET_BUTTON accelerators are to be ignored when this graphics widget has keyboard focus. Setting IGNORE_ACCELERATORS allows a defined list of accelerators to be processed by the graphics widget instead of by the conflicting accelerated button. Valid values are:
- A string or string array containing any value that is legal for WIDGET_BUTTON’s ACCELERATOR keyword
- The number 1, indicating all accelerators should be ignored
Ordinarily, accelerators are processed before keyboard events reach the widget that has the keyboard focus. Setting IGNORE_ACCELERATORS allows a defined list of accelerators to be processed by the graphics widget instead of by associated buttons or menu items. Once the graphics widget loses focus, all specified accelerators are automatically re-enabled.
See Disabling Button Widget Accelerators for usage details and examples.
KEYBOARD_HANDLER
Set this property to the name of a function that will be called when a key is pressed or released. See Creating Keyboard Event Functions for details on how to write these functions.
Tip: Instead of writing separate functions for each of the event handlers, you may find it convenient to create a single object class and use the EVENT_HANDLER property instead.
KILL_NOTIFY
Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such “callback” procedure. It can be removed by setting the routine to an empty string ('').
The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called.
MOUSE_DOWN_HANDLER
Set this property to the name of a user-defined function that is called when the mouse button is pressed.
MOUSE_MOTION_HANDLER
Set this property to the name of a user-defined function that is called when the mouse is moved.
MOUSE_UP_HANDLER
Set this property to the name of a user-defined function that is called when the mouse button is released.
MOUSE_WHEEL_HANDLER
Set this property to the name of a user-defined function that is called when the mouse wheel is moved.
Note: See Creating Functions to Control Mouse Events for details on how to write the mouse event functions.
Tip: Instead of writing separate functions for each of the mouse event handlers, you may find it convenient to create a single object class and use the EVENT_HANDLER property instead.
NO_COPY
Set this keyword to 1 to take the data away from the UVALUE variable and attach it directly to the widget. After the WIDGET_WINDOW function returns, the UVALUE variable will then be undefined. This keyword is ignored if UVALUE is not present.
NOTIFY_REALIZE
Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such “callback” procedure. The callback routine is called with the widget ID as its only argument.
RENDERER
Set this keyword to an integer value indicating which graphics renderer to use when drawing objects within the window. Valid values are:
- 0 = Platform native OpenGL
- 1 = IDL’s software implementation
By default, your platform’s native OpenGL implementation is used. If your platform does not have a native OpenGL implementation, IDL’s software implementation is used regardless of the value of this property.
RESOURCE_NAME
A string containing an X Window System resource name to be applied to the widget. See RESOURCE_NAME for a complete discussion of this keyword.
SELECTION_CHANGE_HANDLER
Set this property to the name of a function that is called when a graphic is selected or deselected. See Creating Selection Change Event Handlers for details on how to write these functions.
Tip: Instead of writing separate functions for each of the event handlers, you may find it convenient to create a single object class and use the EVENT_HANDLER property instead.
SENSITIVE
Set this keyword to 0 to turn off all event processing for the widget. The default is 1, which enables all event processing. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure.
TOOLTIP
Set this keyword to a string that will be displayed when the cursor hovers over the widget. For UNIX platforms, this string must be non-zero in length.
TRACKING_EVENTS
Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see TRACKING_EVENTS in the documentation for WIDGET_BASE.
UNAME
Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.
To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.
UNITS
Set this keyword to specify the units used when supplying measurements or position values. Set UNITS equal to 0 to specify that all measurements are in pixels (this is the default), to 1 to specify that all measurements are in inches, or to 2 to specify that all measurements are in centimeters. This keyword does not change the units used in a widget event structure or in most of the fields of the geometry structure returned by WIDGET_INFO.
UVALUE
The “user value” to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. If UVALUE is not present, the widget’s initial user value is undefined.
X_SCROLL_SIZE
The width of the widget in units specified by the UNITS keyword (pixels are the default). By default X_SCROLL_SIZE is set equal to XSIZE.
Y_SCROLL_SIZE
The height of the widget in units specified by the UNITS keyword (pixels are the default). By default Y_SCROLL_SIZE is set equal to YSIZE.
XSIZE
The width of the graphics window (the drawing area) in units specified by the UNITS keyword (pixels are the default). If XSIZE is larger than X_SCROLL_SIZE then scroll bars will be automatically added. By default, XSIZE is set equal to X_SCROLL_SIZE. If neither XSIZE nor X_SCROLL_SIZE is passed in, then the width is set to 640 pixels.
YSIZE
The height of the graphics window (the drawing area) in units specified by the UNITS keyword (pixels are the default). If YSIZE is larger than Y_SCROLL_SIZE then scroll bars will be automatically added. By default, YSIZE is set equal to Y_SCROLL_SIZE. If neither YSIZE nor Y_SCROLL_SIZE is passed in, then the height is set to 512 pixels.
XOFFSET
The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent.
Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout.
YOFFSET
The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget.
Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout.
Keywords to WIDGET_CONTROL
A number of keywords to the WIDGET_CONTROL procedure affect the behavior of graphics widgets. In addition to those keywords that affect all widgets, the following are particularly useful: DRAW_XSIZE, DRAW_YSIZE, GET_DRAW_VIEW, GET_VALUE, IGNORE_ACCELERATORS, INPUT_FOCUS, SET_DRAW_VIEW, TOOLTIP.
Keywords to WIDGET_INFO
A number of keywords to the WIDGET_INFO function return information that applies specifically to graphics widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: GEOMETRY, TOOLTIP.
Example
The following example creates an IDL widget application with a main graphics window, and a status bar at the bottom. When you move the mouse around the window, the X and Y locations are displayed in the status bar.
Save all of the following code into a file named "widget_window_ex.pro". Then, from within IDL, compile and run the code.
FUNCTION WIDGET_WINDOW_EX_MOUSE_DOWN_EVENT, $
win, x, y, button, keymods, clicks
COMPILE_OPT idl2
state = win.uvalue
IF(button eq 1 && keymods eq 2) then begin
state['drag'] = 1
state['start'] = [x,y]
RETURN, 0
ENDIF
return, 1
END
FUNCTION WIDGET_WINDOW_EX_MOUSE_UP_EVENT, win, x, y, button
COMPILE_OPT idl2
state = win.uvalue
state['drag'] = 0
RETURN, 1
END
FUNCTION WIDGET_WINDOW_EX_MOUSE_MOTION_EVENT, win, x, y, keymods
COMPILE_OPT idl2
state = win.uvalue
IF(state['drag']) then begin
difference = [x,y] - state['start']
new_center = state['center'] + difference[0]
new_width = state['width'] + difference[1]
new_brain = SET_WINDOW(state['image'], new_center, new_width)
win['display'].setdata, new_brain
return, 0
ENDIF
RETURN, 1
END
FUNCTION SET_WINDOW, image, center, width
COMPILE_OPT idl2
lo = center - 0.5*width
hi = center + 0.5*width
RETURN, BYTSCL((image > lo) < hi)
END
PRO WIDGET_WINDOW_EX
COMPILE_OPT idl2
brain = READ_IMAGE(FILE_WHICH('mr_brain.dcm'))
center = 1011
width = 2021
brain_scaled = SET_WINDOW(brain, center, width)
wtop = WIDGET_BASE(/COLUMN, $
TITLE='Graphics event handling with IDL widgets')
wdraw = WIDGET_WINDOW(wtop, $
MOUSE_DOWN_HANDLER='widget_window_ex_mouse_down_event', $
MOUSE_UP_HANDLER='widget_window_ex_mouse_up_event', $
MOUSE_MOTION_HANDLER='widget_window_ex_mouse_motion_event')
WIDGET_CONTROL, wtop, /REALIZE
WIDGET_CONTROL, wdraw, GET_VALUE=w
g = IMAGE(brain_scaled, /CURRENT, TITLE='MR: Brain', NAME='display')
g.SCALE, 1.5, 1.5, 1.0
t = TEXT(0.5,0.02, $
['Hold <Ctrl> and drag horizontally to change brightness,', $
'drag vertically to change contrast'], $
ALIGNMENT='center')
state = HASH()
state['image'] = brain_scaled
state['drag'] = 0
state['start'] = [0,0]
state['center'] = center
state['width'] = width
w.uvalue = state
WIDGET_CONTROL, wtop, SET_UVALUE=w
XMANAGER, 'widget_window_ex', wtop, /NO_BLOCK
END
Version History
|
8.0 |
Introduced |
| 8.1 |
Added the following properties: KEYBOARD_HANDLER, MOUSE_DOWN_HANDLER, MOUSE_MOTION_HANDLER, MOUSE_UP_HANDLER, MOUSE_WHEEL_HANDLER, SELECTION_CHANGE_HANDLER |
| 8.2 |
Remove the following properties: BUTTON_EVENTS, EXPOSE_EVENTS, KEYBOARD_EVENTS, MOTION_EVENTS, VIEWPORT_EVENTS, WHEEL_EVENTS. |
| 8.2.1 |
Properties added: EVENT_HANDLER
|
See Also
!COLOR, WIDGET_DRAW,
WINDOW