AILayerSuite Struct Reference
[API Suite List]

The artwork in an Illustrator document is contained within layers. More...

#include <AILayer.h>

Public Attributes
AIAPI AIErr(*	CountLayers )(ai::int32 *count)
	Gets the number of top-level layers in the current document layer list.
AIAPI AIErr(*	GetNthLayer )(ai::int32 n, AILayerHandle *layer)
	Retrieves a top-level layer by index from the current document.
AIAPI AIErr(*	GetCurrentLayer )(AILayerHandle *layer)
	Retrieves a reference to the current layer in the current document.
AIAPI AIErr(*	SetCurrentLayer )(AILayerHandle layer)
	Makes a layer current.
AIAPI AIErr(*	GetFirstLayer )(AILayerHandle *first)
	Retrieves the topmost layer of the current document layer list.
AIAPI AIErr(*	GetNextLayer )(AILayerHandle prev, AILayerHandle *next)
	Retrieves the next layer below a given layer in the stacking order, at the same level of the layer list stack.
AIAPI AIErr(*	InsertLayer )(AILayerHandle layer, ai::int16 paintOrder, AILayerHandle *newLayer)
	Adds a new layer to a document, inserting it into the layers' lists at a position in the paint order relative to an existing layer.
AIAPI AIErr(*	DeleteLayer )(AILayerHandle layer)
	Removes a layer and all of its contained art from the current document.
AIAPI AIErr(*	GetLayerTitle )(AILayerHandle layer, ai::UnicodeString &title)
	Retrieves the name of a layer.
AIAPI AIErr(*	SetLayerTitle )(AILayerHandle layer, const ai::UnicodeString &newTitle)
	Sets the name of a layer.
AIAPI AIErr(*	GetLayerColor )(AILayerHandle layer, AIRGBColor *color)
	Retrieves the color used when outlining selected artwork in a layer.
AIAPI AIErr(*	SetLayerColor )(AILayerHandle layer, AIRGBColor color)
	Sets the color used when outlining selected artwork in a layer.
AIAPI AIErr(*	GetLayerVisible )(AILayerHandle layer, AIBoolean *visible)
	Reports the visibility status of a layer, which affects whether the artwork is drawn.
AIAPI AIErr(*	SetLayerVisible )(AILayerHandle layer, AIBoolean visible)
	Sets the visibility status of a layer, which affects whether the artwork is drawn.
AIAPI AIErr(*	GetLayerPreview )(AILayerHandle layer, AIBoolean *preview)
	Reports whether a layer specifies preview or outline mode.
AIAPI AIErr(*	SetLayerPreview )(AILayerHandle layer, AIBoolean preview)
	Sets a layer to preview mode or outline mode.
AIAPI AIErr(*	GetLayerEditable )(AILayerHandle layer, AIBoolean *editable)
	Reports whether a layer is editable or locked.
AIAPI AIErr(*	SetLayerEditable )(AILayerHandle layer, AIBoolean editable)
	Sets whether a layer is editable or locked.
AIAPI AIErr(*	GetLayerPrinted )(AILayerHandle layer, AIBoolean *printed)
	Reports whether this layer is considered printable when printing the document.
AIAPI AIErr(*	SetLayerPrinted )(AILayerHandle layer, AIBoolean printed)
	Sets whether this layer is considered printable when printing the document.
AIAPI AIErr(*	GetLayerDimPlacedImages )(AILayerHandle layer, AIBoolean *dimmed)
	Reports whether images in a layer are dimmed (colors shifted toward white) when rendering.
AIAPI AIErr(*	SetLayerDimPlacedImages )(AILayerHandle layer, AIBoolean dimmed)
	Sets whether images in a layer are dimmed (colors shifted toward white) when rendering.
AIAPI AIErr(*	GetLayerSelected )(AILayerHandle layer, AIBoolean *selected)
	Reports whether a layer is selected.
AIAPI AIErr(*	SetLayerSelected )(AILayerHandle layer, AIBoolean selected)
	Sets whether a layer is selected.
AIAPI AIErr(*	GetLayerByTitle )(AILayerHandle *layer, const ai::UnicodeString &title)
	Retrieves a layer by title.
AIAPI AIErr(*	LayerHasArt )(AILayerHandle layer, AIBoolean *hasArt)
	Reports whether a layer contains objects other than sublayers.
AIAPI AIErr(*	LayerHasSelectedArt )(AILayerHandle layer, AIBoolean *hasSel)
	Reports whether a layer contains any selected artwork.
AIAPI AIErr(*	DeselectArtOnLayer )(AILayerHandle layer)
	Deselects all objects on a layer.
AIAPI AIErr(*	SelectArtOnLayer )(AILayerHandle layer)
	Selects all objects on a layer that can be selected.
AIAPI AIErr(*	GetLayerIsTemplate )(AILayerHandle layer, AIBoolean *isTemplate)
	Reports whether a layer is a template layer.
AIAPI AIErr(*	SetLayerIsTemplate )(AILayerHandle layer, AIBoolean isTemplate)
	Sets whether a layer is a template layer.
AIAPI AIErr(*	GetPrevLayer )(AILayerHandle next, AILayerHandle *prev)
	Retrieves the layer above a given layer in the stacking order.
AIAPI AIErr(*	GetLayerDimmedPercent )(AILayerHandle layer, ai::int32 *percent)
	Retrieves the dimming factor used for drawing images when a layer is set to be dimmed.
AIAPI AIErr(*	SetLayerDimmedPercent )(AILayerHandle layer, ai::int32 percent)
	Sets the dimming factor used for drawing images when a layer is set to be dimmed.
AIAPI AIErr(*	GetLayerFirstChild )(const AILayerHandle layer, AILayerHandle *child)
	Retrieves the first child sublayer of a layer.
AIAPI AIErr(*	GetLayerParent )(const AILayerHandle layer, AILayerHandle *parent)
	Retrieves the parent of a layer.
AIAPI AIErr(*	InsertLayerAtArt )(const AIArtHandle art, AIPaintOrder paintOrder, AILayerHandle *newLayer)
	Inserts a new layer into a document at a paint-order position relative to an art object.
AIAPI AIErr(*	ChangeLayerToGroup )(const AILayerHandle layer, const AIArtHandle group)
	Converts a sublayer of this layer to a simple group.
AIAPI AIErr(*	GetNextPreorderLayer )(AILayerHandle prev, AILayerHandle *next)
	Retrieves the next layer in preorder traversal, which finds descendents first, then siblings.
AIAPI AIErr(*	GetNextNonChildPreorderLayer )(AILayerHandle prev, AILayerHandle *next)
	Retrieves the next layer in preorder traversal, skipping descendents and returning only sibling layers.

Detailed Description

The artwork in an Illustrator document is contained within layers.

The document has a stack of lists of layers. The topmost list of layers in the stack are the ones currently being edited. See the AILayerListSuite.

Each layer contains a group of objects, which can include sublayers. All documents begin with at least one layer, and the user or a plug-in can add any number of new layers to it. A layer is a container for an artwork tree; use AIArtSuite::GetFirstArtOfLayer() to get the group of art objects belonging to a layer.

In addition to containing artwork, a layer has a name, a color (used to indicate selected art), and state flags that indicate whether it is visible, editable or locked, printable, and whether it displays placed art as dimmed. A layer reference is opaque; use the functions in this suite to get and set layer properties.

Several layer properties affect whether the artwork on the layer is editable. Normally objects on a non-editable layer cannot be selected, so plug-ins that operate on the current selection need not check. However, in iterating through layers or artwork, call GetLayerEditable() on each layer before attempting to make any changes to the artwork.

A layer can be designated as a template layer, which contains template artwork being used to guide the construction of the document artwork. For example, a template might contain an image that is being traced. Template layers are never printed or exported to final-form file formats.

There are four notifiers associated with layers:
kAICurrentLayerNotifier
kAILayerDeletionNotifier
kAILayerSetNotifier
kAILayerOptionsNotifier

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAILayerSuite and kAILayerVersion.

Member Data Documentation

AIAPI AIErr(* AILayerSuite::ChangeLayerToGroup)(const AILayerHandle layer, const AIArtHandle group)

Converts a sublayer of this layer to a simple group.

You must ensure that the sublayer has no child layers that would be orphaned by removing the layer information.

Parameters:

	layer	The layer object for the sublayer, or `NULL` if you pass the group object.
	group	The art group object associated with the sublayer, or `NULL` if you pass the layer object.

AIAPI AIErr(* AILayerSuite::CountLayers)(ai::int32 *count)

Gets the number of top-level layers in the current document layer list.

Use with GetNthLayer() to iterate through a document's layers.

Parameters:

count

[out] A buffer in which to return the number of layers, or 0 if there is no current document.

AIAPI AIErr(* AILayerSuite::DeleteLayer)(AILayerHandle layer)

Removes a layer and all of its contained art from the current document.

Parameters:

layer

The layer.

Returns:: An error kCantDeleteLastLayerErr if layer is the only layer in the document.

AIAPI AIErr(* AILayerSuite::DeselectArtOnLayer)(AILayerHandle layer)

Deselects all objects on a layer.

Parameters:

layer

The layer.

AIAPI AIErr(* AILayerSuite::GetCurrentLayer)(AILayerHandle *layer)

Retrieves a reference to the current layer in the current document.

This is the layer on which new artwork is created by default. It is indicated in the Layers palette by a black triangle.

Parameters:

layer

[out] A buffer in which to return the layer.

AIAPI AIErr(* AILayerSuite::GetFirstLayer)(AILayerHandle *first)

Retrieves the topmost layer of the current document layer list.

Use with GetNextLayer to iterate through layers.

Parameters:

first

[out] A buffer in which to return the layer.

See also:: GetNextLayer(), GetPrevLayer()

AIAPI AIErr(* AILayerSuite::GetLayerByTitle)(AILayerHandle *layer, const ai::UnicodeString &title)

Retrieves a layer by title.

The layer can be top-level or a sublayer.

Parameters:

	layer	[out] A buffer in which to return the layer.
	title	The title string.

AIAPI AIErr(* AILayerSuite::GetLayerColor)(AILayerHandle layer, AIRGBColor *color)

Retrieves the color used when outlining selected artwork in a layer.

Parameters:

	layer	The layer.
	color	[out] A buffer in which to return the color.

AIAPI AIErr(* AILayerSuite::GetLayerDimmedPercent)(AILayerHandle layer, ai::int32 *percent)

Retrieves the dimming factor used for drawing images when a layer is set to be dimmed.

Parameters:

	layer	The layer.
	percent	[out] A buffer in which to return the dimming factor, in the range [0..100] where 0 in no dimming, and 100 is maximum dimming.

AIAPI AIErr(* AILayerSuite::GetLayerDimPlacedImages)(AILayerHandle layer, AIBoolean *dimmed)

Reports whether images in a layer are dimmed (colors shifted toward white) when rendering.

If a parent layer specifies dimming, images in sublayers are dimmed regardless of the sublayer setting.

Parameters:

	layer	The layer.
	dimmed	[out] A buffer in which to return true if this layer is dimmed; false if it is not.

AIAPI AIErr(* AILayerSuite::GetLayerEditable)(AILayerHandle layer, AIBoolean *editable)

Reports whether a layer is editable or locked.

When a layer is editable, its artwork can be created or modified. If a parent layer is not editable, art in all sublayers cannot be edited, regardless of the sublayer settings.

Parameters:

	layer	The layer.
	editable	[out] A buffer in which to return true if this layer is editable; false if it is locked.

AIAPI AIErr(* AILayerSuite::GetLayerFirstChild)(const AILayerHandle layer, AILayerHandle *child)

Retrieves the first child sublayer of a layer.

Parameters:

	layer	The layer.
	child	[out] A buffer in which to return the sublayer, or NULL if there are no sublayers.

AIAPI AIErr(* AILayerSuite::GetLayerIsTemplate)(AILayerHandle layer, AIBoolean *isTemplate)

Reports whether a layer is a template layer.

All sublayers of a template layer are also template layers.

Parameters:

	layer	The layer.
	isTemplate	[out] A buffer in which to return true if this layer is a template layer; false if it is not.

AIAPI AIErr(* AILayerSuite::GetLayerParent)(const AILayerHandle layer, AILayerHandle *parent)

Retrieves the parent of a layer.

Parameters:

	layer	The layer.
	parent	[out] A buffer in which to return the parent, or NULL if there is no parent.

AIAPI AIErr(* AILayerSuite::GetLayerPreview)(AILayerHandle layer, AIBoolean *preview)

Reports whether a layer specifies preview or outline mode.

If a parent layer specifies outline mode, art in all sublayers is rendered in outline mode regardless of the sublayer settings.

Parameters:

	layer	The layer.
	preview	[out] A buffer in which to return true if this layer specifies preview mode; false if it specifies outline mode.

AIAPI AIErr(* AILayerSuite::GetLayerPrinted)(AILayerHandle layer, AIBoolean *printed)

Reports whether this layer is considered printable when printing the document.

You can print all layers, visible layers or printable, visible layers.

Parameters:

	layer	The layer.
	printed	[out] A buffer in which to return true if this layer is printable; false if it is not.

AIAPI AIErr(* AILayerSuite::GetLayerSelected)(AILayerHandle layer, AIBoolean *selected)

Reports whether a layer is selected.

Parameters:

	layer	The layer.
	selected	[out] A buffer in which to return true if this layer is selected; false if it is not.

Note:: This function is provided for backward compatibility with Illustrator 6.0.

AIAPI AIErr(* AILayerSuite::GetLayerTitle)(AILayerHandle layer, ai::UnicodeString &title)

Retrieves the name of a layer.

Parameters:

	layer	The layer.
	title	[out] A buffer in which to return the name.

AIAPI AIErr(* AILayerSuite::GetLayerVisible)(AILayerHandle layer, AIBoolean *visible)

Reports the visibility status of a layer, which affects whether the artwork is drawn.

If a parent layer's visibility status is false, artwork of a sublayer is not drawn, even if the sublayer's visibility status is true.

Parameters:

	layer	The layer.
	visible	[out] A buffer in which to return the output as true if art in this layer is visible.

AIAPI AIErr(* AILayerSuite::GetNextLayer)(AILayerHandle prev, AILayerHandle *next)

Retrieves the next layer below a given layer in the stacking order, at the same level of the layer list stack.

Does not descend into sublayers.

Parameters:

	prev	The previous layer, or `NULL` to get the topmost layer.
	next	[out] A buffer in which to return the next layer, or `NULL` if there are no more layers.

See also:: GetFirstLayer(), GetPrevLayer()

AIAPI AIErr(* AILayerSuite::GetNextNonChildPreorderLayer)(AILayerHandle prev, AILayerHandle *next)

Retrieves the next layer in preorder traversal, skipping descendents and returning only sibling layers.

Use this to iterate through layers and their parent layers.

Parameters:

	prev	The previous layer.
	next	[out] A buffer in which to return the next layer, or `NULL` if there are no more layers.

See also:: GetFirstLayer(), GetNextPreorderLayer()

AIAPI AIErr(* AILayerSuite::GetNextPreorderLayer)(AILayerHandle prev, AILayerHandle *next)

Retrieves the next layer in preorder traversal, which finds descendents first, then siblings.

Use this to iterate through layers and their sublayers.

Parameters:

	prev	The previous layer.
	next	[out] A buffer in which to return the next layer, or `NULL` if there are no more layers.

See also:: GetFirstLayer(), GetNextNonChildPreorderLayer()

AIAPI AIErr(* AILayerSuite::GetNthLayer)(ai::int32 n, AILayerHandle *layer)

Retrieves a top-level layer by index from the current document.

Use with CountLayers() to iterate through a document�s layers. The layer with index 0 is the topmost layer in the stacking order.

Parameters:

	n	The index, in the range [0..numLayers-1]. If `n` is greater than the number of layers, an error is returned and `layer` is set to `NULL`.
	layer	[out] A buffer in which to return the layer, or `NULL` if the index is out of range.

Note:: It is more efficient to iterate layers using GetFirstLayer() and GetNextLayer().

AIAPI AIErr(* AILayerSuite::GetPrevLayer)(AILayerHandle next, AILayerHandle *prev)

Retrieves the layer above a given layer in the stacking order.

Does not descend into sublayers.

Parameters:

	next	The given layer.
	prev	[out] A buffer in which to return the previous layer, or `NULL` if there are no more layers.

Returns:: The error kNotImplementedErr if next is in a sublayer.

See also:: GetFirstLayer(), GetNextLayer()

AIAPI AIErr(* AILayerSuite::InsertLayer)(AILayerHandle layer, ai::int16 paintOrder, AILayerHandle *newLayer)

Adds a new layer to a document, inserting it into the layers' lists at a position in the paint order relative to an existing layer.

Parameters:

	layer	The prepositional layer for `paintOrder` values `kPlaceAbove` and `kPlaceBelow`, or `NULL` for values `kPlaceAboveAll` (inserts at 0) and `kPlaceBelowAll` (inserts at `count`).
	paintOrder	The paint order, relative to the `layer` object, an `AITypes::AIPaintOrder` value. See `AIArtSuite::NewArt()`.
	newLayer	[out] A buffer in which to return the new layer.

See also:: InsertLayerAtArt()

AIAPI AIErr(* AILayerSuite::InsertLayerAtArt)(const AIArtHandle art, AIPaintOrder paintOrder, AILayerHandle *newLayer)

Inserts a new layer into a document at a paint-order position relative to an art object.

Parameters:

	art	The art object.
	paintOrder	The paint order, relative to the `art` object, an `AITypes::AIPaintOrder` value. See `AIArtSuite::NewArt()`. The position must be appropriate for adding a layer; that is, at the top level or such that the resulting parent is a layer.
	newLayer	[out] A buffer in which to return the new layer.

See also:: InsertLayer()

AIAPI AIErr(* AILayerSuite::LayerHasArt)(AILayerHandle layer, AIBoolean *hasArt)

Reports whether a layer contains objects other than sublayers.

Parameters:

	layer	The layer.
	hasArt	[out] A buffer in which to return true if this layer contains art objects; false if it does not.

AIAPI AIErr(* AILayerSuite::LayerHasSelectedArt)(AILayerHandle layer, AIBoolean *hasSel)

Reports whether a layer contains any selected artwork.

Parameters:

	layer	The layer.
	hasSel	[out] A buffer in which to return true if this layer contains selected art; false if it does not.

AIAPI AIErr(* AILayerSuite::SelectArtOnLayer)(AILayerHandle layer)

Selects all objects on a layer that can be selected.

Parameters:

layer

The layer.

AIAPI AIErr(* AILayerSuite::SetCurrentLayer)(AILayerHandle layer)

Makes a layer current.

The current layer is the one in which new artwork is created by default. It is indicated in the Layers palette by a black triangle.

Parameters:

layer

The layer.

AIAPI AIErr(* AILayerSuite::SetLayerColor)(AILayerHandle layer, AIRGBColor color)

Sets the color used when outlining selected artwork in a layer.

Parameters:

	layer	The layer.
	color	The new color.

AIAPI AIErr(* AILayerSuite::SetLayerDimmedPercent)(AILayerHandle layer, ai::int32 percent)

Sets the dimming factor used for drawing images when a layer is set to be dimmed.

Parameters:

	layer	The layer.
	percent	The dimming factor, in the range [0..100] where 0 in no dimming, and 100 is maximum dimming.

AIAPI AIErr(* AILayerSuite::SetLayerDimPlacedImages)(AILayerHandle layer, AIBoolean dimmed)

Sets whether images in a layer are dimmed (colors shifted toward white) when rendering.

If a parent layer specifies dimming, images in sublayers are dimmed regardless of the sublayer setting.

Parameters:

	layer	The layer.
	dimmed	True to dim images, false to turn dimming off.

AIAPI AIErr(* AILayerSuite::SetLayerEditable)(AILayerHandle layer, AIBoolean editable)

Sets whether a layer is editable or locked.

When a layer is editable, its artwork can be created or modified. If a parent layer is not editable, art in all sublayers cannot be edited, regardless of the sublayer settings.

Parameters:

	layer	The layer.
	editable	True to make this layer is editable, false to lock it.

AIAPI AIErr(* AILayerSuite::SetLayerIsTemplate)(AILayerHandle layer, AIBoolean isTemplate)

Sets whether a layer is a template layer.

All sublayers of a template layer are also template layers.

Parameters:

	layer	The layer.
	isTemplate	True to make this a template layer, false to not make it a template layer.

AIAPI AIErr(* AILayerSuite::SetLayerPreview)(AILayerHandle layer, AIBoolean preview)

Sets a layer to preview mode or outline mode.

If a parent layer specifies outline mode, art in all sublayers is rendered in outline mode regardless of the sublayer settings.

Parameters:

	layer	The layer.
	preview	True to set preview mode, false to set outline mode.

AIAPI AIErr(* AILayerSuite::SetLayerPrinted)(AILayerHandle layer, AIBoolean printed)

Sets whether this layer is considered printable when printing the document.

You can print all layers, visible layers or printable, visible layers.

Parameters:

	layer	The layer.
	printed	True to make this layer printable, false to turn printability off.

AIAPI AIErr(* AILayerSuite::SetLayerSelected)(AILayerHandle layer, AIBoolean selected)

Sets whether a layer is selected.

Parameters:

	layer	The layer.
	selected	True to select this layer, false to deselect it.

Note:: This function is provided for backward compatibility with Illustrator 6.0.

AIAPI AIErr(* AILayerSuite::SetLayerTitle)(AILayerHandle layer, const ai::UnicodeString &newTitle)

Sets the name of a layer.

Parameters:

	layer	The layer.
	title	The new name.

AIAPI AIErr(* AILayerSuite::SetLayerVisible)(AILayerHandle layer, AIBoolean visible)

Sets the visibility status of a layer, which affects whether the artwork is drawn.

If a parent layer's visibility status is false, artwork of a sublayer is not drawn, even if the sublayer's visibility status is true.

Parameters:

	layer	The layer.
	visible	True to make art in this layer is visible, false to hide it.

The documentation for this struct was generated from the following file:

AILayer.h

AILayerSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AILayerSuite Struct Reference
[API Suite List]