1QDockWindow(3qt) QDockWindow(3qt)
2
6 QDockWindow - Widget which can be docked inside a QDockArea or floated
7 as a top level window on the desktop
8
10 #include <qdockwindow.h>
11 Inherits QFrame.
13 Inherited by QToolBar.
15 Public Members
17 enum Place { InDock, OutsideDock }
18 enum CloseMode { Never = 0, Docked = 1, Undocked = 2, Always = Docked |
19 Undocked }
20 QDockWindow ( Place p = InDock, QWidget * parent = 0, const char * name
21 = 0, WFlags f = 0 )
22 QDockWindow ( QWidget * parent, const char * name = 0, WFlags f = 0 )
23 virtual void setWidget ( QWidget * w )
24 QWidget * widget () const
25 Place place () const
26 QDockArea * area () const
27 virtual void setCloseMode ( int m )
28 bool isCloseEnabled () const
29 int closeMode () const
30 virtual void setResizeEnabled ( bool b )
31 virtual void setMovingEnabled ( bool b )
32 bool isResizeEnabled () const
33 bool isMovingEnabled () const
34 virtual void setHorizontallyStretchable ( bool b )
35 virtual void setVerticallyStretchable ( bool b )
36 bool isHorizontallyStretchable () const
37 bool isVerticallyStretchable () const
38 void setHorizontalStretchable ( bool b ) (obsolete)
39 void setVerticalStretchable ( bool b ) (obsolete)
40 bool isHorizontalStretchable () const (obsolete)
41 bool isVerticalStretchable () const (obsolete)
42 bool isStretchable () const
43 virtual void setOffset ( int o )
44 int offset () const
45 virtual void setFixedExtentWidth ( int w )
46 virtual void setFixedExtentHeight ( int h )
47 QSize fixedExtent () const
48 virtual void setNewLine ( bool b )
49 bool newLine () const
50 Qt::Orientation orientation () const
51 QBoxLayout * boxLayout ()
52 virtual void setOpaqueMoving ( bool b )
53 bool opaqueMoving () const
54 Public Slots
56 virtual void undock ()
57 virtual void dock ()
58 virtual void setOrientation ( Orientation o )
59 Signals
61 void orientationChanged ( Orientation o )
62 void placeChanged ( QDockWindow::Place p )
63 void visibilityChanged ( bool visible )
64 Properties
66 int closeMode - the close mode of a dock window
67 bool horizontallyStretchable - whether the dock window is horizontally
68 stretchable
69 bool movingEnabled - whether the user can move the dock window within
70 the dock area, move the dock window to another dock area, or float
71 the dock window
72 bool newLine - whether the dock window prefers to start a new line in
73 the dock area
74 int offset - the dock window's preferred offset from the dock area's
75 left edge (top edge for vertical dock areas)
76 bool opaqueMoving - whether the dock window will be shown normally
77 whilst it is being moved
78 Place place (read only)
79 bool resizeEnabled - whether the dock window is resizeable
80 bool stretchable - whether the dock window is stretchable in the
81 current orientation() (read only)
82 bool verticallyStretchable - whether the dock window is vertically
83 stretchable
84
86 The QDockWindow class provides a widget which can be docked inside a
87 QDockArea or floated as a top level window on the desktop.
88 This class handles moving, resizing, docking and undocking dock
90 windows. QToolBar is a subclass of QDockWindow so the functionality
91 provided for dock windows is available with the same API for toolbars.
92 <center>
94 [Image Omitted]
95 </center> <blockquote><p align="center"> Two QDockWindows (QToolBars)
97 in a QDockArea </p> </blockquote>
98 <center>
100 [Image Omitted]
101 </center> <blockquote><p align="center"> A Floating QDockWindow </p>
103 </blockquote>
104 If the user drags the dock window into the dock area the dock window
106 will be docked. If the user drags the dock area outside any dock areas
107 the dock window will be undocked (floated) and will become a top level
108 window. Double clicking a floating dock window's titlebar will dock the
109 dock window to the last dock area it was docked in. Double clicking a
110 docked dock window's handle will undock (float) the dock window. If the
111 user clicks the close button (which does not appear on dock windows by
112 default - see closeMode) the dock window will disappear. You can
113 control whether or not a dock window has a close button with
114 setCloseMode().
115 QMainWindow provides four dock areas (top, left, right and bottom)
117 which can be used by dock windows. For many applications using the dock
118 areas provided by QMainWindow is sufficient. (See the QDockArea
119 documentation if you want to create your own dock areas.) In
120 QMainWindow a right-click popup menu (the dock window menu) is
121 available which lists dock windows and can be used to show or hide
122 them. (The popup menu only lists dock windows that have a caption.)
123 When you construct a dock window you must pass it a QDockArea or a
125 QMainWindow as its parent if you want it docked. Pass 0 for the parent
126 if you want it floated.
127 QToolBar *fileTools = new QToolBar( this, "File Actions" );
129 moveDockWindow( fileTools, Left );
130 In the example above we create a new QToolBar in the constructor of a
132 QMainWindow subclass (so that the this pointer points to the
133 QMainWindow). By default the toolbar will be added to the Top dock
134 area, but we've moved it to the Left dock area.
135 A dock window is often used to contain a single widget. In these cases
137 the widget can be set by calling setWidget(). If you're constructing a
138 dock window that contains multiple widgets, e.g. a toolbar, arrange the
139 widgets within a box layout inside the dock window. To do this use the
140 boxLayout() function to get a pointer to the dock window's box layout,
141 then add widgets to the layout using the box layout's
142 QBoxLayout::addWidget() function. The dock window will dynamically set
143 the orientation of the layout to be vertical or horizontal as
144 necessary, although you can control this yourself with
145 setOrientation().
146 Although a common use of dock windows is for toolbars, they can be used
148 with any widgets. (See the Qt Designer and Qt Linguist applications,
149 for example.) When using larger widgets it may make sense for the dock
150 window to be resizable by calling setResizeEnabled(). Resizable dock
151 windows are given splitter-like handles to allow the user to resize
152 them within their dock area. When resizable dock windows are undocked
153 they become top level windows and can be resized like any other top
154 level windows, e.g. by dragging a corner or edge.
155 Dock windows can be docked and undocked using dock() and undock(). A
157 dock window's orientation can be set with setOrientation(). You can
158 also use QDockArea::moveDockWindow(). If you're using a QMainWindow,
159 QMainWindow::moveDockWindow() and QMainWindow::removeDockWindow() are
160 available.
161 A dock window can have some preferred settings, for example, you can
163 set a preferred offset from the left edge (or top edge for vertical
164 dock areas) of the dock area using setOffset(). If you'd prefer a dock
165 window to start on a new line when it is docked use setNewLine(). The
166 setFixedExtentWidth() and setFixedExtentHeight() functions can be used
167 to define the dock window's preferred size, and the
168 setHorizontallyStretchable() and setVerticallyStretchable() functions
169 set whether the dock window can be stretched or not. Dock windows can
170 be moved by default, but this can be changed with setMovingEnabled().
171 When a dock window is moved it is shown as a rectangular outline, but
172 it can be shown normally using setOpaqueMoving().
173 When a dock window's visibility changes, i.e. it is shown or hidden,
175 the visibilityChanged() signal is emitted. When a dock window is
176 docked, undocked or moved inside the dock area the placeChanged()
177 signal is emitted.
178 See also Main Window and Related Classes.
180 Member Type Documentation
183 This enum type specifies when (if ever) a dock window has a close
184 button.
185 QDockWindow::Never - The dock window never has a close button and
187 cannot be closed by the user.
188 QDockWindow::Docked - The dock window has a close button only when
190 docked.
191 QDockWindow::Undocked - The dock window has a close button only when
193 floating.
194 QDockWindow::Always - The dock window always has a close button.
196
198 This enum specifies the possible locations for a QDockWindow:
199 QDockWindow::InDock - Inside a QDockArea.
201 QDockWindow::OutsideDock - Floating as a top level window on the
203 desktop.
204
207 * name = 0, WFlags f = 0 )
208 Constructs a QDockWindow with parent parent, called name and with
209 widget flags f.
210 If p is InDock, the dock window is docked into a dock area and parent
212 must be a QDockArea or a QMainWindow. If the parent is a QMainWindow
213 the dock window will be docked in the main window's Top dock area.
214 If p is OutsideDock, the dock window is created as a floating window.
216 We recommend creating the dock area InDock with a QMainWindow as parent
218 then calling QMainWindow::moveDockWindow() to move the dock window
219 where you want it.
220
222 0 )
223 Constructs a QDockWindow with parent parent, called name and with
224 widget flags f.
225
227 Returns the dock area in which this dock window is docked, or 0 if the
228 dock window is floating.
229
231 Returns the layout which is used for adding widgets to the dock window.
232 The layout's orientation is set automatically to match the orientation
233 of the dock window. You can add widgets to the layout using the box
234 layout's QBoxLayout::addWidget() function.
235 If the dock window only needs to contain a single widget use
237 setWidget() instead.
238 See also setWidget() and setOrientation().
240
242 Returns the close mode of a dock window. See the "closeMode" property
243 for details.
244
246 Docks the dock window into the last dock area in which it was docked.
247 If the dock window has no last dock area (e.g. it was created as a
249 floating window and has never been docked), or if the last dock area it
250 was docked in does not exist (e.g. the dock area has been deleted),
251 nothing happens.
252 The dock window will dock with the dock area regardless of the return
254 value of QDockArea::isDockWindowAccepted().
255 See also undock(), QDockArea::moveDockWindow(),
257 QDockArea::removeDockWindow(), QMainWindow::moveDockWindow(),
258 QMainWindow::removeDockWindow(), and QDockArea::isDockWindowAccepted().
259
261 Returns the dock window's preferred size (fixed extent).
262 See also setFixedExtentWidth() and setFixedExtentHeight().
264
266 Returns TRUE if the dock window has a close button; otherwise returns
267 FALSE. The result depends on the dock window's Place and its CloseMode.
268 See also closeMode.
270
272 This function is obsolete. It is provided to keep old source working.
273 We strongly advise against using it in new code.
274
276 Returns TRUE if the dock window is horizontally stretchable; otherwise
277 returns FALSE. See the "horizontallyStretchable" property for details.
278
280 Returns TRUE if the user can move the dock window within the dock area,
281 move the dock window to another dock area, or float the dock window;
282 otherwise returns FALSE. See the "movingEnabled" property for details.
283
285 Returns TRUE if the dock window is resizeable; otherwise returns FALSE.
286 See the "resizeEnabled" property for details.
287
289 Returns TRUE if the dock window is stretchable in the current
290 orientation(); otherwise returns FALSE. See the "stretchable" property
291 for details.
292
294 This function is obsolete. It is provided to keep old source working.
295 We strongly advise against using it in new code.
296
298 Returns TRUE if the dock window is vertically stretchable; otherwise
299 returns FALSE. See the "verticallyStretchable" property for details.
300
302 Returns TRUE if the dock window prefers to start a new line in the dock
303 area; otherwise returns FALSE. See the "newLine" property for details.
304
306 Returns the dock window's preferred offset from the dock area's left
307 edge (top edge for vertical dock areas). See the "offset" property for
308 details.
309
311 Returns TRUE if the dock window will be shown normally whilst it is
312 being moved; otherwise returns FALSE. See the "opaqueMoving" property
313 for details.
314
316 Returns the orientation of the dock window.
317 See also orientationChanged().
319
321 This signal is emitted when the orientation of the dock window is
322 changed. The new orientation is o.
323
325 This function returns where the dock window is placed. This is either
326 InDock or OutsideDock.
327 See also QDockArea::moveDockWindow(), QDockArea::removeDockWindow(),
329 QMainWindow::moveDockWindow(), and QMainWindow::removeDockWindow().
330
332 This signal is emitted when the dock window is docked (p is InDock),
333 undocked (p is OutsideDock) or moved inside the the dock area.
334 See also QDockArea::moveDockWindow(), QDockArea::removeDockWindow(),
336 QMainWindow::moveDockWindow(), and QMainWindow::removeDockWindow().
337
339 Sets the close mode of a dock window to m. See the "closeMode" property
340 for details.
341
343 Sets the dock window's preferred height for its fixed extent (size) to
344 h.
345 See also setFixedExtentWidth().
347
349 Sets the dock window's preferred width for its fixed extent (size) to
350 w.
351 See also setFixedExtentHeight().
353
355 This function is obsolete. It is provided to keep old source working.
356 We strongly advise against using it in new code.
357
359 Sets whether the dock window is horizontally stretchable to b. See the
360 "horizontallyStretchable" property for details.
361
363 Sets whether the user can move the dock window within the dock area,
364 move the dock window to another dock area, or float the dock window to
365 b. See the "movingEnabled" property for details.
366
368 Sets whether the dock window prefers to start a new line in the dock
369 area to b. See the "newLine" property for details.
370
372 Sets the dock window's preferred offset from the dock area's left edge
373 (top edge for vertical dock areas) to o. See the "offset" property for
374 details.
375
377 Sets whether the dock window will be shown normally whilst it is being
378 moved to b. See the "opaqueMoving" property for details.
379
381 Sets the orientation of the dock window to o. The orientation is
382 propagated to the layout boxLayout().
383 Warning: All undocked QToolBars will always have a horizontal
385 orientation.
386
388 Sets whether the dock window is resizeable to b. See the
389 "resizeEnabled" property for details.
390
392 This function is obsolete. It is provided to keep old source working.
393 We strongly advise against using it in new code.
394
396 Sets whether the dock window is vertically stretchable to b. See the
397 "verticallyStretchable" property for details.
398
400 Sets the dock window's main widget to w.
401 See also boxLayout().
403
405 Undocks the QDockWindow from its current dock area if it is docked;
406 otherwise does nothing.
407 See also dock(), QDockArea::moveDockWindow(),
409 QDockArea::removeDockWindow(), QMainWindow::moveDockWindow(), and
410 QMainWindow::removeDockWindow().
411
413 This signal is emitted when the visibility of the dock window
414 relatively to its dock area is changed. If visible is TRUE, the
415 QDockWindow is now visible to the dock area, otherwise it has been
416 hidden.
417 A dock window can be hidden if it has a close button which the user has
419 clicked. In the case of a QMainWindow a dock window can have its
420 visibility changed (hidden or shown) by clicking its name in the dock
421 window menu that lists the QMainWindow's dock windows.
422
424 Returns the dock window's main widget.
425 See also setWidget().
427 Property Documentation
430 This property holds the close mode of a dock window.
431 Defines when (if ever) the dock window has a close button. The choices
433 are Never, Docked (i.e. only when docked), Undocked (only when
434 undocked, i.e. floated) or Always.
435 The default is Never.
437 Set this property's value with setCloseMode() and get this property's
439 value with closeMode().
440
442 This property holds whether the dock window is horizontally
443 stretchable.
444 A dock window is horizontally stretchable if you call
446 setHorizontallyStretchable(TRUE) or setResizeEnabled(TRUE).
447 See also resizeEnabled.
449 Bugs and limitations:
451 Strecthability is broken. You must call setResizeEnabled(TRUE) to get
453 proper behavior and even then QDockWindow does not limit
454 stretchablilty.
455 Set this property's value with setHorizontallyStretchable() and get
457 this property's value with isHorizontallyStretchable().
458
460 This property holds whether the user can move the dock window within
461 the dock area, move the dock window to another dock area, or float the
462 dock window.
463 This property is TRUE by default.
465 Set this property's value with setMovingEnabled() and get this
467 property's value with isMovingEnabled().
468
470 This property holds whether the dock window prefers to start a new line
471 in the dock area.
472 The default is FALSE, i.e. the dock window doesn't require a new line
474 in the dock area.
475 Set this property's value with setNewLine() and get this property's
477 value with newLine().
478
480 This property holds the dock window's preferred offset from the dock
481 area's left edge (top edge for vertical dock areas).
482 The default is 0.
484 Set this property's value with setOffset() and get this property's
486 value with offset().
487
489 This property holds whether the dock window will be shown normally
490 whilst it is being moved.
491 If this property is FALSE, (the default), the dock window will be
493 represented by an outline rectangle whilst it is being moved.
494 Warning: Currently opaque moving has some problems and we do not
496 recommend using it at this time. We expect to fix these problems in a
497 future release.
498 Set this property's value with setOpaqueMoving() and get this
500 property's value with opaqueMoving().
501
503 This property holds whether the dock window is resizeable.
504 A resizeable dock window can be resized using splitter-like handles
506 inside a dock area and like every other top level window when floating.
507 A dock window is both horizontally and vertically stretchable if you
509 call setResizeEnabled(TRUE).
510 This property is FALSE by default.
512 See also verticallyStretchable and horizontallyStretchable.
514 Set this property's value with setResizeEnabled() and get this
516 property's value with isResizeEnabled().
517
519 This property holds whether the dock window is stretchable in the
520 current orientation().
521 This property can be set using setHorizontallyStretchable() and
523 setVerticallyStretchable(), or with setResizeEnabled().
524 See also resizeEnabled.
526 Bugs and limitations:
528 Strecthability is broken. You must call setResizeEnabled(TRUE) to get
530 proper behavior and even then QDockWindow does not limit
531 stretchablilty.
532 Get this property's value with isStretchable().
534
536 This property holds whether the dock window is vertically stretchable.
537 A dock window is vertically stretchable if you call
539 setVerticallyStretchable(TRUE) or setResizeEnabled(TRUE).
540 See also resizeEnabled.
542 Bugs and limitations:
544 Strecthability is broken. You must call setResizeEnabled(TRUE) to get
546 proper behavior and even then QDockWindow does not limit
547 stretchablilty.
548 Set this property's value with setVerticallyStretchable() and get this
550 property's value with isVerticallyStretchable().
551
554 http://doc.trolltech.com/qdockwindow.html
555 http://www.trolltech.com/faq/tech.html
556
558 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
559 license file included in the distribution for a complete license
560 statement.
561
563 Generated automatically from the source code.
564
566 If you find a bug in Qt, please report it as described in
567 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
568 help you. Thank you.
569 The definitive Qt documentation is provided in HTML format; it is
571 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
572 web browser. This man page is provided as a convenience for those users
573 who prefer man pages, although this format is not officially supported
574 by Trolltech.
575 If you find errors in this manual page, please report them to qt-
577 bugs@trolltech.com. Please include the name of the manual page
578 (qdockwindow.3qt) and the Qt version (3.3.8).
579Trolltech AS 2 February 2007 QDockWindow(3qt)