Anonymous avatar Anonymous committed d4b0261

Unfinished tutorial on reading someone else's PyObjC code. Checking
it in mainly to get it off my laptop.

Comments (0)

Files changed (1)

pyobjc/Doc/tutorial_reading.txt

+Understanding existing PyObjC examples
+======================================
+
+Introduction
+------------
+
+This tutorial is aimed primarily at people with little or no background
+in ObjC and Cocoa, and it will help you to understand PyObjC programs
+written by other people, such as the examples included with the distribution.
+This document is actually not a true tutorial: you do not get to build anything,
+only read and examine things.
+
+It is strongly suggested that you first do the
+`Creating your first PyObjC application`_ tutorial to get some hands-on
+experience with PyObjC, Cocoa and especially Interface Builder.
+
+Model-View-Controller
+---------------------
+
+If you have used another GUI toolkit in the past it is essential that
+you understand that Cocoa is different. For this once this isn't marketing-speak:
+Cocoa is inherently different from common toolkits such as Tk, wxWindows,
+Carbon, win32 and all the other popular ones. Apple's documentation explains this,
+but in the introductory sections that are often quickly glanced over. It is a
+good idea to refer back to XXXX after reading this section. If you really
+want you can break out of the architecture sketched in this section, but
+then you are on your own, really: Cocoa and Interface Builder really
+expect you to follow this model.
+
+Cocoa is built on the Model-View-Controller paradigm (MVC). What this means
+is that the application code is going to be split into three parts:
+
+- The *Model* is the actual data you are manipulating, plus the operations
+  on it. It can be as big as a complete database engine or a scientific
+  simulation, or as small as a routine that multiplies one floating point
+  number (an amount of money in currency A) by another (the conversion
+  rate from currency A to currency B), as in the currency converter
+  application you built in the first tutorial.
+- The *View* is what the user sees on-screen, plus his or her interaction
+  with it.
+- The *Controller* is the glue that binds these two together. In the
+  currency converter example, it is the code that gets called when the user
+  presses the "Convert" button, whereupon it gets the data from the "amount"
+  and "rate" fields from the View, passes them to the Model for computation
+  and sends the result back to the View.
+  
+To summarize: the Model knows nothing about dialogs and buttons and such,
+the View knows nothing about data and algorithms and the Controller ties it
+all together. For really tiny applications, such as the currency converter,
+you could do away with the Model and simply put that code right in the
+Controller. MVC purists say you should not do this, and it can indeed
+make your code harder to read (because the Controller will contain a mix
+of algorithms and glue code), but there is no architectural reason that
+stops you. If you combine the two classes it is customary to use the name
+you would use for your document class, so without "Controller".
+
+You should have an MVC trio for every distinct unit of information in your
+program. In case of a simple dialog-style application such as Currency Converter
+you will have one such trio. Most applications, however, will have at least
+two: one for the application itself and one for the "documents" the application
+handles. These may be real documents (i.e. files), but they could also be more
+abstract. If your application does scientific simulation and you want to be
+able to open two simulation windows at the same time you should use the
+document model.
+
+The NIB file
+------------
+
+Cocoa and Interface Builder strongly encourage you to use a NIB file
+per MVC trio. Again: follow this encouragement unless you are sure what
+you are doing.
+
+This brings us to the second big difference between Cocoa and other GUI
+toolkits: almost all the boilerplate code is in the NIB, and therefore
+the source of Cocoa programs, especially example programs that do little
+real work, will look stunningly small if you are familiar with, say,
+Tkinter.
+
+The NIB file is *not* a description of dialogs and menus and buttons, as you 
+would get out of interface-builders for other toolkits. There, at startup
+something will read the description, create the buttons and hand the finished
+dialog to your code. A NIB file is more: it contains a complete set of frozen
+objects, conceptually similar to a pickle in Python. You tell Interface Builder
+knows about all the relevant classes in your application, the instances you
+want to create from those classes, and how the classes should connect to
+each other. Interface Builder the actually instantiates the classes, makes
+all the connections and at that point freezes and stores the whole lot.
+
+When your NIB is read the objects are thawed, the connections restored and
+the objects get a running start. Again, this is conceptually similar
+to how unpickling works.
+
+	The section above explains a lot of the strangeness in PyObjC
+	programs: why you don't create windows and other dialogs (they
+	already exist); why you shouldn't do initialization in `__init__`
+	(because it will be called at some undefined point in time, while
+	reading the NIB) but in `AwakeFromNIB` in stead; why you don't
+	have to create and initialize the attributes that tie your
+	objects together (they are already tied together).
+	
+This also explains why you want separate NIB files for each MVC trio:
+the objects and classes in a NIB file are all unpickled together. In other
+words: if you had created your document window in your application NIB
+(even if you set it to "hidden" initially so it does not show up) it would
+become very difficult to create a second window for a new document.
+
+If you think about the consequences of this section for a while it will
+become clear why all the boilerplate code is missing from Cocoa applications:
+you don't need it. The NIB file usually contains all of the things that need to
+be done for the Views objects, as is often the case with other gui-builders.
+But in addition the NIB also contains a large proportion of your Model
+functionality: creating the View and Controller objects and tieing the
+lot together.
+
+XXXX Explain about delegates in stead of subclassing.
+
+Examining a NIB file
+--------------------
+
+Let us examine the NIB of the Currency Converter tutorial with this in mind.
+If you open it and look at the main window (the one with "MainMenu.nib" as
+its title) and select the "Instances" pane you see six objects. Two of these
+have a greyed-out name ("File's Owner" and "First Responder"): these have
+been created for you by Apple. The other four are created by you. Actually:
+"Main Menu" was created by Apple as a convenience, but you are free to modify
+it. The "File's Owner" is either the Controller or the combined Model-Controller
+object, in this case it is the application itself, an instance of `NSApplication`.
+Because this application is not a document-based application the MVC trio
+for the actual conversion window are in here too: `Converter`, `Window` and
+`ConverterController` respectively.
+
+XXXX Examine ConverterController, show how to see class and methods
+
+XXXX Show how to see connections
+
+XXXX Show how to use outline view
+
+Examining an example
+--------------------
+
+XXXX Pick one of the interesting examples and walk through it, looking at the
+NIB file and the code.
+
+
+.. _`Creating your first PyObjC application`: tutorial/tutorial.html
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.