Doc/library/aetypes.rst

:mod:`aetypes` --- AppleEvent objects
=====================================

.. module:: aetypes
   :platform: Mac
   :synopsis: Python representation of the Apple Event Object Model.
.. sectionauthor:: Vincent Marchetti <vincem@en.com>


.. % \moduleauthor{Jack Jansen?}{email}

The :mod:`aetypes` defines classes used to represent Apple Event data
descriptors and Apple Event object specifiers.

Apple Event data is contained in descriptors, and these descriptors are typed.
For many descriptors the Python representation is simply the corresponding
Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
etc. For OSA types that have no direct Python counterpart this module declares
classes. Packing and unpacking instances of these classes is handled
automatically by :mod:`aepack`.

An object specifier is essentially an address of an object implemented in a
Apple Event server. An Apple Event specifier is used as the direct object for an
Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
module contains the base classes for OSA classes and properties, which are used
by the packages generated by :mod:`gensuitemodule` to populate the classes and
properties in a given suite.

For reasons of backward compatibility, and for cases where you need to script an
application for which you have not generated the stub package this module also
contains object specifiers for a number of common OSA classes such as
``Document``, ``Window``, ``Character``, etc.

The :mod:`AEObjects` module defines the following classes to represent Apple
Event descriptor data:


.. class:: Unknown(type, data)

   The representation of OSA descriptor data for which the :mod:`aepack` and
   :mod:`aetypes` modules have no support, i.e. anything that is not represented by
   the other classes here and that is not equivalent to a simple Python value.


.. class:: Enum(enum)

   An enumeration value with the given 4-character string value.


.. class:: InsertionLoc(of, pos)

   Position ``pos`` in object ``of``.


.. class:: Boolean(bool)

   A boolean.


.. class:: StyledText(style, text)

   Text with style information (font, face, etc) included.


.. class:: AEText(script, style, text)

   Text with script system and style information included.


.. class:: IntlText(script, language, text)

   Text with script system and language information included.


.. class:: IntlWritingCode(script, language)

   Script system and language information.


.. class:: QDPoint(v, h)

   A quickdraw point.


.. class:: QDRectangle(v0, h0, v1, h1)

   A quickdraw rectangle.


.. class:: RGBColor(r, g, b)

   A color.


.. class:: Type(type)

   An OSA type value with the given 4-character name.


.. class:: Keyword(name)

   An OSA keyword with the given 4-character name.


.. class:: Range(start, stop)

   A range.


.. class:: Ordinal(abso)

   Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
   middle.


.. class:: Logical(logc, term)

   The logical expression of applying operator ``logc`` to ``term``.


.. class:: Comparison(obj1, relo, obj2)

   The comparison ``relo`` of ``obj1`` to ``obj2``.

The following classes are used as base classes by the generated stub packages to
represent AppleScript classes and properties in Python:


.. class:: ComponentItem(which[, fr])

   Abstract baseclass for an OSA class. The subclass should set the class attribute
   ``want`` to the 4-character OSA class code. Instances of subclasses of this
   class are equivalent to AppleScript Object Specifiers. Upon instantiation you
   should pass a selector in ``which``, and optionally a parent object in ``fr``.


.. class:: NProperty(fr)

   Abstract baseclass for an OSA property. The subclass should set the class
   attributes ``want`` and ``which`` to designate which property we are talking
   about. Instances of subclasses of this class are Object Specifiers.


.. class:: ObjectSpecifier(want, form, seld[, fr])

   Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
   Specifier. See the Apple Open Scripting Architecture documentation for the
   parameters. Note that this class is not abstract.