SaveFile

Description

The SaveFile class implements the pre-defined file-selection dialog to allow the user to choose a name and location for saving a file. This is a top-level object (i.e. it should not be opened as the child of a window).

To use the dialog, you must first create it using ⎕NEW. (Alternatively, you can create it as a top-level object using the New or Create method of ⎕WI). It will remain hidden at this stage. You can then optionally set the initial file name/path as the file property. This can be either:

• A full path name.
  
• Just the file part, in which case you get the current working directory.
  
• Just a directory ending in a directory-separation character ('\' '/' or ':' depending on the host system), in which case you get no initial file but the initial directory will be set.

Under Windows, the style property defines the behavior of the dialog (it is ignored under MacOS). It is an integer (default 0) made up of the sum of:

     2 =  Disable re-sizing
     4 =  Warn if the selection would overwrite an existing file
     8 =  Give error if the user selects a read-only file (Windows only)
     16 = Path must exist

Under Windows and Linux, the default property defines the default file extension which will automatically be added if the user enters a filename without an extension. It is not implemented in APLX for MacOS.

The filter property sets one or more filters (file extensions or types which will be allowed). It comprises one or more sets of descriptive text, a | character, and a semi-colon delimited list of supported filters. Multiple filters should be separated by a vertical bar.

Under Windows and Linux, you specify file extensions as file wildcards. For example, the filter 'Text files|*.txt;*.log|All files|*.*' gives the user the choice of selecting "Text files" (in which case extensions .txt and .log are accepted), or "All files" (any extension is accepted).

Under MacOS, you can choose to filter either using file extensions (in which case the syntax is identical to that used for Windows and Linux), or using file types. In the latter case the filters are four-character file types rather than file extensions beginning with the wildcard '*.'. For example: 'Picture files|JPEG;PICT' would display the description "Picture files" to the user, and allow selection of files of type JPEG and PICT. The file type '****' matches all file types. You can also combine both types of filter; for example, 'Text files|*.txt;TEXT' would match files which either have the extension .txt or which are of type TEXT.

The filterindex property determines which of the filters (in index origin 1) is displayed from the drop-down list.

Displaying the dialog

When you are ready to show the dialog, call the Show method. This displays the modal dialog. The user can then select a directory; if the Cancel button is pressed, the Show method returns 0. If the OK button is pressed, the Show method returns 1. You can then read the file property to retrieve the file selected by the user. This will be a character vector.

Example

      ∇DEMO_SaveFile;VERSION;⎕IO;DLG
[1]  ⍝ Sample function demonstrating use of the SaveFile object
[2]   DLG←'⎕' ⎕NEW 'SaveFile' ⋄ DLG.caption←'Save demonstration file'
[3]  ⍝
[4]  ⍝ Are we running on Windows or Mac? The way we specify the file filter
[5]  ⍝ is different...
[6]   ⎕IO←1
[7]   VERSION←'⎕' ⎕WI 'version'
[8]   :If VERSION[2]≠0
[9]     ⍝ Running under Windows or Linux:
[10]    ⍝ Set up default file
[11]    :If VERSION[2]=1
[12]      DLG.file←'c:\temp.txt'
[13]    :Else
[14]      DLG.file←'/temp.txt'
[15]    :EndIf
[16] ⍝
[17] ⍝ Set up filter
[18]    DLG.filter←'Text files (*.txt *.log)|*.txt;*.log|APL Workspaces (*.aws)|
      *.aws'
[19]  :Else
[20]    ⍝ Running under MacOS:
[21]    ⍝ Set up default file
[22]    DLG.file←'temp.txt'
[23]    ⍝
[24]    ⍝ Set up filter
[25]    DLG.filter←'Text files|TEXT|APL Workspaces|AXWS'
[26]  :EndIf
[27] ⍝
[28] ⍝ Show the dialog. If user presses Cancel, quit
[29]  →(0=DLG.Show)/0
[30] ⍝
[31] ⍝ He pressed OK.
[32]  'File selected: ',DLG.file
      ∇

Properties

caption children class data default events file filter filterindex methods name opened properties self style tie

Methods

Close Create Delete New Open Send Set Show Trigger

Callbacks

onClose onDestroy onOpen onSend