From 387db114cf09e60b43b13c36c83ef8cf07ee6553 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Wed, 20 May 2009 11:59:54 +0200 Subject: qdoc: Moved qdoc comments from qmacstyle_mac.mm to qstyles.qdoc The .mm file is not read by qdoc for packages other than for the MAC. This problem is overcome by moving the qdoc comments from the .mm file to a .qdoc file in doc/src, because all these files are read by qdoc for each of the packages. #Task-number: 252566 --- .commit-template | 14 +-- doc/src/qstyles.qdoc | 261 ++++++++++++++++++++++++++++++++++++++++ src/gui/styles/qmacstyle_mac.mm | 158 +----------------------- 3 files changed, 273 insertions(+), 160 deletions(-) create mode 100644 doc/src/qstyles.qdoc diff --git a/.commit-template b/.commit-template index 589ca89..171b67b 100644 --- a/.commit-template +++ b/.commit-template @@ -1,10 +1,8 @@ -# ===[ Subject ]==========[ one line, please wrap at 72 characters ]===| +qdoc: Moved qdoc comments from qmacstyle_mac.mm to qstyles.qdoc -# ---[ Details ]---------[ remember extra blank line after subject ]---| +The .mm file is not read by qdoc for packages other than for the MAC. +This problem is overcome by moving the qdoc comments from the .mm file +to a .qdoc file in doc/src, because all these files are read by qdoc +for each of the packages. -# ---[ Fields ]-----------------[ uncomment and edit as applicable ]---| - -#Task-number: -#Reviewed-by: - -# ==================================[ please wrap at 72 characters ]===| +#Task-number: 252566 diff --git a/doc/src/qstyles.qdoc b/doc/src/qstyles.qdoc new file mode 100644 index 0000000..e17097a --- /dev/null +++ b/doc/src/qstyles.qdoc @@ -0,0 +1,261 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +/*! + \class QMacStyle + \brief The QMacStyle class provides a Mac OS X style using the Apple Appearance Manager. + + \ingroup appearance + + This class is implemented as a wrapper to the HITheme + APIs, allowing applications to be styled according to the current + theme in use on Mac OS X. This is done by having primitives + in QStyle implemented in terms of what Mac OS X would normally theme. + + \warning This style is only available on Mac OS X because it relies on the + HITheme APIs. + + There are additional issues that should be taken + into consideration to make an application compatible with the + \link http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html + Apple Human Interface Guidelines \endlink. Some of these issues are outlined + below. + + \list + + \i Layout - The restrictions on window layout are such that some + aspects of layout that are style-dependent cannot be achieved + using QLayout. Changes are being considered (and feedback would be + appreciated) to make layouts QStyle-able. Some of the restrictions + involve horizontal and vertical widget alignment and widget size + (covered below). + + \i Widget size - Mac OS X allows widgets to have specific fixed sizes. Qt + does not fully implement this behavior so as to maintain cross-platform + compatibility. As a result some widgets sizes may be inappropriate (and + subsequently not rendered correctly by the HITheme APIs).The + QWidget::sizeHint() will return the appropriate size for many + managed widgets (widgets enumerated in \l QStyle::ContentsType). + + \i Effects - QMacStyle uses HITheme for performing most of the drawing, but + also uses emulation in a few cases where HITheme does not provide the + required functionality (for example, tab bars on Panther, the toolbar + separator, etc). We tried to make the emulation as close to the original as + possible. Please report any issues you see in effects or non-standard + widgets. + + \endlist + + There are other issues that need to be considered in the feel of + your application (including the general color scheme to match the + Aqua colors). The Guidelines mentioned above will remain current + with new advances and design suggestions for Mac OS X. + + Note that the functions provided by QMacStyle are + reimplementations of QStyle functions; see QStyle for their + documentation. + + \img qmacstyle.png + \sa QWindowsXPStyle, QWindowsStyle, QPlastiqueStyle, QCDEStyle, QMotifStyle +*/ + + +/*! + \enum QMacStyle::WidgetSizePolicy + + \value SizeSmall + \value SizeLarge + \value SizeMini + \value SizeDefault + \omitvalue SizeNone +*/ + +/*! \fn QMacStyle::QMacStyle() + Constructs a QMacStyle object. +*/ + +/*! \fn QMacStyle::~QMacStyle() + Destructs a QMacStyle object. +*/ + +/*! \fn void QMacStyle::polish(QPalette &pal) + \reimp +*/ + +/*! \fn void QMacStyle::polish(QApplication *) + \reimp +*/ + +/*! \fn void QMacStyle::unpolish(QApplication *) + \reimp +*/ + +/*! \fn void QMacStyle::polish(QWidget* w) + \reimp +*/ + +/*! \fn void QMacStyle::unpolish(QWidget* w) + \reimp +*/ + +/*! \fn int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QWidget *widget) const + \reimp +*/ + +/*! \fn QPalette QMacStyle::standardPalette() const + \reimp +*/ + +/*! \fn int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *hret) const + \reimp +*/ + +/*! \fn QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *opt) const + \reimp +*/ + +/*! \fn QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt, const QWidget *widget) const + \reimp +*/ + +/*! + \enum QMacStyle::FocusRectPolicy + + This type is used to signify a widget's focus rectangle policy. + + \value FocusEnabled show a focus rectangle when the widget has focus. + \value FocusDisabled never show a focus rectangle for the widget. + \value FocusDefault show a focus rectangle when the widget has + focus and the widget is a QSpinWidget, QDateTimeEdit, QLineEdit, + QListBox, QListView, editable QTextEdit, or one of their + subclasses. +*/ + +/*! \fn void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) + \obsolete + Sets the focus rectangle policy of \a w. The \a policy can be one of + \l{QMacStyle::FocusRectPolicy}. + + This is now simply an interface to the Qt::WA_MacShowFocusRect attribute and the + FocusDefault value does nothing anymore. If you want to set a widget back + to its default value, you must save the old value of the attribute before + you change it. + + \sa focusRectPolicy() QWidget::setAttribute() +*/ + +/*! \fn QMacStyle::FocusRectPolicy QMacStyle::focusRectPolicy(const QWidget *w) + \obsolete + Returns the focus rectangle policy for the widget \a w. + + The focus rectangle policy can be one of \l{QMacStyle::FocusRectPolicy}. + + In 4.3 and up this function will simply test for the + Qt::WA_MacShowFocusRect attribute and will never return + QMacStyle::FocusDefault. + + \sa setFocusRectPolicy(), QWidget::testAttribute() +*/ + +/*! \fn void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy policy) + + \obsolete + + Call QWidget::setAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, + or Qt::WA_MacNormalSize instead. +*/ + +/*! \fn QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) + \obsolete + + Call QWidget::testAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, + or Qt::WA_MacNormalSize instead. +*/ + +/*! \fn void QMacStyle::drawPrimitive(PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w) const + + \reimp +*/ + +/*! \fn void QMacStyle::drawControl(ControlElement ce, const QStyleOption *opt, QPainter *p, const QWidget *w) const + + \reimp +*/ + +/*! \fn QRect QMacStyle::subElementRect(SubElement sr, const QStyleOption *opt, const QWidget *widget) const + + \reimp +*/ + +/*! \fn void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const + \reimp +*/ + +/*! \fn QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const + \reimp +*/ + +/*! \fn QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *opt, SubControl sc, const QWidget *widget) const + \reimp +*/ + +/*! \fn QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, const QSize &csz, const QWidget *widget) const + \reimp +*/ + +/*! \fn void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPalette &pal, bool enabled, const QString &text, QPalette::ColorRole textRole) const + \reimp +*/ + +/*! \fn bool QMacStyle::event(QEvent *e) + \reimp +*/ + +/*! \fn QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const QStyleOption *opt, const QWidget *widget) const + \internal +*/ + +/*! \fn int QMacStyle::layoutSpacingImplementation(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, const QStyleOption *option, const QWidget *widget) const + + \internal +*/ + diff --git a/src/gui/styles/qmacstyle_mac.mm b/src/gui/styles/qmacstyle_mac.mm index 7a870fe..2e47526 100644 --- a/src/gui/styles/qmacstyle_mac.mm +++ b/src/gui/styles/qmacstyle_mac.mm @@ -39,6 +39,11 @@ ** ****************************************************************************/ +/*! + Note: The qdoc comments for QMacStyle are contained in + .../doc/src/qstyles.qdoc. +*/ + #include "qmacstyle_mac.h" #if defined(Q_WS_MAC) && !defined(QT_NO_STYLE_MAC) @@ -1988,87 +1993,12 @@ void QMacStylePrivate::drawColorlessButton(const HIRect &macRect, HIThemeButtonD p->drawPixmap(int(macRect.origin.x), int(macRect.origin.y) + finalyoff, width, height, pm); } -/*! - \class QMacStyle - \brief The QMacStyle class provides a Mac OS X style using the Apple Appearance Manager. - - \ingroup appearance - - This class is implemented as a wrapper to the HITheme - APIs, allowing applications to be styled according to the current - theme in use on Mac OS X. This is done by having primitives - in QStyle implemented in terms of what Mac OS X would normally theme. - - \warning This style is only available on Mac OS X because it relies on the - HITheme APIs. - - There are additional issues that should be taken - into consideration to make an application compatible with the - \link http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html - Apple Human Interface Guidelines \endlink. Some of these issues are outlined - below. - - \list - - \i Layout - The restrictions on window layout are such that some - aspects of layout that are style-dependent cannot be achieved - using QLayout. Changes are being considered (and feedback would be - appreciated) to make layouts QStyle-able. Some of the restrictions - involve horizontal and vertical widget alignment and widget size - (covered below). - - \i Widget size - Mac OS X allows widgets to have specific fixed sizes. Qt - does not fully implement this behavior so as to maintain cross-platform - compatibility. As a result some widgets sizes may be inappropriate (and - subsequently not rendered correctly by the HITheme APIs).The - QWidget::sizeHint() will return the appropriate size for many - managed widgets (widgets enumerated in \l QStyle::ContentsType). - - \i Effects - QMacStyle uses HITheme for performing most of the drawing, but - also uses emulation in a few cases where HITheme does not provide the - required functionality (for example, tab bars on Panther, the toolbar - separator, etc). We tried to make the emulation as close to the original as - possible. Please report any issues you see in effects or non-standard - widgets. - - \endlist - - There are other issues that need to be considered in the feel of - your application (including the general color scheme to match the - Aqua colors). The Guidelines mentioned above will remain current - with new advances and design suggestions for Mac OS X. - - Note that the functions provided by QMacStyle are - reimplementations of QStyle functions; see QStyle for their - documentation. - - \img qmacstyle.png - \sa QWindowsXPStyle, QWindowsStyle, QPlastiqueStyle, QCDEStyle, QMotifStyle -*/ - - -/*! - \enum QMacStyle::WidgetSizePolicy - - \value SizeSmall - \value SizeLarge - \value SizeMini - \value SizeDefault - \omitvalue SizeNone -*/ - -/*! - Constructs a QMacStyle object. -*/ QMacStyle::QMacStyle() : QWindowsStyle() { d = new QMacStylePrivate(this); } -/*! - Destructs a QMacStyle object. -*/ QMacStyle::~QMacStyle() { delete qt_mac_backgroundPattern; @@ -2142,7 +2072,6 @@ void qt_mac_fill_background(QPainter *painter, const QRegion &rgn, const QPoint } } -/*! \reimp */ void QMacStyle::polish(QPalette &pal) { if (!qt_mac_backgroundPattern) { @@ -2166,17 +2095,14 @@ void QMacStyle::polish(QPalette &pal) } } -/*! \reimp */ void QMacStyle::polish(QApplication *) { } -/*! \reimp */ void QMacStyle::unpolish(QApplication *) { } -/*! \reimp */ void QMacStyle::polish(QWidget* w) { d->addWidget(w); @@ -2240,7 +2166,6 @@ void QMacStyle::polish(QWidget* w) } } -/*! \reimp */ void QMacStyle::unpolish(QWidget* w) { d->removeWidget(w); @@ -2271,7 +2196,6 @@ void QMacStyle::unpolish(QWidget* w) QWindowsStyle::unpolish(w); } -/*! \reimp */ int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QWidget *widget) const { int controlSize = getControlSize(opt, widget); @@ -2650,7 +2574,6 @@ int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QW return ret; } -/*! \reimp */ QPalette QMacStyle::standardPalette() const { QPalette pal = QWindowsStyle::standardPalette(); @@ -2660,7 +2583,6 @@ QPalette QMacStyle::standardPalette() const return pal; } -/*! \reimp */ int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *hret) const { @@ -2955,7 +2877,6 @@ int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w return ret; } -/*! \reimp */ QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *opt) const { @@ -2981,7 +2902,6 @@ QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixm } -/*! \reimp */ QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt, const QWidget *widget) const { @@ -3012,31 +2932,7 @@ QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOpt } return icon.pixmap(size, size); } -/*! - \enum QMacStyle::FocusRectPolicy - - This type is used to signify a widget's focus rectangle policy. - - \value FocusEnabled show a focus rectangle when the widget has focus. - \value FocusDisabled never show a focus rectangle for the widget. - \value FocusDefault show a focus rectangle when the widget has - focus and the widget is a QSpinWidget, QDateTimeEdit, QLineEdit, - QListBox, QListView, editable QTextEdit, or one of their - subclasses. -*/ - -/*! - \obsolete - Sets the focus rectangle policy of \a w. The \a policy can be one of - \l{QMacStyle::FocusRectPolicy}. - - This is now simply an interface to the Qt::WA_MacShowFocusRect attribute and the - FocusDefault value does nothing anymore. If you want to set a widget back - to its default value, you must save the old value of the attribute before - you change it. - \sa focusRectPolicy() QWidget::setAttribute() -*/ void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) { switch (policy) { @@ -3049,29 +2945,11 @@ void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) } } -/*! - \obsolete - Returns the focus rectangle policy for the widget \a w. - - The focus rectangle policy can be one of \l{QMacStyle::FocusRectPolicy}. - - In 4.3 and up this function will simply test for the - Qt::WA_MacShowFocusRect attribute and will never return - QMacStyle::FocusDefault. - - \sa setFocusRectPolicy(), QWidget::testAttribute() -*/ QMacStyle::FocusRectPolicy QMacStyle::focusRectPolicy(const QWidget *w) { return w->testAttribute(Qt::WA_MacShowFocusRect) ? FocusEnabled : FocusDisabled; } -/*! - \obsolete - - Call QWidget::setAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy policy) { QWidget *wadget = const_cast(widget); @@ -3080,12 +2958,6 @@ void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy poli wadget->setAttribute(Qt::WA_MacMiniSize, policy == SizeMini); } -/*! - \obsolete - - Call QWidget::testAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) { while (widget) { @@ -3101,7 +2973,6 @@ QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) return SizeDefault; } -/*! \reimp */ void QMacStyle::drawPrimitive(PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w) const { @@ -3534,7 +3405,6 @@ static inline QPixmap darkenPixmap(const QPixmap &pixmap) -/*! \reimp */ void QMacStyle::drawControl(ControlElement ce, const QStyleOption *opt, QPainter *p, const QWidget *w) const { @@ -4558,7 +4428,7 @@ static void setLayoutItemMargins(int left, int top, int right, int bottom, QRect rect->adjust(left, top, right, bottom); } } -/*! \reimp */ + QRect QMacStyle::subElementRect(SubElement sr, const QStyleOption *opt, const QWidget *widget) const { @@ -4852,7 +4722,6 @@ static inline void drawToolbarButtonArrow(const QRect &toolButtonRect, ThemeDraw HIThemeDrawPopupArrow(&hirect, &padi, cg, kHIThemeOrientationNormal); } -/*! \reimp */ void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const { @@ -5349,7 +5218,6 @@ void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex } } -/*! \reimp */ QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const @@ -5480,7 +5348,6 @@ QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, return sc; } -/*! \reimp */ QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *opt, SubControl sc, const QWidget *widget) const { @@ -5820,7 +5687,6 @@ QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *op return ret; } -/*! \reimp */ QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, const QSize &csz, const QWidget *widget) const { @@ -6107,9 +5973,6 @@ QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, return sz; } -/*! - \reimp -*/ void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPalette &pal, bool enabled, const QString &text, QPalette::ColorRole textRole) const { @@ -6118,9 +5981,6 @@ void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPale QWindowsStyle::drawItemText(p, r, flags, pal, enabled, text, textRole); } -/*! - \reimp -*/ bool QMacStyle::event(QEvent *e) { if(e->type() == QEvent::FocusIn) { @@ -6195,9 +6055,6 @@ void qt_mac_constructQIconFromIconRef(const IconRef icon, const IconRef overlayI } } -/*! - \internal -*/ QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const QStyleOption *opt, const QWidget *widget) const { @@ -6311,9 +6168,6 @@ QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const Q return QWindowsStyle::standardIconImplementation(standardIcon, opt, widget); } -/*! - \internal -*/ int QMacStyle::layoutSpacingImplementation(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, -- cgit v0.12