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

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