/*******************************************************************************
* Copyright (c) 2007, 2014 compeople AG and others.
* 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:
* compeople AG - initial API and implementation
*******************************************************************************/
package org.eclipse.riena.ui.ridgets;
import org.eclipse.core.databinding.observable.list.IObservableList;
/**
* A ridget with two areas. The master area shows a table of objects, from which
* one can be selected. The details are allows the user to edit some details of
* the currently selected object/row.
* <p>
* This ridget is an {@link IComplexRidget} an {@link ITableRidget} to show the
* available objects and several {@link IActionRidget}s to add, delete, update
* the row elements.
* <p>
* The UI of the details area is created by implementing an
* MasterDetailComposite. The binding between UI and ridgets is done by
* implementing an {@link IMasterDetailsDelegate} and introducing it to this
* ridget via {@link #setDelegate(IMasterDetailsDelegate)}.
*/
public interface IMasterDetailsRidget extends IComplexRidget {
/**
* Binds the table to the model data.
*
* @param rowObservables
* An observable list of objects (non-null).
* @param rowClass
* The class of the objects in the list.
* @param columnPropertyNames
* The list of property names that are to be displayed in the
* columns. One property per column. Each object in
* rowObservables must have a corresponding getter. This
* parameter must be a non-null String array.
* @param columnHeaders
* The titles of the columns to be displayed in the header. May
* be null if no headers should be shown for this table.
* Individual array entries may be null, which will show an empty
* title in the header of that column.
* @throws RuntimeException
* when columnHeaders is non-null and the the number of
* columnHeaders does not match the number of
* columnPropertyNames
*/
void bindToModel(IObservableList rowObservables, Class<? extends Object> rowClass, String[] columnPropertyNames,
String[] columnHeaders);
/**
* @param listHolder
* An object that has a property with a list of objects.
* @param listPropertyName
* Property for accessing the list of objects.
* @param rowClass
* Property for accessing the list of objects.
* @param columnPropertyNames
* The list of property names that are to be displayed in the
* columns. One property per column. Each object in
* rowObservables must have a corresponding getter. This
* parameter must be a non-null String array.
* @param headerNames
* The titles of the columns to be displayed in the header. May
* be null if no headers should be shown for this table.
* Individual array entries may be null, which will show an empty
* title in the header of that column.
*/
void bindToModel(Object listHolder, String listPropertyName, Class<? extends Object> rowClass,
String[] columnPropertyNames, String[] headerNames);
/**
* This method checks if the details can be overwritten by
* {@link #suggestNewEntry(Object)}. If the details are dirty, the user will
* be asked to discard changes (via a blocking dialog).
*
* @return true if the details or not dirty or can be overwritten (@see
* {@link #suggestNewEntry(Object)}, false otherwise
* @since 3.0
*/
boolean canSuggest();
/**
* Return the current {@link IMasterDetailsDelegate} or null, if none has
* (yet) been set.
*
* @return the current {@link IMasterDetailsDelegate} or null
* @since 2.0
*/
IMasterDetailsDelegate getDelegate();
/**
* Returns the currently object corresponding to the currently selected row
* in the ridget.
*
* @return the actual selection in the ridget or null (if nothing is
* selected)
*/
Object getSelection();
/**
* Return true if the 'Apply' action enables on the condition that all
* ridgets in the Details have <b>no</b> error markers.
* <p>
* The default setting for this option is false.
*
* @return true if the 'Apply' action enables on the condition that all
* ridgets in the Details have <b>no</b> error markers; otherwise
* false
*
* @since 2.0
*/
boolean isApplyRequiresNoErrors();
/**
* Return true if the 'Apply' action enables on the condition that all
* ridgets in the Details are have <b>no</b> mandatory markers.
* <p>
* The default setting for this option is false.
*
* @return true if the 'Apply' action enables on the condition that all
* ridgets in the Details are have <b>no</b> mandatory markers;
* otherwise false
*
* @since 2.0
*/
boolean isApplyRequiresNoMandatories();
/**
* Return true, if a sucessfull 'Apply' triggers the 'New' action. If the
* 'New' action is unavailable, the method returns false regardless of the
* setting.
* <p>
* The default setting for this option is false.
*
* @return Return true, if a sucessfull 'Apply' triggers the 'New' action. *
* If the 'New' action is unavailable, the method returns false
* regardless of the setting.
*
* @since 2.0
*/
boolean isApplyTriggersNew();
/**
* When direct writing is enabled, changes in the details area will be
* immediately and automatically applied back to the model. When adding new
* rows, these will be immediately added to the table. Since there is no
* need to apply, the 'Apply' action will not be shown.
* <p>
* The default setting for direct writing is false.
*
* @return true if 'directWriting' is enabled; otherwise false
*
* @since 1.2
*/
boolean isDirectWriting();
/**
* When set to true, mandatory and error markers in the details area will
* <b>initially</b> not be shown on new and suggested entries (i.e. when the
* user invokes the 'New' action or the entry is suggested via the
* {@link #suggestNewEntry()} methods). These markers will be displayed once
* the user modifies at least one value in the details area.
* <p>
* The default setting for this option is false.
*
* @return true if this option is enabled, false otherwise
* @since 3.0
*/
boolean isHideMandatoryAndErrorMarkersOnNewEntries();
/**
* When set to true, the 'Remove' action can be used to abort editing of a
* new entry. When aborting, the entry selected before pressing New will be
* selected. If the 'Remove' action is unavailable, the method returns false
* regardless of the setting.
* <p>
* The default setting for this option is false.
*
* @return true if the Remove action can be used to aborting editing of a
* new entry, false otherwise.
*
* @since 3.0
*/
boolean isRemoveCancelsNew();
/**
* Return true, if a sucessfull 'Remove' triggers the 'New' action. If the
* 'Remove' action is unavailable, the method returns false regardless of
* the setting.
* <p>
* The default setting for this option is false.
*
* @return Return true, if a sucessfull 'Remove' triggers the 'New' action.
* * If the 'Remove' action is unavailable, the method returns false
* regardless of the setting.
*
* @since 3.0
*/
boolean isRemoveTriggersNew();
/**
* When set to true, the 'Apply' action will only enable when all ridgets in
* the Details area have <b>no</b> error markers.
* <p>
* The default setting for this option is false.
*
* @param requiresNoErrors
* The new setting for this option.
*
* @since 1.2
*/
void setApplyRequiresNoErrors(boolean requiresNoErrors);
/**
* When set to true, the 'Apply' action will only enable when all ridgets in
* the Details area have <b>no</b> mandatory markers.
* <p>
* The default setting for this option is false.
*
* @param requiresNoMandatories
* The new setting for this option.
*
* @since 2.0
*/
void setApplyRequiresNoMandatories(boolean requiresNoMandatories);
/**
* When set to true, a sucessfull 'Apply' will trigger a 'New'. This will
* only happen if the 'New' action is available.
* <p>
* The default setting for this option is false.
*
* @param triggersNew
* The new settings for this option.
*
* @since 2.0
*/
void setApplyTriggersNew(boolean triggersNew);
/**
* Adjust the column widths of the ridget's table control according to the
* information in the {@code widths} array.
* <p>
* When running on SWT: {@code widths} may only contain subclasses of
* ColumnLayoutData. The following layout managers are supported:
* TableLayout, TableColumnLayout, other. See ColumnUtils for implementation
* details.
*
* @param widths
* an Array with width information, one instance per column. The
* array may be null, in that case the available width is
* distributed equally to all columns.
*
* @since 1.2
*/
void setColumnWidths(Object[] widths);
/**
* Provide this ridget with an {@link IMasterDetailsDelegate} instance,
* which will manage the content of details area.
*
* @param delegate
* an {@link IMasterDetailsDelegate}; never null
*/
void setDelegate(IMasterDetailsDelegate delegate);
/**
* When direct writing is enabled, changes in the details area will be
* immediately and automatically applied back to the model. When adding new
* rows, these will be immediately added to the table. Since there is no
* need to apply, the 'Apply' action will not be shown.
* <p>
* The default setting for direct writing is false.
*
* @param directWriting
* The new direct writing setting.
*
* @since 1.2
*/
void setDirectWriting(boolean directWriting);
/**
* When set to true, mandatory and error markers in the details area will
* <b>initially</b> not be shown on new and suggested entries (i.e. when the
* user invokes the 'New' action or the entry is suggested via the
* {@link #suggestNewEntry()} methods). These markers will be displayed once
* the user modifies at least one value in the details area.
* <p>
* The default setting for this option is false.
* <p>
* Notes:
* <ul>
* <li>when
* {@link IMasterDetailsDelegate#isValidMaster(IMasterDetailsRidget)} fails
* a special marker is added to all ridgets. This marker is always shown
* regardless of the value of this option</li>
* <li>consider enabling {@link ITextRidget}
* {@link #setDirectWriting(boolean)} for text ridgets in the details area,
* so that the markers are re-displayed after the first keystroke</li>
* <li>when this options is enabled, the visual feedback for some markers
* will be disabled. However the markers are never removed or readded from
* the ridgets in the details area (to avoid ambiguity about the marker
* state of those ridgets)</li>
* </ul>
*
* @since 3.0
*/
void setHideMandatoryAndErrorMarkersOnNewEntries(boolean hideMarkers);
/**
* When set to true, the 'Remove' action can be used to abort editing of a
* new entry. When aborting, the entry selected before pressing New will be
* selected.
* <p>
*
*
* @param cancelsNew
* the new setting for this option
*
* @since 3.0
*/
void setRemoveCancelsNew(boolean cancelsNew);
/**
* When set to true, a sucessfull 'Remove' will trigger a 'New'. This will
* only happen if the 'Remove' action is available.
* <p>
* The default setting for this option is false.
*
* @param triggersNew
* The new settings for this option.
*
* @since 3.0
*/
void setRemoveTriggersNew(boolean triggersNew);
/**
* Set the new selection. This behaves exactly like an interactive selection
* change (i.e. the user selecting another value).
*
* @param newSelection
* the newly selected value of this ridget, or null to clear the
* selection
*/
void setSelection(final Object newSelection);
/**
* Suggest a blank object – obtained from
* {@link IMasterDetailsDelegate#createWorkingCopy()}) – as a 'new'
* entry. It will be made editable in the details area. The details area
* will <b>not</b> be considered dirty. The apply action will be
* <b>disabled</b>, until the user edits the contents.
*
* @since 3.0
*/
void suggestNewEntry();
/**
* Suggest the given object as a 'new' entry. It will be made editable in
* the details area. The details area will be considered dirty and the apply
* action will be enabled (unless direct writing is enabled).
*
* @param entry
* a non-null object. Note that when the user invokes the 'Apply'
* operation, the {@code entry} will be updated with the contents
* from the details area and then added into the master table of
* objects. For this reason you should use a <b>new</b>
* {@code entry} instance for each call to this method.
* @since 2.0
*/
void suggestNewEntry(Object entry);
/**
* Suggest the given object as a 'new' entry. It will be made editable in
* the details area. The details area may or not be considered dirty,
* depending on the {@code treatAsDirty} argument. Likewise, the apply
* action may or may not be enabled depending on the {@code treatAsDirty}
* argument.
* <p>
* Note: if direct writing is enabled, the details area / apply button will
* be considered as not dirty regardless of the {@code treatAsDirty} value.
*
* @param entry
* a non-null object. Note that when the user invokes the 'Apply'
* operation, the {@code entry} will be updated with the contents
* from the details area and then added into the master table of
* objects. For this reason you should use a <b>new</b>
* {@code entry} instance for each call to this method.
* @param treatAsDirty
* true, to treat the details area as dirty and enable the apply
* button. False to treat the details area as initially
* unmodified and disable the apply button (until the content is
* modified).
*
* @since 3.0
*/
void suggestNewEntry(Object entry, boolean treatAsDirty);
/**
* Toggles the 'Apply' action state, according to the presence of changes in
* the details area. It will use delegate.isChanged(...) to compare the data
* in the details area with the original and enable the 'Apply' action if it
* differs.
* <p>
* Use this method when the data in the details has been modified without
* sending a notification to the IMasterDetailsRidget (for example, in a
* separate dialog that was opened).
*
* @since 2.0
*/
void updateApplyButton();
/**
* Applies the details to the master.
*
* @since 3.0
*/
void handleApply();
}