Carbon


ATSUGetAttribute

Header: ATSUnicode.h Carbon status: Supported

Obtains a style run attribute value from a style object.

OSStatus ATSUGetAttribute (
    ATSUStyle iStyle, 
    ATSUAttributeTag iTag, 
    ByteCount iExpectedValueSize, 
    ATSUAttributeValuePtr oValue, 
    ByteCount *oActualValueSize
);
Parameter descriptions
iStyle

A reference to a valid style 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 “Style Run Attribute Tag Constants” for a description of the Apple-defined style run attribute tag constants. If you pass a text layout attribute tag constant or an ATSUI-reserved tag constant in this parameter, ATSUGetAttribute returns the result code kATSUInvalidAttributeTagErr. You cannot pass NULL for this parameter.

iExpectedValueSize

The expected size (in bytes) of the value that ATSUGetAttribute passes back in the oValue parameter. To determine the size of an application-defined style run attribute value, see the discussion below. If the value size you specify is too small, ATSUGetAttribute 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 ATSUGetAttribute, 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, ATSUGetAttribute 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, as in the case of custom style run attributes.

function result

A result code.

DISCUSSION

Before calling ATSUGetAttribute, call the function ATSUGetAllAttributes 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 ATSUGetAttribute. If you do not know the size of the style run attribute value you wish to determine, call ATSUGetAttribute twice:

  1. Pass a reference to the style object containing the attribute in the iStyle parameter, NULL for the oValue parameter, and 0 for the other parameters. ATSUGetAttribute returns the size of the style run attribute value in the oActualValueSize parameter.
  2. Allocate enough space for a value of the returned size, then call the function again, passing a pointer in the oValue parameter. On return, the pointer points to the style run attribute value you wish to obtain.

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)