1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qapplication.h"

    43 #include "qapplication_p.h"

    44 #include "qbrush.h"

    45 #include "qcursor.h"

    46 #include "qdesktopwidget.h"

    47 #include "qevent.h"

    48 #include "qhash.h"

    49 #include "qlayout.h"

    50 #include "qmenu.h"

    51 #include "qmetaobject.h"

    52 #include "qpixmap.h"

    53 #include "qpointer.h"

    54 #include "qstack.h"

    55 #include "qstyle.h"

    56 #include "qstylefactory.h"

    57 #include "qvariant.h"

    58 #include "qwidget.h"

    59 #include "qstyleoption.h"

    60 #ifndef QT_NO_ACCESSIBILITY

    61 # include "qaccessible.h"

    62 #endif

    63 #if defined(Q_WS_WIN)

    64 # include "qt_windows.h"

    65 #endif

    66 #ifdef Q_WS_MAC

    67 # include "qt_mac_p.h"

    68 # include "qt_cocoa_helpers_mac_p.h"

    69 # include "qmainwindow.h"

    70 #endif

    71 #if defined(Q_WS_QWS)

    72 # include "qwsdisplay_qws.h"

    73 # include "qwsmanager_qws.h"

    74 # include "qpaintengine.h" // for PorterDuff

    75 # include "private/qwindowsurface_qws_p.h"

    76 #endif

    77 #include "qpainter.h"

    78 #include "qtooltip.h"

    79 #include "qwhatsthis.h"

    80 #include "qdebug.h"

    81 #include "private/qstylesheetstyle_p.h"

    82 #include "private/qstyle_p.h"

    83 #include "private/qinputcontext_p.h"

    84 #include "qfileinfo.h"

    85 #include "private/qsoftkeymanager_p.h"

    86 

    87 #if defined (Q_WS_WIN)

    88 # include <private/qwininputcontext_p.h>

    89 #endif

    90 

    91 #if defined(Q_WS_X11)

    92 # include <private/qpaintengine_x11_p.h>

    93 # include "qx11info_x11.h"

    94 #endif

    95 

    96 #include <private/qgraphicseffect_p.h>

    97 #include <private/qwindowsurface_p.h>

    98 #include <private/qbackingstore_p.h>

    99 #ifdef Q_WS_MAC

   100 # include <private/qpaintengine_mac_p.h>

   101 #endif

   102 #include <private/qpaintengine_raster_p.h>

   103 

   104 #if defined(Q_OS_SYMBIAN)

   105 #include "private/qt_s60_p.h"

   106 #endif

   107 

   108 #include "qwidget_p.h"

   109 #include "qaction_p.h"

   110 #include "qlayout_p.h"

   111 #include "QtGui/qgraphicsproxywidget.h"

   112 #include "QtGui/qgraphicsscene.h"

   113 #include "private/qgraphicsproxywidget_p.h"

   114 #include "QtGui/qabstractscrollarea.h"

   115 #include "private/qabstractscrollarea_p.h"

   116 #include "private/qevent_p.h"

   117 

   118 #include "private/qgraphicssystem_p.h"

   119 #include "private/qgesturemanager_p.h"

   120 

   121 #ifdef QT_KEYPAD_NAVIGATION

   122 #include "qtabwidget.h" // Needed in inTabWidget()

   123 #endif // QT_KEYPAD_NAVIGATION

   124 

   125 // widget/widget data creation count

   126 //#define QWIDGET_EXTRA_DEBUG

   127 //#define ALIEN_DEBUG

   128 

   129 QT_BEGIN_NAMESPACE

   130 

   131 #if !defined(Q_WS_QWS)

   132 static bool qt_enable_backingstore = true;

   133 #endif

   134 #ifdef Q_WS_X11

   135 // for compatibility with Qt 4.0

   136 Q_GUI_EXPORT void qt_x11_set_global_double_buffer(bool enable)

   137 {

   138     qt_enable_backingstore = enable;

   139 }

   140 #endif

   141 

   142 static inline bool qRectIntersects(const QRect &r1, const QRect &r2)

   143 {

   144     return (qMax(r1.left(), r2.left()) <= qMin(r1.right(), r2.right()) &&

   145             qMax(r1.top(), r2.top()) <= qMin(r1.bottom(), r2.bottom()));

   146 }

   147 

   148 static inline bool hasBackingStoreSupport()

   149 {

   150 #ifdef Q_WS_MAC

   151     return QApplicationPrivate::graphicsSystem() != 0;

   152 #else

   153     return true;

   154 #endif

   155 }

   156 

   157 #ifdef Q_WS_MAC

   158 #  define QT_NO_PAINT_DEBUG

   159 #endif

   160 

   161 extern bool qt_sendSpontaneousEvent(QObject*, QEvent*); // qapplication.cpp

   162 extern QDesktopWidget *qt_desktopWidget; // qapplication.cpp

   163 

   164 QWidgetPrivate::QWidgetPrivate(int version)

   165     : QObjectPrivate(version)

   166       , extra(0)

   167       , focus_next(0)

   168       , focus_prev(0)

   169       , focus_child(0)

   170       , layout(0)

   171       , needsFlush(0)

   172       , redirectDev(0)

   173       , widgetItem(0)

   174       , extraPaintEngine(0)

   175       , polished(0)

   176       , graphicsEffect(0)

   177 #if !defined(QT_NO_IM)

   178       , imHints(Qt::ImhNone)

   179 #endif

   180       , inheritedFontResolveMask(0)

   181       , inheritedPaletteResolveMask(0)

   182       , leftmargin(0)

   183       , topmargin(0)

   184       , rightmargin(0)

   185       , bottommargin(0)

   186       , leftLayoutItemMargin(0)

   187       , topLayoutItemMargin(0)

   188       , rightLayoutItemMargin(0)

   189       , bottomLayoutItemMargin(0)

   190       , hd(0)

   191       , size_policy(QSizePolicy::Preferred, QSizePolicy::Preferred)

   192       , fg_role(QPalette::NoRole)

   193       , bg_role(QPalette::NoRole)

   194       , dirtyOpaqueChildren(1)

   195       , isOpaque(0)

   196       , inDirtyList(0)

   197       , isScrolled(0)

   198       , isMoved(0)

   199       , isGLWidget(0)

   200       , usesDoubleBufferedGLContext(0)

   201 #if defined(Q_WS_X11)

   202       , picture(0)

   203 #elif defined(Q_WS_WIN)

   204       , noPaintOnScreen(0)

   205       , nativeGesturePanEnabled(0)

   206 #elif defined(Q_WS_MAC)

   207       , needWindowChange(0)

   208       , window_event(0)

   209       , qd_hd(0)

   210 #endif

   211 {

   212     if (!qApp) {

   213         qFatal("QWidget: Must construct a QApplication before a QPaintDevice");

   214         return;

   215     }

   216 

   217     if (version != QObjectPrivateVersion)

   218         qFatal("Cannot mix incompatible Qt libraries");

   219 

   220     isWidget = true;

   221     memset(high_attributes, 0, sizeof(high_attributes));

   222 #ifdef QWIDGET_EXTRA_DEBUG

   223     static int count = 0;

   224     qDebug() << "widgets" << ++count;

   225 #endif

   226 }

   227 

   228 

   229 QWidgetPrivate::~QWidgetPrivate()

   230 {

   231     if (widgetItem)

   232         widgetItem->wid = 0;

   233 

   234     if (extra)

   235         deleteExtra();

   236 

   237 #ifndef QT_NO_GRAPHICSEFFECT

   238     delete graphicsEffect;

   239 #endif //QT_NO_GRAPHICSEFFECT

   240 }

   241 

   242 QWindowSurface *QWidgetPrivate::createDefaultWindowSurface()

   243 {

   244     Q_Q(QWidget);

   245     if (QApplicationPrivate::graphicsSystem())

   246         return QApplicationPrivate::graphicsSystem()->createWindowSurface(q);

   247     return createDefaultWindowSurface_sys();

   248 }

   249 

   250 /*!

   251     \internal

   252 */

   253 void QWidgetPrivate::scrollChildren(int dx, int dy)

   254 {

   255     Q_Q(QWidget);

   256     if (q->children().size() > 0) {        // scroll children

   257         QPoint pd(dx, dy);

   258         QObjectList childObjects = q->children();

   259         for (int i = 0; i < childObjects.size(); ++i) { // move all children

   260             QWidget *w = qobject_cast<QWidget*>(childObjects.at(i));

   261             if (w && !w->isWindow()) {

   262                 QPoint oldp = w->pos();

   263                 QRect  r(w->pos() + pd, w->size());

   264                 w->data->crect = r;

   265 #ifndef Q_WS_QWS

   266                 if (w->testAttribute(Qt::WA_WState_Created))

   267                     w->d_func()->setWSGeometry();

   268 #endif

   269                 w->d_func()->setDirtyOpaqueRegion();

   270                 QMoveEvent e(r.topLeft(), oldp);

   271                 QApplication::sendEvent(w, &e);

   272             }

   273         }

   274     }

   275 }

   276 

   277 QInputContext *QWidgetPrivate::inputContext() const

   278 {

   279 #ifndef QT_NO_IM

   280     if (ic)

   281         return ic;

   282 #endif

   283     return qApp->inputContext();

   284 }

   285 

   286 /*!

   287     This function returns the QInputContext for this widget. By

   288     default the input context is inherited from the widgets

   289     parent. For toplevels it is inherited from QApplication.

   290 

   291     You can override this and set a special input context for this

   292     widget by using the setInputContext() method.

   293 

   294     \sa setInputContext()

   295 */

   296 QInputContext *QWidget::inputContext()

   297 {

   298     Q_D(QWidget);

   299     if (!testAttribute(Qt::WA_InputMethodEnabled))

   300         return 0;

   301 

   302     return d->inputContext();

   303 }

   304 

   305 /*!

   306   This function sets the input context \a context

   307   on this widget.

   308 

   309   \sa inputContext()

   310 */

   311 void QWidget::setInputContext(QInputContext *context)

   312 {

   313     Q_D(QWidget);

   314     if (!testAttribute(Qt::WA_InputMethodEnabled))

   315         return;

   316 #ifndef QT_NO_IM

   317     if (d->ic)

   318         delete d->ic;

   319     d->ic = context;

   320 #endif

   321 }

   322 

   323 

   324 /*!

   325     \obsolete

   326 

   327     This function can be called on the widget that currently has focus

   328     to reset the input method operating on it.

   329 

   330     This function is providing for convenience, instead you should use

   331     \l{QInputContext::}{reset()} on the input context that was

   332     returned by inputContext().

   333 

   334     \sa QInputContext, inputContext(), QInputContext::reset()

   335 */

   336 void QWidget::resetInputContext()

   337 {

   338     if (!hasFocus())

   339         return;

   340 #ifndef QT_NO_IM

   341     QInputContext *qic = this->inputContext();

   342     if(qic)

   343         qic->reset();

   344 #endif // QT_NO_IM

   345 }

   346 

   347 #ifdef QT_KEYPAD_NAVIGATION

   348 QPointer<QWidget> QWidgetPrivate::editingWidget;

   349 

   350 /*!

   351     Returns true if this widget currently has edit focus; otherwise false.

   352 

   353     This feature is only available in Qt for Embedded Linux.

   354 

   355     \sa setEditFocus(), QApplication::keypadNavigationEnabled()

   356 */

   357 bool QWidget::hasEditFocus() const

   358 {

   359     const QWidget* w = this;

   360     while (w->d_func()->extra && w->d_func()->extra->focus_proxy)

   361         w = w->d_func()->extra->focus_proxy;

   362     return QWidgetPrivate::editingWidget == w;

   363 }

   364 

   365 /*!

   366     \fn void QWidget::setEditFocus(bool enable)

   367 

   368     If \a enable is true, make this widget have edit focus, in which

   369     case Qt::Key_Up and Qt::Key_Down will be delivered to the widget

   370     normally; otherwise, Qt::Key_Up and Qt::Key_Down are used to

   371     change focus.

   372 

   373     This feature is only available in Qt for Embedded Linux and Qt

   374     for Symbian.

   375 

   376     \sa hasEditFocus(), QApplication::keypadNavigationEnabled()

   377 */

   378 void QWidget::setEditFocus(bool on)

   379 {

   380     QWidget *f = this;

   381     while (f->d_func()->extra && f->d_func()->extra->focus_proxy)

   382         f = f->d_func()->extra->focus_proxy;

   383 

   384     if (QWidgetPrivate::editingWidget && QWidgetPrivate::editingWidget != f)

   385         QWidgetPrivate::editingWidget->setEditFocus(false);

   386 

   387     if (on && !f->hasFocus())

   388         f->setFocus();

   389 

   390     if ((!on && !QWidgetPrivate::editingWidget)

   391         || (on && QWidgetPrivate::editingWidget == f)) {

   392         return;

   393     }

   394 

   395     if (!on && QWidgetPrivate::editingWidget == f) {

   396         QWidgetPrivate::editingWidget = 0;

   397         QEvent event(QEvent::LeaveEditFocus);

   398         QApplication::sendEvent(f, &event);

   399         QApplication::sendEvent(f->style(), &event);

   400     } else if (on) {

   401         QWidgetPrivate::editingWidget = f;

   402         QEvent event(QEvent::EnterEditFocus);

   403         QApplication::sendEvent(f, &event);

   404         QApplication::sendEvent(f->style(), &event);

   405     }

   406 }

   407 #endif

   408 

   409 /*!

   410     \property QWidget::autoFillBackground

   411     \brief whether the widget background is filled automatically

   412     \since 4.1

   413 

   414     If enabled, this property will cause Qt to fill the background of the

   415     widget before invoking the paint event. The color used is defined by the

   416     QPalette::Window color role from the widget's \l{QPalette}{palette}.

   417 

   418     In addition, Windows are always filled with QPalette::Window, unless the

   419     WA_OpaquePaintEvent or WA_NoSystemBackground attributes are set.

   420 

   421     This property cannot be turned off (i.e., set to false) if a widget's

   422     parent has a static gradient for its background.

   423 

   424     \warning Use this property with caution in conjunction with

   425     \l{Qt Style Sheets}. When a widget has a style sheet with a valid

   426     background or a border-image, this property is automatically disabled.

   427 

   428     By default, this property is false.

   429 

   430     \sa Qt::WA_OpaquePaintEvent, Qt::WA_NoSystemBackground,

   431     {QWidget#Transparency and Double Buffering}{Transparency and Double Buffering}

   432 */

   433 bool QWidget::autoFillBackground() const

   434 {

   435     Q_D(const QWidget);

   436     return d->extra && d->extra->autoFillBackground;

   437 }

   438 

   439 void QWidget::setAutoFillBackground(bool enabled)

   440 {

   441     Q_D(QWidget);

   442     if (!d->extra)

   443         d->createExtra();

   444     if (d->extra->autoFillBackground == enabled)

   445         return;

   446 

   447     d->extra->autoFillBackground = enabled;

   448     d->updateIsOpaque();

   449     update();

   450     d->updateIsOpaque();

   451 }

   452 

   453 /*!

   454     \class QWidget

   455     \brief The QWidget class is the base class of all user interface objects.

   456 

   457     \ingroup basicwidgets

   458 

   459 

   460     The widget is the atom of the user interface: it receives mouse, keyboard

   461     and other events from the window system, and paints a representation of

   462     itself on the screen. Every widget is rectangular, and they are sorted in a

   463     Z-order. A widget is clipped by its parent and by the widgets in front of

   464     it.

   465 

   466     A widget that is not embedded in a parent widget is called a window.

   467     Usually, windows have a frame and a title bar, although it is also possible

   468     to create windows without such decoration using suitable

   469     \l{Qt::WindowFlags}{window flags}). In Qt, QMainWindow and the various

   470     subclasses of QDialog are the most common window types.

   471 

   472     Every widget's constructor accepts one or two standard arguments:

   473 

   474     \list 1

   475         \i  \c{QWidget *parent = 0} is the parent of the new widget. If it is 0

   476             (the default), the new widget will be a window. If not, it will be

   477             a child of \e parent, and be constrained by \e parent's geometry

   478             (unless you specify Qt::Window as window flag).

   479         \i  \c{Qt::WindowFlags f = 0} (where available) sets the window flags;

   480             the default is suitable for almost all widgets, but to get, for

   481             example, a window without a window system frame, you must use

   482             special flags.

   483     \endlist

   484 

   485     QWidget has many member functions, but some of them have little direct

   486     functionality; for example, QWidget has a font property, but never uses

   487     this itself. There are many subclasses which provide real functionality,

   488     such as QLabel, QPushButton, QListWidget, and QTabWidget.

   489 

   490 

   491     \section1 Top-Level and Child Widgets

   492 

   493     A widget without a parent widget is always an independent window (top-level

   494     widget). For these widgets, setWindowTitle() and setWindowIcon() set the

   495     title bar and icon respectively.

   496 

   497     Non-window widgets are child widgets, displayed within their parent

   498     widgets. Most widgets in Qt are mainly useful as child widgets. For

   499     example, it is possible to display a button as a top-level window, but most

   500     people prefer to put their buttons inside other widgets, such as QDialog.

   501 

   502     \image parent-child-widgets.png A parent widget containing various child widgets.

   503 

   504     The diagram above shows a QGroupBox widget being used to hold various child

   505     widgets in a layout provided by QGridLayout. The QLabel child widgets have

   506     been outlined to indicate their full sizes.

   507 

   508     If you want to use a QWidget to hold child widgets you will usually want to

   509     add a layout to the parent QWidget. See \l{Layout Management} for more

   510     information.

   511 

   512 

   513     \section1 Composite Widgets

   514 

   515     When a widget is used as a container to group a number of child widgets, it

   516     is known as a composite widget. These can be created by constructing a

   517     widget with the required visual properties - a QFrame, for example - and

   518     adding child widgets to it, usually managed by a layout. The above diagram

   519     shows such a composite widget that was created using \l{Qt Designer}.

   520 

   521     Composite widgets can also be created by subclassing a standard widget,

   522     such as QWidget or QFrame, and adding the necessary layout and child

   523     widgets in the constructor of the subclass. Many of the \l{Qt Examples}

   524     {examples provided with Qt} use this approach, and it is also covered in

   525     the Qt \l{Tutorials}.

   526 

   527 

   528     \section1 Custom Widgets and Painting

   529 

   530     Since QWidget is a subclass of QPaintDevice, subclasses can be used to

   531     display custom content that is composed using a series of painting

   532     operations with an instance of the QPainter class. This approach contrasts

   533     with the canvas-style approach used by the \l{Graphics View}

   534     {Graphics View Framework} where items are added to a scene by the

   535     application and are rendered by the framework itself.

   536 

   537     Each widget performs all painting operations from within its paintEvent()

   538     function. This is called whenever the widget needs to be redrawn, either

   539     as a result of some external change or when requested by the application.

   540 

   541     The \l{widgets/analogclock}{Analog Clock example} shows how a simple widget

   542     can handle paint events.

   543 

   544 

   545     \section1 Size Hints and Size Policies

   546 

   547     When implementing a new widget, it is almost always useful to reimplement

   548     sizeHint() to provide a reasonable default size for the widget and to set

   549     the correct size policy with setSizePolicy().

   550 

   551     By default, composite widgets which do not provide a size hint will be

   552     sized according to the space requirements of their child widgets.

   553 

   554     The size policy lets you supply good default behavior for the layout

   555     management system, so that other widgets can contain and manage yours

   556     easily. The default size policy indicates that the size hint represents

   557     the preferred size of the widget, and this is often good enough for many

   558     widgets.

   559 

   560     \note The size of top-level widgets are constrained to 2/3 of the desktop's

   561     height and width. You can resize() the widget manually if these bounds are

   562     inadequate.

   563 

   564 

   565     \section1 Events

   566 

   567     Widgets respond to events that are typically caused by user actions. Qt

   568     delivers events to widgets by calling specific event handler functions with

   569     instances of QEvent subclasses containing information about each event.

   570 

   571     If your widget only contains child widgets, you probably do not need to

   572     implement any event handlers. If you want to detect a mouse click in a

   573     child widget call the child's underMouse() function inside the widget's

   574     mousePressEvent().

   575 

   576     The \l{widgets/scribble}{Scribble example} implements a wider set of

   577     events to handle mouse movement, button presses, and window resizing.

   578 

   579     You will need to supply the behavior and content for your own widgets, but

   580     here is a brief overview of the events that are relevant to QWidget,

   581     starting with the most common ones:

   582 

   583     \list

   584         \i  paintEvent() is called whenever the widget needs to be repainted.

   585             Every widget displaying custom content must implement it. Painting

   586             using a QPainter can only take place in a paintEvent() or a

   587             function called by a paintEvent().

   588         \i  resizeEvent() is called when the widget has been resized.

   589         \i  mousePressEvent() is called when a mouse button is pressed while

   590             the mouse cursor is inside the widget, or when the widget has

   591             grabbed the mouse using grabMouse(). Pressing the mouse without

   592             releasing it is effectively the same as calling grabMouse().

   593         \i  mouseReleaseEvent() is called when a mouse button is released. A

   594             widget receives mouse release events when it has received the

   595             corresponding mouse press event. This means that if the user

   596             presses the mouse inside \e your widget, then drags the mouse

   597             somewhere else before releasing the mouse button, \e your widget

   598             receives the release event. There is one exception: if a popup menu

   599             appears while the mouse button is held down, this popup immediately

   600             steals the mouse events.

   601         \i  mouseDoubleClickEvent() is called when the user double-clicks in

   602             the widget. If the user double-clicks, the widget receives a mouse

   603             press event, a mouse release event and finally this event instead

   604             of a second mouse press event. (Some mouse move events may also be

   605             received if the mouse is not held steady during this operation.) It

   606             is \e{not possible} to distinguish a click from a double-click

   607             until the second click arrives. (This is one reason why most GUI

   608             books recommend that double-clicks be an extension of

   609             single-clicks, rather than trigger a different action.)

   610     \endlist

   611 

   612     Widgets that accept keyboard input need to reimplement a few more event

   613     handlers:

   614 

   615     \list

   616         \i  keyPressEvent() is called whenever a key is pressed, and again when

   617             a key has been held down long enough for it to auto-repeat. The

   618             \key Tab and \key Shift+Tab keys are only passed to the widget if

   619             they are not used by the focus-change mechanisms. To force those

   620             keys to be processed by your widget, you must reimplement

   621             QWidget::event().

   622         \i  focusInEvent() is called when the widget gains keyboard focus

   623             (assuming you have called setFocusPolicy()). Well-behaved widgets

   624             indicate that they own the keyboard focus in a clear but discreet

   625             way.

   626         \i  focusOutEvent() is called when the widget loses keyboard focus.

   627     \endlist

   628 

   629     You may be required to also reimplement some of the less common event

   630     handlers:

   631 

   632     \list

   633         \i  mouseMoveEvent() is called whenever the mouse moves while a mouse

   634             button is held down. This can be useful during drag and drop

   635             operations. If you call setMouseTracking(true), you get mouse move

   636             events even when no buttons are held down. (See also the \l{Drag

   637             and Drop} guide.)

   638         \i  keyReleaseEvent() is called whenever a key is released and while it

   639             is held down (if the key is auto-repeating). In that case, the

   640             widget will receive a pair of key release and key press event for

   641             every repeat. The \key Tab and \key Shift+Tab keys are only passed

   642             to the widget if they are not used by the focus-change mechanisms.

   643             To force those keys to be processed by your widget, you must

   644             reimplement QWidget::event().

   645         \i  wheelEvent() is called whenever the user turns the mouse wheel

   646             while the widget has the focus.

   647         \i  enterEvent() is called when the mouse enters the widget's screen

   648             space. (This excludes screen space owned by any of the widget's

   649             children.)

   650         \i  leaveEvent() is called when the mouse leaves the widget's screen

   651             space. If the mouse enters a child widget it will not cause a

   652             leaveEvent().

   653         \i  moveEvent() is called when the widget has been moved relative to

   654             its parent.

   655         \i  closeEvent() is called when the user closes the widget (or when

   656             close() is called).

   657     \endlist

   658 

   659     There are also some rather obscure events described in the documentation

   660     for QEvent::Type. To handle these events, you need to reimplement event()

   661     directly.

   662 

   663     The default implementation of event() handles \key Tab and \key Shift+Tab

   664     (to move the keyboard focus), and passes on most of the other events to

   665     one of the more specialized handlers above.

   666 

   667     Events and the mechanism used to deliver them are covered in the

   668     \l{Events and Event Filters} document.

   669 

   670     \section1 Groups of Functions and Properties

   671 

   672     \table

   673     \header \i Context \i Functions and Properties

   674 

   675     \row \i Window functions \i

   676         show(),

   677         hide(),

   678         raise(),

   679         lower(),

   680         close().

   681 

   682     \row \i Top-level windows \i

   683         \l windowModified, \l windowTitle, \l windowIcon, \l windowIconText,

   684         \l isActiveWindow, activateWindow(), \l minimized, showMinimized(),

   685         \l maximized, showMaximized(), \l fullScreen, showFullScreen(),

   686         showNormal().

   687 

   688     \row \i Window contents \i

   689         update(),

   690         repaint(),

   691         scroll().

   692 

   693     \row \i Geometry \i

   694         \l pos, x(), y(), \l rect, \l size, width(), height(), move(), resize(),

   695         \l sizePolicy, sizeHint(), minimumSizeHint(),

   696         updateGeometry(), layout(),

   697         \l frameGeometry, \l geometry, \l childrenRect, \l childrenRegion,

   698         adjustSize(),

   699         mapFromGlobal(), mapToGlobal(),

   700         mapFromParent(), mapToParent(),

   701         \l maximumSize, \l minimumSize, \l sizeIncrement,

   702         \l baseSize, setFixedSize()

   703 

   704     \row \i Mode \i

   705         \l visible, isVisibleTo(),

   706         \l enabled, isEnabledTo(),

   707         \l modal,

   708         isWindow(),

   709         \l mouseTracking,

   710         \l updatesEnabled,

   711         visibleRegion().

   712 

   713     \row \i Look and feel \i

   714         style(),

   715         setStyle(),

   716         \l styleSheet,

   717         \l cursor,

   718         \l font,

   719         \l palette,

   720         backgroundRole(), setBackgroundRole(),

   721         fontInfo(), fontMetrics().

   722 

   723     \row \i Keyboard focus functions \i

   724         \l focus, \l focusPolicy,

   725         setFocus(), clearFocus(), setTabOrder(), setFocusProxy(),

   726         focusNextChild(), focusPreviousChild().

   727 

   728     \row \i Mouse and keyboard grabbing \i

   729         grabMouse(), releaseMouse(),

   730         grabKeyboard(), releaseKeyboard(),

   731         mouseGrabber(), keyboardGrabber().

   732 

   733     \row \i Event handlers \i

   734         event(),

   735         mousePressEvent(),

   736         mouseReleaseEvent(),

   737         mouseDoubleClickEvent(),

   738         mouseMoveEvent(),

   739         keyPressEvent(),

   740         keyReleaseEvent(),

   741         focusInEvent(),

   742         focusOutEvent(),

   743         wheelEvent(),

   744         enterEvent(),

   745         leaveEvent(),

   746         paintEvent(),

   747         moveEvent(),

   748         resizeEvent(),

   749         closeEvent(),

   750         dragEnterEvent(),

   751         dragMoveEvent(),

   752         dragLeaveEvent(),

   753         dropEvent(),

   754         childEvent(),

   755         showEvent(),

   756         hideEvent(),

   757         customEvent().

   758         changeEvent(),

   759 

   760     \row \i System functions \i

   761         parentWidget(), window(), setParent(), winId(),

   762         find(), metric().

   763 

   764     \row \i Interactive help \i

   765         setToolTip(), setWhatsThis()

   766 

   767     \endtable

   768 

   769 

   770     \section1 Widget Style Sheets

   771 

   772     In addition to the standard widget styles for each platform, widgets can

   773     also be styled according to rules specified in a \l{styleSheet}

   774     {style sheet}. This feature enables you to customize the appearance of

   775     specific widgets to provide visual cues to users about their purpose. For

   776     example, a button could be styled in a particular way to indicate that it

   777     performs a destructive action.

   778 

   779     The use of widget style sheets is described in more detail in the

   780     \l{Qt Style Sheets} document.

   781 

   782 

   783     \section1 Transparency and Double Buffering

   784 

   785     Since Qt 4.0, QWidget automatically double-buffers its painting, so there

   786     is no need to write double-buffering code in paintEvent() to avoid

   787     flicker.

   788 

   789     Since Qt 4.1, the Qt::WA_ContentsPropagated widget attribute has been

   790     deprecated. Instead, the contents of parent widgets are propagated by

   791     default to each of their children as long as Qt::WA_PaintOnScreen is not

   792     set. Custom widgets can be written to take advantage of this feature by

   793     updating irregular regions (to create non-rectangular child widgets), or

   794     painting with colors that have less than full alpha component. The

   795     following diagram shows how attributes and properties of a custom widget

   796     can be fine-tuned to achieve different effects.

   797 

   798     \image propagation-custom.png

   799 

   800     In the above diagram, a semi-transparent rectangular child widget with an

   801     area removed is constructed and added to a parent widget (a QLabel showing

   802     a pixmap). Then, different properties and widget attributes are set to

   803     achieve different effects:

   804 

   805     \list

   806         \i  The left widget has no additional properties or widget attributes

   807             set. This default state suits most custom widgets using

   808             transparency, are irregularly-shaped, or do not paint over their

   809             entire area with an opaque brush.

   810         \i  The center widget has the \l autoFillBackground property set. This

   811             property is used with custom widgets that rely on the widget to

   812             supply a default background, and do not paint over their entire

   813             area with an opaque brush.

   814         \i  The right widget has the Qt::WA_OpaquePaintEvent widget attribute

   815             set. This indicates that the widget will paint over its entire area

   816             with opaque colors. The widget's area will initially be

   817             \e{uninitialized}, represented in the diagram with a red diagonal

   818             grid pattern that shines through the overpainted area. The

   819             Qt::WA_OpaquePaintArea attribute is useful for widgets that need to

   820             paint their own specialized contents quickly and do not need a

   821             default filled background.

   822     \endlist

   823 

   824     To rapidly update custom widgets with simple background colors, such as

   825     real-time plotting or graphing widgets, it is better to define a suitable

   826     background color (using setBackgroundRole() with the

   827     QPalette::Window role), set the \l autoFillBackground property, and only

   828     implement the necessary drawing functionality in the widget's paintEvent().

   829 

   830     To rapidly update custom widgets that constantly paint over their entire

   831     areas with opaque content, e.g., video streaming widgets, it is better to

   832     set the widget's Qt::WA_OpaquePaintEvent, avoiding any unnecessary overhead

   833     associated with repainting the widget's background.

   834 

   835     If a widget has both the Qt::WA_OpaquePaintEvent widget attribute \e{and}

   836     the \l autoFillBackground property set, the Qt::WA_OpaquePaintEvent

   837     attribute takes precedence. Depending on your requirements, you should

   838     choose either one of them.

   839 

   840     Since Qt 4.1, the contents of parent widgets are also propagated to

   841     standard Qt widgets. This can lead to some unexpected results if the

   842     parent widget is decorated in a non-standard way, as shown in the diagram

   843     below.

   844 

   845     \image propagation-standard.png

   846 

   847     The scope for customizing the painting behavior of standard Qt widgets,

   848     without resorting to subclassing, is slightly less than that possible for

   849     custom widgets. Usually, the desired appearance of a standard widget can be

   850     achieved by setting its \l autoFillBackground property.

   851 

   852 

   853     \section1 Creating Translucent Windows

   854 

   855     Since Qt 4.5, it has been possible to create windows with translucent regions

   856     on window systems that support compositing.

   857 

   858     To enable this feature in a top-level widget, set its Qt::WA_TranslucentBackground

   859     attribute with setAttribute() and ensure that its background is painted with

   860     non-opaque colors in the regions you want to be partially transparent.

   861 

   862     Platform notes:

   863 

   864     \list

   865     \o X11: This feature relies on the use of an X server that supports ARGB visuals

   866     and a compositing window manager.

   867     \o Windows: The widget needs to have the Qt::FramelessWindowHint window flag set

   868     for the translucency to work.

   869     \endlist

   870 

   871 

   872     \section1 Native Widgets vs Alien Widgets

   873 

   874     Introduced in Qt 4.4, alien widgets are widgets unknown to the windowing

   875     system. They do not have a native window handle associated with them. This

   876     feature significantly speeds up widget painting, resizing, and removes flicker.

   877 

   878     Should you require the old behavior with native windows, you can choose

   879     one of the following options:

   880 

   881     \list 1

   882         \i  Use the \c{QT_USE_NATIVE_WINDOWS=1} in your environment.

   883         \i  Set the Qt::AA_NativeWindows attribute on your application. All

   884             widgets will be native widgets.

   885         \i  Set the Qt::WA_NativeWindow attribute on widgets: The widget itself

   886             and all of its ancestors will become native (unless

   887             Qt::WA_DontCreateNativeAncestors is set).

   888         \i  Call QWidget::winId to enforce a native window (this implies 3).

   889         \i  Set the Qt::WA_PaintOnScreen attribute to enforce a native window

   890             (this implies 3).

   891     \endlist

   892 

   893     \sa QEvent, QPainter, QGridLayout, QBoxLayout

   894 

   895     \section1 Softkeys

   896 

   897     Since Qt 4.6, Softkeys are usually physical keys on a device that have a corresponding label or

   898     other visual representation on the screen that is generally located next to its

   899     physical counterpart. They are most often found on mobile phone platforms. In

   900     modern touch based user interfaces it is also possible to have softkeys that do

   901     not correspond to any physical keys. Softkeys differ from other onscreen labels

   902     in that they are contextual.

   903 

   904     In Qt, contextual softkeys are added to a widget by calling addAction() and

   905     passing a \c QAction with a softkey role set on it. When the widget

   906     containing the softkey actions has focus, its softkeys should appear in

   907     the user interface. Softkeys are discovered by traversing the widget

   908     hierarchy so it is possible to define a single set of softkeys that are

   909     present at all times by calling addAction() for a given top level widget.

   910 

   911     On some platforms, this concept overlaps with \c QMenuBar such that if no

   912     other softkeys are found and the top level widget is a QMainWindow containing

   913     a QMenuBar, the menubar actions may appear on one of the softkeys.

   914 

   915     Note: Currently softkeys are only supported on the Symbian Platform.

   916 

   917     \sa addAction(), QAction, QMenuBar

   918 

   919 */

   920 

   921 QWidgetMapper *QWidgetPrivate::mapper = 0;          // widget with wid

   922 QWidgetSet *QWidgetPrivate::allWidgets = 0;         // widgets with no wid

   923 

   924 

   925 /*****************************************************************************

   926   QWidget utility functions

   927  *****************************************************************************/

   928 

   929 QRegion qt_dirtyRegion(QWidget *widget)

   930 {

   931     if (!widget)

   932         return QRegion();

   933 

   934     QWidgetBackingStore *bs = qt_widget_private(widget)->maybeBackingStore();

   935     if (!bs)

   936         return QRegion();

   937 

   938     return bs->dirtyRegion(widget);

   939 }

   940 

   941 /*****************************************************************************

   942   QWidget member functions

   943  *****************************************************************************/

   944 

   945 /*

   946     Widget state flags:

   947   \list

   948   \i Qt::WA_WState_Created The widget has a valid winId().

   949   \i Qt::WA_WState_Visible The widget is currently visible.

   950   \i Qt::WA_WState_Hidden The widget is hidden, i.e. it won't

   951   become visible unless you call show() on it. Qt::WA_WState_Hidden

   952   implies !Qt::WA_WState_Visible.

   953   \i Qt::WA_WState_CompressKeys Compress keyboard events.

   954   \i Qt::WA_WState_BlockUpdates Repaints and updates are disabled.

   955   \i Qt::WA_WState_InPaintEvent Currently processing a paint event.

   956   \i Qt::WA_WState_Reparented The widget has been reparented.

   957   \i Qt::WA_WState_ConfigPending A configuration (resize/move) event is pending.

   958   \i Qt::WA_WState_DND (Deprecated) The widget supports drag and drop, see setAcceptDrops().

   959   \endlist

   960 */

   961 

   962 struct QWidgetExceptionCleaner

   963 {

   964     /* this cleans up when the constructor throws an exception */

   965     static inline void cleanup(QWidget *that, QWidgetPrivate *d)

   966     {

   967 #ifdef QT_NO_EXCEPTIONS

   968         Q_UNUSED(that);

   969         Q_UNUSED(d);

   970 #else

   971         QWidgetPrivate::allWidgets->remove(that);

   972         if (d->focus_next != that) {

   973             if (d->focus_next)

   974                 d->focus_next->d_func()->focus_prev = d->focus_prev;

   975             if (d->focus_prev)

   976                 d->focus_prev->d_func()->focus_next = d->focus_next;

   977         }

   978 #endif

   979     }

   980 };

   981 

   982 /*!

   983     Constructs a widget which is a child of \a parent, with  widget

   984     flags set to \a f.

   985 

   986     If \a parent is 0, the new widget becomes a window. If

   987     \a parent is another widget, this widget becomes a child window

   988     inside \a parent. The new widget is deleted when its \a parent is

   989     deleted.

   990 

   991     The widget flags argument, \a f, is normally 0, but it can be set

   992     to customize the frame of a window (i.e. \a

   993     parent must be 0). To customize the frame, use a value composed

   994     from the bitwise OR of any of the \l{Qt::WindowFlags}{window flags}.

   995 

   996     If you add a child widget to an already visible widget you must

   997     explicitly show the child to make it visible.

   998 

   999     Note that the X11 version of Qt may not be able to deliver all

  1000     combinations of style flags on all systems. This is because on

  1001     X11, Qt can only ask the window manager, and the window manager

  1002     can override the application's settings. On Windows, Qt can set

  1003     whatever flags you want.

  1004 

  1005     \sa windowFlags

  1006 */

  1007 

  1008 QWidget::QWidget(QWidget *parent, Qt::WindowFlags f)

  1009     : QObject(*new QWidgetPrivate, 0), QPaintDevice()

  1010 {

  1011     QT_TRY {

  1012         d_func()->init(parent, f);

  1013     } QT_CATCH(...) {

  1014         QWidgetExceptionCleaner::cleanup(this, d_func());

  1015         QT_RETHROW;

  1016     }

  1017 }

  1018 

  1019 #ifdef QT3_SUPPORT

  1020 /*!

  1021     \overload

  1022     \obsolete

  1023  */

  1024 QWidget::QWidget(QWidget *parent, const char *name, Qt::WindowFlags f)

  1025     : QObject(*new QWidgetPrivate, 0), QPaintDevice()

  1026 {

  1027     QT_TRY {

  1028         d_func()->init(parent , f);

  1029         setObjectName(QString::fromAscii(name));

  1030     } QT_CATCH(...) {

  1031         QWidgetExceptionCleaner::cleanup(this, d_func());

  1032         QT_RETHROW;

  1033     }

  1034 }

  1035 #endif

  1036 

  1037 /*! \internal

  1038 */

  1039 QWidget::QWidget(QWidgetPrivate &dd, QWidget* parent, Qt::WindowFlags f)

  1040     : QObject(dd, 0), QPaintDevice()

  1041 {

  1042     Q_D(QWidget);

  1043     QT_TRY {

  1044         d->init(parent, f);

  1045     } QT_CATCH(...) {

  1046         QWidgetExceptionCleaner::cleanup(this, d_func());

  1047         QT_RETHROW;

  1048     }

  1049 }

  1050 

  1051 /*!

  1052     \internal

  1053 */

  1054 int QWidget::devType() const

  1055 {

  1056     return QInternal::Widget;

  1057 }

  1058 

  1059 

  1060 //### w is a "this" ptr, passed as a param because QWorkspace needs special logic

  1061 void QWidgetPrivate::adjustFlags(Qt::WindowFlags &flags, QWidget *w)

  1062 {

  1063     bool customize =  (flags & (Qt::CustomizeWindowHint

  1064             | Qt::FramelessWindowHint

  1065             | Qt::WindowTitleHint

  1066             | Qt::WindowSystemMenuHint

  1067             | Qt::WindowMinimizeButtonHint

  1068             | Qt::WindowMaximizeButtonHint

  1069             | Qt::WindowCloseButtonHint

  1070             | Qt::WindowContextHelpButtonHint));

  1071 

  1072     uint type = (flags & Qt::WindowType_Mask);

  1073 

  1074     if ((type == Qt::Widget || type == Qt::SubWindow) && w && !w->parent()) {

  1075         type = Qt::Window;

  1076         flags |= Qt::Window;

  1077     }

  1078 

  1079     if (flags & Qt::CustomizeWindowHint) {

  1080         // modify window flags to make them consistent.

  1081         // Only enable this on non-Mac platforms. Since the old way of doing this would

  1082         // interpret WindowSystemMenuHint as a close button and we can't change that behavior

  1083         // we can't just add this in.

  1084 #ifndef Q_WS_MAC

  1085         if (flags & (Qt::WindowMinMaxButtonsHint | Qt::WindowCloseButtonHint | Qt::WindowContextHelpButtonHint)) {

  1086             flags |= Qt::WindowSystemMenuHint;

  1087 #else

  1088         if (flags & (Qt::WindowMinMaxButtonsHint | Qt::WindowCloseButtonHint

  1089                      | Qt::WindowSystemMenuHint)) {

  1090 #endif

  1091             flags |= Qt::WindowTitleHint;

  1092             flags &= ~Qt::FramelessWindowHint;

  1093         }

  1094     } else if (customize && !(flags & Qt::FramelessWindowHint)) {

  1095         // if any of the window hints that affect the titlebar are set

  1096         // and the window is supposed to have frame, we add a titlebar

  1097         // and system menu by default.

  1098         flags |= Qt::WindowSystemMenuHint;

  1099         flags |= Qt::WindowTitleHint;

  1100     }

  1101     if (customize)

  1102         ; // don't modify window flags if the user explicitely set them.

  1103     else if (type == Qt::Dialog || type == Qt::Sheet)

  1104 #ifndef Q_WS_WINCE

  1105         flags |= Qt::WindowTitleHint | Qt::WindowSystemMenuHint | Qt::WindowContextHelpButtonHint | Qt::WindowCloseButtonHint;

  1106 #else

  1107         flags |= Qt::WindowTitleHint | Qt::WindowSystemMenuHint | Qt::WindowCloseButtonHint;

  1108 #endif

  1109     else if (type == Qt::Tool)

  1110         flags |= Qt::WindowTitleHint | Qt::WindowSystemMenuHint | Qt::WindowCloseButtonHint;

  1111     else

  1112         flags |= Qt::WindowTitleHint | Qt::WindowSystemMenuHint | Qt::WindowMinimizeButtonHint | Qt::WindowMaximizeButtonHint | Qt::WindowCloseButtonHint;

  1113 

  1114 

  1115 }

  1116 

  1117 void QWidgetPrivate::init(QWidget *parentWidget, Qt::WindowFlags f)

  1118 {

  1119     Q_Q(QWidget);

  1120     if (QApplication::type() == QApplication::Tty)

  1121         qFatal("QWidget: Cannot create a QWidget when no GUI is being used");

  1122 

  1123     Q_ASSERT(allWidgets);

  1124     allWidgets->insert(q);

  1125 

  1126     QWidget *desktopWidget = 0;

  1127     if (parentWidget && parentWidget->windowType() == Qt::Desktop) {

  1128         desktopWidget = parentWidget;

  1129         parentWidget = 0;

  1130     }

  1131 

  1132     q->data = &data;

  1133 

  1134 #ifndef QT_NO_THREAD

  1135     if (!parent) {