Startseite / Plugin-Entwicklung / Universelle Erweiterungen / Eingabekomponenten / SiteArchitect / Swing-Gadget-Aspekte
Swing Gadget Aspects
Gadget aspects extend the functional abilities of an input component within SiteArchitect's user interface and interaction scheme.
For example, an input component may
- implement the functionality of the aspect Editable to support SiteArchitect's edit mode handling,
- implement the aspect DifferenceVisualizing to support highlighting of the input component's value in a comparison view if that value has changed between two store element revisions, or
- provide the abilities to supply or accept data via drag-and-drop by implementing the aspects TransferSupplying or TransferHandling, respectively.
Providing Aspects
The aspect provisioning process differs depending on the Swing gadget class' implementation style:
- Direct implementation of SwingGadget:
A method getAspect(...) must be implemented and provide an object which implements the requested aspect if available. - Extension of the abstract class AbstractValueHoldingSwingGadget:
The method getAspect(...) is already implemented in the abstract class and cannot be overridden. The abstract class provides a method addAspect(...) through which aspect implementations may be registered.
SiteArchitect occasionally calls the method getAspect(...) with various aspect types as a parameter to identify which input components support a given aspect. If the Swing gadget supports the requested aspect, the method should return an object which implements that aspect; otherwise, it should return null.
Gadget Implementations Using SwingGadget
The Swing gadget class must implement functionality to register aspects whose functionality should be made available in SiteArchitect and to return an appropriate aspect implementation object as requested.
In order to keep track of registered aspects, it is highly recommended that the class AspectMap, available in the FirstSpirit Access API, be used, as it ensures safe aspect mapping.
In order to provide available aspects to SiteArchitect, the gadget base interface SwingGadget extends the interface Aspectable, which defines the method <T> T getAspect(AspectType<T> aspect). If the input component's Swing gadget is to support the aspect type given as a parameter, the method must return an object implementing the associated aspect.
For example, the following code sample defines a Swing gadget class named ExampleComponentSwingGadget which directly implements the aspect Editable and also supports the aspect ValueHolder, which is implemented by a separate class named ExampleComponentValueHolderAspect.
public ExampleComponentSwingGadget implements SwingGadget, Editable {
private final AspectMap _aspects;
public ExampleComponentSwingGadget() {
// In this example, the SwingGadget implementation implements Editable directly.
// Register a reference to this object itself for that aspect.
_aspects.put(Editable.TYPE, this);
// In this example, the aspect ValueHolder<T> is implemented by a separate class.
// Instantiate and register an object of that type.
_aspects.put(ValueHolder.TYPE, new ExampleComponentValueHolderAspect());
}
// Implement the method getAspect(...) of the interface Aspectable,
// which SwingGadget extends.
public <A> A getAspect(final AspectType<A> type) {
// Return the object implementing the requested aspect, if one has been registered.
// If no object registered for the aspect type is available, the map object will return
// "null", and SiteArchitect will not attempt to use that aspect's functionality for
// the input component.
return _aspects.get(type);
}
// ...
}
Gadget Implementations Using AbstractValueHoldingSwingGadget
The abstract class AbstractValueHoldingSwingGadget already implements methods to safely map aspect objects and to provide them to SiteArchitect. A Swing gadget class which extends this abstract class simply needs to implement aspect interfaces by itself or instantiate an object of a separate type which implements a desired aspect and call the method addAspect(AspectType<A> type, A aspect) in order to register the aspect object of the given type.
Gadget Aspects by Category
Swing Gadget Aspects | ||
---|---|---|
Appearance | ||
Aspect | Description | Methods / Notes |
Indicates that the input component supports display of a label in the form view. | String getLabel() | |
Indicates that the input component may be drawn in a single-line layout without a header bar. In a single-line layout, the optional label (see Labelable) will be drawn to the left of the input component's UI. | boolean isSingleLine() | |
In a single-line layout, this aspect indicates if the component's label should be hidden. | boolean isLabelHiding() | |
Provides means to increase or decrease the height of the input component's viewport in form views. | The aspect interface does not define methods. | |
Indicates that the input component's UI has a fixed width which should not be changed by SiteArchitect. | boolean isWidthFixed() | |
Indicates if the input component's Swing UI may be shown in an external window. | The aspect interface does not define methods. | |
Indicates that the input component may be hidden. | boolean shallInitiallyBeShown() | |
Enables a Swing gadget to suggest a suitable inner Swing component to focus on when the Swing gadget receives focus. | void acceptFocus(SwingFocusable.Handler handler) | |
Allows an input component to react to display changes caused by language switching, e.g. replace label texts to observe the new display language. | void onDisplayLanguageChange() | |
Editing and storing component values | ||
Aspect | Description | Methods / Notes |
Controls whether the input component is editable or not. | void setEditable(boolean editable) | |
Enables storing the component's data using FirstSpirit's persistence functionality and retrieving such data for display in the component. | T getValue() | |
Allows an input component to manage changes to its component value, instructing SiteArchitect to let the component's aspect implementation handle change identification itself (instead of SiteArchitect functionality conducting a currentValue.equals(oldValue) comparison on persistence data) as well as setting and clearing the component's value. | boolean hasChanges() | |
Allows likening of a Swing gadget's current value to another, given value, suppressing SiteArchitect's .equals() comparison on persistence data. | boolean likenTo(T value) | |
Provides a means for the input component's code to validate the component's value before it is saved. This aspect's code may identify a list of problems with can be displayed to the user. | Set<? extends Problem> validateIntegrity() | |
Rules and Validation | ||
Aspect | Description | Methods / Notes |
Allows the gadget to define properties (in addition to the set of default properties) which may be read and set using Rules. | Object getProperty(String name) | |
Data Visualization | ||
Aspect | Description | Methods / Notes |
Handles visualization of difference markers (e.g. sets background colors of text sequences which were changed, added, or deleted between two compared revision values of the input component) in the Swing gadget's user interface components. This aspect may be used in the version comparison dialog when two revisions of a store element are compared. | void visualizeDifferences(List<Difference> differences) | |
Highlights text sequences in the Swing gadget's user interface components. | boolean highlightSequences(String regExp) | |
Drag and drop | ||
Aspect | Description | Methods / Notes |
Enables a Swing gadget to supply transfer data for drag and drop operations. | ||
Allows a Swing gadget to check if the transfer data in an ongoing drag and drop operation contains any data that can be processed by the gadget. The gadget can then accept or reject the given drop data, marking the gadget as a valid or invalid drop target, respectively. | ||
This aspect enables a Swing gadget to receive transfer data of a drag and drop operation completed by a drop action on this gadget, allowing it to process that data. | ||