1=============== 2PyObjC Examples 3=============== 4 5Simple scripts that demo the core modules 6----------------------------------------- 7 8The directory `Scripts`__ contains a number of simple command-line scripts 9that make use of Cocoa features. 10 11.. __: Scripts 12 13* `autoreadme.py`_ 14 15 This script is a daemon that will open the ReadMe file in the root of any 16 (removable) volume that is inserted while this script is running. 17 18 The script is part of `Introduction to PyObjC`_, an article at O'Reilly 19 `MacDevCenter.com`_. 20 21.. _`autoreadme.py`: Scripts/autoreadme.py 22.. _`Introduction to PyObjC`: http://macdevcenter.com/pub/a/mac/2003/01/31/pyobjc_one.html 23.. _`MacDevCenter.com`: http://macdevcenter.com/ 24 25* `debugging.py`__ 26 27 This script shows how to use ``PyObjCTools.Debugging`` to show tracebacks 28 of all (Cocoa) exceptions (handled and unhandled). 29 30.. __: Scripts/debugging.py 31 32* `dictionary.py`__ 33 34 Demonstrate the usage of an ``NSMutableDictionary`` object with both 35 Objective-C and Python dictionary syntax. 36 37.. __: Scripts/dictionary.py 38 39* `exportBook.py`__ 40 41 An example of using the ``AddressBook`` framework, this script exports some 42 of the information about people in your addressbook to a CSV file. 43 44.. __: Scripts/exportBook.py 45 46* `findPython.py`__ 47 48 Demonstrate the usage of ``objc.loadBundleFunctions`` to access 49 functionality from the standard C library on Mac OS X (``libSystem``, 50 which is also available as the ``System.framework`` bundle). This 51 example uses the dyld runtime to determine which dylib the Python 52 runtime came from. 53 54.. __: Scripts/findPython.py 55 56* `HelloWorld.py`__ 57 58 Demonstrates a nib-less Cocoa GUI (purely for informational purposes, you 59 probably shouldn't make a habit of this) 60 61.. __: Scripts/HelloWorld.py 62 63* `kvo-debugging.py`__ 64 65 XXX 66 An example script that demonstrates how PyObjC interacts with Key-Value 67 Observing (KVO) at the lowest level. This script was used to debug 68 the PyObjC runtime and should not be used as a guideline for writing 69 new KVO code. It may be interesting to some until we ensure that we 70 have proper unit tests for KVO and remove this example! 71 72.. __: Scripts/kvo-debugging.py 73 74* `pydict-to-objcdict.py`__ 75 76 Shows how ``PyObjCTools.Conversion`` can be used to convert a Python 77 collection into an Objective-C property list. These functions should 78 not typically be necessary as the proxies for Python objects are 79 compatible with Objective-C plists. 80 81.. __: Scripts/pydict-to-objcdict.py 82 83* `rendezvous.py`__ 84 85 Use an NSNetService class to look for servers using rendezvous. 86 87.. __: Scripts/rendezvous.py 88 89* `signal-demo.py`__ 90 91 Demonstrates how to get a backtrace when handling a fatal signal using 92 ``PyObjCTools.Signals``. 93 94.. __: Scripts/signal-demo.py 95 96* `stdinreader.py`__ 97 98 Demonstrates how to write a console runloop based application that uses 99 ``NSFileHandle`` to read stdin asynchronously. 100 101.. __: Scripts/stdinreader.py 102 103* `subclassing-objective-c.py`__ 104 105 A doctest that demonstrates the subclassing of an Objective-C class from 106 Python. Note that it is typically discouraged to define a ``__del__`` 107 method. 108 109.. __: Scripts/subclassing-objective-c.py 110 111* `super-call.py`__ 112 113 Demonstrates how create a subclass of an Objective-C class that overrides 114 a selector, but calls the super implementation using Python syntax 115 equivalent to ``[super init]``. 116 117.. __: Scripts/super-call.py 118 119* `wmEnable.py`__ 120 121 Another ``objc.loadBundleFunctions`` demonstration that shows how to 122 call into a private CoreGraphics SPI and enable full WindowManager 123 access from a process that would not otherwise have it due to a 124 quirk in the implementation of WindowManager (the reason why ``pythonw`` 125 should be used instead of ``python``). Use at your own risk! 126 127.. __: Scripts/wmEnable.py 128 129 130Cocoa Applications 131------------------ 132 133The directory `AppKit`__ contains example applications using the Cocoa 134Application Framework (aka "AppKit"). 135 136.. __: AppKit 137 138Most of the following examples contain a ``setup.py`` script that can 139build an application. See `Building applications`_ for details how to invoke 140these scripts. Some examples contain an ``Xcode`` or ``Project Builder`` 141project file; simply double-click it and choose ``Build and Run``, or invoke 142``xcodebuild`` or ``pbxbuild`` from the command line depending on which you 143have installed. 144 145.. _`Building applications`: ../Doc/intro.html#building-applications 146 147* `ClassBrowser`__ 148 149 A simple class browser, demonstrating the use of ``NSBrowser`` 150 (a "column view" hierarchical widget) and ``NSTableView``. 151 152.. __: AppKit/ClassBrowser 153 154* `CurrencyConverter`_ 155 156 A simple NIB based application. Start with this one. Also see the 157 `PyObjC tutorial`_. 158 159.. _`CurrencyConverter`: AppKit/CurrencyConverter 160.. _`PyObjC tutorial`: ../Doc/tutorial/tutorial.html 161 162* `DotView`__ 163 164 A simple one-window demo showing how to custom drawing in a custom 165 ``NSView``. Additionally shows how easy it is to embed a view in an 166 ``NSScrollView``, as well as how to use an ``NSColorWell``. 167 168.. __: AppKit/DotView 169 170* `FieldGraph`__ 171 172 This shows an simple example of an MVC based application, that also 173 makes use of ``NSBezierPaths``. Contains a ``Project Builder`` project, 174 as well as a ``setup.py`` script. 175 176 The application calculates the field pattern and RMS field of an antenna 177 array with up to three elements. 178 179.. __: AppKit/FieldGraph 180 181* `HotKeyPython`__ 182 183 Demonstrates how to use Carbon global hot keys from a PyObjC application. 184 Also demonstrates how to use a ``NSApplication`` subclass. 185 186.. __: AppKit/HotKeyPYthon 187 188* `iClass`__ 189 190 A more elaborate class browser; demonstrates ``NSOutlineView`` and 191 ``NSTableView``. 192 193.. __: AppKit/iClass 194 195* `PackageManager`__ 196 197 An implementation of the MacPython PackageManager application using 198 Cocoa. 199 200.. __: AppKit/PackageManager 201 202* `PyInterpreter`__ 203 204 A full featured embedded Python interpreter. This demonstrates 205 more complicated uses of ``NSTextView``, manual event dispatching, 206 and the new text completion feature of OS X 10.3. 207 208.. __: AppKit/PyInterpreter 209 210* `PyObjCLauncher`__ 211 212 A reimplementation of the Python script launcher helper application 213 in PyObjC. 214 215.. __: AppKit/PyObjCLauncher 216 217* `PythonBrowser`__ 218 219 A reusable Python object browser, demonstrating the use of ``NSOutlineView`` 220 as well as how to use an ``NSWindowController`` subclass to create a window 221 from a menu action. 222 223.. __: AppKit/PythonBrowser 224 225* `SimpleService`__ 226 227 Shows how to implement entries for the Services menu. 228 229.. __: AppKit/SimpleService 230 231* `TableModel`__ 232 233 Basic demo that shows how to use a ``NSTableView``. 234 235.. __: AppKit/TableModel 236 237* `TinyTinyEdit`__ 238 239 A minimal Document-based text editor application. 240 241.. __: AppKit/TinyTinyEdit 242 243* `TinyURLService`__ 244 245 Another simple service, this one converts URL or strings from the 246 pasteboard to tinyurl.com equivalents. 247 248.. __: AppKit/TinyURLService 249 250* `Todo`_ 251 252 A more complex NIB based applications. This is a document-based application. 253 The code is a translation into Python of an example project in 254 `Learning Cocoa`_ from O'Reilly 255 256.. _`Todo`: AppKit/ToDo 257.. _`Learning Cocoa`: http://www.oreilly.com/catalog/learncocoa2/ 258 259* `WebServicesTool`__ 260 261 Queries an XML-RPC enabled web server for the methods that it implements. 262 Demonstrates a more advanced use of an ``NSTableView``, how to make a 263 toolbar as well as how to use multi-threading. Contains a 264 ``Project Builder`` project as well as a ``setup.py`` script. 265 266.. __: AppKit/WebServicesTool 267 268 269Cocoa Bindings 270-------------- 271 272The `CocoaBindings`__ directory contains a number of examples that make use of 273Key-Value Coding and Cocoa Bindings. These scripts require Mac OS X 10.3 or 274later. 275 276.. __: CocoaBindings 277 278* `Bookmarks`_ 279 280 Shows custom array controller that implements table view data 281 source methods to support drag and drop, including copying 282 objects from one window to another, drop of URLs, and 283 re-ordering of the content array. 284 285 Originally from `Cocoa Bindings Examples and Hints`_, 286 converted to PyObjC by u.fiedler. 287 288.. _`Bookmarks`: CocoaBindings/Bookmarks 289 290* `ControlledPreferences`_ 291 292 Demonstrates how to use Cocoa Bindings to simplify storing and 293 retrieving user preferences. Also demonstrates how to use an 294 ``NSValueTransformer`` to archive/unarchive a non-property-list 295 type automatically (``NSColor``, in this case). 296 297 Originally from `Cocoa Bindings Examples and Hints`_, 298 converted to PyObjC by u.fiedler. 299 300.. _`ControlledPreferences`: CocoaBindings/ControlledPreferences 301 302* `CurrencyConvBinding`_ 303 304 A rewrite of `CurrencyConverter`_ using Cocoa Bindings. 305 306 Originally from 307 `Introduction to Developing Cocoa Applications Using Bindings`_, 308 converted to PyObjC by u.fiedler. 309 310.. _`CurrencyConvBinding`: CocoaBindings/CurrencyConvBinding 311.. _`Introduction to Developing Cocoa Applications Using Bindings`: http://developer.apple.com/documentation/Cocoa/Conceptual/CurrencyConverterBindings/index.html 312 313* `FilteringController`_ 314 315 Demonstrates how to subclass ``NSArrayController`` to implement filtering 316 of a ``NSTableView``. Also demonstrates the use of indexed accessors. 317 318 Originally from `Cocoa Bindings Examples and Hints`_, 319 converted to PyObjC by u.fiedler. 320 321.. _`FilteringController`: CocoaBindings/FilteringController 322 323* `GraphicsBindings`_ 324 325 Shows the use of a custom controller, a value transformer, and two custom 326 bindings-enabled views. One view is a control that allows you to set the 327 angle and offset of a shadow; the other view observes and displays a 328 collection of graphic objects. 329 330 Originally from `Cocoa Bindings Examples and Hints`_, 331 converted to PyObjC by u.fiedler. 332 333.. _`GraphicsBindings`: CocoaBindings/GraphicsBindings 334 335* `ManualBindings`_ 336 337 A simple example that illustrates establishing bindings 338 programmatically, including a number of options such as validation 339 and an array operator, and indexed accessor methods. A custom model 340 object implements custom validation method. 341 342 Originally from `Cocoa Bindings Examples and Hints`_, 343 converted to PyObjC by u.fiedler. 344 345.. _`ManualBindings`: CocoaBindings/ManualBindings 346.. _`Cocoa Bindings Examples and Hints`: http://homepage.mac.com/mmalc/CocoaExamples/controllers.html 347 348* `TableModel`__ 349 350 Shows how to fill an ``NSTableView`` using Key-Value Coding. Contains 351 contains an ``Xcode`` project as well as a ``setup.py`` script. 352 353.. __: CocoaBindings/TableModel 354 355* `TableModelWithSearch`__ 356 357 A more advanced example of Key-Value Coding. This uses a custom 358 ``NSArrayController``. Contains contains an ``Xcode`` project 359 as well as a ``setup.py`` script. 360 361.. __: CocoaBindings/TableModelWithSearch 362 363* `TemperatureTransformer`_ 364 365 An example that uses ``NSValueTransformer`` to convert between Celsius 366 and Fahrenheit. 367 368 Based on Apple's `Value Transformers`_ documentation, 369 converted to PyObjC by u.fiedler. 370 371.. _`TemperatureTransformer`: CocoaBindings/TemperatureTransformer 372.. _`Value Transformers`: http://developer.apple.com/documentation/Cocoa/Conceptual/ValueTransformers/index.html 373 374* `ToDos`_ 375 376 Shows two array controllers, one to manage the contents of a table 377 view, the other to manage a pop-up menu in a table column. Also 378 shows two value transformers to alter the color of text. 379 380 Originally from `Cocoa Bindings Examples and Hints`_, 381 converted to PyObjC by u.fiedler. 382 383.. _`ToDos`: CocoaBindings/ToDos 384 385CoreData 386-------- 387 388The directory `CoreData`__ contains a number of examples 389that use the CoreData framework. This framework is available 390in MacOS X 10.4 and later. 391 392.. __: CoreData 393 394* `OutlineEdit`__ 395 396 A python version of the OutlineEdit example that's included with 397 Xcode 2.0. 398 399.. __: CoreData/OutlineEdit 400 401Foundation 402---------- 403 404The directory `Foundation`_ contains a number of examples 405that use only Foundation facilities. 406 407* `simple-kvo.py`__ 408 409 Demonstrates the use of Key-Value Observing from a simple 410 script, without a runloop. Requires Mac OS X 10.3 or later. 411 412.. __: Foundation/simple-kvo.py 413 414Inject 415------ 416 417The directory `Inject`_ contains a number of examples that use the 418``objc.inject`` facility to inject code into another process. These 419examples require Mac OS X 10.3 or later. 420 421.. _`Inject`: Inject 422 423* `IDNSnitch`_ 424 425 A proof of concept `IDN spoofing defense`_ for Safari (tested with 426 v1.2.4 on Mac OS X 10.3.8). Demonstrates how to write an application 427 that detects the launch of another application by bundle identifier, 428 how to use ``objc.inject`` to load code into another application, 429 how to override the implementation of an existing class but still 430 call back into the original implementation, and how to reduce the 431 size of such an application/plugin combination by using symlinks 432 to share object files (the PyObjC extensions in this case). 433 434.. _`IDNSnitch`: Inject/IDNSnitch 435.. _`IDN spoofing defense`: http://bob.pythonmac.org/archives/2005/02/07/idn-spoofing-defense-for-safari/ 436 437* `InjectInterpreter`_: 438 439 Shows how to inject an in-process Python interpreter into another 440 process. Based on the AppKit PyInterpreter example. 441 442.. _`InjectInterpreter`: Inject/InjectInterpreter 443 444* `InjectBrowser`_: 445 446 Shows how to inject an in-process Python class browser into another 447 process. Based on the AppKit ClassBrowser example. 448 449.. _`InjectBrowser`: Inject/ClassBrowser 450 451 452OpenGL 453------ 454 455The directory `OpenGL`_ contains a number of examples that use OpenGL with 456a Cocoa UI. These examples also require `PyOpenGL`__. 457 458.. _`OpenGL`: OpenGL 459.. __: http://pyopengl.sourceforge.net/ 460 461* `OpenGLDemo`__ 462 463 A simple program that shows how to use OpenGL in a Cocoa program. It is a 464 port of Apple's "CocoaGL" example. 465 466.. __: OpenGL/OpenGLDemo 467 468 469Plugins 470------- 471 472The directory `Plugins`__ contains a number of examples that embed a Python 473plugin into another application. Note that due to an implementation detail 474of the py2app bundle template, these plugins are only compatible with 475Mac OS X 10.3 and later. 476 477.. __: Plugins 478 479* `EnvironmentPrefs`__ 480 481 This ``NSPreferencePane`` can be used to edit the default environment 482 for the current user. It also is a simple example of a localized application. 483 484.. __: Plugins/EnvironmentPrefs 485 486* `ProgressViewPalette`__ 487 488 A simple InterfaceBuilder palette written in Python. 489 490.. __: Plugins/ProgressViewPalette 491 492* `SillyBallsSaver`__ 493 494 A simple screensaver written in Python. 495 496.. __: Plugins/SillyBallsSaver 497 498* `WebKitInterpreter`__ 499 500 Uses the new WebKit Cocoa plugin API available in Safari 1.3 501 and later to embed a PyInterpreter in the browser. 502 503.. __: Plugins/WebKitInterpreter 504 505Twisted Integration 506------------------- 507 508The directory `Twisted`_ contains a number of examples that use 509`Twisted (2.0 or later)`__ with Cocoa. 510 511.. _`Twisted`: Twisted 512.. __: http://www.twistedmatrix.com 513 514* `WebServicesTool`__ 515 516 This is a refactor of the WebServicesTool example that is made much simpler 517 and faster by using Twisted. 518 519.. __: Twisted/WebServicesTool 520 521* `WebServicesTool-ControllerLayer`__ 522 523 This is an even simpler refactor of the Twisted WebServicesTool example that 524 uses Cocoa Bindings to remove a lot of the UI related code. 525 526.. __: Twisted/WebServicesTool-ControllerLayer 527 528 529WebKit 530------ 531 532The directory `WebKit`__ contains a number of examples that use the ``WebKit`` 533framework, the HTML rendering engine from Safari. 534 535.. __: WebKit 536 537* `PyDocURLProtocol`__ 538 539 This example implements a subclass of ``NSURLProtocol`` that can be used 540 to load the ``pydoc`` documentation of a module. 541 542 It also includes a simple documentation browser using ``WebKit`` and the 543 ``PyDocURLProtocol`` class. 544 545.. __: WebKit/PyDocURLProtocol 546 547 548Some work-in-progress examples 549------------------------------ 550 551The directory `NonFunctional`__ may contain a number of examples that are not working 552for one reason or another. The most likely reason is that example relies on features 553that have not yet been implemented. 554 555.. __: NonFunctional 556