Carbon


ATSUGetLayoutControl

Header: ATSUnicode.h Carbon status: Supported

Obtains a text layout attribute value from a text layout object.

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

A reference to an initialized text layout object whose attribute value you want to obtain. You cannot pass NULL for this parameter.

iTag

A valid tag that identifies the attribute value you wish to determine. See “Text Layout Attribute Tag Constants” for a description of the Apple-defined text layout attribute tag constants. If you pass a style run attribute tag constant or an ATSUI-reserved tag in this parameter, ATSUGetLayoutControl returns the result code kATSUInvalidAttributeTagErr. You cannot pass NULL for this parameter.

iExpectedValueSize

The expected size (in bytes) of the value that ATSUGetLayoutControl passes back in the oValue parameter. If the value size you specify is too small, ATSUGetLayoutControl 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 ATSUGetLayoutControl, 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, ATSUGetLayoutControl 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 passed back attribute value.

function result

A result code.

DISCUSSION

Before calling the ATSUGetLayoutControl function, call the function ATSUGetAllLayoutControls 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 ATSUGetLayoutControl.

To determine the value of a text layout attribute value in a single line of a text layout object, call the function ATSUGetLineControl.

VERSION NOTES

Available beginning with ATSUI 1.0.

AVAILABILITY

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


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