MoreOpenAndSave

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 the ditlResID 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, and sfHookNullEvent. 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 or GetDialogItemAsControl to obtain the control handle of the check box. In this situation, you can call MOASI_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 of MOASI_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 to MOASI_EnableDisableNav. You can pass this value to MOASI_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. If MOASI_WillUseNav returns true, MOASI will attempt to use Nav during subsequent calls. If MOASI_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 of MOASI_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 supports dftb resources. This is not parallel with MOASI's Nav Services code path, since MOASI is dependent on Nav to append the items, and Nav calls AppendDITL. 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 and LMGetCurDirStore. 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.