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");
=== 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