mirror of
https://github.com/Insality/druid
synced 2025-06-27 18:37:45 +02:00
142 lines
4.5 KiB
Markdown
142 lines
4.5 KiB
Markdown
# Druid Text Component
|
|
|
|
## Description
|
|
|
|
Text component is a basic component that provides various adjustment modes for text nodes. It allows text to be scaled down to fit within the size of the text node, trimmed, scrolled, or a combination of these adjustments. The component makes it easy to handle text display in different scenarios.
|
|
|
|
## Features
|
|
|
|
- Automatic text size adjustment
|
|
- Multiple text adjustment modes (downscale, trim, scroll, etc.)
|
|
- Text pivot control
|
|
- Text color and alpha management
|
|
- Text size and scale control
|
|
- Text metrics calculation
|
|
- Event-based architecture for text changes
|
|
|
|
## Basic Usage
|
|
|
|
```lua
|
|
local text = self.druid:new_text(node, [initial_value], [adjust_type])
|
|
```
|
|
|
|
### Parameters
|
|
|
|
- **node**: The node or node_id of the text node
|
|
- **initial_value**: (optional) Initial text value. Default is the text from the GUI node
|
|
- **adjust_type**: (optional) Adjustment type for text. Default is "DOWNSCALE". See adjustment types below
|
|
|
|
### Example
|
|
|
|
```lua
|
|
-- Simple text component
|
|
local text = self.druid:new_text("text_node")
|
|
|
|
-- Text with initial value
|
|
local text = self.druid:new_text("text_node", "Hello, World!")
|
|
|
|
-- Text with specific adjustment type
|
|
local text = self.druid:new_text("text_node", "Hello, World!", const.TEXT_ADJUST.TRIM)
|
|
```
|
|
|
|
## Text Adjustment Types
|
|
|
|
The Text component supports several adjustment types to handle different text display scenarios:
|
|
|
|
- **DOWNSCALE**: Scales down the text to fit within the text node's size
|
|
- **NO_ADJUST**: No adjustment, text displays as is
|
|
- **TRIM**: Trims the text with an ellipsis (...) if it doesn't fit
|
|
- **TRIM_LEFT**: Trims the text from the left with an ellipsis if it doesn't fit
|
|
- **DOWNSCALE_LIMITED**: Scales down the text but not below a minimum scale
|
|
- **SCROLL**: Shifts the text anchor when it doesn't fit
|
|
- **SCALE_THEN_SCROLL**: First scales down the text, then scrolls if needed
|
|
- **SCALE_THEN_TRIM**: First scales down the text, then trims if needed
|
|
- **SCALE_THEN_TRIM_LEFT**: First scales down the text, then trims from the left if needed
|
|
|
|
### Example
|
|
|
|
```lua
|
|
-- Import constants
|
|
local const = require("druid.const")
|
|
|
|
-- Create text with TRIM adjustment
|
|
local text = self.druid:new_text("text_node", "Long text that might not fit", const.TEXT_ADJUST.TRIM)
|
|
|
|
-- Change adjustment type later
|
|
text:set_text_adjust(const.TEXT_ADJUST.SCALE_THEN_TRIM)
|
|
```
|
|
|
|
## Events
|
|
|
|
The Text component provides several events you can subscribe to:
|
|
|
|
- **on_set_text**: Triggered when text is set or changed
|
|
- **on_update_text_scale**: Triggered when text scale is updated
|
|
- **on_set_pivot**: Triggered when text pivot is changed
|
|
|
|
### Example
|
|
|
|
```lua
|
|
-- Subscribe to text change event
|
|
text.on_set_text:subscribe(function(self, text_value)
|
|
print("Text changed to: " .. text_value)
|
|
end)
|
|
|
|
-- Subscribe to scale update event
|
|
text.on_update_text_scale:subscribe(function(self, scale, metrics)
|
|
print("Text scale updated to: " .. scale.x)
|
|
end)
|
|
```
|
|
|
|
## Methods
|
|
|
|
```lua
|
|
-- Set text content
|
|
text:set_text("New text content")
|
|
|
|
-- Get current text content
|
|
local current_text = text:get_text()
|
|
|
|
-- Set text area size
|
|
text:set_size(vmath.vector3(200, 100, 0))
|
|
|
|
-- Set text color
|
|
text:set_color(vmath.vector4(1, 0, 0, 1)) -- Red color
|
|
|
|
-- Set text alpha
|
|
text:set_alpha(0.5) -- 50% opacity
|
|
|
|
-- Set text scale
|
|
text:set_scale(vmath.vector3(1.5, 1.5, 1)) -- 150% scale
|
|
|
|
-- Set text pivot
|
|
text:set_pivot(gui.PIVOT_CENTER)
|
|
|
|
-- Check if text is multiline
|
|
local is_multiline = text:is_multiline()
|
|
|
|
-- Set text adjustment type
|
|
text:set_text_adjust(const.TEXT_ADJUST.TRIM)
|
|
|
|
-- Set minimal scale for limited adjustment types
|
|
text:set_minimal_scale(0.5) -- 50% minimum scale
|
|
|
|
-- Get current text adjustment type
|
|
local adjust_type = text:get_text_adjust()
|
|
|
|
-- Get text size (width and height)
|
|
local width, height = text:get_text_size()
|
|
|
|
-- Get text index by width (useful for cursor positioning)
|
|
local char_index = text:get_text_index_by_width(100)
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Text component by default has auto-adjust text sizing. Text will never be bigger than the text node size, which you can set up in the GUI scene.
|
|
- Auto-adjustment can be disabled by setting the adjustment type to `NO_ADJUST`.
|
|
- Text pivot can be changed with `text:set_pivot()`, and the text will maintain its position inside the text size box.
|
|
- For multiline text, the component will try to fit the text within both width and height constraints.
|
|
- The trim postfix (default: "...") can be customized in the style settings.
|
|
- When using `DOWNSCALE_LIMITED` or `SCALE_THEN_SCROLL`, you can set a minimal scale to prevent text from becoming too small.
|