xref: /trunk/main/offapi/com/sun/star/awt/XItemList.idl (revision d1766043)
1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __offapi_com_sun_star_awt_XItemList_idl__
25#define __offapi_com_sun_star_awt_XItemList_idl__
26
27#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
28#include <com/sun/star/beans/Pair.idl>
29
30//==================================================================================================================
31
32module com { module sun { module star { module awt {
33
34published interface XItemListListener;
35
36//==================================================================================================================
37
38/** provides convenient access to the list of items in a list box
39 */
40published interface XItemList
41{
42    /** is the number of items in the list
43    */
44    [attribute, readonly]   long    ItemCount;
45
46    /** inserts a new item into the list
47
48        @param Position
49            the position at which the item should be inserted. Must be greater or equal to 0, and
50            lesser than or equal to <member>ItemCount</member>.
51
52        @param ItemText
53            the text of the item to be inserted.
54
55        @param ItemImageURL
56            the URL of the image to display for the item
57
58        @throws ::com::sun::star::lang::IndexOutOfBoundsException
59            if <code>Position</code> is invalid.
60    */
61    void    insertItem(
62                [in] long Position,
63                [in] string ItemText,
64                [in] string ItemImageURL
65            )
66            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
67
68    /** inserts an item which has only a text, but no image
69
70        @param Position
71            the position at which the item should be inserted. Must be greater or equal to 0, and
72            lesser than or equal to <member>ItemCount</member>.
73
74        @param ItemText
75            the text of the item to be inserted.
76
77        @throws ::com::sun::star::lang::IndexOutOfBoundsException
78            if <code>Position</code> is invalid.
79    */
80    void    insertItemText(
81                [in] long Position,
82                [in] string ItemText
83            )
84            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
85
86    /** inserts an item which has only an image, but no text
87
88        @param Position
89            the position at which the item should be inserted. Must be greater or equal to 0, and
90            lesser than or equal to <member>ItemCount</member>.
91
92        @param ItemImageURL
93            the URL of the image to display for the item
94
95        @throws ::com::sun::star::lang::IndexOutOfBoundsException
96            if <code>Position</code> is invalid.
97    */
98    void    insertItemImage(
99                [in] long Position,
100                [in] string ItemImageURL
101            )
102            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
103
104    /** removes an item from the list
105
106        @param Position
107            the position of the item which should be removed. Must be greater or equal to 0, and
108            lesser than <member>ItemCount</member>.
109
110        @throws ::com::sun::star::lang::IndexOutOfBoundsException
111            if <code>Position</code> is invalid.
112    */
113    void    removeItem(
114                [in] long Position
115            )
116            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
117
118    /** removes all items from the list
119    */
120    void    removeAllItems();
121
122    /** sets a new text for an existing item
123
124        @param Position
125            the position of the item whose text is to be changed. Must be greater or equal to 0, and
126            lesser than <member>ItemCount</member>.
127
128        @param ItemText
129            the new text of the item
130
131        @throws ::com::sun::star::lang::IndexOutOfBoundsException
132            if <code>Position</code> is invalid.
133    */
134    void    setItemText(
135                [in] long Position,
136                [in] string ItemText
137            )
138            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
139
140    /** sets a new image for an existing item
141
142        @param Position
143            the position of the item whose image is to be changed. Must be greater or equal to 0, and
144            lesser than <member>ItemCount</member>.
145
146        @param ItemImageURL
147            the new URL of the image to display for the item
148
149        @throws ::com::sun::star::lang::IndexOutOfBoundsException
150            if <code>Position</code> is invalid.
151    */
152    void    setItemImage(
153                [in] long Position,
154                [in] string ItemImageURL
155            )
156            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
157
158    /** sets both a new position and text for an existing item
159
160        @param Position
161            the position of the item whose text and image is to be changed. Must be greater or equal to 0, and
162            lesser than <member>ItemCount</member>.
163
164        @param ItemText
165            the new text of the item
166
167        @param ItemImageURL
168            the new URL of the image to display for the item
169
170        @throws ::com::sun::star::lang::IndexOutOfBoundsException
171            if <code>Position</code> is invalid.
172    */
173    void    setItemTextAndImage(
174                [in] long Position,
175                [in] string ItemText,
176                [in] string ItemImageURL
177            )
178            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
179
180    /** associates an implementation dependend value with the given list item.
181
182        <p>You can use this to store data for an item which does not interfere with the displayed
183        text and image, but can be used by the client of the list box for an arbitrary purpose.</p>
184
185        @param Position
186            the position of the item whose data value should be set. Must be greater or equal to 0, and
187            lesser than <member>ItemCount</member>.
188
189        @param ItemData
190            the data to associate with the list item
191
192        @throws ::com::sun::star::lang::IndexOutOfBoundsException
193            if <code>Position</code> is invalid.
194
195        @see getItemData
196    */
197    void    setItemData(
198                [in] long Position,
199                [in] any ItemData
200            )
201            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
202
203    /** retrieves the text of an existing item
204
205        @param Position
206            the position of the item whose text should be retrieved. Must be greater or equal to 0, and
207            lesser than <member>ItemCount</member>.
208
209        @throws ::com::sun::star::lang::IndexOutOfBoundsException
210            if <code>Position</code> is invalid.
211    */
212    string  getItemText(
213                [in] long Position
214            )
215            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
216
217    /** retrieves the URL of the image of an existing item
218
219        @param Position
220            the position of the item whose image should be retrieved. Must be greater or equal to 0, and
221            lesser than <member>ItemCount</member>.
222
223        @throws ::com::sun::star::lang::IndexOutOfBoundsException
224            if <code>Position</code> is invalid.
225    */
226    string  getItemImage(
227                [in] long Position
228            )
229            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
230
231    /** retrieves both the text and the image URL of an existing item
232
233        @param Position
234            the position of the item whose text and image should be retrieved. Must be greater or equal to 0, and
235            lesser than <member>ItemCount</member>.
236
237        @throws ::com::sun::star::lang::IndexOutOfBoundsException
238            if <code>Position</code> is invalid.
239    */
240    ::com::sun::star::beans::Pair< string, string >
241            getItemTextAndImage(
242                [in] long Position
243            )
244            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
245
246    /** retrieves the implementation dependend value associated with the given list item.
247        @see setItemData
248
249        @param Position
250            the position of the item whose data value should be retrieved. Must be greater or equal to 0, and
251            lesser than <member>ItemCount</member>.
252
253        @throws ::com::sun::star::lang::IndexOutOfBoundsException
254            if <code>Position</code> is invalid.
255
256        @see setItemData
257    */
258    any     getItemData(
259                [in] long Position
260            )
261            raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
262
263    /** retrieves the texts and images of all items in the list
264    */
265    sequence< ::com::sun::star::beans::Pair< string, string > >
266            getAllItems();
267
268    /** registers a listener which is notified about changes in the item list.
269    */
270    void addItemListListener( [in] XItemListListener Listener );
271
272    /** revokes a listener which is notified about changes in the item list.
273    */
274    void removeItemListListener( [in] XItemListListener Listener );
275};
276
277//==================================================================================================================
278
279}; }; }; };
280
281//==================================================================================================================
282
283#endif
284