Carbon


ATSUSetLineControls

Header: ATSUnicode.h Carbon status: Supported

Sets text layout attributes for a line of text in a text layout object.

OSStatus ATSUSetLineControls (
    ATSUTextLayout iLayout, 
    UniCharArrayOffset iLineStart, 
    ItemCount iAttributeCount, 
    ATSUAttributeTag iTag[], 
    ByteCount iValueSize[], 
    ATSUAttributeValuePtr iValue[]
);
Parameter descriptions
iLayout

A reference to an initialized text layout object that contains the line whose attribute values you want to set. You cannot pass NULL for this parameter.

iLineStart

The edge offset in backing store memory corresponding to the the beginning of the line whose attribute values you want to set.

iAttributeCount

The number of attributes you want to set. This value should correspond to the number of elements in the iTag array.

iTag

An array of attribute tags. Each element in the array must contain a valid tag that corresponds to a text layout attribute value in the line. See “Text Layout Attribute Tag Constants” for a description of Apple-defined tag values. If you pass a style run attribute or an ATSUI-reserved tag value in this parameter, ATSUSetLineControls returns the result code kATSUInvalidAttributeTagErr. You cannot pass NULL for this parameter.

iValueSize

An array of attribute value sizes. Each element in the array must contain the size (in bytes) of the corresponding text layout attribute value being set. If you pass a size that is less than required, ATSUSetLineControls returns the result code kATSUInvalidAttributeSizeErr, and the function sets no attributes. If, after having checked all the given sizes and found them acceptable, ATSUSetLayoutControls sets text layout attributes. You cannot pass NULL for this parameter.

iValue

An array of attribute value pointers. Each pointer in the array must reference a valid value and correspond to a tag in the iTag array. If you pass an invalid or undefined value, ATSUSetLineControls returns the result code kATSUInvalidAttributeValueErr. You cannot pass NULL for this parameter.

function result

A result code. If there is a function error, ATSUSetLineControls will not set any text layout attributes in the line.

DISCUSSION

The ATSUSetLineControls function enables you to set multipe text layout attribute values for a single line in a text layout object. Any unset text layout attribute values are assigned the default values described in “Text Layout Attribute Tag Constants”.

Note that when you set a text layout attribute value for a line, this value will override the value of the text layout attribute set for the text layout object containing the line. This is true even if the attributes for the line are set before those of the entire text layout object containing the line.

To set the text layout attributes of an entire text layout object, call the function ATSUSetLayoutControls.

ATSUI functions that operate on a line of text like ATSUDrawText, ATSUMeasureText, ATSUMeasureTextImage, and ATSUGetGlyphBounds, use text layout attributes that have been set by calling ATSUSetLineControls to calculate dimensions. If none have been set for the line, they use those set for the text layout object containing the line. If none have been set for the text layout object containing the line, ATSUI assigns them their default value.

ATSUSetLineControls may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.1.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.6 or later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)