Button

A UI element, that is clickable and executes a function when it is clicked.

Button in three states: Default, Pressed and Disabled.

Contents:

• Properties

• Functions

Properties

Name	Type	Default
text	string	nil
x	number	nil
y	number	nil
w	number	nil
h	number	nil
style	uilib.Style	Default Style
action	function	nil
args	table	nil
toggle	boolean	false
visible	boolean	true
pressed	boolean	false
disabled	boolean	false

text

Text, which is displayed on the button.

uilib.Button.text = nil

• Type: string

• Default: nil

Note

If the text is longer than the width of the button with padding in mind, the text will just get cut off.

---

x

X component of the position on the screen.

uilib.Button.x = nil

• Type: number

• Default: nil

---

y

Y component of the position on the screen.

uilib.Button.y = nil

• Type: number

• Default: nil

---

w

Width of the button.

uilib.Button.w = nil

• Type: number

• Default: nil

---

h

Height of the button.

uilib.Button.h = nil

• Type: number

• Default: nil

---

style

Style of the button.

uilib.Button.style = uilib.Style:new()

• Type: uilib.Style

• Default: Default Style

---

action

Function, that should be run when the button is clicked.

uilib.Button.action = nil

• Type: function

• Default: nil

---

args

Arguments to the function specified with action.

uilib.Button.args = nil

• Type: table

• Default: nil

Warning

The order of arguments within the table should be the same order as the function specified with action is expecting it.

---

toggle

Enables toggle mode for the button.

uilib.Button.toggle = false

• Type: boolean

• Default: false

---

visible

Contains information about the button being visible or not.

uilib.Button.visible = true

• Type: boolean

• Default: true

Note

Please use show() to enable visibility and hide() to disable visibility of the button.

---

pressed

Contains information about the button being clicked or not.

uilib.Button.pressed = false

• Type: boolean

• Default: false

Important

This property is not meant for being set directly and is usually only set by clickEvent().

---

disabled

Contains information about the button being disabled or not.

uilib.Button.disabled = false

• Type: boolean

• Default: false

Note

Please use disable() to toggle if the button should be disabled of the button.

---

Functions

• new()

• draw()

• clickEvent()

• disable()

• show()

• hide()

new()

Creates a new instance of Button and returns it.

function uilib.Button:new(text, x, y, w, h, action, args, toggle, style)
    ...
    return button
end

Arguments:

Name	Type	Default	Description
text	string	nil	Text to be displayed on the button.
x	number	nil	X component of position of the button.
y	number	nil	Y component of position of the button.
w	number	nil	Width of the button.
h	number	nil	Height of the button.
action	function	nil	Function, that will be executed, when the button is clicked.
args	table	nil	Arguments for the function specified above.
toggle	boolean	false	Enables toggle mode for the button.
style	uilib.Style	Default Style	Style of the button for various states.

Returns:

Type	Description
uilib.Button	Instance of Button with specified properties.

Example:

local uilib = require("uilib")

function onClick(name)
    print("Hello " .. name)
end

local btn = uilib.Button:new("Test", 2, 2, 6, 3, onClick, {"User"}, false, uilib.Style:new())

A Button with the text Test would be cerated at position (2, 2) with a size of 6 x 3 pixels. It would execute onClick("User") when it would be clicked. Toggle mode is disabled for this button, so this button is in one-shot mode. The button would have the default Style.

---

draw()

Function to draw the button on the screen.

function uilib.Button:draw()
    ...
end

Arguments: nil

Returns: nil

Example:

local uilib = require("uilib")

function onClick(name)
    print("Hello " .. name)
end

local btn = uilib.Button:new("Test", 2, 2, 6, 3, onClick, {"User"}, false, uilib.Style:new())
btn:draw()

An instance of Button will be created with the new() method and the returned button will be drawn to the screen.

---

clickEvent()

Function that checks if a click event was on the button and executes action if it was. It will not execute the function if the button is either disabled or not visible.

function uilib.Button:clickEvent(ex, ey)
    ...
    return ret
end

Arguments:

Name	Type	Default	Description
ex	number	false	X component of the event position.
ey	number	false	Y component of the event position.

Returns:

Type	Description
table	Return values from the function specified in action

Example:

local uilib = require("uilib")

function onClick(name)
    print("Hello " .. name)
end

local btn = uilib.Button:new("Test", 2, 2, 6, 3, onClick, {"User"}, false, uilib.Style:new())

while true do
  local e, btn, x, y = os.pullEvent("mouse_click")
  btn:clickEvent(x, y)
end

An instance of Button will be created with the new() method. After that it will wait for a mouse_click event. If this event happened inside the button, the action function will be executed.

---

disable()

Function to disable or enable the button.

function uilib.Button:disable(status)
    ...
end

Arguments:

Name	Type	Default	Description
status	boolean	Inverse of disabled	Specifies if it should be disabled or not.

Note

If status is omitted, the function toggles the disabled flag. If status is specified however, the function will set the disabled flag to status.

Returns: nil

Example:

local uilib = require("uilib")

function onClick(name)
    print("Hello " .. name)
end

local btn = uilib.Button:new("Test", 2, 2, 6, 3, onClick, {"User"}, false, uilib.Style:new())
btn:disable(true)

An instance of Button will be created with the new() method. Adter that the button will be disabled.

---

show()

Function to make the button visible.

function uilib.Button:show()
    ...
end

Arguments: nil

Returns: nil

Example:

local uilib = require("uilib")

function onClick(name)
    print("Hello " .. name)
end

local btn = uilib.Button:new("Test", 2, 2, 6, 3, onClick, {"User"}, false, uilib.Style:new())
btn:show()

An instance of Button will be created with the new() method. Adter that the button will be made visible.

---

hide()

Function to make the button invisible.

function uilib.Button:hide()
  ...
end

Arguments: nil

Returns: nil

Example:

local uilib = require("uilib")

function onClick(name)
    print("Hello " .. name)
end

local btn = uilib.Button:new("Test", 2, 2, 6, 3, onClick, {"User"}, false, uilib.Style:new())
btn:hide()

An instance of Button will be created with the new() method. Adter that the button will be made invisible.