NSScriptCommand Class Reference

Discussion

The effects of mutating or retaining this descriptor are undefined, although it may be copied.

Discussion

If there are no arguments, returns an empty NSDictionary object. When you subclass NSScriptCommand or one of its subclasses, you rarely call this method because it returns the arguments directly, without evaluating any arguments that are object specifiers. If any of a command’s arguments may be object specifiers, which is generally the case, call evaluatedArguments instead.

Discussion

Once a command is created, its command description is immutable.

Discussion

For example, the direct parameter of a print documents Apple event contains a list of documents. This method may return the same object or objects returned by receiversSpecifier.

Discussion

Arguments initially can be either a normal object or an object specifier such as word 5 (represented as an instance of an NSScriptObjectSpecifier subclass). If arguments are object specifiers, the receiver evaluates them before using the referenced objects. Returns nil if the command is not well formed. Also returns nil if an object specifier does not evaluate to an object or if there is no type defined for the argument in the command description.

Discussion

It evaluates receivers, which are always object specifiers, to a proper object. If the command does not specify a receiver, or if the receiver doesn’t accept the command, it returns nil.

Discussion

Before this method executes the command (through NSInvocation mechanisms), it evaluates all object specifiers involved in the command, validates that the receivers can actually handle the command, and verifies that the types of any arguments that were initially object specifiers are valid.

You shouldn’t have to override this method. If the command’s receivers want to handle the command themselves, this method invokes their defined handler. Otherwise, it invokes performDefaultImplementation.

Discussion

To make this command object usable, you must set its receiving objects and arguments (if any) after invoking this method.

Discussion

The method ensures that there is a description of the command and that the number of arguments and the types of non-specifier arguments conform to the command description.

Discussion

Do not invoke this method directly. executeCommand invokes this method when the command being executed is not supported by the class of the objects receiving the command. The default implementation returns nil.

You need to create a subclass of NSScriptCommand only if you need to provide a default implementation of a command.

Discussion

The receiver is typically a container. For example, if the original command is get the third paragraph of the first document, the receiver specifier is the first document—it’s the document that knows how to get or set words or paragraphs it contains.

Discussion

Resumes the execution of the command if a successful, unmatched, invocation of suspendExecution has been made—otherwise, does nothing. The value for result is dependent on the segment of command execution that was suspended:

• If suspendExecution was invoked from within a command handler of one of the command's receivers, result is considered to be the return value of the handler. Unless the command has received a setScriptErrorNumber: message with a nonzero error number, execution of the command will continue and the command handlers of other receivers will be invoked.

• If suspendExecution was invoked from within an override of performDefaultImplementation the result is treated as if it were the return value of the invocation of performDefaultImplementation.

resumeExecutionWithResult: may be invoked in any thread, not just the one in which the corresponding invocation of suspendExecution occurred.

Discussion

When an error occurs during script command execution because an Apple event descriptor wasn’t of the expected type, and the sender requested a reply, Cocoa scripting returns a descriptor for the expected type in a reply Apple event. You can invoke setScriptErrorExpectedTypeDescriptor: to set this descriptor directly.

Discussion

When you subclass NSScriptCommand or one of its subclasses, you shouldn’t need to override this method.

For error conditions specific to your application you can define your own error return values. For some common errors, you may want to return error values defined in MacErrors.h, a header in CarbonCore.framework (a subframework of CoreServices.framework). Look for error constants that start with errAE. For example, errAEEventNotHandled indicates a handler wasn’t able to handle the Apple event.

Discussion

When an error that occurs during script command execution is caused by a specific object, and the sender requested a reply, Cocoa scripting returns a descriptor for the offending object in a reply Apple event. You can invoke setScriptErrorOffendingObjectDescriptor: to set this descriptor directly.

Discussion

When you subclass NSScriptCommand or one of its subclasses, you shouldn’t need to override this method.

Discussion

Each argument in the dictionary is identified by the same name key used for the argument in the command’s class declaration in the script suite file.

Discussion

You don’t normally override this method.

Discussion

If you create a subclass of NSScriptCommand, you don’t necessarily need to override this method, though some of Cocoa’s subclasses do. An override should perform the same function as the superclass method, with a critical difference: it causes the container specifier part of the passed-in object specifier to become the receiver specifier of the command, and the key part of the passed-in object specifier to become the key specifier. In an override, for example, if receiversRef is a specifier for the third rectangle of the first document, the receiver specifier is the first document while the key specifier is the third rectangle.

Discussion

If you override performDefaultImplementation and an error occurs, you should call this method to supply an appropriate error number. In fact, any script handler should call this method when an error occurs. The error number you supply is returned in the reply Apple event.

Invoking setScriptErrorNumber: causes an error message to be displayed. To associate a specific error message with the error number, you invoke setScriptErrorString:. This make sense, for example, when you set an error number that is specific to your application, or when you can supply a specific and useful error message to the user.

If setScriptErrorNumber: is invoked on an NSScriptCommand with multiple receivers, the command will stop sending command handling messages to more receivers.

Discussion

If you override performDefaultImplementation and an error occurs, you should call this method to supply a string that provides a useful explanation. In fact, any script handler should call this method when an error occurs.

Calling this method alone does not cause an error message to be be displayed—you must also call setScriptErrorNumber: to supply an error number.

Discussion

Suspends the execution of the receiver only if the receiver is being executed in the current thread by Cocoa scripting's built-in Apple event handling (that is, the receiver would be returned by [NSScriptCommand currentCommand])—otherwise, does nothing. A matching invocation of resumeExecutionWithResult: must be made.

Another command can execute while a command is suspended.