The Text Objects: 4.4 Text Object Chunks: Paragraph Runs

| Up: GEOS SDK TechDocs | Up | Prev: 4.3 Character Runs | Next: 5 Using VisText

The paragraph attributes of your text object may also be singular or multiple. Singular paragraph attributes use one common set of characteristics for all the text in the text object. Multiple paragraph attributes store their characteristics in "runs" which allow separate paragraphs in the same object to use different attributes.

Singular Paragraph Attributes

You may only need your text object to exhibit a singular set of paragraph attributes. In this case, the text object's paragraph attributes instance field (VTI_ paraAttrRuns for VisText, GEN_TEXT_DEFAULT_PARA_ATTR or GEN_TEXT_PARA_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 chunk of more complex attributes.

Unless your VisTextStorageFlags (in VTI_storageFlags ) specify VTSF_MULTIPLE_PARA_ATTRS, your paragraph attributes will be singular. (This flag will be set automatically for GenTexts using the above attributes.) Initially, all text within the text object will exhibit these same characteristics; also, any changes to the text object's paragraph attributes will affect the entire text. If your text object should allow different paragraphs to exhibit different attributes, see Multiple Paragraph Attributes .

If your paragraph attributes are singular, you have two choices: use a default set of characteristics or use a more complex (and complete) set of characteristics. What you use depends on the variety of choices you wish your application to have over the display of its text. For most simple generic text objects, the default set offers enough variety to accomplish most goals.

To use the default paragraph attributes, specify VTSF_DEFAULT_PARA_ATTRS in the text object's VTI_storageFlags field (for VisText) or set ATTR_GEN_TEXT_DEFAULT_PARA_ATTR (for GenText). The default set uses the VisTextDefaultParaAttr record to store the paragraph's attributes. This record offers a simple collection of paragraph justifications, tab stops and margins, and its definition is given in VisTextDefaultParaAttr . If you need other paragraph styles not found in this record, you should not set VTSF_DEFAULT_PARA_ATTRS.

By default, text objects using the default paragraph attributes will be left-justified, have default tab stops at one inch intervals, and have zero right, left, and paragraph margins.

If you do not use the default paragraph attributes record, you must use the VisTextParaAttr structure to store your text object's paragraph attributes. (In this case, do not set VTSF_DEFAULT_PARA_ATTRS in VTI_storageFlags .) The text object's paragraph attributes instance field will contain a ChunkHandle to this structure instead of the VisTextDefaultParaAttr record.

Code Display 10-18 Setting VisTextParaAttr Attributes

/* This example shows setting the initial default paragraph attributes. */
@object GenTextClass MyTextObject = {
    GTXI_text = "";
    ATTR_GEN_TEXT_DEFAULT_PARA_ATTR = ((J_CENTER << VTDPA_JUSTIFICATION_OFFSET) | 
			( (2*2) << VTDPA_LEFT_MARGIN_OFFSET) |
			( (1*2) << VTDPA_PARA_MARGIN_OFFSET) |
			( VTDDT_HALF_INCH << VTDPA_DEFAULT_TABS_OFFSET));
}
/* This example shows setting non-default singular paragraph attributes. */
@object GenTextClass MyTextObject = {
    GTXI_text = "";
    ATTR_GEN_TEXT_PARA_ATTR = (ChunkHandle) @MyParaAttrs;
}
@chunk VisTextParaAttr MyParaAttrs = 
    PARA_ATTR_STYLE_JUST_LEFT_RIGHT_PARA(0, 0, J_CENTER, 0, 2, 1);

Multiple Paragraph Attributes

To allow your VisText object to exhibit individual paragraph attributes, you should set VTSF_MULTIPLE_PARA_ATTRS and clear the VTSF_DEFAULT_PARA_ATTR flag in the object's VTI_storageFlags record. For GenText, set the attribute ATTR_GEN_TEXT_MULTIPLE_PARA_ATTR_RUNS . Any multiple paragraph attribute object will not be able to use any of the default paragraph attributes of type VisTextDefaultParaAttr .

Multiple paragraph attributes allow your object's individual paragraphs to exhibit different attributes. One paragraph may be left justified; another may be centered with different margins. Any paragraph may exhibit any of the attributes allowed within the VisTextParaAttr structure separately.

Multiple paragraph attributes are stored in the same manner as multiple character attributes. See Character Runs for a full description of how runs are stored.

Paragraph attributes are specified by runs. Each paragraph run is used until another run is encountered, at which point the new paragraph attributes are applied and used. Runs are defined by the character position within a chunk array and an associated token element; therefore, you must take care when defining a paragraph run so that it coincides with the first character of a new paragraph. At the character position, the token corresponds to a VisTextParaAttr element. The paragraph attributes specified in this VisTextParaAttr structure are used until the next VisTextParaAttr element.

Changing Paragraph Attributes

MSG_VIS_TEXT_GET_PARA_ATTR,VisTextParaAttrFlags, VisTextParaAttrBorderFlags, VisTextParaAttrDiffs, MSG_VIS_TEXT_SET_PARA_ATTR_BY_DEFAULT, MSG_VIS_TEXT_SET_PARA_ATTR, MSG_VIS_TEXT_SET_PARA_ATTRIBUTES, MSG_VIS_TEXT_ADD_PARA_ATTR

There may be cases in which you would like to change the attributes exhibited by certain paragraphs in your Text object. As with character attributes, you can do this most easily by including one of the controllers mentioned at the end of this chapter.

If you wish to manually change these character attributes, however, there are several messages to retrieve and set character attributes.

MSG_VIS_TEXT_GET_PARA_ATTR

word 	MSG_VIS_TEXT_GET_PARA_ATTR(@stack
        VisTextGetAttrFlags 			flags,
        VisTextParaAttrDiffs 			*diffs,
        VisTextParaAttr 			*attrs,
        dword 			rangeEnd,
        dword 			rangeStart);

This message returns a buffer filled in with the VisTextParaAttr attributes of the given range of text. If VTGAF_MERGE_WITH_PASSED is passed in the VisTextGetAttrFlags , then a passed VisTextParaAttr structure will be merged with the range of text that this message is sent to. (If this flag is not passed, any information initially in that buffer will be ignored.)

Over the passed range, different paragraphs may exhibit different attributes; a pointer to a VisTextParaAttrDiffs structure is also passed to store information about attributes that are different across the range of text. This structure contains lists of VisTextParaAttrFlags and VisTextParaAttrBorderFlags specifying what paragraph and paragraph border attributes are multiply present. The structure also contains the bitfields of the VisTextParaAttrAttributes , VisTextHyphenationInfo, VisTextKeepInfo , and VisTextDropCapInfo present over the range of text.

Possible VisTextParaAttrFlags . If any of these are set, the selection exhibits the indicated multiple property over the range of text:
VTPAF_MULTIPLE_LEFT_MARGINS
VTPAF_MULTIPLE_RIGHT_MARGINS
VTPAF_MULTIPLE_PARA_MARGINS
VTPAF_MULTIPLE_LINE_SPACINGS
VTPAF_MULTIPLE_DEFAULT_TABS
VTPAF_MULTIPLE_TOP_SPACING
VTPAF_MULTIPLE_BOTTOM_SPACING
VTPAF_MULTIPLE_LEADINGS
VTPAF_MULTIPLE_BG_COLORS
VTPAF_MULTIPLE_BG_GRAY_SCREENS
VTPAF_MULTIPLE_BG_PATTERNS
VTPAF_MULTIPLE_TAB_LISTS
VTPAF_MULTIPLE_STYLES
VTPAF_MULTIPLE_PREPEND_CHARS
VTPAF_MULTIPLE_PARA_NUMBERS
Possible VisTextParaAttrBorderFlags :
VTPABF_MULTIPLE_BORDER_LEFT
VTPABF_MULTIPLE_BORDER_TOP
VTPABF_MULTIPLE_BORDER_RIGHT
VTPABF_MULTIPLE_BORDER_BOTTOM
VTPABF_MULTIPLE_BORDER_DOUBLES
VTPABF_MULTIPLE_BORDER_DRAW_INNERS
VTPABF_MULTIPLE_BORDER_ANCHORS
VTPABF_MULTIPLE_BORDER_WIDTHS
VTPABF_MULTIPLE_BORDER_SPACINGS VTPABF_MULTIPLE_BORDER_SHADOWS VTPABF_MULTIPLE_BORDER_COLORS VTPABF_MULTIPLE_BORDER_GRAY_SCREENS VTPABF_MULTIPLE_BORDER_PATTERNS

Structures: 

typedef struct {
	VisTextParaAttrFlags 					VTPAD_diffs;
	VisTextParaAttrBorderFlags					VTPAD_borderDiffs;
	VisTextParaAttrAttributes					VTPAD_attributes;
	VisTextHyphenationInfo					VTPAD_hyphenationInfo;
	VisTextKeepInfo					VTPAD_keepInfo;
	VisTextDropCapInfo					VTPAD_dropCapInfo;
} VisTextParaAttrDiffs;

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.

diffs
Pointer to a VisTextParaAttrDiffs structure to store attribute differences.
attrs
Pointer to a VisTextParaAttr buffer to store the retrieved paragraph attributes. If VTGAF_MERGE_WITH_PASSED is passed in flags, this buffer initially contains attributes to match against the retrieved attributes.
rangeEnd
End of the range (character position).
rangeStart
Beginning of the range (character position).

Return: The token of the specific paragraph attribute run (word value) if the text object is storing runs of VisTextParaAttr structures. The attrs and diffs buffers are also filled with their relevant information.

Interception: Generally not intercepted.

MSG_VIS_TEXT_SET_PARA_ATTR_BY_DEFAULT

void	MSG_VIS_TEXT_SET_PARA_ATTR_BY_DEFAULT(@stack
        VisTextDefaultParaAttr 				defParaAttrs,
        dword 				rangeEnd,
        dword 				rangeStart);

This message sets the paragraph attributes passed in VisTextDefaultParaAttr over the specified range of the text object. If the text object is not in "default" paragraph attribute mode (i.e. it is storing runs of VisTextParaAttr structures) it will translate the default attributes into their matching VisTextParaAttr attributes.

Source: Unrestricted.

Destination: Any Text object.

Parameters: defParaAttrs VisTextDefaultParaAttr record to set over the passed range of text.

rangeEnd
End of the range (Character position).
rangeStart
Start of the range (Character position).

Interception: Generally not intercepted.

MSG_VIS_TEXT_SET_PARA_ATTR

void	MSG_VIS_TEXT_SET_PARA_ATTR(@stack
        VisTextParaAttr 		*newParaAttrs,
        dword 		rangeEnd,
        dword 		rangeStart);

This message sets the paragraph attributes passed in the VisTextParaAttr buffer over the specified range of the text object. If the text object is in "default" paragraph attribute mode, it will force the text object to begin storing runs of VisTextParaAttr structures.

Source: Unrestricted.

Destination: Any Text object.

Parameters: newParaAttrs Pointer to a VisTextParaAttr buffer.

rangeEnd
End of the range (Character position).
rangeStart
Start of the range (Character position).

Interception: Generally not intercepted.

MSG_VIS_TEXT_ADD_PARA_ATTR

word	MSG_VIS_TEXT_ADD_PARA_ATTR(
        VisTextMaxParaAttr 		*paraAttr);

This message adds a given set of paragraph attributes passed in the VisTextParaAttr buffer to the paragraph "run" for that text object. The text object must not be in "default" paragraph attribute mode; it must already be storing runs of VisTextParaAttr structures.

Source: Unrestricted.

Destination: Any Text object that is storing runs of VisTextParaAttr structures.

Parameters: paraAttr P ointer to a VisTextParaAttr buffer.

Return: Token of the paragraph run entry (word-value).

Interception: Generally not intercepted.

| Up: GEOS SDK TechDocs | Up | Prev: 4.3 Character Runs | Next: 5 Using VisText