NAME: SPD_UI_SPINNER PURPOSE: A compound 'spinner' widget for editing numerical values. Consists of up and down buttons and a text field for display and direct editing. CALLING SEQUENCE: Result = SPINNER(parent) KEYWORD PARAMETERS: VALUE: Initial value (float/double) INCREMENT: Numerical ammount spinner value is incremented/decremented LABEL: String to be used as the widget's label UNITS: String containing the units to appear to the right of the value SPIN_TIME: Delay before 'spinning' when clicking up/down buttons XLABELSIZE: Size of the text label in points getXLabelSize: Set to a named variable to pass back the length of the spinner's label in points TEXT_BOX_SIZE: Size of the text box in # of characters TOOLTIP: String to be used at the buttons' tooltip MAX_VALUE: The maximum allowed value for the spinner (optional) MIN_VALUE: The minimum allowed value for the spinner (optional) EVENT STRUCTURE: When the field is modified (either directly) or by the up/down buttons, the following event is returned: {ID: id, TOP: top, HANDLER: handler, VALUE: value, VALID: valid} VALUE: formatted, double precision number from widget's text field; value is NaN when the text widget contains an unrecognizable or unconvertable number VALID: 0 if value is not a recogizable/convertable number, or if buttons attempt to go outside min/max range, 1 otherwise GETTING/SETTINGS VALUES Using get_value from widget_control will return the same as the VALUE field in the event structure. The set_value procedure expects numerical input (e.g. doubles, floats, ints). Use spd_ui_spinner_set_max_value/spd_ui_spinner_set_min_value to change max_value, min_value. spd_ui_spinner_get_max_value/spd_ui_spinner_get_min_value return MAX_VALUE, MIN_VALUE NOTES: (lphilpott 06/10/11) Setting the max_value and min_value will restrict the use of the up and down buttons to reach values outside that range. They do not impact on values that are typed into the text field (these should be handled by the calling function) or any values simply passed to the set_value procedure. (lphilpott 06/15/11) Use of VALID: VALID=0 if the event is not valid. This includes non-recognizable numbers but ALSO cases where the user tries to go outside the allowed min-max range using up and down buttons. If the user clicks the up/down button and reaches the limit, the value returned is the limit value and valid=0. If the user enters a non numerical value the value returned is NAN and valid=0 This allows the calling procedure to issue messages to the user such as invalid entry based on both VALUE and VALID. Note: valid = 0 only if the starting value of the spinner is at the bounds. If the user holds down the buttons and reaches the bounds valid = 1. This avoids problems where existing code processes events only if event.valid = 1. I have not used max and min to restrict values typed into the field due to the difficulty of knowing when the user has finished typing - do not want to reset the value while the user is still entering it. When using a spinner cases where the user types in a value outside the allowed range need to be handled, also invalid entries. If necessary warning messages should be issued to user when they use the up/down buttons and have reached the allowed limits. Added get and set procedures for min and max designed to be called externally, eg. spd_ui_spinner_set_max_value Idea is to allow max and min to be set in case they need to be changed after spinner is created (e.g for range spinners where allowed values depend on whether scaling is linear or log) HISTORY: $LastChangedBy: $ $LastChangedDate: $ $LastChangedRevision: $ $URL: $