Mac-Source 1994 July

home *** CD-ROM | disk | FTP | other *** search

/ Mac-Source 1994 July / Mac-Source_July_1994.iso / Misc Utils / ResHelper / RH Help < prev next >

Wrap

Text File | 1991-03-03 | 16.2 KB | 334 lines | [TEXT/MSWD]

ResHelper - Version 0.80 A Quick Word from the Author: ============================ I've been working on ResHelper off and on for nearly a year as of March, 1991. I wrote this program to address some complaints I had about other resource building programs and learn more about the internals of the Mac. Early on, I decided to solicit suggestions from readers of the INFO-MAC digest available on the BITNET and INTERNET computer networks to see if there were other features that might prove useful to other users. Several readers (maybe 15) responded and some of their suggestions have been incorporated into this program. At this point, I think I've met most of the goals I set for myself in writing this. Since the program seems to be fairly well behaved, I've decided to try my luck at shareware and make it available to INFO-MAC readers. Because I graduated from Washington University in May of 1990, I no longer have direct access to INFO-MAC. However, I still have connections! Eric Oberle, Manager - Computer Consulting at Washington University not only tried out early versions and provided some helpful suggestions, but has graciously volunteered to post the program to INFO- MAC and accept comments from users via electronic mail and forward them to me. Eric's e-mail address is: Eric Oberle <C09615EO@WUVMD.BITNET> Thank you Eric! You can also send comments directly to me at the following address: Michael Hanrahan 1142 West College - Apt K Liberty, MO 64068 USA Now is your chance to actively participate in the development of something designed to help YOU! I cannot promise this program will be supported with an 800 number and quarterly newsletters but then you aren't expected to pay for that either. Version 0.80 is being offered as shareware for a fee of $30 (US funds). If you send in your shareware fee to me at the above address, I will send you a copy of the latest version on a new diskette. NOTE: This release of ResHelper has a 60-day "timer" within it which will disable all commands but Help and Quit 60 days after you first run the program. This "timer" is not intended to punish users who don't send in shareware fees but rather to prevent obsolete versions of the program from persisting in the electronic ether indefinitely. Users who send in their shareware fee will be provided a version which does not include the timer. (now the real help file!) Introduction ============ One of the most tedious aspects of Macintosh software development is the creation of resources used within the program. Despite the Macintosh's status as the most elegant graphics-based computer on the market, some resource builders for Macintosh developers require resource "source code" to be written and "compiled" into the final form or require the same type of information to be specified via dialogs rather than point- click-drag techniques. ResHelper was written to yield the following capabilities: 1) Allow programmers to specify Finder Bundles in a way that the user sees them, without worrying about local resource IDs, global resource IDs, maps between the BNDL and FREFs, etc. 2) Allow dialogs to be edited using standard draw program methods. Select and move multiple items (ResEdit can't do this). Change control names/edit text without having to open a separate dialog. Support clipboard functions while editing dialogs. Allow all item numbers to be seen and modified in one dialog. 3) Allow menus to be created and "test-driven" within the program to verify the placement of separator bars, command key equivalents, etc. 4) Perform the above functions and others without costing the developer an arm and a leg. ResHelper has been written with safety in mind as well. When you edit resources in a file, ResHelper actually makes a copy of the file and applies your changes to the copy. The original input file remains untouched while you edit resources until you issue a Save command. This disk-based approach may be a tad slow for users without hard drives but it guarantees that your input file will NEVER be corrupted by the program and it allows the program to run in a fairly small 350k partition under MultiFinder. History ======= ResHelper was written using THINK's Pascal Version 3.0 on a Macintosh SE (for the first four months) and IIci (the remainder). It has been thoroughly tested on System 6.0.5 on the IIci and will run in as little as 350k under MultiFinder. By the way, a big hats off to the people at Symantec. THINK Pascal is the only program I've used for EXTENDED (and I mean EXTENDED!) periods of time without having the phrase "I really wish they had thought of _____ when they wrote this" pop into my head A very well thought out product, to say the least... Behind the Scenes ================= After you select a file for editing, ResHelper creates a copy of the input file and places the copy, named $$$TEMP RESOURCE$$$ in your System folder. The program also adds an extra resource (named 'fnam') to the copy which contains the name of the input file name and its Finder information. After making any desired changes and issuing a Save command, ResHelper deletes the old version of your input file, then copies the temp file back to the original's folder (or a different folder and name if you did a Save As...). It then removes the 'fnam' resource from the newly saved file. Why is the 'fnam' resource added and removed? If ResHelper ever terminates abnormally (or something else in your Mac hangs), the temp file with that 'fnam' resource will be left in your System folder. The next time ResHelper is launched, it will detect the presence of that old work file and use the filename within the 'fnam' resource to remind you of the old session and ask if you wish to continue. Since the program immediately writes out all resources to that temp file as they are created/changed, you should never lose more work than the changes to a single resource. EVER. Using the Resource Editors ========================== The use of most of the resource editors in ResHelper is fairly obvious. However, the Bundle and Dialog editors deserve some special coverage since they combine the process of editing several different resources into a single integrated environment. Detailed descriptions of these editors are given below. Editing Your Application's Finder Information --------------------------------------------- The Finder uses three pre-defined resources types (BNDL, FREF, and SIZE) and a user-defined resource (referred to as a signature) to control the application's appearance in the Finder and its use of memory when launched under MultiFinder. A quick description of these resources is given below. Type Purpose ---- ------------------------------------------------- BNDL Provides a summary to the Finder of how many unique file types your program uses. It contains a map of all the FREF resources which define those types. It also contains the (hopefully) unique signature of your application. FREF Provide a one-to-one map between a four-character file type and an ICN# resource to display for files of that file type. There is one FREF resource for each file type your program. creates. SIZE Used by the Finder to provide a memory partition if your program is run under MultiFinder. It also contains a set of flags which you use to tell the System how MultiFinder "smart" your application is. Always saved with id = -1. sign If your application's signature was 'sign', you would have a resource of type 'sign' which contains a string which will be displayed in the Version field when the user chooses the Get Info command in Finder's File menu on your final application. Sounds simple, huh? In fact, the process of creating all these resources is normally rather confusing and tedious. ResHelper provides three dialogs which greatly simplify this process. The Size Dialog --------------- The suggested memory partition field should contain the amount of memory (in kilobytes) in which your program operates most efficiently. The minimum should specify the smallest amount of memory in which your program can operate without encountering memory allocation problems. The flags deserve some special explanation. Some key points are summarized in the table below. (By the way, I have no idea what the Save Screen flag's function is.) 32 bit clean You probably shouldn't check this unless you've successfully tested your program under A/UX. getFrontClicks When your program has been placed in the background under MultiFinder and the user clicks on a window to bring your program back to the foreground, MultiFinder will normally NOT pass your program the mouse-down event which brought it back to the front (you probably don't need to see the event anyway). If you DO wish to receive this event, check this box. acceptSuspendResumeEvents Set this flag if your event handling routine includes support for processing suspend/resume events. If you don't check this option, MF will generate extra "bogus" events designed to trick your program into performing any clipboard housekeeping. For this to have any effect, the MultiFinder aware flag should also be set. MultiFinder aware Setting this flag tells MultiFinder that it won't need to generate activate/deactivate events along with the resume/suspend canBackground MultiFinder provides "time slices" to background applications by passing null events to them. If your program doesn't do anything for null events, don't set this flag. onlyBackground If your program doesn't have a user interface (no menus, dialogs, etc.) and cannot run in the foreground, set this flag. getChildDiedEvents If your program launches other applications and you want to know if they terminated abnormally, set this flag. The Bundle Dialog ----------------- The Bundle dialog allows you to specify your application's four- character signature, its Get Info string ("signature string"), and lists all the file types (FREFs) you've defined with their associated ICN#. If you need to create a new FREF, click on the New FREF button. A second dialog will appear which displays all defined ICN#s and provides a field for your new file type. Type in your new file type, select an ICN# then click on Select. Cancel returns you to the main Bundle dialog. Clicking on Save in the Bundle dialog saves all of the various resources and construct the maps between your FREFs and ICN#s. (If this sounds complicated, you should try it the old way once just for fun!) Editing Dialogs --------------- Editing dialogs is also much easier using ResHelper. Choosing the Dialogs command in the Resource menu displays a list of all defined DLOGs. Double-clicking on an item will display that dialog as the end user will see it. Once a dialog is displayed you can perform all of the following functions: • Create an item by clicking on the desired tool in the palette then clicking where you want it in the dialog window. • Reposition an item by clicking on it and dragging it to the proper position. • Resize an item by dragging its bottom right selection handle. When resizing text boxes, the height will automatically be rounded to the nearest integral multiple of the Chicago font size. • Select multiple items by holding down Shift while clicking on the items. You can also drag a rectangle around items to select them (as you do in the Finder). • Hold down Shift while dragging to limit movement to the horizontal or vertical direction. • Change a control's title or the text in a statText or editText item by double clicking on that item to select the text, type the new title, then press Esc or click outside the item's rectangle to finish editing. • Resize the dialog window by dragging in the lower right corner. • Move the dialog window around the screen by dragging its title bar (if it has one) or by clicking in the first four rows of pixels at the top of the window and dragging. • Add PICTs or ICONs by clicking on the appropriate tool, click in the window where you wish to place it, then select the desired PICT/ICON from a list of defined resources. Poof! It's added. You can edit the ICONs in the dialog by double clicking on them. The Windows Options... dialog allows you to specify the type of window for the dialog and indicate whether the dialog window should be initially hidden (useful if you wish to center the window before showing it to the user) or have a close box (for document-type windows). You can change window types even if you've already added items to the dialog. The Set Item Numbers... dialog lists all defined dialog items in numerical order. You can renumber an item by dragging it on top of the item it should follow in the list. Clicking on Finish returns you to your dialog for more editing. When you save a new dialog, you will be prompted for the dialog's title and the resource IDs of the DLOG and DITL resources (normally you'll want to keep these the same). The title will be used to provide a name to the resource which helps identify them later. You can change this information later by choosing the Save As.. command in the Dialog menu instead of Save. If you create a dialog window which is larger than the 9-inch screen on the compact Macintosh models or you positioned the window so it is not entirely visible on the classic screens, you'll be warned of this fact at the time you save the dialog. MF Strings ---------- If your program uses non-standard command names for "Open..." and "Quit" or places them in a menu called something other than "File", your program will not support MultiFinder's ability to open documents from the Finder while your program is already loaded or quit when the user selects Restart/Shutdown. If you wish to support these features, you need to tell MultiFinder which menu contains these commands and the exact name of the commands. The MF Strings dialog allows you to specify the strings needed to pass this information to MultiFinder. After filling in the fields in the dialog, ResHelper will save the strings out as type 'mstr' with ids 100-103. When your program is running, if MultiFinder can't find the Open or Quit command in their normal menu, it will look for these resources in its attempt to find them. Unfinished Business =================== I'm hoping that many users will provide some feedback about features they like or found lacking in the program. However, I'm sure I can guess what some of them are. The following is a list of the features I'm still trying to implement in the program. 1) I have the routines to draw lines and boxes and outline the default button in a dialog working but haven't figured out a viable way to save them. Actually, saving them as PICTs is easy but when a dialog is opened for editing and read from the DITL on disk, I'll need to be able to determine if the PICT is something I created or a random PICT representing a digitized Van Gogh or something meaningless to ResHelper. (Sounds like a job for picComments!) 2) A better algorithm for automatically building an icon mask for ICN#s is needed. 3) Support for running in a shared environment. I hope to dynamically assign temp file filenames yet continue to allow sessions to be restarted. This will require checking along the lines of "1) does a temp file exist?" and "2) does it belong to THIS user?" 4) Support for editing color icons. I don't know of any program that edits cicn's in a Paint-like environment so I imagine this could be VERY difficult to implement. Even without these features, I think/hope most programmers will find ResHelper very useful in developing their own software.