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

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