001    /*
002     * Created on Jun 12, 2007
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     *
014     * Copyright @2007-2010 the original author or authors.
015     */
016    package org.fest.swing.fixture;
017    
018    import static org.fest.swing.core.MouseButton.LEFT_BUTTON;
019    
020    import java.awt.Point;
021    import java.util.regex.Pattern;
022    
023    import javax.swing.JList;
024    
025    import org.fest.swing.cell.JListCellReader;
026    import org.fest.swing.core.*;
027    import org.fest.swing.driver.BasicJListCellReader;
028    import org.fest.swing.driver.JListDriver;
029    import org.fest.swing.exception.*;
030    import org.fest.swing.timing.Timeout;
031    import org.fest.swing.util.Range;
032    
033    /**
034     * Understands functional testing of <code>{@link JList}</code>s:
035     * <ul>
036     * <li>user input simulation</li>
037     * <li>state verification</li>
038     * <li>property value query</li>
039     * </ul>
040     * <p>
041     * The conversion between the values given in tests and the values being displayed by a <code>{@link JList}</code>
042     * renderer is performed by a <code>{@link JListCellReader}</code>. This fixture uses a
043     * <code>{@link BasicJListCellReader}</code> by default.
044     * </p>
045     *
046     * @author Alex Ruiz
047     * @author Yvonne Wang
048     * @author Fabien Barbero
049     */
050    public class JListFixture extends ComponentFixture<JList> implements CommonComponentFixture,
051      ItemGroupFixture, JComponentFixture, JPopupMenuInvokerFixture {
052    
053      private JListDriver driver;
054    
055      /**
056       * Creates a new <code>{@link JListFixture}</code>.
057       * @param robot performs simulation of user events on a <code>JList</code>.
058       * @param listName the name of the <code>JList</code> to find using the given <code>Robot</code>.
059       * @throws NullPointerException if <code>robot</code> is <code>null</code>.
060       * @throws ComponentLookupException if a matching <code>JList</code> could not be found.
061       * @throws ComponentLookupException if more than one matching <code>JList</code> is found.
062       */
063      public JListFixture(Robot robot, String listName) {
064        super(robot, listName, JList.class);
065        createDriver();
066      }
067    
068      /**
069       * Creates a new <code>{@link JListFixture}</code>.
070       * @param robot performs simulation of user events on the given <code>JList</code>.
071       * @param target the <code>JList</code> to be managed by this fixture.
072       * @throws NullPointerException if <code>robot</code> is <code>null</code>.
073       * @throws NullPointerException if <code>target</code> is <code>null</code>.
074       */
075      public JListFixture(Robot robot, JList target) {
076        super(robot, target);
077        createDriver();
078      }
079    
080      private void createDriver() {
081        driver(new JListDriver(robot));
082      }
083    
084      /**
085       * Sets the <code>{@link JListDriver}</code> to be used by this fixture.
086       * @param newDriver the new <code>JListDriver</code>.
087       * @throws NullPointerException if the given driver is <code>null</code>.
088       */
089      protected final void driver(JListDriver newDriver) {
090        validateNotNull(newDriver);
091        driver = newDriver;
092      }
093    
094      /**
095       * Returns the <code>String</code> representation of the value of an item in this fixture's
096       * <code>{@link JList}</code>, using this fixture's <code>{@link JListCellReader}</code>.
097       * @param index the index of the item to return.
098       * @return the <code>String</code> representation of the value of an item in this fixture's <code>JList</code>.
099       * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in
100       * the <code>JList</code>.
101       * @see #cellReader(JListCellReader)
102       */
103      public String valueAt(int index) {
104        return driver.value(target, index);
105      }
106    
107      /**
108       * Returns the <code>String</code> representation of the elements in this fixture's <code>{@link JList}</code>,
109       * using this fixture's <code>{@link JListCellReader}</code>.
110       * @return the <code>String</code> representation of the elements in this fixture's <code>JList</code>.
111       * @see #cellReader(JListCellReader)
112       */
113      public String[] contents() {
114        return driver.contentsOf(target);
115      }
116    
117      /**
118       * Returns the <code>String</code> representation of the selected elements in this fixture's
119       * <code>{@link JList}</code>, using this fixture's <code>{@link JListCellReader}</code>.
120       * @return the <code>String</code> representation of the selected elements in this fixture's <code>JList</code>.
121       * @see #cellReader(JListCellReader)
122       */
123      public String[] selection() {
124        return driver.selectionOf(target);
125      }
126    
127      /**
128       * Returns a fixture that manages the list item specified by the given index.
129       * @param index of the item.
130       * @return a fixture that manages the list item specified by the given index.
131       * @throws IndexOutOfBoundsException if the index is out of bounds.
132       */
133      public JListItemFixture item(int index) {
134        return new JListItemFixture(this, index);
135      }
136    
137      /**
138       * Returns a fixture that manages the list item specified by the given text.
139       * @param text the text of the item. It can be a regular expression.
140       * @return a fixture that manages the list item specified by the given text.
141       * @throws LocationUnavailableException if an element matching the given text cannot be found.
142       */
143      public JListItemFixture item(String text) {
144        return new JListItemFixture(this, driver.indexOf(target, text));
145      }
146    
147      /**
148       * Returns a fixture that manages the list item whose text matches the given regular expression pattern.
149       * @param pattern the regular expression pattern to match.
150       * @return a fixture that manages the list item whose text matches the given regular expression pattern.
151       * @throws LocationUnavailableException if an element matching the given text cannot be found.
152       * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
153       * @since 1.2
154       */
155      public JListItemFixture item(Pattern pattern) {
156        return new JListItemFixture(this, driver.indexOf(target, pattern));
157      }
158    
159      /**
160       * Clears the selection in this fixture's <code>{@link JList}</code>. Since this method does not simulate user input,
161       * it does not verifies that this fixture's <code>JList</code> is enabled and showing.
162       * @return this fixture.
163       * @since 1.2
164       */
165      public JListFixture clearSelection() {
166        driver.clearSelection(target);
167        return this;
168      }
169    
170      /**
171       * Simulates a user selecting the items (in the specified range) in this fixture's <code>{@link JList}</code>.
172       * @param from the starting point of the selection.
173       * @param to the last item to select (inclusive.)
174       * @return this fixture.
175       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
176       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
177       * @throws IndexOutOfBoundsException if the any index is negative or greater than the index of the last item in the
178       * <code>JList</code>.
179       */
180      public JListFixture selectItems(Range.From from, Range.To to) {
181        driver.selectItems(target, from, to);
182        return this;
183      }
184    
185      /**
186       * Simulates a user selecting the specified items in this fixture's <code>{@link JList}</code>.
187       * @param indices the indices of the items to select.
188       * @return this fixture.
189       * @throws NullPointerException if the given array is <code>null</code>.
190       * @throws IllegalArgumentException if the given array is empty.
191       * @throws IndexOutOfBoundsException if any of the indices is negative or greater than the index of the last item in
192       * the <code>JList</code>.
193       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
194       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
195       */
196      public JListFixture selectItems(int...indices) {
197        driver.selectItems(target, indices);
198        return this;
199      }
200    
201      /**
202       * Simulates a user selecting the specified items in this fixture's <code>{@link JList}</code>. The items to select
203       * should match the given values.
204       * @param items the text of the items to select. Each <code>String</code> can be a regular expression.
205       * @return this fixture.
206       * @throws NullPointerException if the given array is <code>null</code>.
207       * @throws IllegalArgumentException if the given array is empty.
208       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
209       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
210       * @throws LocationUnavailableException if an element matching the any of the given values cannot be found.
211       * @see #cellReader(JListCellReader)
212       */
213      public JListFixture selectItems(String...items) {
214        driver.selectItems(target, items);
215        return this;
216      }
217    
218      /**
219       * Simulates a user selecting the specified items in this fixture's <code>{@link JList}</code>. The items to select
220       * should select the given regular expression patterns.
221       * @param patterns the regular expression patterns to match.
222       * @return this fixture.
223       * @throws NullPointerException if the given array is <code>null</code>.
224       * @throws NullPointerException if any of the regular expression patterns is <code>null</code>.
225       * @throws IllegalArgumentException if the given array is empty.
226       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
227       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
228       * @throws LocationUnavailableException if an element matching the any of the given regular expression patterns cannot
229       * be found.
230       * @see #cellReader(JListCellReader)
231       * @since 1.2
232       */
233      public JListFixture selectItems(Pattern... patterns) {
234        driver.selectItems(target, patterns);
235        return this;
236      }
237    
238      /**
239       * Simulates a user selecting an item in this fixture's <code>{@link JList}</code>.
240       * @param index the index of the item to select.
241       * @return this fixture.
242       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
243       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
244       * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
245       * <code>JList</code>.
246       * @see #item(int)
247       * @see JListItemFixture#select()
248       */
249      public JListFixture selectItem(int index) {
250        driver.selectItem(target, index);
251        return this;
252      }
253    
254      /**
255       * Simulates a user selecting an item in this fixture's <code>{@link JList}</code>.
256       * @param text the text of the item to select. It can be a regular expression.
257       * @return this fixture.
258       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
259       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
260       * @throws LocationUnavailableException if an element matching the given text cannot be found.
261       * @see #item(String)
262       * @see JListItemFixture#select()
263       * @see #cellReader(JListCellReader)
264       */
265      public JListFixture selectItem(String text) {
266        driver.selectItem(target, text);
267        return this;
268      }
269    
270      /**
271       * Simulates a user selecting an item in this fixture's <code>{@link JList}</code>. The value of the item to select
272       * must match the given regular expression pattern.
273       * @param pattern the regular expression pattern to match.
274       * @return this fixture.
275       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
276       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
277       * @throws LocationUnavailableException if an element matching the given text cannot be found.
278       * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
279       * @see #item(Pattern)
280       * @see JListItemFixture#select()
281       * @see #cellReader(JListCellReader)
282       * @since 1.2
283       */
284      public JListFixture selectItem(Pattern pattern) {
285        driver.selectItem(target, pattern);
286        return this;
287      }
288    
289      /**
290       * Simulates a user clicking an item in this fixture's <code>{@link JList}</code>.
291       * @param index the index of the item to clicking.
292       * @return this fixture.
293       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
294       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
295       * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
296       * <code>JList</code>.
297       * @see #item(int)
298       * @see JListItemFixture#click()
299       * @since 1.2
300       */
301      public JListFixture clickItem(int index) {
302        driver.clickItem(target, index, LEFT_BUTTON, 1);
303        return this;
304      }
305    
306      /**
307       * Simulates a user clicking an item in this fixture's <code>{@link JList}</code>.
308       * @param text the text of the item to select. It can be a regular expression.
309       * @return this fixture.
310       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
311       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
312       * @throws LocationUnavailableException if an element matching the given text cannot be found.
313       * @see #item(String)
314       * @see JListItemFixture#select()
315       * @see #cellReader(JListCellReader)
316       * @since 1.2
317       */
318      public JListFixture clickItem(String text) {
319        driver.clickItem(target, text, LEFT_BUTTON, 1);
320        return this;
321      }
322    
323      /**
324       * Simulates a user clicking an item in this fixture's <code>{@link JList}</code>. The value of the item to select
325       * must match the given regular expression pattern.
326       * @param pattern the regular expression pattern to match.
327       * @return this fixture.
328       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
329       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
330       * @throws LocationUnavailableException if an element matching the given text cannot be found.
331       * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
332       * @see #item(Pattern)
333       * @see JListItemFixture#select()
334       * @see #cellReader(JListCellReader)
335       * @since 1.2
336       */
337      public JListFixture clickItem(Pattern pattern) {
338        driver.clickItem(target, pattern, LEFT_BUTTON, 1);
339        return this;
340      }
341    
342      /**
343       * Simulates a user double-clicking an item in this fixture's <code>{@link JList}</code>.
344       * @param index the index of the item to double-click.
345       * @return this fixture.
346       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
347       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
348       * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in
349       * the <code>JList</code>.
350       * @deprecated to be removed in version 2.0. Use <code>{@link #item(int)}</code> and
351       * <code>{@link JListItemFixture#doubleClick()}</code> instead.
352       */
353      @Deprecated
354      public JListFixture doubleClickItem(int index) {
355        clickItem(index, LEFT_BUTTON, 2);
356        return this;
357      }
358    
359      /**
360       * Simulates a user double-clicking an item in this fixture's <code>{@link JList}</code>.
361       * @param text the text of the item to double-click.
362       * @return this fixture.
363       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
364       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
365       * @throws LocationUnavailableException if an element matching the given <code>String</code> cannot be found.
366       * @deprecated to be removed in version 2.0. Use <code>{@link #item(String)}</code> and
367       * <code>{@link JListItemFixture#doubleClick()}</code> instead.
368       */
369      @Deprecated
370      public JListFixture doubleClickItem(String text) {
371        driver.clickItem(target, text, LEFT_BUTTON, 2);
372        return this;
373      }
374    
375      void clickItem(int index, MouseButton button, int times) {
376        driver.clickItem(target, index, button, times);
377      }
378    
379      /**
380       * Simulates a user clicking this fixture's <code>{@link JList}</code>.
381       * @return this fixture.
382       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
383       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
384       */
385      public JListFixture click() {
386        driver.click(target);
387        return this;
388      }
389    
390      /**
391       * Simulates a user clicking this fixture's <code>{@link JList}</code>.
392       * @param button the button to click.
393       * @return this fixture.
394       * @throws NullPointerException if the given <code>MouseButton</code> is <code>null</code>.
395       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
396       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
397       */
398      public JListFixture click(MouseButton button) {
399        driver.click(target, button);
400        return this;
401      }
402    
403      /**
404       * Simulates a user clicking this fixture's <code>{@link JList}</code>.
405       * @param mouseClickInfo specifies the button to click and the times the button should be clicked.
406       * @return this fixture.
407       * @throws NullPointerException if the given <code>MouseClickInfo</code> is <code>null</code>.
408       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
409       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
410       */
411      public JListFixture click(MouseClickInfo mouseClickInfo) {
412        driver.click(target, mouseClickInfo);
413        return this;
414      }
415    
416      /**
417       * Simulates a user double-clicking this fixture's <code>{@link JList}</code>.
418       * @return this fixture.
419       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
420       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
421       */
422      public JListFixture doubleClick() {
423        driver.doubleClick(target);
424        return this;
425      }
426    
427      /**
428       * Simulates a user right-clicking this fixture's <code>{@link JList}</code>.
429       * @return this fixture.
430       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
431       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
432       */
433      public JListFixture rightClick() {
434        driver.rightClick(target);
435        return this;
436      }
437    
438      /**
439       * Gives input focus to this fixture's <code>{@link JList}</code>.
440       * @return this fixture.
441       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
442       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
443       */
444      public JListFixture focus() {
445        driver.focus(target);
446        return this;
447      }
448    
449      /**
450       * Simulates a user pressing given key with the given modifiers on this fixture's <code>{@link JList}</code>.
451       * Modifiers is a mask from the available <code>{@link java.awt.event.InputEvent}</code> masks.
452       * @param keyPressInfo specifies the key and modifiers to press.
453       * @return this fixture.
454       * @throws NullPointerException if the given <code>KeyPressInfo</code> is <code>null</code>.
455       * @throws IllegalArgumentException if the given code is not a valid key code.
456       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
457       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
458       * @see KeyPressInfo
459       */
460      public JListFixture pressAndReleaseKey(KeyPressInfo keyPressInfo) {
461        driver.pressAndReleaseKey(target, keyPressInfo);
462        return this;
463      }
464    
465      /**
466       * Simulates a user pressing and releasing the given keys on this fixture's <code>{@link JList}</code>.
467       * @param keyCodes one or more codes of the keys to press.
468       * @return this fixture.
469       * @throws NullPointerException if the given array of codes is <code>null</code>.
470       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
471       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
472       * @see java.awt.event.KeyEvent
473       */
474      public JListFixture pressAndReleaseKeys(int... keyCodes) {
475        driver.pressAndReleaseKeys(target, keyCodes);
476        return this;
477      }
478    
479      /**
480       * Simulates a user pressing the given key on this fixture's <code>{@link JList}</code>.
481       * @param keyCode the code of the key to press.
482       * @return this fixture.
483       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
484       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
485       * @see java.awt.event.KeyEvent
486       */
487      public JListFixture pressKey(int keyCode) {
488        driver.pressKey(target, keyCode);
489        return this;
490      }
491    
492      /**
493       * Simulates a user releasing the given key on this fixture's <code>{@link JList}</code>.
494       * @param keyCode the code of the key to release.
495       * @return this fixture.
496       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
497       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
498       * @see java.awt.event.KeyEvent
499       */
500      public JListFixture releaseKey(int keyCode) {
501        driver.releaseKey(target, keyCode);
502        return this;
503      }
504    
505      /**
506       * Simulates a drag operation at the location of the first item in this fixture's <code>{@link JList}</code> matching
507       * the given value.
508       * @param text the text of the item to drag. It can be a regular expression.
509       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
510       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
511       * @throws LocationUnavailableException if an element matching the given text cannot be found.
512       * @return this fixture.
513       * @see #cellReader(JListCellReader)
514       */
515      public JListFixture drag(String text) {
516        driver.drag(target, text);
517        return this;
518      }
519    
520      /**
521       * Ends a drag operation at the location of the first item matching the given value.
522       * @param text the text of the item to drop. It can be a regular expression.
523       * @return this fixture.
524       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
525       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
526       * @throws LocationUnavailableException if an element matching the given text cannot be found.
527       * @throws ActionFailedException if there is no drag action in effect.
528       */
529      public JListFixture drop(String text) {
530        driver.drop(target, text);
531        return this;
532      }
533    
534      /**
535       * Simulates a drag operation at the location of the first item in this fixture's <code>{@link JList}</code> matching
536       * the given regular expression pattern.
537       * @param pattern the regular expression pattern to match.
538       * @return this fixture.
539       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
540       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
541       * @throws NullPointerException if the given regular expression pattern in <code>null</code>.
542       * @throws LocationUnavailableException if an element matching the given regular expression pattern cannot be found.
543       * @see #cellReader(JListCellReader)
544       * @since 1.2
545       */
546      public JListFixture drag(Pattern pattern) {
547        driver.drag(target, pattern);
548        return this;
549      }
550    
551      /**
552       * Ends a drag operation at the location of the first item matching the given regular expression pattern.
553       * @param pattern the regular expression pattern to match.
554       * @return this fixture.
555       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
556       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
557       * @throws NullPointerException if the given regular expression pattern in <code>null</code>.
558       * @throws LocationUnavailableException if an element matching the given text cannot be found.
559       * @throws ActionFailedException if there is no drag action in effect.
560       * @see #cellReader(JListCellReader)
561       * @since 1.2
562       */
563      public JListFixture drop(Pattern pattern) {
564        driver.drop(target, pattern);
565        return this;
566      }
567    
568      /**
569       * Simulates a user dropping an item at the center of this fixture's <code>{@link JList}</code>.
570       * @return this fixture.
571       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
572       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
573       * @throws ActionFailedException if there is no drag action in effect.
574       */
575      public JListFixture drop() {
576        driver.drop(target);
577        return this;
578      }
579    
580      /**
581       * Simulates a user dragging an item from this fixture's <code>{@link JList}</code>.
582       * @param index the index of the item to drag.
583       * @return this fixture.
584       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
585       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
586       * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
587       * <code>JList</code>.
588       */
589      public JListFixture drag(int index) {
590        driver.drag(target, index);
591        return this;
592      }
593    
594      /**
595       * Simulates a user dropping an item to this fixture's <code>{@link JList}</code>.
596       * @param index the index of the item to drop.
597       * @return this fixture.
598       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
599       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
600       * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
601       * <code>JList</code>.
602       * @throws ActionFailedException if there is no drag action in effect.
603       */
604      public JListFixture drop(int index) {
605        driver.drop(target, index);
606        return this;
607      }
608    
609      /**
610       * Shows a pop-up menu at the location of the specified item in this fixture's <code>{@link JList}</code>.
611       * @param index the index of the item.
612       * @return a fixture that manages the displayed pop-up menu.
613       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
614       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
615       * @throws ComponentLookupException if a pop-up menu cannot be found.
616       * @throws IndexOutOfBoundsException if the given index is negative or greater than the index of the last item in the
617       * <code>JList</code>.
618       */
619      public JPopupMenuFixture showPopupMenuAt(int index) {
620        return new JPopupMenuFixture(robot, driver.showPopupMenu(target, index));
621      }
622    
623      /**
624       * Shows a pop-up menu at the location of the first item matching the given value in this fixture's
625       * <code>{@link JList}</code>.
626       * @param text the text of the item. It can be a regular expression.
627       * @return a fixture that manages the displayed pop-up menu.
628       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
629       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
630       * @throws ComponentLookupException if a pop-up menu cannot be found.
631       * @throws LocationUnavailableException if an element matching the given value cannot be found.
632       */
633      public JPopupMenuFixture showPopupMenuAt(String text) {
634        return new JPopupMenuFixture(robot, driver.showPopupMenu(target, text));
635      }
636    
637      /**
638       * Shows a pop-up menu at the location of the first item matching the given regular expression pattern in this
639       * fixture's <code>{@link JList}</code>.
640       * @param pattern the regular expression pattern to match.
641       * @return a fixture that manages the displayed pop-up menu.
642       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
643       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
644       * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
645       * @throws ComponentLookupException if a pop-up menu cannot be found.
646       * @throws LocationUnavailableException if an element matching the given value cannot be found.
647       * @since 1.2
648       */
649      public JPopupMenuFixture showPopupMenuAt(Pattern pattern) {
650        return new JPopupMenuFixture(robot, driver.showPopupMenu(target, pattern));
651      }
652    
653      /**
654       * Asserts that this fixture's <code>{@link JList}</code> has input focus.
655       * @return this fixture.
656       * @throws AssertionError if this fixture's <code>JList</code> does not have input focus.
657       */
658      public JListFixture requireFocused() {
659        driver.requireFocused(target);
660        return this;
661      }
662    
663      /**
664       * Asserts that this fixture's <code>{@link JList}</code> is enabled.
665       * @return this fixture.
666       * @throws AssertionError if this fixture's <code>JList</code> is disabled.
667       */
668      public JListFixture requireEnabled() {
669        driver.requireEnabled(target);
670        return this;
671      }
672    
673      /**
674       * Asserts that this fixture's <code>{@link JList}</code> is enabled.
675       * @param timeout the time this fixture will wait for the component to be enabled.
676       * @return this fixture.
677       * @throws WaitTimedOutError if this fixture's <code>JList</code> is never enabled.
678       */
679      public JListFixture requireEnabled(Timeout timeout) {
680        driver.requireEnabled(target, timeout);
681        return this;
682      }
683    
684      /**
685       * Asserts that this fixture's <code>{@link JList}</code> is not enabled.
686       * @return this fixture.
687       * @throws AssertionError if this fixture's <code>JList</code> is enabled.
688       */
689      public JListFixture requireDisabled() {
690        driver.requireDisabled(target);
691        return this;
692      }
693    
694      /**
695       * Asserts that this fixture's <code>{@link JList}</code> is visible.
696       * @return this fixture.
697       * @throws AssertionError if this fixture's <code>JList</code> is not visible.
698       */
699      public JListFixture requireVisible() {
700        driver.requireVisible(target);
701        return this;
702      }
703    
704      /**
705       * Asserts that this fixture's <code>{@link JList}</code> is not visible.
706       * @return this fixture.
707       * @throws AssertionError if this fixture's <code>JList</code> is visible.
708       */
709      public JListFixture requireNotVisible() {
710        driver.requireNotVisible(target);
711        return this;
712      }
713    
714      /**
715       * Verifies that the <code>String</code> representation of the selected item in this fixture's
716       * <code>{@link JList}</code> matches the given text.
717       * @param text the text to match. It can be a regular expression pattern.
718       * @return this fixture.
719       * @throws AssertionError if the selected item does not match the given text.
720       * @see #cellReader(JListCellReader)
721       */
722      public JListFixture requireSelection(String text) {
723        driver.requireSelection(target, text);
724        return this;
725      }
726    
727      /**
728       * Verifies that the <code>String</code> representation of the selected item in this fixture's
729       * <code>{@link JList}</code> matches the given regular expression pattern.
730       * @param pattern the regular expression pattern to match.
731       * @return this fixture.
732       * @throws AssertionError if the selected item does not match the given regular expression pattern.
733       * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
734       * @see #cellReader(JListCellReader)
735       * @since 1.2
736       */
737      public JListFixture requireSelection(Pattern pattern) {
738        driver.requireSelection(target, pattern);
739        return this;
740      }
741    
742      /**
743       * Verifies that the index of the selected item in this fixture's <code>{@link JList}</code> is equal to the given
744       * value.
745       * @param index the expected selection index.
746       * @return this fixture.
747       * @throws AssertionError if the selected index is not equal to the given one.
748       * @since 1.2
749       */
750      public JListFixture requireSelection(int index) {
751        driver.requireSelection(target, index);
752        return this;
753      }
754    
755      /**
756       * Verifies that the <code>String</code> representations of the selected items in this fixture's
757       * <code>{@link JList}</code> match the given text items.
758       * @param items text items to match. Each <code>String</code> can be a regular expression.
759       * @return this fixture.
760       * @throws NullPointerException if the given array is <code>null</code>.
761       * @throws IllegalArgumentException if the given array is empty.
762       * @throws AssertionError if the selected items do not match the given text items.
763       * @see #cellReader(JListCellReader)
764       */
765      public JListFixture requireSelectedItems(String... items) {
766        driver.requireSelectedItems(target, items);
767        return this;
768      }
769    
770      /**
771       * Verifies that the <code>String</code> representations of the selected items in this fixture's
772       * <code>{@link JList}</code> match the given regular expression patterns.
773       * @param patterns the regular expression patterns to match.
774       * @return this fixture.
775       * @throws NullPointerException if the given array is <code>null</code>.
776       * @throws IllegalArgumentException if the given array is empty.
777       * @throws NullPointerException if any of the patterns in the given array is <code>null</code>.
778       * @throws AssertionError if the selected items do not match the given regular expression patterns.
779       * @see #cellReader(JListCellReader)
780       * @since 1.2
781       */
782      public JListFixture requireSelectedItems(Pattern[] patterns) {
783        driver.requireSelectedItems(target, patterns);
784        return this;
785      }
786    
787      /**
788       * Verifies that the given item indices are selected in this fixture's <code>{@link JList}</code>.
789       * @param indices the expected indices of the selected items.
790       * @return this fixture.
791       * @throws NullPointerException if the given array is <code>null</code>.
792       * @throws IllegalArgumentException if the given array is empty.
793       * @throws AssertionError if the selection in this fixture's <code>JList</code> does not match the given one.
794       * @since 1.2
795       */
796      public JListFixture requireSelectedItems(int... indices) {
797        driver.requireSelectedItems(target, indices);
798        return this;
799      }
800    
801      /**
802       * Verifies that this fixture's <code>{@link JList}</code> does not have any selection.
803       * @return this fixture.
804       * @throws AssertionError if this fixture's <code>JList</code> has a selection.
805       */
806      public JListFixture requireNoSelection() {
807        driver.requireNoSelection(target);
808        return this;
809      }
810    
811      /**
812       * Verifies that this fixture's <code>{@link JList}</code> has the expected number of items
813       * @param expected the expected number of items.
814       * @return this fixture.
815       * @throws AssertionError if the number of items in this fixture's <code>JList</code> is not equal to the expected
816       * one.
817       * @since 1.2
818       */
819      public JListFixture requireItemCount(int expected) {
820        driver.requireItemCount(target, expected);
821        return this;
822      }
823    
824      /**
825       * Asserts that the toolTip in this fixture's <code>{@link JList}</code> matches the given value.
826       * @param expected the given value. It can be a regular expression.
827       * @return this fixture.
828       * @throws AssertionError if the toolTip in this fixture's <code>JList</code> does not match the given value.
829       * @since 1.2
830       */
831      public JListFixture requireToolTip(String expected) {
832        driver.requireToolTip(target, expected);
833        return this;
834      }
835    
836      /**
837       * Asserts that the toolTip in this fixture's <code>{@link JList}</code> matches the given regular expression
838       * pattern.
839       * @param pattern the regular expression pattern to match.
840       * @return this fixture.
841       * @throws NullPointerException if the given regular expression pattern is <code>null</code>.
842       * @throws AssertionError if the toolTip in this fixture's <code>JList</code> does not match the given regular
843       * expression pattern.
844       * @since 1.2
845       */
846      public JListFixture requireToolTip(Pattern pattern) {
847        driver.requireToolTip(target, pattern);
848        return this;
849      }
850    
851      /**
852       * Returns the client property stored in this fixture's <code>{@link JList}</code>, under the given key.
853       * @param key the key to use to retrieve the client property.
854       * @return the value of the client property stored under the given key, or <code>null</code> if the property was
855       * not found.
856       * @throws NullPointerException if the given key is <code>null</code>.
857       * @since 1.2
858       */
859      public Object clientProperty(Object key) {
860        return driver.clientProperty(target, key);
861      }
862    
863      /**
864       * Shows a pop-up menu using this fixture's <code>{@link JList}</code> as the invoker of the pop-up menu.
865       * @return a fixture that manages the displayed pop-up menu.
866       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
867       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
868       * @throws ComponentLookupException if a pop-up menu cannot be found.
869       */
870      public JPopupMenuFixture showPopupMenu() {
871        return new JPopupMenuFixture(robot, driver.invokePopupMenu(target));
872      }
873    
874      /**
875       * Shows a pop-up menu at the given point using this fixture's <code>{@link JList}</code> as the invoker of the pop-up
876       * menu.
877       * @param p the given point where to show the pop-up menu.
878       * @return a fixture that manages the displayed pop-up menu.
879       * @throws IllegalStateException if this fixture's <code>JList</code> is disabled.
880       * @throws IllegalStateException if this fixture's <code>JList</code> is not showing on the screen.
881       * @throws ComponentLookupException if a pop-up menu cannot be found.
882       */
883      public JPopupMenuFixture showPopupMenuAt(Point p) {
884        return new JPopupMenuFixture(robot, driver.invokePopupMenu(target, p));
885      }
886    
887      /**
888       * Updates the implementation of <code>{@link JListCellReader}</code> to use when comparing internal values of
889       * this fixture's <code>{@link JList}</code> and the values expected in a test. The default implementation to use
890       * is <code>{@link BasicJListCellReader}</code>.
891       * @param cellReader the new <code>JListCellValueReader</code> to use.
892       * @return this fixture.
893       * @throws NullPointerException if <code>cellReader</code> is <code>null</code>.
894       */
895      public JListFixture cellReader(JListCellReader cellReader) {
896        driver.cellReader(cellReader);
897        return this;
898      }
899    }