diff options
Diffstat (limited to 'Tools')
| -rw-r--r-- | Tools/bgen/README | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/Tools/bgen/README b/Tools/bgen/README index 4c1e9f4..a6c22fd 100644 --- a/Tools/bgen/README +++ b/Tools/bgen/README @@ -22,6 +22,7 @@ ctl Controls dlg Dialogs evt Events menu Menus +list Lists qd QuickDraw res Resources snd Sound @@ -64,6 +65,12 @@ aetools.py Conversions between AE and Python data type echo.py Dummy AE server, echoes all data back tell.py Primitive AE client aete.py Decode 'aete' and 'aeut' resources (incomplete) +gensuitemodule.py + Read aete/aeut resources and turn them into python + modules. The *_Suite.py modules have been generated + with this. +AEservertest.py A simple AE server, similar to echo but different. + In res: @@ -77,3 +84,72 @@ playaiff.py Play an AIFF file morse.py Turn text into Morse code audiodev.py The standard audiodev.py extended with Mac support Audio_mac.py The Mac support for audiodev.py + + +Creating new Macintosh interfaces +--------------------------------- + +These instructions were written up by Jack while he was building the +interface to Lists.h, the macintosh list manager. they may or may not +have a more global scope than exactly that. + +First, start by copying ...scan.py and ...support.py from another, +preferrably similar type. I started with evt, but that was a mistake +since evt has no "own" object. Ctl or Dlg would probably have been a +better idea. + +Now, the first thing to do is to comment out the blacklisted types and +functions and the transformation rules for arguments, we'll fill those +in lateron. Also, change the various definitions at the top, so that +the right include file is parsed, and the .py files are generated with +the correct name. If your manager has a type that will be implemented +as a python object you may as well now change the destination() method +to recognize that. (List was funny in this respect, since it has the +list as the last argument in stead of the first). + +Now run your scanner. This will probably go fine until it tries to +execute the generated code in the ...gen.py module. Look at that file, +it will have formalized "definitions" of all the functions and methods +that will be generated. Look at them all (with the documentation of the +manager you're implementing in hand). Now you'll have to fix the +blacklists and the repair instructions. This is sort of a black art, +but a few guidelines may be handy here: +- If there are argument types you cannot implement (or want to leave for + the moment) put them in blacklisttypes. Complex structures come to + mind, or routine pointers/UPP's. You will probably also want to + blacklist the routine that disposes of your object (since you'll do + that in the python destruction routine). +- Various types of buffers are available in bgenBuffer, bgenHeapBuffer + and macsupport in the bgen directory. These'll let you handle all + sorts of input and output parameters. You can put instructions in the + repair list to let the C-arguments be handled by the correct type + of buffer. Check the other bgen-generated modules for using this for + passing raw structures and input and output buffers. +- It appears that the parser usually guesses correctly whether a parameter + is meant for input or output. But, check the routines to be sure. +- Some types are pretty hard to handle but you need the functionality + the a routine that uses them anyway. Various routines expecting ProcPtrs + or RegionHandles come to mind. Often, you can use the FakeType class + to provide a sensible default (i.e. NULL or a pointer to a routine you + coded in C, or a region specifying "the whole window"). This way, python + programmers won't get the full functionality but at least they'll get the + common case. You put the FakeType stuff in ...support.py. + +Next you'll probably have to write the code to implement your object. +This will probably be a subclass of GlobalObjectDefinition. This goes +into ...support.py. Also, some types used by the manager may look +enough like standard types that you can equate them here (there are a +lot of 2-integer structures that look remarkably like a Point, for +instance). + +You'll also have to define the Function() and Method() classes. The +OSErrFunctionGenerator and its method-counterpart are particularly +handy for a lot of mac managers. + +Finally, you'll have to try and compile your resulting C-source, and go +through the steps above until it works. For tlist.py, the test program +for list, I started with the application framework. This is probably a +good idea for any manager that does something to the display, since +ApplicationFramework takes care of all the intricacies of event +handling and decoding (up to a point). + |