OTUI documentation (LLM-generated)

Images.md

Here is the documentation for defining the style of an image in OTUI using the properties handled in uiwidgetimage.cpp.

---

Defining Image Styles in OTUI

The UIWidget class supports various properties for styling images. These properties allow you to define the source, size, position, appearance, and behavior of images in your OTUI files.

---

Image Style Properties

1. Image Source

• image-source: Specifies the source of the image.
  • Type: String.
  • Format:
    • File path (e.g., images/example.png).
    • Base64-encoded string (e.g., base64:...).
    • "none" to remove the image.
  • Example:

    image-source: "images/example.png"
    image-source: "base64:...encoded-data..."
    image-source: "none"
    

---

2. Image Position

• image-offset-x: Sets the horizontal offset of the image.

  • Type: Integer.
  • Example: image-offset-x: 10

• image-offset-y: Sets the vertical offset of the image.

  • Type: Integer.
  • Example: image-offset-y: 20

• image-offset: Sets both horizontal and vertical offsets as a point.

  • Type: Point (e.g., x y).
  • Example: image-offset: 10 20

---

3. Image Size

• image-width: Sets the width of the image.

  • Type: Integer.
  • Example: image-width: 100

• image-height: Sets the height of the image.

  • Type: Integer.
  • Example: image-height: 50

• image-size: Sets both width and height of the image.

  • Type: Size (e.g., width height).
  • Example: image-size: 100 50

---

4. Image Clipping

• image-rect: Defines the rectangle of the image to be displayed.

  • Type: Rect (e.g., x y width height).
  • Example: image-rect: 0 0 50 50

• image-clip: Specifies the clipping rectangle for the image.

  • Type: Rect (e.g., x y width height).
  • Example: image-clip: 10 10 40 40

---

5. Image Appearance

• image-fixed-ratio: Maintains the aspect ratio of the image.

  • Type: Boolean (true or false).
  • Example: image-fixed-ratio: true

• image-repeated: Repeats the image to fill the widget.

  • Type: Boolean (true or false).
  • Example: image-repeated: true

• image-smooth: Enables smoothing for the image.

  • Type: Boolean (true or false).
  • Example: image-smooth: true

• image-color: Applies a color overlay to the image.

  • Type: Color (e.g., #RRGGBBAA).
  • Example: image-color: #FF0000FF

---

6. Image Borders

• image-border-top: Sets the top border size of the image.

  • Type: Integer.
  • Example: image-border-top: 5

• image-border-right: Sets the right border size of the image.

  • Type: Integer.
  • Example: image-border-right: 5

• image-border-bottom: Sets the bottom border size of the image.

  • Type: Integer.
  • Example: image-border-bottom: 5

• image-border-left: Sets the left border size of the image.

  • Type: Integer.
  • Example: image-border-left: 5

• image-border: Sets all border sizes to the same value.

  • Type: Integer.
  • Example: image-border: 5

---

7. Image Behavior

• image-auto-resize: Automatically resizes the widget to fit the image.

  • Type: Boolean (true or false).
  • Example: image-auto-resize: true

• image-individual-animation: Enables individual animation for animated textures.

  • Type: Boolean (true or false).
  • Example: image-individual-animation: true

---

Example OTUI Definition

Widget
  id: exampleWidget
  image-source: "images/example.png"
  image-offset: 10 20
  image-size: 100 50
  image-fixed-ratio: true
  image-smooth: true
  image-border: 5
  image-color: #FFFFFF80
  image-auto-resize: true

---

This documentation provides a comprehensive overview of the image-related properties available in OTUI. These properties allow you to customize the appearance and behavior of images in your widgets.

Layouts.md

Here is a detailed documentation of layout usage in OTUI, based on the provided code for various layout types (UIBoxLayout, UIVerticalLayout, UIHorizontalLayout, UIGridLayout, and UIAnchorLayout).

---

OTUI Layouts Documentation

Layouts in OTUI are used to organize and position child widgets within a parent widget. Each layout type has specific properties and behaviors that can be configured in OTUI files.

---

1. Box Layout

Description

The UIBoxLayout is a base class for layouts that arrange widgets in a single direction (horizontal or vertical). It provides basic properties like spacing and child fitting.

Common Properties

• spacing: Sets the spacing between child widgets.
  • Type: Integer.
  • Example: spacing: 10
• fit-children: Automatically adjusts the parent widget's size to fit its children.
  • Type: Boolean (true or false).
  • Example: fit-children: true

---

2. Vertical Layout

Description

The UIVerticalLayout arranges child widgets vertically, from top to bottom or bottom to top (if align-bottom is enabled).

Properties

• align-bottom: Aligns child widgets to the bottom of the parent widget.
  • Type: Boolean (true or false).
  • Example: align-bottom: true

Example

VerticalLayout
  spacing: 5
  fit-children: true
  align-bottom: false
  children:
    Label
      text: "Item 1"
    Label
      text: "Item 2"

---

3. Horizontal Layout

Description

The UIHorizontalLayout arranges child widgets horizontally, from left to right or right to left (if align-right is enabled).

Properties

• align-right: Aligns child widgets to the right of the parent widget.
  • Type: Boolean (true or false).
  • Example: align-right: true

Example

HorizontalLayout
  spacing: 10
  fit-children: true
  align-right: false
  children:
    Button
      text: "OK"
    Button
      text: "Cancel"

---

4. Grid Layout

Description

The UIGridLayout arranges child widgets in a grid with configurable cell sizes, spacing, and flow.

Properties

• cell-size: Sets the size of each grid cell.
  • Type: Size (e.g., width height).
  • Example: cell-size: 50 50
• cell-width: Sets the width of each grid cell.
  • Type: Integer.
  • Example: cell-width: 50
• cell-height: Sets the height of each grid cell.
  • Type: Integer.
  • Example: cell-height: 50
• cell-spacing: Sets the spacing between grid cells.
  • Type: Integer.
  • Example: cell-spacing: 5
• num-columns: Sets the number of columns in the grid.
  • Type: Integer.
  • Example: num-columns: 3
• num-lines: Sets the number of rows in the grid.
  • Type: Integer.
  • Example: num-lines: 2
• fit-children: Automatically adjusts the parent widget's size to fit its children.
  • Type: Boolean (true or false).
  • Example: fit-children: true
• auto-spacing: Automatically adjusts spacing between cells to fit the grid.
  • Type: Boolean (true or false).
  • Example: auto-spacing: true
• flow: Enables flow layout, where widgets are placed in rows based on available space.
  • Type: Boolean (true or false).
  • Example: flow: true

Example

GridLayout
  cell-size: 50 50
  cell-spacing: 10
  num-columns: 3
  fit-children: true
  flow: true
  children:
    Button
      text: "1"
    Button
      text: "2"
    Button
      text: "3"
    Button
      text: "4"

---

5. Anchor Layout

Description

The UIAnchorLayout allows precise positioning of child widgets by anchoring them to specific edges or centers of other widgets or the parent widget.

Properties

• anchors.*: Defines anchors for the widget. Anchors specify how a widget is positioned relative to another widget or the parent widget.
  • Type: String (e.g., fill, centerIn, or widget.edge).
  • Examples:
    • anchors.fill: parent
    • anchors.centerIn: parent
    • anchors.left: otherWidget.right

Special Anchors

• fill: Stretches the widget to fill the parent or another widget.
• centerIn: Centers the widget within the parent or another widget.

Example

AnchorLayout
  children:
    Label
      text: "Centered"
      anchors.centerIn: parent
    Button
      text: "Bottom Right"
      anchors.bottom: parent.bottom
      anchors.right: parent.right

---

Summary Table

Layout Type	Key Properties	Description
Box Layout	spacing, fit-children	Base layout for vertical and horizontal layouts.
Vertical Layout	align-bottom	Arranges widgets vertically.
Horizontal Layout	align-right	Arranges widgets horizontally.
Grid Layout	cell-size, cell-spacing, num-columns, fit-children, flow	Arranges widgets in a grid.
Anchor Layout	anchors.*	Positions widgets using anchors relative to other widgets or the parent.

---

This documentation provides an overview of how to use layouts in OTUI files, including their properties and examples. Each layout type is designed to handle specific use cases for widget arrangement and positioning.

OTUI.md

The OTUI format is parsed and processed using the OTMLDocument and OTMLNode classes, which are part of the OTML (Open Tibia Markup Language) framework. Below is a documentation draft for the OTUI format:

---

OTUI Format Documentation

The OTUI format is a custom markup language used in the OTClient project to define user interface elements, styles, and layouts. It is based on the OTML (Open Tibia Markup Language) framework and is parsed using the OTMLDocument and OTMLNode classes.

Structure

An OTUI file consists of hierarchical nodes, where each node represents a widget, style, or property. Nodes can have attributes, child nodes, and values.

Example

MainWindow
  size: 800 600
  background-color: #000000
  children:
    Button
      id: closeButton
      text: "Close"
      size: 100 50
      position: 700 550

Key Components

1. Nodes: Represent elements in the UI, such as widgets or styles.
2. Attributes: Define properties of a node, such as size, position, or color.
3. Child Nodes: Represent nested elements or sub-widgets.

---

Syntax

Nodes

• Each node starts with a tag name.
• Tags can represent widgets, styles, or other UI elements.

Attributes

• Attributes are defined as key: value pairs.
• Common attributes include:
  • id: A unique identifier for the widget.
  • size: The width and height of the widget.
  • position: The x and y coordinates of the widget.
  • text: The text displayed on the widget.
  • background-color: The background color of the widget.

Child Nodes

• Child nodes are indented under their parent node.
• The children attribute can be used to group child nodes explicitly.

---

Parsing and Validation

The OTUI format is parsed using the OTMLDocument and OTMLNode classes. Key methods include:

• OTMLDocument::parse: Parses an OTUI file or input stream into an OTML document.
• OTMLNode::children: Retrieves the child nodes of a given node.
• UIManager::loadUI: Loads an OTUI file and creates widgets based on its content.

Error Handling

Errors in OTUI files are reported using the OTMLException class, which provides detailed error messages, including the source file and line number.

---

Integration with OTClient

The OTUI format is tightly integrated with the OTClient project. Widgets and styles defined in OTUI files are processed and rendered using the UIManager class. Key methods include:

• UIManager::createWidgetFromOTML: Creates a widget from an OTML node.
• UIManager::importStyleFromOTML: Imports styles from an OTML document.

---

Advanced Features

Device-Specific Styles

The UIManager::loadDeviceUI method allows loading device-specific styles by appending a device name to the file name (e.g., file.desktop.otui).

Dynamic UI Loading

The UIManager::loadUIFromString method enables loading UI definitions dynamically from a string.

---

References

• OTMLDocument (/otclient/src/framework/otml/otmldocument.h)
• OTMLNode (/otclient/src/framework/otml/otmlnode.h)
• UIManager (/otclient/src/framework/ui/uimanager.h)
• OTMLException (/otclient/src/framework/otml/otmlexception.h)

UITextEdit.md

Here is the documentation for using UITextEdit in OTUI. This widget is an advanced text input field that supports features like text editing, selection, placeholders, and more.

---

Using UITextEdit in OTUI

The UITextEdit widget is a versatile text input field that allows users to input, edit, and interact with text. It supports various properties for customization, including text alignment, selection, placeholders, and more.

---

UITextEdit Style Properties

1. Text Content

• text: The text to be displayed or edited in the widget.

  • Type: String.
  • Example: text: "Enter your name"

• text-hidden: Hides the text by replacing it with asterisks (e.g., for password fields).

  • Type: Boolean (true or false).
  • Example: text-hidden: true

---

2. Text Behavior

• editable: Enables or disables text editing.

  • Type: Boolean (true or false).
  • Example: editable: true

• multiline: Allows multiple lines of text.

  • Type: Boolean (true or false).
  • Example: multiline: true

• max-length: Sets the maximum number of characters allowed in the text field.

  • Type: Integer.
  • Example: max-length: 50

• shift-navigation: Enables navigation using the Shift key.

  • Type: Boolean (true or false).
  • Example: shift-navigation: true

---

3. Text Selection

• selectable: Enables or disables text selection.

  • Type: Boolean (true or false).
  • Example: selectable: true

• selection-color: Sets the color of the selected text.

  • Type: Color (e.g., #RRGGBBAA).
  • Example: selection-color: #FFFFFF

• selection-background-color: Sets the background color of the selected text.

  • Type: Color (e.g., #RRGGBBAA).
  • Example: selection-background-color: #0000FF

• selection: Defines the selection range as a point (start and end positions).

  • Type: Point (e.g., start end).
  • Example: selection: 0 5

---

4. Cursor Behavior

• cursor-visible: Shows or hides the text cursor.

  • Type: Boolean (true or false).
  • Example: cursor-visible: true

• change-cursor-image: Changes the cursor image when hovering over the text field.

  • Type: Boolean (true or false).
  • Example: change-cursor-image: true

---

5. Scrolling

• auto-scroll: Automatically scrolls the text field to keep the cursor visible.
  • Type: Boolean (true or false).
  • Example: auto-scroll: true

---

6. Placeholder

• placeholder: Sets the placeholder text to display when the text field is empty.

  • Type: String.
  • Example: placeholder: "Enter text here"

• placeholder-color: Sets the color of the placeholder text.

  • Type: Color (e.g., #RRGGBBAA).
  • Example: placeholder-color: #AAAAAA

• placeholder-align: Aligns the placeholder text within the widget.

  • Type: String.
  • Values:
    • left
    • right
    • center
    • top-left
    • top-right
    • bottom-left
    • bottom-right
  • Example: placeholder-align: center

• placeholder-font: Specifies the font for the placeholder text.

  • Type: String (font name).
  • Example: placeholder-font: "verdana-11px"

---

Example OTUI Definition

TextEdit
  id: exampleTextEdit
  text: "Hello, World!"
  text-hidden: false
  editable: true
  multiline: true
  max-length: 100
  selectable: true
  selection-color: #FFFFFF
  selection-background-color: #0000FF
  cursor-visible: true
  auto-scroll: true
  placeholder: "Type something..."
  placeholder-color: #AAAAAA
  placeholder-align: center
  placeholder-font: "verdana-11px"

---

Summary Table

Property	Type	Description	Example
text	String	The text to display or edit.	text: "Hello, World!"
text-hidden	Boolean	Hides the text (e.g., for passwords).	text-hidden: true
editable	Boolean	Enables or disables text editing.	editable: true
multiline	Boolean	Allows multiple lines of text.	multiline: true
max-length	Integer	Sets the maximum number of characters.	max-length: 50
selectable	Boolean	Enables or disables text selection.	selectable: true
selection-color	Color	Sets the color of the selected text.	selection-color: #FFFFFF
selection-background-color	Color	Sets the background color of the selection.	selection-background-color: #0000FF
cursor-visible	Boolean	Shows or hides the text cursor.	cursor-visible: true
auto-scroll	Boolean	Automatically scrolls to keep the cursor visible.	auto-scroll: true
placeholder	String	Sets the placeholder text.	placeholder: "Enter text"
placeholder-color	Color	Sets the color of the placeholder text.	placeholder-color: #AAAAAA
placeholder-align	String	Aligns the placeholder text.	placeholder-align: center
placeholder-font	String	Specifies the font for the placeholder text.	placeholder-font: "verdana-11px"

---

This documentation provides a comprehensive guide to using UITextEdit in OTUI. It covers all the properties available for customizing the behavior and appearance of the text input field.

UIWidget.md

Here is a detailed documentation of the OTUI properties handled in uiwidgetbasestyle.cpp. Each property is mapped to its corresponding C++ method and includes a description of its purpose and expected arguments.

---

OTUI Properties Documentation

General Properties

background-draw-order

• Description: Sets the draw order of the widget's background.
• Arguments: Integer.

border-draw-order

• Description: Sets the draw order of the widget's border.
• Arguments: Integer.

icon-draw-order

• Description: Sets the draw order of the widget's icon.
• Arguments: Integer.

image-draw-order

• Description: Sets the draw order of the widget's image.
• Arguments: Integer.

text-draw-order

• Description: Sets the draw order of the widget's text.
• Arguments: Integer.

---

Position and Size

x, y

• Description: Sets the x or y position of the widget.
• Arguments: Integer.

pos

• Description: Sets the position of the widget as a point.
• Arguments: Point (e.g., x y).

width, height

• Description: Sets the width or height of the widget.
• Arguments: Integer.

min-width, max-width

• Description: Sets the minimum or maximum width of the widget.
• Arguments: Integer.

min-height, max-height

• Description: Sets the minimum or maximum height of the widget.
• Arguments: Integer.

rect

• Description: Sets the widget's rectangle (position and size).
• Arguments: Rect (e.g., x y width height).

---

Background

background

• Description: Sets the background color of the widget.
• Arguments: Color (e.g., #RRGGBBAA).

background-color

• Description: Alias for background.

background-offset-x, background-offset-y

• Description: Sets the x or y offset of the background.
• Arguments: Integer.

background-offset

• Description: Sets the offset of the background as a point.
• Arguments: Point (e.g., x y).

background-width, background-height

• Description: Sets the width or height of the background.
• Arguments: Integer.

background-size

• Description: Sets the size of the background.
• Arguments: Size (e.g., width height).

background-rect

• Description: Sets the rectangle of the background.
• Arguments: Rect (e.g., x y width height).

---

Icon

icon

• Description: Sets the icon texture file.
• Arguments: String (file path).

icon-source

• Description: Alias for icon.

icon-color

• Description: Sets the color of the icon.
• Arguments: Color (e.g., #RRGGBBAA).

icon-offset-x, icon-offset-y

• Description: Sets the x or y offset of the icon.
• Arguments: Integer.

icon-offset

• Description: Sets the offset of the icon as a point.
• Arguments: Point (e.g., x y).

icon-width, icon-height

• Description: Sets the width or height of the icon.
• Arguments: Integer.

icon-size

• Description: Sets the size of the icon.
• Arguments: Size (e.g., width height).

icon-rect

• Description: Sets the rectangle of the icon.
• Arguments: Rect (e.g., x y width height).

icon-clip

• Description: Sets the clipping rectangle of the icon.
• Arguments: Rect (e.g., x y width height).

icon-align

• Description: Sets the alignment of the icon.
• Arguments: Alignment string (e.g., top-left, center, etc.).

---

Visual Properties

opacity

• Description: Sets the opacity of the widget.
• Arguments: Float (0.0 to 1.0).

rotation

• Description: Sets the rotation of the widget.
• Arguments: Float (degrees).

---

State Properties

enabled

• Description: Enables or disables the widget.
• Arguments: Boolean (true or false).

visible

• Description: Sets the visibility of the widget.
• Arguments: Boolean (true or false).

checked

• Description: Sets the checked state of the widget.
• Arguments: Boolean (true or false).

draggable

• Description: Enables or disables dragging for the widget.
• Arguments: Boolean (true or false).

on

• Description: Sets the "on" state of the widget.
• Arguments: Boolean (true or false).

focusable

• Description: Enables or disables focus for the widget.
• Arguments: Boolean (true or false).

auto-focus

• Description: Sets the auto-focus policy of the widget.
• Arguments: String (e.g., none, first, etc.).

phantom

• Description: Sets the widget as a phantom (invisible to input).
• Arguments: Boolean (true or false).

---

Size Constraints

size

• Description: Sets the size of the widget.
• Arguments: Size (e.g., width height).

fixed-size

• Description: Sets whether the widget has a fixed size.
• Arguments: Boolean (true or false).

min-size, max-size

• Description: Sets the minimum or maximum size of the widget.
• Arguments: Size (e.g., width height).

---

Clipping

clipping

• Description: Enables or disables clipping for the widget.
• Arguments: Boolean (true or false).

---

Border

border

• Description: Sets the border width and color.
• Arguments: String (e.g., width color).

border-width

• Description: Sets the border width.
• Arguments: Integer.

border-width-top, border-width-right, border-width-bottom, border-width-left

• Description: Sets the border width for each side.
• Arguments: Integer.

border-color

• Description: Sets the border color.
• Arguments: Color (e.g., #RRGGBBAA).

border-color-top, border-color-right, border-color-bottom, border-color-left

• Description: Sets the border color for each side.
• Arguments: Color (e.g., #RRGGBBAA).

---

Margin and Padding

margin

• Description: Sets the margin for all sides.
• Arguments: Integer or top right bottom left.

margin-top, margin-right, margin-bottom, margin-left

• Description: Sets the margin for a specific side.
• Arguments: Integer.

padding

• Description: Sets the padding for all sides.
• Arguments: Integer or top right bottom left.

padding-top, padding-right, padding-bottom, padding-left

• Description: Sets the padding for a specific side.
• Arguments: Integer.

---

Layout

layout

• Description: Sets the layout type for the widget.
• Arguments: String (e.g., horizontalBox, verticalBox, grid, anchor).

---

Anchors

anchors.*

• Description: Defines anchors for the widget.
• Arguments: String (e.g., fill, centerIn, or widget.edge).

---

This documentation provides a comprehensive overview of the OTUI properties handled in uiwidgetbasestyle.cpp. Each property is mapped to its corresponding method and includes its purpose and expected arguments.

WidgetText.md

Here is the documentation for using UIWidgetText in OTUI. This widget allows you to display and style text with various properties such as alignment, wrapping, font customization, and more.

---

Using UIWidgetText in OTUI

The UIWidgetText widget is used to display text in the user interface. It supports a variety of properties to control the appearance, alignment, and behavior of the text.

---

Text Style Properties

1. Text Content

• text: The text to be displayed in the widget.
  • Type: String.
  • Example: text: "Hello, World!"

---

2. Text Alignment

• text-align: Specifies the alignment of the text within the widget.
  • Type: String.
  • Values:
    • left
    • right
    • center
    • top-left
    • top-right
    • bottom-left
    • bottom-right
  • Example: text-align: center

---

3. Text Offset

• text-offset: Sets the offset of the text within the widget.
  • Type: Point (e.g., x y).
  • Example: text-offset: 10 5

---

4. Text Wrapping

• text-wrap: Enables or disables text wrapping.
  • Type: Boolean (true or false).
  • Example: text-wrap: true

---

5. Text Auto-Resize

• text-auto-resize: Automatically resizes the widget to fit the text.

  • Type: Boolean (true or false).
  • Example: text-auto-resize: true

• text-horizontal-auto-resize: Automatically resizes the widget's width to fit the text.

  • Type: Boolean (true or false).
  • Example: text-horizontal-auto-resize: true

• text-vertical-auto-resize: Automatically resizes the widget's height to fit the text.

  • Type: Boolean (true or false).
  • Example: text-vertical-auto-resize: true

---

6. Text Case

• text-only-upper-case: Converts all text to uppercase.
  • Type: Boolean (true or false).
  • Example: text-only-upper-case: true

---

7. Font Customization

• font: Specifies the font to be used for the text.

  • Type: String (font name).
  • Example: font: "verdana-11px"

• font-scale: Scales the font size.

  • Type: Float.
  • Example: font-scale: 1.5

---

Example OTUI Definition

Widget
  id: exampleTextWidget
  text: "Hello, OTClient!"
  text-align: center
  text-offset: 5 5
  text-wrap: true
  text-auto-resize: true
  text-only-upper-case: false
  font: "verdana-11px"
  font-scale: 1.2

---

Advanced Features

Colored Text

The UIWidgetText widget supports colored text using a special syntax. Colors can be applied to specific parts of the text.

• Syntax: {text,color}
  • Example: {Hello,#FF0000} {World,#00FF00}

Example with Colored Text

Widget
  id: coloredTextWidget
  text: "{Hello,#FF0000} {World,#00FF00}"
  text-align: left
  font: "verdana-11px"

---

Summary Table

Property	Type	Description	Example
text	String	The text to display.	text: "Hello, World!"
text-align	String	Aligns the text within the widget.	text-align: center
text-offset	Point	Sets the offset of the text.	text-offset: 10 5
text-wrap	Boolean	Enables or disables text wrapping.	text-wrap: true
text-auto-resize	Boolean	Resizes the widget to fit the text.	text-auto-resize: true
text-horizontal-auto-resize	Boolean	Resizes the widget's width to fit the text.	text-horizontal-auto-resize: true
text-vertical-auto-resize	Boolean	Resizes the widget's height to fit the text.	text-vertical-auto-resize: true
text-only-upper-case	Boolean	Converts all text to uppercase.	text-only-upper-case: true
font	String	Specifies the font to use.	font: "verdana-11px"
font-scale	Float	Scales the font size.	font-scale: 1.5

---

This documentation provides a comprehensive guide to using UIWidgetText in OTUI. It covers all the properties available for customizing text appearance and behavior.