Panel: dial

Syntax

{<name>:} dial <start>,<finish> {,<value>}

Description

Dial sub-panel. A circular image with indicator arm which can be interactively moved by the mouse to change a numeric value within a given range. The image can be a default circular image with or without graduation ticks, or a user-supplied image.

Membership

• Panel window

• Tab window

• Table window.

Parameters

• <name>
  A name to be given to the sub-panel for reference purposes.

• <start>
  The value corresponding to the dial beginning. This is a numeric value.

• <finish>
  The value corresponding to the dial finish. This is a numeric value.

• <value>
  The initial dial value. This should be between <start> and <finish>. The default is<start>.

Switches

• -a1=<num>
  The angle of the start of the dial. If omitted the default is 225 degrees.

• -a2=<num>
  The angle of the finish of the dial. If omitted, the default is -45 degrees. If the start angle is greater than the finish angle, the dial values increase in a clockwise direction. If not, the values increase in a counterclockwise direction.

• -bc=<color>
  The background color for the dial box. If omitted, the background color of the window is used. If the dial is user-defined image dial this can provide the background color for the image. A value of no_change will use that of the parent window. This is applicable only to monochrome image files only.

• -cr=<file>
  Display a raster image. This should be the name of an image file and defines the dial to be in image form.

• -cx=<num>
  The x center of the dial in pixels measured from the top left corner of the image. This is only meaningful for user-defined image dials.

• -cy=<num>
  The y center of the dial in pixels measured from the top left corner of the image. This is only meaningful for user-defined image dials.

• -dim=<screen_xy>
  Define the dimensions of the dial in pixels. This is usually redundant because dials are by default created sized-to-fit, but is useful when the size needs to be overridden. This is a two-element numeric array providing width and height. If only one is required, the other can be set to -1 and will be ignored.

• -dp=<num>
  The number of decimal places to print when displaying and computing dial values. The default is 0.

• -fc=<color>
  The foreground color for the image. This is applicable only to monochrome images for user-defined image dials.

• -fo=<font>
  The font to be used for the text display of dial values. This must be a fixed font. If omitted the dial inherits the font of its parent row or column.

• -fra
  Enclose the dial within a 3-D frame. The default behavior is not to.

• -gh
  The sub-panel should be initially ghosted, i.e. insensitive to user-interaction.

• -icol=<color>
  The color of the dial indicator arm. If omitted, the text color is used.

• -inv
  Make the sub-panel invisible on creation.

• -ith=<num>
  The thickness of the dial indicator arm. If omitted, a thickness of 1 is used.

• -j=<just>
  The justification of the dial within its parent row or column. Within a parent row the value should be one of L, M, R. Within a parent column the value should be one of T, M or B. The default in both cases is M.

• -link=<text>
  The resize linkage for the panel. This ties panel edges to one or more edges of the parent window, with the result that when the parent window gets resized, the panel gets automatically resized as well. <text> is a combination of the characters L, R, T, B and M. A value of "LRTB" means that the left, right, top and bottom edges of a sub-panel are linked to its parent. The default value is "TL", which links the left and top edges to the parent window but does no resizing because its right and bottom edges are not linked. Note that the linkage is to edges of the parent window, not to column/row extremities. More complicated linkage requirements should be done via the window.resize callback on the parent window.

• -ng=<num>
  The number of graduations marked on the dial. The default is 10. This is ignored when the dial is a user-defined image.

• -num=<nums>
  Dial values to be shown in text form around the outside of the dial. This is a series or an array of numeric values. The default is not to show any values. This attribute is ignored when the dial is a user-defined image.

• -out
  Output only. The presence of this switch will prevent the value of the dial being changed interactively.

• -pj=<just>
  The position justification of the sub-panel within the panel window. This combined with the -x and -y switches can be used to position the sub-panel by one of its corners. The default is ’TL’. It also defines the control point to be used when repositioning the sub-panel after creation.

• -r=<num>
  The radius of the dial in pixels. A suitable value is computed when this is omitted. This is meaningful only for dials shown in image form.

• -res=<num>
  Used in conjunction with the -cr switch, this defines a scaling factor for the image. For example, a value of 0.5 will show the image half-size.

• -tc=<color>
  The color to use when displaying dial values (or the image frame color). If omitted the parent window "other color" is used.

• -th=<num>
  Draw a border of width <num> pixels around the image. The color used is the parent window "other color". This is applicable only to user-defined image dials.

• -x=<num>
  The x position of the dial relative to the top-left corner of its parent row or column. If omitted, the dial is placed adjacent to the previously defined sub-panel.

• -y=<num>
  The y position of the dial relative to the top-left corner of its parent row or column. If omitted, the dial is placed below the previously defined sub-panel.

Callbacks

Called while the dial is being dragged with mouse button one down.

<panel>.drag(<window>,<panel>{,<row})

• Panel/Tab Window

panel.drag {
    args w=window, p=panel
}

• Table Window

panel.drag {
    args w=window, p=panel, row=numeric
}

Called when mouse button 1 is released.

<panel>.exec(<window>,<panel>{,<row>})

• Panel/Tab Window

panel.exec {
    args w=window, p=panel
}

• Table Window

panel.exec {
    args w=window, p=panel, row=numeric
}

Notes

Switches -j, -pj, -x and -y apply only to dials within a panel window. Dials within other windows cannot have a user-defined position or justification.

Examples

Create a panel window containing a row of two dials both of default size.

window w = wpanel {
    row {
    # Eight graduations, khaki arm, red text.
        d1: dial 0,350,125,-ng=8,-ic=khaki,-tc=red,\ 
            -num=<0,50,100,150,200,250,300,350>
    # Six graduations, framed.
        d2: dial 0,2.5,1.25,-ng=6,-fra,-dp=1,\ 
            -num=<0,.5,1,1.5,2,2.5>
    }
}

Create a panel window containing a dial of specified size.

window w = wpanel {
# Six graduations, angles specified, thick arm
    d: dial 0,100,-ng=6,-a1=45,-a2=-225,-th=4,\ 
        -num=<0,20,40,60,80,100>,-dim=<150,150>
}

Create a panel window containing a read-only image dial with color changes.

window w = wpanel {
    d: dial 0,360,45,-cr='coffee.ras',-r=32,-out,\
        -a1=0,-a2=360,-cx=42,-cy=48,-ith=5,\ 
        -fc=red,-bc=no_change
}