6 KiB
Element Creation API
create()
Creates a new UI element, applying any given properties.
Type
function create(classNameOrInstance: string | Instance): (properties: Map<string, any>) -> Instance
Details
The function can take either a string or an Instance as its first argument.
- If given a
string, a new instance with the string class name will be created with default properties already applied. - If given an
Instance, a new instance that is a clone of the given instance will be created.
This returns another function that is used to apply any properties to the new instance.
Example
local frame = create("Frame") {
Name = "NewFrame",
Position = UDim2.fromScale(1, 0)
}
-- creates a clone of `frame` with new properties applied.
local frame2 = create(frame) {
Size = UDim2.fromOffset(50, 100)
}
apply()
Applies any given properties to a given instance.
Type
function apply(instance: Instance): (properties: Map<string, any>) -> Instance
Details
Applies properties in the same manner as create for already existing existances.
Can use symbols and bind state just like create.
Example
local frame = Instance.new("Frame")
apply(frame) {
Position = UDim2.fromScale(1, 0)
}
Layout
Symbol used to pass layout properties to elements.
Type
type Layout = Symbol
type LayoutProps = {
[Symbol] = {
-- These are all properties considered to be "layout properties"
AnchorPoint: Prop<Vector2>?;
LayoutOrder: Prop<number>?;
Position: Prop<UDim2>?;
Rotation: Prop<number>?;
Size: Prop<UDim2>?;
SizeConstraint: Prop<Enum.SizeConstraint>?;
Visible: Prop<boolean>?;
ZIndex: Prop<number>?;
}
}
type Prop<T> = T | State<T>
Details
The primary purpose of this symbol is to enable easy passthrough of layout properties through user-defined component hierarchies.
It is recommended to only set layout properties using the Layout symbol when using
your own components.
Example
local function BlackFrame(props)
return create("Frame") {
BackgroundColor3 = Color3.new(0, 0, 0),
[Layout] = props[Layout]
}
end
BlackFrame {
[Layout] = {
AnchorPoint = Vector2.new(0.5, 0.5),
Position = UDim2.fromScale(0.5, 0.5),
Size = UDim2.fromOffset(100, 50)
}
}
Children
Symbol used to pass child instances to elements.
Type
type Children = Symbol
type ChildrenProps = {
[Symbol] = ChildrenProp
}
type ChildrenProp = Prop<Instance> | Array<ChildrenProp>
Details
This symbol is flexible in the way that children can be passed in the form of nested arrays.
Children can also be assigned using a state binding.
Example
create("Frame") {
-- all of the below are valid methods of assigning children
[Children] = create("TextLabel") {},
[Children] = {
create("TextLabel") {},
create("TextLabel") {},
},
[Children] = {
create("TextLabel") {},
{
create("TextLabel") {},
}
}
}
Event
Symbol used to connect callbacks to instance events.
Type
type Event = Map<string, Symbol>
type EventProps = {
[Symbol] = Prop<(...unknown) -> ()>
}
Details
The Event symbol can be indexed to get symbols to connect to specific events.
Event parameters are passed into the callback.
When callbacks are connected by binding to a state, connections are automatically disconnected when the state changes.
Example
create("TextButton") {
[Event.Activated] = function()
print("Clicked")
end
}
Changed
Symbol used to connect callbacks to instance property changed events.
Type
type Changed = Map<string, Symbol>
type ChangedProps = {
[Symbol] = Prop<(...unknown) -> ()>
}
Details
The Changed symbol can be indexed to get symbols to connect to specific events just like Event.
Event parameters are passed into the callback.
When callbacks are connected by binding to a state, connections are automatically disconnected when the state changes.
Example
create("TextBox") {
[Changed.Text] = function()
print("New text entered")
end
}
Bind
Symbol used to bind states to instance properties.
Type
type Bind = Map<string, Symbol>
type BindProps = {
[Symbol] = State<any>
}
Details
The Bind symbol can be indexed to bind specific properties just like Event.
Sets the given state value to the instance property value immediately after instance creation.
When an instance property is changed, the value of the given state will automatically be set to the new property. Effectively a shorthand for connecting a property changed event to set state values.
Example
local text = wrap()
local box = create("TextBox") {
[Bind.Text] = text
}
box.Text = "New text"
print(text.Value) -- "New text"
Created
Symbol used to run a callback once immediately after instance creation.
Type
type Created = Symbol
type CreatedProps = {
[Symbol] = (Instance) -> ()
}
Details
The instance being defined with the Created symbol is passed as the first
argument to the callback.
Example
local frame
create("Frame") {
Name = "Background",
[Created] = function(instance)
frame = instance
end
}
print(frame.Name) -- "Background"