at.spardat.xma.mdl.UIDelegateClient 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: UIDelegateClient.java 3240 2009-03-03 16:10:56Z gub $
package at.spardat.xma.mdl;
import at.spardat.xma.page.EventAdapter;
/**
* A UIDelegateClient is an aspect of a WidgetModel which is responsible for handling all
* UI related tasks. All client side widget models have a UIDelegateClient attached
* at construction time.
*
* A UIDelegateClient is in one of two states: isUIAttached() or not. This
* specifies, whether a widget is attachet or not.
*
* A note about the WModel enable/disable behauvior as implemented by the UIDelegateClients:
1. A call to WModel.setEnabled() is stored at the attribute enabled_ and set at the underlying widget.
2. If WModel.isEnabled() is called the value is always taken from the underlying widget.
Then this actual value is also stored at the attribute enabled_.
So if the widget was manipulated directly this is reflected at the model.
Also this is the behauvior as implemented so far.
3. Normally at attachUI() the enabled_ value is set at the widget.
4. attachUI(): If the widget is disabled then this overrides the model's enabled_ state.
Then the attribute enabled_ is set to false, too.
It is assumed that disabling a widget is done deliberately (as it is not the default),
so the value is taken from there (instead from the model).
Also this is the behauvior as implemented so far (e.g. in the *Gen classes disabling is set on widgets).
5.Resume: The widget model now stores the enabled state.
But this is always overritten by a widget's negative enabled state, or in other words:
Only a negative enable state of a WModel is rembered, a positive is always overwritten.
*
*
*/
public abstract class UIDelegateClient {
/**
* Constructs a UIDelegateClient. Used by the UIDelegateFactoryClient. After this method
* returns, isUIAttached() is false.
*/
protected UIDelegateClient () {
}
/**
* This method is responsible for accepting events originating from the UI library,
* creating corresponding ModelChangeEvents and updating the WidgetModels.
*
* This method does nothing if isUIAttached() is false.
* @param event the Event-object from a particular UI libraray, e.g., SWT.
* @param type TODO
*/
public abstract void handleUIEvent (Object event, int type);
/**
* The widget model has been changed. The change is described by the provided event
* object. If this UIDelegateClient is UI-attached, this method must synchronize the
* change with the UI. Note that the change has already been applied to
* the model, i.e., the model already reflects the new (changed) state.
*/
public abstract void handleModelChangeEvent (ModelChangeEvent event);
/**
* Returns the WidgetModel this UIDelegateClient is attached to.
*
* @return the WidgetModel, never null.
*/
public abstract WModel getWModel();
/**
* Yields true, if this UIDelegateClient is attached, i.e., has a Control
* of the UI-library associated.
*
* @return true if attached.
*/
public abstract boolean isUIAttached();
/**
* Attaches a UI library control. Upon successful attachement, isUIAttached()
* holds true.
*
* @param control an object of the UI class library. For example, in the
* case of SWT it is a SWT Widget like a Text, Label or Check Box.
* @param label a widget of the UI class library which is the label for control.
* With SWT, typically it the control is a Text field, the
* label is a Label widget which usually is the widget
* holding the describing text in front of the Text field. The label
* is used in error messages. It may be null.
* @exception AttachmentExceptionClient if the control cannot be attached.
*/
public abstract void attachUI (Object control, Object label) throws AttachmentExceptionClient;
/**
* Add the given adapter as listener to the given control. The delegate decides the
* types of listeners the adapter is registered to.
* @since 2.1.0
*/
public abstract void addListeners(Object control,EventAdapter adapter);
/**
* Creates a suitable SWT Control for the widget model of this delegate.
* @param parent an SWT Composite which will be the parent of the new control.
* @since 2.1.0
*/
public abstract Object createControl(Object parent);
/**
* This method returns the attached UI-control.
*
* @return The attached UI-control.
* @throws IllegalStateException if !isUIAttached().
*/
public abstract Object getUIControl ();
/**
* Returns the label that has been provided via attachUI. Returns null if
* the label provided in attachUI was null.
*
* @throws IllegalStateException if !isUIAttached().
*/
public abstract Object getUILabel ();
/**
* Detaches the UI-control.
*/
public abstract void detachUI();
/**
* Returns true if this model's widget may be modified by the end-user.
* Returns false, if the widget may not be edited, but the content of
* the widget should be readable and receive focus.
*/
public abstract boolean isEditable ();
/**
* Sets the editable-state of this models's widget. A widget which is not editable
* can not be modified by the end user. Unlike the disabled-state, its contents
* remains readable and still receives focus.
*
* Usually, this method is called on all widget-models of a page to set the whole
* page to a read-only mode.
*
* If this method is not called, the default is true.
*
* @param what true if the model's widget should be editable, false otherwise.
*/
public abstract void setEditable (boolean what);
/**
* Returns true, if this model's widget is enabled. Returns false,
* if it is disabled. A disabled control is displayed in a grayed look and
* does not receive focus.
*/
public abstract boolean isEnabled ();
/**
* Sets the enabled-state of this model's widget.
*
* @param what the state to set.
*/
public abstract void setEnabled (boolean what);
/**
* If inError, this method sets the background of the corresponding Control c
* to the error color defined in ComponentClient. If inError is false,
* the background is reset to the default color.
*/
public abstract void setErrorColor(boolean inError);
}