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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /**
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __com_sun_star_ui_XUIConfigurationManager_idl__
  21 #define __com_sun_star_ui_XUIConfigurationManager_idl__
  22
  23 #include <com/sun/star/container/XIndexContainer.idl>
  24 #include <com/sun/star/container/XIndexAccess.idl>
  25 #include <com/sun/star/beans/XPropertySet.idl>
  26 #include <com/sun/star/beans/PropertyValue.idl>
  27 #include <com/sun/star/ui/XUIConfigurationListener.idl>
  28 #include <com/sun/star/container/ElementExistException.idl>
  29 #include <com/sun/star/container/NoSuchElementException.idl>
  30 #include <com/sun/star/lang/IllegalArgumentException.idl>
  31 #include <com/sun/star/lang/IllegalAccessException.idl>
  32
  33 module com { module sun { module star { module ui {
  34
  35 /** specifies a user interface configuration manager interface which
  36     controls the structure of all customizable user interface
  37     elements.
  38
  39     @since OOo 2.0
  40 */
  41
  42 interface XUIConfigurationManager : ::com::sun::star::uno::XInterface
  43 {
  44     /** resets the configuration manager to the default user interface
  45         configuration data.
  46         <p>
  47         This means that all user interface configuration data of the
  48         instance will be removed. A module based user interface
  49         configuration manager removes user defined elements, but set all
  50         other elements back to default. It is not possible to remove
  51         default elements from a module user interface configuration
  52         manager.
  53         </p>
  54     */
  55     void reset();
  56
  57     /** retrieves information about all user interface elements within
  58         the user interface configuration manager.
  59
  60         @param ElementType
  61             makes it possible to narrow the result set to only one type
  62             of user interface elements. If all user interface element
  63             types should be returned
  64             <value scope=com::sun::star::ui>UIElementType::UNKNOWN</value>
  65             must be provided.
  66
  67         @return
  68             returns all user interface elements within the user interface
  69             configuration manager that meet the given ElementType
  70             specification. <p>The following
  71             <type scope="com::sun::star::beans">PropertyValue</type> entries
  72             are defined inside the sequence for every user interface element.
  73             <ul>
  74                 <li><b>ResourceURL<b/>specifies the unique resource URL for
  75                 the user interface element.</li>
  76                 <li><b>UIName<b/>specifies the user interface name for the
  77                 user interface element. Not all user interface elements have
  78                 set UIName. At least menubars do not.</li>
  79             </ul>
  80             <p>
  81
  82         @see UIElementType
  83     */
  84     sequence< sequence< com::sun::star::beans::PropertyValue > > getUIElementsInfo( [in] short ElementType ) raises ( com::sun::star::lang::IllegalArgumentException );
  85
  86     /** creates an empty settings data container.
  87
  88         @return
  89             an empty user interface element settings data container, which
  90             implements <type>UIElementSettings</type>.
  91     */
  92     ::com::sun::star::container::XIndexContainer createSettings();
  93
  94     /** determines if the settings of a user interface element is part the
  95         user interface configuration manager.
  96
  97         @param ResourceURL
  98             a resource URL which identifies the user interface element. A
  99             resource URL must meet the following syntax:
 100             "private:resource/$type/$name. It is only allowed to use ASCII
 101             characters for type and name.
 102
 103         @return
 104             <TRUE/> if settings have been found, otherwise <FALSE/>.
 105     */
 106     boolean hasSettings( [in] string ResourceURL ) raises ( com::sun::star::lang::IllegalArgumentException );
 107
 108     /** retrieves the settings of a user interface element.
 109
 110         @param ResourceURL
 111             a resource URL which identifies the user interface element. A
 112             resource URL must meet the following syntax:
 113             "private:resource/$type/$name. It is only allowed to use ASCII
 114             characters for type and name.
 115
 116         @param bWriteable
 117             must be <TRUE/> if the retrieved settings should be a writable.
 118             Otherwise <FALSE/> should be provided to get a shareable reference
 119             to the settings data.
 120
 121         @return
 122             settings data of an existing user interface element, which
 123             implements <type>UIElementSettings</type>. If the settings data
 124             cannot be found a
 125             <type scope="com::sun::star::container">NoSuchElementException</type>
 126             is thrown.  If the <member>ResourceURL</member> is not valid or
 127             describes an unknown type a
 128             <type scope="com::sun::star::lang">IllegalArgumentException</type>
 129             is thrown.
 130     */
 131     ::com::sun::star::container::XIndexAccess getSettings( [in] string ResourceURL, [in] boolean bWriteable ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException );
 132
 133     /** replaces the settings of a user interface element with new settings.
 134
 135         @param ResourceURL
 136             a resource URL which identifies the user interface element to
 137             be replaced. If no element with the given resource URL exists a
 138             <type scope="com::sun::star::container">NoSuchElementException</type>
 139             is thrown.
 140
 141         @param aNewData
 142             the new settings data of an existing user interface element, which
 143             implements <type>UIElementSettings</type>.
 144
 145         <p>
 146         If the settings data cannot be found a
 147         <type scope="com::sun::star::container">NoSuchElementException</type>
 148         is thrown. If the <member>ResourceURL</member> is not valid or describes
 149         an unknown type a
 150         <type scope="com::sun::star::lang">IllegalArgumentException</type>
 151         is thrown. If the configuration manager is read-only a
 152         <type scope="com::sun::star::lang">IllegalAccessException</type> is
 153         thrown.
 154         </p>
 155     */
 156     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 );
 157
 158     /** removes the settings of an existing user interface element.
 159
 160         @param ResourceURL
 161             a resource URL which identifies the user interface element settings
 162             to be removed.
 163
 164         <p>
 165         If the settings data cannot be found a
 166         <type scope="com::sun::star::container">NoSuchElementException</type> is
 167         thrown. If the <member>ResourceURL</member> is not valid or describes an
 168         unknown type a <type scope="com::sun::star::lang">IllegalArgumentException</type>
 169         is thrown. If the configuration manager is read-only a
 170         <type scope="com::sun::star::lang">IllegalAccessException</type> is thrown.
 171         </p>
 172     */
 173     void removeSettings( [in] string ResourceURL ) raises ( com::sun::star::container::NoSuchElementException, com::sun::star::lang::IllegalArgumentException, com::sun::star::lang::IllegalAccessException );
 174
 175     /** inserts the settings of a new user interface element.
 176
 177         @param ResourceURL
 178             a resource URL which identifies the new user interface element.
 179
 180         @param aNewData
 181             the settings data of the new user interface element, which implements
 182             <type>UIElementSettings</type>.
 183
 184         <p>
 185         If the settings data is already present a
 186         <type scope="com::sun::star::container">ElementExistException</type>
 187         is thrown. If the <member>ResourceURL</member> is not valid or describes
 188         an unknown type a <type scope="com::sun::star::lang">IllegalArgumentException</type>
 189         is thrown. If the configuration manager is read-only a
 190         <type scope="com::sun::star::lang">IllegalAccessException</type> is thrown.
 191         </p>
 192     */
 193     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 );
 194
 195     /** retrieves the image manager from the user interface configuration
 196         manager.
 197
 198         <p>
 199         Every user interface configuration manager has one image manager
 200         instance which controls all images of a module or document.
 201         </p>
 202
 203         @return
 204             the image manager of the user interface configuration manager.
 205     */
 206     com::sun::star::uno::XInterface getImageManager();
 207
 208     /** retrieves the keyboard short cut manager from the user interface
 209         configuration manager.
 210
 211         <p>
 212         Every user interface configuration manager has one keyboard short cut
 213         manager instance which controls all short cuts of a module or document.
 214         </p>
 215
 216         @return
 217             the short cut manager of the user interface configuration manager.
 218     */
 219     com::sun::star::uno::XInterface getShortCutManager();
 220
 221     /** retrieves the events manager from the user interface configuration manager.
 222
 223         <p>
 224         Every user interface configuration manager has one events manager
 225         instance which controls the mapping of events to script URLs of a module
 226         or document.
 227         </p>
 228
 229         @return
 230             the events manager of the user interface configuration
 231             manager, if one exists.
 232     */
 233     com::sun::star::uno::XInterface getEventsManager();
 234 };
 235
 236
 237 }; }; }; };
 238
 239 #endif
 240
 241 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */