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