ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSSavePanel

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guides

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 a Save panel instance.

Commonly Used Methods

runModal

Displays the panel and begins the event loop.

filename

Returns the selected or entered filename.

directory

Returns the full path of the selected file.

ok

Invoked when users click OK.

Overview

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 an extension.

Tasks

Constructors

Obtaining

Customizing the NSSavePanel

Working with Extension Hiding

Setting Directory and File Type

Running the NSSavePanel

Getting User Selections

Action Methods

Responding to User Input

Setting the Delegate

Working with filenames

Expanding the panel

Managing panel changes

Constructors

NSSavePanel

Creates an empty NSSavePanel.

public NSSavePanel()

Creates a new NSSavePanel.

public NSSavePanel(NSRect contentRect, int styleMask, int backingType, boolean flag)

Discussion

The contentRect argument specifies the location and size of the panel’s content area in screen coordinates. Note that the window server limits window position coordinates to ±16,000 and sizes to 10,000.

The styleMask argument specifies the panel’s style. Either it can be NSWindow.BorderlessWindowMask, or it can contain any of the options described in NSWindow’s “Constants,” combined using the C bitwise OR operator.

Borderless windows display none of the usual peripheral elements and are generally useful only for display or caching purposes; you should normally not need to create them. Also, note that an NSWindow’s style mask should include NSWindow.TitledWindowMask if it includes any of the others.

The backingType argument specifies how the drawing done in the panel is buffered by the object’s window device, and possible values are described in NSWindow’s “Constants.”

The flag argument determines whether the window server creates a window device for the new panel immediately. If flag is true, it defers creating the window until the panel is moved onscreen. All display messages sent are postponed until the panel is created, just before it’s moved onscreen. Deferring the creation of the window improves launch time and minimizes the virtual memory load on the window server.

The new panel creates an instance of NSView to be its default content view. You can replace it with your own object by using the setContentView method.

Creates a new NSSavePanel.

public NSSavePanel(NSRect contentRect, int styleMask, int backingType, boolean flag, NSScreen aScreen)

Discussion

This constructor is equivalent to the preceding one except contentRect is specified relative to the lower-left corner of aScreen.

If aScreen is null, contentRect is interpreted relative to the lower-left corner of the main screen. The main screen is the one that contains the current key window or, if there is no key window, the one that contains the main menu. If there’s neither a key window nor a main menu (if there’s no active application), the main screen is the one where the origin of the screen coordinate system is located.

Static Methods

savePanel

Creates and returns a new NSSavePanel object.

public static NSSavePanel savePanel()

Discussion

The save panel has been initialized with default values.

Instance Methods

accessoryView

Returns the custom accessory view for the current application.

public NSView accessoryView()

Discussion

This view is set by setAccessoryView.

In order to free up unused memory after closing the receiver, the accessory view is released after the panel is closed. If you rely on the receiver to hold onto the accessory view until the next time you use it, the accessory view may be deallocated unexpectedly. If you retain the accessory view in your own code, though, this deallocation should not be a problem.

See Also

allowedFileTypes

Returns an array of the allowed file types.

public NSArray allowedFileTypes()

Discussion

If the user specifies a file whose type is in the array of allowed types, they will not be presented with another dialog (see allowsOtherFileTypes for details about this dialog) when trying to save. Examples of common file types are “rtf”, “tiff”, and “ps”. File type strings encoding HFS file types are not valid values for this attribute. A null return value, which is the default, indicates that the user can save to any ASCII file.

Availability
See Also

allowsOtherFileTypes

Returns whether the receiver allows the user to save files with an extension that’s not in the list of allowed types.

public boolean allowsOtherFileTypes()

Discussion

If the user tries to save a filename with a recognized extension that's not in the list of allowed types they are presented with a dialog. If this method returns true, then the dialog presents the option of using the extension the user specified.

The default setting is false.

Availability
See Also

beginSheetForDirectory

Presents a Save panel as a sheet with the directory specified by path and optionally, the file specified by name selected.

public void beginSheetForDirectory(String path, String name, NSWindow docWindow, Object modalDelegate, NSSelector didEndSelector, Object contextInfo)

Discussion

If docWindow is not null, the Save panel slides down as a sheet running as a document modal window. If docWindow is null, the behavior defaults to a standalone modal window.

The didEndSelector method is optional. If implemented by the modalDelegate, this method is invoked, passing contextInfo as an argument, after the modal session has ended, but before dismissing the Save panel. didEndSelector may dismiss the Save panel itself; otherwise it will be dismissed on return from the method. modalDelegate is not the same as a delegate assigned to the panel. Modal delegates in sheets are temporary and the relationship only lasts until the sheet is dismissed. The NSSavePanel object does not retain the modal delegate.

didEndSelector should have the following signature:

public void savePanelDidEndReturnCode (NSSavePanel sheet, int returnCode,  Object  contextInfo)

The value passed as returnCode will be either NSPanel.CancelButton or NSPanel.OKButton.

Save as above, without the optional contextInfo.

public void beginSheetForDirectory(String path, String name, NSWindow docWindow, Object modalDelegate, NSSelector didEndSelector)

cancel

This action method is invoked when the user clicks the panel’s Cancel button.

public void cancel(Object sender)

See Also

canCreateDirectories

Returns whether the receiver allows the user to create directories.

public boolean canCreateDirectories()

Availability
See Also

canSelectHiddenExtension

Returns whether the receiver allows the user to hide or show extensions.

public boolean canSelectHiddenExtension()

Availability
See Also

delegate

Returns the receiver’s delegate.

public Object delegate()

Availability
See Also

directory

Returns the absolute pathname of the directory currently shown in the receiver.

public String directory()

See Also

filename

Returns the absolute pathname of the file currently shown in the receiver.

public String filename()

See Also

isExpanded

Returns whether the receiver is expanded.

public boolean isExpanded()

isExtensionHidden

Returns true if the extension-hiding checkbox is visible and checked.

public boolean isExtensionHidden()

Discussion

Returns false otherwise.

See Also

message

Returns the message displayed in the save panel.

public String message()

Discussion

This message appears on all NSSavePanels (or all NSOpenPanels if the receiver of this message is an NSOpenPanel) in your application. The default message text is an empty string.

Availability
See Also

nameFieldLabel

Returns the string displayed in front of the filename text field.

public String nameFieldLabel()

Discussion

By default the label is “Save As:”.

Availability
See Also

ok

This action method is invoked when the user clicks the panel’s OK button.

public void ok(Object sender)

See Also

prompt

Returns the prompt of the default button.

public String prompt()

Discussion

This prompt appears on all NSSavePanels (or all NSOpenPanels if the receiver of this message is an NSOpenPanel) in your application. By default the text in the default button is “Open” for an open panel and “Save” for a Save panel.

See Also

requiredFileType

Returns the required file type (if any).

public String requiredFileType()

Discussion

A file specified in the Save panel is saved with the designated filename and this file type as an extension. Examples of common file types are “rtf”, “tiff”, and “ps”. File type strings encoding HFS file types are not valid values for this attribute. An null return value indicates that the user can save to any ASCII file.

This method is equivalent to calling allowedFileTypes and returning the first element of the list of allowed types, or null if there are none.

See Also

runModal

Displays the receiver and begins its event loop with the current working (or last selected) directory as the default starting point.

public int runModal()

Discussion

Invokes runModalInDirectory (file argument is an empty String), which in turn performs NSApplication’s runModalForWindow method with this as the argument. Returns NSPanel.OKButton (if the user clicks the OK button) or NSPanel.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

Initializes the receiver 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.

public int runModalInDirectory(String path, String filename)

Discussion

If path is null, the previous directory the Save panel was in is used. This method invokes NSApplication’s runModalForWindow method with this as the argument. Returns NSPanel.OKButton (if the user clicks the OK button) or NSPanel.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.

If window is not null, the Save panel slides down as a sheet running as a document modal window. If window is null, the behavior defaults to a standalone modal panel.

public int runModalInDirectory(String path, String filename, NSWindow window)

Availability
See Also

selectText

This method has been deprecated.

public void selectText(Object sender)

Availability

setAccessoryView

Customizes the panel for the application by adding a custom NSView (aView) to the panel.

public void setAccessoryView(NSView aView)

Discussion

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

setAllowedFileTypes

Specifies the allowed file types for the receiver.

public void setAllowedFileTypes(NSArray types)

Discussion

types may not be empty. A file type is an extension to be appended to any selected files that don’t already have that extension; “nib” and “rtf” are examples. The items in types should not include the period that begins the extension. File type strings encoding HFS file types are not valid values. Pass null, to allow any file type, which is the default.

Availability
See Also

setAllowsOtherFileTypes

Sets whether the receiver allows the user to save files with an extension that’s not in the list of allowed types.

public void setAllowsOtherFileTypes(boolean flag)

Discussion

If the user tries to save a filename with a recognized extension that's not in the list of allowed types they are presented with a dialog. If allowsOtherFileTypes is true, then the dialog presents the option of using the extension the user specified.

The default setting is false.

Availability
See Also

setCanCreateDirectories

Sets whether the receiver allows the user to create directories.

public void setCanCreateDirectories(boolean)

Availability
See Also

setCanSelectHiddenExtension

Sets whether the receiver allows the user to hide or show extensions to flag.

public void setCanSelectHiddenExtension(boolean flag)

Discussion

This method must be called before the panel is displayed.

See Also

setDelegate

Makes anObject the receiver’s delegate, after verifying which delegate methods are implemented.

public void setDelegate(Object anObject)

Discussion

Use NSWindow’s delegate method to retrieve the NSSavePanel’s delegate.

setDirectory

Sets the current pathname in the receiver’s browser.

public void setDirectory(String path)

Discussion

The path argument must be an absolute pathname.

See Also

setExtensionHidden

Sets the value of the extension-hiding checkbox to flag.

public void setExtensionHidden(boolean flag)

Discussion

This method should rarely be used since the state is saved on a per application basis. Use this method to set whether a file’s extension should be indicated as being shown.

See Also

setMessage

Sets the message text displayed in the panel.

public void setMessage(String message)

Discussion

This message appears on all NSSavePanels (or all NSOpenPanels if the receiver of this message is an NSOpenPanel) in your application. The default message text is an empty string.

Availability
See Also

setNameFieldLabel

Sets the text displayed in front of the text field to label.

public void setNameFieldLabel(String label)

Discussion

By default the label is “Save As:”.

Availability
See Also

setPrompt

Sets the prompt of the default button.

public void setPrompt(String prompt)

Discussion

This prompt appears on all NSSavePanels (or all NSOpenPanels if the receiver of this message is an NSOpenPanel) in your application. By default the text in the default button is “Open” for an Open panel and “Save” for a Save panel.

It is intended that short words or phrases, such as “Open,” “Save,” “Set,” or “Choose,” be used on the button. The button is not resized to accommodate long prompts.

Since this method previously affected a title field, any colon at the end of prompt is removed.

See Also

setRequiredFileType

Specifies the type, an extension to be appended to any selected files that don’t already have that extension; “nib” and “rtf” are examples.

public void setRequiredFileType(String type)

Discussion

The argument type should not include the period that begins the extension. Pass null to indicate any type. File type strings encoding HFS file types are not valid values for this attribute. You need to invoke this method each time the Save panel is used for another file type within the application.

This method is equivalent to calling setAllowedFileTypes with an array containing only type (unless type is null, and then it’s equivalent to calling setAllowedFileTypes with null).

See Also

setTitle

Sets the title of the receiver to title.

public void setTitle(String title)

Discussion

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

setTreatsFilePackagesAsDirectories

Sets the receiver’s behavior for displaying file packages (for example, MyApp.app) to the user.

public void setTreatsFilePackagesAsDirectories(boolean flag)

Discussion

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

title

Returns the title of the receiver.

public String title()

See Also

treatsFilePackagesAsDirectories

Returns whether the receiver displays file packages to the user as directories.

public boolean treatsFilePackagesAsDirectories()

See Also

URL

Returns the absolute pathname of the file currently shown in the receiver as a URL.

public java.net.URL URL()

See Also

validateVisibleColumns

Validates and possibly reloads the browser columns visible in the receiver by invoking the delegate method panelShouldShowFilename.

public void validateVisibleColumns()

Discussion

You might use this method if 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.

Delegate Methods

panelCompareFilenames

Controls the ordering of files presented by the NSSavePanel sender.

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

Discussion

This method should return:

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

Don’t reorder filenames 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 Finder. The default behavior of Save and Open panels is to order files as they appear in the Finder. Note also that by implementing this method you will reduce the operating performance of the panel.

panelDirectoryDidChange

Sent when the user has changed the selected directory in the NSSavePanel sender.

public abstract void panelDirectoryDidChange(Object sender, String path)

Discussion

path contains the newly selected directory.

Availability

panelIsValidFilename

public abstract boolean panelIsValidFilename(Object sender, String filename)

Discussion

The NSSavePanel sender sends this message just before the end of a modal session for each filename displayed or selected (including filenames in multiple selections). The delegate determines whether it wants the file identified by filename; it returns true if the filename 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 filename or names. If the delegate refuses a filename in a multiple selection, none of the filenames in the selection is accepted.

panelSelectionDidChange

Sent when the user has changed the selection in the NSSavePanel sender.

public abstract void panelSelectionDidChange(Object sender)

Availability

panelShouldShowFilename

Gives the delegate the opportunity to filter out items that it doesn’t want the user to see or choose.

public abstract boolean panelShouldShowFilename(Object sender, String filename)

Discussion

The NSSavePanel sender 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.

panelUserEnteredFilename

Sent when the user confirms a filename choice by hitting OK or Return in the NSSavePanel sender.

public abstract String panelUserEnteredFilename(Object sender, String filename, boolean okFlag)

Discussion

You can either leave the filename alone, return a new filename, or return null to cancel the save (and leave the Save panel as is). This method is sent before any required extension is appended to the filename and before the Save panel asks the user whether to replace an existing file.

Note that in the future, this method may be called multiple times in the sessions as the user types. In those cases, okFlag will be false until the user confirms the choice, in which case okFlag will become true. If the delegate does extensive validation or puts up alerts, it should do so only when okFlag is true.

See Also

panelWillExpand

Sent when the NSSavePanel sender is about to expand or collapse because the user clicked the disclosure triangle that displays or hides the file browser.

public abstract void panelWillExpand(Object sender, boolean expanding)



Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.