Selena Selector Framework

Selector framework provide access to different selectors that are used to select some objects and (optionally) transform them to specified class. For example there may be selector that allows user to select files in tree control and transform them to urls (create URL objects that refer to selected files).

Using selector

In order to use selector one should retrieve selector factory and ask it for selector for specified SWT shell. Selector factories are registered in their plugin descriptors and loaded by selector plugin. Here is an example how to register selector factory:

<extension

point="com.togethersoft.selena.selector.factory">

<factory

class="com.mycompany.MySelectorFactory"

id="MySelector">

</factory>

</extension>

In this example class com.mycompany.MySelectorFactory must implement interface SelectorFactory. SelectorPlugin can be asked for all registered selector factories or selector factory with specified id. Now, when we have selector factory, we can ask it to create selector instance – object that implements Selector interface. Selector instance should be treated as a dialog, though it may not be. By thinking of it as of dialog one write code as he or she used to write for dialogs so reusing this paradigm. Selector interface declares method open() that is called to initiate selection process (open dialog and wait until user press OK). After this one can ask whether for selected objects whether for result of transformation of selected objects to some class.

In order to add more value to selector framework there exists generic implementation of selector based on jface dialog. It has two viewers (left one with available objects and right one with selected objects) and buttons ‘Add’, ‘Remove’, ‘Remove All’ between them. It’s factory can be retrieved using SelectorPlugin.getDefaultSelectorFactory(). In most cases it is advisable to use this default selector since it is used by other components of Selena and thus heavily tested.

Source providers

Originally source providers were designed specially for default selector, but they can also be used by other selectors. As the name implies source providers are used to feed selector with objects available for selection. They are registered in their plugin descriptors almost as selector factories:

<extension

point="com.togethersoft.selena.selector.provider">

<provider

name="My Objects"

class="com.mycompany.MySourceProvider"

id="MyObjects">

</provider>

</extension>

Attribute ‘name’ is a label that can be displayed in selector controls to distinguish objects source. Source providers can be retrieved from SelectorPlugin by id or enumerated. The essence of source provider is a jface ContentViewer that holds source objects; source provider should be able to create it for specified Composite and install IDoubleClickListener. Source provider also may support transformation to some class; in this case it should provide Transformer and custom ILabelProvider for transformed objects. Transformer should be distinguished from IAdapteble – while IAdaptable interface should be implemented by objects that may be adapted and thus it is object-centric, Transformer is tied to some class and knows how to transform different objects to this class so it is target-class-centric.

Customizing selector

Selector factory can be asked for customized instance of selector by passing customizer object in method getSelector(Shell shell, Object customizer). Each selector expect their own customizer so it is an Object. Default selector expect implementation of DefaultSelectorCustomizer; generic implementation of this interface is GenericDefaultSelectorCustomizer.

Interesting feature of DefaultSelctorCustomizer that can be reused in other selectors is acceptors. There is an interface named Acceptor that is used to filter chousen objects before selecting them. GenericDefaultSelectorCustomizer can use multiple acceptors to filter objects; each installed acceptor will throw away objects that should not go into selection.