qwidget.3qt

tmark1.11:用于生成QT/EMBEDDED应用工程的Markfile文件

.br
.ti -1c
.BI "WFlags \fBgetWFlags\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetWFlags\fR ( WFlags )"
.br
.ti -1c
.BI "void \fBclearWFlags\fR ( WFlags n )"
.br
.ti -1c
.BI "virtual void \fBsetFRect\fR ( const QRect & )"
.br
.ti -1c
.BI "virtual void \fBsetCRect\fR ( const QRect & )"
.br
.ti -1c
.BI "virtual bool \fBfocusNextPrevChild\fR ( bool next )"
.br
.ti -1c
.BI "QWExtra* \fBextraData\fR ()"
.br
.ti -1c
.BI "QFocusData* \fBfocusData\fR ()"
.br
.ti -1c
.BI "virtual void \fBsetKeyCompression\fR ( bool )"
.br
.ti -1c
.BI "virtual void \fBsetMicroFocusHint\fR ( int " "x" ", int " "y" ", int " "w" ", int " "h" ", bool " "text" "=TRUE )"
.br
.in -1c
.SH DESCRIPTION
The QWidget class is the base class of all user interface objects.
.PP
The widget is the atom of the user interface: It receives mouse, keyboard and other events from the window system, and paints a representation of itself on the screen. Every widget is rectangular, and they are sorted in a Z-order. A widget is clipped by its parent and by the widgets in front of it.
.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 (though it is also possible to create top level widgets without such decoration by the use of widget flags). 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
The opposite of top-level widgets are child widgets. Those are child windows in their parent widgets. You usually cannot distinguish a child widget from its parent visually. Most other widgets in Qt are useful only as child widgets. (You \fIcan\fR make a e.g. button into a top-level widget, but most people prefer to put their buttons in e.g. dialogs.)
.PP
QWidget has many member functions, but some of them have little direct functionality - for example it has a font but never uses it itself. There are many subclasses which provide real functionality, as diverse as QPushButton, QListBox and QTabDialog.
.PP
\fBGroups of functions:\fR
.IP
.TP
Window functions: show(), hide(), raise(), lower(), close().
.IP
.TP
Top level windows: caption(), setCaption(), icon(), setIcon(), iconText(), setIconText(), isActiveWindow(), setActiveWindow(), showMinimized().
.IP
.TP
Window contents: update(), repaint(), erase(), scroll(), updateMask().
.IP
.TP
Geometry: pos(), size(), rect(), x(), y(), width(), height(), sizePolicy(), sizeHint(), updateGeometry(), layout(), move(), resize(), setGeometry(), frameGeometry(), geometry(), childrenRect(), adjustSize(), mapFromGlobal(), mapFromParent() mapToGlobal(), mapToParent(), maximumSize(), minimumSize(), sizeIncrement(), setMaximumSize(), setMinimumSize(), setSizeIncrement(), setBaseSize(), setFixedSize()
.IP
.TP
Mode: isVisible(), isVisibleTo(), isVisibleToTLW(), visibleRect(), isMinimized(), isDesktop(), isEnabled(), isEnabledTo(), isEnabledToTLW(), isModal(), isPopup(), isTopLevel(), setEnabled(), hasMouseTracking(), setMouseTracking(), isUpdatesEnabled(), setUpdatesEnabled(), setFontPropagation(), fontPropagation(), setPalettePropagation(), palettePropagation().
.IP
.TP
Look and feel: style(), setStyle(), cursor(), setCursor() font(), setFont(), palette(), setPalette(), backgroundMode(), setBackgroundMode(), backgroundPixmap(), setBackgroundPixmap(), backgroundColor(), colorGroup(), fontMetrics(), fontInfo().
.IP
.TP
Keyboard focus functions: isFocusEnabled(), setFocusPolicy(), focusPolicy(), hasFocus(), setFocus(), clearFocus(), setTabOrder(), setFocusProxy().
.IP
.TP
Mouse and keyboard grabbing: grabMouse(), releaseMouse(), grabKeyboard(), releaseKeyboard(), mouseGrabber(), keyboardGrabber().
.IP
.TP
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().
.IP
.TP
Change handlers: backgroundColorChange(), backgroundPixmapChange(), enabledChange(), fontChange(), paletteChange(), styleChange().
.IP
.TP
System functions: parentWidget(), topLevelWidget(), reparentolish((), winId(), find(), metric().
.IP
.TP
Internal kernel functions: setFRect(), setCRect(), focusNextPrevChild(), wmapper(), clearWFlags(), getWFlags(), setWFlags(), testWFlags().
.IP
.TP
What's this help: customWhatsThis()
.PP
Every widget's constructor accepts two or three standard arguments:
.TP
\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's\fR geometry (Unless you specify \fCWType_TopLevel\fR as widget flag).
.TP
\fCconst char * name = 0\fR is the widget name of the new widget. The widget name is little used at the moment - the dumpObjectTree() debugging function uses it, and you can access it using name(). It will become more important when our visual GUI builder is ready (you can name a a widget in the builder, and connect() to it by name in your code).
.TP
\fCWFlags f = 0\fR (where available) sets the widget flags; the default is good for almost all widgets, but to get e.g. top-level widgets 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 peculiar to it (as all useful widgets must), 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 sensible to \fInever\fR 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, mouse press and mouse release events are by far the most important. A widget receives mouse press events when the widget 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, however: If a popup menu appears while the mouse button is held down, that popup steals the mouse events at once.
.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 he/she does not 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.)
.PP
If your widget only contains child widgets, you probably do not need to implement any event handlers.
.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 override QWidget::event().
.IP
.TP
focusInEvent() - called when the widget gains keyboard focus (assuming you have called setFocusPolicy(), of course). 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.
.PP
Some widgets will need to reimplement some more obscure event handlers, too: 
.IP
.TP
mouseMoveEvent() - called whenever the mouse moves while a button is held down. This is useful for e.g. 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.)
.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 override 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).
.PP
There are also some \fIreally\fR 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 every other event to one of the more specialized handlers above.
.PP
When writing a widget, there are a few more things to look out for. 
.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 sizePolicy or at least sizeHint(), so users of your class can set up layout management more easily.
.IP
sizePolicy() lets you supply good defaults for the layout management handling, so that other widgets can contain 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 and QBoxLayout.
.PP
Examples:
.(l
tabdialog/tabdialog.cpp drawlines/connect.cpp mainlyQt/editor.cpp xform/xform.cpp qiconview/main.cpp layout/layout.cpp popup/popup.cpp menu/menu.cpp progress/progress.cpp qmag/qmag.cpp splitter/splitter.cpp forever/forever.cpp desktop/desktop.cpp scrollview/scrollview.cpp customlayout/main.cpp
.)l
.SS "Member Type Documentation"
.SH "QWidget::BackgroundMode"
This enum describes how the background of a widget changes, as the widget's palette changes.
.PP
The background is what the widget contains when <a href="qwidget.html#ef2069">paintEvent() is called. To minimize flicker, this should be the most common color in the widget.
.PP
The following values are valid: 
.IP
.TP
\fCPaletteForeground\fR - use palette() . fillForeground()
.TP
\fCPaletteBackground\fR - use palette() . fillBackground()
.TP
\fCPaletteButton\fR - use palette() . fillButton()
.TP
\fCPaletteLight\fR - use palette() . fillLight()
.TP
\fCPaletteMidlight\fR - use palette() . fillMidlight()
.TP
\fCPaletteDark\fR - use palette() . fillDark()
.TP
\fCPaletteMid\fR - use palette() . fillMid()
.TP
\fCPaletteText\fR - use palette() . fillText()
.TP
\fCPaletteBrightText\fR - use palette() . fillBrightText()
.TP
\fCPaletteButtonText\fR - use palette() . fillButtonText()
.TP
\fCPaletteBase\fR - use palette() . fillBase()
.TP
\fCPaletteShadow\fR - use palette() . fillShadow()
.TP
\fCPaletteHighlight\fR - use palette() . fillHighlight()
.TP
\fCPaletteHighlightedText\fR - use palette() . fillHighlightedText()
.TP
\fCNoBackground\fR - no color or pixmap is used - the paintEvent() must completely cover the drawing area. This can help avoid flicker.
.PP
See also: setBackgroundMode() and backgroundMode().
.SH "QWidget::PropagationMode"
This enum determines how fonts and palette changes are propagated to children of a widget.
.PP
If a widget's propagation mode is \fCNoChildren,\fR changes to that widget's font or palette do not affect the widget's children. IF it is \fCAllChildren,\fR all children are affected. If it is \fCSameFont\fR or \fCSamePalette\fR (mostly the default mode) then changes affect those child widget for which no separate font/palette has been set, but no other children.
.PP
See also: <a href="qwidget.html#26de4b">setFont() and setPalette().
.SH MEMBER FUNCTION DOCUMENTATION
.SH "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 Unless the newly created widget is reparented, it will be deleted when the parent 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 zero). To customize the frame, set the \fCWStyle_Customize\fR flag OR'ed with any of these flags:
.TP
\fCWStyle_NormalBorder\fR gives the window a normal border. Cannot be combined with \fCWStyle_DialogBorder\fR or \fCWStyle_NoBorder.\fR
.TP
\fCWStyle_DialogBorder\fR gives the window a thin dialog border. Cannot be combined with \fCWStyle_NormalBorder\fR or \fCWStyle_NoBorder.\fR
.TP
\fCWStyle_NoBorder\fR gives a borderless window. Note that the user cannot move or resize a borderless window via the window system. Cannot be combined with \fCWStyle_NormalBorder\fR or \fCWStyle_DialogBorder.\fR
.TP
\fCWStyle_Title\fR gives the window a title bar.
.TP
\fCWStyle_SysMenu\fR adds a window system menu.
.TP
\fCWStyle_Minimize\fR adds a minimize button.
.TP
\fCWStyle_Maximize\fR adds a maximize button.
.TP
\fCWStyle_MinMax\fR is equal to \fC(WStyle_Minimize | WStyle_Maximize) \fR.
.TP
\fCWStyle_Tool\fR makes the window a tool window. A tool window is a small window that lives for a short time and it is typically used for creating popup windows. It there is a parent, the tool window will be kept on top of it. If there isn't a parent, you may consider passing WStyle_StaysOnTop as well. If the window system supports it, a tool window will be decorated with a somewhat lighter frame. It can, however, be combined with \fCWStyle_NoBorder\fR as well.
.TP
\fCWStyle_StaysOnTop\fR informs the window system that the window should stay on top of all windows.
.TP
\fCWStyle_Dialog\fR indicates, that the window is a logical subwindow of its parent, in other words: a dialog. The window will not get its own taskbar entry and be kept on top of its parent by the window system. Usually, it will also be minimized when the parent is minized. If not customized, the window is decorated slightly less. WStyle_Dialog is implied by WType_Modal. It is implicitely defined when using the class QDialog.
.PP
Note that X11 does not necessarily support all style flag combinations. X11 window managers live their own lives and can only take hints. Win32 supports all style flags.
.PP
Example:
.PP
.nf
.br
    QLabel *toolTip = new QLabel( 0, "myToolTip",
.br
                                  WStyle_Customize | WStyle_NoBorder |
.br
                                  WStyle_Tool );
.fi
.PP
The widget flags are defined in qwindowdefs.h (which is included by qwidget.h).
.SH "QWidget::~QWidget ()"
Destroys the widget.
.PP
All children of this widget are deleted first. The application exits if this widget is (was) the main widget.
.SH "bool QWidget::acceptDrops () const"
Returns TRUE if drop events are enabled for this widget.
.PP
See also: setAcceptDrops().
.SH "void QWidget::adjustSize () \fC[virtual]\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 equal to or greater than 0), otherwise sets the size to the children rectangle (the union of all child widget geometries).
.PP
See also: sizeHint() and childrenRect().
.PP
Examples:
.(l
movies/main.cpp
.)l
.PP
Reimplemented in QMessageBox.
.SH "bool QWidget::autoMask () const"
Returns whether or not a widget has the auto mask feature enabled.
.PP
See also: setAutoMask(), updateMask(), setMask() and clearMask().
.SH "const QColor & QWidget::backgroundColor () const"
Returns the background color of this widget.
.PP
The background color is independent of the color group.
.PP
Setting a new palette overwrites the background color.
.PP
See also: setBackgroundColor(), foregroundColor(), colorGroup() and palette().
.PP
Examples:
.(l
grapher/grapher.cpp xform/xform.cpp
.)l
.SH "void QWidget::backgroundColorChange ( const QColor & oldBackgroundColor ) \fC[virtual protected]\fR"
This virtual function is called from setBackgroundColor(). \fIoldBackgroundColor\fR is the previous background color; you can get the new background color from backgroundColor().
.PP
Reimplement this function if your widget needs to know when its background color changes. You will almost certainly need to update the widget using either repaint(TRUE) or update().
.PP
The default implementation calls update()
.PP
See also: setBackgroundColor(), backgroundColor(), setPalette(), repaint() and update().
.SH "QWidget::BackgroundMode QWidget::backgroundMode() const"
Returns the mode most recently set by setBackgroundMode(). The default is PaletteBackground
.SH "const QPixmap * QWidget::backgroundPixmap () const"
Returns the background pixmap, or null if no background pixmap has not been set. If the widget has been made empty, this function will return a pixmap which isNull() rather than a null pointer.
.PP
See also: setBackgroundPixmap() and setBackgroundMode().
.SH "void QWidget::backgroundPixmapChange ( const QPixmap & oldBackgroundPixmap ) \fC[virtual protected]\fR"
This virtual function is called from setBackgroundPixmap(). \fIoldBackgroundPixmap\fR is the previous background pixmap; you can get the new background pixmap from backgroundPixmap().
.PP
Reimplement this function if your widget needs to know when its background pixmap changes. You will almost certainly need to update the widget using either repaint(TRUE) or update().
.PP