|
The WIDGET_PROPERTYSHEET function creates a property sheet widget, which exposes the properties of an IDL object subclassed from the IDLitComponent class in a graphical interface. The property sheet widget must be a child of a base or tab widget, and it cannot be the parent of any other widget.
The property sheet widget exposes the properties of an IDL object that subclasses from the IDLitComponent class, which was designed for use by the IDL iTools system. As a result, all IDLit* objects subclass from IDLitComponent, so properties of object classes written for the IDL iTools system can be displayed in a property sheet. In addition, all IDLgr* objects subclass from IDLitComponent, which means that properties of standard IDL graphics objects can be displayed in a property sheet even if the rest of the iTools framework is not in use.
In order to be shown in a property sheet, object properties must be registered and visible. In addition, in order for property values shown in a property sheet to be editable by the user, the property must be sensitive. For information on registering properties, see Registering Properties. For information on making properties visible and sensitive, see Property Attributes.
Result = WIDGET_PROPERTYSHEET(Parent [, /ALIGN_BOTTOM |, /ALIGN_CENTER |, /ALIGN_LEFT |, /ALIGN_RIGHT |, /ALIGN_TOP] [, /CONTEXT_EVENTS] [, EVENT_FUNC=STRING] [, EVENT_PRO=STRING] [, FONT=STRING] [, FUNC_GET_VALUE=STRING] [, KILL_NOTIFY=STRING] [, /NO_COPY] [, NOTIFY_REALIZE=STRING] [, PRO_SET_VALUE=STRING] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SENSITIVE] [, /TRACKING_EVENTS] [, UNAME=STRING] [,UNITS={0 | 1 | 2}] [, UVALUE=VALUE] [, VALUE=VALUE] [, XOFFSET=VALUE] [, XSIZE=VALUE] [, YOFFSET=VALUE] [, YSIZE=VALUE])
The returned value of this function is the widget ID of the newly-created property sheet widget.
The widget ID of the parent for the new property sheet widget. Parent must be a base or tab widget.
Set this keyword to align the new widget with the bottom of its parent base. To take effect, the parent must be a ROW base.
Set this keyword to align the new widget with the center of its parent base. To take effect, the parent must be a ROW or COLUMN base. In ROW bases, the new widget will be vertically centered. In COLUMN bases, the new widget will be horizontally centered.
Set this keyword to align the new widget with the left side of its parent base. To take effect, the parent must be a COLUMN base.
Set this keyword to align the new widget with the right side of its parent base. To take effect, the parent must be a COLUMN base.
Set this keyword to align the new widget with the top of its parent base. To take effect, the parent must be a ROW base.
Set this keyword to cause context menu events (or simply context events) to be issued when the user clicks the right mouse button over the widget. Set the keyword to 0 (zero) to disable such events. Context events are intended for use with context-sensitive menus (also known as pop-up or shortcut menus); pass the context event ID to the WIDGET_DISPLAYCONTEXTMENU procedure within your widget program's event handler to display the context menu.
For more on detecting and handling context menu events, see "Context-Sensitive Menus" in Chapter 26 of the Building IDL Applications manual.
| Note |
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.
A string containing the name of a procedure 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.
The name of the font to be used by the widget. The font specified is a device font (an X Windows font on Motif systems; a TrueType or PostScript font on Windows systems). See "About Device Fonts" in Appendix I of the IDL Reference Guide manual for details on specifying names for device fonts. If this keyword is omitted, the default font is used.
| Note |
A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user.
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 the null 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.
| Note |
Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large.
If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. During a set operation (using the UVALUE keyword to WIDGET_BASE or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. During a get operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined.
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. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument.
A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently
Set this keyword to the desired screen width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword.
Set this keyword to the desired screen height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword.
Set this keyword to control the initial sensitivity state of the widget.
If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input.
Sensitivity can be used to control when a user is allowed to manipulate the widget.
| Note |
After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure.
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 IDL Reference Guide manual in the documentation for WIDGET_BASE.
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.
Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters.
The user value to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created.
If UVALUE is not present, the widget's initial user value is undefined.
The user value for a widget can be accessed and modified at any time by using the GET_UVALUE and SET_UVALUE keywords to the WIDGET_CONTROL procedure.
Set this keyword to the object reference or array of object references to objects that subclass from the IDLitComponent class. Registered properties of the specified objects will be displayed in the property sheet.
If a single object reference is supplied, the property sheet will have a single column containing the object's properties. If an array of object references is supplied, the property sheet will have multiple columns.
| Note |
| Note |
If no object references are supplied, the property sheet will initially be empty. Object references can be loaded into an existing property sheet using the SET_VALUE keyword to WIDGET_CONTROL.
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 bulletin board base widget. Note that it is best to avoid using this style of widget layout.
The desired width, in average character widths, for the widget's font, not including a possible vertical scrollbar and any frame thickness. If neither XSIZE nor SCR_XSIZE is specified, then the property sheet widget will use a default width. This default width is computed by adding the room needed for the property names to the width of a color cell.
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 bulletin board base widget. Note that it is best to avoid using this style of widget layout.
The desired height of the widget, in number of visible properties. The ultimate height of the property sheet in pixels will include the heights of the column header, the possible horizontal scrollbar, and any frame. If neither YSIZE nor SCR_YSIZE is specified, the property sheet will use a default height. This default is based on the number of rows: 10, or the number of visible properties, whichever is less.
A number of keywords to the WIDGET_CONTROL affect the behavior of property sheet widgets. In addition to those keywords that affect all widgets, the following keyword is particularly useful: REFRESH _PROPERTY.
Some keywords to WIDGET_INFO return information that applies specifically to property sheet widgets. In addition to those keywords that apply to all widgets, the following keywords are particularly useful: COMPONENT, PROPERTY_VALID, PROPERTY_VALUE.
Several variations of the property sheet widget event structure depend upon the specific event being reported. All of these structures contain the standard three fields (ID, TOP, and HANDLER) as well as an integer TYPE field that indicates which type of structure has been returned or which type of event was generated. Programs should always check the type field before referencing fields that are not present in all property sheet event structures. The different property sheet widget event structures are described below.
This event is generated whenever the user enters a new value for a property. It is also used to signal that a user-defined property needs to be changed. The following statement defines the event structure returned by the WIDGET_EVENT function:
{WIDGET_PROPSHEET_CHANGE, ID:0L, TOP:0L, HANDLER:0L, TYPE:0L,
COMPONENT:OBJREF, IDENTIFIER:"", PROPTYPE:0L, SET_DEFINED: OL}
The COMPONENT field contains an object reference to the object associated with the property sheet. When multiple objects are associated with the property sheet, this field indicates which object is to change.
The IDENTIFIER field specifies the value of the property's identifier attribute. This identifier is unique among all of the component's properties.
The PROPTYPE field indicates the type of the property (integer, string, etc.). The integer values for these types are:
The SET_DEFINED field indicates whether or not an undefined property is having its value set. In most circumstances, along with its new value, the property should have its UNDEFINED attribute set to zero. If a property is never marked as undefined, this field can be ignored.
The select event is generated whenever the current row or column in the property sheet changes. Navigation between cells is performed by clicking on a cell. When the property sheet is realized, no cell is selected.
The following statement defines the event structure returned by the WIDGET_EVENT function:
{WIDGET_PROPSHEET_SELECT, ID:0L, TOP:0L, HANDLER:0L, TYPE:0L,
COMPONENT:OBJREF, IDENTIFIER:""}
The COMPONENT field is an object reference to the object associated with the property sheet.
The IDENTIFIER field specifies the value of the property's identifier attribute. This identifier is unique among all properties of the component.
Enter the following program in the IDL Editor:
; ExSinglePropSheet
;
; Creates a base with a property sheet. Only the
; default properties are visible. The property sheet's
; event handler sets values and reveals selection
; changes.
PRO PropertyEvent, event
IF (event.type EQ 0) THEN BEGIN ; Value changed.
; Get the value of the property identified by
; event.identifier.
value = WIDGET_INFO(event.id, COMPONENT = event.component, $
PROPERTY_VALUE = event.identifier)
; Set the component's property value.
event.component -> SetPropertyByIdentifier, event.identifier, $
value
PRINT, 'Changed: ', event.identifier, ': ', value
ENDIF ELSE BEGIN ; Selection changed.
PRINT, 'Selected: ' + event.identifier
ENDELSE
END
PRO ExSinglePropSheet_event, event
prop = WIDGET_INFO(event.top, $
FIND_BY_UNAME = 'PropSheet')
WIDGET_CONTROL, prop, XSIZE = event.x, YSIZE = event.y
END
PRO CleanupEvent, baseID
WIDGET_CONTROL, baseID, GET_UVALUE = oComp
OBJ_DESTROY, oComp
END
PRO ExSinglePropSheet
; Create and initialize the component.
oComp = OBJ_NEW('IDLitVisAxis')
; Create a base and property sheet.
base = WIDGET_BASE(/TLB_SIZE_EVENT, $
TITLE = 'Single Property Sheet Example', $
KILL_NOTIFY = 'CleanupEvent')
prop = WIDGET_PROPERTYSHEET(base, VALUE = oComp, $
EVENT_PRO = 'PropertyEvent', UNAME = 'PropSheet')
; Activate the widgets.
WIDGET_CONTROL, base, SET_UVALUE = oComp, /REALIZE
XMANAGER, 'ExSinglePropSheet', base, /NO_BLOCK
END
Save this program as ExSinglePropSheet.pro, then compile and run the program. A property sheet entitled Single Property Sheet Example is displayed:
For examples of the types of settings possible from the property sheet:
Hide from the list.Introduced: 6.0