offapi/com/sun/star/awt/XItemList.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 #ifndef __offapi_com_sun_star_awt_XItemList_idl__
  29 #define __offapi_com_sun_star_awt_XItemList_idl__
  30
  31 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  32 #include <com/sun/star/beans/Pair.idl>
  33
  34 //==================================================================================================================
  35
  36 module com { module sun { module star { module awt {
  37
  38 interface XItemListListener;
  39
  40 //==================================================================================================================
  41
  42 /** provides convenient access to the list of items in a list box
  43  */
  44 interface XItemList
  45 {
  46     /** is the number of items in the list
  47     */
  48     [attribute, readonly]   long    ItemCount;
  49
  50     /** inserts a new item into the list
  51
  52         @param Position
  53             the position at which the item should be inserted. Must be greater or equal to 0, and
  54             lesser than or equal to <member>ItemCount</member>.
  55
  56         @param ItemText
  57             the text of the item to be inserted.
  58
  59         @param ItemImageURL
  60             the URL of the image to display for the item
  61
  62         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  63             if <code>Position</code> is invalid.
  64     */
  65     void    insertItem(
  66                 [in] long Position,
  67                 [in] string ItemText,
  68                 [in] string ItemImageURL
  69             )
  70             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
  71
  72     /** inserts an item which has only a text, but no image
  73
  74         @param Position
  75             the position at which the item should be inserted. Must be greater or equal to 0, and
  76             lesser than or equal to <member>ItemCount</member>.
  77
  78         @param ItemText
  79             the text of the item to be inserted.
  80
  81         @throws ::com::sun::star::lang::IndexOutOfBoundsException
  82             if <code>Position</code> is invalid.
  83     */
  84     void    insertItemText(
  85                 [in] long Position,
  86                 [in] string ItemText
  87             )
  88             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
  89
  90     /** inserts an item which has only an image, but no text
  91
  92         @param Position
  93             the position at which the item should be inserted. Must be greater or equal to 0, and
  94             lesser than or equal to <member>ItemCount</member>.
  95
  96         @param ItemImageURL
  97             the URL of the image to display for the item
  98
  99         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 100             if <code>Position</code> is invalid.
 101     */
 102     void    insertItemImage(
 103                 [in] long Position,
 104                 [in] string ItemImageURL
 105             )
 106             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 107
 108     /** removes an item from the list
 109
 110         @param Position
 111             the position of the item which should be removed. Must be greater or equal to 0, and
 112             lesser than <member>ItemCount</member>.
 113
 114         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 115             if <code>Position</code> is invalid.
 116     */
 117     void    removeItem(
 118                 [in] long Position
 119             )
 120             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 121
 122     /** removes all items from the list
 123     */
 124     void    removeAllItems();
 125
 126     /** sets a new text for an existing item
 127
 128         @param Position
 129             the position of the item whose text is to be changed. Must be greater or equal to 0, and
 130             lesser than <member>ItemCount</member>.
 131
 132         @param ItemText
 133             the new text of the item
 134
 135         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 136             if <code>Position</code> is invalid.
 137     */
 138     void    setItemText(
 139                 [in] long Position,
 140                 [in] string ItemText
 141             )
 142             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 143
 144     /** sets a new image for an existing item
 145
 146         @param Position
 147             the position of the item whose image is to be changed. Must be greater or equal to 0, and
 148             lesser than <member>ItemCount</member>.
 149
 150         @param ItemImageURL
 151             the new URL of the image to display for the item
 152
 153         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 154             if <code>Position</code> is invalid.
 155     */
 156     void    setItemImage(
 157                 [in] long Position,
 158                 [in] string ItemImageURL
 159             )
 160             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 161
 162     /** sets both a new position and text for an existing item
 163
 164         @param Position
 165             the position of the item whose text and image is to be changed. Must be greater or equal to 0, and
 166             lesser than <member>ItemCount</member>.
 167
 168         @param ItemText
 169             the new text of the item
 170
 171         @param ItemImageURL
 172             the new URL of the image to display for the item
 173
 174         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 175             if <code>Position</code> is invalid.
 176     */
 177     void    setItemTextAndImage(
 178                 [in] long Position,
 179                 [in] string ItemText,
 180                 [in] string ItemImageURL
 181             )
 182             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 183
 184     /** associates an implementation dependent value with the given list item.
 185
 186         <p>You can use this to store data for an item which does not interfere with the displayed
 187         text and image, but can be used by the client of the list box for an arbitrary purpose.</p>
 188
 189         @param Position
 190             the position of the item whose data value should be set. Must be greater or equal to 0, and
 191             lesser than <member>ItemCount</member>.
 192
 193         @param ItemData
 194             the data to associate with the list item
 195
 196         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 197             if <code>Position</code> is invalid.
 198
 199         @see getItemData
 200     */
 201     void    setItemData(
 202                 [in] long Position,
 203                 [in] any ItemData
 204             )
 205             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 206
 207     /** retrieves the text of an existing item
 208
 209         @param Position
 210             the position of the item whose text should be retrieved. Must be greater or equal to 0, and
 211             lesser than <member>ItemCount</member>.
 212
 213         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 214             if <code>Position</code> is invalid.
 215     */
 216     string  getItemText(
 217                 [in] long Position
 218             )
 219             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 220
 221     /** retrieves the URL of the image of an existing item
 222
 223         @param Position
 224             the position of the item whose image should be retrieved. Must be greater or equal to 0, and
 225             lesser than <member>ItemCount</member>.
 226
 227         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 228             if <code>Position</code> is invalid.
 229     */
 230     string  getItemImage(
 231                 [in] long Position
 232             )
 233             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 234
 235     /** retrieves both the text and the image URL of an existing item
 236
 237         @param Position
 238             the position of the item whose text and image should be retrieved. Must be greater or equal to 0, and
 239             lesser than <member>ItemCount</member>.
 240
 241         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 242             if <code>Position</code> is invalid.
 243     */
 244     ::com::sun::star::beans::Pair< string, string >
 245             getItemTextAndImage(
 246                 [in] long Position
 247             )
 248             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 249
 250     /** retrieves the implementation dependent value associated with the given list item.
 251         @see setItemData
 252
 253         @param Position
 254             the position of the item whose data value should be retrieved. Must be greater or equal to 0, and
 255             lesser than <member>ItemCount</member>.
 256
 257         @throws ::com::sun::star::lang::IndexOutOfBoundsException
 258             if <code>Position</code> is invalid.
 259
 260         @see setItemData
 261     */
 262     any     getItemData(
 263                 [in] long Position
 264             )
 265             raises  ( ::com::sun::star::lang::IndexOutOfBoundsException );
 266
 267     /** retrieves the texts and images of all items in the list
 268     */
 269     sequence< ::com::sun::star::beans::Pair< string, string > >
 270             getAllItems();
 271
 272     /** registers a listener which is notified about changes in the item list.
 273     */
 274     void addItemListListener( [in] XItemListListener Listener );
 275
 276     /** revokes a listener which is notified about changes in the item list.
 277     */
 278     void removeItemListListener( [in] XItemListListener Listener );
 279 };
 280
 281 //==================================================================================================================
 282
 283 }; }; }; };
 284
 285 //==================================================================================================================
 286
 287 #endif
 288
 289 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */