qwidget.cpp

奇趣公司比较新的qt/emd版本

    their parent widgets. Most widgets in Qt are mainly useful as child
    widgets. For example, it is possible to display a button as a
    top-level window, but most people prefer to put their buttons
    inside other widgets, such as QDialog.

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

    The above diagram shows a QGroupBox widget being used to hold various child
    widgets in a layout provided by QGridLayout. The QLabel child widgets have
    been outlined to indicate their full sizes.

    If you want to use a QWidget to hold child widgets you will
    usually want to add a layout to the parent QWidget. See
    \l{Layout Classes} for more information about these.

    \section1 Composite Widgets

    When a widgets is used as a container to group a number of child widgets,
    it is known as a composite widget. These can be created by constructing
    a widget with the required visual properties - a QFrame, for example - and
    adding child widgets to it, usually managed by a layout. The above diagram
    shows such a composite widget that was created using \l{Qt Designer}.

    Composite widgets can also be created by subclassing a standard widget,
    such as QWidget or QFrame, and adding the necessary layout and child widgets
    in the constructor of the subclass. Many of the
    \l{Qt Examples}{examples provided with Qt} use this approach, and it is
    also covered in the \l{Qt Tutorial}.

    \section1 Custom Widgets and Painting

    Since QWidget is a subclass of QPaintDevice, subclasses can be used to
    display custom content that is composed using a series of painting
    operations with an instance of the QPainter class. This approach
    contrasts with the canvas-style approach used by the
    \l{Graphics View}{Graphics View Framework} where items are added to a
    scene by the application and are rendered by the framework itself.

    Each widget performs all painting operations from within its
    paintEvent() function. This is called whenever the widget needs to be
    redrawn, either as a result of some external change or when requested
    by the application.

    The \l{widgets/analogclock}{Analog Clock example} shows how a simple
    widget can handle paint events.

    \section1 Size Hints and Size Policies

    When implementing a new widget, it is almost always useful to
    reimplement sizeHint() to provide a reasonable default size for the
    widget and to set the correct size policy with setSizePolicy().

    By default, composite widgets which do not provide a size hint will
    be sized according to the space requirements of their child widgets.

    The size policy lets you supply good default behavior for the layout
    management system, so that other widgets can contain and manage
    yours easily. The default size policy indicates that the size hint
    represents the preferred size of the widget, and this is often good
    enough for many widgets.

    \section1 Events

    Widgets respond to events that are typically caused by user actions.
    Qt delivers events to widgets by calling specific event handler functions
    with instances of QEvent subclasses containing information about each
    event.

    If your widget only contains child widgets, you probably do not need to
    implement any event handlers. If you want to detect a mouse click in
    a child widget call the child's underMouse() function inside the
    widget's mousePressEvent().

    The \l{widgets/scribble}{Scribble example} implements
    a wider set of events to handle mouse movement, button presses, and
    window resizing.

    You will need to supply the behavior and content for your own widgets,
    but here is a brief overview of the events that are relevant to
    QWidget, starting with the most common ones:

    \list

    \i paintEvent() is called whenever the widget needs to be
    repainted. Every widget which displays custom content must implement
    it. Painting using a QPainter can only take place in a paintEvent()
    or a function called by a paintEvent().

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

    \i mousePressEvent() is called when a mouse button is pressed when
    the mouse is inside it, or when it has grabbed the mouse using
    grabMouse().

    \i mouseReleaseEvent() is called when a mouse button is released.
    A widget receives mouse release events when it has received the
    corresponding mouse press event. This means that if the user
    presses the mouse inside \e your widget, then drags the mouse to
    somewhere else before releasing the mouse button, \e your widget
    receives the release event. There is one exception: if a popup
    menu appears while the mouse button is held down, this popup
    immediately steals the mouse events.

    \i mouseDoubleClickEvent() is called when the user double clicks
    in the widget. If the user double-clicks, the widget receives a
    mouse press event, a mouse release event and finally this event
    instead of a second mouse press event.
    (Some mouse move events may also be received if the user doesn't
    hold the mouse steady during this operation.)
    It is \e{not possible} to distinguish a click from a double click
    until the second click arrives. (This is one reason why most GUI
    books recommend that double clicks be an extension of single clicks,
    rather than trigger a different action.)

    \endlist

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

    \list

    \i keyPressEvent() is called whenever a key is pressed, and again
    when a key has been held down long enough for it to auto-repeat.
    Note that the \key Tab and \key Shift+Tab keys are only passed to
    the widget if they are not used by the focus-change mechanisms.
    To force those keys to be processed by your widget, you must
    reimplement QWidget::event().

    \i focusInEvent() is called when the widget gains keyboard focus
    (assuming you have called setFocusPolicy()). Well written widgets
    indicate that they own the keyboard focus in a clear but discreet
    way.

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

    \endlist

    Some widgets will also need to reimplement some of the less common
    event handlers:

    \list

    \i mouseMoveEvent() is called whenever the mouse moves while a
    button is held down. This can be useful during drag and drop
    operations. If you call setMouseTracking(true), you get mouse move
    events even when no buttons are held down. (See also the guide to
    \l{Drag and Drop}.)

    \i keyReleaseEvent() is called whenever a key is released, and also
    while it is held down if the key is auto-repeating. In that case
    the widget receives a pair of key release and key press events
    for every repeat. Note that the \key Tab and \key Shift+Tab keys are
    only passed to the widget if they are not used by the focus-change
    mechanisms. To force those keys to be processed by your widget, you
    must reimplement QWidget::event().

    \i wheelEvent() is called whenever the user turns the mouse wheel
    while the widget has the focus.

    \i enterEvent() is called when the mouse enters the widget's screen
    space. (This excludes screen space owned by any children of the
    widget.)

    \i leaveEvent() is called when the mouse leaves the widget's screen
    space. Note that if the mouse enters a child widget it will not
    cause a leaveEvent.

    \i moveEvent() is called when the widget has been moved relative to its
    parent.

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

    \endlist

    There are also some rather obscure events described in the QEvent::Type
    documentation. You need to reimplement event() directly to handle
    these.
    The default implementation of event() handles \key Tab and \key Shift+Tab
    (to move the keyboard focus), and passes on most other events to
    one of the more specialized handlers above.

    Events and the mechanism used to deliver them are covered in the
    \l{Events and Event Filters} document.

    \section1 Groups of Functions and Properties

    \table
    \header \i Context \i Functions and Properties

    \row \i Window functions \i
        show(),
        hide(),
        raise(),
        lower(),
        close().

    \row \i Top-level windows \i
        \l windowModified, \l windowTitle, \l windowIcon, \l windowIconText,
        \l isActiveWindow, activateWindow(), \l minimized, showMinimized(),
        \l maximized, showMaximized(), \l fullScreen, showFullScreen(),
        showNormal().

    \row \i Window contents \i
        update(),
        repaint(),
        scroll().

    \row \i Geometry \i
        \l pos, x(), y(), \l rect, \l size, width(), height(), move(), resize(),
        \l sizePolicy, sizeHint(), minimumSizeHint(),
        updateGeometry(), layout(),
        \l frameGeometry, \l geometry, \l childrenRect, \l childrenRegion,
        adjustSize(),
        mapFromGlobal(), mapToGlobal(),
        mapFromParent(), mapToParent(),
        \l maximumSize, \l minimumSize, \l sizeIncrement,
        \l baseSize, setFixedSize()

    \row \i Mode \i
        \l visible, isVisibleTo(),
        \l enabled, isEnabledTo(),
        \l modal,
        isWindow(),
        \l mouseTracking,
        \l updatesEnabled,
        visibleRegion().

    \row \i Look and feel \i
        style(),
        setStyle(),
        \l styleSheet,
        \l cursor,
        \l font,
        \l palette,
        backgroundRole(), setBackgroundRole(),
        fontInfo(), fontMetrics().

    \row \i Keyboard focus functions \i
        \l focus, \l focusPolicy,
        setFocus(), clearFocus(), setTabOrder(), setFocusProxy(),
        focusNextChild(), focusPreviousChild().

    \row \i Mouse and keyboard grabbing \i
        grabMouse(), releaseMouse(),
        grabKeyboard(), releaseKeyboard(),
        mouseGrabber(), keyboardGrabber().

    \row \i Event handlers \i
        event(),
        mousePressEvent(),
        mouseReleaseEvent(),
        mouseDoubleClickEvent(),
        mouseMoveEvent(),
        keyPressEvent(),
        keyReleaseEvent(),
        focusInEvent(),
        focusOutEvent(),
        wheelEvent(),
        enterEvent(),
        leaveEvent(),
        paintEvent(),
        moveEvent(),
        resizeEvent(),
        closeEvent(),
        dragEnterEvent(),
        dragMoveEvent(),
        dragLeaveEvent(),
        dropEvent(),
        childEvent(),
        showEvent(),
        hideEvent(),
        customEvent().
        changeEvent(),

    \row \i System functions \i
        parentWidget(), window(), setParent(), winId(),
        find(), metric().

    \row \i Interactive help \i
        setToolTip(), setWhatsThis()

    \endtable

    \section1 Widget Style Sheets

    In addition to the standard widget styles for each platform, widgets can
    also be styled according to rules specified in a \l{styleSheet}{style sheet}.
    This feature enables you to customize the appearance of specific widgets
    to provide visual cues to users about their purpose; for example, a button
    could be styled in a particular way to indicate that it performs a
    destructive action.

    The use of widgets style sheets is described in more detail in
    \l{Qt Style Sheets}.

    \section1 Transparency and Double Buffering

    From Qt 4.0, QWidget automatically double-buffers its painting, so
    there's no need to write double-buffering code in paintEvent() to
    avoid flicker. Additionally, it became possible for widgets to
    propagate their contents to children, in order to enable transparency
    effects, by setting the Qt::WA_ContentsPropagated widget attribute -
    this is now deprecated in Qt 4.1.

    In Qt 4.1, the contents of parent widgets are propagated by default
    to each of their children. Custom widgets can be written to take
    advantage of this feature by only updating irregular regions (to
    create non-rectangular child widgets), or by using painting with
    colors that have less than the full alpha component. The following
    diagram shows how attributes and properties of a custom widget can
    be fine-tuned to achieve different effects.

    \image propagation-custom.png

    In the above diagram, a semi-transparent rectangular child widget with
    an area removed is constructed and added to a parent widget (a QLabel
    showing a pixmap) then different properties and widget attributes are
    set to achieve different effects:

    \list
    \o The left widget has no additional properties or widget attributes
       set. This default state suits most custom widgets that use transparency
       or are irregularly-shaped, and that do not paint over their entire area
       with an opaque brush.
    \o The center widget has the \l autoFillBackground property set.
       This property is used with custom widgets that rely on the widget
       to supply a default background, and do not paint over their entire area
       with an opaque brush.
    \o The right widget has the Qt::WA_OpaquePaintEvent widget attribute
       set. This indicates that the widget will paint over its entire area with
       opaque colors. The widget's area will initially be \e{uninitialized}
       (represented in the diagram by a red diagonal grid pattern that shines
       through the overpainted area). This is useful for widgets that need to
       paint their own specialized contents quickly and that do not need a
       default filled background.
    \endlist

    For rapidly updating custom widgets with simple background colors, such
    as real-time plotting or graphing widgets, it is better to define a
    suitable background color (using setBackgroundRole() with the
    QPalette::Window role), set the \l autoFillBackground property, and only
    implement the necessary drawing functionality in the widget's paintEvent().

    For rapidly updating custom widgets that constantly paint over their entire
    areas with opaque content, such as video streaming widgets, it is
    better to set the widget's Qt::WA_OpaquePaintEvent, avoiding any unnecessary
    overhead associated with repainting the widget's background.

    If a widget has both the Qt::WA_OpaquePaintEvent widget attribute \e{and}
    the \l autoFillBackground property set, the Qt::WA_OpaquePaintEvent
    attribute takes precedence. You should choose just one of these
    depending on your requirements.

    In Qt 4.1, the contents of parent widgets are also propagated to standard
    Qt widgets. This can lead to some unexpected results if the parent widget
    is decorated in a non-standard way, as shown in the diagram below.

    \image propagation-standard.png

    The scope for customizing the painting behavior of standard Qt widgets,
    without resorting to subclassing, is slightly less than that possible for
    custom widgets. Usually, the desired appearance of a standard widget can be
    achieved by setting its \l autoFillBackground property.

    \sa QEvent, QPainter, QGridLayout, QBoxLayout
*/

QWidgetMapper *QWidgetPrivate::mapper = 0;                // widget with wid
QWidgetSet *QWidgetPrivate::uncreatedWidgets = 0;         // widgets with no wid


/*****************************************************************************
  QWidget utility functions
 *****************************************************************************/


static QFont qt_naturalWidgetFont(QWidget* w) {
    QFont naturalfont = QApplication::font(w);
    if (w->parentWidget() && !w->testAttribute(Qt::WA_StyleSheet)
        && (!w->isWindow() || w->testAttribute(Qt::WA_WindowPropagation))) {
        if (!naturalfont.isCopyOf(QApplication::font()))
            naturalfont = naturalfont.resolve(w->parentWidget()->font());
        else
            naturalfont = w->parentWidget()->font();
    }
    naturalfont.resolve(0);
    return naturalfont;
}

static QPalette qt_naturalWidgetPalette(QWidget* w) {
    QPalette naturalpalette = QApplication::palette(w);
    if (w->parentWidget() && !w->testAttribute(Qt::WA_StyleSheet)
        && (!w->isWindow() || w->testAttribute(Qt::WA_WindowPropagation))) {
        if (!naturalpalette.isCopyOf(QApplication::palette()))
            naturalpalette = naturalpalette.resolve(w->parentWidget()->palette());
        else
            naturalpalette = w->parentWidget()->palette();
    }
    naturalpalette.resolve(0);
    return naturalpalette;
}

/*****************************************************************************
  QWidget member functions
 *****************************************************************************/

/*
    Widget state flags:
  \list
  \i Qt::WA_WState_Created The widget has a valid winId().
  \i Qt::WA_WState_Visible The widget is currently visible.
  \i Qt::WA_WState_Hidden The widget is hidden, i.e. it won't
  become visible unless you call show() on it. Qt::WA_WState_Hidden
  implies !Qt::WA_WState_Visible.