Init

content/ui-systems/ui-properties.en.md

@@ -0,0 +1,384 @@
+---
+title: UI Properties
+type: docs
+weight: 13
+---
+
+This page documents common properties available on UI widgets.
+
+## Anchor (Positioning)
+
+The `Anchor` property controls widget position and size.
+
+### Position Properties
+
+```
+Anchor: (
+  Left: 10,      // Distance from left edge
+  Right: 10,     // Distance from right edge
+  Top: 10,       // Distance from top edge
+  Bottom: 10     // Distance from bottom edge
+);
+```
+
+### Size Properties
+
+```
+Anchor: (
+  Width: 200,    // Fixed width
+  Height: 100    // Fixed height
+);
+```
+
+### Shorthand Properties
+
+```
+Anchor: (Full: 10);           // All sides = 10
+Anchor: (Horizontal: 20);     // Left and Right = 20
+Anchor: (Vertical: 15);       // Top and Bottom = 15
+```
+
+### Combined Example
+
+```
+// Fixed size, positioned from top-left
+Anchor: (Left: 50, Top: 100, Width: 300, Height: 200);
+
+// Fill parent with margins
+Anchor: (Full: 16);
+
+// Anchored to bottom-right corner
+Anchor: (Right: 20, Bottom: 20, Width: 100, Height: 40);
+
+// Full width, fixed height at bottom
+Anchor: (Horizontal: 0, Bottom: 0, Height: 50);
+```
+
+## Background
+
+The `Background` property sets widget background appearance.
+
+### Solid Color
+
+```
+Background: (Color: #ff5500);
+Background: (Color: #000000(0.5));    // With opacity
+```
+
+### Simple Texture
+
+```
+Background: "MyTexture.png";
+Background: (TexturePath: "MyTexture.png");
+```
+
+### 9-Patch (Stretchable) Texture
+
+```
+// Uniform border
+Background: (TexturePath: "Panel.png", Border: 20);
+
+// Separate horizontal/vertical borders
+Background: (
+  TexturePath: "Button.png",
+  HorizontalBorder: 80,
+  VerticalBorder: 12
+);
+```
+
+### Using PatchStyle
+
+```
+@MyBackground = PatchStyle(
+  TexturePath: "Panel.png",
+  Border: 16
+);
+
+Group {
+  Background: @MyBackground;
+}
+```
+
+## Padding
+
+The `Padding` property sets inner spacing.
+
+```
+Padding: (Full: 16);              // All sides
+Padding: (Horizontal: 20);        // Left and Right
+Padding: (Vertical: 10);          // Top and Bottom
+Padding: (Left: 10, Right: 20);   // Individual sides
+Padding: (Top: 5, Bottom: 15, Horizontal: 10);
+```
+
+### Using Padding Constructor
+
+```
+@ContentPadding = Padding(Full: 16, Top: 8);
+
+Group {
+  Padding: @ContentPadding;
+}
+```
+
+## LayoutMode
+
+The `LayoutMode` property controls how children are arranged.
+
+### Stacking Modes
+
+| Mode | Description |
+|------|-------------|
+| `Top` | Stack children from top to bottom |
+| `Bottom` | Stack children from bottom to top |
+| `Left` | Stack children from left to right |
+| `Right` | Stack children from right to left |
+
+```
+Group {
+  LayoutMode: Top;      // Vertical list, top-aligned
+
+  Label { Text: "First"; Anchor: (Height: 30); }
+  Label { Text: "Second"; Anchor: (Height: 30); }
+  Label { Text: "Third"; Anchor: (Height: 30); }
+}
+```
+
+### Centering Modes
+
+| Mode | Description |
+|------|-------------|
+| `Middle` | Center children vertically |
+| `CenterMiddle` | Center children both horizontally and vertically |
+
+```
+Group {
+  LayoutMode: CenterMiddle;
+
+  Label { Text: "Centered!"; }
+}
+```
+
+### Scrolling Modes
+
+| Mode | Description |
+|------|-------------|
+| `TopScrolling` | Vertical scroll, content from top |
+| `BottomScrolling` | Vertical scroll, content from bottom (chat-style) |
+
+```
+Group #ChatLog {
+  LayoutMode: BottomScrolling;
+  ScrollbarStyle: @DefaultScrollbarStyle;
+  AutoScrollDown: true;
+}
+```
+
+### Wrapping Mode
+
+| Mode | Description |
+|------|-------------|
+| `LeftCenterWrap` | Flow left-to-right, wrap to next row |
+
+```
+Group #ItemGrid {
+  LayoutMode: LeftCenterWrap;
+
+  // Items will wrap to new rows
+}
+```
+
+## FlexWeight
+
+The `FlexWeight` property controls flexible sizing in layout.
+
+```
+Group {
+  LayoutMode: Left;
+
+  Group {
+    Anchor: (Width: 100);    // Fixed width
+  }
+
+  Group {
+    FlexWeight: 1;           // Takes remaining space
+  }
+
+  Group {
+    FlexWeight: 2;           // Takes 2x the space of FlexWeight: 1
+  }
+}
+```
+
+## Visible
+
+Controls widget visibility.
+
+```
+Group #Panel {
+  Visible: true;    // or false, or @Variable
+}
+
+Button #CloseButton {
+  Visible: @CloseButton;    // Controlled by template parameter
+}
+```
+
+## Text
+
+Sets text content for Label and TextButton widgets.
+
+```
+Label {
+  Text: "Static text";
+}
+
+Label {
+  Text: %server.ui.title;    // Translation key
+}
+
+Label #DynamicText {
+  Text: "";                  // Set from Java
+}
+```
+
+## ScrollbarStyle
+
+Configures scrollbar appearance for scrolling containers.
+
+```
+Group {
+  LayoutMode: TopScrolling;
+  ScrollbarStyle: (
+    Spacing: 6,
+    Size: 6,
+    Background: (TexturePath: "Scrollbar.png", Border: 3),
+    Handle: (TexturePath: "ScrollbarHandle.png", Border: 3),
+    HoveredHandle: (TexturePath: "ScrollbarHandleHovered.png", Border: 3),
+    DraggedHandle: (TexturePath: "ScrollbarHandleDragged.png", Border: 3)
+  );
+}
+```
+
+### ScrollbarStyle Options
+
+| Property | Description |
+|----------|-------------|
+| `Spacing` | Gap between scrollbar and content |
+| `Size` | Scrollbar width/height |
+| `Background` | Track background |
+| `Handle` | Normal handle appearance |
+| `HoveredHandle` | Handle when hovered |
+| `DraggedHandle` | Handle when dragging |
+| `OnlyVisibleWhenHovered` | Hide when not interacting |
+
+## AutoScrollDown
+
+For BottomScrolling containers, automatically scroll to new content.
+
+```
+Group #ChatLog {
+  LayoutMode: BottomScrolling;
+  AutoScrollDown: true;
+}
+```
+
+## Disabled
+
+Disables interaction with a widget.
+
+```
+Button #SubmitButton {
+  Disabled: false;
+}
+
+ActionButton #Binding {
+  Disabled: true;
+}
+```
+
+## TooltipText
+
+Displays tooltip on hover.
+
+```
+Button #InfoButton {
+  TooltipText: %ui.tooltip.help;
+}
+```
+
+## TextTooltipStyle
+
+Configures tooltip appearance.
+
+```
+Button {
+  TooltipText: "Help text";
+  TextTooltipStyle: (
+    Background: (TexturePath: "TooltipBg.png", Border: 24),
+    MaxWidth: 400,
+    LabelStyle: (Wrap: true, FontSize: 16),
+    Padding: 24
+  );
+}
+```
+
+## Common Property Combinations
+
+### Panel with Title and Content
+
+```
+Group #Panel {
+  Anchor: (Width: 400, Height: 300);
+  Background: (TexturePath: "Panel.png", Border: 20);
+  LayoutMode: Top;
+  Padding: (Full: 16);
+
+  Label #Title {
+    Anchor: (Height: 40);
+    // ...
+  }
+
+  Group #Content {
+    FlexWeight: 1;
+    LayoutMode: TopScrolling;
+    ScrollbarStyle: @DefaultScrollbarStyle;
+    Padding: (Top: 8);
+  }
+}
+```
+
+### Horizontal Button Row
+
+```
+Group #ButtonRow {
+  Anchor: (Height: 50);
+  LayoutMode: Right;
+  Padding: (Horizontal: 10);
+
+  TextButton #Cancel {
+    Anchor: (Width: 100);
+  }
+
+  Group { Anchor: (Width: 10); }  // Spacer
+
+  TextButton #Confirm {
+    Anchor: (Width: 100);
+  }
+}
+```
+
+### Full-Screen Overlay
+
+```
+Group #Overlay {
+  Anchor: (Full: 0);
+  Background: (Color: #000000(0.7));
+  LayoutMode: CenterMiddle;
+
+  Group #Dialog {
+    Anchor: (Width: 500, Height: 300);
+    Background: (TexturePath: "Dialog.png", Border: 20);
+  }
+}
+```