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
67module 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
78published 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
257