offapi/com/sun/star/frame/XModel.idl

   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 #ifndef __com_sun_star_frame_XModel_idl__
  28 #define __com_sun_star_frame_XModel_idl__
  29
  30 #ifndef __com_sun_star_lang_XComponent_idl__
  31 #include <com/sun/star/lang/XComponent.idl>
  32 #endif
  33
  34 #ifndef __com_sun_star_beans_PropertyValue_idl__
  35 #include <com/sun/star/beans/PropertyValue.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_frame_XController_idl__
  39 #include <com/sun/star/frame/XController.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  43 #include <com/sun/star/container/NoSuchElementException.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_uno_XInterface_idl__
  47 #include <com/sun/star/uno/XInterface.idl>
  48 #endif
  49
  50
  51 //=============================================================================
  52
  53  module com {  module sun {  module star {  module frame {
  54
  55 //=============================================================================
  56 /** represents a component which is created from an URL and arguments.
  57
  58     <p>
  59     It is a representation of a resource in the sense that it was
  60     created/loaded from the resource. The arguments are passed to the loader
  61     to modify its behavior. An example for such an argument is "AsTemplate",
  62     which loads the resource as a template for a new document.
  63     (see <type scope="com::sun::star::document">MediaDescriptor</type> for further details)
  64     </p>
  65
  66     <p>
  67     Models can be controlled by controller components, which are usually
  68     views of the model.
  69     (see <type>Controller</type> for further details)
  70     </p>
  71
  72     <p>
  73     If there is at least one controller, there is by definition a
  74     current controller. And if that controller supports the interface
  75     <type scope="com::sun::star::view">XSelectionSupplier</type>, it has a current selection too.
  76     </p>
  77
  78     @see com::sun::star::document::MediaDescriptor
  79     @see Controller
  80     @see com::sun::star::view::XSelectionSupplier
  81  */
  82 published interface XModel: com::sun::star::lang::XComponent
  83 {
  84     //-------------------------------------------------------------------------
  85     /** informs a model about its resource description.
  86
  87         @param URL
  88             specifies the ressource
  89
  90         @param Arguments
  91             are optional arguments for that ressource
  92             (see <type scope="com::sun::star::document">MediaDescriptor</type>)
  93
  94         @return
  95             <TRUE/> for success
  96             <br>
  97             <FALSE/> otherwise
  98      */
  99     boolean attachResource(
 100         [in] string URL,
 101         [in] sequence<com::sun::star::beans::PropertyValue> Arguments);
 102
 103     //-------------------------------------------------------------------------
 104     /** provides information about the location of this model
 105
 106         @returns
 107             the URL of the resource which is represented by this model.
 108
 109         @see XStorable::getLocation()
 110      */
 111     string getURL();
 112
 113     //-------------------------------------------------------------------------
 114     /** provides read acces on currently representation of the
 115         <type scope="com::sun::star::document">MediaDescriptor</type>
 116         of this model which describes the model and his state
 117
 118         @returns
 119             the arguments with which the model was originally created or
 120             stored the last time.
 121      */
 122     sequence< com::sun::star::beans::PropertyValue > getArgs();
 123
 124     //-------------------------------------------------------------------------
 125     /** is called whenever a new controller is created for this model.
 126
 127         <p>
 128         The <type scope="com::sun::star::lang">XComponent</type> interface
 129         of the controller must be used to recognize when it is deleted.
 130         </p>
 131
 132         @param Controller
 133             a new controller for this model
 134
 135         @see XModel::disconnectController()
 136      */
 137     [oneway] void connectController( [in] XController Controller );
 138
 139     //-------------------------------------------------------------------------
 140     /** is called whenever an existing controller should be deregistered at this model.
 141
 142         <p>
 143         The <type scope="com::sun::star::lang">XComponent</type> interface
 144         of the controller must be used to recognize when it is deleted.
 145         </p>
 146
 147         @param Controller
 148             the existing controller which should be deregistered
 149
 150         @see XModel::connectController()
 151      */
 152     [oneway] void disconnectController( [in] XController Controller );
 153
 154     //-------------------------------------------------------------------------
 155     /** suspends some notifications to the controllers which are used
 156         for display updates.
 157
 158         <p>
 159         The calls to <member>XModel::lockControllers()</member> and
 160         <member>XModel::unlockControllers()</member> may be
 161         nested and even overlapping, but they must be in pairs. While
 162         there is at least one lock remaining, some notifications
 163         for display updates are not broadcasted.
 164         </p>
 165      */
 166     [oneway] void lockControllers();
 167
 168     //-------------------------------------------------------------------------
 169     /** resumes the notifications which were suspended by
 170         <member>XModel::lockControllers()</member>.
 171
 172         <p>
 173         The calls to <member>XModel::lockControllers()</member> and
 174         <member>XModel::unlockControllers()</member> may be
 175         nested and even overlapping, but they must be in pairs. While
 176         there is at least one lock remaining, some notifications for
 177         display updates are not broadcasted.
 178         </p>
 179     */
 180     [oneway] void unlockControllers();
 181
 182     //-------------------------------------------------------------------------
 183     /** determines if there is at least one lock remaining.
 184
 185         <p>
 186         While there is at least one lock remaining, some notifications
 187         for display updates are not broadcasted to the controllers.
 188         </p>
 189
 190         @return
 191             <TRUE/> if any lock exist
 192             <br>
 193             <FALSE/> otherwise
 194      */
 195     boolean hasControllersLocked();
 196
 197     //-------------------------------------------------------------------------
 198     /** provides access to the controller which currently controls this model
 199
 200         @returns
 201             If the controller which is active is a controller of this model,
 202             it will be returned. If not, the controller which was the last
 203             active of this model is returned. If no controller of this model
 204             ever was active, the controller first registered is returned. If no
 205             controller is registered for this model, <NULL/> is returned.
 206      */
 207     XController getCurrentController();
 208
 209     //-------------------------------------------------------------------------
 210     /** sets a registered controller as the current controller.
 211
 212         @param Controller
 213             reference to an already existing connected controller, which should be
 214             the new active one
 215
 216         @throws com::sun::star::container::NoSuchElementException
 217             if <var>xController</var> isn't an already connected controller on this model
 218      */
 219     void setCurrentController( [in] XController Controller )
 220             raises( com::sun::star::container::NoSuchElementException );
 221
 222     //-------------------------------------------------------------------------
 223     /** provides read access on current selection on controller
 224
 225         @returns
 226             the current selection in the current controller.
 227             If there is no current controller, it returns <NULL/>.
 228      */
 229     com::sun::star::uno::XInterface getCurrentSelection();
 230 };
 231
 232 //=============================================================================
 233
 234 }; }; }; };
 235
 236 #endif