Creating styled text

Styled Text refers to text than can have a variety of fonts, font sizes and other font styles. Styled Text can be used with the desktop Text Area control when its Styled property is ON or True (which is the default).

Additionally, on Mac you can use the StyledTextPrinter class to print styled text. This is discussed in the Sending data to the printer topic.

Determining font, size and style of text

TextAreas have properties that make it easy to determine the font, font size, and font style of the selected text. The SelectionFontName property can be used to determine the font of the selected text. If the selected text has only one font, the SelectionFontName property contains the name of that font. If the selected text uses more than one font, the SelectionFontName property is empty.

This function returns the names of fonts for the selected text of the TextArea passed:

Function Fonts(item As TextArea) As String
  Var fonts, theFont As String
  Var i, Start, Length As Integer
  If item.SelectionFontName = "" Then
    Start = item.SelectionStart
    Length = item.SelectionLength
    For i = Start To Start + Length
      Field.SelectionStart = i
      Field.SelectionLength = 1
      If fonts.Indexof(Field.SelectionFontName) = 0 Then
        If fonts = "" Then
          fonts = Field.SelectionFontName
        Else
          fonts = fonts + ", " + Field.SelectionFontName
        End If
      End If
    Next
    Return fonts
  Else
    Return Field.SelectionFontName
  End If
End Function

The SelectionFontSize property is used to determine the font size of the selected text and works the same way as the SelectionFontName property. If all characters of the selected text are the same font size, the SelectionFontSize property will contain that size. If different sizes are used, the SelectionFontSize property will be 0.

There are also boolean properties for determining if all of the characters in the selected text are the same font style. Since text can have multiple styles applied to it, these properties determine if all of the characters in the selected text have a particular font style applied to them. For example, if all of the characters in the selected text are bold but some are also italic, a test for bold returns True. On the other hand, a test for italic returns False since some of the selected text is not in the italic font style. For all of these properties, you test to see if the property is True or False. If the test returns True, then all of the characters in the selected text have that font style. If it returns False, the selected text contains more than one font style. If you want to determine which styles are in use, you can programmatically select each character in the selected text and then test the style properties. This is an operation similar to the sample Font function that determines which fonts are in use in the selected text. In this example, if the selected text of the TextArea is bold, then the Bold menu item is checked:

StyleBold.Checked = TextArea1.SelectionBold

If all of the characters in the selected text are not bold then TextArea1.SelectionBold returns False which will then be assigned to the Checked property of the StyleBold menu item.

Setting the font, size, and style of text in desktop app

For desktop apps, the properties used to check the font, font size, and font styles of the selected text are also used to set these values. A DesktopTextArea can support multiple fonts, font sizes, and styles. A DesktopTextField can support one font, one font size, and the plain style. A DesktopTextField can also support the Bold, Underline, and Italic styles for all the text in the DesktopTextField.

For example, to set the font of the selected text to Helvetica, you do the following:

TextArea1.SelectionFontName = "Helvetica"

Keep in mind when setting fonts that the font must be installed on the user's computer or the assignment will have no effect. You can use the FontAvailable function mentioned earlier in this chapter to determine if a particular font is installed.

You can set the FontSize property of a control to zero to have your application use the font size that looks best for the platform on which the application is running. You can set the font size of the selected text using the SelectionFontSize property. For example, the following code sets the font size of TextArea1 to 12 point:

TextArea1.SelectionFontSize = 12

To apply a particular font style to the selected text, set the appropriate style property to True. For example, the following code applies the Bold style to the selected text in TextArea1:

TextArea1.SelectionBold = True

TextAreas also have built-in methods for toggling the font styles on and off. Toggling in this case means applying the style if some of the selected text doesn 't have the style already applied or removing the style from any of the selected text that already has it applied. The following code toggles the bold style of the selected text in TextArea1:

TextArea1.ToggleSelectionBold

These methods are used to toggle the selection style:

ToggleSelectionBold
ToggleSelectionItalic
ToggleSelectionUnderline

Styled Text objects for DesktopTextArea

When you are working with styled text that is displayed in a TextArea, you can work with the properties of TextAreas that get and set style attributes as described in the previous section to manage styled text. However, there are also classes for opening, saving, and managing styled text separately from a TextArea or any other control. In fact, the styled text doesn 't even have to be displayed at all. This set of techniques uses the properties and methods of the StyledText class. Its Text property contains the styled text that is managed by the StyledText object.

Each method takes parameters for the starting position and length of the text for which the attribute applies. These numbers are zero-based. For example, a call to the Bold property would look like this:

Var st As New StyledText
st.Text = "How now Brown Cow."
st.Bold(0, 3) = True

This sets the first word of the text, “How,” to bold.

Each contiguous set of characters that has the identical set of style attributes makes up a StyleRun object. In the above example, the first three characters make up one StyleRun. The remaining text is the second StyleRun. In the language of a word processor, each StyleRun is an instance of a character style. The entire Text property is made up of a sequence of StyleRuns. The StyledText class has these methods for managing StyleRuns:

Name	Description
Bold	Gets or sets the Bold style to the selected text in Text.
FontName	Gets or sets the font for the selected text in Text.
Italic	Gets or sets the Italic style to the selected text in Text.
FontSize	Gets or sets the font size to the selected text in Text.
TextColor	Gets or sets the color of the selected text in Text.
Underline	Gets or sets the Underline style to the selected text in Text.

The StyledText class has these methods for managing StyleRuns:

Name	Description
AddStyleRun	Appends a StyleRun to the end of Text.
AddStyleRunAt	Inserts a StyleRun at a specified position.
RemoveStyleRunAt	Removes a specified StyleRun from Text.
StyleRun	Provides access to a particular StyleRun in Text. The StyleRun class has its own properties that describe the style that's applied to all the characters in the StyleRun.
StyleRunCount	Returns the number of StyleRuns that make up Text.
StyleRunRange	Accesses the starting position, length, and end position of the StyleRun.
Text	The text that is managed by the StyledText object. Technically, Text is a method, but you can get and set its value as if it were a property.

The Text method of a StyledText object can have multiple paragraphs. A paragraph is the text between two end-of-line characters. A paragraph can be defined either with the EndOfLine function or the end-of-line character for the platform the application is running on.

A paragraph can be made up of multiple StyleRuns. It has only one style property of its own, paragraph alignment (Left, Centered, or Right).

Although you can work with a StyledText object entirely in code — without ever displaying it — the TextArea control is “hooked up” to the StyledText class in the sense that you can access all the methods and properties of the StyledText class via the StyledText property of the TextArea. These methods can be used to work with Paragraphs:

Name	Description
Paragraph	Provides access to a particular Paragraph in Text. The Paragraph class has its own properties that return the start position, length, end position, and alignment of the paragraph.
ParagraphCount	Returns the number of Paragraphs that make up Text.
ParagraphTextAlignment	Sets the alignment of the specified paragraph (Default, Left, Centered, or Right). The ParagraphAlignment method takes one parameter, the number of the paragraph to be aligned (starting at zero). You assign it a TextAlignments enumeration value. For example, to right align the first paragraph, you would use code like this: StyledText1.ParagraphTextAlignment(0) = TextAlignments.Right

In order to work with a StyledText object in a TextArea, both the MultiLine and Styled properties of the TextArea must be ON or True (which is the default). You can do this using the Inspector.

Suppose the styled TextArea already has the text that you want to manipulate using the StyledText class. The following code loads the text into the StyledText object:

Var st As New StyledText
st = TextArea1.StyledText
TextArea1.AddText("This is the added text.")
st.Bold(0, 4) = True

The StyledText object is actually an alias to the TextArea's text, not a static copy. This means that the third line of code changes the contents of the TextArea and the last line sets the first four characters of the TextArea to bold.

The following code sets the Text property of the StyledText object and displays it in the TextArea:

TextArea1.StyledText.Text = "Here is my styled text." + EndOfLine + "Impressive. Most impressive."

From there, you can go ahead and assign style properties to the text. The changes reformat the contents of the TextArea. Here is code that works with these two paragraphs:

Var st, ln As Integer
Var Text As String
Text = "Here is my styled text." + EndOfLine + "Aren 't you really impressed?"
TextArea1.StyledText.Text = Text

// Assign Font and  Size to entire text
TextArea1.StyledText.Font(0, Text.Length) = "Arial"
TextArea1.StyledText.Size(0, Text.Length) = 14

// Apply character highlights to 'my// in first paragraph
TextArea1.StyledText.Bold(8, 2) = True
TextArea1.StyledText.TextColor(8, 2) = &cff0000
// Get positions of second paragraph (0-based)
st = TextArea1.StyledText.Paragraph(1).StartPos - 1
ln = TextArea1.StyledText.Paragraph(1).Length

// Second paragraph in Bold
TextArea1.StyledText.Bold(st, ln) = True

// Second paragraph Centered
TextArea1.StyledText.ParagraphAlignment(1) = Paragraph.AlignCenter

This above code works with the StyledText object "hooked up" to the TextArea, but you can also work with styled text "offline." You declare a StyledText object in a Var statement and operate on it without reference to any control. When you 're ready to display it, you can assign it to the StyledText property of a TextArea.

You would do this with code such as:

Var st As New StyledText
// do whatever you want right here; when you 're done, just write...
TextArea1.StyledText = st

You can also export the styled text as a series of StyleRuns and read them back in and reconstruct the StyledText object using the AddStyleRun method. See StyleRun and StyledText for more information.

Creating styled text

Determining font, size and style of text

Setting the font, size, and style of text in desktop app

Styled Text objects for DesktopTextArea

See also