| ActiveTcl User Guide |

Table of Contents

## Name

dial - Create and manipulate dial widgets

## Synopsis

dial pathName ?options? -activebackground -background -border-width -cursor -font -foreground -highlightbackground -high-lightcolor -highlightthickness -relief -repeatdelay -repeatinter-val -takefocus

## Widget-specific Options

The angle at which the scale of the dial will start. The value is in degrees. Zero is at the top and the angle increases clockwise, just like a compass. If you want the scale to start at the left, use a nega-tive value, not the value above 180 degrees. Some interactions with the dial cause its value to change by â€˜â€˜largeâ€™â€™ increments; this option specifies the size of the large increments. If specified as 0, the large increments default to 1/10 the range of the dial. Specifies the prefix of a Tcl command to invoke whenever the dialâ€™s value is changed via a widget command. The actual command consists of this option followed by a space and a real number indicating the new value of the dial. Specifies whether the value for the dial should be con-strained to the given from and to values and the resolution. If true, the it is limited to the value range and to the nearest resolution. Otherwise, only the displayed value (which is always constrained) is constrained. Defaults to 0. Specifies the border width for the inner dial. Defaults to 3. Specifies the color for the inner dial. Defaults to the normal background. Specifies the relief for the inner dial. Defaults to the raised. An integer specifying how many signifi-cant digits should be retained when converting the value of the dial to a string. If the number is less than or equal to zero, then the dial picks the smallest value that guarantees that every possible dial posi-tion prints as a different string. The angle at which the scale of the dial will end. The value is in degrees. Zero is at the top and the angle increases clockwise, just like a compass. A real value corre-sponding to the counterclockwise-most end of the dial. A string to display as a label for the dial. The label is displayed above the dial. If the option is specified as an empty string, no label is dis-played. Specifies the color for the needle. Defaults to black. Spec-ifies a type for the needle: arc, line, or triangle. arc draws the needle as a filled arc from the from value to the current value. line draws the needle as a thick line at the value. triangle draws the nee-dle as a thin triangle at the value (compass style). Defaults to line. Must be a real value. Determines the spacing between minor tick marks, those without a numerical value or tag. These ticks are also slightly smaller. If 0 (default), no minor tick marks will be displayed. See tickinterval for more details. Specifies the desired radius of the central dial of the dial in screen units (i.e. any form acceptable to Tk_GetPixels). A real value specifying the resolution for the dial. If this value is greater than zero then the dialâ€™s value will always be rounded to an even multiple of this value, as will tick marks and the endpoints of the dial. If the value is less than zero then no rounding occurs. Defaults to 1 (i.e., the value will be integral). Specifies a boolean value indicating whether or not the current value of the dial is to be displayed. Specifies which tags to display at normal tick marks on the dial: value (default), label, both, or none. If value, then the value is always displayed. If label, then only labels speci-fied by the tag command are displayed. all refers to both of the above, and none causes neither to be displayed. Specifies one of three states for the dial: normal, active, or disabled. If the dial is dis-abled then the value may not be changed and the dial wonâ€™t activate. If the dial is active, the dial is displayed using the color specified by the activeBackground option. Specifies the color to be used for the ticks. Defaults to black. Must be a real value. Determines the spac-ing between tick marks displayed with their numeric value or a tag around the dial. This spacing is calculated at tickinterval counts around the dial between the from and to values. If from is 0.0 and to is 100.0, then a tickinterval of 10.0 will place 11 ticks (at 0.0, 10.0, 20.0, ...) on the dial. If 0 (default), no tick marks will be displayed. Specifies the width of the line that ticks are displayed with. 0, the default, means a simple line. If you donâ€™t wish to dis-play ticks, set the tick intervals to 0. Specifies a real value corre-sponding to the clockwise-most end of the dial. This value may be either less than or greater than the from option. Specifies the name of a global variable to link to the dial. Whenever the value of the variable changes, the dial will update to reflect this value. Whenever the dial is manipulated interactively, the variable will be modified to reflect the dialâ€™s new value.

Further options are handled by the dial widget in order to maintain 100% compatibility with the scale widget. These options are not guar-anteed to translate correctly for use by the dial, but they will not cause an error in code.

## Description

The dial command creates a new window (given by the pathName argument) and makes it into a dial widget. Additional options, described above, may be specified on the command line or in the option database to con-figure aspects of the dial such as its colors and relief. The dial command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathNameâ€™s parent must exist.

A dial is a widget that displays a circular dial with a small mark. The position of the dial selects a particular real value of the scale which is determined by the from, to, and resolution options. The dial may be turned (and hence the dialâ€™s value changed) with the mouse or keyboard as described in the BINDINGS section below. Whenever the dialâ€™s value is changed, a Tcl command is invoked (using the command option) to notify other interested widgets of the change. In addition, the value of the dial can be linked to a Tcl variable (using the variable option), so that changes in either are reflected in the other. The dial is modelled after the Tk scale widget and is 100% compatible with the commands and options for a scale.

Five annotations may be displayed in a dial widget: a label appearing at the top left of the widget, a number displaying the current value just below the dial, a collection of major tick marks, numerical or string labels next to the major tick marks and a collection of minor tick marks. Each of these five annotations may be enabled or disabled using the configuration options.

## Widget Command

The dial command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form: pathName option ?arg arg ...? Option and the args determine the exact behavior of the command. The following commands are possible for dial widgets:

pathName cget option
Returns the current value of the configuration option given by option. Option may have any of the values accepted by the dial command.

pathName configure ?option? ?value option value ...? Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for infor-mation on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the dial command.

pathName coords ?value?
Returns a list whose elements are the x and y coordinates of the point along the radius of the dial that corresponds to value. If value is omitted then the dialâ€™s current value is used.

pathName get ?x y?
If x and y are omitted, returns the current value of the dial. If x and y are specified, they give pixel coordinates within the widget; the command returns the dial value corresponding to the given pixel.

pathName identify x y
Returns a string indicating what part of the dial lies under the coordinates given by x and y. A return value of dial means that the point is over the dial; left means that the point is to the left of the dial, and right means that the point is to the right of the dial.

pathName label ?-constrain? ?value? ?string? ?value string ...? This command will associate a string label with a specific value. The value should correspond to a major tick value. It is important that the correct resolution is used for the value (constrained by the tickinterval), as the label will otherwise not be shown. You can use the -constrain option to cause the given value to be constrained to a valid tick value, ensuring that the label will be displayed. This means that given values are open to be changed. Constraining is bound to the current value of tickinterval. When this value changes, so would the constraints. However, constrained tags are not tracked to the change in tickinterval, so changing that could cause tags to not be displayed. All the known labels can be seen when no argu-ments are given. If only a value is given, then the label for that value will be shown, if any. Otherwise, each given value will be assigned the given string. Labels are shown when speci-fied by the showtags option. pathName set ?value? This command is invoked to change the current value of the dial, and hence the orientation of the dial. Value gives the new value for the dial. If no value is given, this behaves like a get and simply returns the current value of the dial. The set command has no effect if the dial is disabled.

## Bindings

Tk automatically creates class bindings for dials that give them the following default behavior.

[1]
  If button 1 is pressed at the area around the dial, the dialâ€™s value will be incremented or decremented by the value of the resolution option. If you press left of the dial, the dial will turn counterclockwise; if you press at the right it turns clock-wise. If the button is held down, the action auto-repeats.
[2]
  If button 1 is pressed over the dial, the dial is turned towards the mouse cursor. If the button is held down, the dial orienta-tion can be dragged with the mouse.
[3]
  If button 1 is pressed at the surrounding with the Control key down, the dial turns all the way to the end of its range. If the cursor was at the left, it goes to the lower limit; if it was at the right, it goes to the upper limit.
[4]
  The Down and Left keys turn the dial counterclockwise by the value of the resolution option.
[5]
  The Up and Right keys turn the dial clockwise by the value of the resolution option.
[6]
  Control-Down and Control-Left turn the dial counterclockwise by the value of the bigIncrement option.
[7]
  Control-Up and Control-Right turn the dial clockwise by the value of the bigIncrement option.
[8]
  Home turns the dial to the lower end of its range.
[9]
  End moves the dial to the higher end of its range.

If the dial is disabled using the state option then none of the above bindings have any effect.

The behavior of dials can be changed by defining new bindings for indi-vidual widgets or by redefining the class bindings.

## Keywords

dial, widget

## Tk 2.0 dial(n)

Table of Contents

- Name
- Synopsis
- Widget-specific Options
- Description
- Widget Command
- Bindings
- Keywords
- Tk 2.0 dial(n)