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