hakowork/vide
3
0
Fork 0
mirror of https://github.com/centau/vide.git synced 2026-08-20 14:41:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Browse source
This commit is contained in:
Aaron Smith 2023-08-03 15:06:40 +01:00
parent 5057b7772b
commit 8e31946dda
9 changed files with 234 additions and 775 deletions
Download patch file Download diff file Expand all files Collapse all files

350
docs/api/creation.md
View file

@ -6,320 +6,76 @@
Creates a new UI element, applying any given properties.
### Type
- ### Type
```lua
function create(classNameOrInstance: string | Instance): (properties: Map<string, any>) -> Instance
```
```lua
function create(class: string): (Properties) -> Instance
function create(instance: Instace): (Properties) -> Instance
### Details
type Properties = Map<string|number, any>
```
The function can take either a `string` or an `Instance` as its first argument.
- ### Details
- 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.
The function can take either a `string` or an `Instance` as its first argument.
This returns another function that is used to apply any properties to the new instance.
- If given a `string`, a new instance with the same class name will be created.
- If given an `Instance`, a new instance that is a clone of the given instance
will be created.
### Example
This returns another function that is used to apply any properties to the new
instance.
```lua
local frame = create("Frame") {
Name = "NewFrame",
Position = UDim2.fromScale(1, 0)
}
- ### Property setting rules
-- creates a clone of `frame` with new properties applied.
local frame2 = create(frame) {
Size = UDim2.fromOffset(50, 100)
}
```
- If a table value is another table, that nested table is processed so that
any properties inside that table are also applied to the instance just
like the outer table.
- If a table index is a string:
- If its value is a function then it will either bind that property to
a state or connect it if the property type is a `RBXScriptSignal`.
- If the value is not a function then the property will be set to that
value.
- If a table index is a number:
- If its value is a function then it will parent any instances returned by
that function as children.
- If its value is an instance then it will be parented to the instance.
-------------------------------------------------------------------
- ### Example
<br/>
Basic element creation.
## apply()
Applies any given properties to a given instance.
### Type
```lua
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
```lua
local frame = Instance.new("Frame")
apply(frame) {
Position = UDim2.fromScale(1, 0)
}
```
-------------------------------------------------------------------
<br/>
## Layout
Symbol used to pass layout properties to elements.
### Type
```lua
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>?;
```lua
local frame = create "Frame" {
Name = "NewFrame",
Position = UDim2.fromScale(1, 0)
}
}
```
type Prop<T> = T | State<T>
```
A component using property nesting/grouping.
### 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
```lua
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)
}
}
```
-------------------------------------------------------------------
<br/>
## Children
Symbol used to pass child instances to elements.
### Type
```lua
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
```lua
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") {},
```lua
type Layout = {
Layout = {
Position: UDim2?,
Size: UDim2?,
AnchorPoint: Vector2?
}
}
}
```
-------------------------------------------------------------------
type Children = {
Children = Array<Instance>
}
<br/>
## Event
Symbol used to connect callbacks to instance events.
### Type
```lua
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
```lua
create("TextButton") {
[Event.Activated] = function()
print("Clicked")
function Background(props: Layout & Children & {
Color: Color3
})
return create "Frame" {
BackgroundColor3 = Color,
props.Layout,
props.Children
}
end
}
```
```
-------------------------------------------------------------------
<br/>
## Changed
Symbol used to connect callbacks to instance property changed events.
### Type
```lua
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
```lua
create("TextBox") {
[Changed.Text] = function()
print("New text entered")
end
}
```
-------------------------------------------------------------------
<br/>
## Bind
Symbol used to bind states to instance properties.
### Type
```lua
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
```lua
local text = wrap()
local box = create("TextBox") {
[Bind.Text] = text
}
box.Text = "New text"
print(text.Value) -- "New text"
```
-------------------------------------------------------------------
<br/>
## Created
Symbol used to run a callback once immediately after instance creation.
### Type
```lua
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
```lua
local frame
create("Frame") {
Name = "Background",
[Created] = function(instance)
frame = instance
end
}
print(frame.Name) -- "Background"
```
-------------------------------------------------------------------
--------------------------------------------------------------------------------