Skip to content

Intro to sliders

Sliders are a powerful way to vary numeric values between a minimum and a maximum value. They have a bar or line (a "rail") over which a "handle" slides left and right (or up and down), and the position of this handle relative to the rail determines the value.

Constructor

The constructor for this widget is UISlider and its signature is the following:

UISlider(_id, _x, _y, _length, _sprite, _sprite_handle, _value, _min_value, _max_value, _orientation=UI_ORIENTATION.HORIZONTAL, _relative_to=UI_DEFAULT_ANCHOR_POINT)
  • id is the string ID.
  • x and y are the offsets with respect to the anchor point. Note that, as directed in the Fundamentals page, your sprites should have its origin point set to top left, to allow for correct positioning in gooey.
  • length is the desired width (if horizontal) or height (if vertical) of the slider rail.
  • sprite is the sprite used to render the slider rail.
  • sprite_handle is the sprite used to render the handle.
  • value is the starting value of the slider.
  • min_value and max_value are the minimum and maximum possible values of the control.
  • orientation determines whether the slider is rendered horizontally or vertically, according to the UI_ORIENTATION enum.
  • relative_to is the anchor point, as usual from the UI_RELATIVE_TO enum.

Setting the value interactively

In sliders you have three ways of interacting with the slider to change a value:

  1. Dragging the handle;
  2. Clicking in the "rail"; and
  3. Scrolling with the mouse wheel

Dragging the handle

You can click and drag the handle to change the value. The value will change in multiples of what is set using setDragChange method (by default, 1 unit).

Clicking the rail

You can click the rail either at the left (or bottom, if vertical) of the handle (to decrease the value) or at the right (or top, if vertical) of the handle (to increase the value). The amount changed per click can be set using the setClickChange method - by default, 2 units.

You can also change the default behavior so that, instead of decreasing or increasing the value each time you click, you directly set the slider to the value at the click position. This is configured by the setClickToSet method.

Scrolling the mouse wheel

You can scroll the mouse wheel while over the slider to increase or decrease the value. The amount changed per scroll will be set using the setScrollChange method - by default, 1 unit.

Setting the value programmatically

You can use setValue to set the value of a slider programatically. This method will clamp the provided value between the minimum and maximum allowed.

Setting up the sprites

Remember that the sprites need to have their origin set at top left. However, this implies the handle will be drawn from the top of the rail down. We can adjust where the handle "intersects" the rail by configuring its offset, with setHandleOffset.

Apart from the base "rail" sprite, you can also configure a "progress" sprite, which shows the sprite overlaid from the start of the slider from the "left" or "bottom" of the rail up to the handle. This is optional and off by default - you can set it using the setSpriteProgress and setImageProgress methods.

Configuring text

By default, the slider will show both the min/max values (at each end of the "rail") and the current value (at the top of the handle). You can enable or disable minimum, maximum and handle text (setShowMinMaxText and setShowHandleText), and you can control the format of this string with setTextFormat, as well as it offset with setHandleTextOffset.

Example

Let's create an example using the included Kenney's UI pack. I will create a Settings menu with three sliders: one for sound volume, one for music volume and one for FOV correction1.

For the Sounds Volume slider, I want it to be a regular slider that goes from 0 to 100. I want it to be able to change by 5 when clicked, by 1 when dragged and by 5 when scrolled. Let's take a look at the code:

1
2
3
4
5
var _panel = new UIPanel("TestPanel", 0, 0, 400, 350, grey_panel, UI_RELATIVE_TO.MIDDLE_CENTER);
var _slider = new UISlider("Sound_Slider", 0, -100, 300, grey_sliderHorizontal, green_sliderDown, 70, 0, 100,, UI_RELATIVE_TO.MIDDLE_CENTER);
_slider.setHandleOffset({x:0, y:-16}).setTextFormat("[c_black]");
_slider.setClickChange(5).setScrollChange(5);
_panel.add(_slider);

I want to change things up a bit for the Music Volume slider. Let's make it so it shows only the handle text, sets the change unit to 10 no matter if it's click, scroll or drag, and enables "click to set", so the slider changes to the value corresponding to the position I click:

6
7
8
9
var _slider = new UISlider("Music_Slider", 0, 0, 300, grey_sliderHorizontal, blue_sliderUp, 50, 0, 100,, UI_RELATIVE_TO.MIDDLE_CENTER);
_slider.setHandleOffset({x:0, y:-16}).setTextFormat("[c_black]").setShowMinMaxText(false);
_slider.setClickChange(10).setScrollChange(10).setDragChange(10).setClickToSet(true);
_panel.add(_slider);

Finally, I want the third slider to vary between -3 and 3, with different increments for click, change and drag.

10
11
12
13
var _slider = new UISlider("FOV_Slider", 0, 100, 300, grey_sliderHorizontal, red_circle, 0, -3, 3,, UI_RELATIVE_TO.MIDDLE_CENTER);
_slider.setHandleOffset({x:0, y:-16}).setTextFormat("[c_black]").setShowMinMaxText(false).setShowHandleText(true);
_slider.setClickChange(0.1).setScrollChange(0.5).setDragChange(1);
_panel.add(_slider);

The final interactive example looks like so:

  1. No idea what this is, I couldn't think of a good example that varies between negative and positive units and relates to a game setting. If something occurs to me, I will change it. ↩