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
24#ifndef __com_sun_star_frame_XLayoutManager_idl__
25#define __com_sun_star_frame_XLayoutManager_idl__
26
27#ifndef __com_sun_star_uno_XInterface_idl__
28#include <com/sun/star/uno/XInterface.idl>
29#endif
30
31#ifndef __com_sun_star_frame_XFrame_idl__
32#include <com/sun/star/frame/XFrame.idl>
33#endif
34
35#ifndef __com_sun_star_awt_Point_idl__
36#include <com/sun/star/awt/Point.idl>
37#endif
38
39#ifndef __com_sun_star_awt_Size_idl__
40#include <com/sun/star/awt/Size.idl>
41#endif
42
43#ifndef __com_sun_star_awt_XWindow_idl__
44#include <com/sun/star/awt/XWindow.idl>
45#endif
46
47#ifndef __com_sun_star_ui_XUIElement_idl__
48#include <com/sun/star/ui/XUIElement.idl>
49#endif
50
51#ifndef __com_sun_star_ui_DockingArea_idl__
52#include <com/sun/star/ui/DockingArea.idl>
53#endif
54
55#ifndef __com_sun_star_ui_XDockingAreaAcceptor_idl__
56#include <com/sun/star/ui/XDockingAreaAcceptor.idl>
57#endif
58
59//=============================================================================
60
61module com { module sun { module star { module frame {
62
63//=============================================================================
64
65/** central interface to query for, create, destroy and manipulate user
66    interface elements which are bound to a layout manager.
67
68    <p>
69    Every user interface element which is controlled by a layout manager has
70    a unique identifier called resource URL.
71
72    A resourcce URL must meet the following syntax:
73    "private:resource/$type/$name". It is only allowed to use ascii characters
74    for type and name.
75
76    Currently the following user interface element types are defined:
77    <ul>
78        <li><b>menubar</b>A configurable user interface element representing
79        a menu bar.</li>
80        <li><b>popupmenu</b>A configurable user interface element representing
81        a popup menu.</li>
82        <li><b>toolbar</b>A configurable user interface element a tool
83        bar.</li>
84        <li><b>statusbar</b>A configurable user interfave element representing
85        a status bar.</li>
86        <li><b>floater</b>A basic user interface element representing a
87        floating window.</li>
88    </ul>
89
90    @see com::sun::star::ui::UIElementTypes
91    @see com::sun::star::frame::XFrame
92    </p>
93
94    @since OOo 2.0
95*/
96
97published interface XLayoutManager : com::sun::star::uno::XInterface
98{
99    /** attaches a <type scope="com::sun::star::frame">XFrame</type> to a layout manager.
100
101        @param Frame
102            specifies the frame that should be attached to the layout manager
103
104        <p>
105        A layout manager needs a <type scope="com::sun::star::frame">XFrame</type> to be
106        able to work. Without a it no user interface elements can be created.
107        </p>
108    */
109    void attachFrame( [in] com::sun::star::frame::XFrame Frame );
110
111    /** resets the layout manager and remove all of its internal user interface
112        elements.
113
114        <p>
115        This call should be handled with care as all user interface elements will
116        be destroyed and the layout manager is reseted to a state after a
117        <member>attachFrame</member> has been made. That means an attached frame
118        which has been set by <member>attachFrame</member> is not released.
119        The layout manager itself calls reset after a component has been attached
120        or reattached to a frame.
121        </p>
122    */
123    void reset();
124
125    /** provides the current docking area size of the layout manager.
126
127        @return
128            The <type scope="com::sun::star::awt">Rectangle</type> contains pixel values. The
129            members of <type scope="com::sun::star::awt">Rectangle</type> are filled as following:
130            <ul>
131                <li>X      = docking area on left side (in pixel)</li>
132                <li>Y      = docking area on top side (in pixel)</li>
133                <li>Width  = docking area on right side (in pixel)</li>
134                <li>Height = docking area on bottom side (in pixel)</li>
135            </ul>
136    */
137    com::sun::star::awt::Rectangle getCurrentDockingArea();
138
139    /** retrieves the current docking area acceptor that controls the border space of the frame's
140        container window.
141
142        @return
143            current docking area acceptor which controls the border space of frame's container window.
144
145        <p>
146        A docking area acceptor retrieved by this method is owned by the layout manager. It is not
147        allowed to dispose this object, it will be destroyed on reference count!
148        </p>
149    */
150    com::sun::star::ui::XDockingAreaAcceptor getDockingAreaAcceptor();
151
152    /** sets a docking area acceptor that controls the border space of the frame's container window.
153
154        @param xDockingAreaAcceptor
155            a docking area acceptor which controls the border space of frame's container window.
156
157        <p>
158        A docking area acceptor decides if the layout manager can use requested border space for
159        docking windows. If the acceptor denies the requested space the layout manager automatically
160        set all docked windows into floating state and will not use this space for docking.<br/>
161        After setting a docking area acceptor the object is owned by the layout manager. It is not
162        allowed to dispose this object, it will be destroyed on reference count!
163        </p>
164    */
165    void setDockingAreaAcceptor( [in] com::sun::star::ui::XDockingAreaAcceptor xDockingAreaAcceptor );
166
167    /** creates a new user interface element.
168
169        @param ResourceURL
170            specifies which user interface element should be created. A resourcce URL must meet the following
171            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
172            name.
173    */
174    void createElement( [in] string ResourceURL );
175
176    /** destroys a user interface element.
177
178        @param ResourceURL
179            specifies which user interface element should be destroyed. A resourcce URL must meet
180            the following syntax: "private:resource/$type/$name". It is only allowed to use ascii
181            characters for type and name.
182    */
183    void destroyElement( [in] string ResourceURL );
184
185    /** request to make a user interface element visible if it is not in hidden state.
186
187        @param ResourceURL
188            specifies which user interface element should be made visible. A resourcce URL must
189            meet the following syntax: "private:resource/$type/$name". It is only allowed to use
190            ascii characters for type and
191            name.
192
193        @return
194            returns <TRUE/> if the user interface element could be made visible, otherwise
195            <FALSE/> will be returned.
196
197        <p>
198        If a user interface element should forced to the visible state
199        <member>XLayoutManager::showElement</member> should be used. This function can be
200        used for context dependent elements which should respect a the current visibility
201        state.
202        </p>
203    */
204    boolean requestElement( [in] string ResourceURL );
205
206    /** retrieves a user interface element which has been created before.
207
208        @param ResourceURL
209            specifies which user interface element should be retrieved. A resourcce URL must meet the following
210            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
211            name.
212
213        <p>
214        The layout manager instance is owner of the returned user interface element. That means that the life time of
215        the user interface element is controlled by the layout manager. It can be disposed at every time!
216        </p>
217    */
218    com::sun::star::ui::XUIElement getElement( [in] string ResourceURL );
219
220    /** retrieves all user interface elements which are currently instanciated.
221
222        @return
223            a sequence of user interface elements providing <type scope="com::sun::star::ui">XUIElement</type>
224            interface.
225
226        <p>
227        The layout manager instance is owner of the returned user interface elements. That means that the life time of
228        the user interface elements is controlled by the layout manager. They can be disposed at every time!
229        </p>
230    */
231    sequence< com::sun::star::ui::XUIElement > getElements();
232
233    /** shows a user interface element.
234
235        @param ResourceURL
236            specifies which user interface element should be shown. A resourcce URL must meet the following
237            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
238            name.
239
240        @return
241            returns <TRUE/> if the user interface element has been shown, otherwise <FALSE/> will be returned.
242    */
243    boolean showElement( [in] string ResourceURL );
244
245    /** hides a user interface element.
246
247        @param ResourceURL
248            specifies which user interface element should be hidden. A resourcce URL must meet the following
249            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
250            name.
251
252        @return
253            returns <TRUE/> if the user interface element has been hidden, otherwise <FALSE/> will be returned.
254    */
255    boolean hideElement( [in] string ResourceURL );
256
257    /** docks a window based user interface element to a specified docking area.
258
259        @param ResourceURL
260            specifies which user interface element should be docked. A resourcce URL must meet the following
261            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
262            name.
263
264        @param DockingArea
265            specifies on which docking area the window based user interface element should docked.
266
267        @param Pos
268            specifies the position inside the docking area.
269
270        @return
271            returns <TRUE/> if the user interface element has been docked, otherwise <FALSE/> will be returned.
272
273        @see com::sun::star::ui::DockingArea
274    */
275    boolean dockWindow( [in] string ResourceURL, [in] com::sun::star::ui::DockingArea DockingArea, [in] com::sun::star::awt::Point Pos );
276
277    /** docks all windows which are member of the provided user interface element type.
278
279        @param nElementType
280            specifies which user interface element type should be docked.
281
282        @return
283            returns <TRUE/> if all user interface elements of the requested type could be
284            docked, otherwise <FALSE/> will be returned.
285
286        @see com::sun::star::ui::UIElementType
287    */
288    boolean dockAllWindows( [in] short nElementType );
289
290    /** forces a window based user interface element to float.
291
292        @param ResourceURL
293            specifies which user interface element should be float. A resourcce URL must meet the following
294            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
295            name.
296
297        @return
298            returns <TRUE/> if the user interface element has been docked, otherwise <FALSE/> will be returned.
299    */
300    boolean floatWindow( [in] string ResourceURL );
301
302    /** locks a window based user interface element if it's in a docked state.
303
304        @param ResourceURL
305            specifies which user interface element should be locked. A resourcce URL must meet the following
306            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
307            name.
308
309        @return
310            returns <TRUE/> if the user interface element has been locked, otherwise <FALSE/> will be returned.
311    */
312    boolean lockWindow( [in] string ResourceURL );
313
314    /** unlocks a window based user interface element if it's in a docked state.
315
316        @param ResourceURL
317            specifies which user interface element should be unlocked. A resourcce URL must
318            meet the following syntax: "private:resource/$type/$name". It is only allowed
319            to use ascii characters for type and name.
320
321        @return
322            returns <TRUE/> if the user interface element has been unlocked, otherwise
323            <FALSE/> will be returned.
324    */
325    boolean unlockWindow( [in] string ResourceURL );
326
327    /** sets a new size for a window based user interface element.
328
329        @param ResourceURL
330            specifies which user interface element should be resized. A resourcce URL must meet the following
331            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
332            name.
333
334        @param Size
335            specifies the new size in pixel.
336
337        <p>
338        It is up to the layout manager to decide if the user interface element can be resized. The new size can be retrieved
339        by calling <member>getElementSize</member>.
340        </p>
341    */
342    void setElementSize( [in] string ResourceURL, [in] com::sun::star::awt::Size Size );
343
344    /** sets a new position for a window based user interface element.
345
346        @param ResourceURL
347            specifies which user interface element should be moved. A resourcce URL must meet the following
348            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
349            name.
350
351        @param Pos
352            specifies the new position in pixel.
353
354        <p>
355        It is up to the layout manager to decide if the user interface element can be moved. The new position can be retrieved
356        by calling <member>getElementPos</member>.
357        </p>
358    */
359    void setElementPos( [in] string ResourceURL, [in] com::sun::star::awt::Point Pos );
360
361    /** sets a new position and size for a window based user interface element.
362
363        @param ResourceURL
364            specifies which user interface element should be moved and resized. A resourcce URL must meet the following
365            syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
366            name.
367
368        @param Pos
369            specifies the new position in pixel.
370
371        @param Size
372            specifies the new position in pixel.
373
374        <p>
375        It is up to the layout manager to decide if the user interface element can be moved and resized. The new position and size can
376        be retrieved by calling <member>getElementPos</member> and <member>getElementSize</member>.
377        </p>
378    */
379    void setElementPosSize( [in] string ResourceURL, [in] com::sun::star::awt::Point Pos, [in] com::sun::star::awt::Size Size );
380
381    /** retrieves the current visibility state of a window based user interface element.
382
383        @param ResourceURL
384            specifies for which user interface element the visibility state should be retrieved. A resource URL must meet
385            the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
386            name.
387
388        @return
389            <TRUE/> if the user interface element is visible, otherwise <FALSE/>.
390    */
391    boolean isElementVisible( [in] string ResourceURL );
392
393    /** retrieves the current floating state of a window based user interface element.
394
395        @param ResourceURL
396            specifies for which user interface element the floating state should be retrieved. A resource URL must meet
397            the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
398            name.
399
400        @return
401            <TRUE/> if the user interface element is floating, otherwise <FALSE/>.
402    */
403    boolean isElementFloating( [in] string ResourceURL );
404
405    /** retrieves the current docking state of a window based user interface element.
406
407        @param ResourceURL
408            specifies for which user interface element the docking state should be retrieved. A resource URL must meet
409            the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
410            name.
411
412        @return
413            <TRUE/> if the user interface element is docked, otherwise <FALSE/>.
414    */
415    boolean isElementDocked( [in] string ResourceURL );
416
417    /** retrieves the current lock state of a window based user interface element.
418
419        @param ResourceURL
420            specifies for which user interface element the lock state should be retrieved. A resource URL must meet
421            the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
422            name.
423
424        @return
425            <TRUE/> if the user interface element is locked, otherwise <FALSE/>.
426    */
427    boolean isElementLocked( [in] string ResourceURL  );
428
429    /** retrieves the current size of a window based user interface element.
430
431        @param ResourceURL
432            specifies for which user interface element the current size should be retrieved. A resource URL must meet
433            the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
434            name.
435
436        @return
437            the size in pixel of the user interface element. A non-window based user interface element provides a zero size.
438    */
439    com::sun::star::awt::Size getElementSize( [in] string ResourceURL );
440
441    /** retrieves the current pixel position of a window based user interface element.
442
443        @param ResourceURL
444            specifies for which user interface element the current position should be retrieved. A resource URL must meet
445            the following syntax: "private:resource/$type/$name". It is only allowed to use ascii characters for type and
446            name.
447
448        @return
449            the size in pixel of the user interface element. A non-window based user interface element provides a zero size.
450    */
451    com::sun::star::awt::Point getElementPos( [in] string ResourceURL );
452
453    /** prohibit all layout updates until unlock is called again.
454
455        <p>
456        This call can be used to speed up the creation process of serveral user interface elements. Otherwise the layout manager
457        would calculate the layout for every creation.
458        </p>
459    */
460    void lock();
461
462    /** permit layout updates again.
463
464        <p>
465        This function should be called to permit layout updates. The layout manager starts to calculate the new layout after
466        this call.
467        </p>
468    */
469    void unlock();
470
471    /** forces a complete new layouting of all user interface elements.
472    */
473    void doLayout();
474
475    /** sets the layout manager to invisible state and hides all user interface elements.
476
477        <p>
478        A layout manager can be set to invisible state to force it to hide all of its
479        user interface elements. If another component wants to use the window for its
480        own user interface elements it can use this function. This function is normally
481        used to implement inplace editing.
482        </p>
483
484        @param Visible
485            provide <FALSE/> to make layout manager invisible otherwise this must be
486            set to <TRUE/>.
487    */
488    void setVisible( [in] boolean Visible );
489
490    /** retrieves the visibility state of a layout manager.
491
492        <p>
493        A layout manager can be set to invisible state to force it to hide all of its
494        user interface elements. If another component wants to use the window for its
495        own user interface elements it can use this function. This function is normally
496        used to implement inplace editing.
497        </p>
498
499    */
500    boolean isVisible();
501
502};
503
504}; }; }; };
505
506#endif
507