1<?php
2
3namespace Facebook\WebDriver;
4
5use Facebook\WebDriver\Exception\NoSuchElementException;
6use Facebook\WebDriver\Exception\UnsupportedOperationException;
7
8/**
9 * Models an element of select type, providing helper methods to select and deselect options.
10 */
11interface WebDriverSelectInterface
12{
13    /**
14     * @return bool Whether this select element support selecting multiple options.
15     */
16    public function isMultiple();
17
18    /**
19     * @return WebDriverElement[] All options belonging to this select tag.
20     */
21    public function getOptions();
22
23    /**
24     * @return WebDriverElement[] All selected options belonging to this select tag.
25     */
26    public function getAllSelectedOptions();
27
28    /**
29     * @throws NoSuchElementException
30     *
31     * @return WebDriverElement The first selected option in this select tag (or the currently selected option in a
32     * normal select)
33     */
34    public function getFirstSelectedOption();
35
36    /**
37     * Select the option at the given index.
38     *
39     * @param int $index The index of the option. (0-based)
40     *
41     * @throws NoSuchElementException
42     */
43    public function selectByIndex($index);
44
45    /**
46     * Select all options that have value attribute matching the argument. That is, when given "foo" this would
47     * select an option like:
48     *
49     * `<option value="foo">Bar</option>`
50     *
51     * @param string $value The value to match against.
52     *
53     * @throws NoSuchElementException
54     */
55    public function selectByValue($value);
56
57    /**
58     * Select all options that display text matching the argument. That is, when given "Bar" this would
59     * select an option like:
60     *
61     * `<option value="foo">Bar</option>`
62     *
63     * @param string $text The visible text to match against.
64     *
65     * @throws NoSuchElementException
66     */
67    public function selectByVisibleText($text);
68
69    /**
70     * Select all options that display text partially matching the argument. That is, when given "Bar" this would
71     * select an option like:
72     *
73     * `<option value="bar">Foo Bar Baz</option>`
74     *
75     * @param string $text The visible text to match against.
76     *
77     * @throws NoSuchElementException
78     */
79    public function selectByVisiblePartialText($text);
80
81    /**
82     * Deselect all options in multiple select tag.
83     *
84     * @throws UnsupportedOperationException If the SELECT does not support multiple selections
85     */
86    public function deselectAll();
87
88    /**
89     * Deselect the option at the given index.
90     *
91     * @param int $index The index of the option. (0-based)
92     * @throws UnsupportedOperationException If the SELECT does not support multiple selections
93     */
94    public function deselectByIndex($index);
95
96    /**
97     * Deselect all options that have value attribute matching the argument. That is, when given "foo" this would
98     * deselect an option like:
99     *
100     * `<option value="foo">Bar</option>`
101     *
102     * @param string $value The value to match against.
103     * @throws UnsupportedOperationException If the SELECT does not support multiple selections
104     */
105    public function deselectByValue($value);
106
107    /**
108     * Deselect all options that display text matching the argument. That is, when given "Bar" this would
109     * deselect an option like:
110     *
111     * `<option value="foo">Bar</option>`
112     *
113     * @param string $text The visible text to match against.
114     * @throws UnsupportedOperationException If the SELECT does not support multiple selections
115     */
116    public function deselectByVisibleText($text);
117
118    /**
119     * Deselect all options that display text matching the argument. That is, when given "Bar" this would
120     * deselect an option like:
121     *
122     * `<option value="foo">Foo Bar Baz</option>`
123     *
124     * @param string $text The visible text to match against.
125     * @throws UnsupportedOperationException If the SELECT does not support multiple selections
126     */
127    public function deselectByVisiblePartialText($text);
128}
129