Doc/library/carbon.rst

   1
   2 .. _toolbox:
   3
   4 *********************
   5 MacOS Toolbox Modules
   6 *********************
   7
   8 There are a set of modules that provide interfaces to various MacOS toolboxes.
   9 If applicable the module will define a number of Python objects for the various
  10 structures declared by the toolbox, and operations will be implemented as
  11 methods of the object.  Other operations will be implemented as functions in the
  12 module.  Not all operations possible in C will also be possible in Python
  13 (callbacks are often a problem), and parameters will occasionally be different
  14 in Python (input and output buffers, especially).  All methods and functions
  15 have a :attr:`__doc__` string describing their arguments and return values, and
  16 for additional description you are referred to `Inside Macintosh
  17 <http://developer.apple.com/documentation/macos8/mac8.html>`_ or similar works.
  18
  19 These modules all live in a package called :mod:`Carbon`. Despite that name they
  20 are not all part of the Carbon framework: CF is really in the CoreFoundation
  21 framework and Qt is in the QuickTime framework. The normal use pattern is ::
  22
  23    from Carbon import AE
  24
  25 .. warning::
  26
  27    The Carbon modules are removed in 3.0.
  28
  29
  30 :mod:`Carbon.AE` --- Apple Events
  31 =================================
  32
  33 .. module:: Carbon.AE
  34    :platform: Mac
  35    :synopsis: Interface to the Apple Events toolbox.
  36    :deprecated:
  37
  38
  39
  40 :mod:`Carbon.AH` --- Apple Help
  41 ===============================
  42
  43 .. module:: Carbon.AH
  44    :platform: Mac
  45    :synopsis: Interface to the Apple Help manager.
  46    :deprecated:
  47
  48
  49
  50 :mod:`Carbon.App` --- Appearance Manager
  51 ========================================
  52
  53 .. module:: Carbon.App
  54    :platform: Mac
  55    :synopsis: Interface to the Appearance Manager.
  56    :deprecated:
  57
  58
  59
  60 :mod:`Carbon.CF` --- Core Foundation
  61 ====================================
  62
  63 .. module:: Carbon.CF
  64    :platform: Mac
  65    :synopsis: Interface to the Core Foundation.
  66    :deprecated:
  67
  68
  69 The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
  70 ``CFURL`` objects are supported, some only partially.
  71
  72
  73 :mod:`Carbon.CG` --- Core Graphics
  74 ==================================
  75
  76 .. module:: Carbon.CG
  77    :platform: Mac
  78    :synopsis: Interface to Core Graphics.
  79    :deprecated:
  80
  81
  82
  83 :mod:`Carbon.CarbonEvt` --- Carbon Event Manager
  84 ================================================
  85
  86 .. module:: Carbon.CarbonEvt
  87    :platform: Mac
  88    :synopsis: Interface to the Carbon Event Manager.
  89    :deprecated:
  90
  91
  92
  93 :mod:`Carbon.Cm` --- Component Manager
  94 ======================================
  95
  96 .. module:: Carbon.Cm
  97    :platform: Mac
  98    :synopsis: Interface to the Component Manager.
  99    :deprecated:
 100
 101
 102
 103 :mod:`Carbon.Ctl` --- Control Manager
 104 =====================================
 105
 106 .. module:: Carbon.Ctl
 107    :platform: Mac
 108    :synopsis: Interface to the Control Manager.
 109    :deprecated:
 110
 111
 112
 113 :mod:`Carbon.Dlg` --- Dialog Manager
 114 ====================================
 115
 116 .. module:: Carbon.Dlg
 117    :platform: Mac
 118    :synopsis: Interface to the Dialog Manager.
 119    :deprecated:
 120
 121
 122
 123 :mod:`Carbon.Evt` --- Event Manager
 124 ===================================
 125
 126 .. module:: Carbon.Evt
 127    :platform: Mac
 128    :synopsis: Interface to the classic Event Manager.
 129    :deprecated:
 130
 131
 132
 133 :mod:`Carbon.Fm` --- Font Manager
 134 =================================
 135
 136 .. module:: Carbon.Fm
 137    :platform: Mac
 138    :synopsis: Interface to the Font Manager.
 139    :deprecated:
 140
 141
 142
 143 :mod:`Carbon.Folder` --- Folder Manager
 144 =======================================
 145
 146 .. module:: Carbon.Folder
 147    :platform: Mac
 148    :synopsis: Interface to the Folder Manager.
 149    :deprecated:
 150
 151
 152
 153 :mod:`Carbon.Help` --- Help Manager
 154 ===================================
 155
 156 .. module:: Carbon.Help
 157    :platform: Mac
 158    :synopsis: Interface to the Carbon Help Manager.
 159    :deprecated:
 160
 161
 162
 163 :mod:`Carbon.List` --- List Manager
 164 ===================================
 165
 166 .. module:: Carbon.List
 167    :platform: Mac
 168    :synopsis: Interface to the List Manager.
 169    :deprecated:
 170
 171
 172
 173 :mod:`Carbon.Menu` --- Menu Manager
 174 ===================================
 175
 176 .. module:: Carbon.Menu
 177    :platform: Mac
 178    :synopsis: Interface to the Menu Manager.
 179    :deprecated:
 180
 181
 182
 183 :mod:`Carbon.Mlte` --- MultiLingual Text Editor
 184 ===============================================
 185
 186 .. module:: Carbon.Mlte
 187    :platform: Mac
 188    :synopsis: Interface to the MultiLingual Text Editor.
 189    :deprecated:
 190
 191
 192
 193 :mod:`Carbon.Qd` --- QuickDraw
 194 ==============================
 195
 196 .. module:: Carbon.Qd
 197    :platform: Mac
 198    :synopsis: Interface to the QuickDraw toolbox.
 199    :deprecated:
 200
 201
 202
 203 :mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
 204 ============================================
 205
 206 .. module:: Carbon.Qdoffs
 207    :platform: Mac
 208    :synopsis: Interface to the QuickDraw Offscreen APIs.
 209    :deprecated:
 210
 211
 212
 213 :mod:`Carbon.Qt` --- QuickTime
 214 ==============================
 215
 216 .. module:: Carbon.Qt
 217    :platform: Mac
 218    :synopsis: Interface to the QuickTime toolbox.
 219    :deprecated:
 220
 221
 222
 223 :mod:`Carbon.Res` --- Resource Manager and Handles
 224 ==================================================
 225
 226 .. module:: Carbon.Res
 227    :platform: Mac
 228    :synopsis: Interface to the Resource Manager and Handles.
 229    :deprecated:
 230
 231
 232
 233 :mod:`Carbon.Scrap` --- Scrap Manager
 234 =====================================
 235
 236 .. module:: Carbon.Scrap
 237    :platform: Mac
 238    :synopsis: The Scrap Manager provides basic services for implementing cut & paste and
 239               clipboard operations.
 240    :deprecated:
 241
 242
 243 This module is only fully available on MacOS9 and earlier under classic PPC
 244 MacPython.  Very limited functionality is available under Carbon MacPython.
 245
 246 .. index:: single: Scrap Manager
 247
 248 The Scrap Manager supports the simplest form of cut & paste operations on the
 249 Macintosh.  It can be use for both inter- and intra-application clipboard
 250 operations.
 251
 252 The :mod:`Scrap` module provides low-level access to the functions of the Scrap
 253 Manager.  It contains the following functions:
 254
 255
 256 .. function:: InfoScrap()
 257
 258    Return current information about the scrap.  The information is encoded as a
 259    tuple containing the fields ``(size, handle, count, state, path)``.
 260
 261    +----------+---------------------------------------------+
 262    | Field    | Meaning                                     |
 263    +==========+=============================================+
 264    | *size*   | Size of the scrap in bytes.                 |
 265    +----------+---------------------------------------------+
 266    | *handle* | Resource object representing the scrap.     |
 267    +----------+---------------------------------------------+
 268    | *count*  | Serial number of the scrap contents.        |
 269    +----------+---------------------------------------------+
 270    | *state*  | Integer; positive if in memory, ``0`` if on |
 271    |          | disk, negative if uninitialized.            |
 272    +----------+---------------------------------------------+
 273    | *path*   | Filename of the scrap when stored on disk.  |
 274    +----------+---------------------------------------------+
 275
 276
 277 .. seealso::
 278
 279    `Scrap Manager <http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
 280       Apple's documentation for the Scrap Manager gives a lot of useful information
 281       about using the Scrap Manager in applications.
 282
 283
 284
 285 :mod:`Carbon.Snd` --- Sound Manager
 286 ===================================
 287
 288 .. module:: Carbon.Snd
 289    :platform: Mac
 290    :synopsis: Interface to the Sound Manager.
 291    :deprecated:
 292
 293
 294
 295 :mod:`Carbon.TE` --- TextEdit
 296 =============================
 297
 298 .. module:: Carbon.TE
 299    :platform: Mac
 300    :synopsis: Interface to TextEdit.
 301    :deprecated:
 302
 303
 304
 305 :mod:`Carbon.Win` --- Window Manager
 306 ====================================
 307
 308 .. module:: Carbon.Win
 309    :platform: Mac
 310    :synopsis: Interface to the Window Manager.
 311    :deprecated: