qwidget.3qt

Trolltech公司发布的基于C++图形开发环境

.br
.ti -1c
.BI "virtual void \fBshowEvent\fR ( QShowEvent * ) "
.br
.ti -1c
.BI "virtual void \fBhideEvent\fR ( QHideEvent * ) "
.br
.ti -1c
.BI "virtual void \fBcustomEvent\fR ( QCustomEvent * ) "
.br
.ti -1c
.BI "virtual void \fBupdateMask\fR () "
.br
.ti -1c
.BI "virtual void \fBstyleChange\fR ( QStyle & ) "
.br
.ti -1c
.BI "virtual void \fBenabledChange\fR ( bool ) "
.br
.ti -1c
.BI "virtual void \fBbackgroundColorChange\fR ( const QColor & ) "
.br
.ti -1c
.BI "virtual void \fBbackgroundPixmapChange\fR ( const QPixmap & ) "
.br
.ti -1c
.BI "virtual void \fBpaletteChange\fR ( const QPalette & ) "
.br
.ti -1c
.BI "virtual void \fBfontChange\fR ( const QFont & ) "
.br
.ti -1c
.BI "virtual int \fBmetric\fR ( int ) const"
.br
.ti -1c
.BI "virtual void \fBcreate\fR ( WId = 0, bool " "initializeWindow" " = TRUE, bool " "destroyOldWindow" " = TRUE ) "
.br
.ti -1c
.BI "virtual void \fBdestroy\fR ( bool " "destroyWindow" " = TRUE, bool " "destroySubWindows" " = TRUE ) "
.br
.ti -1c
.BI "uint \fBgetWState\fR () const (internal)"
.br
.ti -1c
.BI "virtual void \fBsetWState\fR ( uint ) (internal)"
.br
.ti -1c
.BI "void \fBclearWState\fR ( uint n ) (internal)"
.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 & ) (internal)"
.br
.ti -1c
.BI "virtual void \fBsetCRect\fR ( const QRect & ) (internal)"
.br
.ti -1c
.BI "virtual bool \fBfocusNextPrevChild\fR ( bool next ) "
.br
.ti -1c
.BI "QWExtra* \fBextraData\fR () (internal)"
.br
.ti -1c
.BI "QTLWExtra* \fBtopData\fR () (internal)"
.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
.SS "Properties"
.nf
.TS
l l l l l
- - - - -
l l l l l.
Type	Name	READ	WRITE	Options
bool	isTopLevel	isTopLevel
bool	isModal	isModal
bool	isPopup	isPopup
bool	isDesktop	isDesktop
bool	enabled	isEnabled	setEnabled
QRect	geometry	geometry	setGeometry
QRect	frameGeometry	frameGeometry
int	x	x
int	y	y
QPoint	pos	pos
QSize	frameSize	frameSize
QSize	size	size	resize	DESIGNABLE false
int	width	width
int	height	height
QRect	rect	rect
QRect	childrenRect	childrenRect
QRegion	childrenRegion	childrenRegion
QSizePolicy	sizePolicy	sizePolicy	setSizePolicy
QSize	minimumSize	minimumSize	setMinimumSize
QSize	maximumSize	maximumSize	setMaximumSize
int	minimumWidth	minimumWidth	setMinimumWidth	STORED false
int	minimumHeight	minimumHeight	setMinimumHeight	STORED false
int	maximumWidth	maximumWidth	setMaximumWidth	STORED false
int	maximumHeight	maximumHeight	setMaximumHeight	STORED false
QSize	sizeIncrement	sizeIncrement	setSizeIncrement
QSize	baseSize	baseSize	setBaseSize
BackgroundMode	backgroundMode	backgroundMode	setBackgroundMode	DESIGNABLE false
QColor	backgroundColor	backgroundColor	setBackgroundColor	DESIGNABLE false
QColor	foregroundColor	foregroundColor
QPixmap	backgroundPixmap	backgroundPixmap	setBackgroundPixmap	DESIGNABLE false
QColorGroup	colorGroup	colorGroup
QPalette	palette	palette	setPalette	RESET unsetPalette
bool	ownPalette	ownPalette
QFont	font	font	setFont	RESET unsetFont
bool	ownFont	ownFont
QCursor	cursor	cursor	setCursor	RESET unsetCursor
bool	ownCursor	ownCursor
QString	caption	caption	setCaption
QPixmap	icon	icon	setIcon
QString	iconText	iconText	setIconText
bool	mouseTracking	hasMouseTracking	setMouseTracking
bool	isActiveWindow	isActiveWindow
bool	focusEnabled	isFocusEnabled
FocusPolicy	focusPolicy	focusPolicy	setFocusPolicy
bool	focus	hasFocus
bool	updatesEnabled	isUpdatesEnabled	setUpdatesEnabled	DESIGNABLE false
bool	visible	isVisible
QRect	visibleRect	visibleRect
bool	hidden	isHidden
bool	minimized	isMinimized
QSize	sizeHint	sizeHint
QSize	minimumSizeHint	minimumSizeHint
QRect	microFocusHint	microFocusHint
bool	acceptDrops	acceptDrops	setAcceptDrops
bool	autoMask	autoMask	setAutoMask
BackgroundOrigin	backgroundOrigin	backgroundOrigin	setBackgroundOrigin
bool	customWhatsThis	customWhatsThis
.TE
.fi

.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
.TP
Window functions: show(), hide(), raise(), lower(), close().
.TP
Top level windows: caption(), setCaption(), icon(), setIcon(), iconText(), setIconText(), isActiveWindow(), setActiveWindow(), showMinimized(). showMaximized(), showFullScreen(), showNormal().
.TP
Window contents: update(), repaint(), erase(), scroll(), updateMask().
.TP
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()
.TP
Mode: isVisible(), isVisibleTo(), visibleRect(), isMinimized(), isDesktop(), isEnabled(), isEnabledTo(), isModal(), isPopup(), isTopLevel(), setEnabled(), hasMouseTracking(), setMouseTracking(), isUpdatesEnabled(), setUpdatesEnabled(),
.TP
Look and feel: style(), setStyle(), cursor(), setCursor() font(), setFont(), palette(), setPalette(), backgroundMode(), setBackgroundMode(), backgroundPixmap(), setBackgroundPixmap(), setTranslateBackground(), backgroundColor(), colorGroup(), fontMetrics(), fontInfo().
.TP
Keyboard focus functions: isFocusEnabled(), setFocusPolicy(), focusPolicy(), hasFocus(), setFocus(), clearFocus(), setTabOrder(), setFocusProxy().
.TP
Mouse and keyboard grabbing: grabMouse(), releaseMouse(), grabKeyboard(), releaseKeyboard(), mouseGrabber(), keyboardGrabber().
.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().
.TP
Change handlers: backgroundColorChange(), backgroundPixmapChange(), enabledChange(), fontChange(), paletteChange(), styleChange().
.TP
System functions: parentWidget(), topLevelWidget(), reparent(), polish(), winId(), find(), metric().
.TP
Internal kernel functions: setFRect(), setCRect(), focusNextPrevChild(), wmapper(), clearWFlags(), getWFlags(), setWFlags(), testWFlags().
.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. You can access it using name(). The widget name is little used by programmers but is quite useful with GUI builders such as the Qt Designer (you can name a widget in the builder, and connect() to it by name in your code). The dumpObjectTree() debugging function also uses it.
.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: 
.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().
.TP
resizeEvent() - called when the widget has been resized.
.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().
.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.
.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: 
.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().
.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.
.TP
focusOutEvent() - called when the widget loses keyboard focus.
.PP
Some widgets will need to reimplement some more obscure event handlers, too: 
.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.)
.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().
.TP
wheelEvent() -- called whenever the user turns the mouse wheel while the widget has the focus.
.TP
enterEvent() - called when the mouse enters the widget's screen space. (This excludes screen space owned by any children of the widget.)
.TP
leaveEvent() - called when the mouse leaves the widget's screen space.
.TP
moveEvent() - called when the widget has been moved relative to its parent.
.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 most other events to one of the more specialized handlers above.
.PP
When writing a widget, there are a few more things to look out for. 
.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.
.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.
.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
splitter/splitter.cpp iconview/main.cpp mainlyQt/editor.cpp scrollview/scrollview.cpp i18n/main.cpp drawlines/connect.cpp layout/layout.cpp forever/forever.cpp customlayout/main.cpp progress/progress.cpp qmag/qmag.cpp menu/menu.cpp xform/xform.cpp popup/popup.cpp desktop/desktop.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 paintEvent() is called. To minimize flicker, this should be the most common color or pixmap in the widget. For \fCPaletteBackground,\fR use colorGroup().brush( \fCQColorGroup::Background\fR ), and so on. There are also three special values, listed at the end: 
.TP
\fCPaletteForeground\fR
.TP
\fCPaletteBackground\fR
.TP
\fCPaletteButton\fR
.TP
\fCPaletteLight\fR
.TP
\fCPaletteMidlight\fR
.TP
\fCPaletteDark\fR
.TP
\fCPaletteMid\fR
.TP
\fCPaletteText\fR
.TP
\fCPaletteBrightText\fR
.TP
\fCPaletteButtonText\fR
.TP
\fCPaletteBase\fR
.TP
\fCPaletteShadow\fR
.TP
\fCPaletteHighlight\fR
.TP
\fCPaletteHighlightedText\fR
.TP
\fCNoBackground\fR - the widget is not cleared before paintEvent(). If the widget's paint event always draws on all the pixels, using this mode can be both fast and flicker-free.
.TP
\fCFixedColor\fR - the widget is cleared to a fixed color, normally different from all the ones in the palette(). Set using setBackgroundColor().
.TP
\fCFixedPixmap\fR - the widget is cleared to a fixed pixmap, normally different from all the ones in the palette(). Set using setBackgroundPixmap().
.IP
.PP
\fCFixedColor\fR and \fCFixedPixmap\fR sometimes are just the right thing, but if you use them, make sure that your application looks right when the desktop color scheme has been changed. (On X11, a quick way to test is e.g. "./yourapp -bg paleblue". On Windows, you have to use the control panel.)
.PP
See also setBackgroundMode(), backgroundMode(), setBackgroundPixmap() and setBackgroundColor().
.SH "QWidget::BackgroundOrigin"
This enum defines the origin used to draw a widget's background pixmap.
.TP
\fCWidgetOrigin\fR - the pixmap is drawn in the widget's coordinate system.
.TP
\fCParentOrigin\fR - the pixmap is drawn in the parent's coordinate system.
.SH "QWidget::FocusPolicy"
This enum type defines the various policies a widget can have with respect to acquiring keyboard focus.
.PP
The \fIpolicy\fR can be:
.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.
.SH "QWidget::PropagationMode"
\fBThis member is obsolete.\fR It is provided to keep old source working, and will probably be removed in a future version of Qt. We strongly advise against using it in new code.
.PP