Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference
Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference |
|
The QWidget class is the base class of all user interface objects. More...
#include <qwidget.h>
Inherits QObject and QPaintDevice.
Inherited by QDialog, QFrame, QMainWindow, QComboBox, QLineEdit, QButton, ControlWidgetBase, QSlider, QToolBar, DocPropertiesWidget, QTabWidget, QTabBar, QDial, QHeader, QSemiModal, QScrollBar, QSizeGrip, and QStatusBar.
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.
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.
A widget without a parent widget is always a top-level widget.
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 can make a e.g. button into a top-level widget, but most people prefer to put their buttons in e.g. dialogs.)
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.
Groups of functions:
Every widget's constructor accepts two or three standard arguments:
QWidget *parent = 0 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 parent, and be constrained by parent's geometry (Unless you specify WType_TopLevel as
widget flag).
const char *name = 0 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.
WFlags f = 0 (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.
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.
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:
If your widget only contains child widgets, you probably do not need to implement any event handlers.
Widgets that accept keyboard input need to reimplement a few more event handlers:
Some widgets will need to reimplement some more obscure event handlers, too:
There are also some really 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.
When writing a widget, there are a few more things to look out for.
See also QEvent, QPainter, QGridLayout, and QBoxLayout.
This enum describes how the background of a widget changes, as the widget's palette changes.
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 PaletteBackground, use colorGroup().brush( QColorGroup::Background ), and so on. There are also three special values, listed at the end:
FixedColor and FixedPixmap 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.)
See also setBackgroundMode(), backgroundMode(), setBackgroundPixmap(), and setBackgroundColor().
This enum defines the origin used to draw a widget's background pixmap.
This enum type defines the various policies a widget can have with respect to acquiring keyboard focus.
The policy can be:
This type is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
This enum used to determine how fonts and palette changes are propagated to children of a widget.
If parent is 0, the new widget becomes a top-level window. If parent is another widget, this widget becomes a child window inside parent. The new widget is deleted when parent is.
The name is sent to the QObject constructor.
The widget flags argument f is normally 0, but it can be set to customize the window frame of a top-level widget (i.e. parent must be zero). To customize the frame, set the WStyle_Customize flag OR'ed with any of the Qt::WidgetFlags.
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.
Example:
QLabel *spashScreen = new QLabel( 0, "mySplashScreen",
WStyle_Customize | WStyle_NoBorder |
WStyle_Tool );
All children of this widget are deleted first. The application exits if this widget is (was) the main widget.
See also setAcceptDrops().
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).
See also sizeHint() and childrenRect().
Reimplemented in QMessageBox.
See also setAutoMask(), updateMask(), setMask(), and clearMask().
Returns the background color of this widget, which is normally set implicitly by setBackgroundMode(), but can also be set explicitly by setBackgroundColor().
If there is a background pixmap (set using setBackgroundPixmap()), then the return value of this function is indeterminate.
See also setBackgroundColor(), foregroundColor(), colorGroup(), and palette().
This virtual function is called from setBackgroundColor(). oldBackgroundColor is the previous background color; you can get the new background color from backgroundColor().
Reimplement this function if your widget needs to know when its background color changes. You will almost certainly need to call this implementation of the function.
See also setBackgroundColor(), backgroundColor(), setPalette(), repaint(), and update().
See also BackgroundMode and setBackgroundMode().
See also setBackgroundOrigin().
See also setBackgroundPixmap() and setBackgroundMode().
This virtual function is called from setBackgroundPixmap(). oldBackgroundPixmap is the previous background pixmap; you can get the new background pixmap from backgroundPixmap().
Reimplement this function if your widget needs to know when its background pixmap changes. You will almost certainly need to call this implementation of the function.
See also setBackgroundPixmap(), backgroundPixmap(), repaint(), and update().
The base size is used to calculate a proper widget size in case the widget defines sizeIncrement().
See also setBaseSize() and setSizeIncrement().
See also setCaption(), icon(), iconText(), and QString::isNull().
Explicitely hidden children are excluded.
See also childrenRegion().
Explicitely hidden children are excluded.
See also childrenRect().
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.
This widget must enable focus setting in order to get the keyboard input focus, i.e. it must call setFocusPolicy().
See also hasFocus(), setFocus(), focusInEvent(), focusOutEvent(), setFocusPolicy(), and QApplication::focusWidget().
See also setMask().
Clears the widget flags f.
Widget flags are a combination of Qt::WidgetFlags.
See also testWFlags(), getWFlags(), and setWFlags().
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.
The QApplication::lastWindowClosed() signal is emitted when the last visible top level widget is closed.
See also close(bool).
If alsoDelete 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.
The QApplication::lastWindowClosed() signal is emitted when the last visible top level widget is closed.
Note that closing the QApplication::mainWidget() terminates the application.
See also closeEvent(), QCloseEvent, hide(), QApplication::quit(), QApplication::setMainWidget(), and QApplication::lastWindowClosed().
The default implementation calls e->accept(), which hides this widget. See the QCloseEvent documentation for more details.
See also event(), hide(), close(), and QCloseEvent.
The color group is determined by the state of the widget.
A disabled widget returns the QPalette::disabled() color group, a widget in the window with keyboard focus returns the QPalette::active() color group, and all inactive widgets return the QPalette::inactive() color group.
See also palette() and setPalette().
Ensures that the widget is properly initialized by calling polish().
Call constPolish() from functions like sizeHint() that depends on the widget being initialized, and that may be called before show().
Warning: Do not call constPolish() on a widget from inside that widget's constructor.
See also polish().
Initializes the window (sets the geometry etc.) if initializeWindow is TRUE. If initializeWindow is FALSE, no initialization is performed. This parameter makes only sense if window is a valid window.
Destroys the old window if destroyOldWindow is TRUE. If destroyOldWindow is FALSE, you are responsible for destroying the window yourself (using platform native code).
The QWidget constructor calls create(0,TRUE,TRUE) to create a window for this widget.
See also setCursor() and unsetCursor().
See also event() and QCustomEvent.
The widget may leave Whats This mode by calling QWhatsThis::leaveWhatsThisMode(), with or without actually displaying any help text.
You may also reimplement customWhatsThis() if your widget is a so-called "passive interactor" that is supposed to work under all circumstances. Simply don't call QWhatsThis::leaveWhatsThisMode() in that case.
See also QWhatsThis::inWhatsThisMode() and QWhatsThis::leaveWhatsThisMode().
destroy() calls itself recursively for all the child widgets, passing destroySubWindows for the destroyWindow parameter. To have more control over destruction of subwidgets, destroy subwidgets selectively first.
This function is usually called from the QWidget destructor.
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
See also QTextDrag, QImageDrag, and QDragEnterEvent.
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
See also QTextDrag, QImageDrag, and QDragLeaveEvent.
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
See also QTextDrag, QImageDrag, and QDragMoveEvent.
The y position is the base line position of the text. The text is drawn using the default font and the default foreground color.
This function is provided for convenience. You will generally get more flexible results and often higher speed by using a a painter instead.
See also setFont(), foregroundColor(), and QPainter::drawText().
See the Drag-and-drop documentation for an overview of how to provide drag-and-drop in your application.
See also QTextDrag, QImageDrag, and QDropEvent.
This virtual function is called from setEnabled(). oldEnabled is the previous setting; you can get the new setting from isEnabled().
Reimplement this function if your widget needs to know when it becomes enabled or disabled. You will almost certainly need to update the widget using update().
The default implementation repaints the visible part of the widget.
See also setEnabled(), isEnabled(), repaint(), update(), and visibleRect().
An event is sent to the widget when the mouse cursor enters the widget.
See also leaveEvent(), mouseMoveEvent(), and event().
If w is negative, it is replaced with width() - x.
If h is negative, it is replaced width height() - y.
Child widgets are not affected.
See also repaint().
This version erases the entire widget.
Child widgets are not affected.
The main event handler first passes an event through all event filters that have been installed. If none of the filters intercept the event, it calls one of the specialized event handlers.
Key press/release events are treated differently from other events. event() checks for Tab and shift-Tab and tries to move the focus appropriately. If there is no widget to move the focus to (or the key press is not Tab or shift-Tab), event() calls keyPressEvent().
This function returns TRUE if it is able to pass the event over to someone, or FALSE if nobody wanted the event.
See also closeEvent(), focusInEvent(), focusOutEvent(), enterEvent(), keyPressEvent(), keyReleaseEvent(), leaveEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), mousePressEvent(), mouseReleaseEvent(), moveEvent(), paintEvent(), resizeEvent(), QObject::event(), and QObject::timerEvent().
Reimplemented from QObject.
The window identifier type depends by the underlying window system, see qwindowdefs.h for the actual definition. If there is no widget with this identifier, a null pointer is returned.
See also wmapper() and winId().
Focus data always belongs to the top-level widget. The focus data list contains all the widgets in this top-level widget that can accept focus, in tab order. An iterator points to the current focus widget (focusWidget() returns a pointer to this widget).
This information is useful for implementing advanced versions of focusNextPrevChild().
A widget normally must setFocusPolicy() to something other than NoFocus in order to receive focus events. (Note that the application programmer can call setFocus() on any widget, even those that do not normally accept focus.)
The default implementation updates the widget if it accepts focus (see focusPolicy()). It also calls setMicroFocusHint(), hinting any system-specific input tools about the focus of the user's attention.
See also focusOutEvent(), setFocusPolicy(), keyPressEvent(), keyReleaseEvent(), event(), and QFocusEvent.
Reimplemented in QMultiLineEdit.
If next is true, this function searches "forwards", if next is FALSE, "backwards".
Sometimes, you will want to reimplement this function. For example, a web browser might reimplement it to move its "current active link" forwards or backwards, and call QWidget::focusNextPrevChild() only when it reaches the last/first.
Child widgets call focusNextPrevChild() on their parent widgets, and only the top-level widget will thus make the choice of where to redirect focus. By overriding this method for an object, you thus gain control of focus traversal for all child widgets.
See also focusData().
A widget normally must setFocusPolicy() to something other than NoFocus in order to receive focus events. (Note that the application programmer can call setFocus() on any widget, even those that do not normally accept focus.)
The default implementation calls repaint() since the widget's colorGroup() changes from active to normal, so the widget probably needs repainting. It also calls setMicroFocusHint(), hinting any system-specific input tools about the focus of the user's attention.
See also focusInEvent(), setFocusPolicy(), keyPressEvent(), keyReleaseEvent(), event(), and QFocusEvent.
Returns QWidget::TabFocus if the widget accepts focus by tabbing, QWidget::ClickFocus if the widget accepts focus by clicking, QWidget::StrongFocus if it accepts both and QWidget::NoFocus if it does not accept focus at all.
See also isFocusEnabled(), setFocusPolicy(), focusInEvent(), focusOutEvent(), keyPressEvent(), keyReleaseEvent(), and isEnabled().
See also setFocusProxy().
Returns the font currently set for the widget.
fontInfo() tells you what font is actually being used.
As long as no special font has been set, this is either a special font for the widget class, the parent's font or - if this widget is a toplevel widget - the default application font.
See also setFont(), fontInfo(), fontMetrics(), and QApplication::font().
This virtual function is called from setFont(). oldFont is the previous font; you can get the new font from font().
Reimplement this function if your widget needs to know when its font changes. You will almost certainly need to update the widget using update().
The default implementation updates the widget including its geometry.
See also setFont(), font(), update(), and updateGeometry().
Returns the font info for the widget's current font. Equivalent to QFontInto(widget->font()).
See also font(), fontMetrics(), and setFont().
Returns the font metrics for the widget's current font. Equivalent to QFontMetrics(widget->font()).
See also font(), fontInfo(), and setFont().
The return value is meaningless
See also setFontPropagation().
The foreground color is also accessible as colorGroup().foreground().
See also backgroundColor() and colorGroup().
See the Window Geometry documentation for an overview of geometry issues with top-level widgets.
See also geometry(), x(), y(), and pos().
See the Window Geometry documentation for an overview of geometry issues with top-level widgets.
See also frameGeometry(), size(), and rect().
Returns the widget flags for this this widget.
Widget flags are a combination of Qt::WidgetFlags.
See also testWFlags(), setWFlags(), and clearWFlags().
This widget will receive all keyboard events, independent of the active window.
Warning: Grabbing the keyboard might lock the terminal.
See also releaseKeyboard(), grabMouse(), and releaseMouse().
This widget will be the only one to receive mouse events until releaseMouse() is called.
Warning: Grabbing the mouse might lock the terminal.
It is almost never necessary to grab the mouse when using Qt since Qt grabs and releases it sensibly. In particular, Qt grabs the mouse when a button is pressed and keeps it until the last button is released.
Beware that only widgets actually shown on the screen may grab the mouse input.
See also releaseMouse(), grabKeyboard(), and releaseKeyboard().
The cursor will assume shape cursor (for as long as the mouse focus is grabbed) and this widget will be the only one to receive mouse events until releaseMouse() is called().
Warning: Grabbing the mouse might lock the terminal.
See also releaseMouse(), grabKeyboard(), releaseKeyboard(), and setCursor().
Equivalent to qApp->focusWidget() == this.
See also setFocus(), clearFocus(), setFocusPolicy(), and QApplication::focusWidget().
Returns TRUE if mouse tracking is enabled for this widget, or FALSE if mouse tracking is disabled.
See also setMouseTracking().
See the Window Geometry documentation for an overview of geometry issues with top-level widgets.
See also geometry(), width(), and size().
Warning: Does not look at the widget's layout
Reimplemented in QTextView and QMenuBar.
You almost never have to reimplement this function. If you need to do something after a widget is hidden, use hideEvent() instead.
See also isHhideEvent(), isHidden(), show(), showMinimized(), isVisible(), and close().
Reimplemented in QMenuBar.
Hide events are sent to widgets right after they have been hidden.
See also event() and QHideEvent.
See also setIcon(), iconText(), and caption().
See also setIconText(), icon(), caption(), and QString::isNull().
When popup windows are visible, this function returns TRUE for both the active window and the popup.
See also setActiveWindow() and QApplication::activeWindow().
A desktop widget is also a top-level widget.
See also isTopLevel() and QApplication::desktop().
See also setEnabled().
This is the case if neither the widget itself nor every parent up to but excluding ancestor has been explicitly disabled.
isEnabledTo(0) is equivalent to isEnabled().
See also setEnabled() and isEnabled().
This function is deprecated. It is equivalent to isEnabled()
See also setEnabled() and isEnabled().
Returns TRUE if the widget accepts keyboard focus, or FALSE if it does not.
Keyboard focus is initially disabled (i.e. focusPolicy() == QWidget::NoFocus).
You must enable keyboard focus for a widget if it processes keyboard events. This is normally done from the widget's constructor. For instance, the QLineEdit constructor calls setFocusPolicy(QWidget::StrongFocus).
See also setFocusPolicy(), focusInEvent(), focusOutEvent(), keyPressEvent(), keyReleaseEvent(), and isEnabled().
Returns TRUE if the widget is explicitly hidden, or FALSE if it is visible or would become visible if all its ancestors became visible.
See also hide(), show(), isVisible(), and isVisibleTo().
Returns TRUE if this widget is a top-level widget that is maximized, or else FALSE.
Note that due to limitations in some window-systems, this does not always report expected results (eg. if the user on X11 maximizes the window via the window manager, Qt has no way of telling this from any other resize). This will improve as window manager protocols advance.
See also showMaximized().
See also showMinimized(), isVisible(), show(), hide(), and showNormal().
A modal widget is also a top-level widget.
See also isTopLevel() and QDialog.
A popup widget is created by specifying the widget flag WType_Popup to the widget constructor.
A popup widget is also a top-level widget.
See also isTopLevel().
A top-level widget is a widget which usually has a frame and a caption (title bar). Popup and desktop widgets are also top-level widgets.
A top-level widgets can have a parent widget. It will then be grouped with its parent: deleted when the parent is deleted, minimized when the parent is minimized etc. If supported by the window manager, it will also have a common taskbar entry with its parent.
QDialog and QMainWindow widgets are by default top-level, even if a parent widget is specified in the constructor. This behavior is specified by the WType_TopLevel widget flag.
Child widgets are the opposite of top-level widgets.
See also topLevelWidget(), isModal(), isPopup(), isDesktop(), and parentWidget().
See also setUpdatesEnabled().
Returns TRUE if the widget itself is visible, or else FALSE.
Calling show() sets the widget to visible status if all its parent widgets up to the toplevel widget are visible. If an ancestor is not visible, the widget won't become visible until all its ancestors are shown.
Calling hide() hides a widget explicitly. An explicitly hidden widget will never become visible, even if all its ancestors become visible.
Iconified top-level widgets also have hidden status, as well as having isMinimized() return TRUE. Windows that live on another virtual desktop (on platforms that support this concept) also have hidden status.
This function returns TRUE if the widget currently is obscured by other windows on the screen, but would be visible if moved.
A widget receives show- and hide events when its visibility status changes. Between a hide and a show event, there is no need in wasting any CPU on preparing or displaying information to the user. A video application, for example, might simply stop generating new frames.
See also show(), hide(), isHidden(), isVisibleTo(), isMinimized(), showEvent(), and hideEvent().
This is the case if neither the widget itself nor every parent up to but excluding ancestor has been explicitly hidden.
This function returns TRUE if the widget it is obscured by other windows on the screen, but would be visible if moved.
isVisibleTo(0) is very similar to isVisible(), with the exception that it does not cover the iconfied-case or the situation where the window lives on another virtual desktop.
See also show(), hide(), and isVisible().
This function is deprecated. It is equivalent to isVisible()
See also show(), hide(), and isVisible().
A widget must call setFocusPolicy() to accept focus initially and have focus in order to receive a key press event.
If you reimplement this handler, it is very important that you ignore() the event if you do not understand it, so that the widget's parent can interpret it.
The default implementation closes popup widgets if you hit escape. Otherwise the event is ignored.
See also keyReleaseEvent(), QKeyEvent::ignore(), setFocusPolicy(), focusInEvent(), focusOutEvent(), event(), and QKeyEvent.
Reimplemented in QLineEdit, QTextView, and QMultiLineEdit.
A widget must accept focus initially and have focus in order to receive a key release event.
If you reimplement this handler, it is very important that you ignore() the release if you do not understand it, so that the widget's parent can interpret it.
The default implementation ignores the event.
See also keyPressEvent(), QKeyEvent::ignore(), setFocusPolicy(), focusInEvent(), focusOutEvent(), event(), and QKeyEvent.
If no widget in this application is currently grabbing the keyboard, 0 is returned.
See also grabMouse() and mouseGrabber().
Returns a pointer to the layout engine that manages the geometry of this widget's children.
If the widget does not have a layout, layout() returns a null pointer.
See also sizePolicy().
A leave event is sent to the widget when the mouse cursor leaves the widget.
See also enterEvent(), mouseMoveEvent(), and event().
If there are siblings of this widget that overlap it on the screen, this widget will be obscured by its siblings afterwards.
See also raise() and stackUnder().
See also mapTo(), mapFromParent(), and mapFromGlobal().
See also mapToGlobal(), mapFrom(), and mapFromParent().
Same as mapFromGlobal() if the widget has no parent.
See also mapToParent(), mapFrom(), and mapFromGlobal().
See also mapFrom(), mapToParent(), and mapToGlobal().
mapToGlobal(QPoint(0,0))would give the global coordinates of the top-left pixel of the widget.
See also mapFromGlobal(), mapTo(), and mapToParent().
Same as mapToGlobal() if the widget has no parent.
See also mapFromParent(), mapTo(), and mapToGlobal().
Returns the widget's maximum height.
See also maximumSize() and maximumWidth().
The widget cannot be resized to a larger size than the maximum widget size.
See also maximumWidth(), maximumHeight(), setMaximumSize(), minimumSize(), and sizeIncrement().
Returns the widget's maximum width.
See also maximumSize() and maximumHeight().
Use the QPaintDeviceMetrics class instead.
Reimplemented from QPaintDevice.
See also setMicroFocusHint().
Returns the widget's minimum height.
See also minimumSize() and minimumWidth().
The widget cannot be resized to a smaller size than the minimum widget size.
If the returned minimum size equals (0,0) then it means that there are no constraints on the minimum size. However, Qt does nevertheless not allow you to shrink widgets to less than 1 pixel width/height.
See also maximumWidth(), maximumHeight(), setMinimumSize(), maximumSize(), and sizeIncrement().
The default implementation returns an invalid size if there is no layout for this widget, the layout's minimum size otherwise.
See also QSize::isValid(), resize(), setMinimumSize(), and sizePolicy().
Reimplemented in QLineEdit, QMultiLineEdit, and QTabWidget.
Returns the widget's minimum width.
See also minimumSize() and minimumHeight().
The default implementation generates a normal mouse press event.
Note that the widgets gets a mousePressEvent() and a mouseReleaseEvent() before the mouseDoubleClickEvent().
See also mousePressEvent(), mouseReleaseEvent(), mouseMoveEvent(), event(), and QMouseEvent.
If no widget in this application is currently grabbing the mouse, 0 is returned.
See also grabMouse() and keyboardGrabber().
If mouse tracking is switched off, mouse move events only occur if a mouse button is down while the mouse is being moved. If mouse tracking is switched on, mouse move events occur even if no mouse button is down.
QMouseEvent::pos() reports the position of the mouse cursor, relative to this widget. For press and release events, the position is usually the same as the position of the last mouse move event, but it might be different if the user moves and clicks the mouse fast. This is a feature of the underlying window system, not Qt.
See also setMouseTracking(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), event(), and QMouseEvent.
Reimplemented in QSizeGrip.
If you create new widgets in the mousePressEvent() the mouseReleaseEvent() may not end up where you expect, depending on the underlying window system (or X11 window manager), the widgets' location and maybe more.
The default implementation implements the closing of popup widgets when you click outside the window. For other widget types it does nothing.
See also mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), event(), and QMouseEvent.
Reimplemented in QSizeGrip.
See also mouseDoubleClickEvent(), mouseMoveEvent(), event(), and QMouseEvent.
If the widget is visible, it receives a move event immediately. If the widget is not shown yet, it is guaranteed to receive an event before it actually becomes visible.
This function is virtual, and all other overloaded move() implementations call it.
Warning: If you call move() or setGeometry() from moveEvent(), you may see infinite recursion.
See the Window Geometry documentation for an overview of geometry issues with top-level widgets.
See also pos(), resize(), setGeometry(), and moveEvent().
Reimplemented in QSemiModal.
The old position is accessible through QMoveEvent::oldPos().
See also resizeEvent(), event(), move(), and QMoveEvent.
See also setFont() and unsetFont().
See also setPalette() and unsetPalette().
When the paint event occurs, the update region QPaintEvent::region() normally has been cleared to the background color or pixmap. An exception is when repaint(FALSE) is called or the widget sets the WRepaintNoErase or WResizeNoErase flag. Inside the paint event handler, QPaintEvent::erased() carries this information.
For many widgets it is sufficient to redraw the entire widget each time, but some need to consider the update rectangle or region of the QPaintEvent to avoid slow update.
During paintEvent(), any QPainter you create on the widget will be clipped to at most the area covered by the update region.
update() and repaint() can be used to force a paint event.
See also event(), repaint(), update(), QPainter, QPixmap, and QPaintEvent.
Reimplemented in QFrame, QButton, QToolBar, QTabBar, QSizeGrip, and QStatusBar.
As long as no special palette has been set, this is either a special palette for the widget class, the parent's palette or - if this widget is a toplevel widget - the default application palette.
See also setPalette(), colorGroup(), and QApplication::palette().
This virtual function is called from setPalette(). oldPalette is the previous palette; you can get the new palette from palette().
Reimplement this function if your widget needs to know when its palette changes. You will almost certainly need to call this implementation of the function.
See also setPalette() and palette().
The return value is meaningless
This function will be called after a widget has been fully created and before it is shown the very first time.
Polishing is useful for final initialization depending on an instantiated widget. This is something a constructor cannot guarantee since the initialization of the subclasses might not be finished.
After this function, the widget has a proper font and palette and QApplication::polish() has been called.
Remember to call QWidget's implementation when reimplementing this function.
See also constPolish() and QApplication::polish().
See the Window Geometry documentation for an overview of geometry issues with top-level widgets.
See also move(), frameGeometry(), x(), and y().
If there are any siblings of this widget that overlap it on the screen, this widget will be visually in front of its siblings afterwards.
See also lower() and stackUnder().
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
This method is provided to aid porting to Qt 2.0. The function is renamed to reparent() in 2.0, and we hope the FAQs about it will stop.
See the Window Geometry documentation for an overview of geometry issues with top-level widgets.
See also size().
See also grabKeyboard(), grabMouse(), and releaseMouse().
See also grabMouse(), grabKeyboard(), and releaseKeyboard().
Erases the widget area (x,y,w,h) if erase is TRUE.
If w is negative, it is replaced with width() - x.
If h is negative, it is replaced width height() - y.
Use repaint if your widget needs to be repainted immediately, for example when doing some animation. In all other cases, update() is to be preferred. Calling update() many times in a row will generate a single paint event.
Warning: If you call repaint() in a function which may itself be called from paintEvent(), you may see infinite recursion. The update() function never generates recursion.
See also update(), paintEvent(), setUpdatesEnabled(), and erase().
This version erases and repaints the entire widget.
This version repaints the entire widget.
Erases the widget region reg if erase is TRUE.
Use repaint if your widget needs to be repainted immediately, for example when doing some animation. In all other cases, update() is to be preferred. Calling update() many times in a row will generate a single paint event.
Warning: If you call repaint() in a function which may itself be called from paintEvent(), you may see infinite recursion. The update() function never generates recursion.
See also update(), paintEvent(), setUpdatesEnabled(), and erase().
If showIt is TRUE, show() is called once the widget has been reparented.
If the new parent widget is in a different top-level widget, the reparented widget and its children are appended to the end of the TAB chain of the new parent widget, in the same internal order as before. If one of the moved widgets had keyboard focus, reparent() calls clearFocus() for that widget.
If the new parent widget is in the same top-level widget as the old parent, reparent doesn't change the TAB order or keyboard focus.
Warning: Reparenting widgets should be a real exception. In normal applications, you will almost never need it. Dynamic masks can be achieved much easier and cleaner with classes like QWidgetStack or on a higher abstraction level, QWizard.
See also getWFlags().
A convenience version of reparent that does not take widget flags as argument.
Calls reparent(parent, getWFlags()&~WType_Mask, p, showIt )
If the widget is visible, it receives a resize event immediately. If the widget is not shown yet, it is guaranteed to receive an event before it actually becomes visible.
The size is adjusted if it is outside the minimum or maximum widget size.
This function is virtual, and all other overloaded resize() implementations call it.
Warning: If you call resize() or setGeometry() from resizeEvent(), you may see infinite recursion.
See also size(), move(), setGeometry(), resizeEvent(), minimumSize(), and maximumSize().
Reimplemented in QSemiModal.
The widget will be erased and receive a paint event immediately after processing the resize event. No drawing has to (and should) be done inside this handler.
Widgets that have been created with the WResizeNoErase flag will not be erased. Nevertheless, they will receive a paint event for their entire area afterwards. Again, no drawing needs to be done inside this handler.
The default implementation calls updateMask() if the widget has automatic masking enabled.
See also moveEvent(), event(), resize(), QResizeEvent, and paintEvent().
Reimplemented in QFrame and QMainWindow.
If r is empty or invalid, the result is undefined.
After scrolling, scroll() sends a paint event for the the part of r that is read but not written. For example, when scrolling 10 pixels rightwards, the leftmost ten pixels of r need repainting. The paint event may be delivered immediately or later, depending on some heuristics.
This version of scroll() does not move the children of this widget.
See also QScrollView, erase(), and bitBlt().
This version of the function scrolls the entire widget and moves the widget's children along with the scroll.
See also bitBlt() and QScrollView.
If the widgets is the desktop, this may fail if another application is using the desktop - you can call acceptDrops() to test if this occurs.
See also acceptDrops().
An active window is a visible top-level window that has the keyboard input focus.
This function performs the same operation as clicking the mouse on the title bar of a top-level window. On X11, the result depends on the Window Manager. If you want to ensure that the window is stacked on top as well, call raise() in addition. Note that the window has be to visible, otherwise setActiveWindow() has no effect.
On Windows, if you are calling this when the application is not currently the active one then it will not make it the active window. It will flash the task bar entry blue to indicate that the window has done something. This is due to Microsoft not allowing an application to interrupt what the user is currently doing in another application.
See also isActiveWindow(), topLevelWidget(), and show().
Note: When you re-implement resizeEvent(), focusInEvent() or focusOutEvent() in your custom widgets and still want to ensure that the auto mask calculation works, you will have to add
if ( autoMask() )
updateMask();
at the end of your event handlers. Same holds for all member functions that change the appearance of the widget in a way that a recalculation of the mask is necessary.
While being a technically appealing concept, masks have one big drawback: when using complex masks that cannot be expressed easily with relatively simple regions, they tend to be very slow on some window systems. The classic example is a transparent label. The complex shape of its contents makes it necessary to represent its mask by a bitmap, which consumes both memory and time. If all you want is to blend the background of several neighboring widgets together seamlessly, you may probably want to use setBackgroundOrigin() rather than a mask.
See also autoMask(), updateMask(), setMask(), clearMask(), and setBackgroundOrigin().
Note that using this function is very often a mistake. Here are the most common mistakes:
If you want to set the background color of a widget to one of the "usual" colors, setBackgroundMode() is usually the best function. For example, man widgets that usually use white backgrounds (and black text on it) can use this:
thatWidget->setBackgroundMode( QWidget::PaletteBase );
If you want to change the color scheme of a widget, the setPalette() function is better suited. Here is how to set thatWidget to use a light green (RGB value 80, 255, 80) as background color, with shades of green used for all the 3D effects:
thatWidget->setPalette( QPalette( QColor(80, 255, 80) ) );
A fixed background color sometimes is just the right thing, but if you use it, 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.)
<