[PyObjC-svn] r2230 - in trunk/pyobjc/pyobjc-core: . Doc Doc/06tutorial Doc/07tutorial_embed Scripts source-deps
[email protected] Thu, 21 May 2009 08:01:51 -0500
| Newsgroups | gmane.comp.python.pyobjc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: ronaldoussoren
Date: Thu May 21 08:01:50 2009
New Revision: 2230
Log:
* Remove some old junk
* Replace literal blocks in documentation by
sourcecode directives, this allows us to create
a slightly nicer website.
Still todo: seriously clean up and update the
documentation.
Added:
trunk/pyobjc/pyobjc-core/Doc/22fsref-fsspec.txt
- copied, changed from r2228, /trunk/pyobjc/pyobjc-core/Doc/fsref-fsspec.txt
Removed:
trunk/pyobjc/pyobjc-core/Doc/53todo.txt
trunk/pyobjc/pyobjc-core/Doc/fsref-fsspec.txt
trunk/pyobjc/pyobjc-core/Scripts/
trunk/pyobjc/pyobjc-core/source-deps/
Modified:
trunk/pyobjc/pyobjc-core/Doc/01intro.txt
trunk/pyobjc/pyobjc-core/Doc/06tutorial/index.txt
trunk/pyobjc/pyobjc-core/Doc/07tutorial_embed/index.txt
trunk/pyobjc/pyobjc-core/Doc/21protocols.txt
trunk/pyobjc/pyobjc-core/Doc/49structure.txt
trunk/pyobjc/pyobjc-core/Doc/54wrapping.txt
trunk/pyobjc/pyobjc-core/NEWS.txt
Modified: trunk/pyobjc/pyobjc-core/Doc/01intro.txt
==============================================================================
--- trunk/pyobjc/pyobjc-core/Doc/01intro.txt (original)
+++ trunk/pyobjc/pyobjc-core/Doc/01intro.txt Thu May 21 08:01:50 2009
@@ -47,13 +47,17 @@
positional arguments, but parts of the message name (called "selector"
in Objective-C terminology) are interleaved with the arguments.
-An Objective-C message looks like this::
+An Objective-C message looks like this:
- [someObject doSomething:arg1 withSomethingElse:arg2];
+ .. sourcecode:: objective-c
-The selector (message name) for the above snippet is this (note the colons)::
+ [someObject doSomething:arg1 withSomethingElse:arg2];
- doSomething:withSomethingElse:
+The selector (message name) for the above snippet is this (note the colons):
+
+ .. sourcecode:: objective-c
+
+ doSomething:withSomethingElse:
In order to have a lossless and unambiguous translation between Objective-C
messages and Python methods, the Python method name equivalent is simply
@@ -62,22 +66,28 @@
underscores in the PyObjC-ified method name is the number of arguments
that should be given.
-The PyObjC translation of the above selector is (note the underscores)::
+The PyObjC translation of the above selector is (note the underscores):
+
+ .. sourcecode:: python
- doSomething_withSomethingElse_
+ doSomething_withSomethingElse_
-The message dispatch, translated to PyObjC, looks like this::
+The message dispatch, translated to PyObjC, looks like this:
- someObject.doSomething_withSomethingElse_(arg1, arg2)
+ .. sourcecode:: python
+
+ someObject.doSomething_withSomethingElse_(arg1, arg2)
*Methods that take one argument will have a trailing underscore*.
It may take a little while to get used to, but PyObjC does not ever
rename selectors. The trailing underscore will seem strange at first,
-especially for cases like this::
+especially for cases like this:
+
+ .. sourcecode:: python
- # note the trailing underscore
- someObject.setValue_(aValue)
+ # note the trailing underscore
+ someObject.setValue_(aValue)
There are a few additional rules regarding message dispatch, see the
`Overview of the bridge`_ for the complete rundown.
@@ -99,13 +109,17 @@
In Objective-C, the convention is for allocation to be performed by a class
method called ``alloc``, and initialization is done with method
*beginning with* the word ``init``. For example, here is the syntax for
-instantiating an ``NSObject``::
+instantiating an ``NSObject``:
- myObject = NSObject.alloc().init()
+ .. sourcecode:: python
-And here is an example for creating an ``NSData`` instance given a few bytes::
+ myObject = NSObject.alloc().init()
- myData = NSData.alloc().initWithBytes_length_('the bytes', 9)
+And here is an example for creating an ``NSData`` instance given a few bytes:
+
+ .. sourcecode:: python
+
+ myData = NSData.alloc().initWithBytes_length_('the bytes', 9)
You must also follow this convention when subclassing Objective-C classes.
When initializing, an object must always (directly or indirectly) call the
@@ -114,9 +128,12 @@
The designated initializer for ``NSObject`` is ``init``. To find the
designated initializer for other classes, consult the documentation for that
class. Here is an example of an ``NSObject`` subclass with a customized
-initialization phase::
+initialization phase:
- class MyClass(NSObject):
+ .. sourcecode:: python
+ :linenos:
+
+ class MyClass(NSObject):
def init(self):
"""
@@ -134,7 +151,8 @@
# because they are allowed to return any object!
return self
- class MyOtherClass(MyClass):
+
+ class MyOtherClass(MyClass):
def initWithOtherVariable_(self, otherVariable):
"""
@@ -146,11 +164,14 @@
self.otherVariable = otherVariable
return self
- myInstance = MyClass.alloc().init()
- myOtherInstance = MyOtherClass.alloc().initWithOtherVariable_(20)
+ myInstance = MyClass.alloc().init()
+ myOtherInstance = MyOtherClass.alloc().initWithOtherVariable_(20)
Many Objective-C classes provide class methods that perform two-phase
-instantiation for you in one step. Several examples of this are::
+instantiation for you in one step. Several examples of this are:
+
+ .. sourcecode:: python
+ :linenos:
# This is equivalent to:
#
@@ -176,7 +197,10 @@
Unlike Python, Objective-C convention says to use accessors rather than
directly accessing instance variables of other objects. This means
that in order to access an instance variable ``value`` of an object
-``valueContainer`` you will have to use the following syntax::
+``valueContainer`` you will have to use the following syntax:
+
+ .. sourcecode:: python
+ :linenos:
# Getting
#
@@ -193,7 +217,10 @@
When writing your own classes from Python, this is a bit harder since
Python only has one namespace for all attributes, even methods. If you
choose to implement accessors from Python, then you will have to name
-the instance variable something else::
+the instance variable something else:
+
+ .. sourcecode:: python
+ :linenos:
class MyValueHolder(NSObject):
@@ -248,11 +275,15 @@
the implementation is between ``@implementation`` and ``@end``. An expression
enclosed in brackets in Objective-C is called a message, and is the equivalent
to an instance method invocation in Python. For example, this Objective-C
-code::
+code:
+
+ .. sourcecode:: objective-c
[aMutableArray addObject:@"constant string"];
-Is equivalent in intent to the following in Python::
+Is equivalent in intent to the following in Python:
+
+ .. sourcecode:: python
aList.append(u"constant string")
@@ -266,7 +297,9 @@
quite different. Objective-C messages can not have default arguments, and all
arguments are passed in a specific order. The components of a selector may not
be reordered. Syntactically, one argument must be interleaved at every colon in
-the selector. The message::
+the selector. The message:
+
+ .. sourcecode:: objective-c
[anArray indexOfObject:someObject inRange:someRange]
@@ -280,14 +313,19 @@
``someObject``, ``someRange``
As documented later, the straightforward translation of such a message to
-Python is::
+Python is:
+
+ .. sourcecode:: python
anArray.indexOfObject_inRange_(someObject, someRange)
This may be awkward and "unpythonic" at first, however this syntax is necessary
to preserve the semantics of Objective-C message dispatch.
-A class declaration::
+A class declaration:
+
+ .. sourcecode:: objective-c
+ :linenos:
@interface MyClass : MySuperClass
{
@@ -309,7 +347,10 @@
-(int)anotherInstanceVariable;
@end
-A class implementation::
+A class implementation:
+
+ .. sourcecode:: objective-c
+ :linenos:
@implementation MyClass
@@ -476,9 +517,17 @@
in the method name; exceptions to this rule and the behavior of "result"
are mentioned below.
- - ``result = [someObject someMethod:firstArg withFoo:foo andBar:bar];``
- translates to
- ``result = someObject.someMethod_withFoo_andBar_(firstArg, foo, bar)``
+ .. sourcecode:: objective-c
+ :linenos:
+
+ result = [someObject someMethod:firstArg withFoo:foo andBar:bar];
+
+ translates to
+
+ .. sourcecode:: python
+ :linenos:
+
+ result = someObject.someMethod_withFoo_andBar_(firstArg, foo, bar)
Note that it is currently not possible to support methods with a variable
number of arguments from Python. These selectors must be wrapped by
@@ -546,11 +595,16 @@
it turns out this is very straightforward when working with them.
As an example of a method with two output arguments, ``NSMatrix`` implements a
-selector named ``getNumberOfRows:columns:`` with the following signature::
+selector named ``getNumberOfRows:columns:`` with the following signature:
- (void)getNumberOfRows:(int *)rowCount columns:(int *)columnCount
-This method is used from Python like this::
+ .. sourcecode:: objective-c
+
+ -(void)getNumberOfRows:(int *)rowCount columns:(int *)columnCount
+
+This method is used from Python like this:
+
+ .. sourcecode:: python
rowCount, columnCount = matrix.getNumberOfRows_columns_(None, None)
@@ -588,7 +642,10 @@
For complete control of the mapping to Objective-C you can use the function
``objc.selector`` to create custom descriptors. See the documentation of the
``objc`` module for the arguments you can use with this function. It is
-normally used like this::
+normally used like this:
+
+ .. sourcecode:: python
+ :linenos:
class MyObject(NSObject):
@@ -598,7 +655,10 @@
someMethod_ = objc.selector(someMethod_, signature='v@:f')
-From Python 2.4, there is a decorator for this purpose::
+In Python 2.4 or later there is a decorator for this purpose:
+
+ .. sourcecode:: python
+ :linenos:
class MyObject(NSObject):
@@ -703,7 +763,10 @@
existing classes, for splitting classes in several parts and to document
informal protocols.
-An example of a category definition::
+An example of a category definition:
+
+ .. sourcecode:: objective-c
+ :linenos:
@interface NSObject (MyCategory)
- (NSSize)objectFootprint;
@@ -713,7 +776,10 @@
a single method.
The function ``objc.classAddMethods`` can be used to get the same effect in
-Python::
+Python:
+
+ .. sourcecode:: python
+ :linenos:
def objectFootprint(self):
pass
@@ -721,7 +787,10 @@
objc.classAddMethods(NSObject, [objectFootprint])
This is not very clear, PyObjC therefore also provides the following
-mechanism, implemented on top of ``objc.classAddMethods``::
+mechanism, implemented on top of ``objc.classAddMethods``:
+
+ .. sourcecode:: python
+ :linenos:
class NSObject(objc.Category(NSObject)):
def objectFootprint(self):
@@ -832,7 +901,10 @@
Most of Cocoa, and thus PyObjC, requires an ``NSAutoreleasePool`` in order to function
properly. PyObjC does this automatically on the first thread it is imported from,
but other threads will require explicit ``NSAutoreleasePool`` management. The following
-practice for working with ``NSAutoreleasePool`` is recommended::
+practice for working with ``NSAutoreleasePool`` is recommended:
+
+ .. sourcecode:: python
+ :linenos:
pool = NSAutoreleasePool.alloc().init()
...
@@ -909,7 +981,10 @@
offers a way to build distutils scripts for building (standalone)
applications and plugin bundles.
-An example ``setup.py`` script::
+An example ``setup.py`` script:
+
+ .. sourcecode:: python
+ :linenos:
from distutils.core import setup
import py2app
@@ -919,9 +994,11 @@
data_files = ["English.lproj"],
)
-During development you typically invoke it from the command line like this::
+During development you typically invoke it from the command line like this:
- python setup.py py2app -A
+ .. sourcecode:: sh
+
+ $ python setup.py py2app -A
This will build an application bundle in a folder named ``dist`` in the
current folder. The ``-A`` option tells ``py2app`` to add symbolic
@@ -937,9 +1014,11 @@
For more information about ``py2app`` usage, read through some of the
``setup.py`` scripts used by the examples in the `Examples`__ folder.
On any ``setup.py`` script that imports ``py2app``, you can use the
-following command to see the list of options::
+following command to see the list of options:
+
+ .. sourcecode:: sh
- python setup.py py2app --help
+ $ python setup.py py2app --help
.. __: ../Examples/00ReadMe.txt
Modified: trunk/pyobjc/pyobjc-core/Doc/06tutorial/index.txt
==============================================================================
--- trunk/pyobjc/pyobjc-core/Doc/06tutorial/index.txt (original)
+++ trunk/pyobjc/pyobjc-core/Doc/06tutorial/index.txt Thu May 21 08:01:50 2009
@@ -2,6 +2,8 @@
Creating your first PyObjC application.
=======================================
+WARNING: This tutorial is not valid for the current edition of PyObjC.
+
In this tutorial you will learn how to create your first Python Cocoa
application: a simple dialog that allows you to convert amounts of money from
one currency to another. Definitely easier to do with a calculator, but in the
@@ -50,12 +52,16 @@
4. Create the skeleton Python script by running the ``nibclassbuilder`` script.
``nibclassbuilder`` will parse the NIB file and create a skeleton module for
- you. Invoke it as follows (from the ``src`` directory)::
+ you. Invoke it as follows (from the ``src`` directory):
+
+ .. sourcecode:: sh
$ python -c "import PyObjCScripts.nibclassbuilder" MainMenu.nib > CurrencyConverter.py
Depending on your installation, the ``nibclassbuilder`` script may be on your ``$PATH``.
- If so, it can be invoked as such::
+ If so, it can be invoked as such:
+
+ .. sourcecode:: sh
$ nibclassbuilder MainMenu.nib > CurrencyConverter.py
@@ -67,7 +73,10 @@
--------------------------
5. Now we need to create an build script for CurrencyConverter. To do this,
- create a file named ``setup.py`` with the following contents::
+ create a file named ``setup.py`` with the following contents:
+
+ .. sourcecode:: python
+ :linenos:
from distutils.core import setup
import py2app
@@ -82,7 +91,9 @@
.. _step5-setup.py: step5-setup.py.html
6. Run the setup script to create a temporary application bundle for
- development::
+ development:
+
+ .. sourcecode:: sh
$ python setup.py py2app -A
@@ -100,13 +111,17 @@
- double-click ``dist/CurrencyConverter`` from the Finder
(you won't see the .app extension)
- - open it from the terminal with::
+ - open it from the terminal with:
+
+ .. sourcecode:: sh
- $ open dist/CurrencyConverter.app
+ $ open dist/CurrencyConverter.app
- run it directly from the Terminal, as::
+
+ .. sourcecode:: sh
- $ ./dist/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
+ $ ./dist/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
The last method is typically the best to use for development: it leaves
stdout and stderr connected to your terminal session so you can see what
@@ -131,13 +146,17 @@
section "Implementing Currency Converter's Classes". To translate this
Objective C code to Python syntax, we will need to do some name mangling of
the selectors. See *An introduction to PyObjC* for the details, but the
- short is that::
+ short is that:
+
+ .. sourcecode:: objective-c
[anObject modifyArg: arg1 andAnother: arg2]
translates into the following Python code, by replacing the colons in the
selector with underscores, and passing the arguments as you would with a
- normal Python method call::
+ normal Python method call:
+
+ .. sourcecode:: python
anObject.modifyArg_andAnother_(arg1, arg2)
@@ -192,7 +211,9 @@
what sort of spectacular crash we get. Alas, nothing spectacular about it:
when the NIB is loaded the Cocoa runtime system tries to make the
connection, notices that we have no ``invertRate_()`` method in our
- ``ConverterController`` class and it gives an error message::
+ ``ConverterController`` class and it gives an error message:
+
+ .. sourcecode:: sh
$ ./dist/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
2004-12-09 03:29:09.957 CurrencyConverter[4454] Could not connect the action
@@ -214,7 +235,9 @@
offering the choice of continuing or quitting.
To debug this application with pdb, start the application with the
- following command line::
+ following command line:
+
+ .. sourcecode:: sh
$ env USE_PDB=1 ./dist/CurrencyConverter.app/Contents/MacOS/CurrencyConverter
@@ -234,7 +257,9 @@
simply just move it to the ``Applications`` folder (or anywhere else) and
insulate it from the original source code.
-This can be done with the following steps from the ``src`` directory::
+This can be done with the following steps from the ``src`` directory:
+
+ .. sourcecode: sh
$ rm -rf dist
$ python setup.py py2app
Modified: trunk/pyobjc/pyobjc-core/Doc/07tutorial_embed/index.txt
==============================================================================
--- trunk/pyobjc/pyobjc-core/Doc/07tutorial_embed/index.txt (original)
+++ trunk/pyobjc/pyobjc-core/Doc/07tutorial_embed/index.txt Thu May 21 08:01:50 2009
@@ -34,9 +34,11 @@
Follow these steps:
1. Make a copy of ``/Developer/Examples/AppKit/SimpleComboBox`` to work on.
- Let's call this ``SimpleComboBoxPlus``::
+ Let's call this ``SimpleComboBoxPlus``:
+
+ .. sourcecode: sh
- $ cp -R /Developer/Examples/AppKit/SimpleComboBox SimpleComboBoxPlus
+ $ cp -R /Developer/Examples/AppKit/SimpleComboBox SimpleComboBoxPlus
From this point on, all shell commands take place from this
``SimpleComboBoxPlus`` folder.
@@ -61,7 +63,10 @@
simply copy ``ITunesCommunication_1.py`` to ``ITunesCommunication.py``.
8. Now we need to create the build script for our plugin, create a file named
- ``setup.py`` with the following contents::
+ ``setup.py`` with the following contents:
+
+
+ .. sourcecode:: python
from distutils.core import setup
import py2app
@@ -72,7 +77,9 @@
You may also copy this file from ``setup.py``.
-9. Run the setup script to create a temporary plugin bundle for development::
+9. Run the setup script to create a temporary plugin bundle for development:
+
+ .. sourcecode: sh
$ python setup.py py2app -A
@@ -92,6 +99,8 @@
11. Open ``main.m``, it is in the "Other Sources" folder in your Xcode
project, and change the main(...) function to the following::
+ .. sourcecode:: objective-c
+
int main(int argc, const char *argv[]) {
NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
NSString *pluginPath = [[NSBundle mainBundle]
@@ -120,7 +129,9 @@
standard way to generate this package (start the application, ask it for
its terminology) does not work, so we have to actually look into the
bowels of ``iTunes.app``. This leads to the following hefty command line
- which you should run in the ``SimpleComboBoxPlus`` directory::
+ which you should run in the ``SimpleComboBoxPlus`` directory:
+
+ .. sourcecode:: sh
$ cd SimpleComboBoxPlus
$ pythonw -c "from gensuitemodule import main;main()" \
@@ -136,7 +147,9 @@
active. All that is left as an exercise to the reader.
16. To make this application redistributable, perform the following commands
- to make the plugin redistributable::
+ to make the plugin redistributable:
+
+ .. sourcecode:: sh
$ rm -rf dist
$ python setup.py py2app
Modified: trunk/pyobjc/pyobjc-core/Doc/21protocols.txt
==============================================================================
--- trunk/pyobjc/pyobjc-core/Doc/21protocols.txt (original)
+++ trunk/pyobjc/pyobjc-core/Doc/21protocols.txt Thu May 21 08:01:50 2009
@@ -7,7 +7,9 @@
Apple makes use of both formal and informal protocols in the Cocoa framework.
Formal protocols are those protocols that are implemented using Objective-C
-protocols::
+protocols:
+
+ .. sourcecode:: objective-c
@protocol NSFoo <NSSomeProtocol>
-(int)doesIt;
@@ -17,7 +19,9 @@
declare that it implements that protocol, and the implementation must implement
all methods of the protocol.
-Informal protocols are defined as categories on NSObject with no implementation::
+Informal protocols are defined as categories on NSObject with no implementation:
+
+ .. sourcecode:: objective-c
@interface NSObject(FooDelegate)
-(void)optionalFooDelegateMethod;
@@ -56,7 +60,10 @@
protocols, and drop the informal_protocol wrappers for formal protocols.
Declaring conformance to a formal protocol is done by using the formal protocol
-as a mix-in, and by implementing its methods::
+as a mix-in, and by implementing its methods:
+
+ .. sourcecode:: python
+ :linenos:
NSLocking = objc.protocolNamed('NSLocking')
@@ -70,7 +77,9 @@
XXX: Change this example when the pyobjc_classMethods hack is no longer necessary.
The class now formally implements the ``NSLocking`` protocol, this can be
-verified using the Objective-C introspection methods::
+verified using the Objective-C introspection methods:
+
+ .. sourcecode:: pycon
>>> MyLockingObject.pyobjc_classMethods.conformsToProtocol_(NSLocking)
1
Copied: trunk/pyobjc/pyobjc-core/Doc/22fsref-fsspec.txt (from r2228, /trunk/pyobjc/pyobjc-core/Doc/fsref-fsspec.txt)
==============================================================================
--- /trunk/pyobjc/pyobjc-core/Doc/fsref-fsspec.txt (original)
+++ trunk/pyobjc/pyobjc-core/Doc/22fsref-fsspec.txt Thu May 21 08:01:50 2009
@@ -9,7 +9,9 @@
This type represents an opaque ``FSRef`` structure.
-New instances are created using the ``from_pathname`` method::
+New instances are created using the ``from_pathname`` method:
+
+ .. sourcecode: pycon
>>> ref = objc.FSRef.from_pathname("/Libray")
>>> isinstance(ref, objc.FSRef)
@@ -39,7 +41,7 @@
arguments.
Type ``objc.FSSpec``
--------------------
+--------------------
This type represents an opaque ``FSSpec`` structure. It is not possible
to create ``FSSpec`` instances in Python code.
Modified: trunk/pyobjc/pyobjc-core/Doc/49structure.txt
==============================================================================
--- trunk/pyobjc/pyobjc-core/Doc/49structure.txt (original)
+++ trunk/pyobjc/pyobjc-core/Doc/49structure.txt Thu May 21 08:01:50 2009
@@ -51,38 +51,15 @@
Example scripts and applets.
Lib/
- The pure Python parts of the packages that comprise PyObjC. Currently
- contains the packages 'objc', 'PyObjCScripts', 'PyObjCTools' and the
- semi-automatically generated wrappers for the 'AddressBook',
- 'AppKit', 'ExceptionHandling', 'Foundation', 'InterfaceBuilder', 'Message',
- 'PreferencePanes', 'ScreenSaver', 'SecurityInterface' and 'WebKit'
- frameworks.
+ The pure Python parts of the packages that comprise PyObjC.
Modules/
Extension modules related to the packages in 'Lib'.
-Scripts/
- Scripts used during building and/or development of PyObjC.
-
-Installer Package/
- Resources used for building the Apple Installer packages.
-
-Xcode/
- Xcode templates for PyObjC development.
-
libffi-src/
A local copy of libffi, the Foreign Function Interface library used by
PyObjC.
-setup-lib/
- Modules used by setup.py for building and distributing PyObjC.
-
-source-deps/
- Local copies of Python packages and modules used by PyObjC that are not
- expected to be found in the minimum supported version of Python. These
- are not automatically installed by setup.py, but some may be included in
- a bdist_mpkg installer (currently, just py2app).
-
Reference counts
----------------
@@ -123,12 +100,17 @@
text. It is recommended that you use ``unicode`` whenever possible. In order
to help you determine where you are not using ``unicode``, it is possible
to trigger an ``objc.PyObjCStrBridgeWarning`` warning whenever a ``str``
-instance crosses the bridge::
+instance crosses the bridge:
+
+
+ .. sourcecode:: python
import objc
objc.setStrBridgeEnabled(False)
-To promote these to an exception, do the following::
+To promote these to an exception, do the following:
+
+ .. sourcecode:: python
import objc
import warnings
Modified: trunk/pyobjc/pyobjc-core/Doc/54wrapping.txt
==============================================================================
--- trunk/pyobjc/pyobjc-core/Doc/54wrapping.txt (original)
+++ trunk/pyobjc/pyobjc-core/Doc/54wrapping.txt Thu May 21 08:01:50 2009
@@ -17,12 +17,14 @@
The basics
----------
-The code for loading a framework and exporting its classes is pretty simple::
+The code for loading a framework and exporting its classes is pretty simple:
- import objc
- objc.loadBundle("MyFramework", globals(),
- bundle_path=objc.pathForFramework(u'/path/to/MyFramework.framework'))
- del objc
+ .. sourcecode: python
+
+ import objc
+ objc.loadBundle("MyFramework", globals(),
+ bundle_path=objc.pathForFramework(u'/path/to/MyFramework.framework'))
+ del objc
In general you should not load frameworks this way, but you should write a
package or module to do this for you (e.g. place this code in
@@ -72,7 +74,9 @@
'out' (data is returned from the function) or 'inout' (data is passed into
and then returned from the function).
-Given the following class interface::
+Given the following class interface:
+
+ .. sourcecode: objective-c
@interface ClassName {}
@@ -91,7 +95,9 @@
Let's say the first argument is an output parameter. Output parameters are
denoted in the signature string using the character 'o' before the actual
argument signature. The 'correct' signature for method is therefore 'v@:o^@@'.
-The following code tells the bridge about this better method signature::
+The following code tells the bridge about this better method signature:
+
+ .. sourcecode: python
import objc
objc.setSignatureForSelector("ClassName", "selector:withArguments:",
@@ -106,6 +112,9 @@
- input-output parameter: N
+***NOTE:*** The bridge currently supports two other ways to describe metadata,
+which aren't properly documented at the moment.
+
special wrappers
................
@@ -131,5 +140,3 @@
``objc.informal_protocol`` objects for those protocols to your module. These
can be defined in a submodule, as long as you arrange for that module to be
loaded whenever someone imports your package.
-
-See ``Lib/Foundation/protocols.py`` for examples of protocol definitions.
Modified: trunk/pyobjc/pyobjc-core/NEWS.txt
==============================================================================
--- trunk/pyobjc/pyobjc-core/NEWS.txt (original)
+++ trunk/pyobjc/pyobjc-core/NEWS.txt Thu May 21 08:01:50 2009
@@ -26,30 +26,36 @@
- BUGFIX: Enable building from source with the Python.org binary distribution.
- BUGFIX: Fix crash when using the animotor proxy feature of CoreAnimation.
- That is, the following code now works::
+ That is, the following code now works:
- app = NSApplication.sharedApplication()
- window = NSWindow.alloc().init()
- anim = window.animator()
- anim.setAlphaValue_(1.0)
+ .. sourcecode:: python
+ :linenos:
+
+ app = NSApplication.sharedApplication()
+ window = NSWindow.alloc().init()
+ anim = window.animator()
+ anim.setAlphaValue_(1.0)
- Improve handling of non-methods in objc.Category:
* The docstring of a category is now ignored
- * You'll get an explict error exception when trying to add ``ivar``s to
+ * You'll get an explict error exception when trying to add and ``ivar`` to
a class
- * It's now possible to add class attributes in a category::
-
- class NSObject (objc.Category(NSObject)):
- aClassDefault = [ 1, 2, 3 ]
+ * It's now possible to add class attributes in a category:
- @classmethod
- def getDefault(cls):
- return cls.aClassDefault
+ .. sourcecode:: python
+ :linenos:
+ class NSObject (objc.Category(NSObject)):
+ aClassDefault = [ 1, 2, 3 ]
+
+ @classmethod
+ def getDefault(cls):
+ return cls.aClassDefault
+
- Fixed support for ``FSRef`` and ``FSSpec`` structures.
@@ -87,17 +93,23 @@
instead. The ``objc.context`` registry allows you to get a context
integer for an arbitrary Python object, and retrieve that later on.
- To get the context integer for a Python object::
-
- ctx = objc.context.register(myValue)
+ To get the context integer for a Python object:
+
+ .. sourcecode:: python
+
+ ctx = objc.context.register(myValue)
+
+ To unregister the object when you no longer need the context integer:
- To unregister the object when you no longer need the context integer::
+ .. sourcecode:: python
- objc.context.unregister(myValue)
+ objc.context.unregister(myValue)
- To retrieve the Python object given a context integer::
+ To retrieve the Python object given a context integer:
- myValue = objc.context.get(ctx)
+ .. sourcecode:: python
+
+ myValue = objc.context.get(ctx)
NOTE: This API is particularly handy when using Key-Value Observing, where
@@ -127,8 +139,6 @@
instances before using them from Objective-C (such as using an
``NSDateFormatter``)
- using an ``NSKeyedArchiver``.
-
- Objective-C classes that support the ``NSCopying`` protocol can now be
copied using ``copy.copy`` as well.
@@ -144,13 +154,16 @@
- Pure Python objects now support the ``NSCopying`` protocol.
- A new decorator: ``objc.namedselector`` for overriding the Objective-C
- selector. Usage::
+ selector. Usage:
- class MyObject (NSObject):
+ .. sourcecode:: python
+ :linenos:
- @objc.namedselector("foo:bar:")
- def foobar(self, foo, bar):
- pass
+ class MyObject (NSObject):
+
+ @objc.namedselector("foo:bar:")
+ def foobar(self, foo, bar):
+ pass
- A number of new type signature values were added. These are not present
in the Objective-C runtime, but are used to more precisely describe the
@@ -158,19 +171,19 @@
The new values are:
- * _C_UNICHAR: A "UniChar" value in Objective-C
+ * ``_C_UNICHAR``: A "UniChar" value in Objective-C
- * _C_NSBOOL: A "BOOL" value in Objective-C
+ * ``_C_NSBOOL``: A "BOOL" value in Objective-C
- * _C_CHAR_AS_INT: A "char" in Objective-C that is used as a number
+ * ``_C_CHAR_AS_INT``: A "char" in Objective-C that is used as a number
- * _C_CHAR_AS_TEXT: A "char" in Objective-C that is used as a character
+ * ``_C_CHAR_AS_TEXT``: A "char" in Objective-C that is used as a character
PyObjC will automaticly translate these values into the correct Objective-C
type encoding when communicating with the Objective-C runtime, making this
change transparent to anyone but Python users.
- NOTE: _C_CHR is of course still supported, with the same semi-schizofrenic
+ NOTE: ``_C_CHR`` is of course still supported, with the same semi-schizofrenic
behaviour as always.
NOTE2: The non-standard metadata extensions we used before to indicate
@@ -216,7 +229,10 @@
unwanted side-effect of how CoreFoundation types are wrapped.
- BUGFIX: The docstring for newly defined methods is no longer hidden
- by PyObjC. That is, given this code::
+ by PyObjC. That is, given this code:
+
+ .. sourcecode:: python
+ :linenos:
class MyObject (NSObject):
def doit(self):
@@ -227,7 +243,9 @@
versions of PyObjC the docstring was ``None``.
- BUGFIX: Fixed calling and implementation methods where one or more
- of the arguments are defined as arrays, like this::
+ of the arguments are defined as arrays, like this:
+
+ .. sourcecode:: objective-c
-(void)fooCallback:(NSRect[4])rects;
@@ -258,16 +276,23 @@
releases the '@synchronized' mutex for an object, and can also be used
manually.
- That is (as context manager)::
- from __future__ import with_statement
+ That is (as context manager):
- obj = NSObject.new()
+ .. sourcecode:: python
+ :linenos:
+ from __future__ import with_statement
+
+ obj = NSObject.new()
+
with objc.object_lock(obj):
- # Perform work while owning the @synchronize lock
- pass
+ # Perform work while owning the @synchronize lock
+ pass
+
+ or (manually):
- or (manually)::
+ .. sourcecode:: python
+ :linenos:
obj = NSObject.new()
mutex = objc.object_lock(obj)
@@ -278,8 +303,8 @@
finally:
mutex.unlock()
- Note that the first version is slightly saver (see the documentation
- for with-statements for the details).
+ Note that the first version is slightly saver (see the documentation
+ for with-statements for the details).
Version 2.0 (MacOS X 10.5.0)
----------------------------
@@ -318,18 +343,24 @@
- It is now conveniently possible to create instance variables with
a specific type (e.g. without manually making up a encoded type
- string)::
+ string):
- class MyObject (NSObject):
- bounds = objc.ivar.NSRect()
- done = objc.ivar.bool()
+ .. sourcecode:: python
+ :linenos:
+
+ class MyObject (NSObject):
+ bounds = objc.ivar.NSRect()
+ done = objc.ivar.bool()
- Objective-C metaclasses are modelled as Python metaclasses. This brings
- a major improvement: class methods "just work"(TM)::
+ a major improvement: class methods "just work"(TM):
+
+ .. sourcecode:: python
+ :linenos:
o = NSObject.alloc().init()
o.description()
-
+
NSObject.description()
In earlier versions of PyObjC the second call would fail because
@@ -362,13 +393,16 @@
for supercalls for Objective-C class methods.
- It is now easily possible to tell PyObjC that a Python type should be
- treated like a builtin sequence type::
+ treated like a builtin sequence type:
- import UserList, objc
+ .. sourcecode:: python
+ :linenos:
+ import UserList, objc
+
class MyClass (UserList.UserList):
- pass
-
+ pass
+
objc.registerListType(MyClass)
- And likewise for mapping types using ``objc.registerMappingType``.
@@ -380,8 +414,10 @@
- The unittests can now use the leaks(1) command to check for memory leaks. This
slows testing down significantly and is therefore off by default. Enable by
setting ``PYOBJC_WITH_LEAKS`` to a value in the shell environment before running
- the tests::
-
+ the tests:
+
+ .. sourcecode:: sh
+
$ PYOBJC_WITH_LEAKS=1 python setup.py test
NOTE: the actual value is ignored, as long as there is a value.
@@ -389,11 +425,14 @@
- (BUGFIX): PyObjC was leaking memory when doing scans of the Objective-C method tables
- (BUGFIX): The code below now raises an error, as it should have done in previous versions but never
- did::
+ did:
+
+ .. sourcecode:: python
+ :linenos:
class MyObject (object):
- def updateDescription(self):
- self.description = 42
+ def updateDescription(self):
+ self.description = 42
- PyObjC has been split into several smaller packages: ``pyobjc-core`` contains
@@ -402,14 +441,20 @@
- Objective-C objects now have an implicit attribute named ``_`` which can
be used a shortcut for Key-Value-Coding.
- The code fragment below::
+ The code fragment below:
+
+ .. sourcecode:: python
+ :linenos:
o = <Some Objective-C Object>
print o._.myKey
o._.myKey = 44
- is equivalent to::
+ is equivalent to:
+ .. sourcecode:: python
+ :linenos:
+
print o.valueForKey_('myKey')
o.setValue_forKey_(44, 'myKey')
@@ -445,7 +490,9 @@
will still convert MacPython CF-wrappers to the right native type.
Another backward compatible change: ``registerCFSignature`` has a different
- signature::
+ signature:
+
+ .. sourcecode:: python
registerCFSignature(name, encoding, typeId [, tollfreeName]) -> type
@@ -454,7 +501,10 @@
- This version introduces generic support for callback functions. The metadata
metioned before contains information about the signature for callback
functions, the decorator ``callbackFor`` converts a plain function to
- one that can be used as a callback::
+ one that can be used as a callback:
+
+ .. sourcecode:: python
+ :linenos:
@objc.callbackFor(NSArray.sortedArrayUsingFunction_andContext_)
def compare(left, right, context):
@@ -472,7 +522,9 @@
- The decorator ``selectorFor`` can be used to ensure that a method has the
right signature to be used as the callback method for a specific method.
- Usage::
+ Usage:
+
+ .. sourcecode:: python
@objc.selectorFor(NSApplication.beginSheet_modalForWindow_modalDelegate_didEndSelector_contextInfo_)
def sheetDidEnd_returnCode_contextInfo_(self, sheet, returnCode, info):
@@ -552,14 +604,18 @@
There are two functions for adding new convenience methods:
* ``addConvenienceForSelector`` adds a list of methods to a class when that
- class has the specified selector::
+ class has the specified selector:
+
+ .. sourcecode:: python
addConvenienceForSelector('hash', [
('__hash__', lambda self: self.hash()),
])
* ``addConvenienceForClass`` adds a list of methods to the class with the
- specified name::
+ specified name:
+
+ .. sourcecode:: python
addConvenienceForSelector('NSObject', [
('dummy', lambda self: 42 ),
@@ -750,11 +806,13 @@
object, among other things.
- New objc.signature decorator that allows easier specification of
- objc.selector wrappers for functions when using Python 2.4::
+ objc.selector wrappers for functions when using Python 2.4:
- @objc.signature('i@:if')
- def methodWithX_andY_(self, x, y):
- return 0
+ .. sourcecode:: python
+
+ @objc.signature('i@:if')
+ def methodWithX_andY_(self, x, y):
+ return 0
- ``PyObjCTools.KeyValueCoding.getKeyPath`` now supports all of the
Array Operators supported by Mac OS X 10.4.
@@ -901,17 +959,21 @@
that the class directly claims to conform to.
- PyObjC classes can now declare that they implement formal protocols,
- for example::
+ for example:
+
+ .. sourcecode:: python
+
+ class MyLockingClass(NSObject, objc.protocolNamed('NSLocking')):
+ # implementation
+ pass
- class MyLockingClass(NSObject, objc.protocolNamed('NSLocking')):
- # implementation
- pass
+ It is also possible to define new protocols:
- It is also possible to define new protocols::
+ .. sourcecode:: python
- MyProtocol = objc.formal_protocol("MyProtocol", None, [
- selector(None, selector='mymethod', signature='v@:'),
- ])
+ MyProtocol = objc.formal_protocol("MyProtocol", None, [
+ selector(None, selector='mymethod', signature='v@:'),
+ ])
All formal protocols are instances of ``objc.formal_protocol``.
@@ -1123,7 +1185,9 @@
- objc.runtime will now raise AttributeError instead of objc.nosuchclass_error
when a class is not found.
-- objc.Category can be used to define categories on existing classes::
+- objc.Category can be used to define categories on existing classes:
+
+ .. sourcecode:: python
class NSObject (objc.Category(NSObject)):
def myMethod(self):
@@ -1230,19 +1294,20 @@
- Fix installer for Panther: the 1.1a0 version didn't behave correctly
- There is now an easier way to define methods that conform to the expectations
- of Cocoa bindings::
+ of Cocoa bindings:
+
+ .. sourcecode:: python
- class MyClass (NSObject):
+ class MyClass (NSObject):
+ @objc.accessor
def setSomething_(self, value):
pass
- setSomething_ = objc.accessor(setSomething_)
-
+ @objc.accessor
def something(self):
return "something!"
- something = objc.accessor(something)
It is not necessary to use ``objc.accessor`` when overriding an existing
accessor method.
------------------------------------------------------------------------------
Register Now for Creativity and Technology (CaT), June 3rd, NYC. CaT
is a gathering of tech-side developers & brand creativity professionals. Meet
the minds behind Google Creative Lab, Visual Complexity, Processing, &
iPhoneDevCamp asthey present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship. http://www.creativitycat.com