GuiLove

A not-so-simple GUI library for LÖVE.

README

GuiLove is a GUI library for the LÖVE game framework.

The library is a single file with no external dependencies other than LÖVE. MIT license.

Note: The library is in beta, so many things (including documentation) are missing!

Features
Basic Usage
API
Development and Repository

Features

Retained-mode.
Fully automatic layout calculations.
Allows custom themes for rendering.

Basic Usage

function love.load()
	local Gui = require("Gui")
	gui       = Gui()

	local tree = {"root",
		{"vbar", id="myContainer", width=200,
			{"text", text="I'm just a text."},
			{"input", value="foo bar"},
			{"button", id="myButton", text="Press Me!"},
		},
	}
	gui:load(tree)

	local myButton   = gui:find("myButton")
	local pressCount = 0

	myButton:on("press", function(myButton, event)
		pressCount = pressCount + 1

		local myContainer = gui:find("myContainer")
		myContainer:insert{ "text", text="Pressed button "..pressCount.." time(s)!" }
	end)

	gui:getRoot():setDimensions(love.graphics.getDimensions())
end

function love.keypressed(key, scancode, isRepeat)
	gui:keypressed(key, scancode, isRepeat)
end
function love.keyreleased(key, scancode)
	gui:keyreleased(key, scancode)
end
function love.textinput(text)
	gui:textinput(text)
end

function love.mousepressed(mx, my, mbutton, isTouch, pressCount)
	gui:mousepressed(mx, my, mbutton, pressCount)
end
function love.mousemoved(mx, my, dx, dy, isTouch)
	gui:mousemoved(mx, my, dx, dy)
end
function love.mousereleased(mx, my, mbutton, isTouch, pressCount)
	gui:mousereleased(mx, my, mbutton, pressCount)
end
function love.wheelmoved(dx, dy)
	gui:wheelmoved(dx, dy)
end

function love.update(dt)
	gui:update(dt)
end
function love.draw()
	gui:draw()
end

API

Check the source code for more and up-to-date info. These lists are outdated!

Gui Methods

keypressed, keyreleased, textinput
mousepressed, mousemoved, mousereleased, wheelmoved
update
draw

areStandardKeysActive, setStandardKeysActive
blur
defineStyle
find, findAll, findActive, findToggled, match, matchAll
getDefaultSound, setDefaultSound
getElementAt
getFont, setFont, getBoldFont, setBoldFont, getSmallFont, setSmallFont, getLargeFont, setLargeFont, getTooltipFont, setTooltipFont
getHoveredElement
getNavigationTarget, navigateTo, navigateToNext, navigateToPrevious, navigateToFirst, navigate, canNavigateTo
getRoot
getScissorCoordsConverter, setScissorCoordsConverter
getScrollSpeed, setScrollSpeed
getSoundPlayer, setSoundPlayer
getSpriteLoader, setSpriteLoader
getTarget, parseTargetAndEvent, getTargetCallback, setTargetCallback
getTextPreprocessor, setTextPreprocessor, reprocessTexts
getTheme, setTheme
getTime, getTimeSinceNavigation
isBusy, isKeyboardBusy, isMouseBusy
isIgnoringKeyboardInput
isInputCaptured
isInteractionLocked
isMouseGrabbed, setMouseIsGrabbed
load
ok, back
updateLayout

Element Types, Methods and Events

(element)
- animate
- close, canClose
- exists
- getAnchor, setAnchor, getAnchorX, setAnchorX, getAnchorY, setAnchorY
- getCallback, setCallback, on, off, trigger, triggerBubbling
- getClosest
- getClosestInDirection, getNext, getPrevious
- getData, setData, swapData
- getDimensions, setDimensions, getWidth, setWidth, getHeight, setHeight
- getGui
- getGuiTime
- getId, hasId
- getIndex, getDepth
- getLayout
- getLayoutDimensions, getLayoutWidth, getLayoutHeight
- getLayoutPosition, getLayoutX, getLayoutY, getLayoutCenterPosition
- getMinDimensions, getMinWidth, getMinHeight
- getMouseCursor, getResultingMouseCursor, setMouseCursor
- getMousePosition, getMouseX, getMouseY
- getOrigin, setOrigin, getOriginX, setOriginX, getOriginY, setOriginY
- getParent, getParents, hasParent, getParentWithId, hasParentWithId, parents, parentsr, lineageUp
- getPathDescription
- getPosition, setPosition, getX, setX, getY, setY
- getPositionOnScreen, getXOnScreen, getYOnScreen
- getRoot, getNavigationRoot
- getSibling
- getSound, getResultingSound, setSound
- getStyle
- getTimeSinceBecomingVisible
- getTooltip, setTooltip, drawTooltip
- getTooltipFont, useTooltipFont
- hasTag, addTag, removeTag, removeAllTags, setTag
- isAt
- isDisplayed, getClosestHiddenElement, getFarthestHiddenElement
- isFirst, isLast
- isHidden, isVisible, setHidden, setVisible, show, hide, toggleHidden
- isHovered
- isMouseFocus, isKeyboardFocus
- isNavigationTarget
- isScrollbarXHovered, isScrollbarYHovered, isScrollbarXHandleHovered, isScrollbarYHandleHovered
- isScrollingX, isScrollingY
- isSolid
- isType
- playSound
- refresh
- remove
- reprocessTexts
- scrollIntoView
- setScissor, unsetScissor
- showMenu
- updateLayout
- Event: beforedraw, afterdraw
- Event: close, closed
- Event: focused, blurred
- Event: init
- Event: keypressed
- Event: layout
- Event: mousepressed, mousemoved, mousereleased
- Event: navigated
- Event: pressed
- Event: refresh
- Event: show, hide
- Event: textinput
- Event: update
- Event: wheelmoved

container
- find, findAll, findType, findActive, findToggled, match, matchAll
- get, children
- getChildAreaDimensions, getChildAreaWidth, getChildAreaHeight
- getChildWithData
- getElementAt
- getInnerSpace, getInnerSpaceX, getInnerSpaceY
- getMaxDimensions, setMaxDimensions, getMaxWidth, setMaxWidth, getMaxHeight, setMaxHeight
- getPadding, setPadding
- getScroll, getScrollX, getScrollY, setScroll, setScrollX, setScrollY, scroll, updateScroll
- getScrollHandleX, getScrollHandleY
- getScrollLimit, getScrollLimitX, getScrollLimitY
- getToggledChild, setToggledChild
- getVisibleChild, getVisibleChildNumber, getVisibleChildCount, setVisibleChild
- getVisualScroll, getVisualScrollX, getVisualScrollY
- hasScrollbars, hasScrollbarOnRight, hasScrollbarOnBottom
- indexOf
- insert, removeAt, empty
- setChildrenActive
- setChildrenHidden
- sort
- traverse, traverseType, traverseVisible

	(bar)

		hbar

		vbar

	root
	- setDimensions

(leaf)
- getAlign, setAlign
- getFont, useFont
- getMnemonicOffset
- getText, getUnprocessedText, setText, drawText, drawAlignedText
- getTextColor, setTextColor, hasTextColor, useTextColor
- isBold, setBold
- isLarge, setLarge
- isSmall, setSmall

	canvas
	- getCanvasBackgroundColor, setCanvasBackgroundColor
	- Event: draw

	image
	- Includes: imageInclude

	text

	(widget)
	- getPriority, setPriority
	- isActive, setActive
	- Event: navigate
	- Event: navupdate

		button
		- Includes: imageInclude
		- getArrow
		- getText2, getUnprocessedText2, setText2, drawText2, drawAlignedText2
		- isPressable, setPressable
		- isToggled, setToggled
		- press, isPressed
		- Event: press
		- Event: toggle

		input
		- focus, blur, isFocused
		- getBlinkPhase
		- getField
		- getSelectionOffset, getCursorOffset
		- getValue, setValue, getVisibleValue, drawValue, drawPlaceholder
		- isPasswordActive, setPasswordActive
		- Event: change
		- Event: submit
		- Event: valuechange

Includes

imageInclude
- drawImage
- getImageBackgroundColor, setImageBackgroundColor, hasImageBackgroundColor, useImageBackgroundColor
- getImageColor, setImageColor, hasImageColor, useImageColor
- getImageDimensions, setImageSize, maximizeImageSize
- getImageScale, getImageScaleX, getImageScaleY, setImageScale, setImageScaleX, setImageScaleY
- getSprite, setSprite, hasSprite

Utilities

- create9PartQuads
- draw9PartScaled
- newMonochromeImage, newImageUsingPalette

Development and Repository

The library is build using a build system and a preprocessing step. To build GuiLove, install Lua and run build/Build.cmd or this command from the root of the repository:

lua build/build.lua

Repository

File/directory	Description
build/	Build system files.
src/	Source files that will form `Gui.lua`.
Gui.lua	The built library.
defaultTheme.lua	The built default theme file.
init.lua	Helper file for projects cloning the repository into the project. `require"pathToGuiFolder"` can be used instead of `require"pathToGuiFolder.Gui"`.

ReFreezed / GuiLove