offapi/com/sun/star/ui/XUIConfigurationManager.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: XUIConfigurationManager.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_XUIConfigurationManager_idl__
  32 #define __com_sun_star_ui_XUIConfigurationManager_idl__
  33
  34 #ifndef __com_sun_star_container_XIndexContainer_idl__
  35 #include <com/sun/star/container/XIndexContainer.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_container_XIndexAccess_idl__
  39 #include <com/sun/star/container/XIndexAccess.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_beans_XPropertySet_idl__
  43 #include <com/sun/star/beans/XPropertySet.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_beans_PropertyValue_idl__
  47 #include <com/sun/star/beans/PropertyValue.idl>
  48 #endif
  49
  50 #ifndef __com_sun_star_ui_XUIConfigurationListener_idl__
  51 #include <com/sun/star/ui/XUIConfigurationListener.idl>
  52 #endif
  53
  54 #ifndef __com_sun_star_container_ElementExistException_idl__
  55 #include <com/sun/star/container/ElementExistException.idl>
  56 #endif
  57
  58 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  59 #include <com/sun/star/container/NoSuchElementException.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 a user interface configuration manager interface which
  73     controls the structure of all customizable user interface
  74     elements.
  75
  76     @since OOo 2.0.0
  77 */
  78
  79 interface XUIConfigurationManager : ::com::sun::star::uno::XInterface
  80 {
  81     /** resets the configuration manager to the default user interface
  82         configuration data.
  83         <p>
  84         This means that all user interface configuration data of the
  85         instance will be removed. A module based user interface
  86         configuration manager removes user defined elements, but set all
  87         other elements back to default. It is not possible to remove
  88         default elements from a module user interface configuration
  89         manager.
  90         </p>
  91     */
  92     void reset();
  93
  94     /** retrieves information about all user interface elements within
  95         the user interface configuration manager.
  96
  97         @param ElementType
  98             makes it possible to narrow the result set to only one type
  99             of user interface elements. If all user interface element
 100             types should be returned
 101             <value scope=com::sun::star::ui>UIElementType::UNKNOWN</value>
 102             must be provided.
 103
 104         @return
 105             returns all user interface elements within the user interface
 106             configuration manager that meet the given ElementType
 107             specification. <p>The following
 108             <type scope="com::sun::star::beans">PropertyValue</type> entries
 109             are defined inside the sequence for every user interface element.
 110             <ul>
 111                 <li><b>ResourceURL<b/>specifies the unique resource URL for
 112                 the user interface element.</li>
 113                 <li><b>UIName<b/>specifies the user interface name for the
 114                 user interface element. Not all user interface elements have
 115                 set UIName. At least menubars do not.</li>
 116             </ul>
 117             <p>
 118
 119         @see UIElementType
 120     */
 121     sequence< sequence< com::sun::star::beans::PropertyValue > > getUIElementsInfo( [in] short ElementType ) raises ( com::sun::star::lang::IllegalArgumentException );
 122
 123     /** creates an empty settings data container.
 124
 125         @return
 126             an empty user interface element settings data container, which
 127             implements <type>UIElementSettings</type>.
 128     */
 129     ::com::sun::star::container::XIndexContainer createSettings();
 130
 131     /** determines if the settings of a user interface element is part the
 132         user interface configuration manager.
 133
 134         @param ResourceURL
 135             a resource URL which identifies the user interface element. A
 136             resourcce URL must meet the following syntax:
 137             "private:resource/$type/$name. It is only allowed to use ascii
 138             characters for type and name.
 139
 140         @return
 141             <TRUE/> if settings have been found, otherwise <FALSE/>.
 142     */
 143     boolean hasSettings( [in] string ResourceURL ) raises ( com::sun::star::lang::IllegalArgumentException );
 144
 145     /** retrieves the settings of a user interface element.
 146
 147         @param ResourceURL
 148             a resource URL which identifies the user interface element. A
 149             resourcce URL must meet the following syntax:
 150             "private:resource/$type/$name. It is only allowed to use ascii
 151             characters for type and name.
 152
 153         @param bWriteable
 154             must be <TRUE/> if the retrieved settings should be a writeable.
 155             Otherwise <FALSE/> should be provided to get a shareable reference
 156             to the settings data.
 157
 158         @return
 159             settings data of an existing user interface element, which
 160             implements <type>UIElementSettings</type>. If the settings data
 161             cannot be found a
 162             <type scope="com::sun::star::container">NoSuchElementException</type>
 163             is thrown.  If the <member>ResourceURL</member> is not valid or
 164             describes an unknown type a
 165             <type scope="com::sun::star::lang">IllegalArgumentException</type>
 166             is thrown.
 167     */
 168     ::com::sun::star::container::XIndexAccess getSettings( [in] string ResourceURL, [in] boolean bWriteable ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException );
 169
 170     /** replaces the settings of a user interface element with new settings.
 171
 172         @param ResourceURL
 173             a resource URL which identifies the user interface element to
 174             be replaced. If no element with the given resource URL exists a
 175             <type scope="com::sun::star::container">NoSuchElementException</type>
 176             is thrown.
 177
 178         @param aNewData
 179             the new settings data of an existing user interface element, which
 180             implements <type>UIElementSettings</type>.
 181
 182         <p>
 183         If the settings data cannot be found a
 184         <type scope="com::sun::star::container">NoSuchElementException</type>
 185         is thrown. If the <member>ResourceURL</member> is not valid or describes
 186         an unknown type 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 replaceSettings( [in] string ResourceURL, [in] ::com::sun::star::container::XIndexAccess aNewData ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
 194
 195     /** removes the settings of an existing user interface element.
 196
 197         @param ResourceURL
 198             a resource URL which identifies the user interface element settings
 199             to be removed.
 200
 201         <p>
 202         If the settings data cannot be found a
 203         <type scope="com::sun::star::container">NoSuchElementException</type> is
 204         thrown. If the <member>ResourceURL</member> is not valid or describes an
 205         unknown type a <type scope="com::sun::star::lang">IllegalArgumentException</type>
 206         is thrown. If the configuration manager is read-only a
 207         <type scope="com::sun::star::lang">IllegalAccessException</type> is thrown.
 208         </p>
 209     */
 210     void removeSettings( [in] string ResourceURL ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
 211
 212     /** inserts the settings of a new user interface element.
 213
 214         @param ResourceURL
 215             a resource URL which identifies the new user interface element.
 216
 217         @param aNewData
 218             the settings data of the new user interface element, which implements
 219             <type>UIElementSettings</type>.
 220
 221         <p>
 222         If the settings data is already present a
 223         <type scope="com::sun::star::container">ElementExistException</type>
 224         is thrown. If the <member>ResourceURL</member> is not valid or describes
 225         an unknown type a <type scope="com::sun::star::lang">IllegalArgumentException</type>
 226         is thrown. If the configuration manager is read-only a
 227         <type scope="com::sun::star::lang">IllegalAccessException</type> is thrown.
 228         </p>
 229     */
 230     void insertSettings( [in] string NewResourceURL, [in] ::com::sun::star::container::XIndexAccess aNewData ) raises ( com::sun::star::container::ElementExistException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
 231
 232     /** retrieves the image manager from the user interface configuration
 233         manager.
 234
 235         <p>
 236         Every user interface configuration manager has one image manager
 237         instance which controls all images of a module or document.
 238         </p>
 239
 240         @return
 241             the image manager of the user interface configuration manager.
 242     */
 243     com::sun::star::uno::XInterface getImageManager();
 244
 245     /** retrieves the keyboard short cut manager from the user interface
 246         configuration manager.
 247
 248         <p>
 249         Every user interface configuration manager has one keyboard short cut
 250         manager instance which controls all short cuts of a module or document.
 251         </p>
 252
 253         @return
 254             the short cut manager of the user interface configuration manager.
 255     */
 256     com::sun::star::uno::XInterface getShortCutManager();
 257
 258     /** retrieves the events manager from the user interface configuration manager.
 259
 260         <p>
 261         Every user interface configuration manager has one events manager
 262         instance which controls the mapping of events to script URLs of a module
 263         or document.
 264         </p>
 265
 266         @return
 267             the events manager of the user interface configuration
 268             manager, if one exists.
 269     */
 270     com::sun::star::uno::XInterface getEventsManager();
 271 };
 272
 273 //=============================================================================
 274
 275 }; }; }; };
 276
 277 #endif