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