Difference between revisions of "Text Boxes"

From ADRIFT 5 Manual Wiki
Jump to: navigation, search
(Special Characters)
(bgcolour)
 
(2 intermediate revisions by the same user not shown)
Line 291: Line 291:
 
( ) </td><td>Parentheses </td><td>Used to delimit the parameter lists of math and string functions that can be used to calculate parameters for the % function.
 
( ) </td><td>Parentheses </td><td>Used to delimit the parameter lists of math and string functions that can be used to calculate parameters for the % function.
 
</td></tr><tr><td>
 
</td></tr><tr><td>
[ ] </td><td>Square brackets </td><td>When used after a function name these are used to delimit the parameters for the function, [ ] is also used to indicate the index value when used with an array variable. </td></tr><tr><td>
+
[ ] </td><td>Square brackets </td><td>When used after a function name these are used to delimit the parameters for the function, [ ] is also used to indicate the index value when used with an array variable.<br>
 +
If something like "%CharacterName% [am/are/is] not hungry right now." is used in text, then ADRIFT will select one of the three options separated by slashes according to the [[Creating_Libraries_and_Modules#Player_perspective|Player Perspective]] selection on the [[Options]] page.</td></tr><tr><td>
 
, </td><td>comma </td><td>Separates parameters in a parameter list.
 
, </td><td>comma </td><td>Separates parameters in a parameter list.
 
</td></tr><tr><td>
 
</td></tr><tr><td>
Line 353: Line 354:
 
If you need to line up colombs vertically then use a monospaced font such as Lucida Console.<br>
 
If you need to line up colombs vertically then use a monospaced font such as Lucida Console.<br>
 
&lt;/font&gt; Reverts back to the previous font size, color and face.
 
&lt;/font&gt; Reverts back to the previous font size, color and face.
 +
</td></tr><tr><td>
 +
&lt;bgcolour="red"&gt;<br>&lt;bgcolour="#FF8800"&gt;
 +
</td><td>
 +
Sets the background color of the page.<br>
 +
The colour codes are the same as for the font colors above.
 
</td></tr><tr><td>
 
</td></tr><tr><td>
 
&lt;wait N&gt; </td><td>(Where N is a number) Wait for N seconds before continuing. ie. &lt;wait 5&gt; pauses the text output to the screen for 5 seconds.
 
&lt;wait N&gt; </td><td>(Where N is a number) Wait for N seconds before continuing. ie. &lt;wait 5&gt; pauses the text output to the screen for 5 seconds.

Latest revision as of 08:33, 29 May 2015

A text box allows you to enter multiple lines of text that ADRIFT will print to the runner screen at the appropriate time during the game.

Text boxes within ADRIFT are completely flexible as to how and what they display. They are designed to look simple at first glance, with the user typing in basic descriptions. They all support Syntax Highlighting to show functions, references, keys, comments and variables.

It can contain pictures to display with the text, and sounds to play when it is displayed.

Alternate Descriptions can be used to append extra text, or completely change the displayed message, based on Restrictions.

Example text boxes

Text boxes are used for:

The long description of a location and the description of objects and characters:

ImgTip.pngThe short location description can be expanded into a text box by clicking the IconDropDown.jpg

Location.jpg

Text properties:

PropertyCharacterEnterExit.jpg

Restriction text:

RestrictionContainerCanHold.jpg

Task completion messages, sub events, text overrides and user functions.

Automatic Capitalisation

ADRIFT will automatically capitalise the first word of every sentance. Specifically, it capitalises the first word after each full stop.

If your text box contains:

i am a flower. my petals are yellow.

ADRIFT will print:

I am a flower. My petals are yellow.

Normally of course you would do this yourself, but ADRIFT allows sentances to be assembled from separate pieces of text using functions and variables. For example, you may want to print the sentance:

%Colour% light filters in through the window.

But the %Color% variable may contain the word "orange" which is not capitalised, and which you may be using elsewhere where it should not be capitalised. ADRIFT will automatically fix the capitalisation to give you:

Orange light filters in through the window.

If you don't want this capitalisation to occur, then insert less-than, greater-than characters in front of the letter that should remain lower-case:

i.e. <>this is not capitalised.
i.e. this is capitalised.

Which is printed as:

i.e. this is not capitalised.
i.e. This is capitalised.

Tab pages

Down the right-hand side of the text box there may be several tabs named Source, Preview, Graphics and Audio (Abreviated to Src, Pvw, Gfx and Aud in the smaller text boxes on property sheets, or if the window containing the text box is made very small).

Each of these switches the text box to a different page.

The "Source" page is the normal page where you type the text you want to be displayed.

The other 3 tabs are only shown if they are selected in the ADRIFT settings page: GeneralSettings.jpg

The three selections can be seen in the "Text Boxes" section at the lower right of this page.

Preview

This section has still to be completed. I am hoping that it will provide a preview of the text as it would be displayed in Runner. It may also be possible to apply What-You-See-Is-What-You-Get formatting directly to the text.

Graphics

You can insert graphics into a piece of text by selecting the Graphics tab on the right hand side. This provides a handy preview and URL. You can enter a filename, or a URL from the Internet here. Internet images will be downloaded on the fly, which can minimize the size of your adventure. By default, this will display the graphic at the start of the section of text.

It is also possible to insert multiple images in any piece of text by using <img> tags. The format is <img src="filename or url">. Using the <img> tags also allows you to customise exactly where in the text it will appear. This is useful if, for example, you have <waitkey> or <wait X> tags in your text. Also, you may want different images to appear for different alternate descriptions

Audio

As with Graphics, you can insert an audio clip by selecting the Audio tab on the right hand side. This provides three main buttons, a channel selector, and a loop checkbox.

To play a sound, click the Play button. This will bring up the file dialog box, where you can select a WAV, MP3 or MID file. There are plans to allow OGG files in a later release. Once selected, you can preview the sound by right-clicking on the Play button. You can have the audio loop indefinitely by selecting the Loop checkbox.

ADRIFT has 8 sound channels. This means you can have background music on a particular channel, and overlay different audio clips on other channels. By default, everything will be on channel 1.

To pause a sound file (for example, you might want to pause a piece of music when a particular piece of text is displayed), select the Pause button. This will pause any piece of audio on the selected channel. When you next select to play sound on this channel, assuming it is the same audio clip then it will resume where it left off.

To stop a sound file, select the Stop button. If this piece of music is played again, it will start from the beginning.

As with the Play button, you can right-click on the pause/stop buttons to stop a piece of audio from being previewed.

As with graphics, you can control exactly when the sound will be played using tags. This is useful in case you want to play multiple sound effects in the same text box, or wish to play the sound after a wait command. The syntax is:

<audio [play src="filename or url"|pause|stop] {channel=X} {loop=[Y/N]}>

So for example: <audio play src="myfile.mp3" channel=2 loop=Y> or <audio pause channel=2>

Embedded functions

A text box can just contain simple text, but to add variety to the text being output you can insert variables, functions, references and expressions anywhere in the text.

  • Variables are delimited by % symbols, so to display the contents of the "Score" variable you must insert %Score% into the text.
  • Item functions are used to display the values of the properties of an item (character, object or location). If you enter the key of an item followed by a full-stop, ADRIFT will display a list of all of the properties of that item from which you can select the one that you want. NOTE: The object key must use exactly the same case as it is displayed in the folder and the top of the item, usually mostly lower-case but with each word starting with a capital letter.
  • The % delimited General Functions can be used to get the keys of the current player character (%Player%), the only other character in the same room (%AloneWithChar%) and the NPC that the player is talking to (%ConvCharacter%). There are also useful functions to change the case of some text, capitalise the first character, or display a random number.
  • References are only available during the execution of a task. If a task uses an object reference (%object% is used in the general tasks command template) then you can use %object% to provide the key for the functions above.
  • Expressions are for more complex equations than can be done with nested functions. They can be used to calculate a mathematical equation, perform text manipulation, or choose between different text to display using an IF statement. An expression inserted into text must be between the symbols <# and #>

When the contents of the text box is displayed on the screen, ADRIFT makes several passes through the text to substitute variables and references with their contents, and the functions and expressions with the result of evaluating them.

This means that if a text variable contains an expression, ADRIFT will replace the variable with its contents in the first pass, then in the second pass it will recognise the inserted expression and execute it.

Substitution occurs in the following order:

  1. Functions (recursively, including variable substitution)
  2. Item functions (recursively)
  3. Expressions (also includes function evaluation)

Drag and Drop

As well as being able to drag and drop pieces of text into the text boxes, you can also drag items from the main ADRIFT window into the boxes too. This provides a quick way of creating functions. So for example, if you drag a character from a list into a text window it will pop up a menu asking which property of the character you wish to display. By selecting one of these entries, the corresponding function for your selection will be inserted into the textbox at the cursor location.

  1. Open the edit form you wish to place a function on.
    • If the edit window does NOT have a button on the windows taskbar, then open the Settings form and tick the "Show all open windows in taskbar" option.
  2. Move the mouse to the folder window containing the item you wish to use in the function.
  3. Position the mouse over the item and hold down the left button and "Drag" the item down to the button on the windows taskbar that represents the edit window.
  4. Wait a moment until the edit window appears again (keeping the mouse button held down).
  5. Continue dragging the item to the edit window.
  6. Drag the item to the position in the text that you want to insert the function.
  7. Release the mouse button.


If we drag a character to a text box, seven choices will be shown in a menu:

DragCharacter.jpg

If the key of this character is "Susan", then this is what will be inserted into the text:

Menu Selection Inserted Text
Character Name Susan.Name
Character Key Susan
Character description Susan.Description
List objects held by Character Susan.Held.List
List objects worn by Character Susan.Worn.List
Location of Character Susan.CharacterLocation
Parent of Character Susan.Parent

If we drag an object to a text box, seven choices will be shown in the menu:

DragObject.jpg

If the key of this object is "Vase", then this is what will be inserted into the text:

Menu Selection Inserted Text
Object name Vase.Name
Object Key Vase
Object Description Vase.Description
List objects on Vase.Children(On)
List objects inside Vase.Contents
List objects on and inside Vase.Children
Parent of object Vase.Parent


If we drag a location to a text box, five choices will be shown in the menu:

DragLocation.jpg

Menu Selection Inserted Text
Location name Location1.Name
Location Key Location1
Display Location Location1.LongLocationDescription
Exits from Location Location1.Exits.List
Objects at Location Location1.Objects.List(Indefinite)


If we drag an event to a text box, three choices will be shown in the menu:

DragEvent.jpg

Menu Selection Inserted Text
Event Length Event1.Length
Event Position Event1.Position
Event Key Event1

If we drag a Task to a text box, two choices will be shown in the menu:

DragTask.png

Menu Selection Inserted Text
Task Key Task1
Task Completed %TaskCompleted[Task1]%

If we drag a Property to a text box, two choices will be shown in the menu:

DragProperty.png

Menu Selection Inserted Text
Property Value <Item Key>.Property1
Property Key Property1

If we drag a Variable to a text box, two choices will be shown in the menu:

DragVariable.png

Menu Selection Inserted Text
Variable Value %VariableName%
Variable Key Variable1

Special Characters

The following symbol characters are used for special purposes, so cant be used freely in text.

< Less than This is used for HTML markup tags and to insert comments in the text. The tag finishes at the next > character.

To include a < character in text, use the code &LT; and for > use &GT;
Comments are placed between less-than/exclamation/minus/minus and minus/minus/greater-than, as shown below:

<!-- This is a comment -->

<# and #> mark the beginning and end of embedded expressions. This allows you to add logic within text windows. For example:

You have <# IF(Player.Held.Count > 1, "more than one", "zero or one") #> items.
% Percent Two of these are used as delimiters around variable names, functions and references that are embedded in the text and evaluated immediately prior to the text being output. Note that nested % symbols may be placed inside the brackets of a function. The equation finishes and normal text resumes at the next % symbol that is not enclosed by brackets.


The following special symbols are used inside embedded general functions delimited by % symbols:

( ) Parentheses Used to delimit the parameter lists of math and string functions that can be used to calculate parameters for the % function.
[ ] Square brackets When used after a function name these are used to delimit the parameters for the function, [ ] is also used to indicate the index value when used with an array variable.
If something like "%CharacterName% [am/are/is] not hungry right now." is used in text, then ADRIFT will select one of the three options separated by slashes according to the Player Perspective selection on the Options page.
, comma Separates parameters in a parameter list.
< > Less than, greater thanMust be used in pairs inside of other brackets as Adrift does not currently nest different types of delimiter correctly.
To include a < character in text, use the code &LT; and for > use &GT;

Printing to Multiple Windows

It is possible to output some of the text in a text box to a different window.

The syntax is <window Label> where Label is the title of the window to output to. E.g:

<window Inventory><cls>You are holding:
Player.Held.List(Indefinite,Rows)</window>

HTML markup tags

Many standard HTML markup tags, and some unique Adrift tags, can be inserted into the text to control the formatting of the output.

<br> (break) Start a new line.
<img src="filename or url"> Insert an image into the text (see also the graphics section above).
<cls> Clear the screen.
<b>boldface</b> Write in boldface.
<u>underline</u> underline the text.
<i>italics</i> Write in italics.

<centre>Centralise text</centre>

or <center>Centralise text</center>
Centralise text
<right>right justify text</right> right justify text
&LT;Displays the < character
&GT;Displays the > character
&perc;Displays the % character
&quot;Displays the " character

<font colour="#RRGGBB">text</font>
(Note: "colour" can also be spelt "color")
or
<font size=N>text</font>
or
<font face="fontname">text</font>
or in any combination, eg:
<font colour="#RRGGBB" size=N face="fontname">text</font>

Allows the text color, font or point size to be changed.

The color is specified as three 2-digit hexadecimal numbers in the order red-green-blue.
<font color="#000000"> is black
<font colour="#FF0000"> is bright red
<font color="#00FF00"> is bright green
<font colour="#0000FF"> is bright blue
<font color="#C0C000"> is GOLD
The size N can either be specified as an absolute font size, or relative to the current font size.
<font size=10>text</font> creates text slightly smaller than the default.
<font size=+10>text</font> creates text 10 points larger than the default.
<font face="times new roman">text</font> changes the current font to "times new roman".
If you need to line up colombs vertically then use a monospaced font such as Lucida Console.
</font> Reverts back to the previous font size, color and face.

<bgcolour="red">
<bgcolour="#FF8800">

Sets the background color of the page.
The colour codes are the same as for the font colors above.

<wait N> (Where N is a number) Wait for N seconds before continuing. ie. <wait 5> pauses the text output to the screen for 5 seconds.
Press any key<waitkey> Pauses the text output until player presses a key. Note that you need to provide your own "Press a key to continue" message BEFORE the <waitkey> tag.


<<< The Standard LibraryMain PageAlternate Descriptions >>>