Celestin Apprentice 2/Apprentice-Release2.iso/Information/Programming/Mac Programming FAQ/Mac Programming FAQ 3⁄3

Text File | 1994-12-08 | 18.2 KB | 465 lines | [TEXT/R*ch]

*8* IAC

8.1) Q: What are AppleEvents?

A: AppleEvents are a level-5 network protocol.  If you are not familiar
with the ISO network stack, this means it's a way of structuring sessions
between network entities (programs) that is not dependent on the
underlying protocol (such as PPC or TCP/IP) Despite being a network
protocol, they can be very useful on Macs that are not on a network.  In
short, they provide applications with a comprehensive way to send
arbitrary structured data to other applications (or themselves) which
receive the events through their main event loop.

The AppleEvent Object Model is a way of looking at applications and the
data they contain, and also a level-6 network protocol.  You _can_ send
AppleEvent Object Model data through AppleEvents (and the standard
AppleEvents defined in the AppleEvent Registry use it) but you don't have
to - unless you want to talk with other applications, of course, then the
AEOM is a lingua franca.

8.2) Q: What are the four required AppleEvents?

A: There are four events your application really must implement if you
want to sell it: the kCoreEventClass class, kAEOpenApplication,
kAEQuitApplication, kAEOpenDocuments and kAEPrintDocuments events IDs.
When you support these events (or any AppleEvents) you will not get
startup info through GetAppParams() anymore, unless you run under System
6 of course.  The kAEOpenApplication event will be sent to you when the
user double-clicks your app and it's not started yet.  When receiving it,
you can put up a new untitled window.

kAEOpenDocuments is sent when the user double-clicks your apps documents.
Note that if the first AppleEvent you receive is a kAEOpenDocuments
event, the user started your app by double-clicking its documents.

kAEPrintDocuments is sent when the user selects your documents and
chooses "Print" in the Finder menu.  If this is the first AppleEvent you
receive, you should print the documents and then quit the application
again; if you received a kAEOpenApplication or kAEOpenDocuments event
before this, you should just print the documents and close them when
you're done.

kAEQuitApplication is sent to you when the user chooses "Shutdown" or
"Restart" from the Apple Menu.  You should ask the user whether he wants
to save any unsaved changed documents, and then quit unless the user
presses Cancel.

Interestingly enough, you can use these four AppleEvents to send even to
non-AE-aware applications, and the system will translate these events
into fake menu selections for you.

A good way of shutting down the Finder is to send it a Quit AppleEvent.
You should send a Quit AppleEvent to File Sharing Extension before you
shut down the Finder, though; the FSE is found by looking for a process
with the creator 'hhgg'.

8.3) Q: Are there any limits or tradeoffs with AppleEvents?

A: As always, more power means more responsibility.

AppleEvents sent to applications on other Macs require authentification
the first time they are sent.  If the remote Mac allows Guests to link to
programs, the INIT AutoGuest 2.0 might help (or the code solution that
comes with it and you can build into your application)

In the first version of the AppleEvent manager, there was a total 64K
limit on the size of data and overhead.  This limit has been lifted with
the version of the AppleEvent manager that comes with AppleScript.

AppleEvents require a lot of memory copying and handle resizing in their
construction; this means that large AppleEvents may be slow in
construction, especially when compared to a pure PPC Toolbox or
ADSP/ASDSP link.

You should use your own application signature as event class for
AppleEvents you make up, in order not to collide with anybody else.
Other than that, you are free to make your own events for your own needs,
though supporting the required events and at least a subset of the Core
event suite will buy you a lot of functinality from within AppleScript.
Especially important are the Get Current Selection and Set Current
Selection events (which are really Get/Set Data on the contents of the
current selection of the application)

The signature for your application SHOULD be registered with DTS to avoid
conflicts; this is done through e-mail to [e-mail]
and the form you use is located on the developer CDs and found on
ftp.apple.com.

8.4) Q: How do AppleEvents interface with AppleScript?

A: AppleEvents are the meat and potatoes of AppleScript.  If you support
the AppleEvent Object Model from within your application, users can
control you through AppleScript.

The first thing you should do is get ahold of Inside Mac:
Interapplication Communication, and a copy of the AppleEvents Registry.
The former tells you all you ever need to know about AppleEvents, while
the latter is paramount for implementing the right standard events.  If
everybody use the standard events, dynamic data interchange between any
applications will become sweet reality!

Then there is the 'aete' resource which lets you put names on the events
you support, so that users can "Open Terminology" on your application
from within the Apple Script Editor and use the proper AppleScript
commands in their scripts.  The format of an aete resource is defined in
Inside Macintosh: Interapplication Communication.

8.5) Q: Can I compile and run scripts from within my application?

A: Yes, this is very simple.  There are toolbox calls for reading
scripts, compiling scripts, and executing scripts.  (OSACompile,
OSAExecute) These are all documented in Inside Mac: Interapplication
Communication.

8.6) Q: Is this a good way of getting a macro language almost
for free?

A: "Good" is an understatement.  Just let users write scripts, load them
into menu items and go.  Total systems integration in under a week,
including adding support for the AEOM to your application.

There is source code for an application called "MenuScripter" on the
developer CD which shows you how to do an application with all of the
menus being AppleScript scripts.

8.7) Q: Why do I get error -903 (noPortErr) when I try to send an Apple
Event?

A: Make sure the isHighLevelEventAware flag in your application's SIZE
resource is set.  The AE Manager won't allow you to send events if you're
not able to receive them.

*9* Standalone Code and Linking

9.1) Q: How do I do code resources/extensions/external functions, much
like HyperCard XCMDs only for my app/extension?

A: Here is what you need to do:

Define a storage location for the plug-ins.  such as, for an application
called Foo, a folder called "Foo Pouch/ PlugIns/ Modules/ Tools/ Etc",
which your installer creates, and which you search for in the same
folder as your application, the preferences folder, and the System
Folder (for System 6 (no preferences)) the name of the pouch folder
should be in a 'STR ' or 'STR#' resource for easy internationalization.

Next, define a resource type to hold your plug-in exectuable code.  You
should allow any resID number, since some development systems have
restrictions on which id numbers can be used for multi-segment code
resources.

Decide whether you will allow multiple code resources per file.  For
example, Photoshop lets you bundle an import resource, an export
resource, and a filter into the same file, each is its own resource
type.  It uses the resource name to tell the user, so each has its own
name.

Decide on the user interface to plug-ins.  Commonly, at program
start-up, you scan the pouch and collect all the files of the correct
types.  Then you scan for appropriate code resources, then put the names
of the resources in the menus.  You can also use the file names, or run
the code resources and ask them for the correct name.

Decide on the calling convention.  MPW likes to pass parameters as
longs, and pascal development systems usually can't generate C
interfaces, so your best bet is to have the entry point of your code
resource be something like:

extern pascal long PlugIn(long selector, CallbackPtr callback,
        long param1, long param2, long param3, long refcon);

where params 1 through 3 will have specific meanings depending upon
which function selector is asking to be performed.

CallbackPtr is something like this:
typedef struct CallbackRec{
        DrawFunc        erase;
        DrawFunc        paint;
}CallbackRec, *CallbackPtr;

where DrawFunc is something like:
typedef pascal void (*DrawFunc)(Rect *);

This is the place where you define services that your application will
perform when asked to by the code resource of the plug-in.

You'll need to define a bunch of selectors for what you want the plug-in
to do.

You should definately give the plug-in an Init selector, and a dispose
selector, and have Init return an error or a refcon, which will be
passed back to the plug-in on each call, so the plug-in can have some
persistent storage.  You should definately set the CurResFile to the
plug-in's file while it is running, so it can easily get at any
resources it needs.

The Init selector should pass the interface version in param1 and the
program version in param2, so that the plug-in can cope with different
versions of your program.

The actual call to the plug-in looks like:

*code*
    h = GetResource('PLUG', 1);
    HLock(h);
    xh = StripAddress(h);
    ((PlugInFunc) *xh)(kInit, callbacks, kInterfaceVer1, kProgVer1, 0, 0);
    HUnlock(h);
*end*

The StripAddress is important; if your app is running in 24bit
mode, the resource handle may contain tag bits and you don't
want strange things to happen if the code resource switches into
32bit mode (which QuickDraw may do, incidentally)

Exactly how you structure your calling conventions is up to you;
there is no accepted standard (except for HyperCard XCMDs, but
that is probably overkill for you).

*10* Compatibility

10.1) Q: I see all these people call Gestalt without first
checking whether it's implemented. Isn't that bad?

A: No; Gestalt and a few other traps (the HXxx file manager
traps, and FindFolder) are implemented using glue so they do the
right thing even if the trap is not implemented.

If you want to get rid of the glue, you can #define
SystemSevenOrLater (and, using Think C/C++, re-pre-compile
MacHeaders) However, then you will be responsible for checking
for these features before you use them.

10.2) Q: What more functions are implemented in glue?

A: Wake Up and Smell the Glue!

How often have you wished you could use that cool new ToolBox
call, but didn't want to make your application System 7
dependent? Well, it might be that you *could* in fact have used
the call. Several traps are implemented in glue, that is, much
of their functionality is linked into your application and thus
available even if you are running under an old System.

This list applies to MPW 3.2 and should also be valid for the
current version of Think C. If you find any inaccuracies, please
report them to me. ([e-mail])

FSOpen: Tries first OpenDF, then Open.

HOpenResFile: Full functionality emulated if trap not available

HCreateResFile: Full functionality emulated if trap not
available

FindFolder: Under System 6, understands the following values for
folderType and returns the System Folder for all of them:

kAppleMenuFolderType

kControlPanelFolderType

kExtensionFolderType

kPreferencesFolderType

kPrintMonitorDocsFolderType

kStartupFolderType

kSystemFolderType

kTemporaryFolderType

SysEnvirons: Full functionality emulated if trap not available

NewGestalt: Returns an error if not implemented

ReplaceGestalt: Returns an error if not implemented

Gestalt: The following selectors are always implemented:

vers    mach    sysv    proc    fpu

qd      kbd     atlk    ram     lram

10.3) Q: I have to support System 6, don't I?

A: It would be foolish to lock yourself out of the many benefits
the System 7 API provides for software that you start to write
now. Some of the System 6 and older things (likely SFGetFile and
wdRefNums among others) will be phased out of the interfaces and
lose support; especially on future platforms.

The installed base of System 7 is larger than that of System 6;
this is not surprising because Apple has been shipping System 7
for several years with all new machines, including the LCII,
Classic II, Performas and Color Classic. Another argument is
that newer computer owners (having System 7) are much more
likely to buy new software than old computer owners who have
systems that already do what they want them to.

The added work to support both System 6 and System 7 is
significant; if you have the time and money you may want to do
it, but only supporting System 6 and not System 7 is doomed to
fail in the market of today.

Some may call this position subjective; I call it business sense
based on market demographics. A rule of thumb may be that if you
target color machines only, you can just as well demand System 7
as well.

10.4) Q: Why does my application work on an SE with accellerator
(or a Mac II or Quadra), but not on one without?

A: Assuming you're not calling Color QuickDraw (which is not
available on accellerated SEs), you most probably have an
odd-aligned word access somewhere.

The 68000 does not allow words or longwords to be read from odd
addresses, while the 68020 and up relaxes this restriction (it
still is slower than aligned-word access though)

This may or may not crash depending on your compiler:

*code*
struct foo {
   char c1 ;
   char c2 ;
   char c3 ;
   char c4 ;
   char c5 ;
} bar ;

   long * x = ( long * ) & bar . c2 ;
   * x = 0x12345678 ; /* X is odd if compiler doesn't pad */

This WILL crash on an SE/Plus/Classic/PB100:

char foo [ 10 ] ;

   long * x = ( long * ) & foo [ 1 ] ;
   * x = 0x12345678 ;

*end*

10.5) Q: Why does my application work on a IIci but not on a
Quadra?

A: Two reasons:

1) The Quadras 900 and 950 have special processors that handle the serial
ports; if you write directly to the serial chips, you will crash (this
goes for the IIfx as well)

2) The Quadras have 68040 processors, as have the Centrises.  These
processors have separate instruction and data caches (like the 68030) but
they are larger (4K each) and unlike the 68030 which is write-through
data cached, the 68040 is copy-back data cached.  This means that changes
you make to "your code" aren't really changed all the time, since the
changes may still be in the data cache and not written to memory when the
CPU reads that part of memory into its I-cache.  Even worse; that part
might already have been read into the I-cache before you change it in the
D-cache, meaning that writing out the D-cache will still not be enough.
You need to flush both the caches when writing self-modifying code.

Self-modifying code includes code that builds its own jump tables and
code that decrypts itself and code that "stubs" MDEFs or WDEFs to jump
back into the application code.

You flush the cache using FlushDataCache() which is implemented if
Gestalt says you have a 68020 or better processor (or if the _HwDispatch
trap is implemented)

10.6) Q: Why does my application work on my Quadra but not on my
accellerated SE?

A: You're probably calling Color QuickDraw without first checking if it's
available.  The following machines do not have color QuickDraw in ROM nor
RAM:

Mac Plus, Mac SE, Mac Classic, Mac Luggable, PowerBook 100, Outbound

10.7) Q: I do check for color quickdraw, but crash nevertheless.

A: _Gestalt lies under some versions of System 7; it says that non-color
machines HAVE color QuickDraw when you test using the
gestaltQuickdrawFeatures selector.

Instead, check the gestaltQuickdrawVersion selector, if it returns >=
gestalt8BitQuickdraw then you can safely use gestaltQuickdrawFeatures,
else you only have b/w QuickDraw.

10.8) Q: Why are there no C/C++ compilers that optimize for the Mc68040?

A: Beats me; optimizing for the 68040 can make programs up to 50% faster
on that chip while still losing nothing, or very little (less than 10%)
on older chips.

*11* Optional System Software
 *11.1* QuickTime

11.1.1) Q: I want to write a Amiga QuickTime player and need the
CODEC format details.

A: Although the structure of QuickTime movies is well documented in
Inside Mac: QuickTime, the inner workings of the Apple compression
modules is a trade secret that Apple will only license to you at great
cost.  Perhaps it's time for a freeware, cross-platform QuickTime codec?

*12* Third-Party Solutions

12.1) Q: What are some royalty-free databases available for the
Macintosh?

These are commercial with no run-time licenses:

Prograph CPX comes with a database that can do indexes and tables.
<[e-mail]>

C-Index Pro is an engine that comes with source, does tables and indexes
in one compound file.  <[e-mail]>

dtF is a relational database library.  <[e-mail]>

NeoAccess is an object-oriented database, where you can store objects and
retrieve by field value; it handles inheritance as well.  <comes as a
demo on the CodeWarrior CD with an unlockable archive of the real thing>

*13* Dessert

13.1) Q: Dessert?

A: Honey Hill Farms Cookie Jar Frozen Yoghurt or Haagen-Dazs Raspberry &
Cream Ice Cream.

Hokey-Pokey icecream with chocolate sauce and (for those who like their
brain food firmer) Almond and Double Chocolate CookieTime cookies!?

*14* Contributors

This is obviously an incomplete list as far as it reflects pre-10/31/94
submissions, but I will credit new additions to the best of my ability.

Denis Birnie
Scott Bronson <[e-mail]>
Tim Converse <[e-mail]>
Bruce Hoult <[e-mail]>
Matthias Neeracher
David P. Oster <[e-mail]>
Eric Slosser <[e-mail]>
Chris Thomas <[e-mail]>
Jon W..atte <[e-mail]>

--------------------comp.sys.mac.programmer.info---------------------
comp.sys.mac.programmer.info  is  primarily  for  distributing  FAQs,
tutorials, news, and  similar  documents  related to programming  the
Macintosh.  To post, email [e-mail]
-----------------------about MacTech Magazine----------------------
PO Box 250055, Los Angeles, CA 90025, 310-575-4343, Fax:[phone]
For more info, anonymous ftp to ftp.netcom.com and cd to /pub/xplain
or email to the following @xplain.com : custservice, editorial,
adsales, marketing, accounting, pressreleases, progchallenge,
publisher, info