uvi-script
Musical event scripting with Lua

stateless transient button. More...

Inheritance diagram for Button:
Widget

Public Member Functions

 Button (string name)
 creates a push button widget on the user interface.
 
void push (bool callChangedCallback)
 push the button!
 
void setStripImage (string imagePath, int numFrames)
 dress the button from one image holding a frame per state, stacked top to bottom in the order off, on, hovered off, hovered on, held off, held on.
 
void setLottieAnimation (string path, string mode)
 dress the button with a Lottie animation.
 

Public Attributes

string normalImage
 image path for the button at rest
 
string pressedImage
 image path for the button while held down
 
string overImage
 image path for the button while the mouse is over it
 
string backgroundColourOff
 background colour Off: colour string that defines the desired colour.
 
string textColourOff
 textColour Off: colour string that defines the desired colour.
 
string backgroundColourOn
 background colour On: colour string that defines the desired colour.
 
string textColourOn
 textColour On: colour string that defines the
 
bool triggeredOnMouseDown
 Sets whether the button click should happen when the mouse is pressed or released.
 
string dragAndDropFilepath
 file path that should be used for drag and drop
 
string dragAndDropText
 text carried when the button is dragged inside the plugin window.
 
number fontSize
 font size
 
string font
 path to TrueType font
 
string stripImage
 path to the strip image.
 
string lottieAnimation
 path to a Lottie animation or package, see Lottie Animations
 
- Public Attributes inherited from Widget
string name
 widget name, given at construction (read-only)
 
string displayName
 widget display name
 
string displayText
 custom text to display in place of the standard value display, on widgets that show one.
 
string tooltip
 widget tooltip, default is name
 
int x
 x position in pixels
 
int y
 y position in pixels
 
int width
 widget width in pixels
 
int height
 widget height in pixels
 
int w
 alias of width
 
int h
 alias of height
 
table size
 widget size {width, height}
 
table position
 widget position {x,y}
 
table pos
 alias of position
 
table bounds
 widget bounding rect {x,y,width,height}
 
number alpha
 transparency value between 0.0 and 1.0
 
bool enabled
 boolean flag to enable / disable the widget
 
bool visible
 boolean flag to toggle widget visibility
 
bool interceptsMouseClicks
 boolean flag to toggle mouse handling on widget.
 
bool showLabel
 show widgets label if any
 
bool persistent
 flag to tell if the widget values should be serialized when saving.
 
function changed
 callback function used by child widgets to be notified of changes.
 

Detailed Description

stateless transient button.

creates a push button widget on the user interface. Image properties support Retina @2x variants.

b = Button("button")
b.backgroundColourOff = "darkgrey"
b.backgroundColourOn = "darkred"
b.textColourOff = "white"
b.textColourOn = "white"
b.changed = function(self, mods)
-- mods is nil when the callback is run by push() rather than a click
print("button clicked:", mods and mods.altDown)
end
string backgroundColourOn
background colour On: colour string that defines the desired colour.
Definition ui.cpp:1062
void push(bool callChangedCallback)
push the button!
string textColourOn
textColour On: colour string that defines the
Definition ui.cpp:1067
string textColourOff
textColour Off: colour string that defines the desired colour.
Definition ui.cpp:1058
string backgroundColourOff
background colour Off: colour string that defines the desired colour.
Definition ui.cpp:1053
Button(string name)
creates a push button widget on the user interface.
function changed
callback function used by child widgets to be notified of changes.
Definition ui.cpp:1001
function run(fun,...)
launch a function in a separate parallel execution thread.
Definition api.lua:1364

Constructor & Destructor Documentation

◆ Button()

Button::Button ( string name)

creates a push button widget on the user interface.

Parameters
namethe name to give to the widget

Member Function Documentation

◆ push()

void Button::push ( bool callChangedCallback)

push the button!

Parameters
callChangedCallbacktrigger the button changed callback if true

◆ setLottieAnimation()

void Button::setLottieAnimation ( string path,
string mode )

dress the button with a Lottie animation.

See Lottie Animations.

Parameters
pathpath to a .json animation or a .lottie package
mode"toggle" walks the animation on and off, "trigger" replays it from the first frame on every click; any other string reads as "toggle". The argument is required – a call with the path alone raises an error. To keep the toggle mode, assign the lottieAnimation property instead

◆ setStripImage()

void Button::setStripImage ( string imagePath,
int numFrames )

dress the button from one image holding a frame per state, stacked top to bottom in the order off, on, hovered off, hovered on, held off, held on.

Fewer frames are read as the first few of that order, so a strip may stop wherever the separate images stopped. Supports Retina @2x variants.

Parameters
imagePathpath to the strip image
numFrameshow many frames the image holds

Member Data Documentation

◆ backgroundColourOff

string Button::backgroundColourOff

background colour Off: colour string that defines the desired colour.

It can be either a named colour like "blue" or "red" or an hexadecimal string in RGB ("#FF00CC") or ARGB ("#3C00FECD") format

◆ backgroundColourOn

string Button::backgroundColourOn

background colour On: colour string that defines the desired colour.

It can be either a named colour like "blue" or "red" or an hexadecimal string in RGB ("#FF00CC") or ARGB ("#3C00FECD") format

◆ dragAndDropText

string Button::dragAndDropText

text carried when the button is dragged inside the plugin window.

Dropped on a DnDArea of the same script whose acceptedText prefixes it, it calls that area's textDropped. The drag starts after a few pixels of travel, so a click stays a click. Empty (the default) disables it; when set, it takes precedence over dragAndDropFilepath.

◆ stripImage

string Button::stripImage

path to the strip image.

Nothing is drawn from a strip until the frame count is given, so assigning this alone is inert – call setStripImage

◆ textColourOff

string Button::textColourOff

textColour Off: colour string that defines the desired colour.

It can be either a named colour like "blue" or "red" or an hexadecimal string in RGB ("#FF00CC") or ARGB ("#3C00FECD") format

◆ textColourOn

string Button::textColourOn

textColour On: colour string that defines the

desired colour. It can be either a named colour like "blue" or "red" or an hexadecimal string in RGB ("#FF00CC") or ARGB ("#3C00FECD") format

◆ triggeredOnMouseDown

bool Button::triggeredOnMouseDown

Sets whether the button click should happen when the mouse is pressed or released.

By default the button is only considered to have been clicked when the mouse is released