Progress Suite

The Progress Suite provides a set of routines that allows the plug-in control over the display of the progress bar. More...

Data Structures
struct	PSProgressSuite1
	The set of routines available in the Progress Suite. More...
struct	PSProgressSuite2
	The set of routines available in the Progress Suite. More...
Defines
#define	kPSProgressSuite   "Photoshop Progress Suite for Plug-ins"
	Unique identifier for the Progress Suite.
#define	kPSProgressSuiteVersion1   1
	Progress suite, version 1.
#define	kPSProgressSuiteVersion2   2
	Progress suite, version 2.
Typedefs
typedef SPErr(*	Progress_DoProgress )(const ASZString zs, SPErr(*proc)(void *), void *refCon)
	Performs the task defined by proc within a new progress scope.
typedef SPErr(*	Progress_DoForcedProgress )(const ASZString zs, SPErr(*proc)(void *), void *refCon)
	Performs the task defined by proc within a new progress scope.
typedef SPErr(*	Progress_DoTask )(real64 taskLength, SPErr(*proc)(void *), void *refCon)
	Sections off a portion of the unused progress bar for execution of the subtask defined by proc.
typedef SPErr(*	Progress_DoSegmentTask )(int32 segmentLength, int32 *done, int32 total, SPErr(*proc)(void *), void *refCon)
	Limits progress to a section of the progress bar based on executing segmentLength out of total steps.
typedef void(*	Progress_ChangeProgressText )(const ASZString zs)
	Changes the current text in the progress bar.
typedef SPErr(*	Progress_DoPreviewTask )(const char *selector, SPErr(*proc)(void *), void *refCon)
	Performs a task using the preview sniffing logic.
typedef SPErr(*	Progress_DoWatchTask )(SPErr(*proc)(void *), void *refCon)
	Runs a task with the watch cursor up.
typedef SPErr(*	Progress_DoSuspendedWatchTask )(SPErr(*proc)(void *), void *refCon)
	Runs a task without the watch cursor.
typedef void(*	Progress_ContinueWatchCursor )(void)

---

Detailed Description

The Progress Suite provides a set of routines that allows the plug-in control over the display of the progress bar.

The Progress Suite is available in Adobe Photoshop 5.0 and later.

Accessing the Suite

The Progress suite is referred to as:

  #define kPSProgressSuite          "Photoshop Progress Suite for Plug-ins"

The current version of the Progress suite:

  #define kPSProgressSuiteVersion2      2

The suite is acquired as follows:

  PSProgressSuite1 *sPSProgress;
  error = sSPBasic->AcquireSuite(kPSProgressSuite,
                                 kPSProgressSuiteVersion2,
                                 &sPSProgress);
  if (error) goto . . . //handle error

For PICA errors, see SPErrorCodes.h.

---

Define Documentation

#define kPSProgressSuite   "Photoshop Progress Suite for Plug-ins"

Unique identifier for the Progress Suite.

#define kPSProgressSuiteVersion1   1

Progress suite, version 1.

#define kPSProgressSuiteVersion2   2

Progress suite, version 2.

---

Typedef Documentation

typedef SPErr(* Progress_DoProgress)(const ASZString zs, SPErr(*proc)(void *), void *refCon)

Performs the task defined by proc within a new progress scope.

Call the task APIs to control progression of the progress bar.

Parameters:

proc	The procedure to execute as a task.
refCon	This data pointer gets passed through to proc

Returns:

The error code returned from proc.

typedef SPErr(* Progress_DoForcedProgress)(const ASZString zs, SPErr(*proc)(void *), void *refCon)

Performs the task defined by proc within a new progress scope.

Forces the progress bar to display always and immediately, ignoring the normal heuristics that keep it from showing unnecessarily (e.g. during very short tasks). Call the task APIs to control progression of the progress bar.

Parameters:

proc	The procedure to execute as a task.
refCon	This data pointer gets passed through to proc

Returns:

The error code returned from proc.

typedef SPErr(* Progress_DoTask)(real64 taskLength, SPErr(*proc)(void *), void *refCon)

Sections off a portion of the unused progress bar for execution of the subtask defined by proc.

Parameters:

taskLength	The length of the progress bar to section off. Should be between 0.0 and 1.0.
proc	The procedure to execute as a subtask.
refCon	This data pointer gets passed through to proc

Returns:

The error code returned from proc.

typedef SPErr(* Progress_DoSegmentTask)(int32 segmentLength, int32 *done, int32 total, SPErr(*proc)(void *), void *refCon)

Limits progress to a section of the progress bar based on executing segmentLength out of total steps.

Parameters:

segmentLength
done	[OUT] A counter of how much has been accomplished so far. This is incremented by segmentLength if the task succeeds. (We need done because, as with DoTask, we care about the percentage of the remaining progress bar.)
total	The total number of steps.
proc	The procedure to execute as a segment of a task.
refCon	This data pointer gets passed through to proc

Returns:

The error code returned from proc.

typedef void(* Progress_ChangeProgressText)(const ASZString zs)

Changes the current text in the progress bar.

Parameters:

zs	The text to display in the progress bar.

typedef SPErr(* Progress_DoPreviewTask)(const char *selector, SPErr(*proc)(void *), void *refCon)

Performs a task using the preview sniffing logic.

This aborts if Photoshop encounters an event that meets the conditions indicated by selector.

Parameters:

selector	The conditions that indicate when to abort the procedure. Should be one of the following: "up" Continue processing while mouse is up. Abort when mouse down or key stroke. "down" Continue processing while mouse is down. Abort when mouse is released. "paused" Continue processing while mouse is still. Abort when mouse is moved or released. NULL Causes the code to choose between "up" and "paused" dependent on the current mouse state.
proc	The procedure to execute..
refCon	This data pointer gets passed through to proc

Returns:

The error code returned from proc, or an error resulting from an invalid selector value.

typedef SPErr(* Progress_DoWatchTask)(SPErr(*proc)(void *), void *refCon)

Runs a task with the watch cursor up.

Parameters:

proc	The procedure to execute.
refCon

Returns:

The error code returned from proc.

typedef SPErr(* Progress_DoSuspendedWatchTask)(SPErr(*proc)(void *), void *refCon)

Runs a task without the watch cursor.

This doesn't actually take the watch cursor down, but it does keep the watch from spinning.

Parameters:

proc	The procedure to execute.
refCon	This data pointer gets passed through to proc

Returns:

The error code returned from proc.

typedef void(* Progress_ContinueWatchCursor)(void)