osb/doc/lua/widget.md
Kae bd783d3195 make the chat really pretty!!
also slightly optimized text shadow rendering, made sure glyphs with directives stay centered and added two extra Lua arguments to canvas.drawText
2023-06-21 00:59:41 +10:00

8.7 KiB

widget

The widget table contains functions to manipulate and get data about widgets in a scriptpane.

The widgetName passed into most of these functions can contain period separators for getting children.

Example:

widget.getPosition("itemScrollArea.itemList.1.name")

General callbacks

These callbacks are available for all widgets.


void widget.playSound(String audio, [int loops = 0], [float volume = 1.0f])

Plays a sound.


Vec2I widget.getPosition(String widgetName)

Returns the position of a widget.


void widget.setPosition(String widgetName, Vec2I position)

Sets the position of a widget.


Vec2I widget.getSize(String widgetName)

Returns the size of a widget.


void widget.setSize(String widgetName, Vec2I size)

Sets the size of a widget.


void widget.setVisible(String widgetName, bool visible)

Sets the visibility of a widget.


void widget.active(String widgetName)

Returns whether the widget is visible.


void widget.focus(String widgetName)

Sets focus on the specified widget.


void widget.hasFocus(String widgetName)

Returns whether the specified widget is currently focused.


void widget.blur(String widgetName)

Unsets focus on the specified focused widget.


Json widget.getData(String widgetName)

Returns the arbitrary data value set for the widget.


void widget.setData(String widgetName, Json data)

Sets arbitrary data for the widget.

String widget.getChildAt(Vec2I screenPosition)

Returns the full name for any widget at screenPosition.


bool widget.inMember(String widgetName, Vec2I screenPosition)

Returns whether the widget contains the specified screenPosition.


void widget.addChild(String widgetName, Json childConfig, [String childName])

Creates a new child widget with the specified config and adds it to the specified widget, optionally with the specified name.


void widget.removeAllChildren(String widgetName)

Removes all child widgets of the specified widget.


void widget.removeChild(String widgetName, String childName)

Removes the specified child widget from the specified widget.


Widget specific callbacks

These callbacks only work for some widget types.


String widget.getText(String widgetName)

Returns the text set in a TextBoxWidget.


void widget.setText(String widgetName, String text)

Sets the text of: LabelWidget, ButtonWidget, TextBoxWidget


void widget.setFontColor(String widgetName, Color color)

Sets the font color of: LabelWidget, ButtonWidget, TextBoxWidget


void widget.setImage(String widgetName, String imagePath)

Sets the image of an ImageWidget.


void widget.setImageScale(String widgetName, float imageScale)

Sets the scale of an ImageWidget.


void widget.setImageRotation(String widgetName, float imageRotation)

Sets the rotation of an ImageWidget.


void widget.setButtonEnabled(String widgetName, bool enabled)

Sets whether the ButtonWidget should be enabled.


void widget.setButtonImage(String widgetName, String baseImage)

Sets the baseImage of a ButtonWidget.


void widget.setButtonImages(String widgetName, Json imageSet)

Sets the full image set of a ButtonWidget.

{
  base = "image.png",
  hover = "image.png",
  pressed = "image.png",
  disabled = "image.png",
}

void widget.setButtonCheckedImages(String widgetName, Json imageSet)

Similar to widget.setButtonImages, but sets the images used for the checked state of a checkable ButtonWidget.


void widget.setButtonOverlayImage(String widgetName, String overlayImage)

Sets the overlay image of a ButtonWidget.


bool widget.getChecked(String widgetName)

Returns whether the ButtonWidget is checked.


void widget.setChecked(String widgetName, bool checked)

Sets whether a ButtonWidget is checked


int widget.getSelectedOption(String widgetName)

Returns the index of the selected option in a ButtonGroupWidget.


int widget.getSelectedData(String widgetName)

Returns the data of the selected option in a ButtonGroupWidget. Nil if no option is selected.


void widget.setSelectedOption(String widgetName, int index)

Sets the selected option index of a ButtonGroupWidget.


void widget.setOptionEnabled(String widgetName, int index, bool enabled)

Sets whether a ButtonGroupWidget option should be enabled.


void widget.setOptionVisible(String widgetName, int index, bool, visible)

Sets whether a ButtonGroupWidget option should be visible.


void widget.setProgress(String widgetName, float value)

Sets the progress of a ProgressWidget. Value should be between 0.0 and 1.0.


void widget.setSliderEnabled(String widgetName, bool enabled)

Sets whether the SliderBarWidget should be enabled.


float widget.getSliderValue(String widgetName)

Gets the current value of a SliderBarWidget.


void widget.setSliderValue(String widgetName, int newValue)

Sets the current value of a SliderBarWidget.


void widget.getSliderRange(String widgetName, int newMin, int newMax, [int newDelta])

Sets the minimum, maximum and (optionally) delta values of a SliderBarWidget.


void widget.clearListItems(String widgetName)

Clears all items in a ListWidget.


String widget.addListItem(String widgetName)

Adds a list item to a ListWidget using the configured template, and returns the name of the added list item.


void widget.removeListItem(String widgetName, size_t at)

Removes a list item from a ListWidget at a specific index.


String widget.getListSelected(String widgetName)

Returns the name of the currently selected widget in a ListWidget.


void widget.setListSelected(String widgetName, String selected)

Sets the selected widget of a ListWidget.


void widget.registerMemberCallback(String widgetName, String callbackName, LuaFunction callback)

Registers a member callback for a ListWidget's list items to use.


ItemBag widget.itemGridItems(String widgetName)

Returns the full item bag contents of an ItemGridWidget.


ItemDescriptor widget.itemSlotItem(String widgetName)

Returns the descriptor of the item in the specified item slot widget.


void widget.setItemSlotItem(String widgetName, Json itemDescriptor)

Sets the item in the specified item slot widget.


void widget.setItemSlotProgress(String widgetName, float progress)

Sets the progress overlay on the item slot to the specified value (between 0 and 1).


CanvasWidget widget.bindCanvas(String widgetName)

Binds the canvas widget with the specified name as userdata for easy access. The CanvasWidget has the following methods:

Vec2I size()

Returns the size of the canvas.

void clear()

Clears the canvas.

Vec2I mousePosition()

Returns the mouse position relative to the canvas.

void drawImage(String image, Vec2F position, [float scale], [Color color], [bool centered])

Draws an image to the canvas.

void drawImageDrawable(String image, Vec2F position, [Variant<Vec2F, float> scale], [Color color], [float rotation])

Draws an image to the canvas, centered on position, with slightly different options.

void drawImageRect(String texName, RectF texCoords, RectF screenCoords, [Color color])

Draws a rect section of a texture to a rect section of the canvas.

void drawTiledImage(String image, Vec2F offset, RectF screenCoords, [float scale], [Color color])

Draws an image tiled (and wrapping) within the specified screen area.

void drawLine(Vec2F start, Vec2F end, [Color color], [float lineWidth])

Draws a line on the canvas.

void drawRect(RectF rect, Color color)

Draws a filled rectangle on the canvas.

void drawPoly(PolyF poly, Color color, [float lineWidth])

Draws a polygon on the canvas.

void drawTriangles(List<PolyF> triangles, [Color color])

Draws a list of filled triangles to the canvas.

void drawText(String text, Json textPositioning, unsigned fontSize, [Color color], [float lineSpacing], [String directives])

Draws text on the canvas. textPositioning is in the format:

{
  position = {0, 0}
  horizontalAnchor = "left", -- left, mid, right
  verticalAnchor = "top", -- top, mid, bottom
  wrapWidth = nil -- wrap width in pixels or nil
}