001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013: package org.itsnat.comp;
014:
015: import java.beans.PropertyVetoException;
016: import org.itsnat.comp.ui.ItsNatLabelUI;
017:
018: /**
019: * Is the base interface of label components.
020: *
021: * <p>A label component contains a single object value, this value is rendered
022: * as markup using a special object, the renderer, and may be optionally edited "in place"
023: * using a user defined editor.</p>
024: *
025: * <p>Any change to the internal value is notified with a "value" property change event
026: * and may be vetoed (see {@link #setValue(Object)}. The new value, if accepted, is rendered
027: * as markup.</p>
028: *
029: * <p>This component family is the "componentized" version of {@link org.itsnat.core.domutil.ElementLabel} and
030: * follows a similar philosophy.</p>
031: *
032: * @author Jose Maria Arranz Santamaria
033: */
034: public interface ItsNatLabel extends ItsNatElementComponent {
035: /**
036: * Returns the user interface manager of this component.
037: *
038: * @return the user interface manager.
039: */
040: public ItsNatLabelUI getItsNatLabelUI();
041:
042: /**
043: * Returns the current value.
044: *
045: * @return the current value. The default value is null.
046: */
047: public Object getValue();
048:
049: /**
050: * Sets the value. The new value will be rendered automatically to markup.
051: *
052: * <p>This new value is "voted" before is set firing a <code>java.beans.PropertyChangeEvent</code>
053: * event, with name "value", sent to the listeners registered with {@link ItsNatComponent#addVetoableChangeListener(VetoableChangeListener)}
054: * if some listener does a "veto" (throws a <code>java.beans.PropertyVetoException</code>)
055: * the new value is not set. If finally set the <code>PropertyChangeEvent</code> event
056: * is sent to the listeners registered with
057: * {@link ItsNatComponent#addPropertyChangeListener(java.beans.PropertyChangeListener)}
058: * or {@link ItsNatComponent#addPropertyChangeListener(String,java.beans.PropertyChangeListener)}
059: * with property name "value".
060: * </p>
061: *
062: * @param value value to display (and may be edit).
063: * @throws PropertyVetoException if the new value was vetoed.
064: */
065: public void setValue(Object value) throws PropertyVetoException;
066:
067: /**
068: * Returns the current component renderer. This renderer converts the label value to markup.
069: *
070: * @return the current renderer. By default uses the default renderer ({@link ItsNatComponentManager#createDefaultItsNatLabelRenderer()})
071: * @see #setItsNatLabelRenderer(ItsNatLabelRenderer)
072: */
073: public ItsNatLabelRenderer getItsNatLabelRenderer();
074:
075: /**
076: * Sets the component renderer.
077: *
078: * @param renderer the new renderer.
079: * @see #getItsNatLabelRenderer()
080: */
081: public void setItsNatLabelRenderer(ItsNatLabelRenderer renderer);
082:
083: /**
084: * Returns the current label editor. This object is used to edit in place
085: * the current label value.
086: *
087: * @return the current editor. By default uses the default editor
088: * calling ({@link ItsNatComponentManager#createDefaultItsNatLabelEditor(ItsNatComponent)}) with a null parameter.
089: * @see #setItsNatLabelEditor(ItsNatLabelEditor)
090: */
091: public ItsNatLabelEditor getItsNatLabelEditor();
092:
093: /**
094: * Sets the label editor.
095: *
096: * <p>This component automatically adds a listener calling
097: * <code>javax.swing.CellEditor.addCellEditorListener(javax.swing.event.CellEditorListener)</code>
098: * this way the component is informed when the editor stops or cancels editing.</p>
099: *
100: * <p>The edition process starts programmatically by calling {@link #startEditing()}
101: * or by user action (usually double clicking the label or the action/event type
102: * specified by {@link #getEditorActivatorEvent()}). Then the label markup
103: * (below the parent element) is removed and the method
104: * {@link ItsNatLabelEditor#getLabelEditorComponent(ItsNatLabel,Object,Element)}
105: * is called, this method usually places the editor component inside the label.
106: * Current label implementations do nothing with the editor component returned and may be null.</p>
107: *
108: * <p>When the editor stops the component calls <code>CellEditor.getCellEditorValue()</code>
109: * to obtain the new value and sets this value to the label (calling {@link #setValue(Object)})
110: * and the editor is removed and the original label markup is restored modified by the renderer
111: * with the new value. If the editor is cancelled all is the same but no markup change is made.</p>
112: *
113: * @param editor the new editor. May be null (edition disabled).
114: * @see #getItsNatLabelEditor()
115: */
116: public void setItsNatLabelEditor(ItsNatLabelEditor editor);
117:
118: /**
119: * Used to start programmatically the label edition process "in place".
120: *
121: * @see #isEditing()
122: */
123: public void startEditing();
124:
125: /**
126: * Informs whether the label value is being edited.
127: *
128: * @return true if the label is being edited.
129: *
130: * @see #startEditing()
131: */
132: public boolean isEditing();
133:
134: /**
135: * Returns the event type used to activate the label edition process by the user.
136: *
137: * @return the event type used to activate the edition. By default is "dblclick".
138: * @see #setEditorActivatorEvent(String)
139: */
140: public String getEditorActivatorEvent();
141:
142: /**
143: * Sets the event type used to activate the label edition process by the user.
144: *
145: * @param eventType the event type used to activate the edition.
146: * @see #getEditorActivatorEvent()
147: */
148: public void setEditorActivatorEvent(String eventType);
149: }
|