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:

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

Compatibility