1QMainWindow(3qt)                                              QMainWindow(3qt)
2
3
4

NAME

6       QMainWindow - Main application window, with a menu bar, dock windows
7       (e.g. for toolbars), and a status bar
8

SYNOPSIS

10       #include <qmainwindow.h>
11
12       Inherits QWidget.
13
14   Public Members
15       QMainWindow ( QWidget * parent = 0, const char * name = 0, WFlags f =
16           WType_TopLevel )
17       ~QMainWindow ()
18       QMenuBar * menuBar () const
19       QStatusBar * statusBar () const
20       QToolTipGroup * toolTipGroup () const
21       virtual void setCentralWidget ( QWidget * w )
22       QWidget * centralWidget () const
23       virtual void setDockEnabled ( Dock dock, bool enable )
24       bool isDockEnabled ( Dock dock ) const
25       bool isDockEnabled ( QDockArea * area ) const
26       virtual void setDockEnabled ( QDockWindow * dw, Dock dock, bool enable
27           )
28       bool isDockEnabled ( QDockWindow * tb, Dock dock ) const
29       bool isDockEnabled ( QDockWindow * dw, QDockArea * area ) const
30       virtual void addDockWindow ( QDockWindow * dockWindow, Dock edge =
31           DockTop, bool newLine = FALSE )
32       virtual void addDockWindow ( QDockWindow * dockWindow, const QString &
33           label, Dock edge = DockTop, bool newLine = FALSE )
34       virtual void moveDockWindow ( QDockWindow * dockWindow, Dock edge =
35           DockTop )
36       virtual void moveDockWindow ( QDockWindow * dockWindow, Dock edge, bool
37           nl, int index, int extraOffset = -1 )
38       virtual void removeDockWindow ( QDockWindow * dockWindow )
39       bool rightJustification () const  (obsolete)
40       bool usesBigPixmaps () const
41       bool usesTextLabel () const
42       bool dockWindowsMovable () const
43       bool opaqueMoving () const
44       bool getLocation ( QDockWindow * dw, Dock & dock, int & index, bool &
45           nl, int & extraOffset ) const
46       QPtrList<QDockWindow> dockWindows ( Dock dock ) const
47       QPtrList<QDockWindow> dockWindows () const
48       void lineUpDockWindows ( bool keepNewLines = FALSE )
49       bool isDockMenuEnabled () const
50       bool hasDockWindow ( QDockWindow * dw )
51       void addToolBar ( QDockWindow *, Dock = DockTop, bool newLine = FALSE )
52           (obsolete)
53       void addToolBar ( QDockWindow *, const QString & label, Dock = DockTop,
54           bool newLine = FALSE )  (obsolete)
55       void moveToolBar ( QDockWindow *, Dock = DockTop )  (obsolete)
56       void moveToolBar ( QDockWindow *, Dock, bool nl, int index, int
57           extraOffset = -1 )  (obsolete)
58       void removeToolBar ( QDockWindow * )  (obsolete)
59       bool toolBarsMovable () const  (obsolete)
60       QPtrList<QToolBar> toolBars ( Dock dock ) const
61       void lineUpToolBars ( bool keepNewLines = FALSE )  (obsolete)
62       QDockArea * leftDock () const
63       QDockArea * rightDock () const
64       QDockArea * topDock () const
65       QDockArea * bottomDock () const
66       virtual bool isCustomizable () const
67       bool appropriate ( QDockWindow * dw ) const
68       enum DockWindows { OnlyToolBars, NoToolBars, AllDockWindows }
69       QPopupMenu * createDockWindowMenu ( DockWindows dockWindows =
70           AllDockWindows ) const
71
72   Public Slots
73       virtual void setRightJustification ( bool )  (obsolete)
74       virtual void setUsesBigPixmaps ( bool )
75       virtual void setUsesTextLabel ( bool )
76       virtual void setDockWindowsMovable ( bool )
77       virtual void setOpaqueMoving ( bool )
78       virtual void setDockMenuEnabled ( bool b )
79       virtual void whatsThis ()
80       virtual void setAppropriate ( QDockWindow * dw, bool a )
81       virtual void customize ()
82       void setToolBarsMovable ( bool )  (obsolete)
83
84   Signals
85       void pixmapSizeChanged ( bool )
86       void usesTextLabelChanged ( bool )
87       void dockWindowPositionChanged ( QDockWindow * dockWindow )
88       void toolBarPositionChanged ( QToolBar * )  (obsolete)
89
90   Properties
91       bool dockWindowsMovable - whether the dock windows are movable
92       bool opaqueMoving - whether dock windows are moved opaquely
93       bool rightJustification - whether the main window right-justifies its
94           dock windows  (obsolete)
95       bool usesBigPixmaps - whether big pixmaps are enabled
96       bool usesTextLabel - whether text labels for toolbar buttons are
97           enabled
98
99   Protected Members
100       virtual void childEvent ( QChildEvent * e )
101
102   Protected Slots
103       virtual void setUpLayout ()
104       virtual bool showDockMenu ( const QPoint & globalPos )
105       void menuAboutToShow ()
106
108       QTextStream & operator<< ( QTextStream & ts, const QMainWindow &
109           mainWindow )
110       QTextStream & operator>> ( QTextStream & ts, QMainWindow & mainWindow )
111

DESCRIPTION

113       The QMainWindow class provides a main application window, with a menu
114       bar, dock windows (e.g. for toolbars), and a status bar.
115
116       Main windows are most often used to provide menus, toolbars and a
117       status bar around a large central widget, such as a text edit, drawing
118       canvas or QWorkspace (for MDI applications). QMainWindow is usually
119       subclassed since this makes it easier to encapsulate the central
120       widget, menus and toolbars as well as the window's state. Subclassing
121       makes it possible to create the slots that are called when the user
122       clicks menu items or toolbar buttons. You can also create main windows
123       using Qt Designer. We'll briefly review adding menu items and toolbar
124       buttons then describe the facilities of QMainWindow itself.
125
126           QMainWindow *mw = new QMainWindow;
127           QTextEdit *edit = new QTextEdit( mw, "editor" );
128           edit->setFocus();
129           mw->setCaption( "Main Window" );
130           mw->setCentralWidget( edit );
131           mw->show();
132
133       QMainWindows may be created in their own right as shown above. The
134       central widget is set with setCentralWidget(). Popup menus can be added
135       to the default menu bar, widgets can be added to the status bar,
136       toolbars and dock windows can be added to any of the dock areas.
137
138               ApplicationWindow *mw = new ApplicationWindow();
139               mw->setCaption( "Qt Example - Application" );
140               mw->show();
141
142       In the extract above ApplicationWindow is a subclass of QMainWindow
143       that we must write for ourselves; this is the usual approach to using
144       QMainWindow. (The source for the extracts in this description are taken
145       from application/main.cpp, application/application.cpp,
146       action/main.cpp, and action/application.cpp )
147
148       When subclassing we add the menu items and toolbars in the subclass's
149       constructor. If we've created a QMainWindow instance directly we can
150       add menu items and toolbars just as easily by passing the QMainWindow
151       instance as the parent instead of the this pointer.
152
153               QPopupMenu * help = new QPopupMenu( this );
154               menuBar()->insertItem( "&Help", help );
155               help->insertItem( "&About", this, SLOT(about()), Key_F1 );
156
157       Here we've added a new menu with one menu item. The menu has been
158       inserted into the menu bar that QMainWindow provides by default and
159       which is accessible through the menuBar() function. The slot will be
160       called when the menu item is clicked.
161
162               QToolBar * fileTools = new QToolBar( this, "file operations" );
163               fileTools->setLabel( "File Operations" );
164
165               QToolButton * fileOpen
166                   = new QToolButton( openIcon, "Open File", QString::null,
167                                      this, SLOT(choose()), fileTools, "open file" );
168
169       This extract shows the creation of a toolbar with one toolbar button.
170       QMainWindow supplies four dock areas for toolbars. When a toolbar is
171       created as a child of a QMainWindow (or derived class) instance it will
172       be placed in a dock area (the Top dock area by default). The slot will
173       be called when the toolbar button is clicked. Any dock window can be
174       added to a dock area either using addDockWindow(), or by creating a
175       dock window with the QMainWindow as the parent.
176
177               e = new QTextEdit( this, "editor" );
178               e->setFocus();
179               setCentralWidget( e );
180               statusBar()->message( "Ready", 2000 );
181
182       Having created the menus and toolbar we create an instance of the large
183       central widget, give it the focus and set it as the main window's
184       central widget. In the example we've also set the status bar, accessed
185       via the statusBar() function, to an initial message which will be
186       displayed for two seconds. Note that you can add additional widgets to
187       the status bar, for example labels, to show further status information.
188       See the QStatusBar documentation for details, particularly the
189       addWidget() function.
190
191       Often we want to synchronize a toolbar button with a menu item. For
192       example, if the user clicks a 'bold' toolbar button we want the 'bold'
193       menu item to be checked. This synchronization can be achieved
194       automatically by creating actions and adding the actions to the toolbar
195       and menu.
196
197               QAction * fileOpenAction;
198
199               fileOpenAction = new QAction( QPixmap( fileopen ), "&Open...",
200                                             CTRL+Key_O, this, "open" );
201               connect( fileOpenAction, SIGNAL( activated() ) , this, SLOT( choose() ) );
202
203       Here we create an action with an icon which will be used in any menu
204       and toolbar that the action is added to. We've also given the action a
205       menu name, '&Open', and a keyboard shortcut. The connection that we
206       have made will be used when the user clicks either the menu item or the
207       toolbar button.
208
209               QPopupMenu * file = new QPopupMenu( this );
210               menuBar()->insertItem( "&File", file );
211
212               fileOpenAction->addTo( file );
213
214       The extract above shows the creation of a popup menu. We add the menu
215       to the QMainWindow's menu bar and add our action.
216
217               QToolBar * fileTools = new QToolBar( this, "file operations" );
218               fileTools->setLabel( "File Operations" );
219               fileOpenAction->addTo( fileTools );
220
221       Here we create a new toolbar as a child of the QMainWindow and add our
222       action to the toolbar.
223
224       We'll now explore the functionality offered by QMainWindow.
225
226       The main window will take care of the dock areas, and the geometry of
227       the central widget, but all other aspects of the central widget are
228       left to you. QMainWindow automatically detects the creation of a menu
229       bar or status bar if you specify the QMainWindow as parent, or you can
230       use the provided menuBar() and statusBar() functions. The functions
231       menuBar() and statusBar() create a suitable widget if one doesn't
232       exist, and update the window's layout to make space.
233
234       QMainWindow provides a QToolTipGroup connected to the status bar. The
235       function toolTipGroup() provides access to the default QToolTipGroup.
236       It isn't possible to set a different tool tip group.
237
238       New dock windows and toolbars can be added to a QMainWindow using
239       addDockWindow(). Dock windows can be moved using moveDockWindow() and
240       removed with removeDockWindow(). QMainWindow allows default dock window
241       (toolbar) docking in all its dock areas (Top, Left, Right, Bottom). You
242       can use setDockEnabled() to enable and disable docking areas for dock
243       windows. When adding or moving dock windows you can specify their
244       'edge' (dock area). The currently available edges are: Top, Left,
245       Right, Bottom, Minimized (effectively a 'hidden' dock area) and TornOff
246       (floating). See Qt::Dock for an explanation of these areas. Note that
247       the *ToolBar functions are included for backward compatibility; all new
248       code should use the *DockWindow functions. QToolbar is a subclass of
249       QDockWindow so all functions that work with dock windows work on
250       toolbars in the same way.
251
252       If the user clicks the close button, then the dock window is hidden. A
253       dock window can be hidden or unhidden by the user by right clicking a
254       dock area and clicking the name of the relevant dock window on the pop
255       up dock window menu. This menu lists the names of every dock window;
256       visible dock windows have a tick beside their names. The dock window
257       menu is created automatically as required by createDockWindowMenu().
258       Since it may not always be appropriate for a dock window to appear on
259       this menu the setAppropriate() function is used to inform the main
260       window whether or not the dock window menu should include a particular
261       dock window. Double clicking a dock window handle (usually on the left-
262       hand side of the dock window) undocks (floats) the dock window. Double
263       clicking a floating dock window's titlebar will dock the floating dock
264       window. (See also QMainWindow::DockWindows.)
265
266       Some functions change the appearance of a QMainWindow globally:
267
268       QDockWindow::setHorizontalStretchable() and
269       QDockWindow::setVerticalStretchable() are used to make specific dock
270       windows or toolbars stretchable.
271
272       setUsesBigPixmaps() is used to set whether tool buttons should draw
273       small or large pixmaps (see QIconSet for more information).
274
275       setUsesTextLabel() is used to set whether tool buttons should display a
276       textual label in addition to pixmaps (see QToolButton for more
277       information).
278
279       The user can drag dock windows into any enabled docking area. Dock
280       windows can also be dragged within a docking area, for example to
281       rearrange the order of some toolbars. Dock windows can also be dragged
282       outside any docking area (undocked or 'floated'). Being able to drag
283       dock windows can be enabled (the default) and disabled using
284       setDockWindowsMovable().
285
286       The Minimized edge is a hidden dock area. If this dock area is enabled
287       the user can hide (minimize) a dock window or show (restore) a
288       minimized dock window by clicking the dock window handle. If the user
289       hovers the mouse cursor over one of the handles, the caption of the
290       dock window is displayed in a tool tip (see QDockWindow::caption() or
291       QToolBar::label()), so if you enable the Minimized dock area, it is
292       best to specify a meaningful caption or label for each dock window. To
293       minimize a dock window programmatically use moveDockWindow() with an
294       edge of Minimized.
295
296       Dock windows are moved transparently by default, i.e. during the drag
297       an outline rectangle is drawn on the screen representing the position
298       of the dock window as it moves. If you want the dock window to be shown
299       normally whilst it is moved use setOpaqueMoving().
300
301       The location of a dock window, i.e. its dock area and position within
302       the dock area, can be determined by calling getLocation(). Movable dock
303       windows can be lined up to minimize wasted space with
304       lineUpDockWindows(). Pointers to the dock areas are available from
305       topDock(), leftDock(), rightDock() and bottomDock(). A customize menu
306       item is added to the pop up dock window menu if isCustomizable()
307       returns TRUE; it returns FALSE by default. Reimplement isCustomizable()
308       and customize() if you want to offer this extra menu item, for example,
309       to allow the user to change settings relating to the main window and
310       its toolbars and dock windows.
311
312       The main window's menu bar is fixed (at the top) by default. If you
313       want a movable menu bar, create a QMenuBar as a stretchable widget
314       inside its own movable dock window and restrict this dock window to
315       only live within the Top or Bottom dock:
316
317           QToolBar *tb = new QToolBar( this );
318           addDockWindow( tb, tr( "Menubar" ), Top, FALSE );
319           QMenuBar *mb = new QMenuBar( tb );
320           mb->setFrameStyle( QFrame::NoFrame );
321           tb->setStretchableWidget( mb );
322           setDockEnabled( tb, Left, FALSE );
323           setDockEnabled( tb, Right, FALSE );
324
325       An application with multiple dock windows can choose to save the
326       current dock window layout in order to restore it later, e.g. in the
327       next session. You can do this by using the streaming operators for
328       QMainWindow.
329
330       To save the layout and positions of all the dock windows do this:
331
332           QFile file( filename );
333           if ( file.open( IO_WriteOnly ) ) {
334               QTextStream stream( &file );
335               stream << *mainWindow;
336               file.close();
337           }
338
339       To restore the dock window positions and sizes (normally when the
340       application is next started), do following:
341
342           QFile file( filename );
343           if ( file.open( IO_ReadOnly ) ) {
344               QTextStream stream( &file );
345               stream >> *mainWindow;
346               file.close();
347           }
348
349       The QSettings class can be used in conjunction with the streaming
350       operators to store the application's settings.
351
352       QMainWindow's management of dock windows and toolbars is done
353       transparently behind-the-scenes by QDockArea.
354
355       For multi-document interfaces (MDI), use a QWorkspace as the central
356       widget.
357
358       Adding dock windows, e.g. toolbars, to QMainWindow's dock areas is
359       straightforward. If the supplied dock areas are not sufficient for your
360       application we suggest that you create a QWidget subclass and add your
361       own dock areas (see QDockArea) to the subclass since QMainWindow
362       provides functionality specific to the standard dock areas it provides.
363
364                                   [Image Omitted]
365
366                                   [Image Omitted]
367
368       See also QToolBar, QDockWindow, QStatusBar, QAction, QMenuBar,
369       QPopupMenu, QToolTipGroup, QDialog, and Main Window and Related
370       Classes.
371
372   Member Type Documentation

QMainWindow::DockWindows

374       Right-clicking a dock area will pop-up the dock window menu
375       (createDockWindowMenu() is called automatically). When called in code
376       you can specify what items should appear on the menu with this enum.
377
378       QMainWindow::OnlyToolBars - The menu will list all the toolbars, but
379       not any other dock windows.
380
381       QMainWindow::NoToolBars - The menu will list dock windows but not
382       toolbars.
383
384       QMainWindow::AllDockWindows - The menu will list all toolbars and other
385       dock windows. (This is the default.)
386

MEMBER FUNCTION DOCUMENTATION

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

389       f = WType_TopLevel )
390       Constructs an empty main window. The parent, name and widget flags f,
391       are passed on to the QWidget constructor.
392
393       By default, the widget flags are set to WType_TopLevel rather than 0 as
394       they are with QWidget. If you don't want your QMainWindow to be a top
395       level widget then you will need to set f to 0.
396

QMainWindow::~QMainWindow ()

398       Destroys the object and frees any allocated resources.
399

void QMainWindow::addDockWindow ( QDockWindow * dockWindow, Dock edge =

401       DockTop, bool newLine = FALSE ) [virtual]
402       Adds dockWindow to the edge dock area.
403
404       If newLine is FALSE (the default) then the dockWindow is added at the
405       end of the edge. For vertical edges the end is at the bottom, for
406       horizontal edges (including Minimized) the end is at the right. If
407       newLine is TRUE a new line of dock windows is started with dockWindow
408       as the first (left-most and top-most) dock window.
409
410       If dockWindow is managed by another main window, it is first removed
411       from that window.
412

void QMainWindow::addDockWindow ( QDockWindow * dockWindow, const QString &

414       label, Dock edge = DockTop, bool newLine = FALSE ) [virtual]
415       This is an overloaded member function, provided for convenience. It
416       behaves essentially like the above function.
417
418       Adds dockWindow to the dock area with label label.
419
420       If newLine is FALSE (the default) the dockWindow is added at the end of
421       the edge. For vertical edges the end is at the bottom, for horizontal
422       edges (including Minimized) the end is at the right. If newLine is TRUE
423       a new line of dock windows is started with dockWindow as the first
424       (left-most and top-most) dock window.
425
426       If dockWindow is managed by another main window, it is first removed
427       from that window.
428

void QMainWindow::addToolBar ( QDockWindow *, Dock = DockTop, bool newLine =

430       FALSE )
431       This function is obsolete. It is provided to keep old source working.
432       We strongly advise against using it in new code.
433

void QMainWindow::addToolBar ( QDockWindow *, const QString & label, Dock =

435       DockTop, bool newLine = FALSE )
436       This function is obsolete. It is provided to keep old source working.
437       We strongly advise against using it in new code.
438
439       This is an overloaded member function, provided for convenience. It
440       behaves essentially like the above function.
441

bool QMainWindow::appropriate ( QDockWindow * dw ) const

443       Returns TRUE if it is appropriate to include a menu item for the dw
444       dock window in the dock window menu; otherwise returns FALSE.
445
446       The user is able to change the state (show or hide) a dock window that
447       has a menu item by clicking the item.
448
449       Call setAppropriate() to indicate whether or not a particular dock
450       window should appear on the popup menu.
451
452       See also setAppropriate().
453

QDockArea * QMainWindow::bottomDock () const

455       Returns a pointer the Bottom dock area
456
457       See also topDock(), leftDock(), and rightDock().
458

QWidget * QMainWindow::centralWidget () const

460       Returns a pointer to the main window's central widget.
461
462       The central widget is surrounded by the left, top, right and bottom
463       dock areas. The menu bar is above the top dock area.
464
465       See also setCentralWidget().
466
467       Example: qfd/qfd.cpp.
468

void QMainWindow::childEvent ( QChildEvent * e ) [virtual protected]

470       Monitors events, recieved in e, to ensure the layout is updated.
471
472       Reimplemented from QObject.
473

QPopupMenu * QMainWindow::createDockWindowMenu ( DockWindows dockWindows =

475       AllDockWindows ) const
476       Creates the dock window menu which contains all toolbars (if
477       dockWindows is OnlyToolBars ), all dock windows (if dockWindows is
478       NoToolBars) or all toolbars and dock windows (if dockWindows is
479       AllDockWindows - the default).
480
481       This function is called internally when necessary, e.g. when the user
482       right clicks a dock area (providing isDockMenuEnabled() returns TRUE).
483
484       The menu items representing the toolbars and dock windows are
485       checkable. The visible dock windows are checked and the hidden dock
486       windows are unchecked. The user can click a menu item to change its
487       state (show or hide the dock window).
488
489       The list and the state are always kept up-to-date.
490
491       Toolbars and dock windows which are not appropriate in the current
492       context (see setAppropriate()) are not listed in the menu.
493
494       The menu also has a menu item for lining up the dock windows.
495
496       If isCustomizable() returns TRUE, a Customize menu item is added to the
497       menu, which if clicked will call customize(). The isCustomizable()
498       function we provide returns FALSE and customize() does nothing, so they
499       must be reimplemented in a subclass to be useful.
500

void QMainWindow::customize () [virtual slot]

502       This function is called when the user clicks the Customize menu item on
503       the dock window menu.
504
505       The customize menu item will only appear if isCustomizable() returns
506       TRUE (it returns FALSE by default).
507
508       The function is intended, for example, to provide the user with a means
509       of telling the application that they wish to customize the main window,
510       dock windows or dock areas.
511
512       The default implementation does nothing and the Customize menu item is
513       not shown on the right-click menu by default. If you want the item to
514       appear then reimplement isCustomizable() to return TRUE, and
515       reimplement this function to do whatever you want.
516
517       See also isCustomizable().
518

void QMainWindow::dockWindowPositionChanged ( QDockWindow * dockWindow )

520       [signal]
521       This signal is emitted when the dockWindow has changed its position. A
522       change in position occurs when a dock window is moved within its dock
523       area or moved to another dock area (including the Minimized and TearOff
524       dock areas).
525
526       See also getLocation().
527

QPtrList<QDockWindow> QMainWindow::dockWindows ( Dock dock ) const

529       Returns a list of all the dock windows which are in the dock dock area,
530       regardless of their state.
531
532       For example, the DockTornOff dock area may contain closed dock windows
533       but these are returned along with the visible dock windows.
534

QPtrList<QDockWindow> QMainWindow::dockWindows () const

536       This is an overloaded member function, provided for convenience. It
537       behaves essentially like the above function.
538
539       Returns the list of dock windows which belong to this main window,
540       regardless of which dock area they are in or what their state is, (e.g.
541       irrespective of whether they are visible or not).
542

bool QMainWindow::dockWindowsMovable () const

544       Returns TRUE if the dock windows are movable; otherwise returns FALSE.
545       See the "dockWindowsMovable" property for details.
546

bool QMainWindow::getLocation ( QDockWindow * dw, Dock & dock, int & index,

548       bool & nl, int & extraOffset ) const
549       Finds the location of the dock window dw.
550
551       If the dw dock window is found in the main window the function returns
552       TRUE and populates the dock variable with the dw's dock area and the
553       index with the dw's position within the dock area. It also sets nl to
554       TRUE if the dw begins a new line (otherwise FALSE), and extraOffset
555       with the dock window's offset.
556
557       If the dw dock window is not found then the function returns FALSE and
558       the state of dock, index, nl and extraOffset is undefined.
559
560       If you want to save and restore dock window positions then use
561       operator>>() and operator<<().
562
563       See also operator>>() and operator<<().
564

bool QMainWindow::hasDockWindow ( QDockWindow * dw )

566       Returns TRUE if dw is a dock window known to the main window; otherwise
567       returns FALSE.
568

bool QMainWindow::isCustomizable () const [virtual]

570       Returns TRUE if the dock area dock window menu includes the Customize
571       menu item (which calls customize() when clicked). Returns FALSE by
572       default, i.e. the popup menu will not contain a Customize menu item.
573       You will need to reimplement this function and set it to return TRUE if
574       you wish the user to be able to see the dock window menu.
575
576       See also customize().
577

bool QMainWindow::isDockEnabled ( Dock dock ) const

579       Returns TRUE if the dock dock area is enabled, i.e. it can accept user
580       dragged dock windows; otherwise returns FALSE.
581
582       See also setDockEnabled().
583

bool QMainWindow::isDockEnabled ( QDockArea * area ) const

585       This is an overloaded member function, provided for convenience. It
586       behaves essentially like the above function.
587
588       Returns TRUE if dock area area is enabled, i.e. it can accept user
589       dragged dock windows; otherwise returns FALSE.
590
591       See also setDockEnabled().
592

bool QMainWindow::isDockEnabled ( QDockWindow * tb, Dock dock ) const

594       This is an overloaded member function, provided for convenience. It
595       behaves essentially like the above function.
596
597       Returns TRUE if dock area dock is enabled for the dock window tb;
598       otherwise returns FALSE.
599
600       See also setDockEnabled().
601

bool QMainWindow::isDockEnabled ( QDockWindow * dw, QDockArea * area ) const

603       This is an overloaded member function, provided for convenience. It
604       behaves essentially like the above function.
605
606       Returns TRUE if dock area area is enabled for the dock window dw;
607       otherwise returns FALSE.
608
609       See also setDockEnabled().
610

bool QMainWindow::isDockMenuEnabled () const

612       Returns TRUE, if the dock window menu is enabled; otherwise returns
613       FALSE.
614
615       The menu lists the (appropriate()) dock windows (which may be shown or
616       hidden), and has a "Line Up Dock Windows" menu item. It will also have
617       a "Customize" menu item if isCustomizable() returns TRUE.
618
619       See also setDockEnabled(), lineUpDockWindows(), appropriate(), and
620       setAppropriate().
621

QDockArea * QMainWindow::leftDock () const

623       Returns the Left dock area
624
625       See also rightDock(), topDock(), and bottomDock().
626

void QMainWindow::lineUpDockWindows ( bool keepNewLines = FALSE )

628       This function will line up dock windows within the visible dock areas
629       (Top, Left, Right and Bottom) as compactly as possible.
630
631       If keepNewLines is TRUE, all dock windows stay on their original lines.
632       If keepNewLines is FALSE then newlines may be removed to achieve the
633       most compact layout possible.
634
635       The method only works if dockWindowsMovable() returns TRUE.
636

void QMainWindow::lineUpToolBars ( bool keepNewLines = FALSE )

638       This function is obsolete. It is provided to keep old source working.
639       We strongly advise against using it in new code.
640

void QMainWindow::menuAboutToShow () [protected slot]

642       This slot is called from the aboutToShow() signal of the default dock
643       menu of the mainwindow. The default implementation initializes the menu
644       with all dock windows and toolbars in this slot.
645

QMenuBar * QMainWindow::menuBar () const

647       Returns the menu bar for this window.
648
649       If there isn't one, then menuBar() creates an empty menu bar.
650
651       See also statusBar().
652

void QMainWindow::moveDockWindow ( QDockWindow * dockWindow, Dock edge =

654       DockTop ) [virtual]
655       Moves dockWindow to the end of the edge.
656
657       For vertical edges the end is at the bottom, for horizontal edges
658       (including Minimized) the end is at the right.
659
660       If dockWindow is managed by another main window, it is first removed
661       from that window.
662

void QMainWindow::moveDockWindow ( QDockWindow * dockWindow, Dock edge, bool

664       nl, int index, int extraOffset = -1 ) [virtual]
665       This is an overloaded member function, provided for convenience. It
666       behaves essentially like the above function.
667
668       Moves dockWindow to position index within the edge dock area.
669
670       Any dock windows with positions index or higher have their position
671       number incremented and any of these on the same line are moved right
672       (down for vertical dock areas) to make room.
673
674       If nl is TRUE, a new dock window line is created below the line in
675       which the moved dock window appears and the moved dock window, with any
676       others with higher positions on the same line, is moved to this new
677       line.
678
679       The extraOffset is the space to put between the left side of the dock
680       area (top side for vertical dock areas) and the dock window. (This is
681       mostly used for restoring dock windows to the positions the user has
682       dragged them to.)
683
684       If dockWindow is managed by another main window, it is first removed
685       from that window.
686

void QMainWindow::moveToolBar ( QDockWindow *, Dock = DockTop )

688       This function is obsolete. It is provided to keep old source working.
689       We strongly advise against using it in new code.
690

void QMainWindow::moveToolBar ( QDockWindow *, Dock, bool nl, int index, int

692       extraOffset = -1 )
693       This function is obsolete. It is provided to keep old source working.
694       We strongly advise against using it in new code.
695
696       This is an overloaded member function, provided for convenience. It
697       behaves essentially like the above function.
698

bool QMainWindow::opaqueMoving () const

700       Returns TRUE if dock windows are moved opaquely; otherwise returns
701       FALSE. See the "opaqueMoving" property for details.
702

void QMainWindow::pixmapSizeChanged ( bool ) [signal]

704       This signal is emitted whenever the setUsesBigPixmaps() is called with
705       a value different to the current setting. All widgets that should
706       respond to such changes, e.g. toolbar buttons, must connect to this
707       signal.
708

void QMainWindow::removeDockWindow ( QDockWindow * dockWindow ) [virtual]

710       Removes dockWindow from the main window's docking area, provided
711       dockWindow is non-null and managed by this main window.
712

void QMainWindow::removeToolBar ( QDockWindow * )

714       This function is obsolete. It is provided to keep old source working.
715       We strongly advise against using it in new code.
716

QDockArea * QMainWindow::rightDock () const

718       Returns the Right dock area
719
720       See also leftDock(), topDock(), and bottomDock().
721

bool QMainWindow::rightJustification () const

723       Returns TRUE if the main window right-justifies its dock windows;
724       otherwise returns FALSE. See the "rightJustification" property for
725       details.
726

void QMainWindow::setAppropriate ( QDockWindow * dw, bool a ) [virtual slot]

728       Use this function to control whether or not the dw dock window's
729       caption should appear as a menu item on the dock window menu that lists
730       the dock windows.
731
732       If a is TRUE then the dw will appear as a menu item on the dock window
733       menu. The user is able to change the state (show or hide) a dock window
734       that has a menu item by clicking the item; depending on the state of
735       your application, this may or may not be appropriate. If a is FALSE the
736       dw will not appear on the popup menu.
737
738       See also showDockMenu(), isCustomizable(), and customize().
739

void QMainWindow::setCentralWidget ( QWidget * w ) [virtual]

741       Sets the central widget for this main window to w.
742
743       The central widget is surrounded by the left, top, right and bottom
744       dock areas. The menu bar is above the top dock area.
745
746       See also centralWidget().
747

void QMainWindow::setDockEnabled ( Dock dock, bool enable ) [virtual]

749       If enable is TRUE then users can dock windows in the dock area. If
750       enable is FALSE users cannot dock windows in the dock dock area.
751
752       Users can dock (drag) dock windows into any enabled dock area.
753

void QMainWindow::setDockEnabled ( QDockWindow * dw, Dock dock, bool enable )

755       [virtual]
756       This is an overloaded member function, provided for convenience. It
757       behaves essentially like the above function.
758
759       If enable is TRUE then users can dock the dw dock window in the dock
760       area. If enable is FALSE users cannot dock the dw dock window in the
761       dock area.
762
763       In general users can dock (drag) dock windows into any enabled dock
764       area. Using this function particular dock areas can be enabled (or
765       disabled) as docking points for particular dock windows.
766

void QMainWindow::setDockMenuEnabled ( bool b ) [virtual slot]

768       If b is TRUE, then right clicking on a dock window or dock area will
769       pop up the dock window menu. If b is FALSE, right clicking a dock
770       window or dock area will not pop up the menu.
771
772       The menu lists the (appropriate()) dock windows (which may be shown or
773       hidden), and has a "Line Up Dock Windows" item. It will also have a
774       "Customize" menu item if isCustomizable() returns TRUE.
775
776       See also lineUpDockWindows() and isDockMenuEnabled().
777

void QMainWindow::setDockWindowsMovable ( bool ) [virtual slot]

779       Sets whether the dock windows are movable. See the "dockWindowsMovable"
780       property for details.
781

void QMainWindow::setOpaqueMoving ( bool ) [virtual slot]

783       Sets whether dock windows are moved opaquely. See the "opaqueMoving"
784       property for details.
785

void QMainWindow::setRightJustification ( bool ) [virtual slot]

787       Sets whether the main window right-justifies its dock windows. See the
788       "rightJustification" property for details.
789

void QMainWindow::setToolBarsMovable ( bool ) [slot]

791       This function is obsolete. It is provided to keep old source working.
792       We strongly advise against using it in new code.
793

void QMainWindow::setUpLayout () [virtual protected slot]

795       Sets up the geometry management of the window. It is called
796       automatically when needed, so you shouldn't need to call it.
797

void QMainWindow::setUsesBigPixmaps ( bool ) [virtual slot]

799       Sets whether big pixmaps are enabled. See the "usesBigPixmaps" property
800       for details.
801

void QMainWindow::setUsesTextLabel ( bool ) [virtual slot]

803       Sets whether text labels for toolbar buttons are enabled. See the
804       "usesTextLabel" property for details.
805

bool QMainWindow::showDockMenu ( const QPoint & globalPos ) [virtual protected

807       slot]
808       Shows the dock menu at the position globalPos. The menu lists the dock
809       windows so that they can be shown (or hidden), lined up, and possibly
810       customized. Returns TRUE if the menu is shown; otherwise returns FALSE.
811
812       If you want a custom menu, reimplement this function. You can create
813       the menu from scratch or call createDockWindowMenu() and modify the
814       result.
815

QStatusBar * QMainWindow::statusBar () const

817       Returns this main window's status bar. If there isn't one, statusBar()
818       creates an empty status bar, and if necessary a tool tip group too.
819
820       See also menuBar() and toolTipGroup().
821
822       Example: qfd/qfd.cpp.
823

void QMainWindow::toolBarPositionChanged ( QToolBar * ) [signal]

825       This function is obsolete. It is provided to keep old source working.
826       We strongly advise against using it in new code.
827

QPtrList<QToolBar> QMainWindow::toolBars ( Dock dock ) const

829       Returns a list of all the toolbars which are in the dock dock area,
830       regardless of their state.
831
832       For example, the TornOff dock area may contain closed toolbars but
833       these are returned along with the visible toolbars.
834
835       See also dockWindows().
836

bool QMainWindow::toolBarsMovable () const

838       This function is obsolete. It is provided to keep old source working.
839       We strongly advise against using it in new code.
840

QToolTipGroup * QMainWindow::toolTipGroup () const

842       Returns this main window's tool tip group. If there isn't one,
843       toolTipGroup() creates an empty tool tip group.
844
845       See also menuBar() and statusBar().
846

QDockArea * QMainWindow::topDock () const

848       Returns the Top dock area
849
850       See also bottomDock(), leftDock(), and rightDock().
851

bool QMainWindow::usesBigPixmaps () const

853       Returns TRUE if big pixmaps are enabled; otherwise returns FALSE. See
854       the "usesBigPixmaps" property for details.
855

bool QMainWindow::usesTextLabel () const

857       Returns TRUE if text labels for toolbar buttons are enabled; otherwise
858       returns FALSE. See the "usesTextLabel" property for details.
859

void QMainWindow::usesTextLabelChanged ( bool ) [signal]

861       This signal is emitted whenever the setUsesTextLabel() is called with a
862       value different to the current setting. All widgets that should respond
863       to such changes, e.g. toolbar buttons, must connect to this signal.
864

void QMainWindow::whatsThis () [virtual slot]

866       Enters 'What's This?' mode and returns immediately.
867
868       This is the same as QWhatsThis::enterWhatsThisMode(), but implemented
869       as a main window object's slot. This way it can easily be used for
870       popup menus, for example:
871
872           QPopupMenu * help = new QPopupMenu( this );
873           help->insertItem( "What's &This", this , SLOT(whatsThis()), SHIFT+Key_F1);
874
875       See also QWhatsThis::enterWhatsThisMode().
876
877   Property Documentation

bool dockWindowsMovable

879       This property holds whether the dock windows are movable.
880
881       If TRUE (the default), the user will be able to move movable dock
882       windows from one QMainWindow dock area to another, including the
883       TearOff area (i.e. where the dock window floats freely as a window in
884       its own right), and the Minimized area (where only the dock window's
885       handle is shown below the menu bar). Moveable dock windows can also be
886       moved within QMainWindow dock areas, i.e. to rearrange them within a
887       dock area.
888
889       If FALSE the user will not be able to move any dock windows.
890
891       By default dock windows are moved transparently (i.e. only an outline
892       rectangle is shown during the drag), but this setting can be changed
893       with setOpaqueMoving().
894
895       See also setDockEnabled() and opaqueMoving.
896
897       Set this property's value with setDockWindowsMovable() and get this
898       property's value with dockWindowsMovable().
899

bool opaqueMoving

901       This property holds whether dock windows are moved opaquely.
902
903       If TRUE the dock windows of the main window are shown opaquely (i.e. it
904       shows the toolbar as it looks when docked) whilst it is being moved. If
905       FALSE (the default) they are shown transparently, (i.e. as an outline
906       rectangle).
907
908       Warning: Opaque moving of toolbars and dockwindows is known to have
909       several problems. We recommend avoiding the use of this feature for the
910       time being. We intend fixing the problems in a future release.
911
912       Set this property's value with setOpaqueMoving() and get this
913       property's value with opaqueMoving().
914

bool rightJustification

916       This function is obsolete. It is provided to keep old source working.
917       We strongly advise against using it in new code.
918
919       This property holds whether the main window right-justifies its dock
920       windows.
921
922       If disabled (the default), stretchable dock windows are expanded, and
923       non-stretchable dock windows are given the minimum space they need.
924       Since most dock windows are not stretchable, this usually results in an
925       unjustified right edge (or unjustified bottom edge for a vertical dock
926       area). If enabled, the main window will right-justify its dock windows.
927
928       See also QDockWindow::setVerticalStretchable() and
929       QDockWindow::setHorizontalStretchable().
930
931       Set this property's value with setRightJustification() and get this
932       property's value with rightJustification().
933

bool usesBigPixmaps

935       This property holds whether big pixmaps are enabled.
936
937       If FALSE (the default), the tool buttons will use small pixmaps;
938       otherwise big pixmaps will be used.
939
940       Tool buttons and other widgets that wish to respond to this setting are
941       responsible for reading the correct state on startup, and for
942       connecting to the main window's widget's pixmapSizeChanged() signal.
943
944       Set this property's value with setUsesBigPixmaps() and get this
945       property's value with usesBigPixmaps().
946

bool usesTextLabel

948       This property holds whether text labels for toolbar buttons are
949       enabled.
950
951       If disabled (the default), the tool buttons will not use text labels.
952       If enabled, text labels will be used.
953
954       Tool buttons and other widgets that wish to respond to this setting are
955       responsible for reading the correct state on startup, and for
956       connecting to the main window's widget's usesTextLabelChanged() signal.
957
958       See also QToolButton::usesTextLabel.
959
960       Set this property's value with setUsesTextLabel() and get this
961       property's value with usesTextLabel().
962

QTextStream & operator<< ( QTextStream & ts, const QMainWindow & mainWindow )

965       Writes the layout (sizes and positions) of the dock windows in the dock
966       areas of the QMainWindow mainWindow, including Minimized and TornOff
967       dock windows, to the text stream ts.
968
969       This can be used, for example, in conjunction with QSettings to save
970       the user's layout when the \mainWindow receives a closeEvent.
971
972       See also operator>>() and closeEvent().
973

QTextStream & operator>> ( QTextStream & ts, QMainWindow & mainWindow )

975       Reads the layout (sizes and positions) of the dock windows in the dock
976       areas of the QMainWindow mainWindow from the text stream, ts, including
977       Minimized and TornOff dock windows. Restores the dock windows and dock
978       areas to these sizes and positions. The layout information must be in
979       the format produced by operator<<().
980
981       This can be used, for example, in conjunction with QSettings to restore
982       the user's layout.
983
984       See also operator<<().
985
986

SEE ALSO

988       http://doc.trolltech.com/qmainwindow.html
989       http://www.trolltech.com/faq/tech.html
990
992       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
993       license file included in the distribution for a complete license
994       statement.
995

AUTHOR

997       Generated automatically from the source code.
998

BUGS

1000       If you find a bug in Qt, please report it as described in
1001       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
1002       help you. Thank you.
1003
1004       The definitive Qt documentation is provided in HTML format; it is
1005       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
1006       web browser. This man page is provided as a convenience for those users
1007       who prefer man pages, although this format is not officially supported
1008       by Trolltech.
1009
1010       If you find errors in this manual page, please report them to qt-
1011       bugs@trolltech.com.  Please include the name of the manual page
1012       (qmainwindow.3qt) and the Qt version (3.3.8).
1013
1014
1015
1016Trolltech AS                    2 February 2007               QMainWindow(3qt)
Impressum