Widgets - lmparppei/BeatPlugins GitHub Wiki

Plugins can register a widget are into the sidebar. Widgets are visible on the fourth tab, when any active widgets are running. One plugin can run one widget at a time. When the plugin is terminated, its widget will be removed too.

PLEASE NOTE: Widgets are still at a very experimental level. You can toy around with them, but mileage may vary.

Widget object

Creating a widget view for the plugin:

const widget = Beat.widget(height)

Widgets can display either native UI elements, such as buttons and labels, or HTML content (soon). Interacting with HTML content works like HTML Windows, but native elements can be called right out of the plugin script.

Widget properties and methods:

widget.show() - shows the widget sidebar

widget.frame — returns a frame object ({ x: f, y: f, width: f, height: f })
widget.setHeight(height) — set a new height for the widget

Drawing graphics

You can also register a custom drawing method. This method is called whenever the widget is redrawn.

NOTE: Be careful not to fetch any data in the drawing method or you might harm app performance. Do any other processing elsewhere and then just use the results to draw graphics. When you first call onDraw() the widget will be automatically redrawn, so you can also redraw the whole widget area when needed.

widget.onDraw(function (frame) {
    widget.rectangle(x, y, width, height, color)
});

Available drawing methods:

// Draw a simple rectangle:
widget.rectangle(x, y, width, height, fillColor, strokeColor, strokeWidth)

// Draw a rounded rectangle:  
widget.roundedRectangle(x, y, width, height, cornerRadius, fillColor, strokeColor, strokeWidth)

// Draw a circle (x and y define the center):  
widget.circle(x, y, radius, fillColor, strokeColor, strokeWidth)

Color values are strings — either hex values, preceded by # (eg. "#ff0000) or standard Beat colors like "red", "blue" etc. You can leave most of the values out when not needed, or replace them by null.

widget.onDraw(function (frame) {
    // Draw a rectangle with a white border
    widget.rectangle(0, 0, 10, 10, null, "#ffffff", 1.0)

    // Draw a blue rectangle 
    widget.rectangle(2, 0, 10, 10, "#00ff00")
});

UI Elements

When adding UI elements to the widget, you first need to create a new UI element and then add it into the view.

let button = Beat.button("Button",
    function (element) {
        // Do something when clicked
    },
    { x: 0, y: 0, width: 80, height: 20 }
)
widget.addElement(button)

Common methods and properties

Every UI object has a set of common methods and properties.

element.frame — frame of the object ({ x: ..., y: ..., width: ..., height: ... })
element.setFrame(x, y, width, height) — set position and size
element.remove() — remove the object from view

When creating a new UI element, you need to provide an action function. It's a normal callback which is invoked when the element is either clicked, selected or its value is changed by the user.

Frame argument is always a frame object, for example:

let frame = { x: 0, y: 0, width: 100, height: 100 }

Labels

let label = Beat.label(title, frame, color, fontSize, fontName)

label.fontSize — get/set font size in points
label.fontName — get/set font name

Buttons

let button = Beat.button(title, action, frame)

Action receives the button title when clicked.

button.title — the title of button, can be changed during runtime

Dropdowns

let dropdown = Beat.dropdown(["Item Name", "Item Name 2", ...], action, frame)

Action is called whenever an item is selected. The action receives currently selected item name.

dropdown.selectItemWithTitle(title) — select an item by title
dropdown.selectItemAtIndex(index) — select an item by its index
dropdown.setItems([items]) — set dropdown items
dropdown.addItem(item) — add a single item into the dropdown

Checkboxes

let checkbox = Beat.checkbox("Checkbox Label", function (checked, label), frame)

Action receives both checked value (after being clicked) and label name.

checkbox.enabled — when set to false, checkbox cannot be clicked
checkbox.checked — returns true if the box is ticked

Examples

Create a simple widget with a checkbox and a button.

let widget = Beat.widget(60)

// Create a new button object
// Note that this is NOT added to the widget yet
let button = Beat.button("Button", 
    // Action runs when the button is clicked
    function (title) {
        Beat.log(title + " was clicked")
    },

    // Frame
    { x: 10, y: 0,  width: 100, height: 30 }
)

let checkbox = Beat.checkbox("Enable that button",
    function (checked) {
        // Enable button when the checkbox is ticked
        if (checked) button.enabled = true
        else button.enabled = false
    },

    { x: 10, y: 25, width: 100, height: 30 }
)

// Set default value as checked
checkbox.checked = true

// Add both UI elements to the widget
widget.addElement(button)
widget.addElement(checkbox)

Display simple chart with bars:

let widget = Beat.widget(60)

widget.onDraw(function (rect) {
    // When you have wide elements, always try to make them relative to side bar width. 
    // Use the width of your widget to create relative values.
    let width = widget.frame.width * .8 - 20

    // Draw rectangles
    widget.rectangle(10,10, width, 8, "#ff00aa")
    widget.rectangle(10,25, width * .7, 8, "#00ffaa")    
    widget.rectangle(10,40, width * .5, 8, "#ddaa00")
})