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...

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.

Defines

#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.

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,
                                         void *exportParamBlock,
                                         int32 *data,
                                         int16 *result)
    {
        ...

        // Get the Property Suite from the parameter block
        propSuite = ((ExportRecordPtr)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 32 bit integer, 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.