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