Despite what the title may imply, this document does not explain the new API. The purpose of the file at this point in time is to give out tips and explain special issues to be concerned with when programming modules for use with Extensions Strip. To learn more about the API, please read the header file and source code since they are both heavily commented.
NB: at the time of this writing, free registrations of Extensions Strip are being offered to programmers who support ES' API in their modules. Also, if someone wants to convert the ESDemo source code to MW Pascal, I would be very grateful in the same manner. Yes, I care about Pascal even though ES was totally written in C and 68K assembly. I also want to cut back on new (and seasoned) programmers asking me: "What the %[^\n]%* is this?" :-)
Create an alias to your module's project folder and add the alias to the root module folder. Whenever you build your module, click on the strip's title bar with the command & option keys down to get the new compile to load. If you run Extensions Strip as a regular application (by converting it with the "appe <-> APPL" utility) then you will never even have to leave the your development application's context to try the latest build!
• "ES compatible" checklist:
- All memory that was ever permanently allocated is disposed of when the sdevCloseModule selector is called.
• "ES savvy" checklist for existing modules:
- All AppleEvents are sent safely (SBSimpleAESend() is the easiest way to do this.)
- The sdevDontPeriodicTickle bit is returned with the features if no idle events are required. Be nice and return this if you don't need idle time!
- Modifier key and mouse position checks are performed by reading from the event record (with a call to SBGetCurrentEvent().) This ensures that the user's wishes are carried out because if they, for instance, click on your module with the shift key down while the CPU was busy, then your module can tell that the shift key was down, even if the user has since let the key up.
- Support of ES' integrated drag stuff:
1. return the sdevHasDragHandlers bit with the features if a drag handler is installed.
2. the sdevDragAccept selector has been added (to return whether your drag handler(s) accept the current drag or not.)
3. the drag handler(s) call SBGetTotalModuleBounds() to find the total drag-able space.
4. new drags are started from within ES' context so that they may leave the strip.
- Any other ES API stuff is supported.
• Gestalt info:
Extensions Strip implements its own features selector, as well as the Control Strip and Desktop Strip selectors. Here are the selectors and what they each return:
'CsEs' (gestaltExtensionsStripAttr) - returns bit 0 (gestaltExtensionsStripExists) when Extensions Strip is launched. The simple existence of this selector tells whether ES can be launched or not.
'csvr' (gestaltControlStripVersion) - returns the current version of Extensions Strip in the standard format. For instance, version 1.0.2 would be returned as $0102.
'sdev' (gestaltControlStripAttr) - currently returns bits 0 (gestaltControlStripExists), 1 (gestaltControlStripVersionFixed), and 2 (gestaltControlStripUserFont).
'CsWT' (gestaltDesktopStripAttr) - currently returns bits 0 and 1. I don't know what these bits signify, but they are returned anyway since that's what DS 1.2.1 returns.
• PowerPC notes:
All PPC modules load inside Extension Strip's context to prevent shared library loading problems. The downside to this is that you cannot rely upon the current process to have a valid application context ie. the current process will most likely be ES running as a background app. 68K modules, however, are loaded in the front application's process (usually the Finder) to retain maximum compatibility with all available modules.
Remember to use 'weak' links to libraries that are not guaranteed to be present. Not doing so will crash the computer if the lib cannot be found. ExtensionsStripLib and the InterfaceLib are always guaranteed to be present so do not require 'weak' links.
Calling SBSafeToAccessStartupDisk() from PPC code will always return true regardless of the state of the hard disk. This is because I do not have Apple's shared library to link the required calls to, if Apple has even made a library for this yet... If anyone out there has a copy of this library, could you please e-mail it to me?
• ModalDialog() notes:
With Extensions Strip, your dialogs may call ModalDialog() instead of SBModalDialogInContext(). The only real benefit to this is that the user gains access to the edit menu. Note though that as of this writing Desktop Strip crashes when ModalDialog() is called so if you are concerned with compatibility, stick with SBModalDialogInContext().
Also, watch out for ResolveAliasFile(). In order to mount remote volumes, it will display a dialog. While this is ordinarily fine, it will crash your computer if the current process is Extensions Strip running as a background-only app. This situation only occurs if a) you specifically requested to be called from inside ES' context or b) your drag handler is responding to a drag that was created inside ES' context.
• Crashes!:
Tip: If a module crashes your computer, but you are able to resume using your computer (usually through the use of MacsBug's 'es' command), then clicking on any strip will result in a beep. You could resume the use of Extensions Strip by turning it off and back on, but if you are sure that the "crash" was not serious (ex. you felt like force-quitting), then you can resume the use of ES by dragging something onto any strip.
Note that I have left in the debugging names to Extensions Strip's functions. This helps me to locate possible bugs that you may encounter (nobody's perfect!) So if ES crashes while you are using a low level debugger, and you don't think that it's your module's fault, then kindly e-mail me a dump to disk of at least the following things:
-=-=-=-=-=-=-=-
log esCrash1
stat
sc6
sc7
hc
td
ip
ir
log
-=-=-=-=-=-=-=-
BTW, if you are wondering what some of these commands do, just snap into MacsBug and type 'help' followed by the command. Happy hacking!
