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