pepke@loligo.cc.fsu.edu (Eric Pepke) (09/29/89)
As you all know, there are a few questions that are asked over and over again. Every once in a while, somebody asks "Why is my menu bar flashing?" or "Why is the right side of my offscreen bitmap cut off?" The cognoscente among us think "Oh, no, not again," and then post 200 notes flaming the poor person or Apple or somebody for the fact that this stuff is not intuitively obvious. These discussions are fun, and the Apple documentation and tech notes are fine, but neither particularly helps the person who would have to do a linear search through it all to answer a question. Long explanations giving options and details and full explanation are great, but the problem is that people don't read them. In order to help solve this problem, I am compiling a list of one-liners about using and programming the Macintosh. A one-liner is defined as a single line of text (fewer than 80 characters, that is) which gives some vital piece of information for a novice user or programmer. They are kept short so that they can all be written on a single sheet of paper and consulted by reading the entire sheet without spending too much time. One-liners can state facts about the Macintosh or give advice. The facts need not tell the complete story, but they should suggest a place to start. The advice need not give the only way of doing a thing and should not be interpreted by experts as offensive if they think they have a better way, but they should give advice which, if followed, will reduce the possible problems later on. They should resemble proverbs more than explanations. One-liners should ideally implicitly contain keywords that the user can look up in the indices of the Macintosh documentation. The one-liner about Easy Access, for example, does not contain dozens of interesting pages about what Easy Access is and how to use it, but a person who knows the name should be able to look it up. This is what I have so far: Users' One-Liners: A flashing Apple menu means the alarm clock is ringing. A beep on opening a desk accessory means DA Handler is not in the System folder. A U-shaped icon at the right of the menu bar means Easy Access is activated. If HyperCard visual effects donUt work, try setting the monitor to 2 colors. Hold down command-F and click OK in the print dialog to make a PostScript file. Hold down command-K instead to make a PostScript file which includes LaserPrep. Turn background printing off before trying to make a PostScript file. Remove the paper tray during LaserWriter power up to avoid the startup page. Programmers' One-Liners: Do not use SetEventMask to disable mouseUp events. Always set the VisRgn and ClipRgn of offscreen ports. Set the ClipRgn first when making a picture. Move and size windows to the bounding box of GetGrayRgn. Check the application name at $910 before exiting with ES within MacsBug. To exit to shell in the mini-debugger, enter SM 0 A9 F4 and then G 0. itemHit will not be set when a dialog filter is called. Use SysEnvirons to find the Blessed Folder. Use GetAppParms to get the name of the application. The high bit of SysParam . volClik enables the alarm clock. Don't make rowBytes in bitMaps greater than 8191. Don't write in the application file. This will fail with read-only devices. Save application preferences in a file in the Blessed Folder. Hide scroll bars when deactivating a window. Call DrawGrowIcon when activating or deactivating a window with a grow region. DrawGrowIcon does not check to see if the window has a grow region. Ensure that the current grafPort is valid at ALL times. DA's might change it. Truncate and reallocate files before overwriting to reduce fragmentation. Check the creator and type of Save As... files before overwriting. Use a disabled UserItem to draw the roundrect outline around the OK button. If you rewrite files by deleting and creating, copy all Finder information. Delete uses the Poor Man's Search Path, so don't delete blindly. Call GetDblTime to get the maximum time for a double click. Call IsDialogEvents and DialogSelect even if GetNextEvent returns false. Use HT in MacsBug to estimate how many times to call MoreMasters. Use SetItem to include meta characters literally in menus. Most of these are from my own experience. Some are straight from what I have seen in the newsgroups over the past year or so. I have checked out most, but not all. If you have suggestions for additions or corrections, please post them in this newsgroup. Eric Pepke INTERNET: pepke@gw.scri.fsu.edu Supercomputer Computations Research Institute MFENET: pepke@fsu Florida State University SPAN: scri::pepke Tallahassee, FL 32306-4052 BITNET: pepke@fsu Disclaimer: My employers seldom even LISTEN to my opinions. Meta-disclaimer: Any society that needs disclaimers has too many lawyers.
carl@Apple.COM (Carl C. Hewitt) (09/29/89)
In article <221@vsserv.scri.fsu.edu> pepke@loligo.cc.fsu.edu (Eric Pepke) writes: >A beep on opening a desk accessory means DA Handler is not in the System folder A beep could also mean that you don't have enough free memory to launch the DA Handler. >Save application preferences in a file in the Blessed Folder. If I'm not mistaken, Apple DTS has officially sanctified the use of a folder called "Preferences" in the System Folder for preference files. Programs have to be written to know about this folder, but if programmers start using it, it will have the nice effect of reducing the number of preference files in the system folder to a manageable number. -- Carl -- /-----------------------------------------------------------------------------\ | internet: carl@apple.com | Apple Computer, Mac CPU ROM group | | applelink: carl | uucp: {sun,decwrl}!apple!carl | \-----------------------------------------------------------------------------/
edgar@gem.mps.ohio-state.edu (Gerald Edgar) (09/29/89)
>Hold down command-F and click OK in the print dialog to make a PostScript file.
Unfortunately, this does not work with MacDraw II. There, you click OK, wait
for the box saying "Printing pages 1 to 99", then QUICKLY hold down F.
In any case, F will do instead of command-F.
Also, hold it down until the message "Creating Postscript File" appears.
--
Gerald A. Edgar
Department of Mathematics Bitnet: EDGAR@OHSTPY
The Ohio State University Internet: edgar@mps.ohio-state.edu
Columbus, OH 43210 ...!{att,pyramid}!osu-cis!shape.mps.ohio-state.edu!edgar
rmh@apple.com (Rick Holzgrafe) (09/30/89)
In article <221@vsserv.scri.fsu.edu> pepke@loligo.cc.fsu.edu (Eric Pepke) writes: > I am compiling a list of one-liners > about using and programming the Macintosh. This idea is great, and I like the sample list. I've already printed it down to post outside my cube wall. (Yes, at Apple! :-) I have one suggested correction. Instead of: > Ensure that the current grafPort is valid at ALL times. DA's might > change it. how about simply: Always call SetPort before drawing. Just a suggestion, no need for further discussion. ========================================================================== Rick Holzgrafe | {sun,voder,nsc,mtxinu,dual}!apple!rmh Software Engineer | AppleLink HOLZGRAFE1 rmh@apple.com Apple Computer, Inc. | "All opinions expressed are mine, and do 20525 Mariani Ave. MS: 27-O | not necessarily represent those of my Cupertino, CA 95014 | employer, Apple Computer Inc."
pepke@loligo (Eric Pepke) (09/30/89)
In article <4466@internal.Apple.COM> rmh@apple.com (Rick Holzgrafe) writes: >This idea is great, and I like the sample list. I've already printed it >down to post outside my cube wall. (Yes, at Apple! :-) Aw, gee. >I have one suggested correction. Instead of: >> Ensure that the current grafPort is valid at ALL times. DA's might >> change it. >how about simply: > Always call SetPort before drawing. >Just a suggestion, no need for further discussion. I want to. This is to avoid a much more insidious problem, which seems ridiculously unlikely but has caused crashes that have been mentioned on the net. The scenario involves two buggy desk accessories whose bugs are subtle and don't show up very often: Desk accessory A plays hard and fast with its grafPorts. It doesn't bother to save the old grafPort when it puts up a window. Most applications don't care, because they always set their grafPort before drawing. Desk accessory B uses one of the QuickDraw calls which don't really affect the current grafPort but require that the current grafPort be valid. I can't remember what these calls are, but they exist. Now consider this--A opens a window and sets the port to the window. A closes the window, leaving the current grafPort in never land. B tries to do its little thing. Kapow! It doesn't even have to be a desk accessory; it can be some background task that uses a dopey pre-notification manager scheme of alerting the user. Unfortunately, in cases like this it is the application which is blamed for the crash. It is easy to avoid simply by doing a SetPort to a known good grafPort every time through the event loop. Perhaps I should say this outright. It is a subtle and rare problem, I know, but one of the major points of the programming one-liners is that if you do what they say, you simply avoid a large number of well known subtle and rare problems. Eric Pepke INTERNET: pepke@gw.scri.fsu.edu Supercomputer Computations Research Institute MFENET: pepke@fsu Florida State University SPAN: scri::pepke Tallahassee, FL 32306-4052 BITNET: pepke@fsu Disclaimer: My employers seldom even LISTEN to my opinions. Meta-disclaimer: Any society that needs disclaimers has too many lawyers.
danno@eleazar.dartmouth.edu (Daniel McKinnon III) (09/30/89)
Seeing the one-liner about the beep when opening a DA raises a question in my mind. I know that if you: a) Don't have DA Handler, OR b) Don't have enough memory for DA handler you get a beep and the DA won't open. Fine. My problem is that on my SE/30 (Sys 6.0.3), with 4 Megs and only 1 application open, I get a beep AND the DA opens. Not a big problem, but annoying. I am running Font/DA Juggler Plus, but this happens even with the DAs installed in the system. Thoughts, anyone? Danno |\_______/| Someone send me a new Tragedy mask graphic!| Daniel McKinnon | | | | O O | Comedy must be played with a straight face;| danno@dartmouth.edu | \ | Only tragedy deserves laughter. | | - | --Clive Barker | | ___ | \ / \ / It's always darkest before it turns pitch black. ------- --Heretix
wdh@well.UUCP (Bill Hofmann) (09/30/89)
In article <4452@internal.Apple.COM> carl@Apple.COM (Carl C. Hewitt) writes: >If I'm not mistaken, Apple DTS has officially sanctified the use of a folder >called "Preferences" in the System Folder for preference files. Programs >have to be written to know about this folder, but if programmers start using >it, it will have the nice effect of reducing the number of preference files >in the system folder to a manageable number. I think you are mistaken. There was a discussion quite some time ago (at one of the Developer Conferences) about just this problem, and Darin Adler said that DTS was thinking about some way to solve the problem, but I haven't heard a peep. The problem is bigger than it appears: aside from the issue of what to call it in English, what happens when you go to another country (I know, if they don't speak English... 8->). As a user, I'd like to see the solution extended to support folders for cdevs and INITs and etc. I suspect (I hope: scott douglass, are you listening?) that the system 7 finder will address this issue a bit better. As far as I'm concerned, this should be a system level support: SysEnvirons or Gestalt or whatever would return a dirID for the location of the preferences folder, and somebody else (Finder, Control Panel General cdev, whatever) would let the user name it what they pleased. -Bill
blob@apple.com (Brian Bechtel) (09/30/89)
How about: Directory IDs are longs, not shorts. Shorts work ALMOST all the time, so beware. Use the file name, directory id, and volume name to uniquely identify a file. --Brian Bechtel blob@apple.com "My opinion, not Apple's"
cderossi@Apple.COM (Christopher Derossi) (09/30/89)
In article <13877@well.UUCP> wdh@well.UUCP (Bill Hofmann) writes: >I think you are mistaken. There was a discussion quite some time ago (at >one of the Developer Conferences) about just this problem, and Darin Adler >said that DTS was thinking about some way to solve the problem, but I haven't >heard a peep. The problem is bigger than it appears: aside from the issue >of what to call it in English, what happens when you go to another country >(I know, if they don't speak English... 8->). In a subsequent forum (another Developer's Conference? MacWorld? I don't remember), Darin and DTS actually sanctioned a folder named "Preferences". However, they never got around to writing a Technical Note, or publishing this decision, so no one knows about it unless they were there. The bigger issues (like international) are a problem, and they aren't. The concept was that it was a good idea to put your settings, preferences, and temporary documents into a folder anyway. And if everyone could agree on a name and location for this folder, then you gain even more, but it isn't required. If you write your code to use a folder named Preferences if it's there, and to create one of it isn't, then you're in good shape. Sure, when you localize your product for another country, you may pick a different name for the folder than other programs did, but you'd be no worse off than if you were the only program using the Preferences folder. DTS further recommends that you create your own folder within the Preferences folder for your documents. That way you avoid potential conflicts, and give the user some reasonable organization. As far as a system-supported solution goes, it's certainly a reasonable idea. We've talked about, we've tossed ideas back and forth, and we're working on it. But no matter what, if anything, gets implemented in System 7.0, you're going to have to deal with a solution for the 6.0.x world, too. And the Preferences folder works nicely. Chris Derossi cderossi@apple.com Blue Meanies, System Software
ralph@cbnewsj.ATT.COM (Ralph Brandi) (10/01/89)
In article <13877@well.UUCP> wdh@well.UUCP (Bill Hofmann) writes: > As a user, I'd like to see >the solution extended to support folders for cdevs and INITs and etc. I >suspect (I hope: scott douglass, are you listening?) that the system 7 >finder will address this issue a bit better. There is already an INIT that takes care of this (and more). It's called Fresh Start. It allows you to choose the INITs that you start up with, set up multiple environments of INITs for those situations when you want to boot up with extra memory, and clean up the System Folder by moving INITs, cdevs, preference files etc. into separate folders. It's shareware ($25). Version 1.1 had a nasty conflict with Suitcase; version 1.2 is out now and is supposed to fix that. If there's interest, I suspect the author, Bob Hablutzel, could be persuaded to post to c.b.m. -- Ralph Brandi ralph@lzfme.att.com att!lzfme!ralph Work flows toward the competent until they are submerged.
mnkonar@manyjars.SRC.Honeywell.COM (Murat N. Konar) (10/02/89)
In article <4492@internal.Apple.COM> cderossi@apple.com writes: [ discussion of where to put preference files deleted ] >But no matter what, if anything, gets implemented in >System 7.0, you're going to have to deal with a solution for the 6.0.x >world, too. And the Preferences folder works nicely. Is there a hidden message here? Why are we going to have to deal with it for the 6.0.x world? Isn't System 7 going to be available for everyone with >= 2Megs? Or is there a sinister move afoot to make System 7 the corporate standard and leave the rest of us with 6.0.x? Sorry to seem so paranoid but I started getting nervous when I saw an Apple developer mailing with a BLUE(!!!!!) Apple logo on it a few months ago. ____________________________________________________________________ Have a day. :^| Murat N. Konar Honeywell Systems & Research Center, Camden, MN mnkonar@SRC.honeywell.com (internet) {umn-cs,ems,bthpyd}!srcsip!mnkonar(UUCP)
rang@cs.wisc.edu (Anton Rang) (10/02/89)
In article <33350@srcsip.UUCP> mnkonar@manyjars.SRC.Honeywell.COM (Murat N. Konar) writes: >In article <4492@internal.Apple.COM> cderossi@apple.com writes: >[ discussion of where to put preference files deleted ] >>But no matter what, if anything, gets implemented in >>System 7.0, you're going to have to deal with a solution for the 6.0.x >>world, too. And the Preferences folder works nicely. > >Is there a hidden message here? Why are we going to have to deal with >it for the 6.0.x world? Isn't System 7 going to be available for >everyone with >= 2Megs? Not everybody is going to be upgrading to system 7. Why? A few people will have software which breaks, and not have any reason to upgrade. Others just won't bother. And there will be *plenty* of people who haven't got enough memory out there! I try to code defensively (not assuming the existence of HFS or WNE), and most of my programs work on system 3.2 and up (that's the earliest system I have a copy of except for my original at home). If you're only writing for people with 2MB of memory and a 20MB hard drive, you might not have to worry about 6.0.x--but you'll lose a lot of your potential market, too. +----------------------------------+------------------+ | Anton Rang (grad student) | rang@cs.wisc.edu | | University of Wisconsin--Madison | | +----------------------------------+------------------+
kent@sunfs3.camex.uucp (Kent Borg) (10/03/89)
For a Programmer's One-Liner: To dim text--or anything else--draw 50% gray patBic over it. -- Kent Borg "Then again I could be foolish kent@lloyd.uucp not to quit while I'm ahead..." or -from Evita (sung by Juan Peron) ...!husc6!lloyd!kent
mnkonar@gorby.SRC.Honeywell.COM (Murat N. Konar) (10/03/89)
Here's a one-liner to which I don't know the answer: How do you go about registering your signature (ie RSED for ResEdit) with Apple? I looked through the Tech notes and Q&A stacks and couldn't find the answer. I know I saw it somewhere, though. ____________________________________________________________________ Have a day. :^| Murat N. Konar Honeywell Systems & Research Center, Camden, MN mnkonar@SRC.honeywell.com (internet) {umn-cs,ems,bthpyd}!srcsip!mnkonar(UUCP)
keith@Apple.COM (Keith Rollin) (10/03/89)
In article <33424@srcsip.UUCP> mnkonar@gorby.UUCP (Murat N. Konar) writes: >Here's a one-liner to which I don't know the answer: > >How do you go about registering your signature (ie RSED for ResEdit) >with Apple? I looked through the Tech notes and Q&A stacks and >couldn't find the answer. I know I saw it somewhere, though. got to go to an even earlier source. See Inside Mac on page III-9. By the way, the mailstop in IM is out of date (though mail sent to it will still get to us). If you'd like, you could use the more current Mail Stop 75-3T. -- ------------------------------------------------------------------------------ Keith Rollin --- Apple Computer, Inc. --- Developer Technical Support INTERNET: keith@apple.com UUCP: {decwrl, hoptoad, nsc, sun, amdahl}!apple!keith "Argue for your Apple, and sure enough, it's yours" - Keith Rollin, Contusions
pepke@loligo.cc.fsu.edu (Eric Pepke) (10/10/89)
Here is the latest iteration of the Macintosh One-Liners: Users' One-Liners A beep on trying to open a desk accessory may mean the DA Handler is missing. A beep on trying to open a desk accessory may mean there is not enough memory. If opening a document from Finder doesn't work, open it within the application. A flashing Apple menu means the alarm clock is ringing. A U-shaped icon at the right of the menu bar means Easy Access is activated. HyperCard visual effects won't work on monitors set to more than 2 colors. Hold down the F key and click OK in the print dialog to make a PostScript file. Hold down the K key instead to make a PostScript file which contains LaserPrep. Turn background printing off before trying to make a PostScript file. Remove the paper tray during LaserWriter power-up to avoid the startup page. Hold down the mouse while powering on to eject any disk in the computer. Don't put disks on the left side of a small Macintosh or near loudspeakers. It is safer to rebuild the desktop under Finder than under Multifinder. Finder's default memory size is a bare minimum. Increase it with Get Info. Never put more than one System file on a disk. If the cursor is surrounded by a big black rectangle, Close View is activated. Programmers' One-Liners The maximum number of windows in Finder is stored in LAYO resource 128. Don't use SetEventMask to disable mouseUp events. SetPort to a known good grafPort once every time through the event loop. Calling WaitNextEvent with more than 50 ticks will fail on some systems. Use SetItem to include meta characters literally in menus. GetResource doesn't return resNotFound. Check for a NIL handle instead. Move and size windows to the bounding box of GetGrayRgn. Hide scroll bars when deactivating a window. Call DrawGrowIcon when activating or deactivating a window with a grow region. DrawGrowIcon does not check to see if the window has a grow region. itemHit will not be set when a dialog filter is called. Use a disabled UserItem to draw the roundrect outline around the OK button. Call IsDialogEvents and DialogSelect even if GetNextEvent returns false. ModalDialog assumes the dialog is already visible and in the front. Always set the VisRgn and ClipRgn of offscreen ports. Set the ClipRgn first when making a picture. Don't make rowBytes in bitMaps greater than 8191. To dim text, draw a rectangle with penPat=gray and penMode=patBic over it. To draw rotated text, draw to an offscreen bitmap, rotate it, and CopyBits it. Don't write in the application file. This will fail with read-only devices. Save application preferences in a folder named Preferences in the System Folder Truncate and reallocate files before overwriting to reduce fragmentation. Check/change the creator and type of Save As... files before overwriting. If you rewrite files by deleting and creating, copy all Finder information. Delete uses the Poor Man's Search Path, so don't delete blindly. Directory IDs are longs, not shorts. Shorts work ALMOST all the time. Call GetDblTime to get the maximum time for a double click. Measure double click time from mouse up to mouse down. Use SysEnvirons to find the System (Blessed) Folder. Use GetAppParms to get the name of the application. The high bit of SysParam . volClik enables the alarm clock. Check the application name at $910 before exiting with ES within MacsBug. To exit to shell in the mini-debugger, enter SM 0 A9 F4 and then G 0. Use HT in MacsBug to estimate how many times to call MoreMasters. Put an odd long at location zero on a 68000 to help find NIL references. Compiled by Eric Pepke Additional material by Keith Rollin, Gregory Dudek, Brian Bechtel, Henry Minsky, Carl C. Hewitt, Jim Lyons, Alex Lau, Kent Borg. Eric Pepke INTERNET: pepke@gw.scri.fsu.edu Supercomputer Computations Research Institute MFENET: pepke@fsu Florida State University SPAN: scri::pepke Tallahassee, FL 32306-4052 BITNET: pepke@fsu Disclaimer: My employers seldom even LISTEN to my opinions. Meta-disclaimer: Any society that needs disclaimers has too many lawyers.
wilkins@jarthur.Claremont.EDU (Mark Wilkins) (10/10/89)
In the Mac One Liners article pepke@loligo.cc.fsu.edu (Eric Pepke) writes: >Hold down the K key instead to make a PostScript file which contains >LaserPrep. This doesn't work using LW 6.0 for some reason. The PS files are identical if you use F or K. SO, my question is, is there some way of making a file with LaserPrep also? Apple people, any answers? This, even though undocumented, is an important feature of the software and will make many sites refuse to use 6.0 if it is not present.
softa@vax.SPD.3Com.Com (Douglas Phillips) (10/13/89)
In article <256@vsserv.scri.fsu.edu> pepke@loligo.cc.fsu.edu (Eric Pepke) writes: >Programmers' One-Liners >Directory IDs are longs, not shorts. Shorts work ALMOST all the time. At least one networking company returns longs for the directory IDs and your software will screw up if you use a short. Lots of people make this mistake. Douglas
stores@unix.SRI.COM (Matt Mora) (12/16/89)
In article <404@fsu.scri.fsu.edu> pepke@scri1.scri.fsu.edu (Eric Pepke) writes: >Here is the latest version of the Macintosh One-Liners. It's now two pages >long. > >Files >File Manager routines with dirID=0 use the Poor Man's Search Path. >File manager calls with a dirID of zero use the Poor Man's Search Path. Erik Pepke, Are these the same thing? The list is excellent. Thanks for taking the time to compile it. -- ___________________________________________________________ Matthew Mora SRI International stores@unix.sri.com ___________________________________________________________
pepke@loligo (Eric Pepke) (12/16/89)
In article <6927@unix.SRI.COM> stores@unix.UUCP (Matt Mora) writes: >>File Manager routines with dirID=0 use the Poor Man's Search Path. > >>File manager calls with a dirID of zero use the Poor Man's Search Path. > >Are these the same thing? Yes; the duplication (and another) have already been pointed out to me. I have tried to cancel the previous posting, and here is a corrected version: ---------------- Here is the latest version of the Macintosh One-Liners. It's now two pages long. The Macintosh One-Liners are intended to condense onto a couple of sheets of paper information about some of the most common Macintosh problems and programming pitfalls. Each one-liner is a single line of text, shorter than 80 characters, which informs about one aspect of Macintosh use or programming. The one-liners are brief and do not give complete information about their topics. This is intentional. Detailed documentation exists elsewhere, mostly in Inside Macintosh and in the Technical Notes. If you need more information than is provided in a one-liner, you should be able to determine it by a little experimentation or by looking it up using the words in the one-liner as hints. One-liners give either facts or advice. The facts may be obvious to some people and obscure to others but are important for all. The advice is intended to help keep people from running into the most common nontrivial problems. Like proverbs, the advice may not be absolute and may sometimes be more conservative than is strictly neccessary. However, I have found that a little constructive paranoia can go a long way toward avoiding problems, and more than once I have taken a precaution which seemed extreme at the time but which saved my skin later on. The one-liners started as a list I made for myself of things to remember while writing programs. I have augmented them with my condensed records of several years of Info-Mac, Usenet, and Delphi digests and one year of Usenet reading. People who have contributed to the list since its first release are mentioned at the end. The result is very much a gestalt of the Macintosh lore I have seen and depends on the wisdom and efforts of many people. If I have forgotten to include your name, I apologize. Send suggestions for additional one-liners to pepke@gw.scri.fsu.edu on the Internet or PEPKE@FSU on BITNET. Have fun. Users' One-Liners A beep on trying to open a desk accessory may mean the DA Handler is missing. A beep on trying to open a desk accessory may mean there is not enough memory. If opening a document from Finder doesn't work, open it within the application. A flashing Apple menu means the alarm clock is ringing. Pull down Alarm Clock. A U-shaped icon at the right of the menu bar means Easy Access is activated. HyperCard visual effects won't work on monitors set to more than 2 colors. Hold down the F key and click OK in the print dialog to make a PostScript file. Hold down command-K instead to make a PostScript file which contains LaserPrep. Turn background printing off before trying to make a PostScript file. Remove the paper tray during LaserWriter power-up to avoid the startup page. Hold down the mouse button while powering on to eject any disk in the computer. Don't put disks on the left side of a small Macintosh or near loudspeakers. Never rotate a hard disk drive while it's running, not even gently. If the cursor is surrounded by a big black rectangle, Close View is activated. It is safer to rebuild the desktop under Finder than under Multifinder. Finder's default memory size is a bare minimum. Increase it with Get Info. Putting more than one System file on a disk can cause big trouble. The maximum number of windows in Finder is stored in LAYO resource 128. To make a TeachText file read-only, change its file type from 'TEXT' to 'ttro' The first option-space in a TeachText file shows PICT 1000, the 2nd 1001, etc. You can increase the maximum number of files open using a boot block editor. Programmers' One-Liners The Main Loop and Events Call MaxApplZone and MoreMasters when the application starts up. If you call SetApplLimit, do it before calling MaxApplZone. Use HT in MacsBug while running to estimate how many times to call MoreMasters. Don't use SetEventMask to disable mouseUp events. Better not to use it at all. SetPort to a known good grafPort once every time through the event loop. Calling WaitNextEvent with more than 50 ticks will fail on some systems. Set the cursor on suspend and resume events. Call GetDblTime to get the maximum time for a double click. Measure double click time from mouse up to mouse down. Call either WaitNextEvent or both GetNextEvent and SystemTask. Call IsDialogEvents and DialogSelect even if GetNextEvent returns false. Menus Use SetItem to include meta characters literally in menus. Never make MENU resources purgeable. Resources GetResource never produces resNotFound. Check for a NIL handle instead. To create a resource file, call Create, then CreateResFile. To open a resource file read-only for shared access, use OpenRFPerm. Don't leave ResLoad set to false. GetResource on a dctb may return a non-resource copy of the dctb. Windows, Alerts, and Dialogs Move and size windows to the bounding box of GetGrayRgn. Hide scroll bars when deactivating a window. Call DrawGrowIcon when activating or deactivating a window with a grow region. DrawGrowIcon does not check to see if the window has a grow region. Call PenNormal before calling DrawGrowIcon. itemHit will not be set when a dialog filter is called. Use a disabled UserItem to draw the roundrect outline around the OK button. ModalDialog assumes the dialog is already visible and in the front. Use screenBits . bounds to center dialogs, alerts, etc. below the menu bar. If you save window locations in files, they may not be valid for all monitors. DragWindow expects startPt in boundsRect; if not it may not call SelectWindow. SelectWindow does not automatically call SetPort. You must do that yourself. Drawing Always set the VisRgn and ClipRgn of offscreen ports. Set the ClipRgn first when making a picture. Don't make rowBytes in bitMaps greater than 8191. To dim text, draw a rectangle with penPat=gray and penMode=patBic over it. To draw rotated text, draw to an offscreen bitmap, rotate it, and CopyBits it. Don't use picSize to determine the size of a picture. Check the handle size. Never draw outside a window except in XOR mode for temporary effects like drag. To avoid animation flicker, synchronize drawing to the vertical retrace. Lock handles to pictures before calling DrawPicture. CopyBits on more than 3Kb data will work, but it might have to allocate memory. Files Don't write in the application file. This will fail with read-only devices. Use PBGetVInfo to convert a VRefNum to a volume name. Delete uses the Poor Man's Search Path, so don't delete blindly. File Manager routines with dirID=0 use the Poor Man's Search Path. Truncate and reallocate files before overwriting to reduce fragmentation. Check/change the creator and type of Save As... files before overwriting. If you rewrite files by deleting and creating, copy all Finder information. Directory ID's are longs, not shorts. Shorts work ALMOST all the time. Always set the version number that appears in some file manager calls to 0. To convert a pathRefNum to a name or file number, use PBGetFCBInfo. Prevent the creation of files with names that begin with a period. Interrupts and VBL Tasks Don't call any Memory Manager routines during an interrupt. Unlocked handles may not be valid during an interrupt. To synchronize to the vertical retrace on Macs with slots, use SlotVInstall. Handles and Pointers Lock handles before passing their dereferenced pointers to any routine. Lock handles before setting referenced data to expressions containing functions Put an odd long at location zero on a 68000 to help find NIL handle references. Call MoveHHi before locking a handle to avoid memory fragmentation. Use HGetState/HLock/HSetState to lock a handle then put it back as it was. General Always use unsigned characters within text and Pascal-format strings. Save application preferences in a folder named Preferences in the System Folder Use SysEnvirons to find the System (Blessed) Folder. Use GetAppParms to get the name of the application. The high bit of SysParam . volClik enables the alarm clock. Check the application name at $910 before exiting with ES within MacsBug. To exit to shell in the mini-debugger, enter SM 0 A9 F4 and then G 0. In Pascal, don't nest procedures to be passed by procedure pointer. In Pascal, "with theHandle^^" is unsafe if the heap can move. Controversy Corner (Don't flame me; I'm just the messenger.) Avoid writing tail patches for traps. There is no official way to tell if MultiFinder is running or not. Compiled by Eric Pepke Additional material by Steve Maker, Keith Rollin, Gregory Dudek, Brian Bechtel, Henry Minsky, Carl C. Hewitt, Jim Lyons, Alex Lau, Kent Borg, Peter W. Poorman, Ross Yahnke, Mark Fleming.
pepke@gw.scri.fsu.edu (Eric Pepke) (03/29/90)
Here is the latest version of the Macintosh One-Liners. It's now two pages long. The Macintosh One-Liners are intended to condense onto a couple of sheets of paper information about some of the most common Macintosh problems and programming pitfalls. Each one-liner is a single line of text, shorter than 80 characters, which informs about one aspect of Macintosh use or programming. The one-liners are brief and do not give complete information about their topics. This is intentional. Detailed documentation exists elsewhere, mostly in Inside Macintosh and in the Technical Notes. If you need more information than is provided in a one-liner, you should be able to determine it by a little experimentation or by looking it up using the words in the one-liner as hints. One-liners give either facts or advice. The facts may be obvious to some people and obscure to others but are important for all. The advice is intended to help keep people from running into the most common nontrivial problems. Like proverbs, the advice may not be absolute and may sometimes be more conservative than is strictly neccessary. However, I have found that a little constructive paranoia can go a long way toward avoiding problems, and more than once I have taken a precaution which seemed extreme at the time but which saved my skin later on. The one-liners started as a list I made for myself of things to remember while writing programs. I have augmented them with my condensed records of several years of Info-Mac, Usenet, and Delphi digests and one year of Usenet reading. People who have contributed to the list since its first release are mentioned at the end. The result is very much a gestalt of the Macintosh lore I have seen and depends on the wisdom and efforts of many people. If I have forgotten to include your name, I apologize. Send suggestions for additional one-liners to pepke@gw.scri.fsu.edu on the Internet or PEPKE@FSU on BITNET. Have fun. Users' One-Liners A beep on trying to open a desk accessory may mean the DA Handler is missing. A beep on trying to open a desk accessory may mean there is not enough memory. If opening a document from Finder doesn't work, open it within the application. A flashing Apple menu means the alarm clock is ringing. Pull down Alarm Clock. A U-shaped icon at the right of the menu bar means Easy Access is activated. HyperCard visual effects won't work on monitors set to more than 2 colors. Hold down the F key and click OK in the print dialog to make a PostScript file. Hold down command-K instead to make a PostScript file which contains LaserPrep. Turn background printing off before trying to make a PostScript file. Remove the paper tray during LaserWriter power-up to avoid the startup page. Hold down the mouse button while powering on to eject any disk in the computer. Don't put disks on the left side of a small Macintosh or near loudspeakers. Never rotate a hard disk drive while it's running, not even gently. If the cursor is surrounded by a big black rectangle, Close View is activated. It is safer to rebuild the desktop under Finder than under Multifinder. Finder's default memory size is a bare minimum. Increase it with Get Info. Putting more than one System file on a disk can cause big trouble. The maximum number of windows in Finder is stored in LAYO resource 128. To make a TeachText file read-only, change its file type from 'TEXT' to 'ttro' The first option-space in a TeachText file shows PICT 1000, the 2nd 1001, etc. You can increase the maximum number of open files using a boot block editor. Programmers' One-Liners The Main Loop and Events Call MaxApplZone and MoreMasters when the application starts up. If you call SetApplLimit, do it before calling MaxApplZone. Use HT in MacsBug while running to estimate how many times to call MoreMasters. Don't use SetEventMask to disable mouseUp events. Better not to use it at all. SetPort to a known good grafPort once every time through the event loop. Calling WaitNextEvent with more than 50 ticks will fail on some systems. Set the cursor on suspend and resume events. Call GetDblTime to get the maximum time for a double click. Measure double click time from mouse up to mouse down. Call either WaitNextEvent or both GetNextEvent and SystemTask. Call IsDialogEvents and DialogSelect even if GetNextEvent returns false. Menus Use SetItem to include meta characters literally in menus. Never make MENU resources purgeable. Resources GetResource never produces resNotFound. Check for a NIL handle instead. To create a resource file, call Create, then CreateResFile. To open a resource file read-only for shared access, use OpenRFPerm. Don't leave ResLoad set to false. GetResource on a dctb may return a non-resource copy of the dctb. Windows, Alerts, and Dialogs Move and size windows to the bounding box of GetGrayRgn. Hide scroll bars when deactivating a window. Call DrawGrowIcon when activating or deactivating a window with a grow region. DrawGrowIcon does not check to see if the window has a grow region. Call PenNormal before calling DrawGrowIcon. itemHit will not be set when a dialog filter is called. Use a disabled UserItem to draw the roundrect outline around the OK button. ModalDialog assumes the dialog is already visible and in the front. Use screenBits . bounds to center dialogs, alerts, etc. below the menu bar. If you save window locations in files, they may not be valid for all monitors. DragWindow expects startPt in boundsRect; if not it may not call SelectWindow. SelectWindow does not automatically call SetPort. You must do that yourself. DialogSelect responds to activate events but ignores suspend/resume events. Drawing Always set the VisRgn and ClipRgn of offscreen ports. Set the ClipRgn first when making a picture. Don't make rowBytes in bitMaps greater than 8191. To dim text, draw a rectangle with penPat=gray and penMode=patBic over it. To draw rotated text, draw to an offscreen bitmap, rotate it, and CopyBits it. Don't use picSize to determine the size of a picture. Check the handle size. Never draw outside a window except in XOR mode for temporary effects like drag. To avoid animation flicker, synchronize drawing to the vertical retrace. Lock handles to pictures before calling DrawPicture. CopyBits on more than 3Kb data will work, but it might have to allocate memory. The small Mac screen is 512 pixels wide by 342 pixels high including menu bar. Files Don't write in the application file. This will fail with read-only devices. Use PBGetVInfo to convert a VRefNum to a volume name. Delete uses the Poor Man's Search Path, so don't delete blindly. File Manager routines with dirID=0 use the Poor Man's Search Path. Truncate and reallocate files before overwriting to reduce fragmentation. Check/change the creator and type of Save As... files before overwriting. If you rewrite files by deleting and creating, copy all Finder information. Directory ID's are longs, not shorts. Shorts work ALMOST all the time. Always set the version number that appears in some file manager calls to 0. To convert a pathRefNum to a name or file number, use PBGetFCBInfo. Prevent the creation of files with names that begin with a period. Interrupts and VBL Tasks Don't call any Memory Manager routines during an interrupt. Unlocked handles may not be valid during an interrupt. To synchronize to the vertical retrace on Macs with slots, use SlotVInstall. Handles and Pointers Lock handles before passing their dereferenced pointers to any routine. Lock handles before setting referenced data to expressions containing functions Put an odd long at location zero on a 68000 to help find NIL handle references. Call MoveHHi before locking a handle to avoid memory fragmentation. Use HGetState/HLock/HSetState to lock a handle then put it back as it was. General Always use unsigned characters within text and Pascal-format strings. Save application preferences in a folder named Preferences in the System Folder Use SysEnvirons to find the System (Blessed) Folder. Use GetAppParms to get the name of the application. The high bit of SysParam . volClik enables the alarm clock. Check the application name at $910 before exiting with ES within MacsBug. To exit to shell in the mini-debugger, enter SM 0 A9 F4 and then G 0. In Pascal, don't nest procedures to be passed by procedure pointer. In Pascal, "with theHandle^^" is unsafe if memory compaction can occur. Controversy Corner (Don't shoot me; I'm just the messenger.) Avoid writing tail patches for traps. There is no official way to tell if MultiFinder is running or not. Compiled by Eric Pepke Additional material by Steve Maker, Keith Rollin, Gregory Dudek, Brian Bechtel, Henry Minsky, Carl C. Hewitt, Jim Lyons, Alex Lau, Kent Borg, Peter W. Poorman, Ross Yahnke, Mark Fleming, Mark Anderson. Eric Pepke INTERNET: pepke@gw.scri.fsu.edu Supercomputer Computations Research Institute MFENET: pepke@fsu Florida State University SPAN: scri::pepke Tallahassee, FL 32306-4052 BITNET: pepke@fsu Disclaimer: My employers seldom even LISTEN to my opinions. Meta-disclaimer: Any society that needs disclaimers has too many lawyers.