Introduction
This module (MOASI -- the I is historical but not silent) implements functions very similar to those of Standard File. MOASI's user experience, however, is not necessarily that of Standard File.
Vectored User Experience
If Navigation Services is available, MOASI presents that user exeprience to the user. If Navigation Services is not available, MOASI falls back to Standard File. If Navigation Services fails for whatever reason, MOASI will call Standard File as a fall-back. Your code doesn't need to know about any of this decision logic.
Familiar Function Interface
We've gone to considerable lengths to make transitioning from Standard File to Navigation Services (and Carbon) as painless as possible. MOASI supports not only the regular Standard File calls but also the Translation Manager and QuickTime variants. We've even managed to figure out how to support customization, though this is the area in which your code will need to change most.
Programmer Requirements
Before attempting to use MOASI, you should be reasonably familiar with Standard File, which is documented in chapter 3 of Inside Macintosh: Files. Knowledge of Navigation Services is not necessary but would be helpful in understanding some of the limitations imposed by MOASI as compared to direct use of Standard File or Navigation Services.
System Requirements
Navigation Services 1.1 or later must be available for MOASI to present the Navigation Services user experience. (Navigation Services 1.1 or later is present in Mac OS 8.5 and later.) If Navigation Services is not present or a version less than 1.1 is present, MOASI will present the Standard File user experience.
Target Audiences
MOASI has two target audiences:
- Developers who need to get their existing applications up and running quickly with Navigation Services, either because of Carbon or because of market pressure.
- Just about everybody who uses Navigation Services is likely to benefit from reading the MOASI code. It uses a large subset of the Navigation Services API and translates everything it does into familiar terms, namely those of Standard File.
We don't recommend MOASI as an everlasting alternative to adopting Navigation Services. MOASI does not and cannot expose the full flexibility of Navigation Services, and you should be planning to adopt Nav directly over the medium or long term.
Using MOASI
MOASI operates in a way very similar to that of Standard File. This section discusses only how MOASI differs from Standard File.
Customization
There are some significant differences in the area of customization. Because MOASI is a super-sub-set of Navigation Services and Standard File, it was necessary to enforce some limitations on the ability to customize the dialogs.
Adding Items to the Dialog
In some of the function prototypes, you'll see a
ditlResID
parameter. This parameter is the only way to customize MOASI dialogs. The 'DITL' resource whose ID corresponds to this parameter is appended to the dialog just before the dialog hook is called for the first time. If you do not wish to append any items to the dialog, pass 0 for theditlResID
parameter (or use one of the functions which does not have this parameter).The Dialog Hook
The dialog hook is called only for items which were added to the dialog, as well as some of the meta-items.
At this writing, only three meta-items were supported:
sfHookFirstCall
,sfHookLastCall
, andsfHookNullEvent
. Other meta-items may be passed to the hook by future versions of MOASI.The value the hook returns is ignored.
The Modal Filter
If a
mouseDown
event occurs in an item which was added to the dialog, it is tracked (either by MOASI or Nav Services). Regardless of whether the user releases the mouse button within the item, the modal filter is then called.Null events are always passed to the filter.
Any changes a filter makes to its parameters are ignored. The filter's return value is also ignored.
Item Index Numbers for Custom Items
As far as your code is concerned, items added to the dialog have the same index numbers as the items in the dialog item list corresponding to the
ditlResID
parameter. In your hook and filter, the first custom item is reported as index 1, the second is index 2, and so on.Getting the "Real" Item Index Number for the First Custom Item
As discussed above, the dialog hook and modal filter are passed item indexes which correspond to the items in the dialog item list which was added to the dialog. Sometimes, however, you will need to pass a dialog item index to the Dialog Manager. For example, if you need to set the value of a check box, you'll need to call
GetDialogItem
orGetDialogItemAsControl
to obtain the control handle of the check box. In this situation, you can callMOASI_GetFirstCustomItemIndex
and add the result to the item index you wish pass to the Dialog Manager. So, to get the "real" item index for the second custom item, you would add 2 to the return value ofMOASI_GetFirstCustomItemIndex
.Turning off Navigation Services
For testing purposes, you may wish to prevent MOASI from using Navigation Services. In this case, MOASI will always use Standard File. This option is not available under Carbon.
To turn off Navigation Services, call
MOASI_EnableDisableNav
. It will return a value indicating whether Navigation Services support was enabled or disabled before the call toMOASI_EnableDisableNav
. You can pass this value toMOASI_EnableDisableNav
when you wish to restore the previous setting.Determining Whether Navigation Services Will Be Used
Navigation Services may or may not be available, or, if it is, its version may be less than 1.1. Also, Navigation Services may or may not be enabled according to MOASI.
To determine whether a call to MOASI will result in the use of Navigation Services, call
MOASI_WillUseNav
. IfMOASI_WillUseNav
returns true, MOASI will attempt to use Nav during subsequent calls. IfMOASI_WillUseNav
returns false, MOASI will use Standard File during subsequent calls.MOASI_WillUseNav
always returns true under Carbon.Note that the return value of
MOASI_WillUseNav
does not have the same meaning as the return value ofMOASI_EnableDisableNav
.Important Future Directions
Features
- You should be able to pass a NIL reply to the various Get functions. This would result in the reply being withheld from the caller and an appropriate "open documents" Apple event being sent to the current process. This would be a way to support multiple selection in the Nav dialogs.
- At the moment, MOASI's Standard File code uses
AppendDialogItemList
, which supportsdftb
resources. This is not parallel with MOASI's Nav Services code path, since MOASI is dependent on Nav to append the items, and Nav callsAppendDITL
. We should remedy this somehow.Compatibility
- To be properly parallel with Standard File, Nav's filtering popup should be disabled, and the MOASI file filter shim should examine the type list passed in at the MOASI level instead building a
NavTypeList
.
- MOASI should support more dialog hook meta-items. This is likely to require new entry points at the MOASI level which second-guess the dialog hook in the Standard File case and call
NavCustomControl
in the Nav case.
- We need to investigate how Standard File supports stationery more closely and make the Nav case do the same thing.
- We need to verify that the Nav and Standard File cases are doing the same thing with respect to invisible files and volumes.
- We need to decide what to do about
LMGetSFSaveDisk
andLMGetCurDirStore
. At the moment, Nav does not honor these, but MOASI might need to force the issue. Factoid: it turns out Nav honors the Documents folder setting in the General Controls control panel, but not the other two settings.