xref: /aoo42x/main/offapi/com/sun/star/frame/XFrame.idl (revision e9faf1d9)
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_XFrame_idl__
24#define __com_sun_star_frame_XFrame_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_awt_XWindow_idl__
31#include <com/sun/star/awt/XWindow.idl>
32#endif
33
34//=============================================================================
35
36 module com {  module sun {  module star {  module frame {
37
38 published interface XFrameActionListener;
39 published interface XController;
40 published interface XFramesSupplier;
41
42//=============================================================================
43/** a frame object can be considered to be an "anchor" object where a component
44    can be attached to.
45
46    <p>
47    A frame can be (it's not a must!) a part of a frame tree. If not this frame willn't be
48    accessible by using the api. This mode make sense for previews.
49    The root node of the tree can be a <type>Desktop</type> implementation.
50    </p>
51
52    @see Desktop
53 */
54published interface XFrame: com::sun::star::lang::XComponent
55{
56	//-------------------------------------------------------------------------
57    /** is called to initialize the frame within a window - the container window.
58
59        <p>
60        This window will be used as parent for the component window and to support
61        some UI relevant features of the frame service.
62        Note: Re-parenting mustn't supported by a real frame implementation!
63        It's designed for initializing - not for setting.
64        </p>
65
66		<p>This frame will take over ownership of the window referred from
67		<var>xWindow</var>.  Thus, the previous owner is not allowed to
68		dispose this window anymore. </p>
69
70        @param xWindow
71            the new container window
72
73        @see XFrame::getContainerWindow()
74	 */
75    void initialize( [in] com::sun::star::awt::XWindow xWindow );
76
77	//-------------------------------------------------------------------------
78    /** provides access to the container window of the frame.
79
80        <p>
81        Normally this is used as the parent window of the
82        component window.
83        </p>
84
85        @return
86            the container window of this frame
87
88        @see XFrame::initialize()
89	 */
90	com::sun::star::awt::XWindow getContainerWindow();
91
92	//-------------------------------------------------------------------------
93	/** sets the frame container that created this frame.
94
95        <p>
96        Only the creator is allowed to call this method.
97        But creator doesn't mean the implementation which creates this instance ...
98        it means the parent frame of the frame hierarchy.
99        Because; normally a frame should be created by using the api
100        and is necessary for searches inside the tree (e.g. <member>XFrame::findFrame()</member>)
101        </p>
102
103        @param Creator
104            the creator (parent) of this frame
105
106        @see XFrame::getCreator()
107	 */
108    [oneway] void setCreator( [in] XFramesSupplier Creator );
109
110	//-------------------------------------------------------------------------
111    /** provides access to the creator (parent) of this frame
112
113        @returns
114            the frame container that created and contains this frame.
115
116        @see XFrame::setCreator()
117	 */
118	XFramesSupplier getCreator();
119
120	//-------------------------------------------------------------------------
121    /** access to the name property of this frame
122
123        @returns
124            the programmatic name of this frame.
125
126        @see XFrame::setName()
127	 */
128	string getName();
129
130	//-------------------------------------------------------------------------
131	/** sets the name of the frame.
132
133        <p>
134        Normally the name of the frame is set initially (e.g. by the creator).
135        The name of a frame will be used for identifying it if a frame search was started.
136        These searches can be forced by:
137        <ul>
138            <li><member>XFrame::findFrame()</member>
139            <li><member>XDispatchProvider::queryDispatch()</member>
140            <li><member>XComponentLoader::loadComponentFromURL()</member>
141        </ul>
142        Note: Special targets like "_blank", "_self" etc. are not allowed.
143        That's why frame names shouldn't start with a sign "_".
144        </p>
145
146        @param aName
147            the new programmatic name of this frame
148
149        @see XFrame::findFrame()
150        @see XFrame::getName()
151        @see XDispatchProvider
152        @see XComponentLoader
153     */
154    [oneway] void setName( [in] string aName );
155
156	//-------------------------------------------------------------------------
157	/** searches for a frame with the specified name.
158
159        <p>
160        Frames may contain other frames (e.g., a frameset) and may
161		be contained in other frames. This hierarchy is searched with
162        this method.
163        First some special names are taken into account, i.e. "",
164        "_self", "_top", "_blank" etc. <var>SearchFlags</var> is ignored when
165        comparing these names with <var>TargetFrameName</var>; further steps are
166        controlled by <var>SearchFlags</var>. If allowed, the name of the frame
167		itself is compared with the desired one, and then ( again if allowed )
168        the method is called for all children of the frame. Finally may be called
169        for the siblings and then for parent frame (if allowed).
170        </p>
171
172        <p>
173        List of special target names:
174        <table border=1>
175        <tr><td>""/"_self"</td><td>address the starting frame itself</td></tr>
176        <tr><td>"_parent"</td><td>address the direct parent frame only</td></tr>
177        <tr><td>"_top"</td><td>address the top frame of this subtree of the frametree</td></tr>
178        <tr><td>"_blank"</td><td>creates a new top frame</td></tr>
179        </table>
180        </p>
181
182        <p>
183        If no frame with the given name is found, a new top frame is
184        created; if this is allowed by a special flag <const>FrameSearchFlag::CREATE</const>.
185        The new frame also gets the desired name.
186        </p>
187
188        @param aTargetFrameName
189            identify
190            <ul><li>(a) a special target ("_blank","_self" ...) or</li>
191                <li>(b) any well known frame</li><ul>
192            to search it inside the current hierarchy
193
194        @param nSearchFlags
195            optional parameter to regulate search if no special target was used for <var>TargetFrameName</var>
196
197         @see FrameSearchFlag
198         */
199    XFrame findFrame(
200        [in] string aTargetFrameName,
201        [in] long nSearchFlags);
202
203	//-------------------------------------------------------------------------
204	/** determines if the frame is a top frame.
205
206        <p>
207        In general a top frame is the frame which is a direct child of
208        a task frame or which does not have a parent. Possible frame searches must
209        stop the search at such a frame unless the flag <const>FrameSearchFlag::TASKS</const>
210        is set.
211        </p>
212
213        @return
214            <TRUE/> if frame supports top frame specification
215            <br>
216            <FALSE/> otherwise
217	 */
218	boolean isTop();
219
220	//-------------------------------------------------------------------------
221	/** activates this frame and thus the component within.
222
223        <p>
224        At first the frame sets itself as the active frame of its
225        creator by calling <member>XFramesSupplier::setActiveFrame()</member>,
226		then it broadcasts an <type>FrameActionEvent</type> with
227		<const>FrameAction::FRAME_ACTIVATED</const>. The component within
228		this frame may listen to this event to grab the focus on activation;
229		for simple components this can be done by the <type>FrameLoader</type>.
230        </p>
231
232        <p>
233        Finally, most frames may grab the focus to one of its windows
234		or forward the activation to a sub-frame.
235        </p>
236
237        @see XFrame::deactivate()
238        @see XFrame::isActive()
239    */
240	[oneway] void activate();
241
242	//-------------------------------------------------------------------------
243	/** is called by the creator frame when another sub-frame gets activated.
244
245        <p>
246        At first the frame deactivates its active sub-frame, if any.
247		Then broadcasts a <type>FrameActionEvent</type> with
248        <const>FrameAction::FRAME_DEACTIVATING</const>.
249        </p>
250
251        @see XFrame::activate()
252        @see XFrame::isActive()
253	 */
254	[oneway] void deactivate();
255
256	//-------------------------------------------------------------------------
257	/** determines if the frame is active.
258
259        @return
260            <TRUE/> for active or UI active frames
261            <br>
262            <FALSE/> otherwise
263
264        @see XFrame::activate()
265        @see XFrame::deactivate()
266	 */
267	boolean isActive();
268
269	//-------------------------------------------------------------------------
270    /** sets a new component into the frame or release an existing one from a frame.
271
272        @param xComponentWindow
273            the window of the new component or <NULL/> for release
274
275            <p>
276            A valid component window should be a child of the frame container window.
277            </p>
278
279        @param xController
280            the controller of the new component or <NULL/> for release
281
282            <p>
283            Simple components may implement a <type scope="com::sun::star::awt">XWindow</type> only.
284            In this case no controller must be given here.
285            </p>
286
287        @return
288            <TRUE/>if setting of new component or release of an existing one was successfully
289            <br>
290            <FALSE/> otherwise (especially, if an existing controller disagree within his
291            <member>XController::suspend()</member> call)
292
293        @see XFrame::getComponentWindow()
294        @see XFrame::getContainerWindow()
295        @see XFrame::getController()
296	 */
297    boolean setComponent(
298        [in] com::sun::star::awt::XWindow xComponentWindow,
299        [in] XController xController);
300
301	//-------------------------------------------------------------------------
302    /** provides access to the component window
303
304        <p>
305        Note: Don't dispose this window - the frame is the owner of it.
306        </p>
307
308        @returns
309            the current visible component in this frame
310            <br>
311            or <NULL/> if no one currently exist
312
313        @see XFrame::setComponent()
314	 */
315	com::sun::star::awt::XWindow getComponentWindow();
316
317	//-------------------------------------------------------------------------
318    /** provides access to the controller
319
320        <p>
321        Note: Don't dispose it - the frame is the owner of it.
322        Use <member>XController::getFrame()</member> to dispose
323        the frame after you the controller agreed with a
324        <member>XController::suspend()</member> call.
325        </p>
326
327        @returns
328            the current controller within this frame
329            <br>
330            or <NULL/> if no one currently exist
331
332        @see XFrame::setComponent()
333	 */
334	XController getController();
335
336	//-------------------------------------------------------------------------
337	/** notifies the frame that the context of the controller within this
338		frame changed (i.e. the selection).
339
340        <p>
341        According to a call to this interface, the frame calls
342        <method>XFrameEventListener::frameAction</method> with
343		<const>FrameAction::CONTEXT_CHANGED</const> to all listeners which
344        are registered using <member>XFrame::addFrameActionListener</member>.
345		For external controllers this event can be used to requery dispatches.
346
347        @see XFrameEventListener
348        @see FrameAction
349        @see XFrame::addFrameActionListener()
350	*/
351	void contextChanged();
352
353	//-------------------------------------------------------------------------
354	/** registers an event listener, which will be called when certain things
355		happen to the components within this frame or within sub-frames of this frame.
356
357        <p>
358        E.g., it is possible to determine instantiation/destruction and
359        activation/deactivation of components.
360        </p>
361
362        @param xListener
363            specifies the listener which will be informed
364
365        @see XFrame::removeFrameActionListener()
366	 */
367    [oneway] void addFrameActionListener( [in]XFrameActionListener xListener );
368
369	//-------------------------------------------------------------------------
370    /** unregisters an event listener
371
372        @param xListener
373            specifies the listener which willn't be informed any longer
374
375        @see XFrame::addFrameActionListener()
376	 */
377    [oneway] void removeFrameActionListener( [in] XFrameActionListener xListener );
378};
379
380//=============================================================================
381
382}; }; }; };
383
384#endif
385