Package org.eclipse.jface.viewers

Class StructuredViewer

    • Constructor Detail

      • StructuredViewer

        protected StructuredViewer()
        Creates a structured element viewer. The viewer has no input, no content provider, a default label provider, no sorter, and no filters.

    • Method Detail

      • addDoubleClickListener

        public void addDoubleClickListener​(IDoubleClickListener listener)
        Adds a listener for double-clicks in this viewer. Has no effect if an identical listener is already registered.
        Parameters:
        listener - a double-click listener

      • addOpenListener

        public void addOpenListener​(IOpenListener listener)
        Adds a listener for selection-open in this viewer. Has no effect if an identical listener is already registered.
        Parameters:
        listener - an open listener

      • addDragSupport

        public void addDragSupport​(int operations,
                           Transfer[] transferTypes,
                           DragSourceListener listener)
        Adds support for dragging items out of this viewer via a user drag-and-drop operation.
        Parameters:
        operations - a bitwise OR of the supported drag and drop operation types ( DROP_COPY,DROP_LINK, and DROP_MOVE)
        transferTypes - the transfer types that are supported by the drag operation
        listener - the callback that will be invoked to set the drag data and to cleanup after the drag and drop operation finishes
        See Also:
        DND

      • addDropSupport

        public void addDropSupport​(int operations,
                           Transfer[] transferTypes,
                           DropTargetListener listener)
        Adds support for dropping items into this viewer via a user drag-and-drop operation.
        Parameters:
        operations - a bitwise OR of the supported drag and drop operation types ( DROP_COPY,DROP_LINK, and DROP_MOVE)
        transferTypes - the transfer types that are supported by the drop operation
        listener - the callback that will be invoked after the drag and drop operation finishes
        See Also:
        DND

      • assertElementsNotNull

        protected void assertElementsNotNull​(Object... elements)
        Asserts that the given array of elements is itself non- null and contains no null elements.
        Parameters:
        elements - the array to check

      • associate

        protected void associate​(Object element,
                         Item item)
        Associates the given element with the given widget. Sets the given item's data to be the element, and maps the element to the item in the element map (if enabled).
        Parameters:
        element - the element
        item - the widget

      • disassociate

        protected void disassociate​(Item item)
        Disassociates the given SWT item from its corresponding element. Sets the item's data to null and removes the element from the element map (if enabled).
        Parameters:
        item - the widget

      • doFindInputItem

        protected abstract Widget doFindInputItem​(Object element)
        Returns the widget in this viewer's control which represents the given element if it is the viewer's input.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        element - the element to find the representing widget for
        Returns:
        the corresponding widget, or null if none

      • doFindItem

        protected abstract Widget doFindItem​(Object element)
        Returns the widget in this viewer's control which represent the given element. This method searches all the children of the input element.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        element - the element to find the representing widget for
        Returns:
        the corresponding widget, or null if none

      • doUpdateItem

        protected abstract void doUpdateItem​(Widget item,
                                     Object element,
                                     boolean fullMap)
        Copies the attributes of the given element into the given SWT item. The element map is updated according to the value of fullMap. If fullMap is true then the current mapping from element to widgets is removed and the new mapping is added. If full map is false then only the new map gets installed. Installing only the new map is necessary in cases where only the order of elements changes but not the set of elements.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        item - widget item to update
        element - the element to represent
        fullMap - true if mappings are added and removed, and false if only the new map gets installed

      • equals

        protected boolean equals​(Object elementA,
                         Object elementB)
        Compares two elements for equality. Uses the element comparer if one has been set, otherwise uses the default equals method on the elements themselves.
        Parameters:
        elementA - the first element
        elementB - the second element
        Returns:
        whether elementA is equal to elementB

      • filter

        protected Object[] filter​(Object[] elements)
        Returns the result of running the given elements through the filters.
        Parameters:
        elements - the elements to filter
        Returns:
        only the elements which all filters accept

      • findItem

        protected final Widget findItem​(Object element)
        Finds the widget which represents the given element.

        The default implementation of this method tries first to find the widget for the given element assuming that it is the viewer's input; this is done by calling doFindInputItem. If it is not found there, it is looked up in the internal element map provided that this feature has been enabled. If the element map is disabled, the widget is found via doFindInputItem.

        Parameters:
        element - the element
        Returns:
        the corresponding widget, or null if none

      • findItems

        protected final Widget[] findItems​(Object element)
        Finds the widgets which represent the given element. The returned array must not be changed by clients; it might change upon calling other methods on this viewer.

        This method was introduced to support multiple equal elements in a viewer (@see AbstractTreeViewer). Multiple equal elements are only supported if the element map is enabled by calling setUseHashlookup(boolean) and passing true.

        The default implementation of this method tries first to find the widget for the given element assuming that it is the viewer's input; this is done by calling doFindInputItem. If it is not found there, the widgets are looked up in the internal element map provided that this feature has been enabled. If the element map is disabled, the widget is found via doFindItem.

        Parameters:
        element - the element
        Returns:
        the corresponding widgets
        Since:
        3.2

      • fireOpen

        protected void fireOpen​(OpenEvent event)
        Notifies any open event listeners that a open event has been received. Only listeners registered at the time this method is called are notified.
        Parameters:
        event - a double-click event
        See Also:
        IOpenListener.open(OpenEvent)

      • getComparer

        public IElementComparer getComparer()
        Returns the comparer to use for comparing elements, or null if none has been set. If specified, the viewer uses this to compare and hash elements rather than the elements' own equals and hashCode methods.
        Returns:
        the comparer to use for comparing elements or null

      • getFilteredChildren

        protected Object[] getFilteredChildren​(Object parent)
        Returns the filtered array of children of the given element. The resulting array must not be modified, as it may come directly from the model's internal state.
        Parameters:
        parent - the parent element
        Returns:
        a filtered array of child elements

      • getRawChildren

        protected Object[] getRawChildren​(Object parent)
        Returns the children of the given parent without sorting and filtering them. The resulting array must not be modified, as it may come directly from the model's internal state.

        Returns an empty array if the given parent is null.

        Parameters:
        parent - the parent element
        Returns:
        the child elements

      • getRoot

        protected Object getRoot()
        Returns the root element.

        The default implementation of this framework method forwards to getInput. Override if the root element is different from the viewer's input element.

        Returns:
        the root element, or null if none

      • getSelection

        public ISelection getSelection()
        The StructuredViewer implementation of this method returns the result as an IStructuredSelection.

        Call getStructuredSelection() instead to get an instance of IStructuredSelection directly.

        Subclasses do not typically override this method, but implement getSelectionFromWidget(List) instead. If they override this method, they should return an IStructuredSelection as well.
        Specified by:
        getSelection in interface ISelectionProvider
        Specified by:
        getSelection in class Viewer
        Returns:
        ISelection

      • getStructuredSelection

        public IStructuredSelection getStructuredSelection()
                                            throws ClassCastException
        Returns the IStructuredSelection of this viewer.

        Subclasses whose getSelection() specifies to return a more specific type should also override this method and return that type.

        Returns:
        IStructuredSelection
        Throws:
        ClassCastException - if the selection of the viewer is not an instance of IStructuredSelection
        Since:
        3.11

      • getSelectionFromWidget

        protected abstract List getSelectionFromWidget()
        Retrieves the selection, as a List, from the underlying widget.
        Returns:
        the list of selected elements

      • getSortedChildren

        protected Object[] getSortedChildren​(Object parent)
        Returns the sorted and filtered set of children of the given element. The resulting array must not be modified, as it may come directly from the model's internal state.
        Parameters:
        parent - the parent element
        Returns:
        a sorted and filtered array of child elements

      • getSorter

        public ViewerSorter getSorter()
        Returns this viewer's sorter, or null if it does not have one. If this viewer has a comparator that was set via setComparator(ViewerComparator) then this method will return null if the comparator is not an instance of ViewerSorter.

        It is recommended to use getComparator() instead.

        Returns:
        a viewer sorter, or null if none or if the comparator is not an instance of ViewerSorter

      • getComparator

        public ViewerComparator getComparator()
        Return this viewer's comparator used to sort elements. This method should be used instead of getSorter().
        Returns:
        a viewer comparator, or null if none
        Since:
        3.2

      • handleDoubleSelect

        protected void handleDoubleSelect​(SelectionEvent event)
        Handles a double-click select event from the widget.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        event - the SWT selection event

      • handleOpen

        protected void handleOpen​(SelectionEvent event)
        Handles an open event from the OpenStrategy.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        event - the SWT selection event

      • handleInvalidSelection

        protected void handleInvalidSelection​(ISelection invalidSelection,
                                      ISelection newSelection)
        Handles an invalid selection.

        This framework method is called if a model change picked up by a viewer results in an invalid selection. For instance if an element contained in the selection has been removed from the viewer, the viewer is free to either remove the element from the selection or to pick another element as its new selection. The default implementation of this method calls updateSelection. Subclasses may override it to implement a different strategy for picking a new selection when the old selection becomes invalid.

        Parameters:
        invalidSelection - the selection before the viewer was updated
        newSelection - the selection after the update, or null if none

      • handleLabelProviderChanged

        protected void handleLabelProviderChanged​(LabelProviderChangedEvent event)
        The StructuredViewer implementation of this ContentViewer method calls update if the event specifies that the label of a given element has changed, otherwise it calls super. Subclasses may reimplement or extend.
        Overrides:
        handleLabelProviderChanged in class ContentViewer
        Parameters:
        event - the event that generated this update

      • handleSelect

        protected void handleSelect​(SelectionEvent event)
        Handles a select event from the widget.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        event - the SWT selection event

      • handlePostSelect

        protected void handlePostSelect​(SelectionEvent e)
        Handles a post select event from the widget.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        e - the SWT selection event

      • hookControl

        protected void hookControl​(Control control)
        Description copied from class: ContentViewer
        Adds event listener hooks to the given control.

        All subclasses must call this method when their control is first established.

        The ContentViewer implementation of this method hooks dispose events for the given control. Subclasses may override if they need to add other control hooks; however, super.hookControl must be invoked.

        Overrides:
        hookControl in class ContentViewer
        Parameters:
        control - the control

      • hasFilters

        protected boolean hasFilters()
        Returns whether this viewer has any filters.
        Returns:
        boolean

      • internalRefresh

        protected abstract void internalRefresh​(Object element)
        Refreshes this viewer starting at the given element.
        Parameters:
        element - the element

      • internalRefresh

        protected void internalRefresh​(Object element,
                               boolean updateLabels)
        Refreshes this viewer starting at the given element. Labels are updated as described in refresh(boolean updateLabels).

        The default implementation simply calls internalRefresh(element), ignoring updateLabels.

        If this method is overridden to do the actual refresh, then internalRefresh(Object element) should simply call internalRefresh(element, true).

        Parameters:
        element - the element
        updateLabels - true to update labels for existing elements, false to only update labels as needed, assuming that labels for existing elements are unchanged.
        Since:
        2.0

      • mapElement

        protected void mapElement​(Object element,
                          Widget item)
        Adds the element item pair to the element map.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        element - the element
        item - the corresponding widget

      • needsRefilter

        protected boolean needsRefilter​(Object element,
                                String property)
        Determines whether a change to the given property of the given element would require refiltering and/or resorting.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        element - the element
        property - the property
        Returns:
        true if refiltering is required, and false otherwise

      • preservingSelection

        protected void preservingSelection​(Runnable updateCode)
        Attempts to preserves the current selection across a run of the given code. This method should not preserve the selection if {link #getPreserveSelection()} returns false.

        The default implementation of this method:

        • discovers the old selection (via getSelection)
        • runs the given runnable
        • attempts to restore the old selection (using setSelectionToWidget
        • rediscovers the resulting selection (via getSelection)
        • calls handleInvalidSelection if the resulting selection is different from the old selection
        Parameters:
        updateCode - the code to run see #getPreserveSelection()

      • refresh

        public void refresh()
        Description copied from class: Viewer
        Refreshes this viewer completely with information freshly obtained from this viewer's model.
        Specified by:
        refresh in class Viewer

      • refresh

        public void refresh​(boolean updateLabels)
        Refreshes this viewer with information freshly obtained from this viewer's model. If updateLabels is true then labels for otherwise unaffected elements are updated as well. Otherwise, it assumes labels for existing elements are unchanged, and labels are only obtained as needed (for example, for new elements).

        Calling refresh(true) has the same effect as refresh().

        Note that the implementation may still obtain labels for existing elements even if updateLabels is false. The intent is simply to allow optimization where possible.

        Parameters:
        updateLabels - true to update labels for existing elements, false to only update labels as needed, assuming that labels for existing elements are unchanged.
        Since:
        2.0

      • refresh

        public void refresh​(Object element)
        Refreshes this viewer starting with the given element.

        Unlike the update methods, this handles structural changes to the given element (e.g. addition or removal of children). If only the given element needs updating, it is more efficient to use the update methods.

        Parameters:
        element - the element

      • refresh

        public void refresh​(Object element,
                    boolean updateLabels)
        Refreshes this viewer starting with the given element. Labels are updated as described in refresh(boolean updateLabels).

        Unlike the update methods, this handles structural changes to the given element (e.g. addition or removal of children). If only the given element needs updating, it is more efficient to use the update methods.

        Parameters:
        element - the element
        updateLabels - true to update labels for existing elements, false to only update labels as needed, assuming that labels for existing elements are unchanged.
        Since:
        2.0

      • refreshItem

        protected final void refreshItem​(Widget widget,
                                 Object element)
        Refreshes the given item with the given element. Calls doUpdateItem(..., false).

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        widget - the widget
        element - the element

      • removeOpenListener

        public void removeOpenListener​(IOpenListener listener)
        Removes the given open listener from this viewer. Has no effect if an identical listener is not registered.
        Parameters:
        listener - an open listener

      • removeDoubleClickListener

        public void removeDoubleClickListener​(IDoubleClickListener listener)
        Removes the given double-click listener from this viewer. Has no effect if an identical listener is not registered.
        Parameters:
        listener - a double-click listener

      • removeFilter

        public void removeFilter​(ViewerFilter filter)
        Removes the given filter from this viewer, and triggers refiltering and resorting of the elements if required. Has no effect if the identical filter is not registered. If you want to remove more than one filter consider using setFilters(ViewerFilter...).
        Parameters:
        filter - a viewer filter
        See Also:
        setFilters(ViewerFilter...)

      • setFilters

        public void setFilters​(ViewerFilter... filters)
        Sets the filters, replacing any previous filters, and triggers refiltering and resorting of the elements.
        Parameters:
        filters - an varargs of viewer filters
        Since:
        3.3

      • resetFilters

        public void resetFilters()
        Discards this viewer's filters and triggers refiltering and resorting of the elements.

      • reveal

        public abstract void reveal​(Object element)
        Ensures that the given element is visible, scrolling the viewer if necessary. The selection is unchanged.
        Parameters:
        element - the element to reveal

      • assertContentProviderType

        protected void assertContentProviderType​(IContentProvider provider)
        Assert that the content provider is of one of the supported types.
        Parameters:
        provider - content provider to check

      • setInput

        public final void setInput​(Object input)
        Description copied from class: ContentViewer
        The ContentViewer implementation of this Viewer method invokes inputChanged on the content provider and then the inputChanged hook method. This method fails if this viewer does not have a content provider. Subclassers are advised to override inputChanged rather than this method, but may extend this method if required.
        Overrides:
        setInput in class ContentViewer
        Parameters:
        input - the input of this viewer, or null if none

      • setSelection

        public void setSelection​(ISelection selection,
                         boolean reveal)
        Description copied from class: Viewer
        Sets a new selection for this viewer and optionally makes it visible.

        Subclasses must implement this method.

        Specified by:
        setSelection in class Viewer
        Parameters:
        selection - the new selection
        reveal - true if the selection is to be made visible, and false otherwise

      • setSelectionToWidget

        protected abstract void setSelectionToWidget​(List l,
                                             boolean reveal)
        Parlays the given list of selected elements into selections on this viewer's control.

        Subclasses should override to set their selection based on the given list of elements.

        Parameters:
        l - list of selected elements (element type: Object) or null if the selection is to be cleared
        reveal - true if the selection is to be made visible, and false otherwise

      • setSelectionToWidget

        protected void setSelectionToWidget​(ISelection selection,
                                    boolean reveal)
        Converts the selection to a List and calls setSelectionToWidget(List, boolean). The selection is expected to be an IStructuredSelection of elements. If not, the selection is cleared.

        Subclasses do not typically override this method, but implement setSelectionToWidget(List, boolean) instead.

        Parameters:
        selection - an IStructuredSelection of elements
        reveal - true to reveal the first element in the selection, or false otherwise

      • setSorter

        @Deprecated
public void setSorter​(ViewerSorter sorter)
        Deprecated.
        use setComparator() instead.

        Sets this viewer's sorter and triggers refiltering and resorting of this viewer's element. Passing null turns sorting off.

        Parameters:
        sorter - a viewer sorter, or null if none

      • setComparator

        public void setComparator​(ViewerComparator comparator)
        Sets this viewer's comparator to be used for sorting elements, and triggers refiltering and resorting of this viewer's element. null turns sorting off. To get the viewer's comparator, call getComparator().

        IMPORTANT: This method was introduced in 3.2. If a reference to this viewer object is passed to clients who call getSorter(), null may be returned from from that method even though the viewer is sorting its elements using the viewer's comparator.

        Parameters:
        comparator - a viewer comparator, or null if none
        Since:
        3.2

      • setUseHashlookup

        public void setUseHashlookup​(boolean enable)
        Configures whether this structured viewer uses an internal hash table to speed up the mapping between elements and SWT items. This must be called before the viewer is given an input (via setInput).

        Note: enabling hash lookup requires from client code that elements managed by the viewer properly implement Object.hashCode() and Object.equals(Object) and that equal elements are not added to the same parent in the tree (each equal element should have a different parent chain).

        Parameters:
        enable - true to enable hash lookup, and false to disable it

      • setComparer

        public void setComparer​(IElementComparer comparer)
        Sets the comparer to use for comparing elements, or null to use the default equals and hashCode methods on the elements themselves.
        Parameters:
        comparer - the comparer to use for comparing elements or null

      • testFindItem

        public Widget testFindItem​(Object element)
        Hook for testing.
        Parameters:
        element - the element
        Returns:
        the corresponding widget, or null if none

      • testFindItems

        public Widget[] testFindItems​(Object element)
        Hook for testing.
        Parameters:
        element - the element
        Returns:
        the corresponding widgets
        Since:
        3.2

      • unmapAllElements

        protected void unmapAllElements()
        Removes all elements from the map.

        This method is internal to the framework; subclassers should not call this method.

      • unmapElement

        protected void unmapElement​(Object element)
        Removes the given element from the internal element to widget map. Does nothing if mapping is disabled. If mapping is enabled, the given element must be present.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        element - the element

      • unmapElement

        protected void unmapElement​(Object element,
                            Widget item)
        Removes the given association from the internal element to widget map. Does nothing if mapping is disabled, or if the given element does not map to the given item.

        This method is internal to the framework; subclassers should not call this method.

        Parameters:
        element - the element
        item - the item to unmap
        Since:
        2.0

      • update

        public void update​(Object[] elements,
                   String[] properties)
        Updates the given elements' presentation when one or more of their properties change. Only the given elements are updated.

        This does not handle structural changes (e.g. addition or removal of elements), and does not update any other related elements (e.g. child elements). To handle structural changes, use the refresh methods instead.

        This should be called when an element has changed in the model, in order to have the viewer accurately reflect the model. This method only affects the viewer, not the model.

        Specifying which properties are affected may allow the viewer to optimize the update. For example, if the label provider is not affected by changes to any of these properties, an update may not actually be required. Specifying properties as null forces a full update of the given elements.

        If the viewer has a sorter which is affected by a change to one of the properties, the elements' positions are updated to maintain the sort order. Note that resorting may not happen if properties is null.

        If the viewer has a filter which is affected by a change to one of the properties, elements may appear or disappear if the change affects whether or not they are filtered out. Note that resorting may not happen if properties is null.

        Parameters:
        elements - the elements
        properties - the properties that have changed, or null to indicate unknown

      • update

        public void update​(Object element,
                   String[] properties)
        Updates the given element's presentation when one or more of its properties changes. Only the given element is updated.

        This does not handle structural changes (e.g. addition or removal of elements), and does not update any other related elements (e.g. child elements). To handle structural changes, use the refresh methods instead.

        This should be called when an element has changed in the model, in order to have the viewer accurately reflect the model. This method only affects the viewer, not the model.

        Specifying which properties are affected may allow the viewer to optimize the update. For example, if the label provider is not affected by changes to any of these properties, an update may not actually be required. Specifying properties as null forces a full update of the element.

        If the viewer has a sorter which is affected by a change to one of the properties, the element's position is updated to maintain the sort order. Note that resorting may not happen if properties is null.

        If the viewer has a filter which is affected by a change to one of the properties, the element may appear or disappear if the change affects whether or not the element is filtered out. Note that filtering may not happen if properties is null.

        Parameters:
        element - the element
        properties - the properties that have changed, or null to indicate unknown

      • internalUpdate

        protected void internalUpdate​(Widget widget,
                              Object element,
                              String[] properties)
        Updates the given element's presentation when one or more of its properties changes. Only the given element is updated.

        EXPERIMENTAL. Not to be used except by JDT. This method was added to support JDT's explorations into grouping by working sets, which requires viewers to support multiple equal elements. See bug 76482 for more details. This support will likely be removed in Eclipse 3.3 in favor of proper support for multiple equal elements (which was implemented for AbtractTreeViewer in 3.2).

        Parameters:
        widget - the widget for the element
        element - the element
        properties - the properties that have changed, or null to indicate unknown

      • updateItem

        protected final void updateItem​(Widget widget,
                                Object element)
        Copies attributes of the given element into the given widget.

        This method is internal to the framework; subclassers should not call this method. Calls doUpdateItem(widget, element, true).

        Parameters:
        widget - the widget
        element - the element

      • updateSelection

        protected void updateSelection​(ISelection selection)
        Updates the selection of this viewer.

        This framework method should be called when the selection in the viewer widget changes.

        The default implementation of this method notifies all selection change listeners recorded in an internal state variable. Overriding this method is generally not required; however, if overriding in a subclass, super.updateSelection must be invoked.

        Parameters:
        selection - the selection, or null if none

      • usingElementMap

        protected boolean usingElementMap()
        Returns whether this structured viewer is configured to use an internal map to speed up the mapping between elements and SWT items.

        The default implementation of this framework method checks whether the internal map has been initialized.

        Returns:
        true if the element map is enabled, and false if disabled

      • setLabelProvider

        public void setLabelProvider​(IBaseLabelProvider labelProvider)
        Description copied from class: ContentViewer
        Sets the label provider for this viewer.

        The ContentViewer implementation of this method ensures that the given label provider is connected to this viewer and the former label provider is disconnected from this viewer. Overriding this method is generally not required; however, if overriding in a subclass, super.setLabelProvider must be invoked.

        Overrides:
        setLabelProvider in class ContentViewer
        Parameters:
        labelProvider - the label provider, or null if none

      • buildLabel

        protected void buildLabel​(ViewerLabel updateLabel,
                          Object element)
        Build a label up for the element using the supplied label provider.
        Parameters:
        updateLabel - The ViewerLabel to collect the result in
        element - The element being decorated.

      • getColorAndFontCollector

        protected StructuredViewer.ColorAndFontCollector getColorAndFontCollector()
        Get the ColorAndFontCollector for the receiver.
        Returns:
        ColorAndFontCollector
        Since:
        3.1

      • handleDispose

        protected void handleDispose​(DisposeEvent event)
        Description copied from class: ContentViewer
        Handles a dispose event on this viewer's control.

        The ContentViewer implementation of this method disposes of this viewer's label provider and content provider (if it has one). Subclasses should override this method to perform any additional cleanup of resources; however, overriding methods must invoke super.handleDispose.

        Overrides:
        handleDispose in class ContentViewer
        Parameters:
        event - a dispose event