FURWARE text/Reference
Reference manual
This chapter is meant to be a quick overview of pretty much everything necessary to use FURWARE text, especially which names and parameters go where. It is not meant to replace the tutorial in any way.
Commands
fw_data & fw_conf
Per-box settings for text (fw_data) and style (fw_conf)
llMessageLinked(LINK_SET, 0, "Some new text", "fw_data : BoxSpec : BoxSpec : BoxSpec : ...");
llMessageLinked(LINK_SET, 0, "c=red; a=center", "fw_conf : BoxSpec : BoxSpec : BoxSpec : ...");
Each "BoxSpec" can have different forms to select different boxes. In the following table, let "BoxOne" and "BoxTwo" be two valid box names in the same display set:
BoxSpec | Meaning |
---|---|
(empty) | All boxes in all sets. |
BoxOne | Only the box "BoxOne". |
BoxOne ; BoxTwo | All Boxes between* (and including) "BoxOne" and "BoxTwo". |
BoxOne ; | "BoxOne" and all following* boxes in the same display set. |
; BoxTwo | "BoxTwo" and all preceding* boxes in the same display set. |
(*) Depending on the order in which the boxes were added.
fw_defaultconf
Sets global style preferences
llMessageLinked(LINK_SET, 0, "c=red; a=center", "fw_defaultconf");
llMessageLinked(LINK_SET, 0, "c=red; a=center", "fw_defaultconf : root");
llMessageLinked(LINK_SET, 0, "c=red; a=center", "fw_defaultconf : nonroot");
The three variants set the global style preferences for all boxes, all root-boxes and all non-root boxes.
fw_var
Store some string data in a "variable" name. Currently only used for style templates.
llMessageLinked(LINK_SET, 0, "Some string", "fw_var : varName");
Sets the contents of variable "varName" to "Some string". You can delete variables by passing the empty string as data.
fw_addbox
Adds a new virtual text box. There can be at most 16 boxes per set (including the root box).
llMessageLinked(LINK_SET, 0, "Some initial text", "fw_addbox : boxName : parentName : dx, dy, sx, sy : stylePrefs");
Please see the tutorial for details.
fw_delbox
Deletes one or more text boxes.
llMessageLinked(LINK_SET, 0, "", "fw_delbox : boxOne : boxTwo : ...");
Deletes the boxes named "boxOne", "boxTwo", etc.
fw_touchquery
Performs a query which box has been touched where.
llMessageLinked(LINK_SET, 0, "userData", "fw_touchquery : linkNumber : faceNumber");
The reply has the form (pseudo code):
link_message(..., ..., "boxName:dx:dy:rootName:x:y:userData", "fw_touchreply") {
...
}
Please see the tutorial for details.
fw_notify
Enable or disable link message notifications when the script has done rendering. Off by default.
llMessageLinked(LINK_SET, 0, "on", "fw_notify");
llMessageLinked(LINK_SET, 0, "off", "fw_notify");
When notifications are enabled, the text script will send a link message with "id" set to "fw_done" to the whole linkset to let you know when all pending rendering actions have been completed.
fw_memory
Tells the owner how much memory is available.
llMessageLinked(LINK_SET, 0, "", "fw_memory");
fw_reset
Performs a full reset on the text script.
llMessageLinked(LINK_SET, 0, "", "fw_reset");
Tip: When the reset has completed, the script sends a link message with "id" set to "fw_ready" to all prims in the linkset. This tells you when the script is ready to take further commands. |
Important: Only reset the text script if necessary. Initialization is a quite expensive operation and the script will not be available to take commands for a few seconds. |
Style settings
Text styles and format settings are specified using special strings. They are used for global and per-box settings ("fw_conf") as well as for specifying styles directly within the text (inline styles).
A single setting is given as a key=value pair, for example c=red.
Multiple settings are separated by ";", for example c=red; a=center; w=none.
In the following table: Italic = Default
Setting | Key | Values | Description |
---|---|---|---|
Font color | c | R,G,B | Font color as red, green, blue (each in range 0.0-1.0) |
R,G,B,A | Font color as red, green, blue, alpha (each in range 0.0-1.0) | ||
rand | Random color (with alpha = 1) | ||
(predefined) | Predefined color, see table below | ||
Alignment | a | left | Alignment left |
center | Alignment centered | ||
right | Alignment right | ||
Wrapping | w | word | Wrap after words, if possible |
char | Wrap at any position | ||
none | No wrapping; cuts overlong lines | ||
Trimming | t | on | Trims whitespace from beginning and end of lines |
off | Keeps whitespace (except with wrap=word) | ||
Font | f | (UUID/name) | Sets the font texture to UUID or name |
Borders | border | {trblTRBL12} | Specifies the style of box borders |
Style template | style | (Style name) | Uses a style defined using fw_var |
Inline styles | tags | on | Enables usage of inline styles |
off | Disables usage of inline styles | ||
Force refresh | force | on | Enables forced refresh of all faces (disables optimizations!) |
off | Disables forced refresh of all faces (enables optimizations) |
Predefined colors
You may use the following names in place of color vectors in styles.
Fonts
You can use the fonts listed here with the "f=..." style setting either by using their UUID or by putting the corresponding texture item (included in the FURWARE text package) into your object and then use the texture's name.
Version history
2.0.1
- Fixed an issue where characters that are not part of the font texture specification would cause unexpected behavior.
- A box's set pointer is now stored bit-packed together with the rest of its status. This decreases the length of a stride in boxDataList by 1.
- Removed message about free memory on script startup.
- Removed getNumberOfPrims()-function.
- Moved the check if we have any sets at all to the beginning of the link_message()-handler.
2.0
- Made the script open source under the MIT license.
2.0-Beta1
- The functionality of "fw_data" and "fw_conf" has been reworked to (hopefully) make it more intuitive.
- The commands "fw_data", "fw_conf", and "fw_delbox" are now able to modify multiple boxes at once.
- Added "fw_defaultconf" command. Currently used to configure global style settings.
- Touch replies now also contain the name of the root box and the absolute coordinates.
- Added "force" style attribute to force refresh of all faces (useful for fonts where whitespace is not completely transparent).
- Optimized handling when multiple "similar" commands (e.g. "fw_delbox") come in quickly.
2.0-Beta0
- Mesh prims with up to 8 characters per prim, each occupying 0.5 prims
- Virtual text boxes for aligning text arbitrarily
- Style templates for saving format settings
1.1
- The developer version now allows distribution of the script as +copy/-trans or -copy/+trans
1.0.1
- Improved speed
1.0
- First released version