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

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