The Text Objects: 3.2 The Text Object Library: Paragraph Attribute Definitions

| Up: GEOS SDK TechDocs | Up | Prev: 3.1 Character Attribute Definitions | Next: 3.3 Storage Flags

The text object library also provides many ways to shape the appearance of individual paragraphs. Each paragraph within a text object may exhibit its own individual attributes if the text object is set to allow multiple paragraph attributes. The definitions within this section show the full range of possibilities for paragraph attributes.

The VisTextParaAttr Structure

The VisTextParaAttr structure provides the largest set of attributes for use by paragraphs within text objects. Note that although the VisTextParaAttr structure is of a fixed size, the paragraph attributes consist of this structure and a variable number of tabs; therefore, the paragraph attributes within a "run" may be variably sized. These entries are listed in VisTextParaAttr . Comments follow the code display.

Code Display 10-5 VisTextParaAttr

typedef struct {
    StyleSheetElementHeader				VTPA_meta;
    VisTextParaBorderFlags				VTPA_borderFlags;
    ColorQuad				VTPA_borderColor;
    VisTextParaAttrAttributes				VTPA_attributes;
    word				VTPA_leftMargin;
    word				VTPA_rightMargin;
    word				VTPA_paraMargin;
    BBFixedAsWord				VTPA_lineSpacing;
    word				VTPA_leading;
    BBFixedAsWord				VTPA_spaceOnTop;
    BBFixedAsWord				VTPA_spaceOnBottom;
    ColorQuad				VTPA_bgColor;
    byte				VTPA_numberOfTabs;
    byte				VTPA_borderWidth;
    byte				VTPA_borderSpacing;
    byte				VTPA_borderShadow;
    SystemDrawMask				VTPA_borderGrayScreen;
    SystemDrawMask				VTPA_bgGrayScreen;
    HatchPattern				VTPA_borderHatch;
    HatchPattern				VTPA_bgHatch;
    word				VTPA_defaultTabs;
    word				VTPA_startingParaNumber;
    char				VTPA_prependChars[4];
    VisTextHyphenationInfo				VTPA_hyphenationInfo;
    VisTextKeepInfo				VTPA_keepInfo;
    VisTextDropCapInfo				VTPA_dropCapInfo;
    word				VTPA_nextStyle;
    StandardLanguage				VTPA_language;
    byte				VTPA_reserved[15];
} VisTextParaAttr;

VTPA_ meta stores a StyleSheetElementHeader . This structure field allows the VisTextParaAttr structure to act as an element in an element array. For complete information on using paragraph attribute element arrays to implement paragraph style runs, see Paragraph Runs .

VTPA_borderFlags stores the VisTextParaBorderFlags to use in drawing any borders around the text paragraph.

VTPA_ borderColor stores the color (of type ColorQuad ) of the border.

VTPA_ attributes stores the VisTextParaAttrAttributes to use on this paragraph. These attributes specify whether the paragraph uses keep-with, drop caps, automatic hyphenation, or paragraph numbering.

VTPA_ leftMargin stores the left margin of the paragraph. This margin is the distance (offset in points) from the left edge of the text object.

VTPA_ rightMargin stores the right margin of the paragraph. This margin is the distance (offset in points) from the right edge of the text object.

VTPA_ paraMargin stores the paragraph margin. This margin is the additional distance (offset in points from the left margin) to indent the first line of a paragraph.

VTPA_ lineSpacing stores the distance between lines of the paragraph. Single-spacing (a VTPA_ lineSpacing of 1.0) is the default value.

VTPA_ leading stores the leading of the paragraph. Leading is the additional space between all lines of a paragraph, independent of line spacing. This value is expressed in points.

VTPA_ spaceOnTop stores the additional vertical distance (expressed in points) before the first line of the paragraph. VTPA_ spaceOnTop plus VTPA_ spaceOnBottom is the total vertical distance between paragraphs.

VTPA_ spaceOnBottom stores the additional vertical distance (expressed in points) after the last line of the paragraph. VTPA_ spaceOnTop plus VTPA_ spaceOnBottom is the total vertical distance between paragraphs.

VTPA_bgColor stores the background color (of type ColorQuad ) of the paragraph. Note this is different from the background color of an individual character (in VTCA_ bgColor ). The background color of a character, if any, takes precedence over the background color of a paragraph.

VTPA_ numberOfTabs stores the number of tab stops contained in this paragraph. Tabs are added at the end of the VisTextParaAttr structure. Therefore, this structure may be of variable size, depending on the number of tabs.

VTPA_ borderWidth stores the width (in units of eight pixels) of the border, if any, attached to this paragraph.

VTPA_ borderSpacing stores the spacing (in units of eight pixels) between the paragraph border, if any, and the paragraph itself.

VTPA_ borderShadow stores the distance (in units of eight pixels) of the border shadow, if any, from the main border.

VTPA_ borderGrayScreen stores the SystemDrawMask to use when drawing the paragraph border.

VTPA_ bgGrayScreen stores the SystemDrawMask to use when drawing the paragraph background.

VTPA_ borderHatch stores HatchPattern to use when drawing the border.

VTPA_ bgHatch stores the HatchPattern to use when drawing the background.

VTPA_ defaultTabs stores the spacing for default tabs.

VTPA_ startingParaNumber stores the sequential number of this paragraph. This value depends on the VisTextNumberType in VTPA_ attributes .

VTPA_ prependChars stores the characters (up to four) to prepend to the beginning of this paragraph.

VTPA_ hyphenationInfo stores the VisTextHyphenationInfo (see below) to use between lines of text within a paragraph.

VTPA_ keepInfo stores the VisTextKeepInfo (see below) to use between this and other paragraphs.

VTPA_ dropCapInfo stores the VisTextDropCapInfo (see below) to use at the start of this paragraph.

VTPA_nextStyle and VTPA_language represent text attributes that are currently unimplemented but will be added.

VTPA_ reserved reserves fifteen bytes of data at the end of the VisTextParaAttr structure. These bytes are used to designate extra tabs.

Code Display 10-6 VisTextParaBorderFlags

  typedef WordFlags VisTextParaBorderFlags;
#define VTPBF_LEFT				0x8000
#define VTPBF_TOP				0x4000
#define VTPBF_RIGHT				0x2000
#define VTPBF_BOTTOM				0x1000
#define VTPBF_DOUBLE				0x0800
#define VTPBF_DRAW_INNER_LINES				0x0400
#define VTPBF_SHADOW				0x0200
#define VTPBF_ANCHOR				0x0003 /* ShadowAnchor */
#define VTPBF_ANCHOR_OFFSET				0
  typedef ByteEnum ShadowAnchor;
#define	SA_TOP_LEFT		0
#define	SA_TOP_RIGHT		1
#define	SA_BOTTOM_LEFT		2
#define	SA_BOTTOM_RIGHT		3

The VisTextParaBorderFlags specify the manner in which a border should be drawn around the paragraph.

VTPBF_LEFT, VTPBF_TOP, VTPBF_RIGHT, and VTPBF_BOTTOM all specify whether their respective side is drawn with a border. If you wish a border to entirely surround the text object, you should set all of these flags.

VTPBF_DOUBLE specifies that there should be a two-line border around this paragraph. This flag will double any lines set to be drawn with VTPBF_LEFT, VTPBF_TOP, VTPBF_RIGHT, and VTPBF_BOTTOM.

VTPBF_DRAW_INNER_LINES draws lines between bordered paragraphs. If two consecutive paragraphs are marked with this flag, a line border will be drawn between them.

VTPBF_SHADOW specifies that the border should be shadowed. The direction of shadowing is specified in the VTPBF_ANCHOR flag.

VTPBF_ANCHOR specifies the ShadowAnchor to use if drawing a border shadow. The ShadowAnchor specifies the corner of the paragraph to anchor the shadow. The shadowing effect on the paragraph will proceed from this corner towards the opposite corner.

Code Display 10-7 VisTextNumberType

  typedef ByteEnum VisTextNumberType;
#define	VTNT_NUMBER			0
#define	VTNT_LETTER_UPPER_A			1
#define	VTNT_LETTER_LOWER_A			2
#define	VTNT_ROMAN_NUMERAL_UPPER	3
#define	VTNT_ROMAN_NUMERAL_LOWER	4

The VisTextNumberType specifies the paragraph numbering scheme for this paragraph. For each paragraph with a numbering type, the object will number that paragraph sequentially based on the last occurrence of a paragraph with the same type. The text object stores this sequential number in the VTPA_ startingParaNumber entry.

Code Display 10-8 VisTextParaAttrAttributes

  typedef WordFlags VisTextParaAttrAttributes;
#define VTPAA_JUSTIFICATION					0xc000
#define VTPAA_KEEP_PARA_WITH_NEXT					0x2000
#define VTPAA_KEEP_PARA_TOGETHER					0x1000
#define VTPAA_ALLOW_AUTO_HYPHENATION					0x0800
#define VTPAA_DISABLE_WORD_WRAP					0x0400
#define VTPAA_COLUMN_BREAK_BEFORE					0x0200
#define VTPAA_PARA_NUMBER_TYPE					0x01c0
#define VTPAA_DROP_CAP					0x0020
#define VTPAA_KEEP_LINES					0x0010
#define VTPAA_JUSTIFICATION_OFFSET					14
#define VTPAA_PARA_NUMBER_TYPE_OFFSET					5

VTPAA_JUSTIFICATION stores the Justification to use with this paragraph.

VTPAA_KEEP_PARA_WITH_NEXT ensures that this paragraph and the next one will not be split along page breaks.

VTPAA_KEEP_PARA_TOGETHER ensures that the entire paragraph will not be split along page breaks. In most cases, this will cause a paragraph capable of being split to appear at the top of the next page.

VTPAA_ALLOW_AUTO_HYPHENATION allows the paragraph to automatically hyphenate words that cross line breaks. If this flag is set, the entry VTPA_ hyphenationInfo will store the VisTextHyphenationInfo to use when hyphenating words.

VTPAA_DISABLE_WORD_WRAP disables automatic word wrapping. Each line break will immediately wrap to next line without keeping words together.

VTPAA_PARA_NUMBER_TYPE stores the VisTextParaType for this paragraph. The actual paragraph number is stored in the VTPA_ startingParaNumber entry. The paragraph number type in tandem with the paragraph number determines what number heading this paragraph will have.

VTPAA_DROP_CAP signifies that a this paragraph uses Drop Caps. If this flag is set, the VisTextParaAttr entry VTPA_ dropCapInfo stores the VisTextParaDropCapInfo (see below).

VTPAA_KEEP_LINES specifies that this paragraph should make sure that beginning or ending lines of certain lengths should not be allowed to stand alone. If this flag is set, the VisTextParaAttr entry VTCA_ keepInfo stores the VisTextKeepInfo (see below).

Code Display 10-9 VisTextHyphenationInfo

  typedef WordFlags VisTextHyphenationInfo;
#define VTHI_HYPHEN_MAX_LINES					0xf000
#define VTHI_HYPHEN_SHORTEST_WORD					0x0f00
#define VTHI_HYPHEN_SHORTEST_PREFIX					0x00f0
#define VTHI_HYPHEN_SHORTEST_SUFFIX					0x000f
#define VTHI_HYPHEN_MAX_LINES_OFFSET						12
#define VTHI_HYPHEN_SHORTEST_WORD_OFFSET						 8
#define VTHI_HYPHEN_SHORTEST_PREFIX_OFFSET						 4
#define VTHI_HYPHEN_SHORTEST_SUFFIX_OFFSET						 0

If the VTPA_attributes flag VTPAA_ALLOW_AUTO_HYPHENATION is set, VisTextHyphenationInfo stores the criteria to use when hyphenating words in VTPA_ hyphenationInfo . If hyphenation is set, words will be automatically hyphenated using a Houghton-Mifflin engine.

VTHI_SHORTEST_WORD sets the shortest word-length (in character counts) to hyphenate. Words shorter than this character count will be wrapped to the next line.

VTHI_SHORTEST_PREFIX and VTHI_SHORTEST_SUFFIX set the shortest prefix and suffix to leave on a line after hyphenation. Prefixes or suffixes shorter than this character count will be tied to the main word and wrapped, if necessary.

Code Display 10-10 VisTextKeepInfo

  typedef ByteFlags VisTextKeepInfo;
#define VTKI_TOP_LINES				0xf0
#define VTKI_BOTTOM_LINES				0x0f
#define VTKI_TOP_LINES_OFFSET				4
#define VTKI_BOTTOM_LINES_OFFSET				0

If the VTPA_ attributes flag VTPAA_KEEP_LINES is set, VisTextKeepInfo specifies the number of lines at the beginning and end of a paragraph that should not remain across page breaks. This prevents "widows" and "orphans"--single lines either at the end of one page or the beginning of another.

VTKI_TOP_LINES specifies the minimum number of lines at the beginning of a paragraph to be considered able to stand alone and not kept part of the main paragraph along a page break.

VTKI_BOTTOM_LINES specifies the minimum number of lines at the end of a paragraph to be considered able to stand alone and not kept part of the main paragraph along a page break.

For example, if VTKI_BOTTOM_LINES is set to three, then single or double lines will not be able to stand on their own at the top of a page, and either the orphans will be kept with the main paragraph or additional line(s) will be brought over from the preceding page to pad the next page.

Code Display 10-11 VisTextDropCapInfo

  typedef WordFlags VisTextDropCapInfo;
#define VTDCI_CHAR_COUNT				0xf000
#define VTDCI_LINE_COUNT				0x0f00
#define VTDCI_POSITION				0x00f0
#define VTDCI_CHAR_COUNT_OFFSET					12
#define VTDCI_LINE_COUNT_OFFSET					8
#define VTDCI_POSITION_OFFSET					4

If the VTPA_ attributes flag VTPAA_DROP_CAP is set, VisTextDropCapInfo specifies the criteria to use when implementing Drop Caps. Drop Caps are currently not implemented in GEOS though they will be supported for later releases.

VTDCI_CHAR_COUNT sets the number of characters to capitalize at the start of the paragraph before resuming normal capitalization.

VTDCI_LINE_COUNT sets the number of lines to capitalize at the start of a paragraph before resuming normal capitalization.

Code Display 10-12 Tabs

  typedef ByteEnum TabLeader;
#define	TL_NONE 		0
#define	TL_DOT 		1
#define	TL_LINE		2
#define	TL_BULLET		3
#define	TL_GRAY_LINE		4
  typedef ByteEnum TabType;
#define TT_LEFT			0
#define TT_CENTER			1
#define TT_RIGHT			2
#define TT_ANCHORED			3
  typedef ByteFlags TabAttributes;
#define	TA_LEADER		0x1c		/* TabLeader */
#define	TA_TYPE		0x03		/* TabType */
#define TA_LEADER_OFFSET			2
#define TA_TYPE_OFFSET			0
  typedef struct {
    word			T_position;
    TabAttributes			T_attr;		/* TabAttributes */
    SystemDrawMask			T_grayScreen;
    byte			T_lineWidth;
    byte			T_lineSpacing;
    word			T_anchor;
} Tab;
  typedef struct {
    VisTextParaAttr			VTMPA_paraAttr;
    Tab			VTMPA_tabs[VIS_TEXT_MAX_TABS];
} VisTextMaxParaAttr;

The Tab structure allows your paragraph to add custom tab stops to a paragraph. These tabs are in addition to any default tab stops that are defined in VTPA_ defaultTabs . You may add up to 25 custom tabs to each paragraph. These tabs are added at the end of the VisTextParaAttr structure. Therefore, different paragraphs may have paragraph attributes of different lengths depending on the number of custom tabs in use by that paragraph.

Default Paragraph Attributes

You may decide that you do not need many of the features within the VisTextParaAttr structure in your paragraphs. If your text object is simple, you may want to use a set of default paragraph attributes provided in the text object library. These default attributes supersede the use of the VisTextParaAttr structure. All of these attributes will fit into a single word record of type VisTextDefaultParaAttr .

The VisTextDefaultParaAttr structure allows your text object to exhibit a Justification , a subset of default tabs, and left, right, and paragraph margins.

Code Display 10-13 VisTextDefaultParaAttr

typedef WordFlags VisTextDefaultParaAttr;
#define VTDPA_JUSTIFICATION				0xc000 /* Justification */
#define VTDPA_DEFAULT_TABS				0x3000 /* VisTextDefaultTab */
#define VTDPA_LEFT_MARGIN				0x0f00 /* In units of half-inches */
#define VTDPA_PARA_MARGIN				0x00f0 /* In units of half-inches */
#define VTDPA_RIGHT_MARGIN				0x000f /* In units of half-inches */
#define VTDPA_JUSTIFICATION_OFFSET					14
#define VTDPA_DEFAULT_TABS_OFFSET					12
#define VTDPA_LEFT_MARGIN_OFFSET					8
#define VTDPA_PARA_MARGIN_OFFSET					4
#define VTDPA_RIGHT_MARGIN_OFFSET					0
#define VIS_TEXT_INITIAL_PARA_ATTR ( (0*2) << VTDPA_LEFT_MARGIN_OFFSET) | \
				( (0*2) << VTDPA_PARA_MARGIN_OFFSET) | \
				( (0*2) << VTDPA_RIGHT_MARGIN_OFFSET) | \
				(VTDDT_INCH << VTDPA_DEFAULT_TABS_OFFSET) | \
				(J_LEFT << VTDPA_JUSTIFICATION_OFFSET)
  typedef ByteEnum VisTextDefaultDefaultTab;
#define VTDDT_NONE				0
#define VTDDT_HALF_INCH				1
#define VTDDT_INCH				2
#define VTDDT_CENTIMETER				3

The VisTextDefaultDefaultTab type is solely for use within a VisTextDefaultParaAttr record. The default tab stops provide either no tab stops (VTDDT_NONE) or tab stops every half-inch, centimeter, or inch. Note that no other application-defined tabs are allowed when using the default paragraph attributes.

Macros for Defining VisTextParaAttr Structures

The text object library also provides a macro to make the definition of the VisTextParaAttr structure simpler; there are also a few macros to aid in setting up justification and tab structures. These macros are listed in VisTextParaAttr Macros . In many cases, these macros make the definition of paragraph style runs vastly easier.

Code Display 10-14 VisTextParaAttr Macros

 #define PARA_ATTR_STYLE_JUST_LEFT_RIGHT_PARA(ref, style, just, left, right, para)\
{ \
	{{{ref, 0}}, style}, 0, {C_BLACK, CF_INDEX, 0, 0}, \
	just << VTPAA_JUSTIFICATION_OFFSET, (left)*PIXELS_PER_INCH, \
	(right)*PIXELS_PER_INCH, (para)*PIXELS_PER_INCH, \
	1<<8, 0, 0, 0, {C_WHITE, CF_INDEX, 0, 0}, \
	0, 1*8, 2*8, 1*8, SDM_100, SDM_0, {0}, {0}, \
	PIXELS_PER_INCH/2*8, VIS_TEXT_DEFAULT_STARTING_NUMBER, "", 0, 0, 0,
	CA_NULL_ELEMENT, SL_ENGLISH, {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}}
#define DEF_PARA_ATTR_JUST_TABS(just, tabs) \
	(( (0*2) << VTDPA_LEFT_MARGIN_OFFSET ) | \
	 ( (0*2) << VTDPA_PARA_MARGIN_OFFSET ) | \
	 ( (0*2) << VTDPA_RIGHT_MARGIN_OFFSET ) | \
	 ( (tabs) << VTDPA_DEFAULT_TABS_OFFSET ) | \
	 ( (just) << VTDPA_JUSTIFICATION_OFFSET ))
#define DEF_PARA_ATTR_CENTER DEF_PARA_ATTR_JUST_TABS(J_CENTER, VTDDT_INCH)
#define DEF_PARA_ATTR_RIGHT DEF_PARA_ATTR_JUST_TABS(J_RIGHT, VTDDT_INCH)
| Up: GEOS SDK TechDocs | Up | Prev: 3.1 Character Attribute Definitions | Next: 3.3 Storage Flags