at.spardat.xma.mdl.ISelectable Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2003, 2007 s IT Solutions AT Spardat GmbH .
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* s IT Solutions AT Spardat GmbH - initial API and implementation
*******************************************************************************/
// @(#) $Id: ISelectable.java 2089 2007-11-28 13:56:13Z s3460 $
package at.spardat.xma.mdl;
/**
* This interface is implemented by widget models that support the selection of entries in a
* keyed set (lists, tables, trees). Each entry in the underlying value domain has a key of
* type String which uniquely identifies the entry within the value domain. There may exist at most one
* entry with a particular key. This interface allows either to query the selection or to modify it.
*
* This interface supports two variants. The first behaviour is called strict. With
* strict behaviour, the currently selected entries are always drawn from the underlying value
* domain. With !isStrict() (which is only allowed in models having !isMultiSelect()),
* the selected value needs not to be contained in the domain.
*
* @author YSD, 08.04.2003 17:51:45
*/
public interface ISelectable {
/**
* Sets the entry with a provided key as selected. If this model does not allow
* multiselection, a previous selected element is deselected before.
*
* If isStrict() and the provided key is not contained in the underlying
* domain, this method does nothing.
*
* @param key the entry to select
* @exception IllegalArgumentException if key is null.
*/
public void select (String key);
/**
* Deselects a particular entry. If the entry for the provided key is not selected, this
* method does nothing.
*
* @param key identifies the entry to deselect. If the entry with the provided key is not
* selected, this method does nothing.
* @exception IllegalArgumentException if key is null.
*/
public void deselect (String key);
/**
* All selected entries get deselected. After calling this method, the condition
* getSelectionCount() == 0 holds.
*/
public void deselectAll ();
/**
* Returns true if more than one entry may be selected.
*
* @return boolean true if the widget model realizing this interface allows multiselection.
*/
public boolean isMultiSelect ();
/**
* Returns the id of the selected element. If nothing is selected, null is returned.
* If more than one entry is selected, some of them is returned. Note that the selected
* id need not have to be in the underlying domain of this if !isStrict().
*
* Usually, this method is the preferred way of querying the selection state if
* !isMultiSelect().
*
* @return key of selected entry or null if nothing is selected
*/
public String getSelected ();
/**
* Returns a newly created array containing the ids of the selected entries or
* an empty array, if nothing is selected.
*
* @return array of the selected keys. The length of the array equals getSelectionCount().
*/
public String[] getSelection ();
/**
* Returns the number of selected elements.
*
* @return number of selected elements
*/
public int getSelectionCount();
/**
* Returns true if the entry with the provided key is selected, false otherwise.
*/
public boolean isSelected (String key);
/**
* Returns if this Selectable has strict behaviour, that is, the selected keys must
* always be in the underlying domain of this. In the case of !isStrict(),
* the selected key may be freely choosen and need not be drawn from the domain.
*
* Strict behaviour is only supported if !isMultiSelect(). That means,
* isMultiSelect() always implies isStrict().
*
* @return true if the widget model implementing this interface supports strict behaviour,
* false otherwise.
*/
public boolean isStrict();
}