Plug-In Interaction with ACDSee

This section will describe the general ways that ACDSee interacts with your plug-in. This will include the general Load/Unload workflow, as well as plug-in type-specific workflows.

After a plug-in is loaded, and before any other function is called, the Init function will be callled by ACDSee. For instance, after ACDSee loads a Command Extension plug-in, it must call CX_Init before it will call any other function.

After the Init function is called, ACDSee will also call the GetPlugInInfo function to determine what kinds of files, filters, etc. the plug-in supports. Additionally, if a plug-in has exported the Free function, then ACDSee will call it just before it unloads the plug-in, as long as Init has also been called.

As an example, suppose ACDSee wants to use a filter plug-in to apply a filter to an image. The first two functions called would be IF_Init and IF_GetPlugInInfo. The last function call would be IF_Free.

There are some functions that are common across all plug-in types which may be called at any time during plug-in execution. They are: ErrorHandler, Help, and ShowPlugInDialog. These are for handling plug-in errors, showing a help document for the plug-in, and showing an about/settings dialog for the plug-in.

Here is an example usage of a plug-in:

• The ACDSee initializes the plug-in, as described above.
• The user wants to see an "About" dialog for the plug-in, so ACDSee calls ID_ShowPlugInDialog.
• ACDSee starts decoding an image through the plug-in, but the plug-in returns a plug-in-defined error code. So ACDSee calls ID_GetError to retrieve a string describing the error.
• The plug-in causes an unhandled exception, so ACDSee calls ID_ErrorHandler to let the plug-in alert the user to the crash.
• The user wants to see help for the plug-in, so ACDSee calls ID_Help.
• Finally, ACDSee calls ID_Free before it unloads the plug-in.

Below are some type-specific call orders for each type of plug-in. It is assumed that the appropriate initialization functions have been called in each of the examples. (See above.)

Command Extension

Invoke a plug-in command:

CX_InvokeCommand

The host usually passes user input to the plug-in until the function returns.

 

Image Decoding

Decode an image with metadata:

ID_OpenImage	Opens the image.
ID_GetImageInfo	Retrieves information about the image.
ID_GetPageInfo	Obtains page-specific information.
ID_PageDecodeStart	Starts decoding the image.
ID_PageDecodeStep	Calls until the image is fully decoded.
ID_PageDecodeStop	Calls when the image has been decoded.
ID_GetMetadata	Retrieves image metadata.
ID_CloseImage	Closes the image.
ID_FreeMetadata	The plug-in should free the memory allocated during ID_GetMetadata.

 

Image Encoding

Get pixel formats:

IE_GetValidPixelFormats

Gets the valid pixel formats for a supported image format.

 

Encode an image:

IE_GetDefaultEncodeParams	Obtains default encoding parameters for the image format to be written to.
IE_ShowEncodeParamsDialog	Instructs the plug-in to show a dialog allowing the user to customize encoding parameters.
IE_ImageEncodeStart	Starts encoding the image.
IE_ImageEncodePage	Calls each time a page should be encoded.
IE_ImageEncodeFinish	Finishes encoding the image.

 

Image Filter

Invoke a filter from ACDSee's GUI:

IF_RunFilter

Invokes a plug-in filter from ACDSee's UI.

 

Invoke a plug-in filter from a menu while (optionally) recording an action:

IF_RunMenuFilter	Plug-in creates its own UI in a modal dialog. User sets parameters. User finishes with the plug-in UI and the filter is run on the image. Plug-in returns selected parameters to ACDSee.
IF_FreeAllocatedParams	Plug-in frees the parameter array it returned in the previous function call.

 

ACDSee Actions playback:

IF_RunMenuFilterAction

Called during action playback. Plug-in runs the specified filter using a copy of the parameter array it returned from IF_RunMenuFilter.

See also:

• Plug-In API Overview