Doc/library/carbon.rst

   1
   2 .. _toolbox:
   3
   4 **********************
   5 Mac OS Toolbox Modules
   6 **********************
   7
   8 There are a set of modules that provide interfaces to various Mac OS 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 :mod:`Carbon.Appearance` --- Appearance Manager constants
  59 =========================================================
  60
  61 .. module:: Carbon.Appearance
  62    :platform: Mac
  63    :synopsis: Constant definitions for the interface to the Appearance Manager.
  64    :deprecated:
  65
  66
  67
  68 :mod:`Carbon.CF` --- Core Foundation
  69 ====================================
  70
  71 .. module:: Carbon.CF
  72    :platform: Mac
  73    :synopsis: Interface to the Core Foundation.
  74    :deprecated:
  75
  76
  77 The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
  78 ``CFURL`` objects are supported, some only partially.
  79
  80
  81 :mod:`Carbon.CG` --- Core Graphics
  82 ==================================
  83
  84 .. module:: Carbon.CG
  85    :platform: Mac
  86    :synopsis: Interface to Core Graphics.
  87    :deprecated:
  88
  89
  90
  91 :mod:`Carbon.CarbonEvt` --- Carbon Event Manager
  92 ================================================
  93
  94 .. module:: Carbon.CarbonEvt
  95    :platform: Mac
  96    :synopsis: Interface to the Carbon Event Manager.
  97    :deprecated:
  98
  99 :mod:`Carbon.CarbonEvents` --- Carbon Event Manager constants
 100 =============================================================
 101
 102 .. module:: Carbon.CarbonEvents
 103    :platform: Mac
 104    :synopsis: Constants for the interface to the Carbon Event Manager.
 105    :deprecated:
 106
 107
 108
 109 :mod:`Carbon.Cm` --- Component Manager
 110 ======================================
 111
 112 .. module:: Carbon.Cm
 113    :platform: Mac
 114    :synopsis: Interface to the Component Manager.
 115    :deprecated:
 116
 117 :mod:`Carbon.Components` --- Component Manager constants
 118 ========================================================
 119
 120 .. module:: Carbon.Components
 121    :platform: Mac
 122    :synopsis: Constants for the interface to the Component Manager.
 123    :deprecated:
 124
 125
 126 :mod:`Carbon.ControlAccessor` --- Control Manager accssors
 127 ===========================================================
 128
 129 .. module:: Carbon.ControlAccessor
 130    :platform: Mac
 131    :synopsis: Accessor functions for the interface to the Control Manager.
 132    :deprecated:
 133
 134 :mod:`Carbon.Controls` --- Control Manager constants
 135 ====================================================
 136
 137 .. module:: Carbon.Controls
 138    :platform: Mac
 139    :synopsis: Constants for the interface to the Control Manager.
 140    :deprecated:
 141
 142 :mod:`Carbon.CoreFounation` --- CoreFounation constants
 143 =======================================================
 144
 145 .. module:: Carbon.CoreFounation
 146    :platform: Mac
 147    :synopsis: Constants for the interface to CoreFoundation.
 148    :deprecated:
 149
 150 :mod:`Carbon.CoreGraphics` --- CoreGraphics constants
 151 =======================================================
 152
 153 .. module:: Carbon.CoreGraphics
 154    :platform: Mac
 155    :synopsis: Constants for the interface to CoreGraphics.
 156    :deprecated:
 157
 158 :mod:`Carbon.Ctl` --- Control Manager
 159 =====================================
 160
 161 .. module:: Carbon.Ctl
 162    :platform: Mac
 163    :synopsis: Interface to the Control Manager.
 164    :deprecated:
 165
 166 :mod:`Carbon.Dialogs` --- Dialog Manager constants
 167 ==================================================
 168
 169 .. module:: Carbon.Dialogs
 170    :platform: Mac
 171    :synopsis: Constants for the interface to the Dialog Manager.
 172    :deprecated:
 173
 174 :mod:`Carbon.Dlg` --- Dialog Manager
 175 ====================================
 176
 177 .. module:: Carbon.Dlg
 178    :platform: Mac
 179    :synopsis: Interface to the Dialog Manager.
 180    :deprecated:
 181
 182 :mod:`Carbon.Drag` --- Drag and Drop Manager
 183 =============================================
 184
 185 .. module:: Carbon.Drag
 186    :platform: Mac
 187    :synopsis: Interface to the Drag and Drop Manager.
 188    :deprecated:
 189
 190 :mod:`Carbon.Dragconst` --- Drag and Drop Manager constants
 191 ===========================================================
 192
 193 .. module:: Carbon.Dragconst
 194    :platform: Mac
 195    :synopsis: Constants for the interface to the Drag and Drop Manager.
 196    :deprecated:
 197
 198 :mod:`Carbon.Events` --- Event Manager constants
 199 ================================================
 200
 201 .. module:: Carbon.Events
 202    :platform: Mac
 203    :synopsis: Constants for the interface to the classic Event Manager.
 204    :deprecated:
 205
 206 :mod:`Carbon.Evt` --- Event Manager
 207 ===================================
 208
 209 .. module:: Carbon.Evt
 210    :platform: Mac
 211    :synopsis: Interface to the classic Event Manager.
 212    :deprecated:
 213
 214 :mod:`Carbon.File` --- File Manager
 215 ===================================
 216
 217 .. module:: Carbon.File
 218    :platform: Mac
 219    :synopsis: Interface to the File Manager.
 220    :deprecated:
 221
 222 :mod:`Carbon.Files` --- File Manager constants
 223 ==============================================
 224
 225 .. module:: Carbon.Files
 226    :platform: Mac
 227    :synopsis: Constants for the interface to the File Manager.
 228    :deprecated:
 229
 230
 231 :mod:`Carbon.Fm` --- Font Manager
 232 =================================
 233
 234 .. module:: Carbon.Fm
 235    :platform: Mac
 236    :synopsis: Interface to the Font Manager.
 237    :deprecated:
 238
 239
 240
 241 :mod:`Carbon.Folder` --- Folder Manager
 242 =======================================
 243
 244 .. module:: Carbon.Folder
 245    :platform: Mac
 246    :synopsis: Interface to the Folder Manager.
 247    :deprecated:
 248
 249 :mod:`Carbon.Folders` --- Folder Manager constants
 250 ==================================================
 251
 252 .. module:: Carbon.Folders
 253    :platform: Mac
 254    :synopsis: Constants for the interface to the Folder Manager.
 255    :deprecated:
 256
 257
 258 :mod:`Carbon.Fonts` --- Font Manager constants
 259 ==================================================
 260
 261 .. module:: Carbon.Fonts
 262    :platform: Mac
 263    :synopsis: Constants for the interface to the Font Manager.
 264    :deprecated:
 265
 266
 267
 268 :mod:`Carbon.Help` --- Help Manager
 269 ===================================
 270
 271 .. module:: Carbon.Help
 272    :platform: Mac
 273    :synopsis: Interface to the Carbon Help Manager.
 274    :deprecated:
 275
 276 :mod:`Carbon.IBCarbon` --- Carbon InterfaceBuilder
 277 ==================================================
 278
 279 .. module:: Carbon.IBCarbon
 280    :platform: Mac
 281    :synopsis: Interface to the Carbon InterfaceBuilder support libraries.
 282    :deprecated:
 283
 284 :mod:`Carbon.IBCarbonRuntime` --- Carbon InterfaceBuilder constants
 285 ===================================================================
 286
 287 .. module:: Carbon.IBCarbonRuntime
 288    :platform: Mac
 289    :synopsis: Constants for the interface to the Carbon InterfaceBuilder support libraries.
 290    :deprecated:
 291
 292 :mod:`Carbon.Icn` --- Carbon Icon Manager
 293 =========================================
 294
 295 .. module:: Carbon.Icns
 296    :platform: Mac
 297    :synopsis: Interface to the Carbon Icon Manager
 298    :deprecated:
 299
 300 :mod:`Carbon.Icons` --- Carbon Icon Manager constants
 301 =====================================================
 302
 303 .. module:: Carbon.Icons
 304    :platform: Mac
 305    :synopsis: Constants for the interface to the Carbon Icon Manager
 306    :deprecated:
 307
 308 :mod:`Carbon.Launch` --- Carbon Launch Services
 309 ===============================================
 310
 311 .. module:: Carbon.Launch
 312    :platform: Mac
 313    :synopsis: Interface to the Carbon Launch Services.
 314    :deprecated:
 315
 316 :mod:`Carbon.LaunchServices` --- Carbon Launch Services constants
 317 =================================================================
 318
 319 .. module:: Carbon.LaunchServices
 320    :platform: Mac
 321    :synopsis: Constants for the interface to the Carbon Launch Services.
 322    :deprecated:
 323
 324
 325 :mod:`Carbon.List` --- List Manager
 326 ===================================
 327
 328 .. module:: Carbon.List
 329    :platform: Mac
 330    :synopsis: Interface to the List Manager.
 331    :deprecated:
 332
 333
 334
 335 :mod:`Carbon.Lists` --- List Manager constants
 336 ==============================================
 337
 338 .. module:: Carbon.Lists
 339    :platform: Mac
 340    :synopsis: Constants for the interface to the List Manager.
 341    :deprecated:
 342
 343 :mod:`Carbon.MacHelp` --- Help Manager constants
 344 ================================================
 345
 346 .. module:: Carbon.MacHelp
 347    :platform: Mac
 348    :synopsis: Constants for the interface to the Carbon Help Manager.
 349    :deprecated:
 350
 351 :mod:`Carbon.MediaDescr` --- Parsers and generators for Quicktime Media descriptors
 352 ===================================================================================
 353
 354 .. module:: Carbon.MediaDescr
 355    :platform: Mac
 356    :synopsis: Parsers and generators for Quicktime Media descriptors
 357    :deprecated:
 358
 359
 360 :mod:`Carbon.Menu` --- Menu Manager
 361 ===================================
 362
 363 .. module:: Carbon.Menu
 364    :platform: Mac
 365    :synopsis: Interface to the Menu Manager.
 366    :deprecated:
 367
 368 :mod:`Carbon.Menus` --- Menu Manager constants
 369 ==============================================
 370
 371 .. module:: Carbon.Menus
 372    :platform: Mac
 373    :synopsis: Constants for the interface to the Menu Manager.
 374    :deprecated:
 375
 376
 377 :mod:`Carbon.Mlte` --- MultiLingual Text Editor
 378 ===============================================
 379
 380 .. module:: Carbon.Mlte
 381    :platform: Mac
 382    :synopsis: Interface to the MultiLingual Text Editor.
 383    :deprecated:
 384
 385 :mod:`Carbon.OSA` --- Carbon OSA Interface
 386 ==========================================
 387
 388 .. module:: Carbon.OSA
 389    :platform: Mac
 390    :synopsis: Interface to the Carbon OSA Library.
 391    :deprecated:
 392
 393 :mod:`Carbon.OSAconst` --- Carbon OSA Interface constants
 394 =========================================================
 395
 396 .. module:: Carbon.OSAconst
 397    :platform: Mac
 398    :synopsis: Constants for the interface to the Carbon OSA Library.
 399    :deprecated:
 400
 401 :mod:`Carbon.QDOffscreen` --- QuickDraw Offscreen constants
 402 ===========================================================
 403
 404 .. module:: Carbon.QDOffscreen
 405    :platform: Mac
 406    :synopsis: Constants for the interface to the QuickDraw Offscreen APIs.
 407    :deprecated:
 408
 409
 410 :mod:`Carbon.Qd` --- QuickDraw
 411 ==============================
 412
 413 .. module:: Carbon.Qd
 414    :platform: Mac
 415    :synopsis: Interface to the QuickDraw toolbox.
 416    :deprecated:
 417
 418
 419
 420 :mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
 421 ============================================
 422
 423 .. module:: Carbon.Qdoffs
 424    :platform: Mac
 425    :synopsis: Interface to the QuickDraw Offscreen APIs.
 426    :deprecated:
 427
 428
 429
 430 :mod:`Carbon.Qt` --- QuickTime
 431 ==============================
 432
 433 .. module:: Carbon.Qt
 434    :platform: Mac
 435    :synopsis: Interface to the QuickTime toolbox.
 436    :deprecated:
 437
 438 :mod:`Carbon.QuickDraw` --- QuickDraw constants
 439 ===============================================
 440
 441 .. module:: Carbon.QuickDraw
 442    :platform: Mac
 443    :synopsis: Constants for the interface to the QuickDraw toolbox.
 444    :deprecated:
 445
 446 :mod:`Carbon.QuickTime` --- QuickTime constants
 447 ===============================================
 448
 449 .. module:: Carbon.QuickTime
 450    :platform: Mac
 451    :synopsis: Constants for the interface to the QuickTime toolbox.
 452    :deprecated:
 453
 454
 455 :mod:`Carbon.Res` --- Resource Manager and Handles
 456 ==================================================
 457
 458 .. module:: Carbon.Res
 459    :platform: Mac
 460    :synopsis: Interface to the Resource Manager and Handles.
 461    :deprecated:
 462
 463 :mod:`Carbon.Resources` --- Resource Manager and Handles constants
 464 ==================================================================
 465
 466 .. module:: Carbon.Resources
 467    :platform: Mac
 468    :synopsis: Constants for the interface to the Resource Manager and Handles.
 469    :deprecated:
 470
 471
 472 :mod:`Carbon.Scrap` --- Scrap Manager
 473 =====================================
 474
 475 .. module:: Carbon.Scrap
 476    :platform: Mac
 477    :synopsis: The Scrap Manager provides basic services for implementing cut & paste and
 478               clipboard operations.
 479    :deprecated:
 480
 481
 482 This module is only fully available on Mac OS 9 and earlier under classic PPC
 483 MacPython.  Very limited functionality is available under Carbon MacPython.
 484
 485 .. index:: single: Scrap Manager
 486
 487 The Scrap Manager supports the simplest form of cut & paste operations on the
 488 Macintosh.  It can be use for both inter- and intra-application clipboard
 489 operations.
 490
 491 The :mod:`Scrap` module provides low-level access to the functions of the Scrap
 492 Manager.  It contains the following functions:
 493
 494
 495 .. function:: InfoScrap()
 496
 497    Return current information about the scrap.  The information is encoded as a
 498    tuple containing the fields ``(size, handle, count, state, path)``.
 499
 500    +----------+---------------------------------------------+
 501    | Field    | Meaning                                     |
 502    +==========+=============================================+
 503    | *size*   | Size of the scrap in bytes.                 |
 504    +----------+---------------------------------------------+
 505    | *handle* | Resource object representing the scrap.     |
 506    +----------+---------------------------------------------+
 507    | *count*  | Serial number of the scrap contents.        |
 508    +----------+---------------------------------------------+
 509    | *state*  | Integer; positive if in memory, ``0`` if on |
 510    |          | disk, negative if uninitialized.            |
 511    +----------+---------------------------------------------+
 512    | *path*   | Filename of the scrap when stored on disk.  |
 513    +----------+---------------------------------------------+
 514
 515
 516 .. seealso::
 517
 518    `Scrap Manager <http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
 519       Apple's documentation for the Scrap Manager gives a lot of useful information
 520       about using the Scrap Manager in applications.
 521
 522
 523
 524 :mod:`Carbon.Snd` --- Sound Manager
 525 ===================================
 526
 527 .. module:: Carbon.Snd
 528    :platform: Mac
 529    :synopsis: Interface to the Sound Manager.
 530    :deprecated:
 531
 532 :mod:`Carbon.Sound` --- Sound Manager constants
 533 ===============================================
 534
 535 .. module:: Carbon.Sound
 536    :platform: Mac
 537    :synopsis: Constants for the interface to the Sound Manager.
 538    :deprecated:
 539
 540
 541 :mod:`Carbon.TE` --- TextEdit
 542 =============================
 543
 544 .. module:: Carbon.TE
 545    :platform: Mac
 546    :synopsis: Interface to TextEdit.
 547    :deprecated:
 548
 549 :mod:`Carbon.TextEdit` --- TextEdit constants
 550 =============================================
 551
 552 .. module:: Carbon.TextEdit
 553    :platform: Mac
 554    :synopsis: Constants for the interface to TextEdit.
 555    :deprecated:
 556
 557
 558
 559 :mod:`Carbon.Win` --- Window Manager
 560 ====================================
 561
 562 .. module:: Carbon.Win
 563    :platform: Mac
 564    :synopsis: Interface to the Window Manager.
 565    :deprecated:
 566
 567 :mod:`Carbon.Windows` --- Window Manager constants
 568 ==================================================
 569
 570 .. module:: Carbon.Windows
 571    :platform: Mac
 572    :synopsis: Constants for the interface to the Window Manager.
 573    :deprecated: