Slider

What is it?

This slider library can be used in a few ways. It can be used as a progress bar of sorts, without any interaction needed. But it is designed for so much more. I want this library to be a very easy to use library for users.

Where to use it?

This is made for LÖVE2D. It was designed in version 11.3 but will likely work in earlier versions too.

How to use it?

This tutorial assumes basic knowledge of how to use LÖVE2D. See Getting Started for more information.

First you must require the module. You can do this in two ways if you have the full jjui package.

Ui = require "ui" -- If you have the full package, you can wrap all the ui libraries into one.

-- otherwise

SliderLibrary = require "ui.modules.slider" -- require just the slider module.

Next, create the slider. It is recommended to do this somewhere that isn't looped so your slider will not keep resetting.

function love.load()

	local x = 50
	local y = 100
	local angle = 0 -- angle the slider will be.
	-- Can use the following angle aliases
	-- - "left" for left to right
	-- - "right" for right to left
	-- - "bottom" for bottom to top
	-- - "top" for top to bottom

	local length = 150 -- how long the slider is
	local width = 5 -- optional: defaults to 5

	-- Called the same way whether or not you have the full jjui package.
	slider = Ui.new(x, y, angle, length)

end

You also have these variables to work with.

-- set these variables like this
slider.width = 6

parent
--This is for if you want it to draw relative to another object.
--Good for moving multiple ui elements at once

width -- how wide the slider is.

 --These are parallel and perpendicular to the sliders angle.
 --If the bar is horizontal, the hoverPerpendicularBuffer is amount above or below
    --and the hoverParallelBuffer is left and right
hoverPerpendicularBuffer
hoverParallelBuffer 

knobImage --Give it an image as the knob if you hover over the slider
knobOnHover --If false, it will always show. If you don't want a knob, don't make one.
knobScale --{xscale, yscale} scales the size of the knob.
fillColor --Part of the slider not filled
fill --Percent [0-1] of the bar that is filled.
clampFill --Prevent fill level from going out of range.
baseColor --Filled portion of the slider

range --{minRange, maxRange} This is the range from empty to full slider. A full slider with maxRange of 10 would = 10
triggerMouse --Array of all the mouse buttons that can trigger a slide action.
triggerKeyboard --Array of all the keyboard buttons that can trigger a slide action.
requireSelfClick --Require press to happen in this slider, then release in this slider.

You will want to pass in the sliders to the following LÖVE2D functions for full functionality.

1. love.update
2. love.draw
3. love.keypressed / love.keyreleased (If mouse functionality used)
4. love.mousepressed / love.mousereleased (If keyboard functionality used)

This may seem like a lot, and if so, look into my uisets wiki page for details to help reduce the clutter.

Available methods

These are the functions that you will likely need. There are more exposed functions that are mostly meant for internal use.

slider:inBounds(x, y)

Returns boolean if x, y is in bounds of the slider. This includes the buffer variables in it's calculations.

slider:getValue()

Returns the value of it's fill according to the range set.

slider.fill = 0.5 -- half full slider
slider.range = {0,1}
slider:getValue() -- returns 0.5
slider.range = {10, 20}
slider:getValue() -- returns 15

slider:setFill(fill, range)

Sets fill level of slider. Allows calculation based off of range if range == true

slider:setFill(0.5) -- makes slider half way filled.  Same as slider.fill = 0.5
slider.range = {100, 200}
slider:setFill(100, true) -- bar will be empty
slider:setFill(150, true) -- bar will be half filled

slider:setPosition(x, y)

Allows setting the first point of the line to x, y. This will automatically move point b as needed.

slider:addFill(fill)

Simply adds fill to its current fill value. This only works fills based off of a 0-1 range.

slider:setAngle(angle)

Sets the angle of the slider. This will calculate x,y coords of point b automatically.

slider:addAngle(angle)

Simply adds angle to its current angle.

How to change functions

If you need to change how functions work, it is very simple. Let's look at slider:callback() as an example. slider:callback() is the function that is called whenever the slider is moved.

function slider:callback()
    print(self.fill)
end

Now anytime you slide the knob, it will print out it's value, not totally useful, but you can imagine the possibilities.