content: /*
   * Created on Jun 12, 2007
   *
   * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
   * the License. You may obtain a copy of the License at
   *
   * http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
   * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
   * specific language governing permissions and limitations under the License.
   *
   * Copyright @2007-2013 the original author or authors.
   */
  package org.fest.swing.fixture;
  
  import static org.fest.swing.core.MouseButton.LEFT_BUTTON;
  
  import java.util.regex.Pattern;
  
  import javax.annotation.Nonnull;
  import javax.annotation.Nullable;
  import javax.swing.JList;
  
  import org.fest.swing.cell.JListCellReader;
  import org.fest.swing.core.MouseButton;
  import org.fest.swing.core.Robot;
  import org.fest.swing.driver.BasicJListCellReader;
  import org.fest.swing.driver.JListDriver;
  import org.fest.swing.exception.ActionFailedException;
  import org.fest.swing.exception.ComponentLookupException;
  import org.fest.swing.exception.LocationUnavailableException;
  import org.fest.swing.util.Range;
  
  /**
   * <p>
   * Supports functional testing of {@code JList}s.
   * </p>
   *
   * <p>
   * The conversion between the values given in tests and the values being displayed by a {@code JList} renderer is
   * performed by a {@link JListCellReader}. This fixture uses a {@link BasicJListCellReader} by default.
   * </p>
   *
   * @author Alex Ruiz
   * @author Yvonne Wang
   * @author Fabien Barbero
   */
  public class JListFixture extends AbstractJPopupMenuInvokerFixture<JListFixture, JList, JListDriver> implements
      ItemGroupFixture<JListFixture> {
    /**
     * Creates a new {@link JListFixture}.
     *
     * @param robot performs simulation of user events on a {@code JList}.
     * @param listName the name of the {@code JList} to find using the given {@code Robot}.
     * @throws NullPointerException if {@code robot} is {@code null}.
     * @throws ComponentLookupException if a matching {@code JList} could not be found.
     * @throws ComponentLookupException if more than one matching {@code JList} is found.
     */
    public JListFixture(@Nonnull Robot robot, @Nullable String listName) {
      super(JListFixture.class, robot, listName, JList.class);
    }
  
    /**
     * Creates a new {@link JListFixture}.
     *
     * @param robot performs simulation of user events on the given {@code JList}.
     * @param target the {@code JList} to be managed by this fixture.
     * @throws NullPointerException if {@code robot} is {@code null}.
     * @throws NullPointerException if {@code target} is {@code null}.
     */
    public JListFixture(@Nonnull Robot robot, @Nonnull JList target) {
      super(JListFixture.class, robot, target);
    }
  
    @Override
    protected @Nonnull JListDriver createDriver(@Nonnull Robot robot) {
      return new JListDriver(robot);
    }
  
    /**
     * Returns the {@code String} representation of the value of an item in this fixture's {@code JList}, using this
     * fixture's {@link JListCellReader}.
     *
     * @param index the index of the item to return.
     * @return the {@code String} representation of the value of an item in this fixture's {@code JList}.
     * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
     *           {@code JList}.
     * @see #replaceCellReader(JListCellReader)
     */
    @Override
    public @Nullable String valueAt(int index) {
      return driver().value(target(), index);
    }
  
    /**
     * Returns the {@code String} representation of the elements in this fixture's {@code JList}, using this fixture's
     * {@link JListCellReader}.
     *
     * @return the {@code String} representation of the elements in this fixture's {@code JList}.
     * @see #replaceCellReader(JListCellReader)
     */
    @Override
    public @Nonnull String[] contents() {
      return driver().contentsOf(target());
    }
  
    /**
     * Returns the {@code String} representation of the selected elements in this fixture's {@code JList}, using this
     * fixture's {@link JListCellReader}.
     *
     * @return the {@code String} representation of the selected elements in this fixture's {@code JList}.
     * @see #replaceCellReader(JListCellReader)
     */
    public @Nonnull String[] selection() {
      return driver().selectionOf(target());
    }
  
    /**
     * Returns a fixture that manages the list item specified by the given index.
     *
     * @param index of the item.
     * @return a fixture that manages the list item specified by the given index.
     * @throws IndexOutOfBoundsException if the index is out of bounds.
     */
    public @Nonnull JListItemFixture item(int index) {
      return new JListItemFixture(this, index);
    }
  
    /**
     * Returns a fixture that manages the list item specified by the given text.
     *
     * @param text the text of the item. It can be a regular expression.
     * @return a fixture that manages the list item specified by the given text.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     */
    public @Nonnull JListItemFixture item(@Nullable String text) {
      return new JListItemFixture(this, driver().indexOf(target(), text));
    }
  
    /**
     * Returns a fixture that manages the list item whose text matches the given regular expression pattern.
     *
     * @param pattern the regular expression pattern to match.
     * @return a fixture that manages the list item whose text matches the given regular expression pattern.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @throws NullPointerException if the given regular expression pattern is {@code null}.
     * @since 1.2
     */
    public @Nonnull JListItemFixture item(@Nonnull Pattern pattern) {
      return new JListItemFixture(this, driver().indexOf(target(), pattern));
    }
  
    /**
     * Clears the selection in this fixture's {@code JList}. Since this method does not simulate user input, it does not
     * verifies that this fixture's {@code JList} is enabled and showing.
     *
     * @return this fixture.
     * @since 1.2
     */
    @Override
    public @Nonnull JListFixture clearSelection() {
      driver().clearSelection(target());
      return this;
    }
  
    /**
     * Simulates a user selecting an item in this fixture's {@code JList}.
     *
     * @param index the index of the item to select.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
     *           {@code JList}.
     * @see #item(int)
     * @see JListItemFixture#select()
     */
    @Override
    public @Nonnull JListFixture selectItem(int index) {
      driver().selectItem(target(), index);
      return this;
    }
  
    /**
     * Simulates a user selecting an item in this fixture's {@code JList}.
     *
     * @param text the text of the item to select. It can be a regular expression.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @see #item(String)
     * @see JListItemFixture#select()
     * @see #replaceCellReader(JListCellReader)
     */
    @Override
    public @Nonnull JListFixture selectItem(@Nullable String text) {
      driver().selectItem(target(), text);
      return this;
    }
  
    /**
     * Simulates a user selecting an item in this fixture's {@code JList}. The value of the item to select must match the
     * given regular expression pattern.
     *
     * @param pattern the regular expression pattern to match.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @throws NullPointerException if the given regular expression pattern is {@code null}.
     * @see #item(Pattern)
     * @see JListItemFixture#select()
     * @see #replaceCellReader(JListCellReader)
     * @since 1.2
     */
    @Override
    public @Nonnull JListFixture selectItem(@Nonnull Pattern pattern) {
      driver().selectItem(target(), pattern);
      return this;
    }
  
    /**
     * Verifies that the {@code String} representation of the selected item in this fixture's {@code JList} matches the
     * given text.
     *
     * @param text the text to match. It can be a regular expression pattern.
     * @return this fixture.
     * @throws AssertionError if the selected item does not match the given text.
     * @see #replaceCellReader(JListCellReader)
     */
    @Override
    public @Nonnull JListFixture requireSelection(@Nullable String text) {
      driver().requireSelection(target(), text);
      return this;
    }
  
    /**
     * Verifies that the {@code String} representation of the selected item in this fixture's {@code JList} matches the
     * given regular expression pattern.
     *
     * @param pattern the regular expression pattern to match.
     * @return this fixture.
     * @throws AssertionError if the selected item does not match the given regular expression pattern.
     * @throws NullPointerException if the given regular expression pattern is {@code null}.
     * @see #replaceCellReader(JListCellReader)
     * @since 1.2
     */
    @Override
    public @Nonnull JListFixture requireSelection(@Nonnull Pattern pattern) {
      driver().requireSelection(target(), pattern);
      return this;
    }
  
    /**
     * Verifies that the index of the selected item in this fixture's {@code JList} is equal to the given value.
     *
     * @param index the expected selection index.
     * @return this fixture.
     * @throws AssertionError if the selected index is not equal to the given one.
     * @since 1.2
     */
    @Override
    public @Nonnull JListFixture requireSelection(int index) {
      driver().requireSelection(target(), index);
      return this;
    }
  
    /**
     * Verifies that this fixture's {@code JList} does not have any selection.
     *
     * @return this fixture.
     * @throws AssertionError if this fixture's {@code JList} has a selection.
     */
    @Override
    public @Nonnull JListFixture requireNoSelection() {
      driver().requireNoSelection(target());
      return this;
    }
  
    /**
     * Verifies that this fixture's {@code JList} has the expected number of items
     *
     * @param expected the expected number of items.
     * @return this fixture.
     * @throws AssertionError if the number of items in this fixture's {@code JList} is not equal to the expected one.
     * @since 1.2
     */
    @Override
    public @Nonnull JListFixture requireItemCount(int expected) {
      driver().requireItemCount(target(), expected);
      return this;
    }
  
    /**
     * Simulates a user selecting the items (in the specified range) in this fixture's {@code JList}.
     *
     * @param from the starting point of the selection.
     * @param to the last item to select (inclusive.)
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws IndexOutOfBoundsException if the any index is negative or greater than the index of the last item in the
     *           {@code JList}.
     */
    public @Nonnull JListFixture selectItems(@Nonnull Range.From from, @Nonnull Range.To to) {
      driver().selectItems(target(), from, to);
      return this;
    }
  
    /**
     * Simulates a user selecting the specified items in this fixture's {@code JList}.
     *
     * @param indices the indices of the items to select.
     * @return this fixture.
     * @throws NullPointerException if the given array is {@code null}.
     * @throws IllegalArgumentException if the given array is empty.
     * @throws IndexOutOfBoundsException if any of the indices is negative or greater than the index of the last item in
     *           the {@code JList}.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     */
    public @Nonnull JListFixture selectItems(@Nonnull int... indices) {
      driver().selectItems(target(), indices);
      return this;
    }
  
    /**
     * Simulates a user selecting the specified items in this fixture's {@code JList}. The items to select should match
     * the given values.
     *
     * @param items the text of the items to select. Each {@code String} can be a regular expression.
     * @return this fixture.
     * @throws NullPointerException if the given array is {@code null}.
     * @throws IllegalArgumentException if the given array is empty.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the any of the given values cannot be found.
     * @see #replaceCellReader(JListCellReader)
     */
    public @Nonnull JListFixture selectItems(@Nonnull String... items) {
      driver().selectItems(target(), items);
      return this;
    }
  
    /**
     * Simulates a user selecting the specified items in this fixture's {@code JList}. The items to select should select
     * the given regular expression patterns.
     *
     * @param patterns the regular expression patterns to match.
     * @return this fixture.
     * @throws NullPointerException if the given array is {@code null}.
     * @throws NullPointerException if any of the regular expression patterns is {@code null}.
     * @throws IllegalArgumentException if the given array is empty.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the any of the given regular expression patterns cannot
     *           be found.
     * @see #replaceCellReader(JListCellReader)
     * @since 1.2
     */
    public @Nonnull JListFixture selectItems(@Nonnull Pattern... patterns) {
      driver().selectItems(target(), patterns);
      return this;
    }
  
    /**
     * Simulates a user clicking an item in this fixture's {@code JList}.
     *
     * @param index the index of the item to clicking.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
     *           {@code JList}.
     * @see #item(int)
     * @see JListItemFixture#click()
     * @since 1.2
     */
    public @Nonnull JListFixture clickItem(int index) {
      driver().clickItem(target(), index, LEFT_BUTTON, 1);
      return this;
    }
  
    /**
     * Simulates a user clicking an item in this fixture's {@code JList}.
     *
     * @param text the text of the item to select. It can be a regular expression.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @see #item(String)
     * @see JListItemFixture#select()
     * @see #replaceCellReader(JListCellReader)
     * @since 1.2
     */
    public JListFixture clickItem(@Nullable String text) {
      driver().clickItem(target(), text, LEFT_BUTTON, 1);
      return this;
    }
  
    /**
     * Simulates a user clicking an item in this fixture's {@code JList}. The value of the item to select must match the
     * given regular expression pattern.
     *
     * @param pattern the regular expression pattern to match.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @throws NullPointerException if the given regular expression pattern is {@code null}.
     * @see #item(Pattern)
     * @see JListItemFixture#select()
     * @see #replaceCellReader(JListCellReader)
     * @since 1.2
     */
    public @Nonnull JListFixture clickItem(@Nonnull Pattern pattern) {
      driver().clickItem(target(), pattern, LEFT_BUTTON, 1);
      return this;
    }
  
    void clickItem(int index, @Nonnull MouseButton button, int times) {
      driver().clickItem(target(), index, button, times);
    }
  
    /**
     * Verifies that the given item indices are selected in this fixture's {@code JList}.
     *
     * @param indices the expected indices of the selected items.
     * @return this fixture.
     * @throws NullPointerException if the given array is {@code null}.
     * @throws IllegalArgumentException if the given array is empty.
     * @throws AssertionError if the selection in this fixture's {@code JList} does not match the given one.
     * @since 1.2
     */
    public @Nonnull JListFixture requireSelectedItems(@Nonnull int... indices) {
      driver().requireSelectedItems(target(), indices);
      return this;
    }
  
    /**
     * Verifies that the {@code String} representations of the selected items in this fixture's {@code JList} match the
     * given text items.
     *
     * @param items text items to match. Each {@code String} can be a regular expression.
     * @return this fixture.
     * @throws NullPointerException if the given array is {@code null}.
     * @throws IllegalArgumentException if the given array is empty.
     * @throws AssertionError if the selected items do not match the given text items.
     * @see #replaceCellReader(JListCellReader)
     */
    public @Nonnull JListFixture requireSelectedItems(@Nonnull String... items) {
      driver().requireSelectedItems(target(), items);
      return this;
    }
  
    /**
     * Verifies that the {@code String} representations of the selected items in this fixture's {@code JList} match the
     * given regular expression patterns.
     *
     * @param patterns the regular expression patterns to match.
     * @return this fixture.
     * @throws NullPointerException if the given array is {@code null}.
     * @throws IllegalArgumentException if the given array is empty.
     * @throws NullPointerException if any of the patterns in the given array is {@code null}.
     * @throws AssertionError if the selected items do not match the given regular expression patterns.
     * @see #replaceCellReader(JListCellReader)
     * @since 1.2
     */
    public @Nonnull JListFixture requireSelectedItems(@Nonnull Pattern[] patterns) {
      driver().requireSelectedItems(target(), patterns);
      return this;
    }
  
    /**
     * Simulates a user dragging an item from this fixture's {@code JList}.
     *
     * @param index the index of the item to drag.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
     *           {@code JList}.
     */
    public @Nonnull JListFixture drag(int index) {
      driver().drag(target(), index);
      return this;
    }
  
    /**
     * Simulates a user dropping an item to this fixture's {@code JList}.
     *
     * @param index the index of the item to drop.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
     *           {@code JList}.
     * @throws ActionFailedException if there is no drag action in effect.
     */
    public @Nonnull JListFixture drop(int index) {
      driver().drop(target(), index);
      return this;
    }
  
    /**
     * Simulates a drag operation at the location of the first item in this fixture's {@code JList} matching the given
     * value.
     *
     * @param text the text of the item to drag. It can be a regular expression.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @return this fixture.
     */
    public @Nonnull JListFixture drag(@Nullable String text) {
      driver().drag(target(), text);
      return this;
    }
  
    /**
     * Ends a drag operation at the location of the first item matching the given value.
     *
     * @param text the text of the item to drop. It can be a regular expression.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @throws ActionFailedException if there is no drag action in effect.
     */
    public @Nonnull JListFixture drop(@Nullable String text) {
      driver().drop(target(), text);
      return this;
    }
  
    /**
     * Simulates a drag operation at the location of the first item in this fixture's {@code JList} matching the given
     * regular expression pattern.
     *
     * @param pattern the regular expression pattern to match.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws NullPointerException if the given regular expression pattern in {@code null}.
     * @throws LocationUnavailableException if an element matching the given regular expression pattern cannot be found.
     * @since 1.2
     */
    public @Nonnull JListFixture drag(@Nonnull Pattern pattern) {
      driver().drag(target(), pattern);
      return this;
    }
  
    /**
     * Ends a drag operation at the location of the first item matching the given regular expression pattern.
     *
     * @param pattern the regular expression pattern to match.
     * @return this fixture.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws NullPointerException if the given regular expression pattern in {@code null}.
     * @throws LocationUnavailableException if an element matching the given text cannot be found.
     * @throws ActionFailedException if there is no drag action in effect.
     * @since 1.2
     */
    public @Nonnull JListFixture drop(@Nonnull Pattern pattern) {
      driver().drop(target(), pattern);
      return this;
    }
  
    /**
     * Shows a pop-up menu at the location of the specified item in this fixture's {@code JList}.
     *
     * @param index the index of the item.
     * @return a fixture that manages the displayed pop-up menu.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws ComponentLookupException if a pop-up menu cannot be found.
     * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
     *           {@code JList}.
     */
    public @Nonnull JPopupMenuFixture showPopupMenuAt(int index) {
      return new JPopupMenuFixture(robot(), driver().showPopupMenu(target(), index));
    }
  
    /**
     * Shows a pop-up menu at the location of the first item matching the given value in this fixture's {@code JList}.
     *
     * @param text the text of the item. It can be a regular expression.
     * @return a fixture that manages the displayed pop-up menu.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws ComponentLookupException if a pop-up menu cannot be found.
     * @throws LocationUnavailableException if an element matching the given value cannot be found.
     */
    public @Nonnull JPopupMenuFixture showPopupMenuAt(@Nullable String text) {
      return new JPopupMenuFixture(robot(), driver().showPopupMenu(target(), text));
    }
  
    /**
     * Shows a pop-up menu at the location of the first item matching the given regular expression pattern in this
     * fixture's {@code JList}.
     *
     * @param pattern the regular expression pattern to match.
     * @return a fixture that manages the displayed pop-up menu.
     * @throws IllegalStateException if this fixture's {@code JList} is disabled.
     * @throws IllegalStateException if this fixture's {@code JList} is not showing on the screen.
     * @throws NullPointerException if the given regular expression pattern is {@code null}.
     * @throws ComponentLookupException if a pop-up menu cannot be found.
     * @throws LocationUnavailableException if an element matching the given value cannot be found.
     * @since 1.2
     */
    public @Nonnull JPopupMenuFixture showPopupMenuAt(@Nonnull Pattern pattern) {
      return new JPopupMenuFixture(robot(), driver().showPopupMenu(target(), pattern));
    }
  
    public void replaceCellReader(@Nonnull JListCellReader cellReader) {
      driver().replaceCellReader(cellReader);
    }
  }
  