|
StyledText Class
All documentation is preliminary and subject to change
What is the StyledText Class?
The StyledText class provides a set of methods and properties to safely manipulate text that has been formatted using the formatting codes defined
for use in SKY Index. SICI developers should use these classes whenever modifying text since using conventional string manipulation such as Left(),
Right(), Mid() and so on can result in corrupted/malformed coding which will ultimately mean your program returns an inappropriate result.
The StyledText class provides formatting aware alternatives to the functions mentioned above and also allows for the more advanced text manipulation
as well.
How do I use the StyledText class?
How you use them depends on what you're trying to do. If all you want to do is do string manipulation with functions like Left(), Right() and Mid(),
you would simply create a reference to a StyledText class and then call the appropriate method. For instance, there is a LeftStr() method, and a
RightStr() method. If you want to find out what formatting has been applied to a text string, you would call the SetSKYText method to force the text to
be parsed into formatted segments and then you would step through the segments to determine the formatting that has been applied to each segment. You
can make changes to those segments and then determine the resulting text using GetSKYText method.
String Manipulation Replacements
All of these functions accept a StyledText string as input and return a StyledText string (if a string is returned). In other words, all applied formatting is retained where
appropriate.
Notes
All Count parameters and Offset parameters assume you're counting using the 'plain text' version of the string. For instance,
calling LeftStr("/i1Kamm Schreiner/i0", 4) would give you "/i1Kamm/i0".
All Offset parameters are one based (the first character of a string is 1, not 0)
If you wish to examine a string for a specific character - for instance, if you want to see if the first character of a string is the capital letter
'T', you must use the Plain Text version of the StyledText (using PlainStr) and then just examine whatever characters within the string that you wish to
determine using plain text versions of the programming language you are using.
If you want to determine if the first character is a capital 'T' and you want to know the formatting of that letter, break the text into
Segments. Text Segments are described later.
If the parameter is "StyledText" it can include formatting codes. If the parameter is "Text" it cannot include formatting codes (the codes would
simply be treated as text).
InsertStr(StyledText As String, Offset As Integer, Text As String) As String
|
Description
|
Inserts 'Text' into 'StyledText' after the character specified by 'Offset'.
|
|
Parameters
|
StyledText (String) – the Styled Text into which 'Text' will be inserted.
Offset (Long) – the offset within the plain text version of StyledText to insert Text.
Text (String) - the text to insert into the styled text input string.
|
|
Returns
|
(String) A new StyledText string that includes the Text which was inserted after the character specified by Offset.
|
|
Notes
|
- The inserted text will take on the same formatting as the character immediately before it. If you are inserting the text before the first
character, it will take on the formatting of the first character of the StyledText.
- If you specify 0 (or less) for an offset, the text will be prepended to the Styled Text.
- If you specify an Offset greater than or equal to the number of characters in the StyledText, the Text will be appended to the StyledText
|
InString(StyledText As String, Text As String, Optional Compare As Integer = 0) As Integer
|
Description
|
Locates the position of Text within StyledText. The search starts with the first character of StyledText.
|
|
Parameters
|
StyledText (String) – the Styled Text into which is to be searched.
Text (String) - the text to find within the styled text input string.
Compare (Integer) – the method used to compare Text with the text in the StyledText input string.
(omitted) = Uses the default comparison method of case sensitive comparison.
0 = case sensitive.
1 = non-case sensitive.
|
|
Returns
|
(Integer) The offset within StyleText of the Text substring.
|
|
Notes
|
- Returns 0 if Text could not be found within StyledText.
- The returned offset is relative to the plain text version of StyledText. An offset of 1 would be the very first character of the input string.
|
InStringRev(StyledText As String, Text As String, Optional Compare As Integer = 0) As Integer
|
Description
|
Locates the position of Text within StyledText. The search starts with the last character of StyledText and moves backward toward the first
character.
|
|
Parameters
|
StyledText (String) – the Styled Text into which is to be searched.
Text (String) - the text to find within the styled text input string.
Compare (Integer) – the method used to compare Text with the text in the StyledText input string.
(omitted) = Uses the default comparison method of case sensitive comparison.
0 = case sensitive.
1 = non-case sensitive.
|
|
Returns
|
(Integer) The offset within StyleText of the Text substring.
|
|
Notes
|
- Returns 0 if Text could not be found within StyledText.
- The returned offset is relative to the plain text version of StyledText. An offset of 1 would be the very first character of the input string.
|
LeftStr(StyledText as String, Count as Long) As String
|
Description
|
Returns the first 'Count' characters from the specified string.
|
|
Parameters
|
StyledText (String) – the text to extract the substring from.
Count (Long) – the number of characters to include in the extracted substring.
|
|
Returns
|
(String) The first Count characters from the input Text starting with the first character. If less than Count characters exist, all characters in the
input string are returned. If Count is zero or negative, no characters are returned.
|
|
Notes
|
No Notes
|
LenStr(StyledText as String) As Long
|
Description
|
Returns the length of the string after all formatting codes have been removed. |
|
Parameters
|
StyledText (String) – the text to determine the length of.
|
|
Returns
|
(Long) The length of text after all formatting codes have been removed.
|
LTrimStr(StyledText as String) As String
|
Description
|
Removes all space characters from the beginning of the specified string.
|
|
Parameters
|
StyledText (String) – the text to remove leading spaces from.
|
|
Returns
|
(String) The same string as the input string minus any leading spaces.
|
|
Notes
|
See also RemoveLeadingPunctuation
|
MidStr(StyledText As String, Offset As Integer, Optional Length As Integer = -1) As String
|
Description
|
Extracts text from the Styled Text string 'StyledText' starting at Offset and continuting for Length characters.
|
|
Parameters
|
StyledText (String) – the Styled Text from which a substring will be extracted.
Offset (Long) – the offset relative to the plain text version of StyledText where substring will be extracted.
Length (Integer) - (optional) the number of plain text characters to extract.
|
|
Returns
|
(String) A new StyledText string that is a substring of StyledText.
|
|
Notes
|
- If Offset is less than one, an empty string is returned.
- If Length is omitted or is -1, all characters after the specified Offset will be included.
- If Offset is greater than the length of the StyledText input string, an empty string is returned.
|
PlainStr(StyledText as String) As String
|
Description
|
Returns the 'plain text' version of the input string. All formatting codes are stripped away. |
|
Parameters
|
StyledText (String) – the text that you want to remove the formatting from.
|
|
Returns
|
(String) Returns the 'plain text' version of the input string. All formatting codes are stripped away.
|
RemoveLeadingPunctuationStr(StyledText as String, Optional Punctuation as String) As String
|
Description
|
Removes all puncuation from the beginning of the specified string.
|
|
Parameters
|
StyledText (String) – the text to remove leading spaces from.
Punctuation (String) – a string containing all characters that are to be considered as punctuation.
|
|
Returns
|
(String) The same string as the input string minus any leading spaces.
|
|
Notes
|
By default, these characters are considered punctuation:
(space) .(period) ,(comma) !(exclamation point) "(double quote) '(single quote)
See also LTrimStr
|
RemoveTrailingPunctuationStr(StyledText as String, Optional Punctuation as String) As String
|
Description
|
Removes all puncuation from the end of the specified string.
|
|
Parameters
|
StyledText (String) – the text to remove trailing spaces from.
Punctuation (String) – a string containing all characters that are to be considered as punctuation.
|
|
Returns
|
(String) The same string as the input string minus any trailing spaces.
|
|
Notes
|
By default, these characters are considered punctuation:
(space) .(period) ,(comma) !(exclamation point) "(double quote) '(single quote)
See also RTrimStr
|
RightStr(StyledText as String, Count as Long) As String
|
Description
|
Returns the last 'Count' characters from the specified string.
|
|
Parameters
|
StyledText (String) – the text to extract the substring from.
Count (Long) – the number of characters to include in the extracted substring.
|
|
Returns
|
(String) The last Count characters from the input Text starting with the last character. If less than Count characters exist, all characters in the
input string are returned. If Count is zero or negative, no characters are returned.
|
|
Notes
|
No Notes
|
RTrimStr(StyledText as String) As String
|
Description
|
Removes all space characters from the end of the specified string.
|
|
Parameters
|
StyledText (String) – the text to remove trailing spaces from.
|
|
Returns
|
(String) The same string as the input string minus any trailing spaces.
|
|
Notes
|
See also RemoveTrailingPunctuation
|
SplitStr(ByVal StyledText As String, ByVal Delimiter As String) As String()
|
Description
|
Splits the Styled Text string at each occurence of the specified delimiter and returns a zero based array containing each string that was extracted.
|
|
Parameters
|
StyledText (String) – the Styled Text from which a substring will be extracted.
Delimiter (String) – the character or characters that will be used to split the string into substrings.
|
|
Returns
|
(String()) A zero based array of StyledText strings that contains all of the substrings that existed around the specified delimiter
text.
|
|
Notes
|
No Notes
|
StuffStr(StyledText As String, Offset As Integer, DeleteCount As Integer, InsertText As String, Optional Style As
TextStyle) As String
|
Description
|
Inserts and/or deletes text starting at the specified 1 based offset. When inserting text, you can optionally include a TextStyle object to define
any formatting to be applied to the inserted string.
|
|
Parameters
|
StyledText (String) – the text to extract the substring from.
Offset (Integer) – the number of characters to include in the extracted substring.
DeleteCount (Integer) – then number of characters to delete from the input string.
InsertText (String) – Text that you wish to be inserted at Offset.
Style (TextStyle) – an optional parameter that allows you to specify the style of the text being inserted.
|
|
Returns
|
(String) .
|
|
Notes
|
Stuffing plain text into the middle of a formatted string will result in plain text in the middle of the string. If you want a character style
applied to the inserted text, use the optional Style object to specify the style of the text you're inserting or your can manually add formatting codes
to format the text. If you choose to do the latter, be certain to match the codes or potentially undesirable and certainly undefined results will occur.
See also InsertStr
|
TrimStr(StyledText as String) As String
|
Description
|
Removes all space characters from the beginning and end of the specified string.
|
|
Parameters
|
StyledText (String) – the text to remove leading and trailing spaces from.
|
|
Returns
|
(String) The same string as the input string minus any leading or trailing spaces.
|
|
Notes
|
See also RemoveLeadingPunctuation; RemoveTrailingPunctuation
|
Working with Text Segments
The StyledText class includes methods for splitting styled text into Segments. A segment is the largest text substring that contains no changes in
character style. Anytime a character style change is detected, a new segment is created. Each Segment contains the following two properties:
Text - The text that is included in the segment
TextStyle - A TextStyle object that defines what characters styles, if any, have been applied to the text
Two examples:
This text: "My first segment example" contains three segments
Segment(1): "My first " (no character style)
Segment(2): "segment " (italic style)
Segment(3): "example" (no character style)
This text: "My second segment example" contains four segments
Segment(1): "My " (no character style)
Segment(2): "second " (bold style)
Segment(3): "segment " (italic+underline style)
Segment(4): "example" (italic style)
Creating a segment list
To create a segment list, use the SetSKYText method. For example:
Dim MyStyledText as New StyledText
MyStyledText.SetSKYText("My /i1styled/i0 text string")
After making that call, the StyledText class will create a segment collection that can be accessed through the Segments property. You can use the
SegmentCount property to determine how many segments exist for the specified text.
You can then read the results like this:
Print MyStyledText.Segments(1).Text (Output="My ")
Print MyStyledText.Segments(1).TextStyle.Italic (Output=False)
Print MyStyledText.Segments(2).Text (Output="styled")
Print MyStyledText.Segments(2).TextStyle.Italic (Output=True)
TextStyle Object Properties:
Note: Use of the properties with an asterisk is stongly discouraged. When using the SICI, you should ignore these properties. Do not
read or write to them.
*Name (String) - The default font's name
Bold (Boolean) - Specifies if the bold attribute is on or off
Italic (Boolean) - Specifies if the italic attribute is on or off
Underline (Boolean) - Specifies if the bold attribute is on or off
*SmallCaps (Boolean) - not used for SKY Index 7.0
StrikeThru (Boolean) - Specifies if the strikout attribute is on or off
Superscript (Boolean) - Specifies if the superscript attribute is on or off
Subscript (Boolean) - Specifies if the subscript attribute is on or off
FontID (Integer) - Specifies if an alternative font has been applied: 0 = no, 1-3 = yes
*ColorID (Integer) - Specifies if a color has been applied: 0 = no, 1-9 = yes
*TitleCase (Boolean) - not used for SKY Index 7.0
*Unicode (Boolean) - not used for SKY Index 7.0
Hidden (Boolean) - Specifies if the hidden attribute has been applied
Ignored (Boolean) - Specifies if the ignored attribute has been applied
Note (Boolean) - Specifies if the note attribute has been applied
|