Next Page >

Hide TOC

NSScriptCommand Class Reference

Inherits from	NSObject
Conforms to	NSCoding NSObject (NSObject)
Framework	/System/Library/Frameworks/Foundation.framework
Availability	Available in Mac OS X v10.0 and later.
Companion guide	Cocoa Scripting Guide
Declared in	NSScriptCommand.h
Related sample code	Quartz Composer WWDC 2005 TextEdit SimpleCarbonAppleScript SimpleScriptingVerbs Sketch-112 TextEditPlus

Overview

An instance of NSScriptCommand represents a scripting statement, such as set word 5 of the front document to word 1 of the second document, and contains the information needed to perform the operation specified by the statement.

When an Apple event reaches a Cocoa application, Cocoa’s built-in scripting support transforms it into a script command (that is, an instance of NSScriptCommand or one of the subclasses provided by Cocoa scripting or by your application) and executes the command in the context of the application. Executing a command means either invoking the selector associated with the command on the object or objects designated to receive the command, or having the command perform its default implementation method (performDefaultImplementation).

Your application most likely calls methods of NSScriptCommand to extract the command arguments. You do this either in the performDefaultImplementation method of a command subclass you have created, or in an object method designated as the selector to handle a particular command.

As part of Cocoa’s standard scripting implementation, NSScriptCommand and its subclasses can handle the default command set for AppleScript's Standard suite for most applications without any subclassing. The Standard suite includes commands such as copy, count, create, delete, exists, and move, as well as common object classes such as application, document, and window.

For more information on working with script commands, see Script Commands in Cocoa Scripting Guide.

Adopted Protocols

NSCoding

Tasks

Initializing a Script Command

Getting the Current Command

Getting the Apple Event

Executing the Command

Accessing Receivers

Accessing Arguments

Accessing the Direct Parameter

Getting Command Information

Handling Script Execution Errors

Suspending and Resuming Commands

Class Methods

currentCommand

If a command is being executed in the current thread by Cocoa scripting's built-in Apple event handling, return the command.

+ (NSScriptCommand *)currentCommand

Discussion

A command is being executed in the current thread by Cocoa scripting's built-in Apple event handling if an instance of NSScriptCommand is handling an executeCommand message at this instant as the result of the dispatch of an Apple event. Returns nil otherwise. setScriptErrorNumber: and setScriptErrorString: messages sent to the returned command object will affect the reply event sent to the sender of the event from which the command was constructed, if the sender has requested a reply.

A suspended command is not considered the current command. If a command is suspended and no other command is being executed in the current thread, currentCommand returns nil.

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSScriptCommand.h

Instance Methods

appleEvent

If the receiver was constructed by Cocoa scripting's built-in Apple event handling, returns the Apple event descriptor from which it was constructed.

- (NSAppleEventDescriptor *)appleEvent

Discussion

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

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSScriptCommand.h

arguments

Returns the arguments of the command.

- (NSDictionary *)arguments

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

commandDescription

Returns the command description for the command.

- (NSScriptCommandDescription *)commandDescription

Discussion

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

directParameter

Returns the object that corresponds to the direct parameter of the Apple event from which the receiver derives.

- (id)directParameter

Return Value

An object. Returns nil if the received Apple event doesn’t contain a direct parameter.

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.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSScriptCommand.h

evaluatedArguments

Returns a dictionary containing the arguments of the command, evaluated from object specifiers to objects if necessary. The keys in the dictionary are the argument names.

- (NSDictionary *)evaluatedArguments

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.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

NSScriptCommand.h

evaluatedReceivers

Returns the object or objects to which the command is to be sent (called both the “receivers” or “targets” of script commands).

- (id)evaluatedReceivers

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

executeCommand

Executes the command if it is valid and returns the result, if any.

- (id)executeCommand

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

initWithCommandDescription:

Returns an a script command object initialized from the passed command description.

- (id)initWithCommandDescription:(NSScriptCommandDescription *)commandDesc

Parameters

commandDesc: A command description for the command to be created.

Return Value

A newly initialized instance of NSScriptCommand or a subclass.

Discussion

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

isWellFormed

Returns a Boolean value indicating whether the receiver is well formed according to its command description.

- (BOOL)isWellFormed

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

performDefaultImplementation

Overridden by subclasses to provide a default implementation for the command represented by the receiver.

- (id)performDefaultImplementation

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

receiversSpecifier

Returns the object specifier that, when evaluated, yields the receiver or receivers of the command.

- (NSScriptObjectSpecifier *)receiversSpecifier

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

resumeExecutionWithResult:

If a successful, unmatched, invocation of suspendExecution has been made, resume the execution of the command.

- (void)resumeExecutionWithResult:(id)result

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.

Important: The script command handler that is being executed when suspendExecution is invoked must return before you invoke resumeExecutionWithResult:. That is, it is not valid to suspend a command’s execution and then resume it immediately.

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSScriptCommand.h

scriptErrorExpectedTypeDescriptor

Returns the type descriptor that was put in the reply Apple event if the sender requested a reply, execution of the receiver completed, and an error number was set.

- (NSAppleEventDescriptor *)scriptErrorExpectedTypeDescriptor

Return Value

A descriptor that specifies a type.

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.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSScriptCommand.h

scriptErrorNumber

Returns the script error number, if any, associated with execution of the command.

- (int)scriptErrorNumber

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

scriptErrorOffendingObjectDescriptor

Returns the object descriptor that was put in the reply Apple event if the sender requested a reply, execution of the receiver completed, and an error number was set.

- (NSAppleEventDescriptor *)scriptErrorOffendingObjectDescriptor

Return Value

A descriptor that specifies an object.

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.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSScriptCommand.h

scriptErrorString

Returns the script error string, if any, associated with execution of the command.

- (NSString *)scriptErrorString

Discussion

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

setArguments:

Sets the arguments of the command to args.

- (void)setArguments:(NSDictionary *)args

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

setDirectParameter:

Sets the object that corresponds to the direct parameter of the Apple event from which the receiver derives.

- (void)setDirectParameter:(id)directParameter

Parameters

directParameter: An object to be set as the direct parameter.

Discussion

You don’t normally override this method.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

setReceiversSpecifier:

Sets the object specifier to receiversSpec that, when evaluated, indicates the receiver or receivers of the command.

- (void)setReceiversSpecifier:(NSScriptObjectSpecifier *)receiversSpec

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

setScriptErrorExpectedTypeDescriptor:

Sets a descriptor for the expected type that will be put in the reply Apple event if the sender requested a reply, execution of the receiver completes, and an error number was set.

- (void)setScriptErrorExpectedTypeDescriptor:(NSAppleEventDescriptor *)errorExpectedTypeDescriptor

Parameters

errorExpectedTypeDescriptor: A descriptor that specifies a type.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSScriptCommand.h

setScriptErrorNumber:

Sets a script error number that is associated with the execution of the command and is returned in the reply Apple event, if a reply was requested by the sender.

- (void)setScriptErrorNumber:(int)errorNumber

Parameters

errorNumber: An error number to associate with the command.

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.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Sketch-112

Declared In

NSScriptCommand.h

setScriptErrorOffendingObjectDescriptor:

Sets a descriptor for an object that will be put in the reply Apple event if the sender requested a reply, execution of the receiver completes, and an error number was set.

- (void)setScriptErrorOffendingObjectDescriptor:(NSAppleEventDescriptor *)errorOffendingObjectDescriptor

Parameters

errorOffendingObjectDescriptor: A descriptor that specifies an object that was responsible for an error.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSScriptCommand.h

setScriptErrorString:

Sets a script error string that is associated with execution of the command.

- (void)setScriptErrorString:(NSString *)errorString

Parameters

errorString: A string that describes an error.

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSScriptCommand.h

suspendExecution

Suspends the execution of the receiver.

- (void)suspendExecution

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.

Important: The script command handler that is being executed when this method is invoked must return before the subsequent invocation of resumeExecutionWithResult:. That is, it is not valid to suspend a command’s execution and then resume it immediately.

Another command can execute while a command is suspended.

Availability

Available in Mac OS X v10.3 and later.

Declared In

NSScriptCommand.h

Constants

NSScriptCommand—General Command Execution Errors

NSScriptCommand uses the following error codes for general command execution problems:

enum {
   NSNoScriptError = 0,
   NSReceiverEvaluationScriptError,
   NSKeySpecifierEvaluationScriptError,
   NSArgumentEvaluationScriptError,
   NSReceiversCantHandleCommandScriptError,
   NSRequiredArgumentsMissingScriptError,
   NSArgumentsWrongScriptError,
   NSUnknownKeyScriptError,
   NSInternalScriptError,
   NSOperationNotSupportedForKeyScriptError,
   NSCannotCreateScriptCommandError
};