MIB-Documentation/MoreDocumentation/MoreOpenAndSave.html

<HTML>
<HEAD>
   <TITLE>MoreOpenAndSave</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H1><!--Copyright (c) Apple Computer, Inc., 1998-1999-->MoreOpenAndSave</H1>
 
<BLOCKQUOTE><H2>Introduction</H2>
   
   <P>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.</P>
   
   <BLOCKQUOTE><H3>Vectored User Experience</H3>
      
      <P>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.</P>
      
      <H3>Familiar Function Interface</H3>
      
      <P>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.</P>
      
      <H3>Programmer Requirements</H3>
      
      <P>Before attempting to use MOASI, you should be reasonably
      familiar with <A HREF="http://developer.apple.com/techpubs/mac/Files/Files-302.html" TARGET="_TOP">Standard
      File</A>, which is documented in chapter 3 of <I>Inside
      Macintosh: Files</I>. Knowledge of <A HREF="http://developer.apple.com/techpubs/macosx/Carbon/Files/NavigationServices/Navigation_Services/index.html">Navigation
      Services</A> 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.</P>
      
      <H3>System Requirements</H3>
      
      <P>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.</P>
      
      <H3>Target Audiences</H3>
      
      <P>MOASI has two target audiences:</P>
      
      <UL>
         <LI>Developers who need to get their existing applications
         up and running quickly with Navigation Services, either
         because of Carbon or because of market pressure.<BR>
         <BR>
         </LI>
         
         <LI>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.</LI>
      </UL>
      
      <P>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.</P></BLOCKQUOTE>
   
   <H2>Using MOASI</H2>
   
   <P>MOASI operates in a way very similar to that of Standard File.
   This section discusses only how MOASI differs from Standard
   File.</P>
   
   <BLOCKQUOTE><H3>Customization</H3>
      
      <P>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.</P>
      
      <BLOCKQUOTE><H4>Adding Items to the Dialog</H4>
         
         <P>In some of the function prototypes, you'll see a
         <CODE>ditlResID</CODE> 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 <CODE>ditlResID</CODE> parameter (or use one of the
         functions which does not have this parameter).</P>
         
         <H4>The Dialog Hook</H4>
         
         <P>The dialog hook is called only for items which were added
         to the dialog, as well as some of the meta-items.</P>
         
         <P>At this writing, only three meta-items were supported:
         <CODE>sfHookFirstCall</CODE>, <CODE>sfHookLastCall</CODE>,
         and <CODE>sfHookNullEvent</CODE>. Other meta-items may be
         passed to the hook by future versions of MOASI.</P>
         
         <P>The value the hook returns is ignored.</P>
         
         <H4>The Modal Filter</H4>
         
         <P>If a <CODE>mouseDown</CODE> 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.</P>
         
         <P>Null events are always passed to the filter.</P>
         
         <P>Any changes a filter makes to its parameters are ignored.
         The filter's return value is also ignored.</P>
         
         <H4>Item Index Numbers for Custom Items</H4>
         
         <P>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 <CODE>ditlResID</CODE>
         parameter. In your hook and filter, the first custom item is
         reported as index 1, the second is index 2, and so on.</P>
         
         <H4>Getting the "Real" Item Index Number for the First
         Custom Item</H4>
         
         <P>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 <CODE>GetDialogItem</CODE>
         or <CODE>GetDialogItemAsControl</CODE> to obtain the control
         handle of the check box. In this situation, you can call
         <CODE>MOASI_GetFirstCustomItemIndex</CODE> 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
         <CODE>MOASI_GetFirstCustomItemIndex</CODE>.</P></BLOCKQUOTE>
      
      <H3>Turning off Navigation Services</H3>
      
      <P>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.</P>
      
      <P>To turn off Navigation Services, call
      <CODE>MOASI_EnableDisableNav</CODE>. It will return a value
      indicating whether Navigation Services support was enabled or
      disabled before the call to
      <CODE>MOASI_EnableDisableNav</CODE>. You can pass this value to
      <CODE>MOASI_EnableDisableNav</CODE> when you wish to restore
      the previous setting.</P>
      
      <H3>Determining Whether Navigation Services Will Be Used</H3>
      
      <P>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.</P>
      
      <P>To determine whether a call to MOASI will result in the use
      of Navigation Services, call <CODE>MOASI_WillUseNav</CODE>. If
      <CODE>MOASI_WillUseNav</CODE> returns <B>true</B>, MOASI will
      attempt to use Nav during subsequent calls. If
      <CODE>MOASI_WillUseNav</CODE> returns <B>false</B>, MOASI will
      use Standard File during subsequent calls.
      <CODE>MOASI_WillUseNav</CODE> always returns <B>true</B> under
      Carbon.</P>
      
      <P>Note that the return value of <CODE>MOASI_WillUseNav</CODE>
      does not have the same meaning as the return value of
      <CODE>MOASI_EnableDisableNav</CODE>.</P></BLOCKQUOTE>
   
   <H2>Important Future Directions</H2>
   
   <BLOCKQUOTE><H3>Features</H3>
      
      <UL>
         <LI>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.<BR>
         <BR>
         </LI>
         
         <LI>At the moment, MOASI's Standard File code uses
         <CODE>AppendDialogItemList</CODE>, which supports
         <CODE>dftb</CODE> 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
         <CODE>AppendDITL</CODE>. We should remedy this somehow.</LI>
      </UL>
      
      <H3>Compatibility</H3>
      
      <UL>
         <LI>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 <CODE>NavTypeList</CODE>.<BR>
         <BR>
         </LI>
         
         <LI>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 <CODE>NavCustomControl</CODE> in the Nav case.<BR>
         <BR>
         </LI>
         
         <LI>We need to investigate how Standard File supports
         stationery more closely and make the Nav case do the same
         thing.<BR>
         <BR>
         </LI>
         
         <LI>We need to verify that the Nav and Standard File cases
         are doing the same thing with respect to invisible files and
         volumes.<BR>
         <BR>
         </LI>
         
         <LI>We need to decide what to do about
         <CODE>LMGetSFSaveDisk</CODE> and
         <CODE>LMGetCurDirStore</CODE>. 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.</LI>
      </UL>
   </BLOCKQUOTE></BLOCKQUOTE>
</BODY>
</HTML>


Copyright © 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-10-27