Button Library

What is it?

The button library gives you the ability to make quick buttons. These buttons have 6 states to them based on if the button is selected, pressed and hovered. I designed this library to handle them all. With this, you create the button as you want it to be, the library will handle the rest.

What button types does this support?

Polygon buttons, including rectangle buttons. Circe buttons Arc buttons

How to use

Most button types use very similar methods and variables. I note the functions that are specific to one type of button below.

Most variables for these buttons follow a naming convention. If the button is pressed, it is implied that you are hovering over the button. hover/pressed is the first part of their respective variables Selected will come after hover/pressed. If you are not pressing the button, omit pressed from the variable name. Same for hover and selected. Variables have first word lowercase, the rest capitalized.

For example, if you are pressing a button that has already been toggled, then you would preface the variable as pressedSelected

Variables you have to work with are...

font
fitText -- attempts to fit text into button
fitHoverText -- attempts to fit text into prompt
visible -- shows/hides button.
requireSelfClick -- requires button to be clicked and released in the same button.
parent -- The origin object that coordinates are translated from.
triggerMouse -- Array of mouse buttons to trigger button
triggerKeyboard -- Array of key buttons to trigger button

text -- text to print
textRotation -- rotation the text will print at
textColor -- color of text
textBackgroundBuffer -- Buffer in pixels for surrounding highlight.
textXOffset -- Horizontal text offset within button.  Note, doesn't have to be inside button.
textYOffset -- Vertical offset within button
image -- Image to draw, has to be lg.newImage, not path to image.  You can use formatImage.
color -- color of main button area.
outlineColor -- Color of outline draw.
outlineWidth -- Width of outline

Any constructor with the optional parameter "extra" takes a table to set these variables upon construction.

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

First, require the file.

Ui = require "ui" -- If you have the full package, this is groups all ui libraries into one.

-- Alternatively

Buttons = require "ui.modules.button" -- Can require directly.

Rectangle Button

A rectangle button is a polygon button behind the scenes, but there is a simple constructor to make it easy to make.

function love.load()
	local left = 50
	local top = 25
	local width = 150
	local height = 50
	rectangle = Ui.newRectangleButton(left, top, width, height)
end

You will also want to put these functions into their respective LOVE2D functions. See uisets for simplifying this.

rectangle:update(dt)
rectangle:draw()
rectangle:mousepressed(x, y, button)
rectangle:mousereleased(x, y, button)
rectangle:keypressed(key) -- only if you assign keyboard input.
rectangle:keyreleased(key) -- only if you assign keyboard input.

Circle Button

Ui.newCircleButton(x, y, radius)

Circle button has

Arc Button

arc = Ui.newArcButton(x, y, radius, angle1, angle2, extra)

Angle Button

This is just an Arc button, but it makes it easier to give it a specific angle.

angle = Ui.newAngleButton(x, y, radius, startAngle, addAngle, extra)

Arc and Angle buttons have the extra function. button:getCenterAngle() allows you to get the midpoint between it's start and ending angles.

Polygon Button

This is definitely the most complicated of the button, but don't fret. It's easy enough. The vertices passed will be relative to the passed x, y position. The vertices must be in multiples of two. One per x coordinate, one per y.

polygon = Ui.newPolygonButton(500, 600, {0, 0, 55, 50, 0, 50})

Polygon buttons have the extra function button:setVertices(...) This function assists you with setting vertices. In large part, it's meant to ensure correct formatting.

Available methods

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

button:toggle(bool)

sets button to bool if passed, otherwise will toggle.

button:inBounds(x, y)

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

button:prompt() WIP

This is a secondary draw function. It is meant to be called after other objects. While hovering over the button long enough, this will show.

button:setVar(var, value, ...) WIP

This is one function that minimizes variable setting. There are multiple ways to use this function. Valid var are "Text", "TextRotation", "TextColor", "TextBackgroundColor", "TextBackgroundBuffer", "Image", "Color", "OutlineColor", "OutlineWidth"
These are case sensitive. This defines which type of variables you want to set.

value is what you want to set them to.

varargs ... is for all the variables you want to set.

User Defined Functions

These functions are blank by default. You can give them any function you'd like.

function button:onPress()
    print("I've been pressed!")
end

button:onRelease() -- What happens when a valid mouse button is released inBounds.
button:onPress() -- What happens when a valid mouse is pressed inBounds.
button:onHoldPress() -- What happens when button is held down.
button:hover() -- What happens when you hover over the button.
button:onEnter() -- What happens when your cursor enters the button bounds.
button:onExit() -- What happens when your cursor exits the button bounds.
button:onholdStart() -- The first callback once you hold down a button.
button:onHold() -- The callback that happens every frame while holding.
button:onHoldStop() -- The callback that happens when you stop holding.

By default, buttons aren't selectable. Think of the previous/next buttons on your favorite music player. When you click them, they don't change. They just trigger. By contrast, a selectable button is like the play/pause button. You click it, and it toggles back and forth from the play button to the pause button. To make your button do this, put button:toggle() into your trigger function.