FURWARE text/Reference

Template:Needs Translation/es Template:Needs Translation/el Template:Needs Translation/fr Template:Needs Translation/he Template:Needs Translation/it Template:Needs Translation/ja Template:Needs Translation/ko Template:Needs Translation/nl Template:Needs Translation/hu Template:Needs Translation/no Template:Needs Translation/da Template:Needs Translation/sv Template:Needs Translation/tr Template:Needs Translation/pl Template:Needs Translation/pt Template:Needs Translation/ru Template:Needs Translation/th Template:Needs Translation/uk Template:Needs Translation/zh-Hans Template:Needs Translation/zh-Hant

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