If possible, use kAVCommandKeyBaseFileNameASText instead.

An AVCommand represents an action that the user can perform on the current document or the current selection in the current document. Specifically, an AVCommand represents a command which can be added to a command sequence and executed either interactively or via batch processing.

See Also

See Also

A set of callbacks that perform the actions required of a command.

Stop working and clean up as though the command executed to completion.

See Also

Called after a command is created. The command handler can establish default parameters and so forth for the newly created command.

See Also

Called before a command is destroyed. The command handler should free any memory allocated by the command.

See Also

Retrieves a cabinet from a command. It is used in the GetParams and GetProps members of the AVCommandHandlerRec structure. When retrieving command parameters, the handler should first remove any existing items from theCab using ASCabMakeEmpty(), and then copy all parameter values from the command into theCab. When retrieving properties, the command handler should replace any entries in theCab with key names it recognizes with copies of the command-specific properties.

Every command in a sequence has its Postflight command callback called after all commands in a given sequence have been executed but before the file is closed.

Preflights and Postflights are good for getting user data or preparing the command at the beginning of the sequence. For example, you could use the Preflight to ask what password the 'Add Security' command should use. This is important since you only want to ask once (not for every file), and you do not want to store the password in the sequence file (or the command's persistent parameters).

See AVCommandPreflightSequenceProc() for the order in which the AVCommand Pre/Postflight callbacks are called.

Every command in a sequence has its Postflight command callback called after the sequence is executed.

Preflights and Postflights are good for getting user data or preparing the command at the beginning of the sequence. For example, you could use the Preflight to ask what password the 'Add Security' command should use. This is important since you only want to ask once (not for every file), and you do not want to store the password in the sequence file (or the command's persistent parameters).

See AVCommandPreflightSequenceProc() for the order in which the AVCommand Pre/Postflight callbacks are called.

Every command in a sequence has its Preflight callback called after each file has been opened to be processed but before any commands have been executed on that file. If any of the Preflight callbacks returns an error, the sequence is aborted.

Preflights and Postflights are good for getting user data or preparing the command at the beginning of the sequence. For example, you could use the Preflight to ask what password the 'Add Security' command should use. This is important since you only want to ask once (not for every file), and you do not want to store the password in the sequence file (or the command's persistent parameters).

See AVCommandPreflightSequenceProc() for the order in which the AVCommand Pre/Postflight callbacks are called.

Every command in a sequence has its Preflight callback called before the sequence is executed. If any of the Preflight callbacks returns an error, the sequence is aborted.

Preflights and Postflights are good for getting user data or preparing the command at the beginning of the sequence. For example, you could use the Preflight to ask what password the 'Add Security' command should use. This is important since you only want to ask once (not for every file), and you do not want to store the password in the sequence file (or the command's persistent parameters).

• Sequence Begins

• AVCommandPreflightSequenceProc() for all commands are called

• Open File # 1

• AVCommandPreflightFileProcs() for all commands are called

• Execute all commands on given file

• AVCommandPostflightFileProcs for all commands are called

• Close File # 1

• Open File # 2

• ... (repeat pre/post file procs)

• Close last file

• AVCommandPostflightSequenceProcs for all commands are called.

• Sequence ends

Stops working, clears any errors, and tries to get back into a Ready state. For many commands this is equivalent to cancelling.

See Also

Called to set a cabinet within a command. It is used in the SetParams member of the AVCommandHandlerRec structure. The command handler should copy any information from the cabinet into the command. It must not destroy or modify the cabinet.

See Also

Displays the command's parameter setting dialog box and allows the user to alter the parameters.

Do some work. If it does not finish its work, return kAVCommandWorking. If it does finish its work, return kAVCommandDone. If the user cancels the operation, return kAVCommandCanceled. If an error occurs, return kAVCommandInError.

In most cases this method performs its work until it returns kAVCommandDone, but in some cases it may be called on to cancel or reset before its work is done.

See Also

Cancels the specified command. If the command is currently processing a file, the command might not attempt to roll back any modifications it has made to the document. This may leave the PDF in an invalid state.

Parameters

See Also

Since

Destroys the specified command and its associated resources.

Parameters

See Also

Since

Runs the specified AVCommand, after it has been set up using AVCommandSetInputs() and AVCommandSetParams().

The method runs the command using the following process:

• Reset the command if its status is not AVCommandReady.

• If only a PDDoc input has been configured, AVCommandExecute() does nothing to the inputs. If no AVDoc or PDDoc inputs have been configured, AVCommandExecute() configures the command to use the active AVDoc. In all cases, if an AVDoc has been configured (either by AVCommandExecute() or its caller) the implementation ensures that the PDDoc input matches the AVDoc input.

• If the command can display a dialog box (that is, if the command handler has a ShowDialog callback and the command's kAVCommandKeyCanShowDialog property is true), present the dialog box to allow the user to alter the command's parameters.

• Repeatedly call AVCommandWork() on cmd until that method returns a status other than kAVCommandWorking.

This method should be used when the client does not need the level of control provided when calling AVCommandWork() directly. Specifically, this method is useful for using a global command from within a menu or a toolbar button's execution procedure.

Parameters

See Also

Since

Retrieves the AVDoc from a command's inputs ASCab.

Parameters

See Also

Since

Returns the ASCab stored in the specified command under the key. If the cabinet is not available, this method will create it if create is set to true. The command retains ownership of the returned cabinet.

This method can only be exercised by an AVCommandHandler. Command handlers can use this call to attach arbitrary information to a command. Only the command handler should access these cabinets. See AVCommandSetInputs() and AVCommandSetParams().

Parameters

See Also

Since

Returns a cancellation procedure for the command. If the user interface policy is anything other than kAVCommandUIInteractive, this cancellation procedure must be used. If the user interface policy is kAVCommandUIInteractive, an appropriate default cancel proc will be provided, but the command may use a more appropriate one it if preferred. Pass in the command itself as the client data.

Parameters

Since

Retrieves the configuration parameters for the specified command.

Configuration values are controlled by the mechanism that is driving the command, such as a client or the batch framework. For example, one configuration value determines whether to display a dialog box while executing; it can be a setting that the user can toggle through the user interface, or a client can set it through AVCommandSetConfig().

To retrieve all the configuration parameters, pass in an empty cabinet for config and the method will fill in the cabinet with the current configuration keys and values. To retrieve specific configuration parameter values, fill the initial dictionary with the keys in which you are interested, each with a NULL value, and the method will attempt to fill in the appropriate value for each key.

Currently the only configuration parameters defined are:

Parameters

See Also

Since

Retrieves the input parameters of the specified command. The inputs of a command consist of an ASCab detailing properties of the object on which the command will operate. The contents of the cabinet are dependent on the mechanism through which the command is initialized.

The batch framework attempts to provide the following:

Clients should also attempt to provide this information. The content of the inputs cabinet is not limited to the keys listed above. Clients (or the command handler itself ) can specify additional inputs as necessary. The caller retains ownership of inputs.

Parameters

See Also

Since

Returns the name of the command.

Parameters

Since

Retrieves the parameter set for the specified command. It is possible that some commands have no parameters that can be configured, in which case no data will be written to params. The params cabinet should be empty when passed in. Upon return, it will be filled with copies of all of the command's parameter settings.

The caller retains ownership of params.

Parameters

See Also

Since

Retrieves the PDDoc from a command's inputs ASCab.

Parameters

Since

Returns a progress monitor the command can use to report progress. The command itself should be passed in as the clientData associated with the monitor's callbacks.

Command handlers should use this progress monitor rather than a custom implementation.

If the command is driven by the batch framework, the progress monitor updates the batch progress dialog box. If the command is driven by a client and the AVDoc input key has been set, the progress monitor updates the progress pane at the bottom of the document's window; otherwise, the progress monitor's callbacks are no-ops.

Parameters

Since

Retrieves the properties of the specified command. Properties are values intrinsic to the command or to the command's current state.

To retrieve properties, create a cabinet containing the keys for the properties in which you are interested (the values should be invalid, such as NULL), and pass it into this method. The command will copy the requested properties into your cabinet. If the cabinet is empty, the command will fill in all properties.

The following properties are pre-defined:

Parameters

Since

Returns the ASReportProc associated with the specified command. AVCommandHandlers should report all error and status messages through this procedure.

Pass the AVCommand itself as the clientData parameter when calling the procedure.

Parameters

Since

Returns the current status of the specified command.

Parameters

Since

Retrieves the user interface policy that the command will respect while it is executed. The user interface policy is determined by a combination of the command's configuration and the context in which the command is executing (for example, a batch sequence).

Parameters

See Also

Since

Creates a new command of the specified type. An AVCommandHandler for that command type must have already been registered. See AVCommand Descriptions (Built-in Commands) for the names and parameters of built-in commands, as defined in AVCmdDefs.h.

Parameters

See Also

Since

Stores a cabinet in the specified command. If a cabinet is currently stored under the key, it is overwritten. The command assumes ownership of cabVal.

This method can only be exercised by an AVCommandHandler. Command handlers can use this call to store state information (such as parameters) in a command. Only the command handler associated with the command should access these cabinets. See AVCommandSetInputs() and AVCommandSetParams().

Parameters

See Also

Exceptions

Since

Resets the specified command. The command is expected to clean up its current state and assume a ready state.

If the command is currently processing a file, the command might not attempt to roll back any modifications it has made to the PDF. This may leave the PDF in an invalid state.

Parameters

See Also

Since

Sets the configuration for the specified command. See AVCommandGetConfig() for more information.

config will be merged with the current configuration cabinet to generate the new configuraton. To erase configuration settings, set their values to NULL in your cabinet.

Currently the only configuration parameters defined are:

The caller retains ownership of config.

Parameters

See Also

Since

Sets the input parameters of the specified command. The inputs of a command consist of an ASCab detailing properties of the object on which the command will operate. Use this method and AVCommandSetParams() to set up a command before calling AVCommandExecute() to execute it.

A command handler should provide at least the following information:

The command handler can specify additional inputs as necessary. The caller retains ownership of inputs.

Parameters

See Also

Since

Sets the parameters for the specified command. The parameters are those pieces of information that can be controlled by the user, such as the pages to act on. Use this method and AVCommandSetInputs() to set up a command before calling AVCommandExecute() to execute it.

Setting any parameters for a command sets all parameters. The command supplies appropriate default parameters for any that are missing from params. Passing an empty cabinet causes all parameters to be set to their default values.

If the command is not in a ready state, the parameters are not updated.

The caller retains ownership of params.

Parameters

See Also

Since

Instructs the command to bring up its configuration dialog box and gather parameter information from the user. The dialog box is shown regardless of the UIPolicy of the command.

If the user confirms the configuration dialog box, the cmd object's parameter set is updated; otherwise cmd will enter a cancelled state.

Query cmd for its kAVCommandKeyCanShowDialog property using AVCommandGetProps() to determine whether it has a configuration dialog box.

Parameters

Since

Instructs the command do some work based on its current parameters.

A command will either divide its processing across multiple AVCommandWork() calls, or perform all the processing within a single call.

If cmd is in a working state upon return, it is the client's responsibility to poll the command's cancel proc, before calling AVCommandWork() again, to continue processing.

Parameters

See Also

Since