Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSSavePanel


Inherits from:
NSPanel : NSWindow : NSResponder : NSObject
Package:
com.apple.yellow.application

Class at a Glance


An NSSavePanel object manages a panel that allows users to specify the directory and name under which a file is saved. It supports browsing of the file system and it accommodates custom accessory views. An NSSavePanel is a recycled object: when you request a Save panel, NSSavePanel tries to reuse an existing Save panel rather than create a new one.

Principal Attributes


Creation



savePanel Returns the shared save panel instance.

Commonly Used Methods



runModal Displays the panel and begins the event loop.
filename Returns the selected or entered file name.
directory Returns the full path of the selected file.
ok Invoked when users click OK.


Class Description


NSSavePanel creates and manages a Save panel, and allows you to run the panel in a modal loop. The Save panel provides a simple way for a user to specify a file to use when saving a document or other data. It can restrict the user to files of a certain type, as specified by a file name extension.

When the user decides on a file name, the message panelIsValidFilename is sent to the NSSavePanel's delegate. If it responds to that message, the delegate can determine whether the specified file name can be used; it returns true if the file name is valid, or false if the Save panel should stay up and wait for the user to type in a different file name.

Typically, you access an NSSavePanel by invoking the savePanel method. When the class receives a savePanel message, it tries to reuse an existing panel rather than create a new one. When a panel is reused its attributes are reset to the default values so the effect is the same as receiving a new panel. Because a Save panel may be reused, you shouldn't modify the instance returned by savePanel except through the methods listed below. For example, you can set the panel's title and required file type, but not the arrangement of the buttons within the panel.

A typical programmatic use of NSSavePanel requires you to:




Method Types


Constructors
NSSavePanel
Creating an NSSavePanel
savePanel
Customizing the NSSavePanel
setAccessoryView
accessoryView
setTitle
title
setPrompt
prompt
Setting directory and file type
setDirectory
setRequiredFileType
requiredFileType
treatsFilePackagesAsDirectories
setTreatsFilePackagesAsDirectories:
validateVisibleColumns
Running the NSSavePanel
runModal
runModalInDirectory
Getting user selections
directory
filename
Action methods
cancel
ok
Responding to user input
selectText
Setting the delegate
setDelegate


Constructors



NSSavePanel

public NSSavePanel()

Description forthcoming.

public NSSavePanel( NSRect aRect, int anInt, int anInt, boolean flag)

Description forthcoming.

public NSSavePanel( NSRect aRect, int anInt, int anInt, boolean aBoolean, NSScreen aScreen)

Description forthcoming.


Static Methods



savePanel

public static NSSavePanel savePanel()

Returns an instance of NSSavePanel, creating one if necessary. Otherwise, the instance is a recycled NSSavePanel object. The method sets the attributes of the instance to the default values:


Instance Methods



accessoryView

public NSView accessoryView()

Returns the custom accessory view for the current application. This view is set by setAccessoryView.

See Also: setAccessoryView



cancel

public void cancel(Object sender)

Invoked when the user clicks the panel's Cancel button.

directory

public String directory()

Returns the absolute pathname of the directory currently shown in the panel. Do not invoke this method within a modal session ( runModal or runModalInDirectory) because the directory information is only updated just before the modal session ends.

See Also: setDirectory



filename

public String filename()

Returns the absolute path name of the file currently shown in the panel. Do not invoke this method within a modal session ( runModal or runModalInDirectory) because the filename information is only updated just before the modal session ends.

ok

public void ok(Object sender)

Invoked when the user clicks the panel's OK button.

prompt

public String prompt()

Returns the prompt of the Save panel field that holds the current pathname or file name. By default this prompt is "Name:".

See Also: setPrompt



requiredFileType

public String requiredFileType()

Returns the required file type (if any). A file specified in the Save panel is saved with the designated file name and this file type as an extension. Examples of common file types are "rtf", "tiff", and "ps". An empty String return value indicates that the user can save to any ASCII file.

See Also: setRequiredFileType



runModal

public int runModal()

Displays the panel and begins its event loop with the current working (or last selected) directory as the default starting point. Invokes runModalInDirectory (file argument is an empty String), which in turn performs NSApplication's runModalForWindow method with this as the argument. Returns OKButton (if the user clicks the OK button) or CancelButton (if the user clicks the Cancel button). Do not invoke filename or directory within a modal loop because the information these methods fetch is updated only upon return.

See Also: runModalInDirectory, runModalForWindow (NSApplication)



runModalInDirectory

public int runModalInDirectory( String path, String filename)

Initializes the panel to the directory specified by path and, optionally, the file specified by filename, then displays it and begins its modal event loop; path and filename can be empty strings, but cannot be null. The method invokes NSApplication's runModalForWindow method with this as the argument. Returns OKButton (if the user clicks the OK button) or CancelButton (if the user clicks the Cancel button). Do not invoke filename or directory within a modal loop because the information these methods fetch is updated only upon return.

See Also: runModal, runModalForWindow (NSApplication)



selectText

public void selectText(Object sender)

Advances the current browser selection one line when Tab or the up-arrow key is pressed, and goes back one line when Shift-Tab or the down-arrow key is pressed; after it makes the new selection it writes the selected item in the field after the prompt. The argument sender identifies the object invoking this method. This method is primarily of interest to those who want to override it to get different behavior.

setAccessoryView

public void setAccessoryView(NSView aView)

Customizes the panel for the application by adding a custom NSView (aView) to the panel. The custom NSView that's added appears just above the OK and Cancel buttons at the bottom of the panel. The NSSavePanel automatically resizes itself to accommodate aView. You can invoke this method repeatedly to change the accessory view as needed. If aView is null, the NSSavePanel removes the current accessory view.

See Also: accessoryView



setDelegate

public void setDelegate(Object anObject)

Makes anObject the NSSavePanel's delegate, after verifying which delegate methods are implemented. Use NSWindow's delegate method to retrieve the NSSavePanel's delegate.

setDirectory

public void setDirectory(String path)

Sets the current path name in the Save panel's browser. The path argument must be an absolute path name.

See Also: directory



setPrompt

public void setPrompt(String prompt)

Sets the prompt of the field that holds the current pathname or file name. This prompt appears on all NSSavePanels (or all NSOpenPanels if the receiver of this message is an NSOpenPanel) in your application. "Name:" is the default prompt string.

See Also: prompt



setRequiredFileType

public void setRequiredFileType(String type)

Specifies the type, a file name extension to be appended to any selected files that don't already have that extension; "nib" and "rtf" are examples. The argument type should not include the period that begins the extension. You need to invoke this method each time the Save panel is used for another file type within the application.

See Also: requiredFileType



setTitle

public void setTitle(String title)

Sets the title of the NSSavePanel to title. By default, "Save" is the title string. If you adapt the NSSavePanel for other uses, its title should reflect the user action that brings it to the screen.

See Also: title



setTreatsFilePackagesAsDirectories:

public void setTreatsFilePackagesAsDirectories(boolean flag)

Sets the NSSavePanel's behavior for displaying file packages (for example, MyApp.app) to the user. If flag is true, the user is shown files and subdirectories within a file package. If false, the NSSavePanel shows each file package as a file, thereby giving no indication that it is a directory.

See Also: treatsFilePackagesAsDirectories



title

public String title()

Returns the title of the NSSavePanel.

See Also: setTitle



treatsFilePackagesAsDirectories

public boolean treatsFilePackagesAsDirectories()

Returns whether the Save panel displays file packages to the user as directories.

See Also: setTreatsFilePackagesAsDirectories:



validateVisibleColumns

public void validateVisibleColumns()

Validates and possibly reloads the browser columns visible in the Save panel by invoking the delegate method panelShouldShowFilename. You might use this method if you want the browser 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.

URL

public java.net.URL URL()

Description forthcoming.


Methods Implemented By the Delegate


panelCompareFilenames

public abstract int panelCompareFilenames( Object sender, String fileName1, String fileName2, boolean flag)

Controls the ordering of files presented by the NSSavePanel. This method should return:

The flag argument, if true, indicates that the ordering is to be case-sensitive.

Don't reorder file names in the Save panel without good reason, because it may confuse the user to have files in one Save panel or Open panel ordered differently than those in other such panels or in the Workspace Manager. The default behavior of Save and Open panel is to order files as they appear in the Workspace Manager file viewer. Note also that by implementing this method you will reduce the operating performance of the panel.



panelIsValidFilename

public abstract boolean panelIsValidFilename( Object sender, String filename)

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 filename; it returns true if the file name is valid, or false 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.

panelShouldShowFilename

public abstract boolean panelShouldShowFilename( Object sender, String filename)

Gives the delegate the opportunity to filter out items that it doesn't want the user to see or choose. The NSSavePanel sends this message to the panel's delegate for each file or directory (filename) it is about to load in the browser. The delegate returns true if filename should be displayed, and false if the NSSavePanel should ignore the file or directory.


Table of Contents