Lib/plat-mac/aetools.py

   1 """Tools for use in AppleEvent clients and servers.
   2
   3 pack(x) converts a Python object to an AEDesc object
   4 unpack(desc) does the reverse
   5
   6 packevent(event, parameters, attributes) sets params and attrs in an AEAppleEvent record
   7 unpackevent(event) returns the parameters and attributes from an AEAppleEvent record
   8
   9 Plus...  Lots of classes and routines that help representing AE objects,
  10 ranges, conditionals, logicals, etc., so you can write, e.g.:
  11
  12     x = Character(1, Document("foobar"))
  13
  14 and pack(x) will create an AE object reference equivalent to AppleScript's
  15
  16     character 1 of document "foobar"
  17
  18 Some of the stuff that appears to be exported from this module comes from other
  19 files: the pack stuff from aepack, the objects from aetypes.
  20
  21 """
  22
  23
  24 from warnings import warnpy3k
  25 warnpy3k("In 3.x, the aetools module is removed.", stacklevel=2)
  26
  27 from types import *
  28 from Carbon import AE
  29 from Carbon import Evt
  30 from Carbon import AppleEvents
  31 import MacOS
  32 import sys
  33 import time
  34
  35 from aetypes import *
  36 from aepack import packkey, pack, unpack, coerce, AEDescType
  37
  38 Error = 'aetools.Error'
  39
  40 # Amount of time to wait for program to be launched
  41 LAUNCH_MAX_WAIT_TIME=10
  42
  43 # Special code to unpack an AppleEvent (which is *not* a disguised record!)
  44 # Note by Jack: No??!? If I read the docs correctly it *is*....
  45
  46 aekeywords = [
  47     'tran',
  48     'rtid',
  49     'evcl',
  50     'evid',
  51     'addr',
  52     'optk',
  53     'timo',
  54     'inte', # this attribute is read only - will be set in AESend
  55     'esrc', # this attribute is read only
  56     'miss', # this attribute is read only
  57     'from'  # new in 1.0.1
  58 ]
  59
  60 def missed(ae):
  61     try:
  62         desc = ae.AEGetAttributeDesc('miss', 'keyw')
  63     except AE.Error, msg:
  64         return None
  65     return desc.data
  66
  67 def unpackevent(ae, formodulename=""):
  68     parameters = {}
  69     try:
  70         dirobj = ae.AEGetParamDesc('----', '****')
  71     except AE.Error:
  72         pass
  73     else:
  74         parameters['----'] = unpack(dirobj, formodulename)
  75         del dirobj
  76     # Workaround for what I feel is a bug in OSX 10.2: 'errn' won't show up in missed...
  77     try:
  78         dirobj = ae.AEGetParamDesc('errn', '****')
  79     except AE.Error:
  80         pass
  81     else:
  82         parameters['errn'] = unpack(dirobj, formodulename)
  83         del dirobj
  84     while 1:
  85         key = missed(ae)
  86         if not key: break
  87         parameters[key] = unpack(ae.AEGetParamDesc(key, '****'), formodulename)
  88     attributes = {}
  89     for key in aekeywords:
  90         try:
  91             desc = ae.AEGetAttributeDesc(key, '****')
  92         except (AE.Error, MacOS.Error), msg:
  93             if msg[0] != -1701 and msg[0] != -1704:
  94                 raise
  95             continue
  96         attributes[key] = unpack(desc, formodulename)
  97     return parameters, attributes
  98
  99 def packevent(ae, parameters = {}, attributes = {}):
 100     for key, value in parameters.items():
 101         packkey(ae, key, value)
 102     for key, value in attributes.items():
 103         ae.AEPutAttributeDesc(key, pack(value))
 104
 105 #
 106 # Support routine for automatically generated Suite interfaces
 107 # These routines are also useable for the reverse function.
 108 #
 109 def keysubst(arguments, keydict):
 110     """Replace long name keys by their 4-char counterparts, and check"""
 111     ok = keydict.values()
 112     for k in arguments.keys():
 113         if keydict.has_key(k):
 114             v = arguments[k]
 115             del arguments[k]
 116             arguments[keydict[k]] = v
 117         elif k != '----' and k not in ok:
 118             raise TypeError, 'Unknown keyword argument: %s'%k
 119
 120 def enumsubst(arguments, key, edict):
 121     """Substitute a single enum keyword argument, if it occurs"""
 122     if not arguments.has_key(key) or edict is None:
 123         return
 124     v = arguments[key]
 125     ok = edict.values()
 126     if edict.has_key(v):
 127         arguments[key] = Enum(edict[v])
 128     elif not v in ok:
 129         raise TypeError, 'Unknown enumerator: %s'%v
 130
 131 def decodeerror(arguments):
 132     """Create the 'best' argument for a raise MacOS.Error"""
 133     errn = arguments['errn']
 134     err_a1 = errn
 135     if arguments.has_key('errs'):
 136         err_a2 = arguments['errs']
 137     else:
 138         err_a2 = MacOS.GetErrorString(errn)
 139     if arguments.has_key('erob'):
 140         err_a3 = arguments['erob']
 141     else:
 142         err_a3 = None
 143
 144     return (err_a1, err_a2, err_a3)
 145
 146 class TalkTo:
 147     """An AE connection to an application"""
 148     _signature = None   # Can be overridden by subclasses
 149     _moduleName = None  # Can be overridden by subclasses
 150     _elemdict = {}      # Can be overridden by subclasses
 151     _propdict = {}      # Can be overridden by subclasses
 152
 153     __eventloop_initialized = 0
 154     def __ensure_WMAvailable(klass):
 155         if klass.__eventloop_initialized: return 1
 156         if not MacOS.WMAvailable(): return 0
 157         # Workaround for a but in MacOSX 10.2: we must have an event
 158         # loop before we can call AESend.
 159         Evt.WaitNextEvent(0,0)
 160         return 1
 161     __ensure_WMAvailable = classmethod(__ensure_WMAvailable)
 162
 163     def __init__(self, signature=None, start=0, timeout=0):
 164         """Create a communication channel with a particular application.
 165
 166         Addressing the application is done by specifying either a
 167         4-byte signature, an AEDesc or an object that will __aepack__
 168         to an AEDesc.
 169         """
 170         self.target_signature = None
 171         if signature is None:
 172             signature = self._signature
 173         if type(signature) == AEDescType:
 174             self.target = signature
 175         elif type(signature) == InstanceType and hasattr(signature, '__aepack__'):
 176             self.target = signature.__aepack__()
 177         elif type(signature) == StringType and len(signature) == 4:
 178             self.target = AE.AECreateDesc(AppleEvents.typeApplSignature, signature)
 179             self.target_signature = signature
 180         else:
 181             raise TypeError, "signature should be 4-char string or AEDesc"
 182         self.send_flags = AppleEvents.kAEWaitReply
 183         self.send_priority = AppleEvents.kAENormalPriority
 184         if timeout:
 185             self.send_timeout = timeout
 186         else:
 187             self.send_timeout = AppleEvents.kAEDefaultTimeout
 188         if start:
 189             self._start()
 190
 191     def _start(self):
 192         """Start the application, if it is not running yet"""
 193         try:
 194             self.send('ascr', 'noop')
 195         except AE.Error:
 196             _launch(self.target_signature)
 197             for i in range(LAUNCH_MAX_WAIT_TIME):
 198                 try:
 199                     self.send('ascr', 'noop')
 200                 except AE.Error:
 201                     pass
 202                 else:
 203                     break
 204                 time.sleep(1)
 205
 206     def start(self):
 207         """Deprecated, used _start()"""
 208         self._start()
 209
 210     def newevent(self, code, subcode, parameters = {}, attributes = {}):
 211         """Create a complete structure for an apple event"""
 212
 213         event = AE.AECreateAppleEvent(code, subcode, self.target,
 214                   AppleEvents.kAutoGenerateReturnID, AppleEvents.kAnyTransactionID)
 215         packevent(event, parameters, attributes)
 216         return event
 217
 218     def sendevent(self, event):
 219         """Send a pre-created appleevent, await the reply and unpack it"""
 220         if not self.__ensure_WMAvailable():
 221             raise RuntimeError, "No window manager access, cannot send AppleEvent"
 222         reply = event.AESend(self.send_flags, self.send_priority,
 223                                   self.send_timeout)
 224         parameters, attributes = unpackevent(reply, self._moduleName)
 225         return reply, parameters, attributes
 226
 227     def send(self, code, subcode, parameters = {}, attributes = {}):
 228         """Send an appleevent given code/subcode/pars/attrs and unpack the reply"""
 229         return self.sendevent(self.newevent(code, subcode, parameters, attributes))
 230
 231     #
 232     # The following events are somehow "standard" and don't seem to appear in any
 233     # suite...
 234     #
 235     def activate(self):
 236         """Send 'activate' command"""
 237         self.send('misc', 'actv')
 238
 239     def _get(self, _object, asfile=None, _attributes={}):
 240         """_get: get data from an object
 241         Required argument: the object
 242         Keyword argument _attributes: AppleEvent attribute dictionary
 243         Returns: the data
 244         """
 245         _code = 'core'
 246         _subcode = 'getd'
 247
 248         _arguments = {'----':_object}
 249         if asfile:
 250             _arguments['rtyp'] = mktype(asfile)
 251
 252         _reply, _arguments, _attributes = self.send(_code, _subcode,
 253                 _arguments, _attributes)
 254         if _arguments.has_key('errn'):
 255             raise Error, decodeerror(_arguments)
 256
 257         if _arguments.has_key('----'):
 258             return _arguments['----']
 259             if asfile:
 260                 item.__class__ = asfile
 261             return item
 262
 263     get = _get
 264
 265     _argmap_set = {
 266         'to' : 'data',
 267     }
 268
 269     def _set(self, _object, _attributes={}, **_arguments):
 270         """set: Set an object's data.
 271         Required argument: the object for the command
 272         Keyword argument to: The new value.
 273         Keyword argument _attributes: AppleEvent attribute dictionary
 274         """
 275         _code = 'core'
 276         _subcode = 'setd'
 277
 278         keysubst(_arguments, self._argmap_set)
 279         _arguments['----'] = _object
 280
 281
 282         _reply, _arguments, _attributes = self.send(_code, _subcode,
 283                 _arguments, _attributes)
 284         if _arguments.get('errn', 0):
 285             raise Error, decodeerror(_arguments)
 286         # XXXX Optionally decode result
 287         if _arguments.has_key('----'):
 288             return _arguments['----']
 289
 290     set = _set
 291
 292     # Magic glue to allow suite-generated classes to function somewhat
 293     # like the "application" class in OSA.
 294
 295     def __getattr__(self, name):
 296         if self._elemdict.has_key(name):
 297             cls = self._elemdict[name]
 298             return DelayedComponentItem(cls, None)
 299         if self._propdict.has_key(name):
 300             cls = self._propdict[name]
 301             return cls()
 302         raise AttributeError, name
 303
 304 # Tiny Finder class, for local use only
 305
 306 class _miniFinder(TalkTo):
 307     def open(self, _object, _attributes={}, **_arguments):
 308         """open: Open the specified object(s)
 309         Required argument: list of objects to open
 310         Keyword argument _attributes: AppleEvent attribute dictionary
 311         """
 312         _code = 'aevt'
 313         _subcode = 'odoc'
 314
 315         if _arguments: raise TypeError, 'No optional args expected'
 316         _arguments['----'] = _object
 317
 318
 319         _reply, _arguments, _attributes = self.send(_code, _subcode,
 320                 _arguments, _attributes)
 321         if _arguments.has_key('errn'):
 322             raise Error, decodeerror(_arguments)
 323         # XXXX Optionally decode result
 324         if _arguments.has_key('----'):
 325             return _arguments['----']
 326 #pass
 327
 328 _finder = _miniFinder('MACS')
 329
 330 def _launch(appfile):
 331     """Open a file thru the finder. Specify file by name or fsspec"""
 332     _finder.open(_application_file(('ID  ', appfile)))
 333
 334
 335 class _application_file(ComponentItem):
 336     """application file - An application's file on disk"""
 337     want = 'appf'
 338
 339 _application_file._propdict = {
 340 }
 341 _application_file._elemdict = {
 342 }
 343
 344 # Test program
 345 # XXXX Should test more, really...
 346
 347 def test():
 348     target = AE.AECreateDesc('sign', 'quil')
 349     ae = AE.AECreateAppleEvent('aevt', 'oapp', target, -1, 0)
 350     print unpackevent(ae)
 351     raw_input(":")
 352     ae = AE.AECreateAppleEvent('core', 'getd', target, -1, 0)
 353     obj = Character(2, Word(1, Document(1)))
 354     print obj
 355     print repr(obj)
 356     packevent(ae, {'----': obj})
 357     params, attrs = unpackevent(ae)
 358     print params['----']
 359     raw_input(":")
 360
 361 if __name__ == '__main__':
 362     test()
 363     sys.exit(1)