Carbon


ATSUGetLineControl

Header: ATSUnicode.h Carbon status: Supported

Obtains a text layout attribute value from a line of text.

OSStatus ATSUGetLineControl (
    ATSUTextLayout iLayout, 
    UniCharArrayOffset iLineStart, 
    ATSUAttributeTag iTag, 
    ByteCount iExpectedValueSize, 
    ATSUAttributeValuePtr oValue, 
    ByteCount *oActualValueSize
);
Parameter descriptions
iLayout

A reference to an initialized text layout object containing the line whose attribute value you want to obtain. 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 value you want to determine.

iTag

A valid tag that identifies the attribute value you wish to determine. Pass a valid tag that corresponds to the text layout attribute whose value you want to determine. 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, ATSUGetLineControl returns the result code kATSUInvalidAttributeTagErr.

iExpectedValueSize

The expected size (in bytes) of the value that ATSUGetLineControl passes back in the oValue parameter. If the value size you specify is too small, ATSUGetLineControl returns the result code kATSUInvalidAttributeSizeErr and does not pass back the attribute value in the oValue parameter.

oValue

A pointer to an attribute value. Before calling ATSUGetLineControl, pass a pointer to memory you have allocated for the attribute value. If you are uncertain of how much memory to allocate, see the discussion below. On return, a pointer to the attribute value you wish to obtain. If the value was not previously set, ATSUGetLineControl passes back the default value in this parameter and returns the result code kATSUNotSetErr.

oActualValueSize

On return, a pointer to the actual size (in bytes) of the attribute value. You should examine this parameter if you are unsure of the size of the attribute value you wish to obtain.

function result

A result code.

DISCUSSION

Before calling the ATSUGetLineControl function, call the function ATSUGetAllLineControls to obtain an array of tag/attribute size pairs passed back in the oAttributeInfoArray array. You should then pass the tag/value size pair whose attribute value you want to determine in the iTag and iMaximumValueSize parameters of ATSUGetLineControl.

To determine the value of a text layout attribute value in a text layout object, call the function ATSUGetLayoutControl.

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)