<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.0//EN" "http://www.gnustep.org/gsdoc-1_0_0.xml">
<gsdoc base="NSSavePanel" up="Gui">
  <head>
    <title>NSSavePanel</title>
    <author name="Jonathan Gapen">
      <email address="jagapen@smithlab.chem.wisc.edu">
        jagapen@smithlab.chem.wisc.edu
      </email>
    </author>
    <author name="Nicola Pero">
      <email address="n.pero@mi.flashnet.it">
        n.pero@mi.flashnet.it
      </email>
    </author>
    <author name="Mirko Viviani">
      <email address="mirko.viviani@rccr.cremona.it">
        mirko.viviani@rccr.cremona.it
      </email>
    </author>
    <abstract>Standard panel for saving files</abstract>
    <copy>1999, 2000 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>
        Software documentation for the NSSavePanel class
      </heading>
      <class name="NSSavePanel" super="NSPanel">
        <declared>AppKit/NSSavePanel.h</declared>
        <desc>
          <p>
            Implements a panel that allows the user to save
            a file.
          </p>
          <p>
            There is only one save panel per application and this
            panel is obtained by calling the
            <ref type="method" id="+savePanel">
              +savePanel
            </ref>
            class method. From here, you should set the required
            file extension using
            <ref type="method" id="-setRequiredFileType:">
              -setRequiredFileType:
            </ref>
            When ready to show the panel, use the
            <ref type="method" id="-runModal">
              -runModal
            </ref>
            , or a similar method to show the panel in a modal
            session. Other methods allow you to set the
            initial directory and initially choosen file. The
            method will return one of NSOKButton or
            NSCancelButton depending on which button the
            user pressed.
          </p>
          <p>
            Use the
            <ref type="method" id="-filename">
              -filename
            </ref>
            method to retrieve the name of the file the user
            choose.
          </p>
        </desc>
        <method type="NSSavePanel*" factory="yes">
          <sel>savePanel</sel>
          <desc>
            Returns the shared NSSavePanel instance
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSURL*">
          <sel>URL</sel>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSView*">
          <sel>accessoryView</sel>
          <desc>
            Returns the accesory view (if any).
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>beginSheetForDirectory:</sel>
          <arg type="NSString*">path</arg>
          <sel>file:</sel>
          <arg type="NSString*">filename</arg>
          <sel>modalForWindow:</sel>
          <arg type="NSWindow*">docWindow</arg>
          <sel>modalDelegate:</sel>
          <arg type="id">delegate</arg>
          <sel>didEndSelector:</sel>
          <arg type="SEL">didEndSelector</arg>
          <sel>contextInfo:</sel>
          <arg type="void*">contextInfo</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>cancel:</sel>
          <arg type="id">sender</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSString*">
          <sel>directory</sel>
          <desc>
            Returns the directory choosen by the user. Do not
            invoke directory within a modal loop because the
            information that these methods fetch is updated
            only upon return.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSString*">
          <sel>filename</sel>
          <desc>
            Returns the absolute filename choosen by the user.
            Do not invoke filename within a modal loop because the
            information that these methods fetch is updated
            only upon return.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="BOOL">
          <sel>isExpanded</sel>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="BOOL">
          <sel>isExtensionHidden</sel>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>ok:</sel>
          <arg type="id">sender</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSString*">
          <sel>prompt</sel>
          <desc>
            Returns the prompt used in the current path field.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSString*">
          <sel>requiredFileType</sel>
          <desc>
            Returns the required file type. The default is no
            required file type.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>runModal</sel>
          <desc>
            Shows the save panel for the user. This method
            invokes
            <ref type="method" id="-runModalForDirectory:file:">
              -runModalForDirectory:file:
            </ref>
            with empty strings for the filename. Returns
            NSOKButton (if the user clicks the OK button) or
            NSCancelButton (if the user clicks the
            Cancel button).
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>runModalForDirectory:</sel>
          <arg type="NSString*">path</arg>
          <sel>file:</sel>
          <arg type="NSString*">filename</arg>
          <desc>
            Initializes the panel to the directory
            specified by <var>path</var> and, optionally, the
            file specified by <var>filename</var>, then displays
            it and begins its modal event loop; <var>path</var> and
            <var>filename</var> can be empty strings. The method
            invokes [NSApplication:-runModalForWindow:] method
            with self as the argument. Returns NSOKButton (if the
            user clicks the OK button) or NSCancelButton (if the
            user clicks the Cancel button). If <var>path</var> is
            <code>nil</code> then the panel displays the last
            selected directory or as a last resort, the
            current working directory.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>runModalForDirectory:</sel>
          <arg type="NSString*">path</arg>
          <sel>file:</sel>
          <arg type="NSString*">filename</arg>
          <sel>relativeToWindow:</sel>
          <arg type="NSWindow*">window</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>selectText:</sel>
          <arg type="id">sender</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setAccessoryView:</sel>
          <arg type="NSView*">aView</arg>
          <desc>
            Sets an accessory view which is shown near the bottom
            of the panel. The panel is automatically expanded with
            enough room to show the extra view. You can use this
            extra view to customize various characteristics of
            the file selection mechanism. For instance you could
            add a popup button which allows the user to select the
            format that the file is saved in (e.g. rtf or txt).
            See also
            <ref type="method" id="-validateVisibleColumns">
              -validateVisibleColumns
            </ref>
            .
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setCanSelectHiddenExtension:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setDirectory:</sel>
          <arg type="NSString*">path</arg>
          <desc>
            Sets the current <var>path</var> name in the Save
            panel's browser. The <var>path</var> argument must
            be an absolute <var>path</var> name.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setExtensionHidden:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setPrompt:</sel>
          <arg type="NSString*">prompt</arg>
          <desc>
            Returns the <var>prompt</var> of the Save panel
            field that holds the current pathname or file name.
            By default this <var>prompt</var> is 'Name: '.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setRequiredFileType:</sel>
          <arg type="NSString*">fileType</arg>
          <desc>
            Specifies the type, a file name extension to be
            appended to any selected files that don't already
            have that extension; The argument type should not
            include the period that begins the extension.
            Invoke this method each time the Save panel is used
            for another file type within the application.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setTitle:</sel>
          <arg type="NSString*">title</arg>
          <desc>
            Sets the <var>title</var> of the NSSavePanel to
            <var>title</var>. By default, 'Save' is the
            <var>title</var> string. If you adapt the NSSavePanel
            for other uses, its <var>title</var> should reflect the
            user action that brings it to the screen.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setTreatsFilePackagesAsDirectories:</sel>
          <arg type="BOOL">flag</arg>
          <desc>
            Sets the NSSavePanel's behavior for displaying file
            packages (for example, MyApp.app) to the user. If
            <var>flag</var> is <code>YES</code>, the user is
            shown files and subdirectories within a file package.
            If <code>NO</code>, the NSSavePanel shows each file
            package as a file, thereby giving no indication
            that it is a directory.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSString*">
          <sel>title</sel>
          <desc>
            Returns the title of the save panel
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="BOOL">
          <sel>treatsFilePackagesAsDirectories</sel>
          <desc>
            Returns <code>YES</code> if file packages are shown
            as directories. The default is <code>NO</code>.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>validateVisibleColumns</sel>
          <desc>
            Validates and possibly reloads the browser
            columns that are visible in the Save panel by
            causing the delegate method
            <ref type="method" id="-panel:shouldShowFilename:">
              -panel:shouldShowFilename:
            </ref>
            to be invoked. One situation in which this method would
            find use is whey you want the browser to show only
            files with certain extensions based on the selection
            made in an accessory-view pop-up list. When the user
            changes the selection, you would invoke this method
            to revalidate the visible columns.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <standards>
          <MacOS-X /> <OpenStep /> <GNUstep />
        </standards>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the
        NSObject(NSSavePanelDelegate)
        informal protocol
      </heading>
      <category name="NSSavePanelDelegate" class="NSObject">
        <declared>AppKit/NSSavePanel.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="NSComparisonResult">
          <sel>panel:</sel>
          <arg type="id">sender</arg>
          <sel>compareFilename:</sel>
          <arg type="NSString*">filename1</arg>
          <sel>with:</sel>
          <arg type="NSString*">filename2</arg>
          <sel>caseSensitive:</sel>
          <arg type="BOOL">caseSensitive</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="BOOL">
          <sel>panel:</sel>
          <arg type="id">sender</arg>
          <sel>isValidFilename:</sel>
          <arg type="NSString*">filename</arg>
          <desc>
            The NSSavePanel sends this message just before the end
            of a modal session for each file name displayed or
            selected (including file names in multiple
            selections). The delegate determines whether
            it wants the file identified by <var>filename</var>; it
            returns <code>YES</code> if the file name is valid,
            or <code>NO</code> if the NSSavePanel should stay in its
            modal loop and wait for the user to type in or select
            a different file name or names. If the delegate refuses a
            file name in a multiple selection, none of the file
            names in the selection are accepted.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="BOOL">
          <sel>panel:</sel>
          <arg type="id">sender</arg>
          <sel>shouldShowFilename:</sel>
          <arg type="NSString*">filename</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSString*">
          <sel>panel:</sel>
          <arg type="id">sender</arg>
          <sel>userEnteredFilename:</sel>
          <arg type="NSString*">fileName</arg>
          <sel>confirmed:</sel>
          <arg type="BOOL">okFlag</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <standards>
          <MacOS-X /> <OpenStep /> <GNUstep />
        </standards>
      </category>
    </chapter>
  </body>
</gsdoc>
