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