WwControlsBox Function

Reference Guide > W Routines > WwControlsBox Function

Creates a box containing sliders.

Usage

controls = WwControlsBox(parent, [labels,] range, changedCallback)

Input Parameters

parent — The widget ID of the parent widget.

labels — (optional) A string or array of strings containing the text used to label the sliders. If the labels parameter is not defined or is defined as a null string or an array of null strings, the function looks for slider labels in a resource specification (see Discussion).

range — An array of values specifying the minimum and maximum slider values.

changedCallback — A string containing the name of the callback routine that is executed when the value of a slider changes.

Returned Value

controls — The widget ID of the controls box widget.

Input Keywords

Border — Specifies width in pixels of the controls box and slider borders.

Center — An array specifying the position of the left and right edge of sliders as a percentage of controls box width. By default, buttons are spaced evenly in the box.

Drag — If present and nonzero, the callback procedure is called while the slider is being dragged.

Float — Lets you display a floating-point slider, with ranges that include implied decimal numbers. This keyword specifies the number of digits that appear after the decimal point. For example, to display a floating-point slider with the range 0.5 to 12.5, use:

controls=WwControlsBox(parent, 'myslider',[5, 125], $
'mycallback', Float=1)

The decimal point is implied in that it is used for display purposes only. If the user chooses a slider value of 5.7, the value returned to the callback is 57. The value of Float can be obtained through the Userdata keyword of the WwGetValue function. Thus, you can obtain the implied decimal position that was used in a WwControlsBox function. For example:

PRO mycallback, wid, which
  ndec = WwGetValue(wid, /Userdata)
  value = WwGetValue(wid)
  PRINT, 'User Selected Value: ', Float(value)/10.0^ndec

note	If you pass floating point values to the range parameter, be sure to set the Float keyword as well. Otherwise, the value returned by the function will be unexpected.

Form — When present and nonzero, sliders are placed in a form layout and all specified attachment keywords are honored (i.e., /Left, /Right, /Top, /Bottom). By default, sliders are placed in a row/column layout.

Height — Specifies the height of the sliders. (Unix only.)

Horizontal — When present and nonzero, creates a horizontally aligned row of sliders.

Hslider — When present and nonzero, creates horizontally oriented sliders.

Layout_name — Specifies the name of the layout widget. This name is part of the resource specification. The default name for Layout_name depends on other keywords specified in the WwControlsBox usage.

If Form or Horizontal or Vertical are used to organize the sliders, the Layout_name default is controls.

If the Form widget is used to organize the slider and Text is also specified, the default for Layout_name is ctrlform.

Measure — Specifies the number of columns of sliders (for a vertical box) or rows (for a horizontal box).

Name — Specifies an array of strings containing the names of the Scale widget and, optionally, the TextField widget if Text is also specified. The Name keyword can be used in place of the labels parameter, although labels (if other than an array of null strings) will take precedence if both are given. (Default: slider_0, text_0, slider_1, text_1, ..., slider_n, text_n.)

NoValueDisplay — If present and nonzero, the slider value text field above the slider will not be displayed.

Position — If the controls box widget is to be placed in a bulletin board layout, use this keyword to specify the x, y coordinates of the controls box widget within the bulletin board.

Spacing — Specifies the space between sliders.

Tab_WinOff — (Windows only) If this keyword is present and nonzero, the tab navigation feature is turned off for this widget.

Text — When present and nonzero, an input text field is created for each slider.

Vertical — When present and nonzero, creates a vertically aligned column of sliders.

Vslider — When present and nonzero, creates vertically oriented sliders.

Width — Specifies the width of the sliders. (Unix only.)

Output Keywords

Sliders — Returns an array of slider widget IDs.

Color/Font Keywords

Background — Specifies the background color name.

Basecolor — Specifies the base color.

Font — Specifies the name of the font used for slider text.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Attachment Keywords

Bottom — If a widget ID is specified (for example, Bottom=wid), then the bottom of the controls box widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the controls box widget is attached to the bottom of the parent widget.

Left — If a widget ID is specified (for example, Left=wid), then the left side of the controls box widget is attached to the right side of the specified widget. If no widget ID is specified (for example, /Left), then the left side of the controls box widget is attached to the left side of the parent widget.

Right — If a widget ID is specified (for example, Right=wid), then the right side of the controls box widget is attached to the left side of the specified widget. If no widget ID is specified (for example, /Right), then the right side of the controls box widget is attached to the right side of the parent widget.

Top — If a widget ID is specified (for example, Top=wid), then the top of the controls box widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the controls box widget is attached to the top of the parent widget.

Get/Set Value

getvalue — Gets the value of the selected slider.

setvalue — Sets the value of the selected slider.

Callback Parameters

Any controls box callback procedure must have the following two parameters:

wid — Slider widget ID.

index — Index value of the slider that has changed (1 – n).

Discussion

A “controls box” is a special widget in which individual sliders are arranged. If only one slider is requested, that slider’s widget ID is returned. By default, the sliders are placed in a row/column format.

A slider allows the user to change a value interactively by moving the slider handle back and forth within a predefined range. You have the option of including a text input field with each slider. The text input field lets the user enter an exact value for the slider.

The widget name portion of the slider label resource specification can be specified using the Name keyword.

note

The labels parameter provides a method for “hard-coding” the slider labels in the application. For greater flexibility, create your slider label resource file using a text editor, and load the resources containing the slider labels and text strings using WtResource. The Name keyword can then be used in the WwControlsBox calling sequence to specify the slider (and text) widget names.

Example 1

This example creates a box with three sliders labeled Pressure, RPM, and Temperature. Whenever the user moves one of the sliders, the callback procedure is executed.

Enter the callback procedure into a file, and compile the procedure with the .RUN command. Then, enter the widget commands at the WAVE> prompt. To dismiss the controls box, select the appropriate function (such as Close) from the window manager menu.

PRO SliderCB, wid, which

   CASE which OF

      1: PRINT,'First Slider Moved'

      2: PRINT,'Second Slider Moved'

      3: PRINT,'Third Slider Moved'

   ENDCASE

   value = WwGetValue(wid)

   PRINT, value

END

PRO ww_ex22

   top=WwInit('ww_ex22', 'Examples', layout)

   labels=['Pressure','RPM','Temperature']

   ranges=[0,100,2000,4000,50,150]

   controls = WwControlsBox(layout, labels, $

      ranges, 'SliderCB',/Vertical,/Text, $

      Foreground='gray',Background='white', $

      Basecolor='blue')

   status=WwSetValue(top, /Display)

   WwLoop

END

Example 2

A typical resource specification used in WwControlsBox is:

myapp.layout.sliderform.xslider.titleString: X Rotation