Property Suite Callbacks

The Property suite allows a plug-in module to get and set certain values in the plug-in host. More...

Data Structures
struct	PropertyProcs
	The set of routines available in the Property Suite. More...
Defines
#define	kCurrentPropertyProcsVersion   1
	Current version of the Property Suite.
#define	kPIPropertySuite   "Photoshop Property Suite for Plug-ins"
#define	kPIPropertySuiteVersion   kCurrentPropertyProcsVersion
#define	kCurrentPropertyProcsCount   ((sizeof(PropertyProcs) - offsetof(PropertyProcs, getPropertyProc)) / sizeof(void *))
	Current number of routines in the Property Suite.
Typedefs
typedef struct PropertyProcs	PropertyProcs
	The set of routines available in the Property Suite.
Property Suite Callbacks
typedef MACPASCAL OSErr(*	GetPropertyProc )(PIType signature, PIType key, int32 index, intptr_t *simpleProperty, Handle *complexProperty)
	Gets information about the document currently being processed.
typedef MACPASCAL OSErr(*	SetPropertyProc )(PIType signature, PIType key, int32 index, intptr_t simpleProperty, Handle complexProperty)
	Updates information in the plug-in host about the document currently being processed.

---

Detailed Description

The Property suite allows a plug-in module to get and set certain values in the plug-in host.

Properties are defined as either a 32 bit integer, simpleProperty, or a handle, complexProperty. Properties are identified by a signature and key, which form a pair to identify the property of interest. Some properties, like channel names and path names, are also indexed; you must supply the signature, key, and index (zero-based) to access or update these properties. For a list of keys, See Property Keys Recognized by Property Suite Callbacks. The property suite is available to all plug-ins.

Note:

The term property is used with two different meanings in this toolkit. Besides its use in the Property suite, the term is also a part of the PiPL data structure, documented in Cross Application Plug-in Development Resource Guide. There is no connection between PiPL properties and the Property suite.

The standard Property Suite is found as a pointer in the parameter blocks of the plug-in modules. You can access the routines within the Property Suite in the following manner:

    PropertyProcs *propSuite;

    DLLExport MACPASCAL void PluginMain (const int16 selector,
                                         ExportRecordPtr exportParamBlock,
                                         intptr_t* data,
                                         int16* result)
    {
        ...

        // Get the Property Suite from the parameter block
        propSuite = exportParamBlock->propertyProcs;

        // Get the value for the simple property propNumberOfPaths from Photoshop, 
        // return value goes in count.
        int32 *count;
        propSuite->getPropertyProc('8BIM', propNumberOfPaths, 0, count, nil);
        ...
    }

---

Define Documentation

#define kCurrentPropertyProcsVersion   1

Current version of the Property Suite.

#define kPIPropertySuite   "Photoshop Property Suite for Plug-ins"

Unique identifier for the Property Suite.

#define kPIPropertySuiteVersion   kCurrentPropertyProcsVersion

Version number for the Property Suite.

#define kCurrentPropertyProcsCount   ((sizeof(PropertyProcs) - offsetof(PropertyProcs, getPropertyProc)) / sizeof(void *))

Current number of routines in the Property Suite.

---

Typedef Documentation

typedef MACPASCAL OSErr(* GetPropertyProc)(PIType signature, PIType key, int32 index, intptr_t *simpleProperty, Handle *complexProperty)

Gets information about the document currently being processed.

Properties are returned as a intptr_t, simpleProperty, or a handle, complexProperty. In the case of a complex, handle based property, your plug-in is responsible for disposing the handle. Use the DisposePIHandleProc callback defined in the Handle suite.

Properties involving strings, such as channel names and path names, are returned in a Photoshop handle. The length of the handle and size of the string are obtained with GetPIHandleSizeProc. There is no length byte, nor is the string zero terminated.

Note:

This callback replaces the non-suite callback, which has been renamed getPropertyObsolete in the plug-in parameter blocks. The obsolete callback pointer is still correct, and is maintained for backwards compatibility.

Parameters:

signature	The host signature. The signature for Photoshop is '8BIM' (0x3842494D).
key	The key for the property you wish to get. See Property Keys Recognized by Property Suite Callbacks.
index	The index for the property you wish to get.
simpleProperty	[OUT] The returned value when the property is simple.
complexProperty	[OUT] The returned value when the property is complex.

typedef MACPASCAL OSErr(* SetPropertyProc)(PIType signature, PIType key, int32 index, intptr_t simpleProperty, Handle complexProperty)

Updates information in the plug-in host about the document currently being processed.

Parameters:

signature	The host signature. The signature for Photoshop is '8BIM' (0x3842494D).
key	The key for the property you wish to update. The plug-in can only set certain, modifiable properties See Property Keys Recognized by Property Suite Callbacks.
index	The index for the property you wish to update.
simpleProperty	The value to set if the property is simple.
complexProperty	The value to set if the property is complex.

typedef struct PropertyProcs PropertyProcs

The set of routines available in the Property Suite.