Macintosh Python crash coursegensuitemodule.py, and lives in
-Tools:bgen:ae. When we start it, it asks us for an input
+Mac:scripts. When we start it, it asks us for an input
file and we point it to the Eudora Light executable. It starts parsing
the AETE resource, and for each AppleEvent suite it finds it prompts
us for the filename of the resulting python module. Remember to change
@@ -46,7 +46,7 @@ Required_Suite.py would hide the correct module of that
name from our application.
-
+
-
Time for a sidebar. If you want to re-create
+
Let's glance at the Eudora_Suite.py just created. You
@@ -81,7 +81,7 @@ Required_Suite.py or one of the other standard modules
you should look in System Folder:Extensions:Scripting
@@ -55,7 +55,7 @@ Creating the Python interface module
Finder_Suite interface: don't look in the finder (it has
an old System 7.0 scripting suite), look at the extension Finder
Scripting Extension.
aetools, an auxiliary module
-living in Tools:bgen:ae which contains some other nifty
+living in Lib:toolbox which contains some other nifty
AppleEvent tools as well. Have a look at it sometime, there is (of
course) no documentation yet. @@ -130,10 +130,7 @@
addpack calls to extend
-sys.path to include Tools:bgen:ae, use of
-ni should be preferred over addpack but I
-have not managed to master it yet). Then we get the class definition
+with some imports. Then we get the class definition
for our main object and a constant giving the signature of Eudora. This, again, needs a little explanation. There are various ways to diff --git a/Mac/Demo/example2.html b/Mac/Demo/example2.html index 3bd2791b9f3..aebe73d2932 100644 --- a/Mac/Demo/example2.html +++ b/Mac/Demo/example2.html @@ -11,7 +11,7 @@
@@ -61,15 +61,13 @@
-
-A more complete description of FrameWork is
-sorely needed, and will (at some point) be incorporated in the
-programmers manual or in place of this paragraph. For now you'll have
-to make do with the knowledge that you use FrameWork by building your
-classes upon the classes provided by it and selectively overriding
-methods to extend its functionality (or override the default
-behaviour). And you should read the Source, of Course:-)
-
+If you have not used FrameWork before you may want to
+first take a look at the Pathetic EDitor
+example, which builds a minimal text editor using FrameWork and TextEdit.
+On the other hand: we don't use many features of FrameWork, so you could
+also continue with this document.
+
After the imports we get the definitions of resource-IDs in our
resource file, slightly changed from the previous version of our
diff --git a/Mac/Demo/index.html b/Mac/Demo/index.html
index fda20b7aca0..774db686f83 100644
--- a/Mac/Demo/index.html
+++ b/Mac/Demo/index.html
@@ -19,7 +19,7 @@ Macintosh Python crash course-The document was actually written while I was working on a "real" +Some of these documents were actually written while I was working on a "real" project: creating a single-button application that will allow my girlfriend to read her mail (which actually pass thry my mailbox, so I get to read it too, but don't tell her:-) without her @@ -28,15 +28,16 @@
Macintosh Python crash course
-
-If you want to try the examples here you will have to download some
-fixes to the 1.3 distribution to your Macintosh. You need an updated
+
-
+If you want to try the examples with a version of Python earlier
+than 1.3.1 you have to download some things. You need an updated
version of FrameWork.py (to
go in
+the Lib:mac and updated project templates to go into
-the PlugIns folder for PPC users.
-Users of 1.3.1 or later distributions don't need these fixes.PlugIns folder for PPC users.
+The TextEdit and WASTE examples are not useable with distributions +before 1.3.3. + If you are reading this document on the web and would prefer to read it offline you can transfer the whole stuff (as a BinHexed StuffIt @@ -59,12 +60,13 @@
FrameWork application framework and the
+TextEdit toolbox to build a text editor.
+
+MovieInWindow and
+VerySimplePlayer examples, re-coded in Python.
+
+@@ -95,4 +118,4 @@
FrameWork and TextEdit
+modules to create a simple text editor. The functionality
+of the editor is very basic: you can open multiple files, type text and use
+cut/copy/paste. The main intention is to explain the use of FrameWork, really. + +
Application
+__init__ routine
+to do your own initializations and override makeusermenus to create your menus
+(your menu callback routines may be here too, but this is by no means necessary).
+The event handling code can be overridden at various levels, from very low-level (the
+dispatch method) to intermedeate level (do_keyDown, for instance)
+to high-level (do_key). The application class knows about the Window
+objects you create, and will forward events to the appropriate window (So, normally you
+would have a do_key method in your window object, not your application object).
+
+MenuBar, Menu and MenuItem
+SubMenu) handle your menus. You would not
+normally override them but use them as-is. The idiom for creating menus is a bit strange,
+see the test code at the bottom of FrameWork for sample use. The apple menu is handled for you
+by MenuBar and Application.
+
+Window
+open. Your
+open method should call do_postopen to let the base class handle linking in to
+the application object. Similarly with close and do_postclose. The
+rest of the code is mainly event-oriented: you override do_postresize,
+do_contentclick, do_update, do_activate
+and do_key to "do your thing". When these methods are called the relevant environment
+has been setup (like BeginDrawing has been called for updates, etc).
+
+windowbounds
+ControlsWindow
+do_controlhit.
+
+ScrolledWindow
+do_activate
+or do_postresize you must call the ScrolledWindow methods at the end of your override.
+You call scrollbars to enable/disable scrollbars and updatescrollbars to
+update them. You provide getscrollbarvalues to return the current x/y values (a helper
+method scalebarvalues is available) and scrollbarcallback to update your
+display after the user has used the scrollbars.
+
+DialogWindow
+
+
+Ped creates two classes, TEWindow and Ped. Let us start with the latter one,
+which is a subclass of FrameWork.Application and our main application. The init function
+has little to do aside from the standard init: it remembers a window sequence number (for untitled windows),
+and sets things up for menu disable to work. Remember, the makeusermenus is called
+automatically.
+
+Makeusermenus creates the File and Edit menus. It also initializes
+a couple of lists that are used later to correctly enable and disable menu items (and complete menus) depending
+on whether a window is open, text is selected, etc. The callback functions for the menu items are
+all methods of this class.
+
+Updatemenubar handles greying out (and re-enabling) of menu items depending on whether there
+is a current window and its state.
+
+The rest of the methods are all callbacks and simple to understand. They check whether there is an active
+window (and complain loudly if there is none: the corresponding menu entry should have been disabled
+in that case!) and call the appropriate window method. Only the _open method (the common code
+for Open and New) deserves some mention. It instantiates a TEWindow
+object and opens it with the title, filename and contents of the file to edit. Note that FrameWork takes
+care of remembering the window object. A minor note on opening the file in binary mode: this is because
+TextEdit expects MacOS style carriage-return terminated lines, not python/unix/C style newline-terminated
+lines.
+
+Oh yes: the quit callback does a little magic too. It closes all windows, and only if this
+succeeds it actually quits. This gives the user a chance to cancel the operation if some files are unsaved.
+Quitting itself is also a bit strange: you raise self to break out of the main loop. This bit
+of idiom was invented by Guido, so blame him:-).
+
+Lastly, there is the idle method, called by the Application base class when no event
+is available. It is forwarded to the active window, so it can blink the text caret.
+
+The TEWindow object handles a single window. Due to this structuring it is absolutely no
+problem to have multiple windows open at the same time (although a real application should exercise care when
+two windows refer to the same document). TEWindow uses the standard init code inherited from
+ScrolledWindow, and sets itself up at the time of the open call. It obtains screen
+coordinates, opens the window, creates rectangles for TextEdit to work in (the magical number 15
+here is the size of a normal scroll bar: unfortunately there is no symbolic constant for it),
+creates the TextEdit object and initializes it with our data. Finally, the scroll bars are created (the
+initial values will be obtained automatically through getscrollbarvalues) and we activate
+ourselves (this is unfortunately not done automatically by the MacOS event handling code).
+
+Do_idle simply calls the TextEdit routine that blinks the cursor. Getscrollbarvalues
+returns the current X and Y scrollbar values, scaled to 0..32767. For X we return None,
+which means "no scrollbar, please", for Y we use the scaler provided by ScrolledWindow.
+
+Scrollbar_callback is called when the user uses the scrollbar. It is passed a string 'x'
+or 'y', one of 'set', '-', '--', '+', '++' and (for set) an absolute
+value. Note that the sign of the value passed to TEPinScroll is counter-intuitive.
+
+do_activate (de)activates the scrollbars and calls the relevant TextEdit routine. Moreover, it
+tells the application object if we are now the active window, and updates the menubar. The next few methods
+are update and menu callbacks, and pretty straightforward. Note that do_close can
+return without closing the window (if the document is changed and the users cancels out of the operation).
+Also note the "magic" in menu_save_as
+that set the correct window title.
+
+Things get moderately interesting again at the cut/copy/paste handling, since the TextEdit scrap is
+separate from the desktop scrap. For that reason there are various calls to routines that move the scrap
+back and forth. Have_selection is called by the menubar update code to determine whether cut and
+copy should be enabled.
+ +Understanding the main program is left as an exercise to the reader.
+ +
diff --git a/Mac/Demo/using.html b/Mac/Demo/using.html index 5f2009732b3..849c6d15cf5 100644 --- a/Mac/Demo/using.html +++ b/Mac/Demo/using.html @@ -14,6 +14,14 @@
+There is currently no good tutorial for the mac-specific features of +Python, but to whet your appetite: it has interfaces to many MacOS +toolboxes (quickdraw, sound, quicktime, open scripting, etc) and +various portable toolboxes are available too (Tk, stdwin, complex +numbers, image manipulation, etc). Some +annotated sample programs are available to give you an idea of +Python's power.
+ The document refers to Python 1.3.3 or higher, some of the features (like setting applet options) will not work in earlier versions of Python.
@@ -24,7 +32,7 @@
Python, PythonPPC (for powerpc
macs) or Python68K (indeed, for 68K macs). It will always
be recognizable by the "16 ton" icon, though. You start the
-interpreter in interactive mode by double-clicking it. +interpreter in interactive mode by double-clicking its icon:
@@ -88,7 +96,7 @@
-
+
Make sure the program is a module file (filename must be a Python
identifier followed by '
+workspace.
.py'). You can then import it
@@ -121,7 +129,7 @@ Creating Python scripts
it. For instance, import foo; reload(foo). Because the
module object already exists internally, the import statement does not
attempt to execute the module again -- it just places it in your
-workspace.
.py. +
+Older releases of Python used the creator code ++'PYTH'in stead of'Pyth'. If you still have +older Python sources on your system and named them with +'.py'extension thefixfiletypesscript will +correct them. +
+ +WASTE is written by Marco Piovanelli, <piovanel@kagi.com>, +and copyrighted by him. You can always obtain the latest version (for use in C +or Pascal programs) and the documentation from +<ftp://ftp.dsi.unimi.it/DSI/piovanel/WASTE>. + +We explain the useage of waste here by showing how to modify the TextEdit based +ped.py of the +previous example into the waste-based wed.py, +so you should have both sources handy.
+
+Functionally, wed.py provides three new things: resizable windows, a horizontal
+scroll bar and undo.
+
+Let us look at the code, first at the application class Wed. The only real change is that
+we now handle undo. Aside from enabling it in the creation routine and the addition of
+a callback routine there is a bit of new code in updatemenubar: Waste not only handles
+the full details of implementing undo, it will also tell us what the next undo operation will undo
+(or redo). We use this to our advantage by changing the undo menu label to tell the user.
+
+The WasteWindow has seen a bit more change. Initialization of the waste data structure is
+a bit different, in that we can specify some options at creation time. Also, waste has no SetText
+method but a UseText which expects a handle as parameter. We have to be very careful
+that we keep this handle around, because Python will happily free the handle if we have no more references
+to it (and I doubt that Waste would like this:-). A final difference in open
+is that we use a large number for the destination rectangle width, because we will use a horizontal scroll
+bar.
+
+The idle method is a bit more involved, since we also call WEAdjustCursor to
+provide the correct cursor based on mouse-position. Users like this.
+
+Getscrollbarvalues is simpler than its' TextEdit counterpart because Waste correctly
+updates the destination rectangle when the document changes. Also note that waste uses accessor functions
+to get at internal values, as opposed to direct struct access for TextEdit.
+
+Scrollbar_callback on the other hand is more elaborate (but also provides more functionality).
+It also handles horizontal scrolls (scrolling one-tenth and half a screenful with the buttons). This
+function is also "multi-font-ready" in that scrolling one line will do the expected thing in case of multiple
+fonts. We will implement a multi-font editor later. A minor annoyance of Waste is that is does not provide
+a pinned scroll, so at the end of our callback routine we have to check that we have not scrolled past the
+beginning or end of the document, and adjust when needed.
+
+do_update is also changed, because Waste is completely region-based (as opposed to rect-based).
+Hence, we erase regions here and we can also return immedeately if there is nothing to update.
+
+Do_postresize is new: because Waste uses accessor functions we can now modify the viewRect from
+Python, which is impossible in the Python TextEdit interface, and hence we can implement resize. The
+do_key and do_contentclick methods have also seen minor changes, because the
+corresponding waste routines need a bit more information than their TextEdit counterparts. The Cut/copy/paste
+code is simplified, because Waste uses the normal desktop scrap.
+
+Implementing undo is a wonder of simplicity: Waste handles all the details for us. Also, the new
+can_paste method (which controls greying out of the paste menu entry) is an improvement
+over what ped did: in ped it was possible that paste was enabled but that the data on the
+scrap was incompatible with TextEdit. No more such problems here.
+ +