richtextdisplay(
richtextdisplay(
RICHTEXT
)

The richtextdisplay( function works with Text Display objects to display text with multiple styles, fonts, colors and alignments.

Parameters

This function has one parameter:

richtext – The text to display, with embedded tags to modify the style and appearance of the text.

Description

This function works with Text Display objects to display text with multiple styles, fonts, colors and alignments. You can control the format of the displayed text using tags that are similar in concept to those used for formatting in HTML.

Keep in mind that the richtextdisplay( function should only be used with Text Display objects, and it must be the enclosing function in that object’s formula. In other words, there should not be anything in the formula before or after the richtextdisplay( function.

    richtextdisplay(" ... ") ☞ Ok
    richtextdisplay(" ... ")+anything ☞ Wrong!
    anything+richtextdisplay(" ... ") ☞ Wrong!

(Advanced note: The richtextdisplay( function actually generates a special binary value that is intercepted by the Text Display object. The binary value contains information the Text Display object uses to select the styles and colors, as well as the text itself. For the super nerdy, this binary value is an encoded Objective-C NSAttributedString object. The tags described below give you complete control over the formatting of this object.)

#### RTML vs. HTML

The richtextdisplay( function uses a language we call RTML, or Rich Text Markup Language. If you’re familiar with HTML you’ll find many aspects of RTML familiar, but there are significant differences.

Like HTML, RTML uses embedded tags to modify the appearance of the displayed text. By default, each tag starts with `<` and ends with `>`. However, RTML gives you the option to change these characters to make it easier to include the < and > characters in the body text.

Some RTML tags have one or more parameters. The parameters are separated from the tag name and each other with the `:` character. This example shows a tag with two parameters, alpha and beta:

    <tag:alpha:beta>

Unlike HTML, RTML doesn’t do any special whitespace processing. Whitespace characters (space, tab, carriage return, line feed) are passed thru “as-is”. To start a new line, use a carriage return character (there is no `<br>` or `<p>` tag). If your text includes two or more spaces in a row, they will be displayed in the final output rather than being coalesced into a single blank.

There are no character entities in RTML (`&gt;`, `&lt;`, etc.). There is a special `<char>` tag that allows you to insert any unicode character, and as mentioned above, you can also change the tag characters to make it easier to include < and > characters.

Unlike HTML, the effect of most tags is not reversible with a matching `/` tag (for example as HTML does with the `<font>...</font>` tags). Instead, the appearance must be changed explicitly each time with a new tag. However, you can revert to a previous appearance by using a `<style>...</style>` tag pair, and you can also set up named styles. Both of these options are discussed later on this page.

#### Reverting to a Previous Style

In general, RTML tags affect the appearance of the text from that point onwards. However, if you want to go back to a previous style you can use the `<style>` and `</style>` tags. The `</style>` tag reverts the text appearance back to what it was at the time of the last `<style>` tag. Here is an example.

    richtextdisplay("This is black, <style><color:0000FF>this is blue,
        <color:FF0000>this is red, </style> and this is black again.")

As you can see, the `</style>` tag undos all style changes made since the last `<style>` tag. Note: You can nest multiple `<style>..</style>` tag pairs inside each other.

#### Named Styles

Using the `<definestyle:name>` tag you can save all current appearance options, then call them up again later with a `<style:name>` tag. This example defines three styles – Title, Body and Code, then uses two of these styles.

    richtextdisplay(
        "<font:Futura:24><color:0000CC><align=center><leftmargin:0><definestyle:Title>"+
        "<font:Gill Sans:13><color:000000><align=justify><leftmargin:0><definestyle:Body>"+
        "<font:Courier:10><color:009999><align=left><leftmargin:36><definestyle:Code>"+
        "<style:Title>July 2014 Results"+cr()+cr()+
        "<style:Body>The results are in, and ..."+cr()+
        "Conclusions we can draw from these values are that ...")

Tip: If you want to use the same styles in multiple objects, put the definition for these styles into a variable, like this (this code could be in an .Initialization procedure, or you could use a permanent variable):

     fileglobal myStyles
     myStyles=
        "<font:Futura:24><color:0000CC><align=center><leftmargin:0><definestyle:Title>"+
        "<font:Gill Sans:13><color:000000><align=justify><leftmargin:0><definestyle:Body>"+
        "<font:Courier:10><color:009999><align=left><leftmargin:36><definestyle:Code>"

Then you can use these over and over again like this:

    richtextdisplay(myStyles+"text to be displayed ...")

Note: Panorama automatically creates a style name `object` for you. This style contains all of the default appearance options for the Text Display object being displayed – the font, color, etc. as specified by the object inspector palette.

#### Embedding Data in Rich Text

The examples on this page all show fixed text, but what if you want to include database data in the rich text? That’s not a problem, simply include the fields or variables in the formula. This example creates a mailing label, with the name displayed in bold text.

    richtextdisplay("<b>"+First+" "+Last+"</b>"+cr()+Address+cr()+City+" "+State+" <i>"+Zip+"</i>")

However, what if the field or variable being displayed contains a `<` character? To prevent this character from confusing the richtextdisplay( function, enclose the field or variable with the richtextdata( function. This modified example will work correctly even if the Address field contains a `<` character.

    richtextdisplay("<b>"+First+" "+Last+"</b>"+cr()+
        richtextdata(Address)+cr()+City+" "+State+" <i>"+Zip+"</i>")

Note: An alternate method is to change the tag character, as described at the bottom of this page.

#### Bold and Italic

Use the `<b>` and `<i>` tags to generate bold or italic text, just like HTML.

    richtextdisplay("Text can be <b>bold</b> or "+
        "<i>italic</i> or <b><i>both</i></b>.")

#### Underlines

Use the `<ul>` tag for underlined text. Underlines can be double or thick, but they are always ended with `</ul>`.

    richtextdisplay("Text can be <ul>underlined</ul>, "+
        "<doubleul>double underlined</ul> or "+
        "<thickul>thick undelined</ul>.")

#### Color

The `<color:rrggbb>` tag has one parameter – the color specified using the standard HTML format for colors (2 hex digits each for red, green and blue). If the color parameter is missing it is set to black.

    richtextdisplay("Text can be <color:FF0000>red<color>, <color:00FF00>green<color>, "+
        "<color:0000FF>blue<color> or any other color.")

The background color is usually set to transparent, but you can change it with the `<bgcolor:rrggbb>` tag. If the color parameter is missing it is set to transparent.

    richtextdisplay("Here is some <bgcolor:FFFF00>yellow highlighting<bgcolor>.")

#### Font and Text Size

Use the `<font:name:height>` tag to change the font, and optionally the size, of the displayed text. (The size is specified in points.)

    richtextdisplay("Text can be <font:Savoye LET:64>fancy or <font:Courier:15>plain.")

If you leave the size off it will remain the same.

    richtextdisplay("Different <font:Monaco>fonts <font:Arial>in <font:Times>the same size.")

If you want to change the size but leave the font the same, use the `<size:height>` tag.

    richtextdisplay("Text can be <size:96>big<size:9> or small.")

#### Displaying Unicode Characters

To display a unicode character by value, use the `<char:value>` tag. This example displays the `<` character.

    richtextdisplay("Here is one way to insert the <char:60> character.")

If you prefix the value with `x` or `0x`, the number will be interpreted as a hexadecimal value. This example also displays the `<` character.

    richtextdisplay("Here is another way to insert the <char:x3C> character.")

You can also optionally specify the font, size and/or color for the displayed character. This example displays a big green check mark.

    richtextdisplay("<char:0xf00c:FontAwesome:36:66FF66>")

Unlike the `<font>` tag, the effect of any font or color settings in the `<char>` tag is temporary. Text after the `<char>` tag will resume with the font, size and color that were in use before the tag.

You can omit any of the optional parameters. For example, this example will display a red `<` character, using the current font and text size.

    richtextdisplay("Here is another way to insert the <char:x3C::FF0000> character.")

Note: Font Awesome (http://fortawesome.github.io/Font-Awesome/) is an open source icon font that includes over 400 icons. Font Awesome is included with Panorama, so you can easily use any of these icons in your designs. See the cheat sheet on the Font Awesome web site for a list of all available icons in this font.

#### Displaying Images

Use the `<image:name>` tag to display an image. The image will be displayed inline in the text (on the same line as other text, unless you’ve included carriage returns before and after the image. If the image is in the same folder as the database, you can simply include the name of the file containing the image (be sure to include the extension – .jpg, .png, etc.)

    richtextdisplay("Here is a flower: <image:flower.jpg>")

If the image is in a subfolder relative to the database, you can specify a relative path. This example assumes that there is a folder named flowers in the same folder as the database.

    richtextdisplay("Here is a flower: <image:flowers/rose.jpg>")

If the image is anywhere else on the computer you must specify a complete path, like this:

    richtextdisplay("We had fun here: <~/Pictures/Vacation/Ferry Building 87.jpg>")

If the image is inside the Panorama application, or included in the system, you can prefix the image name with `##` and Panorama will automatically locate it.

    richtextdisplay("##Pancil.png")

#### Tab Stops

If the text being displayed contains tab characters you can use the `<tab:stops>` tag to control where each tab is positioned. In its simplest form this tag simply contains a comma separated list of tab positions. Each position is specified in points from the left edge of the text. This example sets three tab stops, at 1 inch, 2 inches, and 4 inches (72 points to an inch).

    richtextdisplay("<tabs:72,144,288>+ ... text that contains tabs ...")

In addition to normal left justified tabs, you can also set up centered, right justified, or decimal justified tabs by appending the letter `C`, `R`, or `D` after the location. Decimal justified tabs are designed for numbers, and will line up the decimal points on the tab location. In this example the Option column will be centered and the Price column will be aligned on the decimal points.

    richtextdisplay("<tabs:100c,300d>"+
        "<ul>Option</ul>"+tab()+"<ul>Price</ul>"+cr()+
        "Deluxe"+tab()+"$199.99"+cr()+
        "Ultimate"+tab()+$399.99")

Of course normally the table wouldn’t be hard coded like this, but would be generated by arraybuild( or a similar function.

#### Alignment and Wrapping Options

Text is normally displayed left justified. For other options, use the `<align:option>` tag. The available options are `LEFT`, `RIGHT`, `CENTER` and `JUSTIFIED` (actually only the first letter is required). The `JUSTIFIED` option will spread each line within a paragraph so that the text is both left and right justified (except for the last line in each paragraph).

    richtextdisplay("<align:center>Main Title"+cr()+cr()+
        "<align:justified>Body of main paragraph ... ")

Use the `<hyphenate:factor>` tag if you would like automatic hypenation to occur. The factor is a number from 0 to 1, 0 is no hyphenation (the default), 1 is maximum aggression in hyphenation. Fractional values are allowed.

When a line of text is wider than the Text Display object, Panorama normally wraps the text into a paragraph at word boundaries. The `<linebreak:mode>` tag allows ths behavior to be modified. The possible modes are:

wordwrapping – This is the normal mode. (It can be abbreviated as word, or simply by omitting the parameter.)

charwrapping – In this mode, the text will be wrapped at character boundaries instead of word boundaries. In other words, words may be split in the middle. (This mode can be abbreviated as char.)

clipping – In this and the following modes, the text does not wrap at all. If the text is too wide to fit, it is simply truncated. (This mode can be abbreviated as clip.)

truncatingtail – In this mode, if the text is too wide to fit, it is truncated on the right, but an ellipsis (…) will be displayed to indicate that there is additional text that is not being displayed. (This mode can be abbreviated as tail.)

truncatinghead – In this mode, if the text is too wide to fit, it is truncated on the left, but a leading ellipsis (…) will be displayed to indicate that there is additional text that is not being displayed. (This mode can be abbreviated as head.)

truncatingmiddle – In this mode, if the text is too wide to fit, it is truncated in the middle, with an ellipsis (…) displayed in the middle to indicate that there is additional text that is not being displayed. (This mode can be abbreviated as middle.)

When using the truncation options, the system will try to compress the text before truncating. If the text will fit if compressed by 5%, it will be displayed compressed instead of truncated. You can use the `<tighten:factor>` tag to modify this. If the factor is set to `0` the text will never be compressed, if the factor is `0.1` it could be compressed by up to 10%.

#### Paragraph Layout (including Margins)

To indent text, use the `<leftmargin:margin>` tag. The margin is specified in points – this example indents the following text by 1/2 inch (36 points).

    richtextdisplay("<leftmargin:36>Body of paragraph ... ")

The first line of each paragraph can be indented separately by adding a second parameter: `<leftmargin:margin:indent>`. The indent value is relative to the left margin. In this example the text is indented by 1/2 inch, but the first line of each paragraph is indented an additional 1/4 inch (18 points) for a total of 3/4 inch.

    richtextdisplay("<leftmargin:36:18>Body of paragraph ... ")

The indent can be negative if you want the first line to have less margin than the rest of the paragraph. In this example the first line of following paragraphs isn’t indented at all, even though the rest of the text is indented by 1/2 inch (36 points).

    richtextdisplay("<leftmargin:36:-36>Body of paragraph ... ")

You can also use the `<rightmargin:margin>` tag to indent the right edge of the text. This example indents both the left and right margins by 1/4 inch.

    richtextdisplay("<leftmargin:18><rightmargin:18>Body of paragraph ... ")

The `<paragraphspacing:after:before>` tag allows extra space to be added after or before each paragraph. This example adds an extra 1/4 inch (18 points) after each paragraph.

    richtextdisplay("<paragraphspacing:18>Body of paragraph ... ")

This example adds an extra 1/3 of an inch (24 points) before each paragraph.

    richtextdisplay("<paragraphspacing::24>Body of paragraph ... ")

Of course you can also add extra space both before and after each paragraph.

#### Line Height and Spacing

The `<linespacing:space>` tag allows extra space to be added below each line. This example adds 1/12 inch (6 points) after each line.

    richtextdisplay("<linespacing:6>Body of paragraph ... ")

The `<lineheight:min:max:multiple>` tag has three parameters for controlling the line height. Normally the line height is automatically calculated based on the largest item in the line – for example a tall character or an image will increase the line height. The `min` value guarantees a minimum line height even if nothing on the line is that tall. In the example below, each line is guaranteed to be at least 1/2 inch tall, even if nothing in the line is that tall. (Since this is a minimum, the line could be taller than 1/2 inch if there is something tall in the line.)

    richtextdisplay("<lineheight:36>Body of paragraph ... ")

The ’max` parameter specifies the maximum height a line can be. If the line contains items that are taller than this, they will overlap other lines. This example guarantees that no line can be more than 1 inch high.

    richtextdisplay("<lineheight::72>Body of paragraph ... ")

Of course you can specify both min and max values if necessary.

The `multiple` parameter takes the automatically calculated line height and multiplies it by the specified factor. This example uses a factor of 2 to display double spaced text.

    richtextdisplay("<lineheight::2>Body of double spaced paragraph ... ")

The factor can be a non-integer value, for example `1.5` for halfway between single and double spacing. If the factor is less than 1 the lines will overlap (however, 0 is treated as 1.0). You can also specify minimum and maximum values which can limit the calculated spacing.

#### Changing the Tag Characters

RTML normally uses the `<` and `>` functions to identify tags. However, this may conflict with data you want to display. One way around this is to use the richtextdisplay( function, but you can also use the `<tag:open:close>` tag to change the tag characters. This example changes the tag characters to `(((` and `)))` (yes, multiple characters are allowed).

    richtextdisplay("<tag:(((,)))>(((color:00FF00)))some green text (((tag)))<color:FF0000>some red text"

As shown above, using the `tag` tag with no parameters switches the characters back to `<` and `>`.

See Also

- textdisplay( -- works with Text Display Objects to control the color and style of text on the fly.

History

Version | Status | Notes
10.0 | New | New in this version.