qwidget.3qt

Linux下的基于X11的图形开发环境。

.PP
A widget that isn't embedded in a parent widget is called a top-level widget. Usually, top-level widgets are windows with a frame and a title bar (although it is also possible to create top-level widgets without such decoration if suitable widget flags are used). In Qt, QMainWindow and the various subclasses of QDialog are the most common top-level windows.
.PP
A widget without a parent widget is always a top-level widget.
.PP
Non-top-level widgets are child widgets. These are child windows in their parent widgets. You cannot usually distinguish a child widget from its parent visually. Most other widgets in Qt are useful only as child widgets. (It is possible to make, say, a button into a top-level widget, but most people prefer to put their buttons inside other widgets, e.g. QDialog.)
.PP
QWidget has many member functions, but some of them have little direct functionality: for example, QWidget has a font property, but never uses this itself. There are many subclasses which provide real functionality, such as QPushButton, QListBox and QTabDialog, etc.
.SH "Groups of functions:"
<center>.nf
.TS
l - l. Context Functions Window functions show(), hide(), raise(), lower(), close(). Top level windows caption(), setCaption(), icon(), setIcon(), iconText(), setIconText(), isActiveWindow(), setActiveWindow(), showMinimized(). showMaximized(), showFullScreen(), showNormal(). Window contents update(), repaint(), erase(), scroll(), updateMask(). Geometry pos(), size(), rect(), x(), y(), width(), height(), sizePolicy(), setSizePolicy(), sizeHint(), updateGeometry(), layout(), move(), resize(), setGeometry(), frameGeometry(), geometry(), childrenRect(), adjustSize(), mapFromGlobal(), mapFromParent() mapToGlobal(), mapToParent(), maximumSize(), minimumSize(), sizeIncrement(), setMaximumSize(), setMinimumSize(), setSizeIncrement(), setBaseSize(), setFixedSize() Mode isVisible(), isVisibleTo(), visibleRect(), isMinimized(), isDesktop(), isEnabled(), isEnabledTo(), isModal(), isPopup(), isTopLevel(), setEnabled(), hasMouseTracking(), setMouseTracking(), isUpdatesEnabled(), setUpdatesEnabled(), Look and feel style(), setStyle(), cursor(), setCursor() font(), setFont(), palette(), setPalette(), backgroundMode(), setBackgroundMode(), colorGroup(), fontMetrics(), fontInfo(). Keyboard focus
.br
functions isFocusEnabled(), setFocusPolicy(), focusPolicy(), hasFocus(), setFocus(), clearFocus(), setTabOrder(), setFocusProxy(). Mouse and
.br
keyboard grabbing grabMouse(), releaseMouse(), grabKeyboard(), releaseKeyboard(), mouseGrabber(), keyboardGrabber(). Event handlers event(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), keyPressEvent(), keyReleaseEvent(), focusInEvent(), focusOutEvent(), wheelEvent(), enterEvent(), leaveEvent(), paintEvent(), moveEvent(), resizeEvent(), closeEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), childEvent(), showEvent(), hideEvent(), customEvent(). Change handlers enabledChange(), fontChange(), paletteChange(), styleChange(), windowActivationChange(). System functions parentWidget(), topLevelWidget(), reparent(), polish(), winId(), find(), metric(). What's this help customWhatsThis() Internal kernel
.br
functions
.TE
.fi
</center>
.PP
Every widget's constructor accepts two or three standard arguments: <ol type=1>
.IP 1
\fCQWidget *parent = 0\fR is the parent of the new widget. If it is 0 (the default), the new widget will be a top-level window. If not, it will be a child of \fIparent\fR, and be constrained by \fIparent\fR's geometry (unless you specify WType_TopLevel as widget flag).
.IP 2
\fCconst char *name = 0\fR is the widget name of the new widget. You can access it using name(). The widget name is little used by programmers but is quite useful with GUI builders such as \fIQt Designer\fR (you can name a widget in \fIQt Designer\fR, and connect() to it using the name in your code). The dumpObjectTree() debugging function also uses it.
.IP 3
\fCWFlags f = 0\fR (where available) sets the widget flags; the default is suitable for almost all widgets, but to get, for example, a top-level widget without a window system frame, you must use special flags.
.PP
The tictac/tictac.cpp example program is good example of a simple widget. It contains a few event handlers (as all widgets must), a few custom routines that are specific to it (as all useful widgets do), and has a few children and connections. Everything it does is done in response to an event: this is by far the most common way to design GUI applications.
.PP
You will need to supply the content for your widgets yourself, but here is a brief run-down of the events, starting with the most common ones:
.IP
.TP
paintEvent() - called whenever the widget needs to be repainted. Every widget which displays output must implement it, and it is wise \fInot\fR to paint on the screen outside paintEvent().
.IP
.TP
resizeEvent() - called when the widget has been resized.
.IP
.TP
mousePressEvent() - called when a mouse button is pressed. There are six mouse-related events, but the mouse press and mouse release events are by far the most important. A widget receives mouse press events when the mouse is inside it, or when it has grabbed the mouse using grabMouse().
.IP
.TP
mouseReleaseEvent() - called when a mouse button is released. A widget receives mouse release events when it has received the corresponding mouse press event. This means that if the user presses the mouse inside \fIyour\fR widget, then drags the mouse to somewhere else, then releases, \fIyour\fR widget receives the release event. There is one exception: if a popup menu appears while the mouse button is held down, this popup immediately steals the mouse events.
.IP
.TP
mouseDoubleClickEvent() - not quite as obvious as it might seem. If the user double-clicks, the widget receives a mouse press event (perhaps a mouse move event or two if they don't hold the mouse quite steady), a mouse release event and finally this event. It is \fInot possible\fR to distinguish a click from a double click until you've seen whether the second click arrives. (This is one reason why most GUI books recommend that double clicks be an extension of single clicks, rather than trigger a different action.)
.IP
.PP
If your widget only contains child widgets, you probably do not need to implement any event handlers. If you want to detect a mouse click in a child widget call the child's hasMouse() function inside the parent widget's mousePressEvent().
.PP
Widgets that accept keyboard input need to reimplement a few more event handlers:
.IP
.TP
keyPressEvent() - called whenever a key is pressed, and again when a key has been held down long enough for it to auto-repeat. Note that the Tab and Shift+Tab keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement QWidget::event().
.IP
.TP
focusInEvent() - called when the widget gains keyboard focus (assuming you have called setFocusPolicy()). Well written widgets indicate that they own the keyboard focus in a clear but discreet way.
.IP
.TP
focusOutEvent() - called when the widget loses keyboard focus.
.IP
.PP
Some widgets will also need to reimplement some of the less common event handlers:
.IP
.TP
mouseMoveEvent() - called whenever the mouse moves while a button is held down. This is useful for, for example, dragging. If you call setMouseTracking(TRUE), you get mouse move events even when no buttons are held down. (Note that applications which make use of mouse tracking are often not very useful on low-bandwidth X connections.) (See also the drag and drop information.)
.IP
.TP
keyReleaseEvent() - called whenever a key is released, and also while it is held down if the key is auto-repeating. In that case the widget receives a key release event and immediately a key press event for every repeat. Note that the Tab and Shift+Tab keys are only passed to the widget if they are not used by the focus-change mechanisms. To force those keys to be processed by your widget, you must reimplement QWidget::event().
.IP
.TP
wheelEvent() -- called whenever the user turns the mouse wheel while the widget has the focus.
.IP
.TP
enterEvent() - called when the mouse enters the widget's screen space. (This excludes screen space owned by any children of the widget.)
.IP
.TP
leaveEvent() - called when the mouse leaves the widget's screen space.
.IP
.TP
moveEvent() - called when the widget has been moved relative to its parent.
.IP
.TP
closeEvent() - called when the user closes the widget (or when close() is called).
.IP
.PP
There are also some rather obscure events. They are listed in qevent.h and you need to reimplement event() to handle them. The default implementation of event() handles Tab and Shift+Tab (to move the keyboard focus), and passes on most other events to one of the more specialized handlers above.
.PP
When implementing a widget, there are a few more things to consider.
.IP
.TP
In the constructor, be sure to set up your member variables early on, before there's any chance that you might receive an event.
.IP
.TP
It is almost always useful to reimplement sizeHint() and to set the correct size policy with setSizePolicy(), so users of your class can set up layout management more easily. A size policy lets you supply good defaults for the layout management handling, so that other widgets can contain and manage yours easily. sizeHint() indicates a "good" size for the widget.
.IP
.TP
If your widget is a top-level window, setCaption() and setIcon() set the title bar and icon respectively.
.IP
.PP
See also QEvent, QPainter, QGridLayout, QBoxLayout, and Abstract Widget Classes.
.SS "Member Type Documentation"
.SH "QWidget::BackgroundOrigin"
This enum defines the origin used to draw a widget's background pixmap.
.PP
The pixmap is drawn using the:
.TP
\fCQWidget::WidgetOrigin\fR - widget's coordinate system.
.TP
\fCQWidget::ParentOrigin\fR - parent's coordinate system.
.TP
\fCQWidget::WindowOrigin\fR - top-level window's coordinate system.
.TP
\fCQWidget::AncestorOrigin\fR - same origin as the parent uses.
.SH "QWidget::FocusPolicy"
This enum type defines the various policies a widget can have with respect to acquiring keyboard focus.
.TP
\fCQWidget::TabFocus\fR - the widget accepts focus by tabbing.
.TP
\fCQWidget::ClickFocus\fR - the widget accepts focus by clicking.
.TP
\fCQWidget::StrongFocus\fR - the widget accepts focus by both tabbing and clicking.
.TP
\fCQWidget::WheelFocus\fR - like StrongFocus plus the widget accepts focus by using the mouse wheel.
.TP
\fCQWidget::NoFocus\fR - the widget does not accept focus.
.PP
.SH MEMBER FUNCTION DOCUMENTATION
.SH "explicit QWidget::QWidget ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )"
Constructs a widget which is a child of \fIparent\fR, with the name \fIname\fR and widget flags set to \fIf\fR.
.PP
If \fIparent\fR is 0, the new widget becomes a top-level window. If \fIparent\fR is another widget, this widget becomes a child window inside \fIparent\fR. The new widget is deleted when its \fIparent\fR is deleted.
.PP
The \fIname\fR is sent to the QObject constructor.
.PP
The widget flags argument, \fIf\fR, is normally 0, but it can be set to customize the window frame of a top-level widget (i.e. \fIparent\fR must be 0). To customize the frame, set the WStyle_Customize flag OR'ed with any of the Qt::WidgetFlags.
.PP
If you add a child widget to an already visible widget you must explicitly show the child to make it visible.
.PP
Note that the X11 version of Qt may not be able to deliver all combinations of style flags on all systems. This is because on X11, Qt can only ask the window manager, and the window manager can override the application's settings. On Windows, Qt can set whatever flags you want.
.PP
Example:
.PP
.nf
.br
    QLabel *splashScreen = new QLabel( 0, "mySplashScreen",
.br
                                WStyle_Customize | WStyle_Splash );
.br
.fi
.SH "QWidget::~QWidget ()"
Destroys the widget.
.PP
All this widget's children are deleted first. The application exits if this widget is the main widget.
.SH "bool QWidget::acceptDrops () const"
Returns TRUE if drop events are enabled for this widget; otherwise returns FALSE. See the "acceptDrops" property for details.
.SH "void QWidget::adjustSize ()\fC [virtual slot]\fR"
Adjusts the size of the widget to fit the contents.
.PP
Uses sizeHint() if valid (i.e if the size hint's width and height are >= 0), otherwise sets the size to the children rectangle (the union of all child widget geometries).
.PP
See also sizeHint and childrenRect.
.PP
Example: xform/xform.cpp.
.PP
Reimplemented in QMessageBox.
.SH "bool QWidget::autoMask () const"
Returns TRUE if the auto mask feature is enabled for the widget; otherwise returns FALSE. See the "autoMask" property for details.
.SH "const QBrush & QWidget::backgroundBrush () const"
Returns the widget's background brush. See the "backgroundBrush" property for details.
.SH "const QColor & QWidget::backgroundColor () const"
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code. Use paletteBackgroundColor() or eraseColor() instead.
.SH "BackgroundMode QWidget::backgroundMode () const"
Returns the color role used for painting the background of the widget. See the "backgroundMode" property for details.
.SH "BackgroundOrigin QWidget::backgroundOrigin () const"
Returns the origin of the widget's background. See the "backgroundOrigin" property for details.
.SH "const QPixmap * QWidget::backgroundPixmap () const"
\fBThis function is obsolete.\fR It is provided to keep old source working. We strongly advise against using it in new code. Use paletteBackgroundPixmap() or erasePixmap() instead.
.PP
Examples:
.)l themes/metal.cpp and themes/wood.cpp.
.SH "QSize QWidget::baseSize () const"
Returns the base size of the widget. See the "baseSize" property for details.
.SH "QString QWidget::caption () const"
Returns the window caption (title). See the "caption" property for details.
.SH "QWidget * QWidget::childAt ( int x, int y, bool includeThis = FALSE ) const"
Returns the visible child widget at pixel position \fI(x, y)\fR in the widget's own coordinate system.
.PP
If \fIincludeThis\fR is TRUE, and there is no child visible at \fI(x, y)\fR, the widget itself is returned.
.SH "QWidget * QWidget::childAt ( const QPoint & p, bool includeThis = FALSE ) const"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns the visible child widget at point \fIp\fR in the widget's own coordinate system.
.PP
If \fIincludeThis\fR is TRUE, and there is no child visible at \fIp\fR, the widget itself is returned.
.SH "QRect QWidget::childrenRect () const"
Returns the bounding rectangle of the widget's children. See the "childrenRect" property for details.
.SH "QRegion QWidget::childrenRegion () const"
Returns the combined region occupied by the widget's children. See the "childrenRegion" property for details.
.SH "void QWidget::clearFocus ()\fC [slot]\fR"
Takes keyboard input focus from the widget.
.PP
If the widget has active focus, a focus out event is sent to this widget to tell it that it is about to lose the focus.
.PP
This widget must enable focus setting in order to get the keyboard input focus, i.e. it must call setFocusPolicy().
.PP
See also focus, setFocus(), focusInEvent(), focusOutEvent(), focusPolicy, and QApplication::focusWidget().
.SH "void QWidget::clearMask ()"
Removes any mask set by setMask().
.PP
See also setMask().
.SH "void QWidget::clearWFlags ( WFlags f )\fC [protected]\fR"
Clears the widget flags \fIf\fR.
.PP
Widget flags are a combination of Qt::WidgetFlags.
.PP
See also testWFlags(), getWFlags(), and setWFlags().
.SH "bool QWidget::close ()\fC [slot]\fR"
Closes this widget. Returns TRUE if the widget was closed; otherwise returns FALSE.
.PP
First it sends the widget a QCloseEvent. The widget is hidden if it accepts the close event. The default implementation of QWidget::closeEvent() accepts the close event.
.PP
The QApplication::lastWindowClosed() signal is emitted when the last visible top level widget is closed.
.PP
Examples:
.)l dialog/mainwindow.cpp, mdi/application.cpp, and popup/popup.cpp.
.SH "bool QWidget::close ( bool alsoDelete )\fC [virtual]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Closes this widget. Returns TRUE if the widget was closed; otherwise returns FALSE.
.PP
If \fIalsoDelete\fR is TRUE or the widget has the WDestructiveClose widget flag, the widget is also deleted. The widget can prevent itself from being closed by rejecting the QCloseEvent it gets.
.PP
The QApplication::lastWindowClosed() signal is emitted when the last visible top level widget is closed.
.PP
Note that closing the QApplication::mainWidget() terminates the application.
.PP
See also closeEvent(), QCloseEvent, hide(), QApplication::quit(), QApplication::setMainWidget(), and QApplication::lastWindowClosed().
.SH "void QWidget::closeEvent ( QCloseEvent * e )\fC [virtual protected]\fR"
This event handler, for event \fIe\fR, can be reimplemented in a subclass to receive widget close events.
.PP
The default implementation calls e->accept(), which hides this widget. See the QCloseEvent documentation for more details.
.PP
See also event(), hide(), close(), and QCloseEvent.
.PP
Examples:
.)l action/application.cpp, application/application.cpp, chart/chartform.cpp, i18n/mywidget.cpp, popup/popup.cpp, and qwerty/qwerty.cpp.
.SH "const QColorGroup & QWidget::colorGroup () const"
Returns the current color group of the widget palette. See the "colorGroup" property for details.
.SH "void QWidget::constPolish () const\fC [slot]\fR"
Ensures that the widget is properly initialized by calling polish().
.PP
Call constPolish() from functions like sizeHint() that depends on the widget being initialized, and that may be called before show().
.PP
\fBWarning:\fR Do not call constPolish() on a widget from inside that widget's constructor.
.PP
See also polish().
.SH "void QWidget::contextMenuEvent ( QContextMenuEvent * e )\fC [virtual protected]\fR"
This event handler, for event \fIe\fR, can be reimplemented in a subclass to receive widget context menu events.
.PP
The default implementation calls e->ignore(), which rejects the context event. See the QContextMenuEvent documentation for more details.
.PP
See also event() and QContextMenuEvent.
.PP
Example: menu/menu.cpp.
.SH "void QWidget::create ( WId window = 0, bool initializeWindow = TRUE, bool destroyOldWindow = TRUE )\fC [virtual protected]\fR"
Creates a new widget window if \fIwindow\fR is 0, otherwise sets the widget's window to \fIwindow\fR.
.PP
Initializes the window (sets the geometry etc.) if \fIinitializeWindow\fR is TRUE. If \fIinitializeWindow\fR is FALSE, no initialization is performed. This parameter only makes sense if \fIwindow\fR is a valid window.
.PP
Destroys the old window if \fIdestroyOldWindow\fR is TRUE. If \fIdestroyOldWindow\fR is FALSE, you are responsible for destroying the window yourself (using platform native code).
.PP
The QWidget constructor calls create(0,TRUE,TRUE) to create a window for this widget.
.SH "const QCursor & QWidget::cursor () const"
Returns the cursor shape for this widget. See the "cursor" property for details.
.SH "bool QWidget::customWhatsThis () const\fC [virtual]\fR"
Returns TRUE if the widget wants to handle What's This help manually; otherwise returns FALSE. See the "customWhatsThis" property for details.
.SH "void QWidget::destroy ( bool destroyWindow = TRUE, bool destroySubWindows = TRUE )\fC [virtual protected]\fR"
Frees up window system resources. Destroys the widget window if \fIdestroyWindow\fR is TRUE.
.PP
destroy() calls itself recursively for all the child widgets, passing \fIdestroySubWindows\fR for the \fIdestroyWindow\fR parameter. To have more control over destruction of subwidgets, destroy subwidgets selectively first.
.PP
This function is usually called from the QWidget destructor.
.SH "void QWidget::dragEnterEvent ( QDragEnterEvent * )\fC [virtual protected]\fR"
This event handler is called when a drag is in progress and the mouse enters this widget.
.PP
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
.PP
See also QTextDrag, QImageDrag, and QDragEnterEvent.
.PP
Example: iconview/simple_dd/main.cpp.
.SH "void QWidget::dragLeaveEvent ( QDragLeaveEvent * )\fC [virtual protected]\fR"
This event handler is called when a drag is in progress and the mouse leaves this widget.
.PP
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
.PP
See also QTextDrag, QImageDrag, and QDragLeaveEvent.
.SH "void QWidget::dragMoveEvent ( QDragMoveEvent * )\fC [virtual protected]\fR"
This event handler is called when a drag is in progress and the mouse enters this widget, and whenever it moves within the widget.
.PP
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
.PP
See also QTextDrag, QImageDrag, and QDragMoveEvent.
.SH "void QWidget::drawText ( int x, int y, const QString & str )"
Draws the string \fIstr\fR at position \fI(x, y)\fR.
.PP
The \fIy\fR position is the base line position of the text. The text is drawn using the default font and the default foreground color.
.PP
This function is provided for convenience. You will generally get more flexible results and often higher speed by using a a painter instead.
.PP
See also font, foregroundColor(), and QPainter::drawText().
.SH "void QWidget::drawText ( const QPoint & pos, const QString & str )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Draws the string \fIstr\fR at position \fIpos\fR.
.SH "void QWidget::dropEvent ( QDropEvent * )\fC [virtual protected]\fR"
This event handler is called when the drag is dropped on this widget.
.PP
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
.PP
See also QTextDrag, QImageDrag, and QDropEvent.
.PP
Example: iconview/simple_dd/main.cpp.