Utilities and internals

Ember hangs the parts it is made of off the module, so a control you register looks like one that shipped with the library rather than something bolted to the side of it.

local Util = Ember.Util

Everything here is stable API. It is also lower-level than the rest of the docs: reach for it when you are registering a control or painting your own GUI, not when a control already does the job.

Building instances#

Util.create is the constructor the whole library uses. Props, then children, with Parent applied last so a frame is never briefly parented while half configured.

local frame = Util.create("Frame", {
    Parent = slot,
    BackgroundColor3 = Ember.Theme.panel2,
    Size = UDim2.fromOffset(120, 26),
}, { Util.corner(6), Util.stroke(Ember.Theme.border) })

Util.label coerces a non-string, so a number is safe. richText is off unless you pass true.

Layout and shape#

Each returns a bare UI object for you to parent, or to pass in create's children array.

Colour and style#

local look = Util.style("filled", Ember.Theme.accent)
 
local button = Util.create("TextButton", {
    BackgroundColor3 = look.fill,
    BackgroundTransparency = look.fillFade,
    TextColor3 = look.ink,
}, { Util.stroke(look.edge, nil, look.edgeFade) })

Util.style(name, tone) resolves one of four named looks against a tone colour and returns { fill, fillFade, ink, edge, edgeFade, name }. An unknown name falls back to outline, and name tells you which you actually got.

Util.brighten(colour, amount) lifts a Color3 toward white in HSV, amount being 0–1. Use it for a hover tint that keeps the hue.

Animation#

Util.tween(inst, props, info?) is TweenService:Create plus the two things every call site needed anyway: it cancels any in-flight tween touching the same properties, and it honours the effects config. When animation is off, or RespectReducedMotion is on and the player set that flag, it assigns the values immediately and returns nil rather than animating.

Util.tween(frame, { BackgroundColor3 = Ember.Theme.accent }, Ember.Motion.fast)

info defaults to Motion.fast. The return is the Tween, or nil when it applied instantly — so do not assume there is something to :Play() again.

Hover, pointer and input#

Util.hover covers selection as well as the mouse, which is why controls respond to a gamepad. Both callbacks are wrapped, so one that errors warns rather than leaving the control stuck lit.

Util.interact's spec takes Glyph, Caption, and a Hover and Click table of { Icon, Text, Scale, Rotate, Hold }. It returns a table with SetIcon(name) and SetHoverIcon(name) for changing what the control rests at later — which a control whose meaning flips, like a minimise button, needs.

The pointer helpers — pointerPosition, pointerInside, watchPointer, setCursor and Util.Cursors — are documented under Pointer and cursor helpers.

Cards and panels#

A control's row is a card. Controls.mount is the usual way in, since it also registers the row for search:

Ember.RegisterControl("Badge", function(section, opts)
    local card, slot = Ember.Controls.mount(section, opts)
    -- put your control in `slot`
    return { Instance = card }
end)

Ember.Card.new(parent, opts) is the same card without the registration, for a row outside a section. It returns six values:

Ember.Panel.round(frame, radius?, sides?, colour?) rounds a frame and squares off named sides, for a panel that has to butt up against another.

Ember.Panel.round(myFrame, 8, { "top", "left" })

sides takes any of "top", "bottom", "left", "right". It returns false if the frame is not a GuiObject.

The measurement tables#

Read these so a control you build lines up with the ones that ship.

Ember.Metrics.control      --> 26, the height of every control
Ember.Metrics.ctlRadius    --> 6, their corner radius
Ember.Metrics.controlCol   --> 104, the minimum width of the right-hand column

Tune the dissolve through Configure rather than by writing to Fx.

Odds and ends#

Section:ClosePopups(except?) shuts every open dropdown and picker in a section, optionally sparing one instance. A control that opens its own popup should call it so two menus are never open at once.