The Rich Text option allows text to be displayed with multiple styles, fonts, colors and alignments – you can even include images and icons. You can control the format of the displayed text using tags that are similar in concept to those used for formatting in HTML. The Rich Text option is available in Text Display Objects, Text List Objects, Push Button Objects and Data Button Objects. Here are some examples of objects with rich text.

The Rich Text option can even be used in Custom Menus.

By the way, the icons in the examples above all come from Font Awesome Icons, which are built in to Panorama X.

In addition to the material below, there is also an intensive Panorama X video training session titled Text Objects which covers rich text in depth. Choose Panorama X Video Training from the Help menu to access the training sessions.

Rich Text Markup Language (RTML)

The basic idea of rich text is that you add tags to the text to control the style, in a manner that is very similar to HTML. Here is a simple example with bold and italic text.

RTML Quick Reference

There are about two dozen tags available, as listed in this table.

CategoryTagDescription
Text <b>…</b> Bold
<i>…</i> Italic
<ul>…</ul> Underline
<doubleul>…</ul> Double Underline
<thickul>…</ul> Thick Underline
<color:rrggbb>…</color> Color
<bgcolor:rrggbb>…</bgcolor> Background Color
<font:name:height>…</font> Font (height is optional)
<size:height>…</size> Font Height (in points)
Artwork <char:number> Unicode Character (dingbats & icons)
<image:name> Image (name may include relative or full path)
Layout <tabs:tab1,tab2,tab3,…> Tab Stops
<align:option> Horizontal Alignment (left/center/right/justified)
<leftmargin:value> Left Margin (points)
<rightmargin:value> Right Margin (points)
<paragraphspacing:before:after> Extra space before/after paragraphs (points)
<linespacing:after> Extra space after lines (points)
<lineheight:min:max:multiple> Line Height (points)
Wrapping <hyphenate:factor> Enable hyphenation
<linebreak:mode> Wrap Mode (wordwrapping/charwrapping/clipping/ truncatingtail/truncatinghead/truncatingmiddle)
<tighten:factor> Enable compression
Styles <style>…</style> Revert to previous style
<definestyle:name> Define named style
<style:name> Use named style
Other <tag:open:close> Tag Characters

See below for detailed information about each of these tags.

Enabling Rich Text in Graphic Objects

Graphic objects in a form normally display plain text. To enable rich text, check the Rich Text checkbox. (Of course you also have to put one or more tags into your text!) This example shows how to enable rich text in a Text Display Object.

Rich text can also be enabled in Text Lists, Push Buttons, and Data Buttons.

Enabling Rich Text in Custom Menus

To enable rich text in a custom menu, set the font to "#RichText".

This code produces this custom menu which includes bold text (the word Cube) and various icons.

To learn more, see Custom Menus.

RTML vs. HTML

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.

Technical Note: Basic RTML tags are the same as HTML, but many RTML tags are unique – for example tab stops, line & paragraph spacing, justification, text wrapping options etc. RTML includes almost all of the text attributes provided by Apple’s native text styling code (NSAttributedString). Basically, RTML is a version of Apple’s native text styling code that is readable and understandable by humans.

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 and the zip code in blue.

Here is another example that uses a Text Display object to create an entire letter with data merged into the text. It even includes a formula to automatically display today’s date.

However, what if a field or variable being merged into the text contains a < character? Panorama will think this is the start of a rich text tag, and the merge won’t work correctly. In this example, the company name contains a < so the letter is messed up wherever that field is included.

To prevent the < character from confusing the RTML formatting, enclose the field or variable with the richtextdata( function. This modified example will work correctly even if the Address field contains a < character.

Any < characters inside the richtextdata( function will be passed thru, without being interpreted as an RTML tag. (Of course if the data actually contains RTML tags, you won’t want to use this function.)

Note: An alternate method for fixing this problem 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.

"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>.

"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.

"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.

"Here is some <bgcolor:FFFF00>yellow highlighted</bgcolor> text."

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.)

"Text can be <font:SavoyeLetPlain:48>fancy</font> or <font:Courier:15>plain</font>."

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

"Different <font:TektonPro-Bold>fonts <font:Impact>in <font:Herculanum>the same size."

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

"Text can be <size:24>big</size> or <size:9>small."

Displaying Unicode Characters

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

"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.

"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.

"<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.

"Here is a red <char:x3C:::FF0000> character."

Note: Font Awesome is an open source icon font that includes over 500 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.)

"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 fruit in the same folder as the database.

"Apple <image:fruit/apple-100.jpg> Pears <image:fruit/pear-100.jpg>"

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

"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.

"<image:##Pencil.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 two tab stops, at 75 and 180 points (72 points to an inch). In this illustration the left side shows the RTML source, the right side shows the displayed rich text.

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. In this example the first tab stop is centered, but the second is normal.

Decimal justified tabs are designed for numbers, and will line up the decimal points on the tab location.

As you can see above, decimal tab stops don’t work too well when mixing numbers and text. Here’s the same data but with right aligned tab stops.

Don’t forget, you can mix in all of the other formatting tags into tabular data!

Of course normally the tabbed data wouldn’t be hard coded like these examples, 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).

"<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 this 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/3 inch (24 points).

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/3 inch, but the first line of each paragraph is indented an additional 1/4 inch (18 points).

The indent can be negative if you want the first line to have less margin than the rest of the paragrah. 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/3 inch (24 points).

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.

"<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.

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

"<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 8 points after each line.

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.)

"<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.

"<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.

"<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.

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.

"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 un-does 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.

"<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:

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.

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).

"<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 >.


History

VersionStatusNotes
10.0NewNew in this version.