The 'file' property

Character vector (or a nested vector of character vectors)

Valid for: Movie, OpenFile, SaveFile, Image, Picture, OLEContainer, System

The file property allows you to set or retrieve a file name. The exact meaning depends on the object:

OpenFile and SaveFile pre-defined dialogs

For the two pre-defined dialogs which allow the user to select a file name, the file property contains the filename. If you set this property to a character vector before displaying the dialog, it determines the initial choice which will be presented in the dialog. You can set either:

• A full path name

• Just the file part, in which case you the current working directory is assumed.

• Just a directory (ending in a directory-separator character), in which case there is no initial file selection in the dialog, but the initial directory will be set.

After the dialog has been closed by the user, the file property contains the fully-qualified name of the selected file, usually as a character vector. In the case of the OpenFile dialog, you can optionally allow multiple files to be selected, by setting the style value 1. In this case, the file property will return a nested vector of file names.

Picture object

For a Picture object, the file property determines the image which will be displayed in the picture. Under Windows, it should be the name of a Windows bitmap, icon, or JPEG image file (.bmp, .ico, .jpg or .jpeg). Under MacOS, it should be the name of a JPEG or PICT file, or any image type supported by Apple's QuickTime software. Under Linux, the supported types depend on the operating system version but will typically include .png .xpm .jpg .jpeg .ico and .bmp files.

If you write an empty vector to the file property, a dialog is displayed allowing the user to choose an image file.

Image object

For an Image object, the file property contains the name of the file (if any) from which the image was loaded. Writing to the property causes the named file to be loaded. If you write an empty vector to the file property, a dialog is displayed allowing the user to choose an image file, which can be of any format supported by ImageMagick.

Movie object

When you initially create a Movie object, a blank rectangle is displayed because the system does not know what movie you wish to play. You select the particular movie you want by setting the file property for the movie object. (Note that you must do this after setting the style property). There are two ways you can specify the file:

(a) If you set the file property to be a file name, that is used as the movie file. The name can either be a simple file name (in which case the default volume and directory is assumed), or a full pathname. For example:

      MyWin.Mov.file←'Mydisk:Movies:Advert'

(b) If you set the file property to be an empty vector, APLX displays the standard file selection dialog box, allowing the user to choose a movie file. This is then used for the movie object automatically.

A special feature of movie objects is that setting the file property has the side effect of re-sizing the object to the default size for the selected movie. The movie will usually display best if the size of the object is the same as (or an integral multiple of) the original movie size. You can change the size of the movie object if you wish, but this must be done after setting the file property.

OLEContainer object

For an OLEContainer control, the file property determines the name of the document. If the OLE container is linked to a document, reading the file property allows you to find out its name.

Writing to the file property causes the container to attempt to load the document (or link to it, if the style is 1). If you write an empty vector, a dialog is displayed allowing the user to choose a document.

System object

If you have packaged your APL workspace as a standalone application, it may be launched by the user dragging one or more documents on to the application icon or double-clicking a document (for this to work, you need to have set up the association between the file type/extension and the application). Under Windows, the user may also have started the application from the command-line. The System object's file property allows your APL program to respond correctly to these user actions. It is a read-only property.

Under MacOS, file contains the full names of the document or documents which you should open or print. If there are several file names, they will be delimited by carriage-return characters. The action property indicates whether your should open or print them. The onOpen event is triggered if your application is already running.

Under Windows and Linux, there are two possibilities. If the user dragged a document icon on to your application icon (or double-clicked the document icon), file will contain the full filename of the document. If the user started your application from the command-line, file will contain the command-line options which were entered.