Scale(3pm)

📦
version 804.036 · 15 versions
, in debian trixie, ubuntu questing

💖 Scale — the Tk::Scale manual, but make it make sense 💖

okay bestie, sit down, hydrate, because we're talking about Tk::Scale — the widget that makes and manipulates Scale widgets. This page lives in the User Contributed Perl Documentation corner of the perl universe, and it's genuinely so much fun once it clicks. 🎀

✨ NAME ✨

Tk::Scale — Create and manipulate Scale widgets. That's the whole vibe. A little trough, a little slider, a whole lot of value-changing. 💅

🦋 SYNOPSIS 🦋

$scale = $parent->Scale(?options?);

yes that's it. that's the whole entrance. $parent is the parent widget, options are optional, and you get a scale back. iconic. ✨

🌈 STANDARD OPTIONS 🌈

these are the classics, the ones every well-behaved Tk widget shows up with:

  • -activebackground
  • -background
  • -borderwidth
  • -cursor
  • -font
  • -foreground
  • -highlightbackground
  • -highlightcolor
  • -highlightthickness
  • -orient
  • -relief
  • -repeatdelay
  • -repeatinterval
  • -takefocus
  • -troughcolor

See Tk::options for details of the standard options. like, go read it, it's right there, it's giving reference material. 📚

🎀 WIDGET-SPECIFIC OPTIONS 🎀

okay these are the ones that are specifically scale-coded. each one has a Name, a Class, and a Switch, and yes we're listing all of them, no skipping, that's the rule bestie. 💖

  • -bigincrement — Name: bigIncrement, Class: BigIncrement. Some interactions with the scale make its value jump by "large" increments, and this option sets how big those large increments are. If you set it to 0, the large increments default to 1/10 the range of the scale. 🦘
  • -command — Name: command, Class: Command. This is the prefix of a perl/Tk callback that gets invoked whenever the scale's value is changed via a method. The actual command is this option, then a space, then a real number with the scale's new value. so it's like yourcallback 42.5 basically. 🔔
  • -digits — Name: digits, Class: Digits. An integer saying how many significant digits get kept when the scale's value is converted to a string. If it's less than or equal to zero, the scale picks the smallest value that guarantees every possible slider position prints as a different string. no duplicate string eras allowed. 🔢
  • -from — Name: from, Class: From. A real value matching the left or top end of the scale. 📍
  • -label — Name: label, Class: Label. A string shown as a label for the scale. On vertical scales it shows up just to the right of the top end; on horizontal scales it shows up just above the left end. If you set it to an empty string, no label shows up at all. ghosted. 👻
  • -length — Name: length, Class: Length. The desired long dimension of the scale, in screen units (i.e. any of the forms acceptable to Tk_GetPixels). Vertical scale → that's the height. Horizontal scale → that's the width. 📏
  • -resolution — Name: resolution, Class: Resolution. A real value specifying the resolution for the scale. If it's greater than zero, the scale's value always rounds to an even multiple of it, and so do the tick marks and the endpoints of the scale. If it's less than zero, no rounding happens at all. Defaults to 1 (i.e. the value will be integral). 🎯
  • -showvalue — Name: showValue, Class: ShowValue. A boolean value saying whether the scale's current value is displayed or not. 👀
  • -sliderlength — Name: sliderLength, Class: SliderLength. Specifies the size of the slider, measured in screen units along the slider's long dimension. The value can be in any of the forms acceptable to Tk_GetPixels. 🎚️
  • -sliderrelief — Name: sliderRelief, Class: SliderRelief. The relief used when drawing the slider, like raised or sunken. 💠
  • -state — Name: state, Class: State. One of three states for the scale: normal, active, or disabled. If it's disabled, the value can't be changed and the scale won't activate. If it's active, the slider is displayed using the color specified by the activeBackground option. 💫
  • -tickinterval — Name: tickInterval, Class: TickInterval. Must be a real value. Determines the spacing between the numerical tick marks displayed below or to the left of the slider. If it's 0, no tick marks are displayed. no ticks, no notes. 🎵
  • -to — Name: to, Class: To. A real value corresponding to the right or bottom end of the scale. This value may be either less than or greater than the from option — yes, either, the scale does not care. 🌀
  • -variable — Name: variable, Class: Variable. The name of a global variable to link to the scale. Whenever the variable's value changes, the scale updates to reflect it. Whenever the scale is manipulated interactively, the variable gets modified to reflect the scale's new value. it's giving mutual pining, except it's two-way data binding. 💞
  • -width — Name: width, Class: Width. The desired narrow dimension of the trough, in screen units (i.e. any of the forms acceptable to Tk_GetPixels). Vertical scale → trough's width. Horizontal scale → trough's height. 📐

🌸 DESCRIPTION 🌸

The Scale method creates a new window (given by the $widget argument) and makes it into a scale widget. Additional options, described above, can be specified on the command line or in the option database to configure aspects of the scale like its colors, orientation, and relief. The scale command returns its $widget argument. At the time this command is invoked, there must not already exist a window named $widget, but $widget's parent must exist. no squatters, but your parent has to show up for you. 😭

A scale is a widget that displays a rectangular trough and a small slider. The trough corresponds to a range of real values (determined by the from, to, and resolution options), and the position of the slider selects a particular real value. The slider's position (and therefore the scale's value) can be adjusted with the mouse or the keyboard, as described in the BINDINGS section below. Whenever the scale's value changes, a Tcl command is invoked (using the command option) to notify other interested widgets about the change. On top of that, the scale's value can be linked to a Tcl variable (using the variable option), so that changes in either one are reflected in the other. 💫

Three annotations can be displayed in a scale widget:

  1. a label appearing at the top right of the widget (top left for horizontal scales)
  2. a number displayed just to the left of the slider (just above the slider for horizontal scales)
  3. a collection of numerical tick marks just to the left of the current value (just below the trough for horizontal scales)

Each of these three annotations can be enabled or disabled using the configuration options. pick your faves, mix and match. ✨

💅 WIDGET METHODS 💅

The Scale method creates a widget object. This object supports the configure and cget methods described in Tk::options, which you can use to enquire about and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class. family tree moment. 🌳

The following additional methods are available for scale widgets:

  • $scale->coords(?value?) — Returns a list whose elements are the x and y coordinates of the point along the centerline of the trough that corresponds to value. If value is omitted, the scale's current value is used. 📍
  • $scale->get(?x, y?) — If x and y are omitted, returns the scale's current value. If x and y are specified, they give pixel coordinates within the widget, and the command returns the scale value corresponding to that pixel. Only one of x or y is used: for horizontal scales y is ignored, and for vertical scales x is ignored. 👑
  • $scale->identify(x, y) — Returns a string indicating what part of the scale lies under the coordinates given by x and y. A return value of slider means the point is over the slider; trough1 means the point is over the portion of the slider above or to the left of the slider; and trough2 means the point is over the portion of the slider below or to the right of the slider. If the point isn't over one of these elements, an empty string is returned. nothing to see here, literally. 🙈
  • $scale->set(value) — This command is invoked to change the scale's current value, and therefore the position at which the slider is displayed. Value gives the new value for the scale. The command has no effect if the scale is disabled. 🚫

🔥 BINDINGS 🔥

Tk automatically creates class bindings for scales that give them the following default behavior. Where the behavior is different for vertical and horizontal scales, the horizontal behavior is described in parentheses. ok ready, here's the whole choreography:

  1. If button 1 is pressed in the trough, the scale's value will be incremented or decremented by the value of the resolution option so that the slider moves in the direction of the cursor. If the button is held down, the action auto-repeats. 🖱️
  2. If button 1 is pressed over the slider, the slider can be dragged with the mouse. grab and go. ✋
  3. If button 1 is pressed in the trough with the Control key down, the slider moves all the way to the end of its range, in the direction towards the mouse cursor. zoom. ⚡
  4. If button 2 is pressed, the scale's value is set to the mouse position. If the mouse is dragged with button 2 down, the scale's value changes with the drag. 🎯
  5. The Up and Left keys move the slider up (left) by the value of the resolution option. ⬆️
  6. The Down and Right keys move the slider down (right) by the value of the resolution option. ⬇️
  7. Control-Up and Control-Left move the slider up (left) by the value of the bigIncrement option. 💨
  8. Control-Down and Control-Right move the slider down (right) by the value of the bigIncrement option. 💨
  9. Home moves the slider to the top (left) end of its range. 🏠
  10. End moves the slider to the bottom (right) end of its range. 🏁
heads up bestie: if the scale is disabled using the state option, then none of the above bindings have any effect. like, at all. it's not ignoring you, it's just disabled. 💀

The behavior of scales can be changed by defining new bindings for individual widgets or by redefining the class bindings. customize away. 🎨

⭐ KEYWORDS ⭐

scale, slider, trough, widget

and that's the page, bestie. 🫶

this whole thing came from perl v5.40.1, dated 2025-04-13, in the User Contributed Perl Documentation collection — go forth and build the prettiest little slider the world has ever seen. periodt. 👑💖✨

📦 where this page comes from