AIPathStyleSuite Struct Reference
[API Suite List]

This suite provides functions to access or set stroke and fill paint style information for art objects. More...

#include <AIPathStyle.h>

Public Attributes
AIAPI AIErr(*	GetPathStyle )(AIArtHandle path, AIPathStyle *style)
	Retrieves the path style used to fill and/or stroke a path art object.
AIAPI AIErr(*	SetPathStyle )(AIArtHandle path, const AIPathStyle *style)
	Sets the path style used to fill and/or stroke a path art object, if the object is one of these types: `kPathArt` `kCompoundPathArt` `kRasterArt` `kMeshArt` `kPlacedArt` `kTextFrameArt`.
AIAPI AIErr(*	GetCurrentPathStyle )(AIPathStyle style, AIPathStyleMap stylemap, AIDictionaryRef *advStrokeParams)
	Retrieves the common attributes of the current selected objects.
AIAPI AIErr(*	SetCurrentPathStyle )(AIPathStyle style, AIPathStyleMap stylemap, ConstAIDictionaryRef advStrokeParams)
	Applies a path style to any currently selected and paint-targeted objects.
AIAPI AIErr(*	ImportStyles )(const ai::FilePath &source, AIDocumentHandle *newdoc)
	Imports styles from a file, and creates a new document containing the styles.
AIAPI AIErr(*	ImportStylesMixedColorSpace )(const ai::FilePath &source, AIDocumentHandle *newdoc)
	Imports mixed-colorspace styles from a file, and creates a new document containing the styles.
AIAPI AIErr(*	SetObjectAIColor )(AIArtHandle art, const AIColor *color, AIBoolean onStroke)
	Applies a color to the stroke or fill of an art object.
AIAPI AIErr(*	PathStyleUsesAIColor )(const AIPathStyle pathStyle, const AIPathStyleMap psMap, const AIColor color, AIBoolean matchTint, AIBoolean lookForIndirectUsage, AIColorUsedHow usage)
	Reports whether and how a path style makes use of a specific color in its fill or stroke.
AIAPI AIErr(*	ApplyAIColorToPathStyle )(AIPathStyle pathStyle, AIPathStyleMap psMap, const AIColor newColor, const AIColor matchColor, AIBoolean onStroke, AIBoolean useOldTint, AIArtHandle destination, AIColorUsedHow *whatChanged)
	Applies a color to a path style in a typical way, as for the Swatch palette.
AIAPI AIErr(*	ObjectUsesAIColor )(AIArtHandle art, const AIColor targetColor, AIBoolean matchTint, AIBoolean lookForIndirectUsage, AIColorUsedHow usage)
	Reports whether and how an art object uses a color.
AIAPI AIErr(*	ReplaceObjectAIColor )(AIArtHandle art, const AIColor oldColor, const AIColor newColor, AIBoolean useOldTint, AIBoolean *madeReplacement)
	Replaces one color with another in an art object.
AIAPI AIErr(*	GetInitialPathStyle )(AIPathStyle *style)
	Retrieves the default path style that tools should use when creating new objects other than text objects.
AIAPI AIErr(*	SetInitialPathStyle )(const AIPathStyle *style)
	Sets the default path style that tools should use when creating new objects other than text objects.
AIAPI AIErr(*	GetInitialTextStyle )(AIPathStyle *style)
	Retrieves the default path style that tools should use when creating text objects.
AIAPI AIErr(*	SetInitialTextStyle )(const AIPathStyle *style)
	Sets the default path style that tools should use when creating text objects.
AIAPI AIErr(*	RetargetForCurrentDoc )(AIColor *color)
	Makes a color appropriate for the artwork in the current document.
AIAPI AIErr(*	SetCurrentPathStyleForceSimple )(AIPathStyle style, AIPathStyleMap stylemap)
	Applies a path style to any currently selected and paint-targeted objects.
AIAPI AIErr(*	SetPathStyleForceSimple )(AIArtHandle path, const AIPathStyle *style)
	Applies a path style to a path object.
AIAPI AIErr(*	InterpolatePathStyle )(const AIPathStyle style0, const AIPathStyle style1, AIPathStyle *styleOut, AIReal percent)
	Interpolates a new style between two path styles.
AIAPI AIErr(*	InterpolateAIColor )(const AIColor color0, const AIColor color1, AIColor *colorOut, AIReal fraction)
	Interpolates a color between two colors.
AIAPI AIErr(*	SetSyncInitialPathStyle )(AIBoolean syncInitialPathStyle)
	Sets the synchronization state for the initial path style.
AIAPI AIBoolean(*	GetSyncInitialPathStyle )()
	Reports the synchronization state for the initial path style.
AIAPI AIErr(*	AdjustObjectAIColors )(AIArtHandle art, AIAdjustColorFunc adjustColorCallback, void clientData, VisitAIColorFlags controlFlags, AIBoolean madeReplacement)
	Examines or modifies colors in an object by calling a developer-defined callback function.
AIAPI AIErr(*	GetPathStyleEx )(AIArtHandle path, AIPathStyle style, AIBoolean fillVisible, AIBoolean *strokeVisible)
	Retrieves the path style used to fill and/or stroke a path art object and the visibility of fill and stroke.
AIAPI AIErr(*	SetPathStyleEx )(AIArtHandle path, const AIPathStyle *style, AIBoolean fillVisible, AIBoolean strokeVisible)
	Sets the path style used to fill and/or stroke a path art object and the visibility of fill and stroke, if the object is one of these types: `kPathArt` `kCompoundPathArt` `kRasterArt` `kMeshArt` `kPlacedArt` `kTextFrameArt`.
AIAPI AIErr(*	GetCurrentPathStyleEx )(AIPathStyle style, AIPathStyleMap stylemap, AIBoolean fillVisible, AIBoolean strokeVisible)
	Retrieves the common attributes of the current selected objects.
AIAPI AIErr(*	SetCurrentPathStyleEx )(AIPathStyle style, AIPathStyleMap stylemap, AIBoolean fillVisible, AIBoolean strokeVisible)
	Applies a path style to any currently selected and paint-targeted objects.

Detailed Description

This suite provides functions to access or set stroke and fill paint style information for art objects.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIPathStyleSuite and kAIPathStyleVersion.

Member Data Documentation

AIAPI AIErr(* AIPathStyleSuite::AdjustObjectAIColors)(AIArtHandle art, AIAdjustColorFunc adjustColorCallback, void *clientData, VisitAIColorFlags controlFlags, AIBoolean *madeReplacement)

Examines or modifies colors in an object by calling a developer-defined callback function.

Parameters:

	art	The art object, or `NULL` to iterate through the entire art tree of the current document.
	adjustColorCallback	The developer-defined callback procedure.
	clientData	Optional developer-defined data to pass through to the callback.
	controlFlags	Options for how colors are enumerated to the callback, a logical OR of `VisitAIColorFlagValues`.
	madeReplacement	[out] Optional, a buffer in which to return true if any colors were replaced.

Note:: You can use this to simply visit all the colors used in a document or in the selection, for static purposes such as building up a collection of colors or compiling statistics on them. You could iterate twice, once to collect statistics and again to make changes, for example to average colors or to posterize art based on a histogram of the colors that it uses.

AIAPI AIErr(* AIPathStyleSuite::ApplyAIColorToPathStyle)(AIPathStyle *pathStyle, AIPathStyleMap *psMap,const AIColor *newColor, const AIColor *matchColor, AIBoolean onStroke, AIBoolean useOldTint, AIArtHandle destination, AIColorUsedHow *whatChanged)

Applies a color to a path style in a typical way, as for the Swatch palette.

If the new color is a gradient or pattern, ignores its vector and transform. If the path style is of the same type, retains its vector and transform. Otherwise, uses default values.
If the new color is a spot color, uses the tint.
Uses reasonable defaults when changing from one kind of color to another (such as solid to pattern or gradient) or when assigning color to a fill or stroke that was previously unpainted.

Parameters:

	pathStyle	The full or partial path style. Modified in place.
	psMap	The map indicating which fields of the partial style contain valid values, or `NULL` for a full style.
	newColor	The new color.
	matchColor	Optional. If supplied, `onStroke` is ignored and the new color is applied to the stroke or fill that matches this color. Matching is exact, including color space. Never assigns paint to an unpainted stroke or fill unless the value is `kNoneColor`.
	onStroke	If `matchColor` is `NULL`, then when true, applies the new color to stroke, and when false, applies it to fill. To apply to both, you must call the function twice.
	useOldTint	When true, and the new color and match color are both custom colors, uses the tint from the match color. When false, uses the tint from the new color.
	destination	The art object that uses the style, Used if a bounding box is needed to calculate a gradient vector. If it is a compound path, calculates bounds from the entire compound group.
	whatChanged	[out] Optional. A buffer in which to return a structure indicating what part of the path style was changed.

AIAPI AIErr(* AIPathStyleSuite::GetCurrentPathStyle)(AIPathStyle *style, AIPathStyleMap *stylemap, AIDictionaryRef *advStrokeParams)

Retrieves the common attributes of the current selected objects.

Parameters:

	style	[out] A buffer in which to return the partial style containing the common attributes.
	stylemap	[out] A buffer in which to return the map indicating which fields of the partial style contain valid values.
	advStrokeParams	[out, optional] A pointer to a dictionary ref which may be created and populated with common advanced stroke parameters.

AIAPI AIErr(* AIPathStyleSuite::GetCurrentPathStyleEx)(AIPathStyle *style, AIPathStyleMap *stylemap, AIBoolean *fillVisible, AIBoolean *strokeVisible)

Retrieves the common attributes of the current selected objects.

Parameters:

	style	[out] A buffer in which to return the partial style containing the common attributes.
	stylemap	[out] A buffer in which to return the map indicating which fields of the partial style contain valid values.

AIAPI AIErr(* AIPathStyleSuite::GetInitialPathStyle)(AIPathStyle *style)

Retrieves the default path style that tools should use when creating new objects other than text objects.

Parameters:

style

[out] A buffer in which to return the path style.

AIAPI AIErr(* AIPathStyleSuite::GetInitialTextStyle)(AIPathStyle *style)

Retrieves the default path style that tools should use when creating text objects.

Parameters:

style

[out] A buffer in which to return the path style.

AIAPI AIErr(* AIPathStyleSuite::GetPathStyle)(AIArtHandle path, AIPathStyle *style)

Retrieves the path style used to fill and/or stroke a path art object.

Parameters:

	path	The art object.
	style	[out] A buffer in which to return the style.

Returns:: The error kBadParameterErr if the art object is not an allowed type.

AIAPI AIErr(* AIPathStyleSuite::GetPathStyleEx)(AIArtHandle path, AIPathStyle *style, AIBoolean *fillVisible, AIBoolean *strokeVisible)

Retrieves the path style used to fill and/or stroke a path art object and the visibility of fill and stroke.

Parameters:

	path	The art object.
	style	[out] A buffer in which to return the style.
	fillVisible	[out] A buffer in which to return true if fill is visible.
	strokeVisible	[out] A buffer in which to return true if stroke is visible.

Returns:: The error kBadParameterErr if the art object is not an allowed type.

AIAPI AIBoolean(* AIPathStyleSuite::GetSyncInitialPathStyle)()

Reports the synchronization state for the initial path style.

(Note that this function returns a boolean value, not an error code.)

Returns:: True if synchronization is on.

See also:: SetSyncInitialPathStyle()

AIAPI AIErr(* AIPathStyleSuite::ImportStyles)(const ai::FilePath &source, AIDocumentHandle *newdoc)

Imports styles from a file, and creates a new document containing the styles.

Use the AIArtStyleSuite and AISwatchListSuite to access the information. For instance, use AISwatchListSuite::GetSwatchList to import colors from the document.

Parameters:

	source	The file that contains the styles.
	newdoc	[out] A buffer in which to return the new document.

AIAPI AIErr(* AIPathStyleSuite::ImportStylesMixedColorSpace)(const ai::FilePath &source, AIDocumentHandle *newdoc)

Imports mixed-colorspace styles from a file, and creates a new document containing the styles.

Rarely needed; use only to allow a mixed colorspace in a swatch library. Mixed colorspaces are not allowed in artwork. (ImportStyles() always converts to a single colorspace.)

Parameters:

	source	The file that contains the styles.
	newdoc	[out] A buffer in which to return the new document.

AIAPI AIErr(* AIPathStyleSuite::InterpolateAIColor)(const AIColor *color0, const AIColor *color1, AIColor *colorOut, AIReal fraction)

Interpolates a color between two colors.

Parameters:

	color0	The first color.
	color1	The second color.
	colorOut	[out] A buffer in which to return the new color. If the colors are of incompatible types, such as two patterns, returns the first color.

See also:: AIPathInterpolateSuite

AIAPI AIErr(* AIPathStyleSuite::InterpolatePathStyle)(const AIPathStyle *style0, const AIPathStyle *style1, AIPathStyle *styleOut, AIReal percent)

Interpolates a new style between two path styles.

Parameters:

	style0	The first path style object.
	style1	The second path style object.
	styleOut	[out] A buffer in which to return the new path style.
	percent	The distance from the source styles. 0 to return the first style, 1 to return the second style, or an interpolation point between the two.

See also:: AIPathInterpolateSuite.

AIAPI AIErr(* AIPathStyleSuite::ObjectUsesAIColor)(AIArtHandle art, const AIColor *targetColor, AIBoolean matchTint, AIBoolean lookForIndirectUsage, AIColorUsedHow *usage)

Reports whether and how an art object uses a color.

Parameters:

	art	The art object. Can be of any type.
	targetColor	The color.
	matchTint	When false, the tint percentage for spot and global process colors is not considered.
	lookForIndirectUsage	When true, checks for a match inside patterns, gradients, and graph designs. When false, still checks inside the graph style change records of graph objects, but not in patterns, gradients, or graph designs.
	usage	[out] A buffer in which to return the result.

AIAPI AIErr(* AIPathStyleSuite::PathStyleUsesAIColor)(const AIPathStyle *pathStyle, const AIPathStyleMap *psMap, const AIColor *color, AIBoolean matchTint, AIBoolean lookForIndirectUsage, AIColorUsedHow *usage)

Reports whether and how a path style makes use of a specific color in its fill or stroke.

Parameters:

	pathStyle	The full or partial path style.
	psMap	The map indicating which fields of the partial style contain valid values, or `NULL` for a full style.
	color	The color.
	matchTint	When false, the tint percentage for spot and global process colors is not considered.
	lookForIndirectUsage	When true, and if the path style is a pattern, searches the pattern definition for the color.
	usage	[out] A buffer in which to return the result.

AIAPI AIErr(* AIPathStyleSuite::ReplaceObjectAIColor)(AIArtHandle art, const AIColor *oldColor, const AIColor *newColor, AIBoolean useOldTint, AIBoolean *madeReplacement)

Replaces one color with another in an art object.

For direct usage of the old color (that is, a stroke or fill, including inside graph path style change records), calls SetObjectAIColor() to set the new color. Does not replace indirectly used colors--that is, those inside patterns, gradients, or graph designs used by the art object.

You can replace pattern or gradient colors by defining a new pattern or gradient, then calling this function for the pattern or gradient object itself, with the new replacement object.

Parameters:

	art	The art object, or `NULL` to replace the color in all art in the current document. Can be any type except `kPlacedArt`, including those that are reported as `kMysteryPathArt` (paths inside text paths and graphs), and those that are reported as `kUnknownArt`, such as graphs and layer masks.
	oldColor	The color to replace.
	newColor	The new color.
	useOldTint	When true, and both colors are custom colors, uses the tint from the old color. When false, uses the tint from the new color.
	madeReplacement	[out] Optional. A buffer in which to return true if a replacement was made.

AIAPI AIErr(* AIPathStyleSuite::RetargetForCurrentDoc)(AIColor *color)

Makes a color appropriate for the artwork in the current document.

For example, if it uses a pattern that is not available, replaces it with an equivalent pattern that is available.

Parameters:

color

The color (typically from clipboard artwork).

AIAPI AIErr(* AIPathStyleSuite::SetCurrentPathStyle)(AIPathStyle *style, AIPathStyleMap *stylemap, ConstAIDictionaryRef advStrokeParams)

Applies a path style to any currently selected and paint-targeted objects.

For this function to apply, a targeted object must be a path or compound path, or have a style that already contains a fill or stroke. If a targeted object has an active style, the new style is merged into the focal fill and stroke filters. Any effects and non-focal fills and strokes remain unmodified.

Parameters:

	style	The new partial style.
	stylemap	The map indicating which fields of the partial style contain valid values.
	advStrokeParams	[optional] A dictionary ref containing advanced stroke parameters, may be null.

Note:: To completely replace active styles, use SetCurrentPathStyleForceSimple()

AIAPI AIErr(* AIPathStyleSuite::SetCurrentPathStyleEx)(AIPathStyle *style, AIPathStyleMap *stylemap, AIBoolean fillVisible, AIBoolean strokeVisible)

Applies a path style to any currently selected and paint-targeted objects.

For this function to apply, a targeted object must be a path or compound path, or have a style that already contains a fill or stroke. If a targeted object has an active style, the new style is merged into the focal fill and stroke filters. Any effects and non-focal fills and strokes remain unmodified.

Parameters:

	style	The new partial style.
	stylemap	The map indicating which fields of the partial style contain valid values.
	fillVisible	True if fill should be visible.
	strokeVisible	True if stroke should be visible.

Note:: To completely replace active styles, use SetCurrentPathStyleForceSimple()

AIAPI AIErr(* AIPathStyleSuite::SetCurrentPathStyleForceSimple)(AIPathStyle *style, AIPathStyleMap *stylemap)

Applies a path style to any currently selected and paint-targeted objects.

For this function to apply, a targeted object must be a path or compound path, or have a style that already contains a fill or stroke. When a selected object has an active style, merges the input style values only with the paint attributes, and gives the object that simple style. Compare SetCurrentPathStyle().

Parameters:

	style	The new partial style, or `NULL` to replace all selected active styles with the simple style corresponding to their focal fill and/or stroke filters.
	stylemap	The map indicating which fields of the partial style contain valid values, or `NULL` if style is not supplied.

AIAPI AIErr(* AIPathStyleSuite::SetInitialPathStyle)(const AIPathStyle *style)

Sets the default path style that tools should use when creating new objects other than text objects.

Parameters:

style

The new path style.

AIAPI AIErr(* AIPathStyleSuite::SetInitialTextStyle)(const AIPathStyle *style)

Sets the default path style that tools should use when creating text objects.

Parameters:

style

The new path style.

AIAPI AIErr(* AIPathStyleSuite::SetObjectAIColor)(AIArtHandle art, const AIColor *color, AIBoolean onStroke)

Applies a color to the stroke or fill of an art object.

Generally does what you would want to do when applying a color. It sets the gradient vector to the default, handles compound paths, and so on. For example, if you have an object that is stroked with a dashed line and you pass in a new color with onStroke true, the old dash pattern is retained. If the object did not have a stroke before, the function looks for one in the current paint style. If the current paint style does not have a stroke, it uses a sensible default.

Parameters:

	art	The art object.
	color	The new color.
	onStroke	True to apply the color only to strokes, false to apply only to fill.

Note:: The function enumerates container objects. Do not call on both a container and its children.

AIAPI AIErr(* AIPathStyleSuite::SetPathStyle)(AIArtHandle path, const AIPathStyle *style)

Sets the path style used to fill and/or stroke a path art object, if the object is one of these types:
kPathArt
kCompoundPathArt
kRasterArt
kMeshArt
kPlacedArt
kTextFrameArt.

For group types, (kGroupArt, kPluginArt, kSymbolArt), modifies the existing fill or stroke. If there is no existing fill or stroke value, has no effect. Use the AIArtStyleSuite to add a new fill or stroke to a group object.

Parameters:

	path	The art object.
	style	The new style.

Returns:: The error kBadParameterErr if the art object is not an allowed type (kForeignArt, kLegacyTextArt, kUnknownArt).

AIAPI AIErr(* AIPathStyleSuite::SetPathStyleEx)(AIArtHandle path, const AIPathStyle *style, AIBoolean fillVisible, AIBoolean strokeVisible)

Sets the path style used to fill and/or stroke a path art object and the visibility of fill and stroke, if the object is one of these types:
kPathArt
kCompoundPathArt
kRasterArt
kMeshArt
kPlacedArt
kTextFrameArt.

For group types, (kGroupArt, kPluginArt, kSymbolArt), modifies the existing fill or stroke. If there is no existing fill or stroke value, has no effect. Use the AIArtStyleSuite to add a new fill or stroke to a group object.

Parameters:

	path	The art object.
	style	The new style.

Returns:: The error kBadParameterErr if the art object is not an allowed type (kForeignArt, kLegacyTextArt, kUnknownArt).

AIAPI AIErr(* AIPathStyleSuite::SetPathStyleForceSimple)(AIArtHandle path, const AIPathStyle *style)

Applies a path style to a path object.

When the path has an active style, merges the input style values only with the paint attributes, and gives the object that simple style. Compare SetPathStyle().

Parameters:

	path	The path object.
	style	The new style, or `NULL` to replace the active style with the simple style corresponding to the focal fill and/or stroke filters.

AIAPI AIErr(* AIPathStyleSuite::SetSyncInitialPathStyle)(AIBoolean syncInitialPathStyle)

Sets the synchronization state for the initial path style.

When synchronization is on (which it usually is) Illustrator synchronizes the initial path style with the current path style whenever the selection changes, and when calls are made to GetCurrentPathStyle(), SetCurrentPathStyle(), GetInitialPathStyle() or SetInitialPathStyle(). The Swatches palette, Color palette, and Toolbox all show the current path style.

When synchronization is off, the initial path style and the current path style become independent. In this mode, getting or setting the current path style does not affect the initial path style, and getting or setting the initial path style does not affect the current path style or the current selection. The palettes and Toolbox show the initial path style rather than the current path style.

Parameters:

syncInitialPathStyle

True to turn synchronization on, false to turn it off.

Note:: You might want to maintain a tool-specific style that is not modified when the selection changes. This allows the user to have a selection, choose a specific tool and color, and not have the color apply to the current selection. This is used by the paintbucket tool, for example. To get this behavior, turn synchronization off, then get and set the initial style (rather than the current style) while the tool is selected.

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

AIPathStyle.h

AIPathStyleSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIPathStyleSuite Struct Reference
[API Suite List]