offapi/com/sun/star/ui/XImageManager.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XImageManager.idl,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_ui_XImageManager_idl__
  32 #define __com_sun_star_ui_XImageManager_idl__
  33
  34 #ifndef __com_sun_star_lang_XComponent_idl__
  35 #include <com/sun/star/lang/XComponent.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_graphic_XGraphic_idl__
  39 #include <com/sun/star/graphic/XGraphic.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_ui_XUIConfigurationListener_idl__
  43 #include <com/sun/star/ui/XUIConfigurationListener.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_ui_XUIConfigurationPersistence_idl__
  47 #include <com/sun/star/ui/XUIConfigurationPersistence.idl>
  48 #endif
  49
  50 #ifndef __com_sun_star_ui_XUIConfiguration_idl__
  51 #include <com/sun/star/ui/XUIConfiguration.idl>
  52 #endif
  53
  54 #ifndef __com_sun_star_ui_ImageType_idl__
  55 #include <com/sun/star/ui/ImageType.idl>
  56 #endif
  57
  58 #ifndef __com_sun_star_lang_XInitialization_idl__
  59 #include <com/sun/star/lang/XInitialization.idl>
  60 #endif
  61
  62 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  63 #include <com/sun/star/lang/IllegalArgumentException.idl>
  64 #endif
  65
  66 #ifndef __com_sun_star_lang_IllegalAccessException_idl__
  67 #include <com/sun/star/lang/IllegalAccessException.idl>
  68 #endif
  69
  70 module com { module sun { module star { module ui {
  71
  72 /** specifies access functions to an images manager interface to add,
  73     replace and remove images assocations to command URLs.
  74
  75     <p>
  76     An image manager controls a number of image sets which are specified
  77     by a <type>ImageType</type>.
  78     </p>
  79 */
  80
  81 interface XImageManager
  82 {
  83     /** resets the image manager to default data.
  84
  85         <p>
  86         This means that all user images of the instance will be removed.
  87         </p>
  88     */
  89     void reset();
  90
  91     /** retrieves the list of command URLs which have images associated.
  92
  93         @param nImageType
  94             specifies the image type for this operation.
  95
  96         @return
  97             all command URLs within the images manager that have an image
  98             associated.
  99     */
 100     sequence< string > getAllImageNames( [in] short nImageType );
 101
 102     /** determines if a command URL has an associated image.
 103
 104         @param nImageType
 105             specifies the image type for this operation.
 106
 107         @param ResourceURL
 108             a command URL that should be checked for an associated image.
 109
 110         @return
 111             <TRUE/> if an image is associated, otherwise <FALSE/>.
 112     */
 113     boolean hasImage( [in] short nImageType, [in] string aCommandURL ) raises ( com::sun::star::lang::IllegalArgumentException );
 114
 115     /** retrieves the associated images of command URLs.
 116
 117         @param nImageType
 118             specifies the image type for this association operation.
 119
 120         @param aCommandURLSequence
 121             a sequence of command URLs for which the images are requested.
 122
 123         @return
 124             a sequence of graphics object which are associated with the
 125             provided command URLs. If an unknown command URL is provided or
 126             a command URL has no associated image a graphics object with an
 127             empty image is provided. If the sequence
 128             <var>aCommandURLSequence</var> contains an invalid command
 129             URL a <type scope="com::sun::star::lang">IllegalArgumentException</type>
 130             is thrown.
 131     */
 132     sequence< ::com::sun::star::graphic::XGraphic > getImages( [in] short nImageType, [in] sequence< string > aCommandURLSequence ) raises ( com::sun::star::lang::IllegalArgumentException );
 133
 134     /** replaces the associated images of command URLs.
 135
 136         @param nImageType
 137             specifies the image type for this association operation.
 138
 139         @param aCommandURLSequence
 140             a sequence of command URLs for which images should be replaced.
 141
 142         @param aGraphicsSequence
 143             a sequence of graphic objects which should replace the old images
 144             of the provided command URLs.
 145
 146         <p>
 147         If a command URL cannot be found the replace call will be omitted. If
 148         <var>aCommandURLSequence</var> contains an invalid command URL a
 149         <type scope="com::sun::star::lang">IllegalArgumentException</type>
 150         is thrown. If the image manager is  associated with a read-only configuration
 151         manager a <type scope="com::sun::star::lang">IllegalAccessException</type>
 152         is thrown.
 153         </p>
 154     */
 155     void replaceImages( [in] short nImageType, [in] sequence< string > aCommandURLSequence, [in] sequence< ::com::sun::star::graphic::XGraphic > aGraphicsSequence ) raises ( com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
 156
 157     /** removes associated images to a command URL.
 158
 159         @param nImageType
 160             specifies the image type for this association operation.
 161
 162         @param aCommandURLSequence
 163             a sequence of command URLs for which the images should be removed.
 164
 165         <p>
 166         If the <var>aCommandURLSequence</var> contains an invalid command URL a
 167         <type scope="com::sun::star::lang">IllegalArgumentException</type> is
 168         thrown. If  the image manager is associated with a read-only configuration
 169         manager a <type scope="com::sun::star::lang">IllegalAccessException</type>
 170         is thrown.
 171         </p>
 172     */
 173     void removeImages( [in] short nImageType, [in] sequence< string > aResourceURLSequence ) raises ( com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
 174
 175     /** inserts new image/command associations to a image manager.
 176
 177         @param nImageType
 178             specifies the image type for this association operation.
 179
 180         @param aCommandURLSequence
 181             a sequence of command URLs which specify which commands get an new image.
 182
 183         @param aGraphicSequence
 184             a sequence of graphic objects which should be associated with the provided
 185             command URLs.
 186
 187         <p>
 188         If an association is already present it is replaced. If
 189         <var>aCommandURLSequence</var> contains an invalid command URL a
 190         <type scope="com::sun::star::lang">IllegalArgumentException</type>
 191         is thrown. If the configuration manager is read-only a
 192         <type scope="com::sun::star::lang">IllegalAccessException</type> is
 193         thrown.
 194         </p>
 195     */
 196     void insertImages( [in] short nImageType, [in] sequence< string > aCommandURLSequence, [in] sequence< ::com::sun::star::graphic::XGraphic > aGraphicSequence ) raises ( com::sun::star::container::ElementExistException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
 197
 198     /** provides access to persistence functions to load/store images
 199         data from a storage.
 200     */
 201     interface com::sun::star::ui::XUIConfigurationPersistence;
 202
 203     /** provides functions to add and remove listeners for changes within an
 204         image manager.
 205
 206         <p>
 207         An image manager implementation notifies its listener whenever an image
 208         set has been changed, due to insert, remove or replace operations. To
 209         minimize the overhead for notifications an image manager places all
 210         inserted and/or replaced images into a single notify call. A container
 211         which implements <type scope="com::sun::star::container">XNameAccess</type>
 212         holds the information. The access key is a command URL and provides a
 213         <type scope="::com::sun::star::graphic">XGraphic</type>. This container
 214         is placed into  the
 215         <member scope="com::sun::star::ui">ConfigurationEvent::Element</member>.
 216         The image set which has been changed is put into the
 217         <member scope="com::sun::star::ui">ConfigurationEvent::aInfo</member>.
 218         </p>
 219     */
 220     interface com::sun::star::ui::XUIConfiguration;
 221
 222     /** allows controlling or observing the lifetime of an imahge manager
 223         instance.
 224
 225     <p>The owner of the object may dispose of this object using
 226     <member scope="com::sun::star::lang">XComponent::dispose()</member>.
 227     </p>
 228     */
 229     interface ::com::sun::star::lang::XComponent;
 230
 231     /** initializes an image manager instance.
 232
 233         An image manager instance must be initialized using
 234         <member scope=com::sun::star::lang>XInitialization::initialize</member>
 235         before it can be used.<br>
 236         The following property must be provided if the image manager is
 237         related to a module:
 238         <ul>
 239             <li><b>ModuleIdentifier</b>specifies a string property which is the
 240             unique identifier of module.
 241             </li>
 242             <li><b>UserConfigStorage</b>specifies a
 243             <type scope="com::sun::star::embed">XStorage</type> property which
 244             provides access to the configuration storage of the module.
 245             </li>
 246             <li><b>UserRootCommit</b>specifies an optional
 247             <type scope="com::sun::star::embed">XTransactedObject</type>
 248             property which makes it possible to commit a root storage.
 249             </li>
 250         </ul>
 251     */
 252     interface ::com::sun::star::lang::XInitialization;
 253 };
 254
 255 //=============================================================================
 256
 257 }; }; }; };
 258
 259 #endif