/core/externals/update-engine/externals/google-toolbox-for-mac/Foundation/GTMNSAppleScript+Handler.h

  1//
  2//  GTMNSAppleScript+Handler.h
  3//
  4//  Copyright 2008 Google Inc.
  5//
  6//  Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7//  use this file except in compliance with the License.  You may obtain a copy
  8//  of the License at
  9// 
 10//  http://www.apache.org/licenses/LICENSE-2.0
 11// 
 12//  Unless required by applicable law or agreed to in writing, software
 13//  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 14//  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 15//  License for the specific language governing permissions and limitations under
 16//  the License.
 17//
 18
 19#import <Foundation/Foundation.h>
 20#import "GTMDefines.h"
 21
 22// A category for calling handlers in NSAppleScript
 23
 24enum {
 25  // Data type is OSAID. These will generally be representing
 26  // scripts.
 27  typeGTMOSAID = 'GTMO' 
 28};
 29
 30@interface NSAppleScript(GTMAppleScriptHandlerAdditions)
 31// Allows us to call a specific handler in an AppleScript.
 32// parameters are passed in left-right order 0-n.
 33//
 34// Args:
 35//   handler - name of the handler to call in the Applescript
 36//   params - the parameters to pass to the handler
 37//   error - in non-nil returns any error that may have occurred.
 38//
 39// Returns:
 40//   The result of the handler being called. nil on failure.
 41- (NSAppleEventDescriptor*)gtm_executePositionalHandler:(NSString*)handler 
 42                                             parameters:(NSArray*)params 
 43                                                  error:(NSDictionary**)error;
 44
 45
 46// Allows us to call a specific labeled handler in an AppleScript.
 47// Parameters for a labeled handler can be in any order, as long as the
 48// order of the params array corresponds to the order of the labels array
 49// such that labels are associated with their correct parameter values.
 50//
 51// Args:
 52//   handler - name of the handler to call in the Applescript
 53//   labels - the labels to associate with the parameters
 54//   params - the parameters to pass to the handler
 55//   count - number of labels/parameters
 56//   error - in non-nil returns any error that may have occurred.
 57//
 58// Returns:
 59//   The result of the handler being called. nil on failure.
 60- (NSAppleEventDescriptor*)gtm_executeLabeledHandler:(NSString*)handler
 61                                              labels:(AEKeyword*)labels
 62                                          parameters:(id*)params
 63                                               count:(NSUInteger)count
 64                                               error:(NSDictionary **)error;
 65
 66// Same as executeAppleEvent:error: except that it handles return values of
 67// script correctly. Return values containing scripts will have the
 68// typeGTMOSAID. Calling gtm_objectValue on a NSAppleEventDescriptor of
 69// typeGTMOSAID will resolve correctly to a script value. We don't use
 70// typeScript because that actually copies the script instead of returning the
 71// actual value. Therefore if you called executeAppleEvent:error: (instead of
 72// the GTM version) to execute an event that returns a script, you will
 73// get a completely new Applescript, instead of the actual script you wanted. If
 74// you are working with script information, use gtm_executeAppleEvent:error
 75// instead of executeAppleEvent:error: to avoid the problem.
 76- (NSAppleEventDescriptor *)gtm_executeAppleEvent:(NSAppleEventDescriptor *)event 
 77                                            error:(NSDictionary **)error;
 78
 79// The set of all handlers that are defined in this script and its parents.
 80// Remember that handlers that are defined in an sdef will have their
 81// eventclass/eventid as their handler instead of the name seen in the script.
 82// So:
 83// on open(a)
 84//   blah
 85// end open
 86// won't be "open" it will be "aevtodoc".
 87- (NSSet*)gtm_handlers;
 88
 89// The set of all properties that are defined in this script and its parents.
 90// Note that properties can be strings or GTMNSFourCharCodes, so expect both
 91// coming back in the set.
 92- (NSSet*)gtm_properties;
 93
 94// Return a value for a property. Will look up the inheritence tree.
 95// Property must be an NSString or a GTMFourCharCode.
 96- (id)gtm_valueForProperty:(id)property;
 97
 98// Return a value for a property by type (eg pASParent). Will look up the
 99// inheritence tree
100- (id)gtm_valueForPropertyEnum:(DescType)property;
101
102// Set a script property value. Returns YES/NO on success/failure.
103// Property must be of kind NSString or GTMFourCharCode.
104// If addingDefinition is YES, it will add a definition to the script
105// if the value doesn't exist in the script or one of it's parents.
106- (BOOL)gtm_setValue:(id)value 
107         forProperty:(id)property 
108    addingDefinition:(BOOL)adding;
109
110// Set a value for a property by type (eg pASParent). See note above
111// for gtm_setValue:forProperty.
112- (BOOL)gtm_setValue:(id)value 
113     forPropertyEnum:(DescType)property
114    addingDefinition:(BOOL)adding;
115
116// Return YES if the script has an open documents (odoc) handler
117// Does not require script compilation, so it's a fast check.
118- (BOOL)gtm_hasOpenDocumentsHandler;
119
120@end
121
122// Error keys that we may return in the error dictionary on top of the standard
123// NSAppleScriptError* keys.
124extern NSString const* GTMNSAppleScriptErrorPartialResult;  // id
125extern NSString const* GTMNSAppleScriptErrorOffendingObject;  // id
126extern NSString const* GTMNSAppleScriptErrorExpectedType;  // GTMFourCharCode
127
128@interface NSAppleEventDescriptor (GTMAppleEventDescriptorOSAAdditions)
129// Returns an NSValue containing an NSRange of script source when an error
130// occurs while compiling and/or executing a script.
131- (id)gtm_OSAErrorRangeValue;
132@end