Package org.apache.pivot.wtk

Class ListView

    • Constructor Detail

      • ListView

        public ListView()
        Creates a list view populated with an empty array list.

      • ListView

        public ListView​(List<?> listData)
        Creates a list view populated with the given list data.

        Note that the default renderer uses (as last option) the toString method on list elements, so override it to return whatever you want to display in the ListView, or implement your own custom renderer.

        Parameters:
        listData - The data to set.
        See Also:
        ListViewItemRenderer

    • Method Detail

      • getListData

        public List<?> getListData()
        Returns the list data.
        Returns:
        The data currently presented by the list view.

      • setListData

        public void setListData​(List<?> listData)
        Sets the list data.
        Parameters:
        listData - The data to be presented by the list view.
        Throws:
        java.lang.IllegalArgumentException - if the list data is null.

      • setListData

        public final void setListData​(java.lang.String listData)
        Sets the list data.
        Parameters:
        listData - A JSON string (must begin with [ and end with ]) denoting the data to be presented by the list view.
        Throws:
        java.lang.IllegalArgumentException - if the list data argument is null or cannot be parsed into a list of items.

      • setListData

        public void setListData​(java.net.URL listData)
        Sets the list data.
        Parameters:
        listData - A URL referring to a JSON file containing the data to be presented by the list view.
        Throws:
        java.lang.IllegalArgumentException - if the list data URL is null or if there is any kind of error trying to retrieve the list data from that location.

      • setSkin

        protected void setSkin​(Skin skin)
        Description copied from class: Component
        Sets the skin, replacing any previous skin.
        Overrides:
        setSkin in class Component
        Parameters:
        skin - The new skin.

      • getItemRenderer

        public ListView.ItemRenderer getItemRenderer()
        Returns:
        The item renderer used for items in this list.

      • setItemRenderer

        public void setItemRenderer​(ListView.ItemRenderer itemRenderer)
        Sets the item renderer to be used for items in this list.
        Parameters:
        itemRenderer - The item renderer for the list.
        Throws:
        java.lang.IllegalArgumentException - if the renderer given is null.

      • getItemEditor

        public ListView.ItemEditor getItemEditor()
        Returns the editor used to edit items in this list.
        Returns:
        The item editor, or null if no editor is installed.

      • setItemEditor

        public void setItemEditor​(ListView.ItemEditor itemEditor)
        Sets the editor used to edit items in this list.
        Parameters:
        itemEditor - The item editor for the list.

      • getSelectedIndex

        public int getSelectedIndex()
        Returns the currently selected index, even when in multi-select mode.
        Returns:
        The currently selected index.

      • setSelectedIndex

        public void setSelectedIndex​(int index)
        Sets the selection to a single index.
        Parameters:
        index - The index to select, or -1 to clear the selection.

      • setSelectedRange

        public void setSelectedRange​(int start,
                             int end)
        Sets the selection to a single range.
        Parameters:
        start - The beginning of the single selection.
        end - The end of the selection.

      • getSelectedRanges

        public ImmutableList<Span> getSelectedRanges()
        Returns the currently selected ranges.
        Returns:
        An immutable list containing the currently selected ranges. Note that the returned list is a wrapper around the actual selection, not a copy. Any changes made to the selection state will be reflected in the list, but events will not be fired.

      • setSelectedRanges

        public Sequence<Span> setSelectedRanges​(Sequence<Span> selectedRanges)
        Sets the selection to the given range sequence. Any overlapping or connecting ranges will be consolidated, and the resulting selection will be sorted in ascending order.
        Parameters:
        selectedRanges - The new set of selected ranges.
        Returns:
        The ranges that were actually set.
        Throws:
        java.lang.IllegalArgumentException - if the ranges argument is null or if any of the individual range elements is null.

      • setSelectedRanges

        public final Sequence<Span> setSelectedRanges​(java.lang.String selectedRanges)
        Sets the selection to the given range sequence.
        Parameters:
        selectedRanges - A JSON-formatted string containing the ranges to select.
        Returns:
        The ranges that were actually set.
        Throws:
        java.lang.IllegalArgumentException - if the range string is null or if it can't be parsed as a JSON list.
        java.lang.IllegalArgumentException - if the input string is null or if the value cannot be parsed correctly to a range specification.
        See Also:
        setSelectedRanges(Sequence)

      • getFirstSelectedIndex

        public int getFirstSelectedIndex()
        Returns the first selected index.
        Returns:
        The first selected index, or -1 if nothing is selected.

      • getLastSelectedIndex

        public int getLastSelectedIndex()
        Returns the last selected index.
        Returns:
        The last selected index, or -1 if nothing is selected.

      • addSelectedIndex

        public boolean addSelectedIndex​(int index)
        Adds a single index to the selection.
        Parameters:
        index - The index to add.
        Returns:
        true if the index was added to the selection; false, otherwise.

      • addSelectedRange

        public Sequence<Span> addSelectedRange​(int start,
                                       int end)
        Adds a range of indexes to the selection.
        Parameters:
        start - The first index in the range.
        end - The last index in the range.
        Returns:
        The ranges that were added to the selection.
        Throws:
        java.lang.IllegalStateException - if the ListView is not in multi-selection mode.

      • addSelectedRange

        public Sequence<Span> addSelectedRange​(Span range)
        Adds a range of indexes to the selection.
        Parameters:
        range - The range to add.
        Returns:
        The ranges that were added to the selection.
        Throws:
        java.lang.IllegalArgumentException - if the range is null.

      • removeSelectedIndex

        public boolean removeSelectedIndex​(int index)
        Removes a single index from the selection.
        Parameters:
        index - The index to remove.
        Returns:
        true if the index was removed from the selection; false, otherwise.

      • removeSelectedRange

        public Sequence<Span> removeSelectedRange​(int start,
                                          int end)
        Removes a range of indexes from the selection.
        Parameters:
        start - The start of the range to remove.
        end - The end of the range to remove.
        Returns:
        The ranges that were removed from the selection.
        Throws:
        java.lang.IllegalStateException - if we are not in multi-select mode.

      • removeSelectedRange

        public Sequence<Span> removeSelectedRange​(Span range)
        Removes a range of indexes from the selection.
        Parameters:
        range - The range to remove.
        Returns:
        The ranges that were removed from the selection.

      • selectAll

        public void selectAll()
        Selects all items in the list.

      • clearSelection

        public void clearSelection()
        Clears the selection.

      • isItemSelected

        public boolean isItemSelected​(int index)
        Returns the selection state of a given index.
        Parameters:
        index - The index whose selection state is to be tested.
        Returns:
        true if the index is selected; false, otherwise.

      • getSelectedItem

        public java.lang.Object getSelectedItem()

      • setSelectedItem

        public void setSelectedItem​(java.lang.Object item)

      • getSelectedItems

        public Sequence<?> getSelectedItems()

      • setSelectedItems

        public void setSelectedItems​(Sequence<java.lang.Object> items)

      • getSelectMode

        public ListView.SelectMode getSelectMode()
        Returns:
        The current selection mode.

      • setSelectMode

        public void setSelectMode​(ListView.SelectMode selectMode)
        Sets the selection mode. Clears the selection if the mode has changed (but does not fire a selection change event).
        Parameters:
        selectMode - The new selection mode.

      • getCheckmarksEnabled

        public boolean getCheckmarksEnabled()
        Returns:
        Whether or not checkmarks on each item are enabled.

      • setCheckmarksEnabled

        public void setCheckmarksEnabled​(boolean checkmarksEnabled)
        Enables or disables checkmarks. Clears the check state if the check mode has changed (but does not fire any check state change events).
        Parameters:
        checkmarksEnabled - Whether or not to enable checkmarks for each item.

      • isItemChecked

        public boolean isItemChecked​(int index)
        Returns an item's checked state.

        For a tri-state checkmark, if the checkmarksMixedAsChecked flag is set, this method returns true if the state is Button.State.MIXED.

        Parameters:
        index - The index of the item to test.
        Returns:
        Whether or not the given item is checked.

      • setItemChecked

        public void setItemChecked​(int index,
                           boolean checked)
        Sets an item's checked state.
        Parameters:
        index - Index of the item to change.
        checked - The new value of that item's checked state.
        Throws:
        java.lang.IllegalStateException - if checkmarks are not enabled.

      • getCheckedIndexes

        public ImmutableList<java.lang.Integer> getCheckedIndexes()
        Returns the indexes of currently checked items.

        If the checkmarksMixedAsChecked flag is set this method will return all the checked and MIXED state items.

        Returns:
        The complete list of currently checked items.

      • clearCheckmarks

        public void clearCheckmarks()
        Clears the checked state of all checked items.

      • isCheckmarkDisabled

        public boolean isCheckmarkDisabled​(int index)
        Tells whether or not an item's checkmark is disabled. Queries the current disabled checkmark filter (if any).
        Parameters:
        index - The index of the item whose disabled checkmark state is to be tested.
        Returns:
        true if the item's checkmark is disabled; false otherwise (such as if no disabled checkmark filter is set).

      • getCheckmarkStates

        public ImmutableList<Button.State> getCheckmarkStates()
        Gets the state of all items' checkmarks (for the tri-state case).
        Returns:
        The complete list of all checkmark states.

      • getItemCheckmarkState

        public Button.State getItemCheckmarkState​(int index)
        Gets an item's checkmark state (for tri-state checkmarks).

        Note: this method returns the real state regardless of the setting of the checkmarksMixedAsChecked flag.

        Parameters:
        index - The index of the item in question.
        Returns:
        The checkmark state for that item.

      • setItemCheckmarkState

        public void setItemCheckmarkState​(int index,
                                  Button.State state)
        Sets an item's checkmark state (for tri-state checkmarks).
        Parameters:
        index - The index of the item to change.
        state - The new checkmark state for the item.

      • getDisabledCheckmarkFilter

        public Filter<?> getDisabledCheckmarkFilter()
        Returns the disabled checkmark filter, which determines which checkboxes are interactive and which are not. Note that this filter only affects user interaction; items may still be checked programatically despite their inclusion in this filter. If this filter is set to null, all checkboxes will be interactive.

        Note: this filter is only relevant if checkmarksEnabled is set to true.

        Returns:
        The disabled checkmark filter, or null if no disabled checkmark filter is set

      • setDisabledCheckmarkFilter

        public void setDisabledCheckmarkFilter​(Filter<?> disabledCheckmarkFilter)
        Sets the disabled checkmark filter, which determines which checkboxes are interactive and which are not. Note that this filter only affects user interaction; items may still be checked programatically despite their inclusion in this filter. If this filter is set to null, all checkboxes will be interactive.

        Note: this filter is only relavent if checkmarksEnabled is set to true. enabled.

        Parameters:
        disabledCheckmarkFilter - The disabled checkmark filter, or null for no disabled checkmark filter

      • getAllowTriStateCheckmarks

        public boolean getAllowTriStateCheckmarks()
        Get the flag saying whether tri-state checkmarks are allowed in this ListView.

        Tri-state checkmarks show checked, unchecked and mixed states. For a list view with this property enabled, then there are additional methods to set the mixed state, to get the true state of all the items, and to decide if mixed state should be treated as checked or not for all the other "checked" methods.

        Returns:
        Whether or not tri-state checkmarks are enabled.

      • setAllowTriStateCheckmarks

        public void setAllowTriStateCheckmarks​(boolean allow)
        Set the flag saying whether tri-state checkmarks are allowed in this ListView.

        Tri-state checkmarks show checked, unchecked and mixed states. For a list view with this property enabled, then there are additional methods to set the mixed state, to get the true state of all the items, and to decide if mixed state should be treated as checked or not for all the other "checked" methods.

        Clears the check state if the setting has changed (but does not fire any check state change events).

        Parameters:
        allow - Whether or not to allow tri-state checkmarks.

      • getCheckmarksMixedAsChecked

        public boolean getCheckmarksMixedAsChecked()
        Get the flag saying whether the mixed state of tri-state checkmarks should be treated for all other purposes as "checked" or not. This setting will also affect what happens when we get mouse clicks on the checkmark. Set to false UNSELECTED will go to MIXED; while set to true UNSELECTED will go to SELECTED.
        Returns:
        Whether or not to treat the mixed state as "checked".

      • setCheckmarksMixedAsChecked

        public void setCheckmarksMixedAsChecked​(boolean mixedAsChecked)
        Set the flag saying whether the mixed state of the tri-state checkmarks should be treated for all other purposes as "checked" or not.
        Parameters:
        mixedAsChecked - Whether or not to treat the mixed state as "checked".

      • isItemDisabled

        public boolean isItemDisabled​(int index)
        Returns an item's disabled state.
        Parameters:
        index - The index of the item whose disabled state is to be tested.
        Returns:
        true if the item is disabled; false, otherwise.

      • getDisabledItemFilter

        public Filter<?> getDisabledItemFilter()
        Returns the disabled item filter.
        Returns:
        The disabled item filter, or null if no disabled item filter is set.

      • setDisabledItemFilter

        public void setDisabledItemFilter​(Filter<?> disabledItemFilter)
        Sets the disabled item filter.
        Parameters:
        disabledItemFilter - The disabled item filter, or null for no disabled item filter.

      • getListDataKey

        public java.lang.String getListDataKey()
        Returns name of the key that is used in context binding.
        Returns:
        The key.

      • setListDataKey

        public void setListDataKey​(java.lang.String listDataKey)
        Set the name of the key that is used in context binding.
        Parameters:
        listDataKey - The key to set.

      • getListDataBindType

        public BindType getListDataBindType()

      • setListDataBindType

        public void setListDataBindType​(BindType listDataBindType)

      • getSelectedItemKey

        public java.lang.String getSelectedItemKey()

      • setSelectedItemKey

        public void setSelectedItemKey​(java.lang.String selectedItemKey)

      • getSelectedItemBindType

        public BindType getSelectedItemBindType()

      • setSelectedItemBindType

        public void setSelectedItemBindType​(BindType selectedItemBindType)

      • setSelectedItemBindMapping

        public void setSelectedItemBindMapping​(ListView.ItemBindMapping selectedItemBindMapping)

      • getSelectedItemsKey

        public java.lang.String getSelectedItemsKey()

      • setSelectedItemsKey

        public void setSelectedItemsKey​(java.lang.String selectedItemsKey)

      • getSelectedItemsBindType

        public BindType getSelectedItemsBindType()

      • setSelectedItemsBindType

        public void setSelectedItemsBindType​(BindType selectedItemsBindType)

      • setSelectedItemsBindMapping

        public void setSelectedItemsBindMapping​(ListView.ItemBindMapping selectedItemsBindMapping)

      • getCheckedItemsKey

        public java.lang.String getCheckedItemsKey()

      • setCheckedItemsKey

        public void setCheckedItemsKey​(java.lang.String checkedItemsKey)

      • getCheckedItemsBindType

        public BindType getCheckedItemsBindType()

      • setCheckedItemsBindType

        public void setCheckedItemsBindType​(BindType checkedItemsBindType)

      • setCheckedItemsBindMapping

        public void setCheckedItemsBindMapping​(ListView.ItemBindMapping checkedItemsBindMapping)

      • getItemsStateKey

        public java.lang.String getItemsStateKey()

      • setItemsStateKey

        public void setItemsStateKey​(java.lang.String itemsStateKey)

      • getItemsStateBindType

        public BindType getItemsStateBindType()

      • setItemsStateBindType

        public void setItemsStateBindType​(BindType itemsStateBindType)

      • load

        public void load​(java.lang.Object context)
        Description copied from class: Component
        Copies bound values from the bind context to the component. This functionality must be provided by the subclass; the base implementation is a no-op.
        Overrides:
        load in class Component
        Parameters:
        context - The object to load the bound values from.

      • store

        public void store​(java.lang.Object context)
        Description copied from class: Component
        Copies bound values from the component to the bind context. This functionality must be provided by the subclass; the base implementation is a no-op.
        Overrides:
        store in class Component
        Parameters:
        context - The object to store the bound values into.

      • clear

        public void clear()
        Description copied from class: Component
        Clears any bound values in the component. This functionality must be provided by the subclass; the base implementation is a no-op.
        Overrides:
        clear in class Component

      • getItemAt

        public int getItemAt​(int y)
        Returns the index of the item at a given location.
        Parameters:
        y - The y-coordinate of the item to identify.
        Returns:
        The item index, or -1 if there is no item at the given y-coordinate.

      • getItemBounds

        public Bounds getItemBounds​(int index)
        Returns the bounding area of a given item.
        Parameters:
        index - The item index.
        Returns:
        The bounding area of the item.

      • getItemIndent

        public int getItemIndent()
        Returns the item indent.
        Returns:
        The horizontal space preceding items in the list.