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

     2 **

     3 ** Copyright (C) 2009 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 // widget/widget data creation count

   122 //#define QWIDGET_EXTRA_DEBUG

   123 //#define ALIEN_DEBUG

   124 

   125 QT_BEGIN_NAMESPACE

   126 

   127 #if !defined(Q_WS_QWS)

   128 static bool qt_enable_backingstore = true;

   129 #endif

   130 #ifdef Q_WS_X11

   131 // for compatibility with Qt 4.0

   132 Q_GUI_EXPORT void qt_x11_set_global_double_buffer(bool enable)

   133 {

   134     qt_enable_backingstore = enable;

   135 }

   136 #endif

   137 

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

   139 {

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

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

   142 }

   143 

   144 static inline bool hasBackingStoreSupport()

   145 {

   146 #ifdef Q_WS_MAC

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

   148 #else

   149     return true;

   150 #endif

   151 }

   152 

   153 #ifdef Q_WS_MAC

   154 #  define QT_NO_PAINT_DEBUG

   155 #endif

   156 

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

   158 extern QDesktopWidget *qt_desktopWidget; // qapplication.cpp

   159 

   160 QWidgetPrivate::QWidgetPrivate(int version)

   161     : QObjectPrivate(version)

   162       , extra(0)

   163       , focus_next(0)

   164       , focus_prev(0)

   165       , focus_child(0)

   166       , layout(0)

   167       , needsFlush(0)

   168       , redirectDev(0)

   169       , widgetItem(0)

   170       , extraPaintEngine(0)

   171       , polished(0)

   172       , graphicsEffect(0)

   173 #if !defined(QT_NO_IM)

   174       , imHints(Qt::ImhNone)

   175 #endif

   176       , inheritedFontResolveMask(0)

   177       , inheritedPaletteResolveMask(0)

   178       , leftmargin(0)

   179       , topmargin(0)

   180       , rightmargin(0)

   181       , bottommargin(0)

   182       , leftLayoutItemMargin(0)

   183       , topLayoutItemMargin(0)

   184       , rightLayoutItemMargin(0)

   185       , bottomLayoutItemMargin(0)

   186       , hd(0)

   187       , size_policy(QSizePolicy::Preferred, QSizePolicy::Preferred)

   188       , fg_role(QPalette::NoRole)

   189       , bg_role(QPalette::NoRole)

   190       , dirtyOpaqueChildren(1)

   191       , isOpaque(0)

   192       , inDirtyList(0)

   193       , isScrolled(0)

   194       , isMoved(0)

   195       , usesDoubleBufferedGLContext(0)

   196 #if defined(Q_WS_X11)

   197       , picture(0)

   198 #elif defined(Q_WS_WIN)

   199       , noPaintOnScreen(0)

   200 #elif defined(Q_WS_MAC)

   201       , needWindowChange(0)

   202       , isGLWidget(0)

   203       , window_event(0)

   204       , qd_hd(0)

   205 #endif

   206 {

   207     if (!qApp) {

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

   209         return;

   210     }

   211 

   212     if (version != QObjectPrivateVersion)

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

   214 

   215     isWidget = true;

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

   217 #ifdef QWIDGET_EXTRA_DEBUG

   218     static int count = 0;

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

   220 #endif

   221 }

   222 

   223 

   224 QWidgetPrivate::~QWidgetPrivate()

   225 {

   226     if (widgetItem)

   227         widgetItem->wid = 0;

   228 

   229     if (extra)

   230         deleteExtra();

   231 

   232     delete graphicsEffect;

   233 }

   234 

   235 QWindowSurface *QWidgetPrivate::createDefaultWindowSurface()

   236 {

   237     Q_Q(QWidget);

   238     if (QApplicationPrivate::graphicsSystem())

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

   240     return createDefaultWindowSurface_sys();

   241 }

   242 

   243 /*!

   244     \internal

   245 */

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

   247 {

   248     Q_Q(QWidget);

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

   250         QPoint pd(dx, dy);

   251         QObjectList childObjects = q->children();

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

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

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

   255                 QPoint oldp = w->pos();

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

   257                 w->data->crect = r;

   258 #ifndef Q_WS_QWS

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

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

   261 #endif

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

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

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

   265             }

   266         }

   267     }

   268 }

   269 

   270 QInputContext *QWidgetPrivate::inputContext() const

   271 {

   272 #ifndef QT_NO_IM

   273     if (ic)

   274         return ic;

   275 #endif

   276     return qApp->inputContext();

   277 }

   278 

   279 /*!

   280     This function returns the QInputContext for this widget. By

   281     default the input context is inherited from the widgets

   282     parent. For toplevels it is inherited from QApplication.

   283 

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

   285     widget by using the setInputContext() method.

   286 

   287     \sa setInputContext()

   288 */

   289 QInputContext *QWidget::inputContext()

   290 {

   291     Q_D(QWidget);

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

   293         return 0;

   294 

   295     return d->inputContext();

   296 }

   297 

   298 /*!

   299   This function sets the input context \a context

   300   on this widget.

   301 

   302   \sa inputContext()

   303 */

   304 void QWidget::setInputContext(QInputContext *context)

   305 {

   306     Q_D(QWidget);

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

   308         return;

   309 #ifndef QT_NO_IM

   310     if (d->ic)

   311         delete d->ic;

   312     d->ic = context;

   313 #endif

   314 }

   315 

   316 

   317 /*!

   318     \obsolete

   319 

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

   321     to reset the input method operating on it.

   322 

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

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

   325     returned by inputContext().

   326 

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

   328 */

   329 void QWidget::resetInputContext()

   330 {

   331     if (!hasFocus())

   332         return;

   333 #ifndef QT_NO_IM

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

   335     if(qic)

   336         qic->reset();

   337 #endif // QT_NO_IM

   338 }

   339 

   340 #ifdef QT_KEYPAD_NAVIGATION

   341 QPointer<QWidget> QWidgetPrivate::editingWidget;

   342 

   343 /*!

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

   345 

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

   347 

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

   349 */

   350 bool QWidget::hasEditFocus() const

   351 {

   352     const QWidget* w = this;

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

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

   355     return QWidgetPrivate::editingWidget == w;

   356 }

   357 

   358 /*!

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

   360 

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

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

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

   364     change focus.

   365 

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

   367 

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

   369 */

   370 void QWidget::setEditFocus(bool on)

   371 {

   372     QWidget *f = this;

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

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

   375 

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

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

   378 

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

   380         f->setFocus();

   381 

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

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

   384         return;

   385     }

   386 

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

   388         QWidgetPrivate::editingWidget = 0;

   389         QEvent event(QEvent::LeaveEditFocus);

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

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

   392     } else if (on) {

   393         QWidgetPrivate::editingWidget = f;

   394         QEvent event(QEvent::EnterEditFocus);

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

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

   397     }

   398 }

   399 #endif

   400 

   401 /*!

   402     \property QWidget::autoFillBackground

   403     \brief whether the widget background is filled automatically

   404     \since 4.1

   405 

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

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

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

   409 

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

   411     WA_OpaquePaintEvent or WA_NoSystemBackground attributes are set.

   412 

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

   414     parent has a static gradient for its background.

   415 

   416     \warning Use this property with caution in conjunction with

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

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

   419 

   420     By default, this property is false.

   421 

   422     \sa Qt::WA_OpaquePaintEvent, Qt::WA_NoSystemBackground,

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

   424 */

   425 bool QWidget::autoFillBackground() const

   426 {

   427     Q_D(const QWidget);

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

   429 }

   430 

   431 void QWidget::setAutoFillBackground(bool enabled)

   432 {

   433     Q_D(QWidget);

   434     if (!d->extra)

   435         d->createExtra();

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

   437         return;

   438 

   439     d->extra->autoFillBackground = enabled;

   440     d->updateIsOpaque();

   441     update();

   442     d->updateIsOpaque();

   443 }

   444 

   445 /*!

   446     \class QWidget

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

   448 

   449     \ingroup basicwidgets

   450 

   451 

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

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

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

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

   456     it.

   457 

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

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

   460     to create windows without such decoration using suitable

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

   462     subclasses of QDialog are the most common window types.

   463 

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

   465 

   466     \list 1

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

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

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

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

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

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

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

   474             special flags.

   475     \endlist

   476 

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

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

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

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

   481 

   482 

   483     \section1 Top-Level and Child Widgets

   484 

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

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

   487     title bar and icon respectively.

   488 

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

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

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

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

   493 

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

   495 

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

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

   498     been outlined to indicate their full sizes.

   499 

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

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

   502     information.

   503 

   504 

   505     \section1 Composite Widgets

   506 

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

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

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

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

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

   512 

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

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

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

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

   517     the Qt \l{Tutorials}.

   518 

   519 

   520     \section1 Custom Widgets and Painting

   521 

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

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

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

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

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

   527     application and are rendered by the framework itself.

   528 

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

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

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

   532 

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

   534     can handle paint events.

   535 

   536 

   537     \section1 Size Hints and Size Policies

   538 

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

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

   541     the correct size policy with setSizePolicy().

   542 

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

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

   545 

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

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

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

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

   550     widgets.

   551 

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

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

   554     inadequate.

   555 

   556 

   557     \section1 Events

   558 

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

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

   561     instances of QEvent subclasses containing information about each event.

   562 

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

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

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

   566     mousePressEvent().

   567 

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

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

   570 

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

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

   573     starting with the most common ones:

   574 

   575     \list

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

   577             Every widget displaying custom content must implement it. Painting

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

   579             function called by a paintEvent().

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

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

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

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

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

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

   586             widget receives mouse release events when it has received the

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

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

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

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

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

   592             steals the mouse events.

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

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

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

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

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

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

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

   600             books recommend that double-clicks be an extension of

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

   602     \endlist

   603 

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

   605     handlers:

   606 

   607     \list

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

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

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

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

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

   613             QWidget::event().

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

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

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

   617             way.

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

   619     \endlist

   620 

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

   622     handlers:

   623 

   624     \list

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

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

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

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

   629             and Drop} guide.)

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

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

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

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

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

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

   636             reimplement QWidget::event().

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

   638             while the widget has the focus.

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

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

   641             children.)

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

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

   644             leaveEvent().

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

   646             its parent.

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

   648             close() is called).

   649     \endlist

   650 

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

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

   653     directly.

   654 

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

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

   657     one of the more specialized handlers above.

   658 

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

   660     \l{Events and Event Filters} document.

   661 

   662     \section1 Groups of Functions and Properties

   663 

   664     \table

   665     \header \i Context \i Functions and Properties

   666 

   667     \row \i Window functions \i

   668         show(),

   669         hide(),

   670         raise(),

   671         lower(),

   672         close().

   673 

   674     \row \i Top-level windows \i

   675         \l windowModified, \l windowTitle, \l windowIcon, \l windowIconText,

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

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

   678         showNormal().

   679 

   680     \row \i Window contents \i

   681         update(),

   682         repaint(),

   683         scroll().

   684 

   685     \row \i Geometry \i

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

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

   688         updateGeometry(), layout(),

   689         \l frameGeometry, \l geometry, \l childrenRect, \l childrenRegion,

   690         adjustSize(),

   691         mapFromGlobal(), mapToGlobal(),

   692         mapFromParent(), mapToParent(),

   693         \l maximumSize, \l minimumSize, \l sizeIncrement,

   694         \l baseSize, setFixedSize()

   695 

   696     \row \i Mode \i

   697         \l visible, isVisibleTo(),

   698         \l enabled, isEnabledTo(),

   699         \l modal,

   700         isWindow(),

   701         \l mouseTracking,

   702         \l updatesEnabled,

   703         visibleRegion().

   704 

   705     \row \i Look and feel \i

   706         style(),

   707         setStyle(),

   708         \l styleSheet,

   709         \l cursor,

   710         \l font,

   711         \l palette,

   712         backgroundRole(), setBackgroundRole(),

   713         fontInfo(), fontMetrics().

   714 

   715     \row \i Keyboard focus functions \i

   716         \l focus, \l focusPolicy,

   717         setFocus(), clearFocus(), setTabOrder(), setFocusProxy(),

   718         focusNextChild(), focusPreviousChild().

   719 

   720     \row \i Mouse and keyboard grabbing \i

   721         grabMouse(), releaseMouse(),

   722         grabKeyboard(), releaseKeyboard(),

   723         mouseGrabber(), keyboardGrabber().

   724 

   725     \row \i Event handlers \i

   726         event(),

   727         mousePressEvent(),

   728         mouseReleaseEvent(),

   729         mouseDoubleClickEvent(),

   730         mouseMoveEvent(),

   731         keyPressEvent(),

   732         keyReleaseEvent(),

   733         focusInEvent(),

   734         focusOutEvent(),

   735         wheelEvent(),

   736         enterEvent(),

   737         leaveEvent(),

   738         paintEvent(),

   739         moveEvent(),

   740         resizeEvent(),

   741         closeEvent(),

   742         dragEnterEvent(),

   743         dragMoveEvent(),

   744         dragLeaveEvent(),

   745         dropEvent(),

   746         childEvent(),

   747         showEvent(),

   748         hideEvent(),

   749         customEvent().

   750         changeEvent(),

   751 

   752     \row \i System functions \i

   753         parentWidget(), window(), setParent(), winId(),

   754         find(), metric().

   755 

   756     \row \i Interactive help \i

   757         setToolTip(), setWhatsThis()

   758 

   759     \endtable

   760 

   761 

   762     \section1 Widget Style Sheets

   763 

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

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

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

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

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

   769     performs a destructive action.

   770 

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

   772     \l{Qt Style Sheets} document.

   773 

   774 

   775     \section1 Transparency and Double Buffering

   776 

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

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

   779     flicker.

   780 

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

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

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

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

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

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

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

   788     can be fine-tuned to achieve different effects.

   789 

   790     \image propagation-custom.png

   791 

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

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

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

   795     achieve different effects:

   796 

   797     \list

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

   799             set. This default state suits most custom widgets using

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

   801             entire area with an opaque brush.

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

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

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

   805             area with an opaque brush.

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

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

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

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

   810             grid pattern that shines through the overpainted area. The

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

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

   813             default filled background.

   814     \endlist

   815 

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

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

   818     background color (using setBackgroundRole() with the

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

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

   821 

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

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

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

   825     associated with repainting the widget's background.

   826 

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

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

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

   830     choose either one of them.

   831 

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

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

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

   835     below.

   836 

   837     \image propagation-standard.png

   838 

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

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

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

   842     achieved by setting its \l autoFillBackground property.

   843 

   844 

   845     \section1 Creating Translucent Windows

   846 

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

   848     on window systems that support compositing.

   849 

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

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

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

   853 

   854     Platform notes:

   855 

   856     \list

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

   858     and a compositing window manager.

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

   860     for the translucency to work.

   861     \endlist

   862 

   863 

   864     \section1 Native Widgets vs Alien Widgets

   865 

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

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

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

   869 

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

   871     one of the following options:

   872 

   873     \list 1

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

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

   876             widgets will be native widgets.

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

   878             and all of its ancestors will become native (unless

   879             Qt::WA_DontCreateNativeAncestors is set).

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

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

   882             (this implies 3).

   883     \endlist

   884 

   885     \sa QEvent, QPainter, QGridLayout, QBoxLayout

   886 

   887     \section1 Softkeys

   888 

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

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

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

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

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

   894     in that they are contextual.

   895 

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

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

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

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

   900     heirarchy so it is possible to define a single set of softkeys that are

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

   902 

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

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

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

   906 

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

   908 

   909     \sa addAction(), QAction, QMenuBar

   910 

   911 */

   912 

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

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

   915 

   916 

   917 /*****************************************************************************

   918   QWidget utility functions

   919  *****************************************************************************/

   920 

   921 QRegion qt_dirtyRegion(QWidget *widget)

   922 {

   923     if (!widget)

   924         return QRegion();

   925 

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

   927     if (!bs)

   928         return QRegion();

   929 

   930     return bs->dirtyRegion(widget);

   931 }

   932 

   933 /*****************************************************************************

   934   QWidget member functions

   935  *****************************************************************************/

   936 

   937 /*

   938     Widget state flags:

   939   \list

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

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

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

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

   944   implies !Qt::WA_WState_Visible.

   945   \i Qt::WA_WState_CompressKeys Compress keyboard events.

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

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

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

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

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

   951   \endlist

   952 */

   953 

   954 struct QWidgetExceptionCleaner

   955 {

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

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

   958     {

   959 #ifdef QT_NO_EXCEPTIONS

   960         Q_UNUSED(that);

   961         Q_UNUSED(d);

   962 #else

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

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

   965             if (d->focus_next)

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

   967             if (d->focus_prev)

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

   969         }

   970 #endif

   971     }

   972 };

   973 

   974 /*!

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

   976     flags set to \a f.

   977 

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

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

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

   981     deleted.

   982 

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

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

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

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

   987 

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

   989     explicitly show the child to make it visible.

   990 

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

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

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

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

   995     whatever flags you want.

   996 

   997     \sa windowFlags

   998 */

   999 

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

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

  1002 {

  1003     QT_TRY {

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

  1005     } QT_CATCH(...) {

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

  1007         QT_RETHROW;

  1008     }

  1009 }

  1010 

  1011 #ifdef QT3_SUPPORT

  1012 /*!

  1013     \overload

  1014     \obsolete

  1015  */

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

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

  1018 {

  1019     QT_TRY {

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

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

  1022     } QT_CATCH(...) {

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

  1024         QT_RETHROW;

  1025     }

  1026 }

  1027 #endif

  1028 

  1029 /*! \internal

  1030 */

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

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

  1033 {

  1034     Q_D(QWidget);

  1035     QT_TRY {

  1036         d->init(parent, f);

  1037     } QT_CATCH(...) {

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

  1039         QT_RETHROW;

  1040     }

  1041 }

  1042 

  1043 /*!

  1044     \internal

  1045 */

  1046 int QWidget::devType() const

  1047 {

  1048     return QInternal::Widget;

  1049 }

  1050 

  1051 

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

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

  1054 {

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

  1056             | Qt::FramelessWindowHint

  1057             | Qt::WindowTitleHint

  1058             | Qt::WindowSystemMenuHint

  1059             | Qt::WindowMinimizeButtonHint

  1060             | Qt::WindowMaximizeButtonHint

  1061             | Qt::WindowCloseButtonHint

  1062             | Qt::WindowContextHelpButtonHint));

  1063 

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

  1065 

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

  1067         type = Qt::Window;

  1068         flags |= Qt::Window;

  1069     }

  1070 

  1071     if (flags & Qt::CustomizeWindowHint) {

  1072         // modify window flags to make them consistent.

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

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

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

  1076 #ifndef Q_WS_MAC

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

  1078             flags |= Qt::WindowSystemMenuHint;

  1079 #else

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

  1081                      | Qt::WindowSystemMenuHint)) {

  1082 #endif

  1083             flags |= Qt::WindowTitleHint;

  1084             flags &= ~Qt::FramelessWindowHint;

  1085         }

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

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

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

  1089         // and system menu by default.

  1090         flags |= Qt::WindowSystemMenuHint;

  1091         flags |= Qt::WindowTitleHint;

  1092     }

  1093     if (customize)

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

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

  1096 #ifndef Q_WS_WINCE

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

  1098 #else

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

  1100 #endif

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

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

  1103     else

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

  1105 

  1106 

  1107 }

  1108 

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

  1110 {

  1111     Q_Q(QWidget);

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

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

  1114 

  1115     Q_ASSERT(allWidgets);

  1116     allWidgets->insert(q);

  1117 

  1118     QWidget *desktopWidget = 0;

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

  1120         desktopWidget = parentWidget;

  1121         parentWidget = 0;

  1122     }

  1123 

  1124     q->data = &data;

  1125 

  1126 #ifndef QT_NO_THREAD

  1127     if (!parent) {

  1128         Q_ASSERT_X(q->thread() == qApp->thread(), "QWidget",

  1129                    "Widgets must be created in the GUI thread.");

  1130     }

  1131 #endif

  1132 

  1133 #if defined(Q_WS_X11)

  1134     if (desktopWidget) {