# Creating Elements

This guide covers how to create canvases and elements in DisplayKit.

> [!IMPORTANT]
> You will have to add a reference to `UnityEngine.UIElementsModule` and `UnityEngine.TextRenderingModule` to use certain properties.

## Table of Contents

- [Creating a Canvas](#creating-a-canvas)
- [Adding Container Elements](#adding-container-elements)
- [Adding Text Elements](#adding-text-elements)
- [Nested Elements](#nested-elements)

---

## Creating a Canvas

Use the static factory method to create a new canvas:

```csharp
using DisplayKit.Elements;
using UnityEngine;

// Create a new canvas
DisplayCanvas canvas = DisplayCanvas.Create();

// Configure canvas properties
canvas.DefaultVisibility = CanvasVisibility.Visible; // or Hidden, with Visible being default
canvas.SortOrder = 10; // UI layering order

// Set background color
canvas.Background.Color = new Color(0.1f, 0.1f, 0.1f, 0.9f);

// Sets default text color for all text elements in this canvas
canvas.Text.Color = Color.white;

// Make it fill the screen
canvas.Flex.Grow = 1f;
```
![Result](Images/example2.png)

### Canvas Properties

| Property | Type | Description |
|----------|------|-------------|
| `DefaultVisibility` | `CanvasVisibility` | Initial visibility (`Visible` or `Hidden`) |
| `SortOrder` | `int?` | UI layering priority (higher = on top) |

See [Style Properties](DisplayKit-StyleProperties#text-textdata) for all styling options.

---

## Adding Container Elements

Container elements (`DisplayElement`) can hold other elements and are used for layout organization:

```csharp
// Add a container to the canvas
DisplayElement container = canvas.AddElement();

// Configure the container
container.Flex.Grow = 1f;
container.Flex.Direction = FlexDirection.Column;
container.Align.JustifyContent = Justify.Center;
container.Align.AlignItems = Align.Center;

// Add background and margin
container.Background.Color = new Color(0.5f, 0.5f, 0.5f, 0.9f);
container.Spacing.MarginBottom = new Length(20, LengthUnit.Pixel);
container.Spacing.MarginTop = new Length(20, LengthUnit.Pixel);
container.Spacing.MarginLeft = new Length(20, LengthUnit.Pixel);
container.Spacing.MarginRight = new Length(20, LengthUnit.Pixel);
```
![Result](Images/example3.png)

### Container Element Methods

| Method | Returns | Description |
| --- | --- | --- |
| `AddElement()` | `DisplayElement` | Add a child container element |
| `AddText(string text)` | `DisplayText` | Add a child text element |

See [Style Properties](DisplayKit-StyleProperties#text-textdata) for all styling options.

---

## Adding Text Elements

Text elements (`DisplayText`) display text content:

```csharp
// Add text to an element
DisplayText titleText = canvas.AddText("Welcome to DisplayKit");

// Configure text appearance
titleText.Text.Font = FontType.RobotoBold;
titleText.Text.FontSize = 32f;
titleText.Text.Color = Color.white;
titleText.Text.Align = TextAnchor.MiddleCenter;

// Add text shadow
titleText.Text.TextShadow = new TextShadow
{
    color = new Color(0, 0, 0, 0.5f),
    offset = new Vector2(2, 2),
    blurRadius = 3f
};

// Configure spacing
titleText.Spacing.MarginBottom = 10f;
```
![Result](Images/example4.png)

### Text Element Properties

| Property | Type | Description |
| --- | --- | --- |
| `Value` | `string` | The text content to display |

See [Style Properties](DisplayKit-StyleProperties#text-textdata) for all text styling options.

---

## Nested Elements

Build complex hierarchies by nesting elements:

```csharp
// Create main container
DisplayElement mainContainer = canvas.AddElement();
mainContainer.Flex.Direction = FlexDirection.Row;
mainContainer.Flex.Grow = 1f;

// Sets default text color for all text elements in this container.
mainContainer.Text.Color = Color.white;

// Left panel
DisplayElement leftPanel = mainContainer.AddElement();
leftPanel.Size.Width = 200f;
leftPanel.Background.Color = new Color(0.2f, 0.2f, 0.2f);

// Right panel
DisplayElement rightPanel = mainContainer.AddElement();
rightPanel.Flex.Grow = 1f;
rightPanel.Background.Color = new Color(0.15f, 0.15f, 0.15f);

// Add content to panels
DisplayText leftText = leftPanel.AddText("Left Panel");
DisplayText rightText = rightPanel.AddText("Right Panel");
```
![Result](Images/example5.png)

### Hierarchy Example

```
Canvas (root)
└── MainContainer (Row)
    ├── LeftPanel (200px width)
    │   └── Text: "Left Panel"
    └── RightPanel (flex grow)
        └── Text: "Right Panel"
```

---

## Common Patterns

### Centered Content

```csharp
DisplayCanvas canvas = DisplayCanvas.Create();
canvas.Align.AlignItems = Align.Center;
canvas.Align.JustifyContent = Justify.Center;

// Sets default text color for all text elements in this canvas
canvas.Text.Color = Color.white;

DisplayText text = canvas.AddText("Centered Text");
```
![Result](Images/example6.png)

### Full-Screen Panel

```csharp
DisplayCanvas canvas = DisplayCanvas.Create();
canvas.Flex.Grow = 1f; // Fill available space

DisplayElement panel = canvas.AddElement();
panel.Size.Width = Length.Percent(100f);
panel.Size.Height = Length.Percent(100f);
panel.Background.Color = Color.black;
```
![Result](Images/example7.png)

### Horizontal Layout

```csharp
DisplayElement row = canvas.AddElement();
row.Flex.Direction = FlexDirection.Row;
row.Align.JustifyContent = Justify.SpaceAround;

row.AddText("Item 1");
row.AddText("Item 2");
row.AddText("Item 3");
```
![Result](Images/example8.png)

### Vertical Layout

```csharp
DisplayElement column = canvas.AddElement();
column.Flex.Direction = FlexDirection.Column;
column.Align.AlignItems = Align.Center;

column.AddText("Title");
column.AddText("Subtitle");
column.AddText("Description");
```
![Result](Images/example9.png)

---

## Next Steps

- [Modifying Elements](DisplayKit-ModifyingElements) - Learn how to update elements after creation
- [Sending to Players](DisplayKit-SendingToPlayers) - Understand per-player vs global canvases
- [Style Properties](DisplayKit-StyleProperties) - Explore all styling options