The Yoix^® Scripting Language

The most important fields in a JFileDialog are file, directory, and filters. In addition, a filedialog consumes system resources that are currently only returned after the filedialog is explicitly disposed, which happens when your program stores a non-zero value in the filedialog's dispose field. Yoix programs normally interact with a JFileDialog using event handlers and by reading or writing the following fields:

approvebuttonmnemonic	An int key code that is used as a mnemonic for the filedialog's approval button. Reading returns a snapshot of the current value. Writing immediately changes the mnemonic to the new value.
approvebuttontext	A String used to label the approval button used when choosing a file. Reading returns a snapshot of the current text. Writing immediately changes the text to the new value.
approvebuttontooltiptext	A String used as a tooltip when the cursor is over the filedialog's approval button. Reading returns a snapshot of the current tooltip text. Writing immediately changes the tooltip text to the new value.
autodispose	An int that arranges to dispose the filedialog, exactly as if a non-zero value had been stored in the dispose field, whenever a visible filedialog is hidden while autodispose is non-zero. Failure to dispose of unused filedialogs means system resources are lost, and that can eventually affect the performance of your program.
autoraise	An int that automatically puts the filedialog on top of all other windows whenever a non-zero value is stored in the filedialog's visible field.
background	The Color used to paint the background of the filedialog and it is also used as the background color of the filedialog that is displayed by the filedialog. A filedialog that does not set its own background color uses VM.screenbackground. Reading returns a snapshot of the current color. Writing immediately sets the background color of the filedialog and the filedialog that is displayed by the filedialog.
backgroundhints	An int that controls how backgroundimage is displayed in the filedialog. The value should be one of SCALE_AREA, SCALE_DEFAULT, SCALE_FAST, SCALE_NONE, SCALE_REPLICATE, SCALE_SMOOTH, or SCALE_TILE, which are all defined in yoix.image. SCALE_NONE places the unscaled image in the upper left corner of the filedialog, while SCALE_TILE (the default) tiles the entire filedialog with the unscaled image. The other values select the algorithm used to scale backgroundimage so it fills the entire filedialog. Reading returns the current hints. Writing immediately repaints the filedialog using the new hints to display the background image.
backgroundimage	An Object that should be an Image or String that identifies an image that is automatically displayed as part of the filedialog's background in a way that is controlled by the value assigned to backgroundhints. A NULL value, which is the default, means there is no image. A backgroundimage that is a String should name a local a file or URL that contains a GIF or JPEG image. Reading returns the current image. Writing immediately repaints the filedialog using the new image.
border	An Object that should be a Border, Insets, Number, or String that describes the border that is drawn around this filedialog. A NULL value, which is the default, means no border. A border that is an Insets or Number is handled differently than most other Swing components, because it is used, in combination with the insets field, to set the extent of the highlighted border, in units of 72 dots per inch, that is drawn around the filedialog. A border that is a String is a quick way to surround this filedialog with a border that uses the String as its title. Reading returns a snapshot of the current border. Writing immediately sets the filedialog's border to the new value.
components	A Dictionary maintained by the interpreter's layout machinery that contains a single entry that references the filedialog that is displayed by the filedialog.
cursor	An Object that should be an int, Image, or String that selects the cursor shown when the pointer is over the filedialog. A cursor that is an int should be one of the cursors defined in the yoix.awt.Cursor dictionary. A cursor that is an Image can describe the cursor using its size and hotspot fields and often draws it using its paint function. A cursor that is a String should be the name of a cursor that is already defined in yoix.awt.Cursor or the name a local a file or URL that contains a GIF or JPEG image that will be used as the cursor. Reading returns the current cursor. Writing immediately sets the filedialog's cursor to the new value. A filedialog that does not set its own cursor uses DEFAULT_CURSOR.
directory	A String that names the directory where the filedialog is currently looking for files, with NULL being a quick way to reference a system dependent directory (often the user's home). The directory and file fields in a filedialog are connected and changing either one usually affects the current directory, however when a filedialog is created the directory field is always processed before the file field. Reading directory returns the full pathname of the current directory. Storing a value in directory updates the current directory and sets the selected file to NULL. Storing a value in file selects that file and updates the current directory based on the newly selected file.
dispose	An int that is 1 when the filedialog has been properly disposed and 0 otherwise. Reading returns the current dispose state. Writing a non-zero value immediately disposes the filedialog; writing 0 has no effect, which means you cannot resurrect a disposed filedialog. Failure to dispose of unused filedialog means system resources are lost, and that can eventually affect the performance of your program.
doublebuffered	An int that is 1 (the default) when the filedialog uses double-buffering to draw itself and 0 when it does not. Reading returns the current double-buffering behavior. Writing immediately sets the filedialog's double-buffering behavior to the new value. Note that double-buffering may be required when transparent components are used. In addition, components contained in a filedialog that is using double-buffering may be using that buffer even when they explicitly disable double-buffering.
dragenabled	An int that should be set to 1 when this filedialog wants to use the automatic drag handling that Swing provides for some components, and 0 (the default) when it does not. Components that do not provide automatic drag handling always return 0 when their dragenabled field is read, so storing 1 in dragenabled should only be viewed as a request for a service that may not be available. Swing components can always take complete control of their drag and drop handling using their transferhandler field or special drag and drop event handlers.
enabled	An int that is 1 when the filedialog, or any of the components contained in the filedialog, can respond to user input, and 0 when they can not. Reading returns the current state. Writing immediately sets the filedialog's state to the new value.
file	A String, when multiplemode is zero, or an Array, when multiplemode is non-zero, that names the file or files currently selected by the filedialog. The directory and file fields in a filedialog are connected and changing either one can affect the current selection, however when a filedialog is created the directory field is always processed before the file field. Reading file returns the full pathname of each selected file or NULL if no file was selected or the Cancel button was hit. Storing a value in directory updates the current directory and sets the selected file to NULL. Storing a value in file selects the specified file or files and updates the current directory based on new selection.
fileselectionmode	An int that should be FILES_ONLY when only files can be selected, DIRECTORIES_ONLY when only directories can be selected, and FILES_AND_DIRECTORIES (the default) when files and directories can be selected. Reading returns the current setting. Writing immediately changes the selection mode that the filedialog is using.
filter	A String that is the text describing the current file filter. Reading returns the current setting. Writing immediately changes the file filter to the first filter among the loaded filters whose descriptor matches the supplied text. Text that matches none of the filter descriptors is silently ignored.
filters	An Array, organized in pairs, that provides a complete description of file filters that are available for reducing the set of files (but not directories) displayed by the filedialog. The first entry in a pair is the String that is displayed by the filedialog as the description of that filter. The second entry in the pair is the pattern, which can be supplied as a String or Regexp, that is matched against individual files. A pair that consists of two consecutive NULL entries is special and indicates that the "All Files" filter option should be included, however the "All Files" entry is only displayed once and it always is the last listed filter. Setting filters to NULL indicates that only the "All Files" filter should be supplied. Remember, directories are unaffected by the filters. By default, the last filter in the list is active; the filter field can be used to make a different filter active. Reading returns the current filter set. Writing immediately resets the filter set.
focusable	An int that is non-zero (the default) when the filedialog can accept the keyboard focus and zero when it can not. Reading returns the filedialog's current focusable state. Writing immediately changes the filedialog's focusable state to the new value, which means the focus is automatically transferred if the new value is zero and the filedialog is the current focus owner.
focusowner	A read-only int that is non-zero when the filedialog has the focus.
font	The Font, or font name if it is a String, assigned to the filedialog that is displayed by the filedialog. Reading returns a snapshot of the current font. Writing immediately changes the font used by the filedialog.
foreground	The Color used as the foreground color by the filedialog that is displayed by the filedialog. A filedialog that does not set its own foreground color uses VM.screen.foreground. Reading returns a snapshot of the current color. Writing immediately changes the foreground color of the filedialog that is displayed by the filedialog.
glasspane	A Swing component, often a JCanvas or JPanel, that completely covers the filedialog when its visible field is non-zero and is hidden otherwise. The component is transparent unless its opaque field is non-zero. Reading returns the current glasspane, which is NULL by default. Writing immediately changes the component the filedialog is using as its glasspane. In the current implementation the root field in glasspane does not point to the filedialog, but that may change in a future release.
graphics	A Graphics object that defines properties and built-ins that are used to apply graphics operations to this filedialog. Writing after a filedialog has been created is not allowed and will result in an invalidaccess error.
hiddenfiles	An int that should be non-zero when hidden files should be displayed in the chooser and zero otherwise. Reading returns the current setting. Writing immediately changes the display status of hidden files.
layout	An Array that is permanently set to NULL. Writing is not allowed and will result in an invalidaccess error.
layoutmanager	A LayoutManager that is permanently set to BorderLayout. Writing is not allowed and will result in an invalidaccess error.
location	A Point that determines the location of the filedialog's upper left corner in the default Yoix coordinate system, which has its origin at the upper left corner of the screen, positive x to the right, positive y down, and a resolution of 72 dots per inch. Reading returns a snapshot of the current location. Writing immediately moves the filedialog to the new location.
menubar	A JMenuBar that is attached to the filedialog. Reading returns the current menubar. Writing immediately removes the current menubar, if there is one and it is different than the new one, and attaches the new menubar.
modal	An int that is 1 (the default) when the filedialog must be dismissed (i.e., either hidden or disposed) before any user input will go to other windows, and 0 otherwise. Writing after a filedialog has been created is currently not allowed and will result in an invalidaccess error.
mode	An int that should be OPEN (the default) or LOAD when the user is being asked to select a file that will be read and SAVE when the selected file will be written. All three constants are defined in yoix.swing. Reading returns the current mode. Writing immediately changes the filedialog's mode to the new value.
multiplemode	A non-zero value indicates that multiple selections are possible, while a zero value indicates that only one selection at a time is permissible. Reading returns the current mode. Writing immediately changes the behavior of the filedialog.
opaque	An int that should be 0 (the default) or 1 that determines whether the filedialog that is displayed by the filedialog lets the background of the filedialog show through or not.
paint([Rectangle rect])	A Function that is called, if it is not NULL, whenever the filedialog needs to be painted. The optional rect argument describes the rectangle that needs repainting in the coordinate system specified by graphics.CTM, which by default has its origin at the filedialog's upper left corner, positive x to the right, positive y down, and a resolution of 72 dots per inch.
parent	A window, which usually should be a JFrame, JDialog, JFileDialog, JWindow, or JInternalFrame, that is responsible for the filedialog. Hiding, disposing, iconifying or deiconifying the parent does the same thing to its children, so using a parent is a convenient way to manage a group of windows. In addition, a filedialog with a parent that has not been explicitly placed somewhere (i.e., nothing has been stored in its location field) will be centered as well as possible over the parent whenever the it is shown. Reading returns the current parent. Writing sets the filedialog's parent to the new value.
popup	A JPopupMenu that is associated with the filedialog. Reading returns the current popup menu. Writing immediately shows the popup menu at the point in the filedialog's coordinate system specified by the popup menu's location field, assuming of course that the filedialog is showing on the screen. Storing TRUE in the popup menu's visible field, which was added in release 1.2.0, is an easy way to show the popup menu that currently belongs to the filedialog.
repaint([int immediate])	A Builtin that tells the filedialog to completely repaint itself, which means the background is regenerated and then the filedialog's paint function is called. If the optional immediate argument is non-zero the repaint request is handled immediately rather than being queued as an event that is processed later. Obviously repaint should not be called, either directly or indirectly, from the filedialog's paint function, however erasedrawable is safe because it does not trigger a paint call.
requestfocus	An int that can be used to request or transfer the keyboard focus. Storing a non-zero value in requestfocus tries to get the focus. Storing 0 tries to transfer the focus. Reading requestfocus does not currently return any useful information.
resizable	An int that is 1 (the default) when the filedialog can be resized by user actions, and 0 when its size is fixed.
root	A read-only field that for convenience always points to the filedialog itself.
screen	An Object that must be a Screen or an int that identifies the monitor that owns this filedialog. An int selects an element from the VM.screens array, with negative numbers mapped to the screen at index 0 and numbers that are too big mapped to the last screen in that array. Reading always returns the Screen object that owns the filedialog. Wrting is only allowed in the declaration that creates the filedialog. After that any attempt to change it will result in a invalidaccess error.
showing	A read-only int that is non-zero when the filedialog is showing on the screen. Reading showing or visible produce identical results for a top-level container like a filedialog.
size	A Dimension that determines the size of the filedialog in units of 72 dots per inch. Reading returns a snapshot of the current size. Writing immediately changes the filedialog's size to the new value. Setting size to NULL means the layoutmanager determines the size of the filedialog based on the preferred size of the filedialog.
tag	A String used to identify the filedialog that is either supplied when the filedialog is declared, or automatically generated otherwise. JFileDialogs are top-level containers, so the tag field is not particularly useful and may be deleted in future releases.
title	A String that is used as the filedialog's title. Reading returns a snapshot of the current title. Writing immediately changes the title to the new value.
tooltiptext	A String of characters that is displayed in a tightly sized pop-up window that appears near the cursor whenever the cursor lingers over the filedialog. Setting this value to NULL (the default) disables the tooltip mechanism. Reading returns the current tooltip text. Writing immediately sets the new tooltip text.
toyoixpath	An int that controls what happens to platform dependent file separators when the file and directory fields are read. When toyoixpath is non-zero all file separators are replaced by the slash character /, otherwise no changes are made.
visible	An int that is 1 when the filedialog is visible, and 0 otherwise. Reading returns the current visibility. Writing immediately sets the filedialog's visibility to the new state.

Several permanent fields have not been documented and should not be used in Yoix applications.

A filedialog can be told where to look by setting its directory or file fields. By default, a filedialog blocks the rest of your application while it is visible, however that behavior can be changed using the modal field. When a filedialog is dismissed all you do is read the file field and you get the full pathname of the selected file, or NULL if no file was selected or the Cancel button was hit; the style of that pathname is controlled by the toyoixpath field.

Event handlers are functions that must be added to a filedialog when it is declared. The handlers that work with filedialogs are listed below; the names should be familiar if you have done some Java programming.

Event Handlers:	componentHidden, componentMoved, componentResized, componentShown, dragDropEnd, dragEnter, dragExit, dragGestureRecognized, dragMouseMoved, dragOver, drop, dropActionChanged, focusGained, focusLost, invocationRun, keyPressed, keyReleased, keyTyped, mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, mouseWheelMoved, windowActivated, windowClosed, windowClosing, windowDeactivated, windowDeiconified, windowIconified, windowOpened
Example:	The program, import yoix.*.*; JFileDialog fd = { String directory = VM.tmpdir; int mode = OPEN; Array filters = { "Text files", "*.txt", NULL, NULL, }; }; printf("Ready...\n"); fd.visible = TRUE; if (fd.file != NULL) printf("You selected: %s\n", fd.file); else printf("You made no selection\n"); printf("Ready to try again...\n"); fd.visible = TRUE; if (fd.file != NULL) printf("The second time, you selected: %s\n", fd.file); else printf("The second time, you made no selection\n"); shows a filedialog that starts in your system's temp directory. It also supplies a filter for selecting files that end with a "txt" suffix. Pick a file and the full pathname should print on standard output; hit the Cancel button and you should see an indication that you made no selection on standard output. After this interaction, the filedialog will start again in the same directory and with the same selected file, if any, as at the end of your previous interaction.
See Also:	BorderLayout, BoxLayout, CardLayout, CustomLayout, FlowLayout, GridBagLayout, GridLayout, invokeLater, JButton, JCanvas, JCheckBox, JCheckBoxMenuItem, JChoice, JColorChooser, JComboBox, JDesktopPane, JDialog, JFileChooser, JFrame, JInternalFrame, JLabel, JLayeredPane, JList, JMenu, JMenuBar, JMenuItem, JPanel, JPasswordField, JPopupMenu, JProgressBar, JRadioButton, JRadioButtonMenuItem, JScrollBar, JScrollPane, JSeparator, JSlider, JSplitPane, JTabbedPane, JTable, JTextArea, JTextCanvas, JTextField, JTextPane, JTextTerm, JToggleButton, JToolBar, JTree, JWindow, LayoutManager, postEvent, toBack, toFront