• Whereas the DropShell documentation states: "DropShell consists of four source files and five header files that are designed to let you quickly add your own application’s functionality without having to change the DropShell sources themselves much", BoxMaker++ takes this one step further: it lets you quickly add your own application’s functionality without having to change or recompile the BoxMaker++ sources themselves at all. (this is just a commercial for C++; in the case of DropShell vs BoxMaker++ the difference is very minor).
• BoxMaker++ lets you access the entire CInfoPBRec obtained during a catalog traversal, whereas DropShell only passes a FSSpec. The accompanying examples 'll-R' and 'touch' show why this can be handy. To achieve something similar in DropShell one would have to do an additional call of GetCatInfo (which, to be honest, would access data in the disk cache, so it would not be very time-consuming). For convenience, an FSSpec for the file to be handled is also available.
• BoxMaker++ comes with some example dropboxes which even are actually useful (that is why I wrote them, in the first place)
• BoxMaker++ dropboxes can be changed significantly by changing just a few resources in the application. The resources to change are the 'typs' resource, the 'tycr' resource, and the 'flgs' resource, all three with ID 128.
The 'typs' and 'tycr' resources determine which files will be passed to the dropbox's OpenDoc handler. Both resources implement a filter, and a file must pass both filters to be passed to the OpenDoc handler. They can for instance be used to change 'll-R' (see below) into an application which lists all Think Project files on your disk. Simply add a 'typs' with contents 'PROJ', and drop your disk onto 'll-R'. Similarly, 'touch' (described below) can be changed to only 'touch' all your TEXT files, or all your applications.
The 'typs' resource contains a series of file types, the 'tycr' resource a series of type-creator pairs.
When changing the 'typs' resource one could also update the 'BNDL' resource (but see below for repercussions; one then should register one's own file creator with Apple). If the 'BNDL' resource is not changed the set of files which can be dropped on the dropbox is different from that which can be selected in the open file dialog, or from that which is passed to the OpenDoc handler when a disk or folder is dropped on the dropbox.
The 'tycr' resource, when present, can be used to further restrict the files passed on to your OpenDoc handler. As a wildcard one can use the type or creator '****'. For instance, a 'tycr' resource can be used to select all BBEdit files and all 'TEXT' files by not including a 'typs' resource (thus selecting every file), and a 'tycr' resource listing 'TEXT****' and '****R*ch'.
Note: as stated above a file must pass both the 'typs' and the 'tycr' check in order to be passed to your OpenDoc handler. It is not necessary to include either of the two types of resources, however. If one of the resources is absent all files will pass the relevant test. We could do away with the 'typs' check since any such selection can also be made with a 'tycr' selection with wildcards, but it is easier to type a simple file selection this way, and more importantly, BoxMaker++ 1.1 is compatible with version 1.0 this way. Finally, it is handy from the viewpoint of the programmer since the contents of the 'typs' resource can be passed directly to the Standard File Package's 'StandardGetFile' routine.
Since a 'tycr' resource allows for selections on file creator it generally is not possible to match the 'BNDL' resource with the 'tycr' resource, so if a 'tycr' resource is present it will always be possible to drop files on the dropbox which are not passed on to your OpenDoc handler.
The 'flgs' resource specifies whether invisible files and folders are passed to your dropbox and whether visible and invisible folders are entered. This resource can be used to make dropboxes somewhat less drastic. A good candidate for this is 'touch', which can be made to only touch files and folders dropped directly onto it, just by changing a flag in its 'flgs' resource.
To help in changing these resources ResEdit templates are included with this distribution.
Known bugs and shortcomings:
• BoxMaker++ does not have balloon help.
• The 'Open…' menu item doesn't let one select a folder or disk. This was done to remain compatible with DropShell (well, actually I haven't deemed it neccessary. If you want to process a folder or disk, just drop it on the dropbox, that is why it is called a dropbox). Also, the 'Open…' item lets one choose files which will not pass the 'tycr' check, and thus will not be passed to the OpenDoc handler. Similarly, files which will not pass the 'typs' or 'tycr' checks can be dropped. It is possible to fix this for the 'typs' check by specifying these same types in the application's BNDL, too (in which case you should register your creator with Apple; see below)
• The preferences item in file menu is not disabled when the preferences window is visible. This could be fixed by inserting lines:
DisableMenuItem( GetMHandle( kFileMenuID), kPrefsItem) after the 'ShowWindow'
and
EnableMenuItem( GetMHandle( kFileMenuID), kPrefsItem) after the 'HideWindow'
in boxmaker.cp, but then no subclass can change the location of the preferences item in the file menu. Subclasses can do that now, as long as they do override 'DoMenu', too.
• All information gathering is done using synchronous I/O. There might be uses of BoxMaker++ which become faster if I/O would be asynchronous.
• The shell is not 100% safe to use. If a subclass does change directory entries and the 'EnterFolders' flag is set some files may be passed more than once or not at all. It even is conceivable that BoxMaker++ may recurse indefinitely, and eventually crash due to lack of memory. The rule to avoid this is: If your dropbox does change a directory entry which may be passed to the dropbox, or whose parent folder may be passed to the dropbox, you should postpone these changes until (depending on the exact nature of the directory entry changes) ExitFolder is called, or until EndABunch is called, or until your dropbox's destructor is called, unless you know better (e.g. in a shell which 'touches' files or changes the 'locked' bit). Also, the fields 'theCInfoPBRec', 'theFSSpec', and 'theSubDirID' should be made private. However, a subclass may want to do a SetCatInfo, so I kept them protected. Read the comments in 'boxmaker.h' for further instructions on safe use of these fields, and test your dropboxes thoroughly. Note that this is not a problem only BoxMaker++ suffers from. It is common to any directory-traversing program.
Building a dropbox of your own:
Building a dropbox is done by creating a subclass of class 'boxmaker', adding a main function, and linking it with the ‘boxmaker++ π’ project file. Your subclass can be as simple as:
class myDrop : public boxmaker
{
virtual void OpenDoc( Boolean opening);
};
void myDrop::OpenDoc( Boolean opening)
{
//
// most important fields available:
//
// CInfoPBRec theCInfoPBRec; filled in by GetCatInfo
// FSSpec theFSSpec; current file or folder
// long theSubDirID; ID of parent directory
//
}
and the main function typically is:
void main()
{
myDrop dubbel_zout;
dubbel_zout.run();
}
where OpenDoc is the routine called for every file or folder opened. Read the file ‘boxmaker.h’ for more information.
When building your own dropboxes you should use your own file creator for the finished application. Three of the distributed applications have the creator '∂ƒ**', which I registered with Apple. I personally use '∂ƒ**' for programs built with BoxMaker++, as long as they fulfill the following requirements:
• the bundle resource indicates that the dropbox accepts folders, disks and all file types. You can include 'typs' and/or 'tycr' resources to prevent some of these to be processed by your dropbox, though.
• the icon of the dropbox is a system 7 custom icon, and not specified in the 'BNDL' resource. Thus, the icon does not get stored in the desktop file, and does not proliferate to other dropboxes using the same file creator.
• the dropbox does not create files, other than possibly a preferences file, and such a preferences file has the type 'pref' and creator '????'. Thus, the problem of 'dropbox B' creating a file which gets specified in the Finder as 'dropbox A document' is evaded.
• the dropbox does not accept any other apple events than 'Open Application', 'Open Document', 'Print Document', and 'Quit Application'.
• the dropbox does not contain any other information which makes it possible to the Finder to discriminate it from other dropboxes (such as 'kind' resources used with Macintosh Easy Open).
If you intend to distribute a dropbox of your own, I strongly recommend that you register your own file creator with Apple, even if your dropbox does satisfy these requirements. Distribution of dropboxes not satisfying these requirements, and having creator '∂ƒ**' is certainly a no-no, since it may one day lead to more or less serious troubles. Also, if you modify an included dropbox, be sure to change its name, and more importantly, the name of its preferences file (BTW: Apple should start a registry for names of preferences files, but it probably is too late to do that)
Example dropboxes in the distribution:
BoxMaker++ comes with five example dropboxes. Three of the examples (ll-R, touch, and typical) in this distribution have a touch of Unix. Apart from µZak and ll-R the example dropboxes can cause considerable damage to the files on a hard-disk, without having warned the user that they do so. These are not full-quality Macintosh applications, but should just be used as example code. Some things which should be changed are:
• About boxes explaining what the program does.
• Balloon help
• Error reporting (now mostly done by a simple SysBeep or a DebugStr call)
Feel free to build and use the example dropboxes, but do not distribute them. Instead, distribute the entire release, including this documentation. If you wish to distribute finished dropboxes based upon the examples you should take responsibility for any damage done by them. In short:
Use the example dropboxes at your own risk; they can be pretty useful, but can also be dangerous. When in doubt, use the source code to determine what a dropbox is exactly doing.
ll-R is a directory lister, named after the Unix command of that name ('long listing, recursive') The directory listing is saved in a file on the desktop, or in a user-selectable file. This is the most basic of dropboxes possible, written to test the directory traversal routines. The nicest part of this shell is the preferences class (which is also used by touch and µZak)
touch can be used to change modification and/or creation dates of files. This can be dangerous since these dates are used by back-up programs. Drag your hard-disk icon onto touch, and the next backup may be a lengthy one. It can be used to set all modification dates of a file tree to midnight today or something similar, for instance to make a set of files ready for distribution.
typical can be used to set the creator and type of files. Configuration is simple: make a copy and give it a name which is at least 8 characters long. typical will use the first four characters to set the file type, and the second four to set the creator. Special cases are creator or filetype '****'. If these are encountered the filetype or creator is not modified. Examples:
'ttrottxt' makes files a TeachText read-only document
'****R*ch' makes files a BBEdit document
'********' does nothing
This configuration method was chosen because:
• it allows one to have several copies of typical on disk, each with its own configuration. Typical is only about 12K on disk. I maintain a 'typicals' folder, accessible from the Apple menu which contains about ten copies of typical.
• typical can be run without any user intervention (i.e. no dialog asking for the type and creator to set)
• reconfiguration is easy: just rename the application
• the part of the filename after the eighth character can be used to elucidate the cryptic part, e.g. 'ttrottxt TeachText read-only', 'TEXTR*ch BBEdit textfile' or even (for a copy with appropriate 'typs' and 'tycr' resources) 'TEXTR*ch Alpha/Edit2 to BBEdit'
Monochromize is a utility for converting PICT files into black-and-white PICT files. I wrote it after discovering that most GIF-converters convert even 1-bit GIF files into 8-bit PICT-files. Thus, conversion of a GIF-file results in a more than sevenfold increase in file size. Monochromize shrinks the file back to a manageable size (usually just a little larger than the original GIF-file). Warning: Monochromize does overwrite the file dropped onto it, so you should not drop color pictures you want to keep around on it (read the warning written in large type above, again, please). Also, if a vector-PICT file is dropped it is converted to a black-and-white bitmap. Monochromize uses offscreen GWorld to do its work; the GWorld class included may be useful on its own.
µZak is a utility for playing the sound tracks of QuickTime™ Movies. Just drag the icon of your hard-disk on µZak, and listen to the play. Preferences settings are pretty self-explanatory. µZak shows how one can separate the directory traversal from the handling of the files, by building a list of items to handle. The OpenDoc handler simply adds any item to be opened to the list of items to play, and the actual playing of the sounds is done via the EventLoopHook virtual member of BoxMaker++. This shell shows one way to delay the actual handling of files to after the OpenDoc handler has been called.
Distribution policy:
BoxMaker++ may be freely used and modified. However, distribution of BoxMaker++ or parts of it may only be done by distributing the entire distribution (BoxMaker++ sources, ll-R, touch, typical, Monochromize, and µZak) with sourcefiles and documentation. Note: this implies that distribution of the example dropboxes without this documentation and the full source code is forbidden. Distribution of dropboxes built with BoxMaker++ is allowed, as long as both the documentation of the dropbox (be it in printed or electronic form) and the program itself mention that the dropbox is built using 'BoxMaker++ by Reinder Verlinde'.
An exception to this policy is µZak. Since it is safe enough in the hands of the unwary I have distributed it separately, together with a document describing its use. µZak may be distributed without its source code, as long as that documentation (a SimpleText document called ‘µZak About’) is distributed with it and both the program and its documentation are distributed unmodified.
Version history:
941201: 1.0
For publication with Apprentice, release 2
950120: 1.1
• Renamed the program from 'DropShell++' to 'BoxMaker++' in order to make it more clear that this program was not written by the authors of DropShell.
• Made BoxMaker++ skip folders for which no read privileges exist (instead of bailing out with an error message)
• Slight modification to ll-R to write a line saying so, whenever a folder can not be entered due to lack of read privileges.
Added 'tycr' resource, which allows further restrictions to the files passed on to the 'ODOC' routine.
• Included Monochromize and µZak in the distribution.
• Added some multi-Finder friendliness. Dropboxes can now be sent to the background during a directory traversal.
