GEOS SDK TechDocs
|
| 
4.2 Lines and Fields
| 
4.4 Paragraph Runs
The character attributes of your text object may be singular or multiple. Singular character attributes have one common set of character attributes for use by all characters within a text object. Multiple character attributes store their characteristics in "runs" which allow separate characters in the same object to show different character attributes.
In many cases, your text object will need only one set of attributes for all characters. In those cases, the text object's character attributes instance field (VTI_
charAttrRuns
for VisText,
ATTR_GEN_TEXT_DEFAULT_CHAR_ATTR
or
ATTR_GEN_TEXT_CHAR_ATTR
for GenText) will store a single set of attributes. This word of data will contain either a 16-bit record or a ChunkHandle to a
VisTextCharAttr
structure. Those attributes will be exhibited by all characters in that text object.
Unless your
VisTextStorageFlags
specify VTSF_MULTIPLE_CHAR_ATTRS, your character attributes will be singular. (For GenText, this field is set automatically if using the singular attributes shown above.) All text within the text object will exhibit the same characteristics; also, any changes to the character attributes will affect every character in the entire text. If you need your text object to allow different characters to show different attributes (such as in a word processor), see Multiple Character Attributes
.
If your character attributes are singular, you have two choices: use a default set of characteristics or use a more complex (and complete) set of characteristics. For most simple generic text objects, the default set offers enough variety to accomplish most goals. If you need other character styles not offered in the default set, you will have to use the complete set of character attributes.
To use the default character attributes with a VisText, specify VTSF_DEFAULT_CHAR_ATTRS in your
VisTextStorageFlags
. The default set uses the
VisTextDefaultCharAttr
record to store the character's attributes. This record offers a simple collection of character fonts, point sizes, and other attributes (see below). If you need other character styles not found in this record, you should not set VTSF_DEFAULT_CHAR_ATTRS. The text object will automatically use the
VisTextCharAttr
structure.
By default, text objects using the default character attributes will be set to a font of VTDF_BERKELEY, a point size of VTDS_12, and a text color of C_BLACK.
If you do not use the default character attributes record, you must use the
VisTextCharAttr
structure to store your text object's character attributes. (In this case, do not set the VTSF_DEFAULT_CHAR_ATTRS flag in
VisTextStorageFlags
.) The text object's character attributes instance field will contain a ChunkHandle to this structure instead of the
VisTextDefaultCharAttr
record (see Setting Character Attributes
).
Code Display 10-16 Setting Character Attributes
/* This example shows how to set the default character attributes. */
@object GenTextClass MyTextObject = {
GTXI_text = "";
ATTR_GEN_TEXT_DEFAULT_CHAR_ATTR = (VTDCA_UNDERLINE |
(VTDS_18 << VTDCA_SIZE_OFFSET) | VTDF_BERKELEY);
/* This sets the default character attributes record (of type
* VisTextDefaultCharAttr) to use underlined Berkeley font in
* point size 18. */
}
/* This example shows how to use non-default singular character attributes. */
@object GenTextClass MyTextObject = {
GTXI_text = "";
ATTR_GEN_TEXT_CHAR_ATTR = (ChunkHandle) @MyTextCharAttrs;
/* This is a chunk handle to the chunk holding the text
* attributes (of type VisTextCharAttr). */
}
@chunk VisTextCharAttr MyCharAttrs =
CHAR_ATTR_FONT_SIZE_STYLE(FID_DTC_URW_ROMAN, 32, TS_UNDERLINE);
/* This chunk holds the record that will determine the character
* attributes of all the GenText's text. The text will be
* 32-point Roman, underlined. */
To allow a VisText object to exhibit multiple character attributes, you should set VTSF_MULTIPLE_CHAR_ATTRS and clear VTSF_DEFAULT_CHAR_ATTR flag in the object's
VisTextStorageFlags
(stored in
VTI_storageFlags
). For GenText, you should set
ATTR_GEN_TEXT_MULTIPLE_CHAR_ATTR_RUNS
. Any multiple character attribute object will not be able to use any of the default character attributes of type
VisTextDefaultCharAttr
.
Multiple character attributes allow your object's individual characters to exhibit different attributes. One character may be bold and italic; another may be underlined and in a different font. Any character may exhibit any of the attributes allowed within the
VisTextCharAttr
structure.
Multiple attributes are stored as lists of
VisTextCharAttr
Character attributes are specified by "runs." Each character run is used until another run is encountered, at which point the new character attributes are used. Runs are defined by a character position within a chunk array and an associated token element. At the character position, the token corresponds to a
VisTextCharAttr
element. The character attributes specified in this
VisTextCharAttr
structure are used until the character position of the next
VisTextCharAttr
token.
If, for example, a GenText object contains the text "Initial Text Here" with the word "Text" underlined, the chunk array of elements would look as shown in the figure above.
Code Display 10-17 Setting Multiple Character Attribute Runs
@object GenTextClass MultipleCharAttrsObject = {
ATTR_GEN_TEXT_MULTIPLE_CHAR_ATTR_RUNS = (ChunkHandle) @MyMultCharAttrs;
GTXI_text = "Initial Text Here";
}
#define MCA_PLAIN 0
#define MCA_UNDERLINE 1
@CHAR_ATTR_ELEMENT_ARRAY_HEADER CharAttrElements = {
CHAR_ATTR_FONT_SIZE_STYLE(FID_DTC_URW_ROMAN, 12, 0), /* Element 0 */
CHAR_ATTR_FONT_SIZE_STYLE(FID_DTC_URW_ROMAN, 12, TS_UNDERLINE) /* Element 1 */
};
@RUN_ARRAY_HEADER(CharAttrElements) MyMultCharAttrs = {
TRAE_ABS(0, MCA_PLAIN), /* Element 0 */
TRAE_ABS(8, MCA_UNDERLINE), /* Element 1 */
TRAE_END
};
MSG_VIS_TEXT_GET_CHAR_ATTR,VisTextCharAttrFlags, VisTextCharAttrDiffs, VisTextGetAttrFlags, MSG_VIS_TEXT_SET_CHAR_ATTR_BY_DEFAULT, MSG_VIS_TEXT_SET_CHAR_ATTR, MSG_VIS_TEXT_SET_FONT_ID, MSG_VIS_TEXT_SET_POINT_SIZE, MSG_VIS_TEXT_SET_TEXT_STYLE
There may be cases in which you would like to change the attributes exhibited by certain characters in your Text object. In most cases, you can do this most easily by including one of the controllers mentioned at the end of this chapter. The controllers leave any underlying work up to the specific controller implementation.
If you wish to manually change these character attributes, however, there are several messages to retrieve and set character attributes.
word MSG_VIS_TEXT_GET_CHAR_ATTR(@stack
VisTextGetAttrFlags flags,
VisTextCharAttrDiffs *diffs,
VisTextCharAttr *attrs,
dword rangeEnd,
dword rangeStart);
This message returns a buffer filled in with the
VisTextCharAttr
attributes of the given range of text. If VTGAF_MERGE_WITH_PASSED is passed in the
VisTextGetAttrFlags
, then the passed
VisTextCharAttr
structure will be compared with the range of text that this message is sent to (and any differences will be pointed out in the passed
diffs
buffer.(If this flag is not passed, any information initially in that buffer will be ignored.)
Over the passed range, different characters may exhibit different attributes; a pointer to a
VisTextCharAttrDiffs
structure is also passed to store information about attributes that are different across the range of text.
VisTextCharAttrDiffs
contains a list of
VisTextCharAttrFlags
specifying what attributes are multiply present. The structure also contains the bitfields of the
TextStyle
and
VisTextExtendedStyles
present over the range of text. Any attribute differences will produce a mention in one of these records; you can think of this process as XORing the attribute bitfields together.
VisTextCharAttrFlags
:Structures:
typedef struct {
VisTextCharAttrFlags VTCAD_diffs;
VisTextExtendedStyles VTCAD_extendedStyles;
TextStyle VTCAD_textStyles;
byte VTCAD_unused;
} VisTextCharAttrDiffs;
Source: Unrestricted.
Destination: Any text object.
Parameters: flags VTGAF_MERGE_WITH_PASSED to merge the retrieved text attributes with the text in the passed range.
VisTextCharAttrDiffs
structure to store attribute differences.
VisTextCharAttr
buffer to store the retrieved character attributes. If VTGAF_MERGE_WITH_PASSED is passed in flags, this buffer initially contains attributes to match against the retrieved attributes.
Return: The token of the specific character attribute run (word value) if the text object is storing runs of
VisTextCharAttr
structures. The
attrs
and
diffs
buffers are also filled with their relevant information.
Interception: Generally not intercepted.
void MSG_VIS_TEXT_SET_CHAR_ATTR_BY_DEFAULT(@stack
VisTextDefaultCharAttr defCharAttrs,
dword rangeEnd,
dword rangeStart);
This message sets the character attributes passed in
VisTextDefaultCharAttr
over the specified range of the text object. If the text object is not in "default" character attribute mode (i.e. it is storing runs of
VisTextCharAttr
structures) it will translate the default attributes into their matching
VisTextCharAttr
attributes.
Source: Unrestricted.
Destination: Any Text object.
Parameters:
defCharAttrs
VisTextDefaultCharAttr
record to set over the passed range of text.
Interception: Generally not intercepted.
void MSG_VIS_TEXT_SET_CHAR_ATTR(@stack
VisTextCharAttr *attrs,
dword rangeEnd,
dword rangeStart);
This message sets the character attributes passed in the
VisTextCharAttr
buffer over the specified range of the text object. If the text object is in "default" character attribute mode, it will force the text object to begin storing runs of
VisTextCharAttr
structures.
Source: Unrestricted.
Destination: Any Text object.
Parameters:
attrs
Pointer to a
VisTextCharAttr
buffer.
Interception: Generally not intercepted.
@importMessage MetaTextMessages, void MSG_VIS_TEXT_SET_FONT_ID(@stack
FontID fid,
dword rangeEnd,
dword rangeStart);
This message sets the passed
FontID
over the specified range of the text object. If the text object currently displays its values in "default" character attributes, it will force the text object to use character attribute runs to store its
VisTextCharAttr
structures.
Source: Unrestricted.
Destination: Any Text object.
Interception: Generally not intercepted.
@importMessage MetaTextMessages, void MSG_VIS_TEXT_SET_POINT_SIZE(@stack
WWFixed pointSize,
dword rangeEnd,
dword rangeStart);
This message sets the passed point size over the specified range of the text object. If the text object currently displays its values in "default" character attributes, it will force the text object to use character attribute runs to store its
VisTextCharAttr
structures.
Source: Unrestricted.
Destination: Any Text object.
Interception: Generally not intercepted.
@importMessage MetaTextMessages, void MSG_VIS_TEXT_SET_TEXT_STYLE(@stack
word extBitsToClear,
word extBitsToSet,
word styleBitsToClear,
word styleBitsToSet,
dword rangeEnd,
dword rangeStart);
This message sets the passed text styles over the specified range of the text object. You must specify the specific style bits to set and clear, both for the VTCA_
styles
and the VTCA_
extendedStyles
entries.
If the text object currently displays its values in "default" character attributes, it will force the text object to use character attribute runs to store its
VisTextCharAttr
structures.
Source: Unrestricted.
Destination: Any Text object.
Interception: Generally not intercepted.
GEOS SDK TechDocs
|
| 4.2 Lines and Fields
| 4.4 Paragraph Runs