Class - dh

dh_Knob:

Draws a knob with optional caption and optional display. Built upon the Lokasenna Knob. Changed some property names, and added many customizable features.

Basic Properties:

centered: If false then knob is positioned with x and y as the top-left of an imaginary square around knob body. If true then knob is positioned with x and y as the center of knob.

min: The minimum range of the knob (fully counter-clockwise). May be an integer or floating-point number.

max: The maximum range of the knob (fully clockwise). May be an integer or floating-point number.

inc: This is the value that the Knob's output changes with each step of the knob's rotation. May be an integer or floating-point number. The increment determines the number of steps in the knob's rotation: (max - min) / inc

default: This determines the initial value of the knob, and where it returns to when double-clicked. The default value must be an integer corresponding to a step in the knob's range (0 to steps), with 0 being fully ccw.

  min   max   inc   steps   def  val
   0     10    1     10      0    0
   0     10    1     10      5    5
-100    100    1    200    100    0
-100    100   10     20     10    0
   0      1    0.1   10      0    0
   0      1    0.1   10      5    0.5
  -1      1    0.1   20     10    0

knob_style:

Pointer: Displays a knob with a triangular pointer attached to the knob body.

Flange: Displays a knob with a flange and a central body. The indicator is a white line on a black flange.

Simple: Displays a round knob with the indicator on top.

travel: Accepts one of three values: 90,180, 270.
The default is 270 degrees (135 left and 135 right from top). 90 will travel 45 left and 45 right. 180 will travel 90 left and 90 right.

retval: It is calculated internally and should not be set directly. It can be accessed directly. It holds the current value as a formatted string.

cur_num_val: It is calculated internally and should not be set directly. It can be accessed directly. It holds the current numerical value.

Display Properties:

There are several ways to display the current value of the knob. You can use any or a combination of the various ways.

show_values: If true then values are displayed as numbers around the knob. Note: when increasing 'font_values' size you may need to also increase 'pad_values', or else values may overlap.

output: This property is used to modify how values are displayed. It accepts a table or a function. See Lokasenna docs for details.

show_tickmarks: If true then tickmarks will be drawn around the knob.

tickmark_size: Set the size of the tickmarks.

tickmark_steps: Tickmark steps should have some correspondence to knob steps. Say, knob steps is 100, tickmark_steps can be 10.

hard_ticks: Hard ticks refers to a set of tickmarks which can be enhanced with length and/or thickness. Hard ticks are specified in a table e.g., {0, 5, 10} which indicate at which positions (knob.steps) the hard ticks will be drawn. If 'hard_ticks' is nil or an empty table, or 'show_tickmarks' is false then no hard ticks will be drawn.

show_min_max: If true alpha-numerical values can be drawn at specified steps. Although the property is called 'min_max_values' it can also display values beside the minimum and maximum. They are specified in the a table, e.g., {{0,"0"}, {5,"5"}, {10,"10"}}. Each item in the table contains the position and the value to be displayed. The position is an integer corresponding to a knob step. The value is a string so anything alpha-numerical is valid.

display_style: The current value can be displayed in a box above (or below) the knob. If 'display_style' is "none" then a box will NOT be displayed. If 'display_style' is "box" then the values are displayed in a box similar to a textbox. If 'display_style' is "plain" the values are displayed in the area defined by the display box, but with no outline, and using the background color of where the knob is placed. 'display_pad_x' and 'display_pad_y' are used to tweak the position of the box. 'display_align' is used to position the value text inside the box. It can be "left", "center", or "right".

col_frame: The display box frame color, by default, uses highlight/lowlight colors that are automatically calculated from the 'col_backdrop' color. However, the frame can be set to use a single color (specified by the 'col_frame' property) by setting 'frame_use_outline' property to true. Some themes can call for single color outlines regardless of the 'frame_use_outline' setting.

---------------------------------------------------------
attribute:            property_name       default value       
---------------------------------------------------------
knob style:           knob_style         "pointer"
knob travel:          travel              270
centered:             centered            true
min value(number):    min                 0
max value(number):    max                 10
increment size:       inc                 1
default setting:      default             5
shadow element:       shadow              false

formatted value:      retval             [read only]
numerical value:      cur_num_val        [read only]

caption (string):     caption             ""
caption position:     cap_pos            "top" 
caption font:         font_caption       "sans22"
caption padding:      cap_pad             4
shadow caption:       shadow_caption      false

show values:          show_values         false
values font:          font_values        "sans18"
values padding:       pad_values          4 
displayed vals: *     output              nil

show tickmarks:       show_tickmarks      false
tickmark steps:       tickmark_steps      10 
tickmark size:        tickmark_size       4
tickmarks padding:    pad_ticks           4
hard ticks:           hard_ticks         {0, 5, 10}
hard tickmark size:   hard_tick_size      6
thicken hard ticks:   hard_tick_thk       false

show min-max vals:    show_min_max        false
min-max values:       min_max_values      table

display style:        display_style      "none"
display position:     display_pos        "top"
display width:        display_w           48
display height:       display_h           28
display font:         font_display       "sans24"
display pad x:        display_pad_x       0
display pad y:        display_pad_y       8
display align:        display_align      "center"

frame outline:        frame_use_outline   false
frame thickness: **   frame_thk           2
allow sel.outline:    allow_sel_outline   false

-- colors --
background:           col_bg             "wnd_bg" 
knob body:            col_body           "btn_face" 
knob outline:         col_outline        "btn_outline"
knob pointer: ***     col_indicator      "btn_txt"
caption text:         col_cap_text       "txt"

values text:          col_values         "txt"

display bg:           col_display_bg     "elm_bg"
display text:         col_display_text   "elm_txt"
display box frame:    col_frame          "elm_frame"
elm sel.outline:      col_active         "elm_active"

*    Used to modify/format displayed value. 
       Accepts table or function.
       Refer to Lokasenna documentation for details.
**   Display box frame. 
***  As of 04-16-2026 automatically derived from body color 
       except 'flange' style uses white.      
---------------------------------------------------------