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 { |
| } | 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: |
| 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: |
| 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: |
| 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: |
| 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: |
| 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. |
unsigned int opening:1;