Android Programming Press on the image to return to the main documentation page.

RichString

Written by Andrew Graham

This library contains RichString and RichStringBuilder objects. These objects are
analogous to the normal String and StringBuilder. However RichStrings can contain
formatting information that controls how they are drawn when used as the text in a View.

This library also contains a RichStringFormatter object. This object, once suitably
initialised, will efficiently format RichStrings passed to it. For long strings that
require many changes of format this is much more efficien than using the individual
RichString formatting commands.

List of types:

RichString
RichStringBuilder
RichStringFormatter

RichString

A RichString supports formatting of its contents at the individual character level.
The formatting methods are available in two forms.

The first form accepts a start and index for the region of the RichString to format
in the same way that regions of ordinary strings are specified.

The second form uses matched identifiers within the RichString contents to identify the
regions to be formatted. The identifiers are arbitary strings used in pairs within the
RichString content to bracket the regions to be formatted. Multiple regions within the
RichString content can be specified in a single call.

Events:

None

Members:


  BackColor (color As Int, start As Int, end As Int) As RichString

  BackColor2 (color As Int, metachars As String) As RichString

  Color (color As Int, start As Int, end As Int) As RichString

  Color2 (color As Int, metachars As String) As RichString

  Initialize (text As CharSequence)

  IsInitialized As Boolean

  Length As Int [read only]

  RelativeSize (scale As Float, start As Int, end As Int) As RichString

  RelativeSize2 (scale As Float, metachars As String) As RichString

  ScaleX (scale As Float, start As Int, end As Int) As RichString

  ScaleX2 (scale As Float, metachars As String) As RichString

  SetSpanBehaviour (spanbehaviour As Int)

  SPAN_EXCLUSIVE_EXCLUSIVE As Int

  SPAN_EXCLUSIVE_INCLUSIVE As Int

  SPAN_INCLUSIVE_EXCLUSIVE As Int

  SPAN_INCLUSIVE_INCLUSIVE As Int

  Strikethrough (start As Int, end As Int) As RichString

  Strikethrough2 (metachars As String) As RichString

  Style (style As Int, start As Int, end As Int) As RichString

  STYLE_BOLD As Int

  STYLE_BOLD_ITALIC As Int

  STYLE_ITALIC As Int

  STYLE_NORMAL As Int

  Style2 (style As Int, metachars As String) As RichString

  Subscript (start As Int, end As Int) As RichString

  Subscript2 (metachars As String) As RichString

  Superscript (start As Int, end As Int) As RichString

  Superscript2 (metachars As String) As RichString

  Typeface (typefamily As String, start As Int, end As Int) As RichString

  Typeface2 (typefamily As String, metachars As String) As RichString

  TypefaceCustom (Typeface As android.graphics.Typeface, start As Int, end As Int) As RichString

  TypefaceCustom2 (Typeface As android.graphics.Typeface, metachars As String) As RichString

  Underscore (start As Int, end As Int) As RichString

  Underscore2 (metachars As String) As RichString

Members description:

BackColor (color As Int, start As Int, end As Int) As RichString
Sets the background colour of the region.
BackColor2 (color As Int, metachars As String) As RichString
Sets the background colour of the regions.
Color (color As Int, start As Int, end As Int) As RichString
Sets the text colour of the region.
Color2 (color As Int, metachars As String) As RichString
Sets the text colour of the regions.
Initialize (text As CharSequence)
Initialise the RichString with the provided text.
Text can be a String, a RichString or a RichStringBuilder.
IsInitialized As Boolean
Length As Int [read only]
Return the number of characters in this RichString.
RelativeSize (scale As Float, start As Int, end As Int) As RichString
Sets the size of the text in the region relative to the normal text.
A value of 1.0 specifies the normal text size. i.e unchanged.
A smaller value reduces the size and a larger value increases it.
RelativeSize2 (scale As Float, metachars As String) As RichString
Sets the size of the text in the regions relative to the normal text.
A value of 1.0 specifies the normal text size. i.e unchanged.
A smaller value reduces the size and a larger value increases it.
ScaleX (scale As Float, start As Int, end As Int) As RichString
Sets the horizontal size of the text in the region relative to the normal text.
A value of 1.0 specifies the normal text size. i.e unchanged.
A smaller value reduces the size and a larger value increases it.
ScaleX2 (scale As Float, metachars As String) As RichString
Sets the horizontal size of the text in the region relative to the normal text.
A value of 1.0 specifies the normal text size. i.e unchanged.
A smaller value reduces the size and a larger value increases it.
SetSpanBehaviour (spanbehaviour As Int)
SpanBehaviour determines how each region behaves when it is edited and sshould be
one of the SPAN_XXXX constants.
On initialisation the default is SPAN_INCLUSIVE_EXCLUSIVE;

Unlike a RichStringFormatter each region may be added with its own SpanBehaviour.
SPAN_EXCLUSIVE_EXCLUSIVE As Int
Regions of this type do not expand to include text inserted at either their start or end point.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces nRnBnRn
SPAN_EXCLUSIVE_INCLUSIVE As Int
Non zero length regions of this type expand to include text inserted at their end point
but not at their start point.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces nRrBbRr
SPAN_INCLUSIVE_EXCLUSIVE As Int
Non zero length regions of type SPAN_INCLUSIVE_EXCLUSIVE expand to include text inserted at
their start point but not at their end point.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces rRbBrRn
This was the default in previous versions of RichStringFormatter.
SPAN_INCLUSIVE_INCLUSIVE As Int
Regions of this type expand to include text inserted at either their start or end point.
If two regions adjoin then the rightmost region format appears to be adopted.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces rRbBrRr
Strikethrough (start As Int, end As Int) As RichString
Sets the region to display struckthrough text.
Strikethrough2 (metachars As String) As RichString
Sets the regions to display struckthrough text.
Style (style As Int, start As Int, end As Int) As RichString
Sets the style of the region to one of the RichText.STYLE_XXXX constants.
STYLE_BOLD As Int
STYLE_BOLD_ITALIC As Int
STYLE_ITALIC As Int
STYLE_NORMAL As Int
Style2 (style As Int, metachars As String) As RichString
Sets the style of the regions to one of the RichText.STYLE_XXXX constants.
Subscript (start As Int, end As Int) As RichString
Sets the region to display subscript text.
Subscript2 (metachars As String) As RichString
Sets the regions to display subscript text.
Superscript (start As Int, end As Int) As RichString
Sets the region to display superscript text.
Superscript2 (metachars As String) As RichString
Sets the regions to display superscript text.
Typeface (typefamily As String, start As Int, end As Int) As RichString
Sets the typeface family to be used for the region.
Examples are "monospace", "serif", and "sans-serif".
Typeface2 (typefamily As String, metachars As String) As RichString
Sets the typeface family to be used for the regions.
Examples are "monospace", "serif", and "sans-serif".
TypefaceCustom (Typeface As android.graphics.Typeface, start As Int, end As Int) As RichString
Sets the typeface to be used for the region.
TypefaceCustom2 (Typeface As android.graphics.Typeface, metachars As String) As RichString
Sets the typeface to be used for the regions.
Underscore (start As Int, end As Int) As RichString
Sets the region to display underscored text.
Underscore2 (metachars As String) As RichString
Sets the regions to display underscored text.

RichStringBuilder

RichStringBuilder is a mutable RichString unlike regular RichStrings which are immutable.
RichStringBuilder is especially useful when you need to concatenate many RichStrings.
Methods of a RichStringBuilder return itself so methods may be repeatedly invoked

Events:

None

Members:


  Append (text As CharSequence) As RichStringBuilder

  Initialize

  Insert (offset As Int, text As CharSequence) As RichStringBuilder

  IsInitialized As Boolean

  Length As Int [read only]

  Remove (startoffset As Int, endoffset As Int) As RichStringBuilder

  Version As Double [read only]

Members description:

Append (text As CharSequence) As RichStringBuilder
Appends the specified text at the end.
Returns the same object, so you can chain methods.
Text can be a String, a RichString or a RichStringBuilder.
Initialize
Initialise the RichStringBuilder.
Insert (offset As Int, text As CharSequence) As RichStringBuilder
Inserts the specified text at the specified offset.
Returns the same object, so you can chain methods.
Text can be a String, a RichString or a RichStringBuilder.
IsInitialized As Boolean
Length As Int [read only]
Return the number of characters in this RichStringBuilder.
Remove (startoffset As Int, endoffset As Int) As RichStringBuilder
Removes the specified characters.
StartOffset - The first character to remove.
EndOffset - The ending index. This character will not be removed.
Returns the same object, so you can chain methods.
Text can be a String, a RichString or a RichStringBuilder.
Version As Double [read only]
Returns the version number of the library.

RichStringFormatter

A RichStringFormatter provides a very efficient way of applying multiple formats to
a RichString using matched identifiers within the RichString contents to identify the
regions to be formatted.

Each of the RichString format commands iterates along the entire RichString
so applying several different formats to the same RichString invokes several iterations.
This is fine for short strings like Labels but may take a significant time for longer text
with more complicated formatting.

In constrast a RichStringFormatter will format a RichString in a single pass over the string.
However in order to accomplish this some initialisation work is necessary to define the
formatting tokens that will be accepted by the formatter. Once initialised a RichStringFormatter
may be used repeatedly on RichStrings as long as they are using the same tokens for formatting
as the RichStringFormatter was initialised to expect.

All formatting tokens must start and end with the characters specified in Initialize.
Note that start and end characters need not be different, the same character can be used for both.
Formatting tokens are case-sensitive and may be of arbitrary length.

Unlike XML or HTML formatting tokens do not need to be properly nested. They may overlap with no
adverse effect and the resulting formatting will be as expected.

Events:

None

Members:


  AddToken (token As String, format As Int, data As String)

  Format (richstring As android.text.SpannableString, spanbehaviours As Int) As RichString

  FORMAT_BACKCOLOR As Int

  FORMAT_COLOR As Int

  FORMAT_RELATIVESIZE As Int

  FORMAT_SCALEX As Int

  FORMAT_STRIKETHROUGH As Int

  FORMAT_STYLE As Int

  FORMAT_SUBSCRIPT As Int

  FORMAT_SUPERSCRIPT As Int

  FORMAT_TYPEFACE As Int

  FORMAT_UNDERSCORE As Int

  Initialize (sampletoken As String)

  SPAN_EXCLUSIVE_EXCLUSIVE As Int

  SPAN_EXCLUSIVE_INCLUSIVE As Int

  SPAN_INCLUSIVE_EXCLUSIVE As Int

  SPAN_INCLUSIVE_INCLUSIVE As Int

  STYLE_BOLD As Int

  STYLE_BOLD_ITALIC As Int

  STYLE_ITALIC As Int

  STYLE_NORMAL As Int

  UnimplementedTokens As String()

  UnpairedTokens As String()

Members description:

AddToken (token As String, format As Int, data As String)
Add a token that will be recognised when formatting a RichString. As many tokens as
required may be added and once added may be used across multiple invocations of Format.

token - is the token that must start and end with the same characters specified in Initialize.
format - is one of the RichStringFormatter FORMAT_XXXX constants
data - is any data relevant to the specified format as used in the RichString format methods.
Format (richstring As android.text.SpannableString, spanbehaviours As Int) As RichString
Format the specified RichString using the token set built using AddToken.
SpanBehaviour determines how each region behaves when it is edited and should be
one of the SPAN_XXXX constants.

Returns a new RichString.
FORMAT_BACKCOLOR As Int
FORMAT_COLOR As Int
FORMAT_RELATIVESIZE As Int
FORMAT_SCALEX As Int
FORMAT_STRIKETHROUGH As Int
FORMAT_STYLE As Int
FORMAT_SUBSCRIPT As Int
FORMAT_SUPERSCRIPT As Int
FORMAT_TYPEFACE As Int
FORMAT_UNDERSCORE As Int
Initialize (sampletoken As String)
Initialise the formatter with the start and end characters of each token.
The characters are taken from the start and end characters of the sample token.
Adding a token that does not start and end correctly will throw an exception.
SPAN_EXCLUSIVE_EXCLUSIVE As Int
Regions of this type do not expand to include text inserted at either their start or end point.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces nRnBnRn
SPAN_EXCLUSIVE_INCLUSIVE As Int
Non zero length regions of this type expand to include text inserted at their end point
but not at their start point.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces nRrBbRr
SPAN_INCLUSIVE_EXCLUSIVE As Int
Non zero length regions of type SPAN_INCLUSIVE_EXCLUSIVE expand to include text inserted at
their start point but not at their end point.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces rRbBrRn
This was the default in previous versions of RichStringFormatter.
SPAN_INCLUSIVE_INCLUSIVE As Int
Regions of this type expand to include text inserted at either their start or end point.
If two regions adjoin then the rightmost region format appears to be adopted.
For example, where R(ed) and B(Blue) are red and blue regions of a string RBR
and r(ed) and b(lue) and n(ormal) are the color of inserted characters
then this span constant produces rRbBrRr
STYLE_BOLD As Int
STYLE_BOLD_ITALIC As Int
STYLE_ITALIC As Int
STYLE_NORMAL As Int
UnimplementedTokens As String()
Returns a String array containing any tokens that were found in the RichString
but were not added to the formatter.
A zero length array is returned if there are no unimplemented tokens.
UnpairedTokens As String()
Returns a String array containing any tokens that remained unpaired after Format.
A zero length array is returned if there are no unpaired tokens.
Top