Class AbstractViewer

Object
   |
   +--AbstractViewer

Direct Known Subclasses:

TreeViewer, TableViewer, ListViewer

class AbstractViewer

Defined in abstract_viewer.js

Constructor Detail

AbstractViewer

function AbstractViewer(<LabelProvider> labelProvider, <ContentProvider> contentProvider, <Widget> widget, <Array> events, <ViewerSorter> sorter, menuProvider)

AbstractViewer is an abstract base class for viewers. Viewers are part of a model-view-controller paradigm. ContentProviders are a façade to the model part of the paradigm, and viewers implement the view and part of the controller. Viewers essentially serve to translate back and forth between the domain objects provided by the ContentProvider and the Widgets used to display them. Viewers use their LabelProvider to translate the domain objects provided by their ContentProvider into text and icons to be displayed to the user. The text and icons are displayed in the Widget that is governed by the viewer. The viewer listens to events generated by the content provider to keep its widget up to date (ie. as domain objects are added to and removed from the model, the content provider fires events to notify the viewer and the viewer translates these model changes into widget changes by either adding or removing widgets from the container it is governing). The viewer also listens to widget-based events, such as selection changes and clicks, and generates analogous events but with the arguments converted from widgets to domain objects. For example, if the user clicks on a Table that is being governed by a TableViewer, the table generates a selectionchanged event and the selection is presented in terms of TableRow widgets. The viewer will trap this widget-based event and, in response, generate its own selectionchanged event with the selection expressed in terms of the domain objects that are being displayed in the selected rows. In this way, the programmer can forget about constructing the underlying widgets and translating between those widgets and the domain objects. Instead, the programmer can think exclusively in terms of domain objects, which hopefully simplies the design. Also, although each viewer should have its own instance of a given content provider, it should be possible to use the same content provider class (or label provider class) for two different viewers (for example a ListViewer for an overview of the data, and a TableViewer for more detail), thus reducing code duplication and reducing the chance of error.

Parameters:
labelProvider - the label provider to use
contentProvider - the content provider to use
widget - the widget that will display the contents of the model
events - a list of event names that this viewer can generate
sorter - (Optional) - the sorter for this viewer. Defaults to a default instance of ViewerSorter.

addEventListener

void addEventListener(<string> event, <Function> listener)

Adds an event listener to this viewer's listener list. Does nothing if listener is already registered for events named event.

Parameters:
event - the name of the event to listen for
listener - a function to be called when an event named event is raised

findNext

Object findNext(<Function> pred, <Object> startAt, <boolean> wrap)

Searches the viewer for the next object after startAt for which pred returns true. If wrap is true and there are no such objects after startAt, then the first matching object in the viewer is returned (ie. the search wraps around to the beginning again).

Parameters:
pred - a function that determines the search results. pred should accept an instance of the viewer's domain objects as its only argument. It should return true if its argument matches the search criteria and false otherwise.
startAt - (Optional) - an object in the viewer at which to start the search. If startAt is null, the search starts at the beginning of the viewer. Defaults to null.
wrap - (Optional) - if wrap is true then the search will wrap around to the beginning of the viewer if no objects after startAt cause pred to return true. If wrap is false, the search stops at the end of the viewer. Defaults to false.

Returns:
the first matching object, or null if there is no such object

findPrev

Object findPrev(<Function> pred, <Object> startAt, <boolean> wrap)

Searches the viewer for the previous object before startAt for which pred returns true. If wrap is true and there are no such objects before startAt, then the last matching object in the viewer is returned (ie. the search wraps around to the end again).

Parameters:
pred - a function that determines the search results. pred should accept an instance of the viewer's domain objects as its only argument. It should return true if its argument matches the search criteria and false otherwise.
startAt - (Optional) - an object in the viewer at which to start the search. If startAt is null, the search starts at the end of the viewer. Defaults to null.
wrap - (Optional) - if wrap is true then the search will wrap around to the end of the viewer if no objects before startAt cause pred to return true. If wrap is false, the search stops at the beginning of the viewer. Defaults to false.

Returns:
the first matching object, or null if there is no such object

getAssociatedObject

Object getAssociatedObject(<Widget> widget)

Gets the domain object associated with the given Widget.

Parameters:
widget - the Widget to search for

Returns:
the domain object associated with widget

getAssociatedWidget

Widget getAssociatedWidget(<Object> object)

Gets the Widget associated with object. Note: if object is null or undefined, then the returned value is this.getWidget().

Parameters:
object - the domain object to search for

Returns:
the Widget displaying a value for object

getContentProvider

ContentProvider getContentProvider()

Returns the ContentProvider associated with this viewer.

Returns:
this viewer's ContentProvider

getLabelProvider

LabelProvider getLabelProvider()

Returns the LabelProvider associated with this viewer.

Returns:
this viewer's LabelProvider

getMenuProvider

MenuProvider getMenuProvider()

getSelection

AbstractList getSelection()

Returns the viewer's selection as an AbstractList of domain objects. This method queries the underlying Widget for its selection and converts each selected Widget to its corresponding domain object.

Returns:
the viewer's selection

getSorter

ViewerSorter getSorter()

getWidget

Widget getWidget()

Returns the Widget displaying this viewer's contents.

Returns:
this viewer's Widget

removeEventListener

void removeEventListener(<string> event, <Function> listener)

Removes an event listener from this viewer's listener list. Does nothing if listener is not registered for events named event.

Parameters:
event - the name of the event to stop listening for
listener - a function registered for events named event

selectNext

void selectNext(<Function> pred, <boolean> wrap)

Selects the next item in the viewer (after the tail of the current selection) that matches the given predicate, and then selects it. If there are no elements in the viewer that match the predicate, or if wrap is false and there are no matching elements after the current selection, then the viewer's selection will be cleared.

Parameters:
pred - a function accepting domain objects and returning true or false. Return true to select that object, or false to continue searching.
wrap - (Optional) - if wrap is true, then the search will wrap at the end of the list and start searching again at the top. If wrap is false, the search will stop at the end of the list. Defaults to false.

selectPrev

void selectPrev(<Function> pred, <boolean> wrap)

Selects the previous item in the viewer (before the head of the current selection) that matches the given predicate, and then selects it. If there are no elements in the viewer that match the predicate, or if wrap is false and there are no matching elements before the current selection, then the viewer's selection will be cleared.

Parameters:
pred - a function accepting domain objects and returning true or false. Return true to select that object, or false to continue searching.
wrap - (Optional) - if wrap is true, then the search will wrap at the beginning of the list and start searching again at the bottom. If wrap is false, the search will stop at the beginning of the list. Defaults to false.

setSelection

void setSelection(<Object> objectSelection)

Sets the viewer's selection to match objectSelection. objectSelection can be an Array, an AbstractList, or a plain object. If objectSelection is either an array or a list, then each element will be selected. If objectSelection is a single object then that item will be selected. If objectSelection is null, undefined, or not provided then the viewer's selection is set to empty.

Note: Although setSelection is forgiving about what it accepts as arguments, limitations in certain browsers make it difficult to be sure about the type of object that is passed in. If you run into problems with this method and you are passing a single object, try wrapping the argument in an anonymous array as follows: viewer.setSelection([arg]); and see if it solves your problem.

Parameters:
objectSelection - an indication of what objects to select

setSorter

void setSorter(<ViewerSorter> newSorter, <boolean> forceResort)

Sets this viewer's sorter to be newSorter. If newSorter is different from the existing sorter then the elements in the viewer will be resorted according to the new sorter.

Parameters:
newSorter - a ViewerSorter to start using
forceResort - (Optional) - a boolean to indicate whether or not to force a re-sort. If forceResort is false, then the widgets will only be re-sorted if newSorter is different from the existing sorter. Defaults to false.