1QDockWindow(3qt)                                              QDockWindow(3qt)
2
3
4

NAME

6       QDockWindow - Widget which can be docked inside a QDockArea or floated
7       as a top level window on the desktop
8

SYNOPSIS

10       #include <qdockwindow.h>
11
12       Inherits QFrame.
13
14       Inherited by QToolBar.
15
16   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
55   Public Slots
56       virtual void undock ()
57       virtual void dock ()
58       virtual void setOrientation ( Orientation o )
59
60   Signals
61       void orientationChanged ( Orientation o )
62       void placeChanged ( QDockWindow::Place p )
63       void visibilityChanged ( bool visible )
64
65   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

DESCRIPTION

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
89       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
93       <center>
94                                   [Image Omitted]
95
96       </center> <blockquote><p align="center"> Two QDockWindows (QToolBars)
97       in a QDockArea </p> </blockquote>
98
99       <center>
100                                   [Image Omitted]
101
102       </center> <blockquote><p align="center"> A Floating QDockWindow </p>
103       </blockquote>
104
105       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
116       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
124       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
128           QToolBar *fileTools = new QToolBar( this, "File Actions" );
129           moveDockWindow( fileTools, Left );
130
131       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
136       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
147       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
156       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
162       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
174       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
179       See also Main Window and Related Classes.
180
181   Member Type Documentation

QDockWindow::CloseMode

183       This enum type specifies when (if ever) a dock window has a close
184       button.
185
186       QDockWindow::Never - The dock window never has a close button and
187       cannot be closed by the user.
188
189       QDockWindow::Docked - The dock window has a close button only when
190       docked.
191
192       QDockWindow::Undocked - The dock window has a close button only when
193       floating.
194
195       QDockWindow::Always - The dock window always has a close button.
196

QDockWindow::Place

198       This enum specifies the possible locations for a QDockWindow:
199
200       QDockWindow::InDock - Inside a QDockArea.
201
202       QDockWindow::OutsideDock - Floating as a top level window on the
203       desktop.
204

MEMBER FUNCTION DOCUMENTATION

QDockWindow::QDockWindow ( Place p = InDock, QWidget * parent = 0, const char

207       * name = 0, WFlags f = 0 )
208       Constructs a QDockWindow with parent parent, called name and with
209       widget flags f.
210
211       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
215       If p is OutsideDock, the dock window is created as a floating window.
216
217       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

QDockWindow::QDockWindow ( QWidget * parent, const char * name = 0, WFlags f =

222       0 )
223       Constructs a QDockWindow with parent parent, called name and with
224       widget flags f.
225

QDockArea * QDockWindow::area () const

227       Returns the dock area in which this dock window is docked, or 0 if the
228       dock window is floating.
229

QBoxLayout * QDockWindow::boxLayout ()

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
236       If the dock window only needs to contain a single widget use
237       setWidget() instead.
238
239       See also setWidget() and setOrientation().
240

int QDockWindow::closeMode () const

242       Returns the close mode of a dock window. See the "closeMode" property
243       for details.
244

void QDockWindow::dock () [virtual slot]

246       Docks the dock window into the last dock area in which it was docked.
247
248       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
253       The dock window will dock with the dock area regardless of the return
254       value of QDockArea::isDockWindowAccepted().
255
256       See also undock(), QDockArea::moveDockWindow(),
257       QDockArea::removeDockWindow(), QMainWindow::moveDockWindow(),
258       QMainWindow::removeDockWindow(), and QDockArea::isDockWindowAccepted().
259

QSize QDockWindow::fixedExtent () const

261       Returns the dock window's preferred size (fixed extent).
262
263       See also setFixedExtentWidth() and setFixedExtentHeight().
264

bool QDockWindow::isCloseEnabled () const

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
269       See also closeMode.
270

bool QDockWindow::isHorizontalStretchable () const

272       This function is obsolete. It is provided to keep old source working.
273       We strongly advise against using it in new code.
274

bool QDockWindow::isHorizontallyStretchable () const

276       Returns TRUE if the dock window is horizontally stretchable; otherwise
277       returns FALSE. See the "horizontallyStretchable" property for details.
278

bool QDockWindow::isMovingEnabled () const

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

bool QDockWindow::isResizeEnabled () const

285       Returns TRUE if the dock window is resizeable; otherwise returns FALSE.
286       See the "resizeEnabled" property for details.
287

bool QDockWindow::isStretchable () const

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

bool QDockWindow::isVerticalStretchable () const

294       This function is obsolete. It is provided to keep old source working.
295       We strongly advise against using it in new code.
296

bool QDockWindow::isVerticallyStretchable () const

298       Returns TRUE if the dock window is vertically stretchable; otherwise
299       returns FALSE. See the "verticallyStretchable" property for details.
300

bool QDockWindow::newLine () const

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

int QDockWindow::offset () const

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

bool QDockWindow::opaqueMoving () const

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

Qt::Orientation QDockWindow::orientation () const

316       Returns the orientation of the dock window.
317
318       See also orientationChanged().
319

void QDockWindow::orientationChanged ( Orientation o ) [signal]

321       This signal is emitted when the orientation of the dock window is
322       changed. The new orientation is o.
323

Place QDockWindow::place () const

325       This function returns where the dock window is placed. This is either
326       InDock or OutsideDock.
327
328       See also QDockArea::moveDockWindow(), QDockArea::removeDockWindow(),
329       QMainWindow::moveDockWindow(), and QMainWindow::removeDockWindow().
330

void QDockWindow::placeChanged ( QDockWindow::Place p ) [signal]

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
335       See also QDockArea::moveDockWindow(), QDockArea::removeDockWindow(),
336       QMainWindow::moveDockWindow(), and QMainWindow::removeDockWindow().
337

void QDockWindow::setCloseMode ( int m ) [virtual]

339       Sets the close mode of a dock window to m. See the "closeMode" property
340       for details.
341

void QDockWindow::setFixedExtentHeight ( int h ) [virtual]

343       Sets the dock window's preferred height for its fixed extent (size) to
344       h.
345
346       See also setFixedExtentWidth().
347

void QDockWindow::setFixedExtentWidth ( int w ) [virtual]

349       Sets the dock window's preferred width for its fixed extent (size) to
350       w.
351
352       See also setFixedExtentHeight().
353

void QDockWindow::setHorizontalStretchable ( bool b )

355       This function is obsolete. It is provided to keep old source working.
356       We strongly advise against using it in new code.
357

void QDockWindow::setHorizontallyStretchable ( bool b ) [virtual]

359       Sets whether the dock window is horizontally stretchable to b. See the
360       "horizontallyStretchable" property for details.
361

void QDockWindow::setMovingEnabled ( bool b ) [virtual]

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

void QDockWindow::setNewLine ( bool b ) [virtual]

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

void QDockWindow::setOffset ( int o ) [virtual]

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

void QDockWindow::setOpaqueMoving ( bool b ) [virtual]

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

void QDockWindow::setOrientation ( Orientation o ) [virtual slot]

381       Sets the orientation of the dock window to o. The orientation is
382       propagated to the layout boxLayout().
383
384       Warning: All undocked QToolBars will always have a horizontal
385       orientation.
386

void QDockWindow::setResizeEnabled ( bool b ) [virtual]

388       Sets whether the dock window is resizeable to b. See the
389       "resizeEnabled" property for details.
390

void QDockWindow::setVerticalStretchable ( bool b )

392       This function is obsolete. It is provided to keep old source working.
393       We strongly advise against using it in new code.
394

void QDockWindow::setVerticallyStretchable ( bool b ) [virtual]

396       Sets whether the dock window is vertically stretchable to b. See the
397       "verticallyStretchable" property for details.
398

void QDockWindow::setWidget ( QWidget * w ) [virtual]

400       Sets the dock window's main widget to w.
401
402       See also boxLayout().
403

void QDockWindow::undock () [virtual slot]

405       Undocks the QDockWindow from its current dock area if it is docked;
406       otherwise does nothing.
407
408       See also dock(), QDockArea::moveDockWindow(),
409       QDockArea::removeDockWindow(), QMainWindow::moveDockWindow(), and
410       QMainWindow::removeDockWindow().
411

void QDockWindow::visibilityChanged ( bool visible ) [signal]

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
418       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

QWidget * QDockWindow::widget () const

424       Returns the dock window's main widget.
425
426       See also setWidget().
427
428   Property Documentation

int closeMode

430       This property holds the close mode of a dock window.
431
432       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
436       The default is Never.
437
438       Set this property's value with setCloseMode() and get this property's
439       value with closeMode().
440

bool horizontallyStretchable

442       This property holds whether the dock window is horizontally
443       stretchable.
444
445       A dock window is horizontally stretchable if you call
446       setHorizontallyStretchable(TRUE) or setResizeEnabled(TRUE).
447
448       See also resizeEnabled.
449
450       Bugs and limitations:
451
452       Strecthability is broken. You must call setResizeEnabled(TRUE) to get
453       proper behavior and even then QDockWindow does not limit
454       stretchablilty.
455
456       Set this property's value with setHorizontallyStretchable() and get
457       this property's value with isHorizontallyStretchable().
458

bool movingEnabled

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
464       This property is TRUE by default.
465
466       Set this property's value with setMovingEnabled() and get this
467       property's value with isMovingEnabled().
468

bool newLine

470       This property holds whether the dock window prefers to start a new line
471       in the dock area.
472
473       The default is FALSE, i.e. the dock window doesn't require a new line
474       in the dock area.
475
476       Set this property's value with setNewLine() and get this property's
477       value with newLine().
478

int offset

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
483       The default is 0.
484
485       Set this property's value with setOffset() and get this property's
486       value with offset().
487

bool opaqueMoving

489       This property holds whether the dock window will be shown normally
490       whilst it is being moved.
491
492       If this property is FALSE, (the default), the dock window will be
493       represented by an outline rectangle whilst it is being moved.
494
495       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
499       Set this property's value with setOpaqueMoving() and get this
500       property's value with opaqueMoving().
501

bool resizeEnabled

503       This property holds whether the dock window is resizeable.
504
505       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
508       A dock window is both horizontally and vertically stretchable if you
509       call setResizeEnabled(TRUE).
510
511       This property is FALSE by default.
512
513       See also verticallyStretchable and horizontallyStretchable.
514
515       Set this property's value with setResizeEnabled() and get this
516       property's value with isResizeEnabled().
517

bool stretchable

519       This property holds whether the dock window is stretchable in the
520       current orientation().
521
522       This property can be set using setHorizontallyStretchable() and
523       setVerticallyStretchable(), or with setResizeEnabled().
524
525       See also resizeEnabled.
526
527       Bugs and limitations:
528
529       Strecthability is broken. You must call setResizeEnabled(TRUE) to get
530       proper behavior and even then QDockWindow does not limit
531       stretchablilty.
532
533       Get this property's value with isStretchable().
534

bool verticallyStretchable

536       This property holds whether the dock window is vertically stretchable.
537
538       A dock window is vertically stretchable if you call
539       setVerticallyStretchable(TRUE) or setResizeEnabled(TRUE).
540
541       See also resizeEnabled.
542
543       Bugs and limitations:
544
545       Strecthability is broken. You must call setResizeEnabled(TRUE) to get
546       proper behavior and even then QDockWindow does not limit
547       stretchablilty.
548
549       Set this property's value with setVerticallyStretchable() and get this
550       property's value with isVerticallyStretchable().
551
552

SEE ALSO

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

AUTHOR

563       Generated automatically from the source code.
564

BUGS

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
570       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
576       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).
579
580
581
582Trolltech AS                    2 February 2007               QDockWindow(3qt)
Impressum