edu.uky.rch.ept.data.ui
Interface IAddressSelector

All Known Implementing Classes:

FileSystemAddressSelector, GeneralAddressSelector

public interface IAddressSelector

Interface for address selector. An address selector provides an widget (via the makeControl(Composite) and getControl() methods) which allows the user to select resources from a data source. Each data source driver provides its own implementation of IAddressSelector. The various methods of this interface, other than makeControl(Composite), may be called at any time, either before or after makeControl is called, though some may return null as specified by the method documentation. Those methods that change the selector's behaviour are effective both before and after the control has been created.

Author:

Neil Moore, Kranthi Bathula

Field Summary

static int	CREATE Mode for selecting only non-existing files.
static int	OPEN Mode for selecting only existing files.
static int	SAVE Mode for selecting either existing or non-existing files.

Method Summary

void	addAddressListener(IAddressListener listener) Add an address listener to this selector.
String	getAddress() Get the address for this selector.
org.eclipse.swt.widgets.Control	getControl() Get the already-created GUI control.
int	getExistenceMode() Get the existence mode for this selector.
String	getRoot() Get the relative-mode root for this selector.
boolean	hasAddress() Determine whether the user has selected a valid address.
boolean	isDirectories() Determine whether this selector is configured to select files or directories.
boolean	isRelative() Determine whether this selector is in relative mode.
org.eclipse.swt.widgets.Control	makeControl(org.eclipse.swt.widgets.Composite parent) Create a GUI control for this selector.
void	removeAddressListener(IAddressListener listener) Remove the specified address listener to this selector.
void	setAbsolute() Set this address selector to absolute mode.
void	setDirectories(boolean dir) Configure this selector to allow selection of files or directories.
void	setExistenceMode(int mode) Set the existence mode for this selector.
void	setRelative(String root) Set this address selector to relative mode with the specified root.

Field Detail

OPEN

public static final int OPEN

Mode for selecting only existing files.

See Also:

setExistenceMode(int), Constant Field Values

CREATE

public static final int CREATE

Mode for selecting only non-existing files.

See Also:

setExistenceMode(int), Constant Field Values

SAVE

public static final int SAVE

Mode for selecting either existing or non-existing files.

See Also:

setExistenceMode(int), Constant Field Values

Method Detail

addAddressListener

public void addAddressListener(IAddressListener listener)

Add an address listener to this selector. Every time the selected address changes (even to an invalid address), the listener's IAddressListener.addressChanged(IAddressSelector) method is called.

Parameters:

listener - the listener to add to this selector.

removeAddressListener

public void removeAddressListener(IAddressListener listener)

Remove the specified address listener to this selector.

Parameters:

listener - the listener to remove from this selector.

setRelative

public void setRelative(String root)
                 throws MalformedAddressException

Set this address selector to relative mode with the specified root. In relative mode, the user may only select files located beneath the root, and getAddress() returns relative paths. Changing between relative and absolute modes clears any address the user had previously selected.

Parameters:

root - the data layer address relative to which the user selects addresses. If it does not end in IDataConstants.SEP_MAJOR, that string is appended.

Throws:

MalformedAddressException - if root is not an absolute data layer address with the correct protocol identifier.

setAbsolute

public void setAbsolute()

Set this address selector to absolute mode. In absolute mode, the user may select any file on the filesystem, and getAddress() returns absolute data layer addresses. Changing between relative and absolute modes clears any address the user had previously selected.

isRelative

public boolean isRelative()

Determine whether this selector is in relative mode.

Returns:

true if this selector is in relative mode, false if it is in absolute mode.

getRoot

public String getRoot()

Get the relative-mode root for this selector.

Returns:

this selector's root as an absolute data layer address, if in relative mode. If in absolute mode, returns null.

setDirectories

public void setDirectories(boolean dir)

Configure this selector to allow selection of files or directories.

Parameters:

dir - if true, configure this selector to allow the selection of directories only. If false, allow the selection of non-directories only.

isDirectories

public boolean isDirectories()

Determine whether this selector is configured to select files or directories.

Returns:

true if this selector is configured to allow the selection of directories, otherwise false.

See Also:

setDirectories(boolean)

makeControl

public org.eclipse.swt.widgets.Control makeControl(org.eclipse.swt.widgets.Composite parent)

Create a GUI control for this selector. The precise realization of this control is up to the implementing data source driver.

Parameters:

parent - the parent for the control.

Returns:

the control.

Throws:

IllegalStateException - if makeControl has already been called.

getControl

public org.eclipse.swt.widgets.Control getControl()

Get the already-created GUI control.

Returns:

the control previously returned by makeControl(Composite), or null if makeControl has not yet been called.

hasAddress

public boolean hasAddress()

Determine whether the user has selected a valid address. An address is valid if its parent directory exits; and either the selector is in directory mode and no non-directory exists at the selected address, or the selector is not in directory mode and no directory exists at that address.

Returns:

true if a valid address has been selected, false otherwise.

getAddress

public String getAddress()

Get the address for this selector. Returns null if no valid address is selected (i.e., if hasAddress() would return false. If the selector is in relative mode, returns a relative address that may be appended to the result of getRoot() to obtain an absolute data layer address. If the selector is in absolute mode, returns an absolute data layer address.

Returns:

the currently-selected address, or null if none is selected.

setExistenceMode

public void setExistenceMode(int mode)

Set the existence mode for this selector. The existence mode determines whether the user may select files that already exist (open mode), files that do not yet exist (create mode), or either (save mode). If this method is not called, the default is open mode.

Parameters:

mode - one of the constants OPEN, SAVE, or CREATE.

Throws:

IllegalArgumentException - if the mode is not one of these constants.

getExistenceMode

public int getExistenceMode()

Get the existence mode for this selector.

Returns:

one of the constants OPEN, SAVE, or CREATE.

See Also:

setExistenceMode(int)