Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

SavePanel



Inherits From: Panel : Window : Responder : Object
Declared In: appkit/SavePanel.h



Class Description

The SavePanel provides a simple way for an application to query the user for the name of a file to use when saving a document or other data.  It allows the application to restrict the file name to have a certain file type, as specified by a file name extension. There is one and only one SavePanel in an application and the new method returns a pointer to it.

Whenever the user actually decides on a file name, the message panelValidateFilenames: is sent to the SavePanel's delegate (if it responds to that message).  The delegate can then determine whether that file name can be used; it returns YES if the file name is valid, or NO if the SavePanel should stay up and wait for the user to type in a different file name.  The delegate can also implement a panel:filterFile:inDirectory: method to test that both the file name and the directory are valid.



Instance Variables

id form;

id browser;

id okButton;

id accessoryView;

id separator;

char *filename;

char *directory;

const char **filenames;

char *requiredType;

struct _spFlags {
unsigned int  opening:1;
unsigned int  exitOk:1;
unsigned int  allowMultiple:1;
unsigned int  dirty:1;
unsigned int  invalidateMatrices:1;
unsigned int  filtered:1;

} spFlags;
unsigned short  directorySize;


form The form in which the user types file names
browser The browser displaying the file hierarchy
okButton The OK button
accessoryView Application-customized area
separator The line separating the icon from the rest of the panel
filename The chosen file name
directory The directory of the chosen file
filenames The list of chosen files
requiredType The type of file to save
spFlags.opening Specifies whether file is being opened or saved
spFlags.exitOk Exit status
spFlags.allowMultiple Whether to allow multiple files
spFlags.dirty Dirty flag for invisible updates
spFlags.invalidateMatrices Whether the matrices are valid
spFlags.filtered Whether types are filtered
directorySize Length of the directory string



Method Types

Creating and freeing a SavePanel
+ newContent:style:backing:buttonMask:defer:
free
Setting the SavePanel class + setSavePanelFactory:
Customizing the SavePanel setAccessoryView:
accessoryView
setTitle:
setPrompt:
Setting directory and file type setDirectory:
setRequiredFileType:
requiredFileType
Handling file packages doesTreatFilePackagesAsDirectories
setTreatsFilePackagesAsDirectories:
Running the SavePanel runModal
runModalForDirectory:file:
Reading save information directory
filename
Completing a partial filename commandKey:
Action methods cancel:
ok:
Responding to user input selectText:
textDidGetKeys:isEmpty:
textDidEnd:endChar:
Setting the delegate setDelegate:
delegate (Window)



Class Methods

alloc
+ alloc

Generates an error message.  This method cannot be used to create SavePanel instances.  Use the newContent:style:backing:buttonMask:defer: method instead.

See also:   + newContent:style:backing:buttonMask:defer:



allocFromZone:
+ allocFromZone:(NXZone *)zone

Generates an error message.  This method cannot be used to create SavePanel instances.  Use the newContent:style:backing:buttonMask:defer: method instead.

See also:  + newContent:style:backing:buttonMask:defer:



newContent:style:backing:buttonMask:defer:
+ newContent:(const NXRect *)contentRect
style:(int)aStyle
backing:(int)bufferingType
buttonMask:(int)mask
defer:(BOOL)flag

Creates, if necessary, and returns a new instance of SavePanel.  Each application shares just one instance of SavePanel; this method returns the shared instance if it exists.  A simpler interface is available via the inherited method new, which invokes this method with all the appropriate parameters.

See also:  + setSavePanelFactory:



setSavePanelFactory:
+ setSavePanelFactory:class

Sets the class from which SavePanel will be instantiated.  class should be a subclass of SavePanel.  If you want to use your own SavePanel subclass, your application must invoke this method before it creates the shared instance of SavePanel, or else free the shared instance before invoking this method.  When the newContent:style:backing: buttonMask:defer: method is invoked, the object it returns will belong to class.

See also:  + newContent:style:backing:buttonMask:defer:



Instance Methods

accessoryView
accessoryView

Returns the view set by setAccessoryView:.

See also:  setAccessoryView:



cancel:
cancel:sender

This method is the action message sent by the Cancel button to the SavePanel.  Returns self.



commandKey:
(BOOL)commandKey:(NXEvent *)theEvent

This method is used to accept command-key events.  If theEvent contains a Command-Space, the SavePanel will do file name completion; if it contains a Command-H, the SavePanel jumps to the user's home directory.  Other command-key events are ignored.  Returns YES.



directory
(const char *)directory

Returns the path of the directory that the SavePanel is currently showing.



doesTreatFilePackagesAsDirectories
(BOOL)doesTreatFilePackagesAsDirectories

Tests whether the SavePanel displays file packages to the user as directories.  Returns YES (the default)  if the user is shown files and subdirectories within a file package.  Returns NO if the user is shown only file package names, with no indication that they are directories.

See also:  setTreatsFilePackagesAsDirectories:



filename
(const char *)filename

Returns the filename--including the path to the file--that the SavePanel last accepted.



free
free

Frees all storage used by the SavePanel.



ok:
ok:sender

This method is the action message sent by the OK button to the SavePanel.



requiredFileType
(const char *)requiredFileType

Returns the last type set by setRequiredFileType:.



runModal
(int)runModal

Displays the panel and begins its event loop.  Invokes Application's runModalFor: method with self as the argument.  Returns NX_OKTAG (if the user clicks the OK button) or NX_CANCELTAG (if the user clicks the Cancel button).

See also:   runModalFor: (Application)



runModalForDirectory:file:
(int)runModalForDirectory:(const char *)path file:(const char *)filename

Initializes the panel to the file specified by path and name, then displays it and begins its modal event loop.  Invokes Application's runModalFor: method with self as the argument.   Returns NX_OKTAG (if the user clicks the OK button) or NX_CANCELTAG (if the user clicks the Cancel button).

See also:   runModalFor: (Application)



selectText:
selectText:sender

Advances the current browser selection one line when Tab is pressed (goes back one line when Shift-Tab is pressed).



setAccessoryView:
setAccessoryView:aView

aView should be the top View in a view hierarchy which will be added just above the OK and Cancel buttons at the bottom of the panel.  The panel is automatically resized to accommodate aView.  This method can be called repeatedly to change the accessory view depending on the situation.  If aView is nil, any accessory view in the panel will be removed.



setDelegate:
setDelegate:anObject

Makes anObject the SavePanel's delegate.  Returns self.



setDirectory:
setDirectory:(const char *)path

Sets the current path in the SavePanel browser.  Returns self.



setPrompt:
setPrompt:(const char *)prompt

Sets the title for the form field in which users type their entries into the panel.  This title will appear on all SavePanels (or all OpenPanels if the receiver of this message is an OpenPanel) in your application.  "File:" is the default prompt string.  Returns self.



setRequiredFileType:
setRequiredFileType:(const char *)type

Specifies the type, a file name extension to be appended to any selected files that don't already have that extension; for example, "nib".  type should not include the period that begins the extension.  Be careful to invoke this method each time the SavePanel is used for another file type within the application.  Returns self.



setTreatsFilePackagesAsDirectories:
setTreatsFilePackagesAsDirectories:(BOOL)flag

Sets the SavePanel's behavior for displaying file packages to the user.  If flag is YES, the user is shown files and subdirectories within a file package.  If NO, the user is shown only file package names, with no indication that they are directories.

See also:  doesTreatFilePackagesAsDirectories



setTitle:
setTitle:(const char *)newTitle

Sets the title of the SavePanel to newTitle and returns self.  By default, "Save" is the title string.  If a SavePanel is adapted to other uses, its title should reflect the user action that brings it to the screen.



textDidEnd:endChar:
textDidEnd:textObject endChar:(unsigned short)endChar

Determines whether the key that ended text was Tab or Shift-Tab so that selectText: knows whether to move forward or backwards.  Returns self.



textDidGetKeys:isEmpty:
textDidGetKeys:textObject isEmpty:(BOOL)flag

Invoked by the Panel's text to indicate whether there is any text in the Panel.  Disables the OK button if there is no text in the Panel.



Methods Implemented by the Delegate

panel:compareFilenames::checkCase:
(int)panel:sender
compareFilenames:(const char *)fileName1 :(const char *)fileName2
checkCase:(BOOL)flag

Controls the ordering of files presented by the SavePanel.  This method should return 1 if fileName1 should precede fileName2, 0 if the two names are equivalent, and -1 if fileName2 should precede fileName1.

Don't reorder file names in the SavePanel lightly, since it may confuse the user to have files in one SavePanel or OpenPanel ordered differently than those in other such panels or in the Workspace Manager.  SavePanel and OpenPanel's default behavior is to order files as they are in the Workspace Manager file viewer.  Note also that implementing this method will reduce the operating performance of the panel.



panel:filterFile:inDirectory:
(BOOL)panel:sender
filterFile:(const char *)filename
inDirectory:(const char *)directory

A SavePanell sends this message to the panel's delegate for each file or directory it is about to display in the browser.  The delegate can then determine whether the filename or directory should be displayed in the panel, giving it the ability to filter out items that it doesn't want the user to see or choose.  It returns YES if it is to be displayed, or NO if the SavePanel should ignore the file or directory.



panelValidateFilenames:
(BOOL)panelValidateFilenames:sender

Sent to the panel's delegate.  The delegate can then determine whether the current file name in the SavePanel can be used; it returns YES if the file name is valid, or NO if the SavePanel should stay up and wait for the user to type in a different file name. The delegate can get the file name in the SavePanel by sending a filename message back to sender.