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