This page covers the API and functionality of the Widget mixin.

Overview

Widget is the mixin that is most commonly mixed into other UI-related mixins. It provides common operations and default behaviors for mixins that represent UI. It mixes Bindable, which handles reacting to specific key presses.

CanvasBufferedWidget has almost the exact same interface, with the addition of a refresh method that manually instructs the widget to paint to its canvas. (Normally Widgets don't have their own canvases.)

Note: LÖVE's graphical API uses a global draw state. Attempting to use absolute instead of relative transforms may break some widget draw state invariants. Avoid using love.graphics.replaceTransform in particular.

API

Construction

Widget:new(color_scheme) → Widget

This is the Widget instance constructor.

• color_scheme : ColorScheme – The widget's color scheme is set to color_scheme as if it had been passed to Widget.set_color_scheme.

Graphics and Rendering

draw(x, y)

Draw the widget to the screen. This is the forward-facing, "just draw this widget" starting point for the graphics pipeline to use.

• x : number (by default 0), y : number (by default 0) – The relative screen coordinates of the widget's top left corner.

paint()

Render the widget. This is called by draw to handle the intricacies of how the widget is drawn. (For CanvasBufferedWidget, it's called by refresh instead.) It does not need to be called directly, but can be redefined if necessary.

paint_foreground()

Render the foreground of the widget using the foreground palette.

By default, this method does nothing; it's meant to be replaced.

paint_background()

Render the background of the widget using the background palette.

By default, this method renders a flat background using index 0 of the background palette. It can be replaced to do more involved background rendering.

get_color_scheme() → ColorScheme; set_color_scheme(new_color_scheme)

These are the getter and setter for the widget's color scheme, which describes which colors to use in paint_foreground and paint_background.

• new_color_scheme : ColorScheme

get_dimensions() → number, number

This is the getter for the widget's dimensions, as set by resize, represented as two numbers: width and height.

apply_palette(background_or_foreground)

Change the draw state to use four colors from this widget's color scheme; which colors depends on whether 'background' or 'foreground' is passed. Future LÖVE graphical calls will use these colors until the draw state is reverted or otherwise changed.

This is called by the default paint method.

• background_or_foreground : either 'background' or 'foreground' – Which palette to use: 'background' for the four background colors, 'foreground' for the four foreground colors

resize(width, height)

Set the size of the widget to the provided dimensions.

• width : number, height : number – new dimensions for the widget, expressed as pixels

Callbacks

press(x, y)

This method is called whenever the widget receives a mouse press.

By default, this method does nothing; it's meant to be replaced.

• x : number, y : number – the screen coordinates of the press

scroll(units, ctrl)

This method is called whenever the widget receives mouse scroll input.

By default, this method does nothing; it's meant to be replaced.

• units : number – the number of relative scrolls that occurred, positive for down and negative for up
• ctrl : boolean – whether a Ctrl key is being held (this is a convenient shortcut for two love.keyboard.isDown calls)

text_input(text)

This method is called whenever the widget receives text, such as from a keyboard or an IME.

By default, this method does nothing; it's meant to be replaced.

• text : string – the text fragment that was entered; this can simply be appended to a relevant text buffer if there is one

tick()

This method is called once every logical frame (as opposed to every draw frame, and even if the game client isn't focused).

By default, this method does nothing; it's meant to be replaced.