From 97b5b8009254004608feefb903cbf44abaa099f6 Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Mon, 7 May 2012 18:49:48 +0200 Subject: Doc: Modularize QtWidgets documentation. This change moves the snippets and images to the modularized directories. Change-Id: Idec1afb9db7ea6add1ca4cf25ec4019d8bce0c4d Reviewed-by: Marius Storm-Olsen --- doc/src/widgets/qtwidgets.qdoc | 45 - doc/src/widgets/widgets-and-layouts/focus.qdoc | 186 - .../widgets/widgets-and-layouts/gallery-cde.qdoc | 133 - .../widgets-and-layouts/gallery-cleanlooks.qdoc | 138 - .../widgets/widgets-and-layouts/gallery-gtk.qdoc | 141 - .../widgets-and-layouts/gallery-macintosh.qdoc | 138 - .../widgets/widgets-and-layouts/gallery-motif.qdoc | 138 - .../widgets-and-layouts/gallery-plastique.qdoc | 138 - .../widgets-and-layouts/gallery-windows.qdoc | 138 - .../widgets-and-layouts/gallery-windowsvista.qdoc | 138 - .../widgets-and-layouts/gallery-windowsxp.qdoc | 138 - doc/src/widgets/widgets-and-layouts/gallery.qdoc | 84 - doc/src/widgets/widgets-and-layouts/layout.qdoc | 396 -- doc/src/widgets/widgets-and-layouts/styles.qdoc | 2102 ----------- .../widgets/widgets-and-layouts/stylesheet.qdoc | 3963 -------------------- doc/src/widgets/widgets-and-layouts/widgets.qdoc | 162 - 16 files changed, 8178 deletions(-) delete mode 100644 doc/src/widgets/qtwidgets.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/focus.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-cde.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-cleanlooks.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-gtk.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-macintosh.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-motif.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-plastique.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-windows.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-windowsvista.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery-windowsxp.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/gallery.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/layout.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/styles.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/stylesheet.qdoc delete mode 100644 doc/src/widgets/widgets-and-layouts/widgets.qdoc (limited to 'doc/src/widgets') diff --git a/doc/src/widgets/qtwidgets.qdoc b/doc/src/widgets/qtwidgets.qdoc deleted file mode 100644 index 4be460a2ab..0000000000 --- a/doc/src/widgets/qtwidgets.qdoc +++ /dev/null @@ -1,45 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtWidgets - \title QtWidgets Module - \ingroup modules - - \brief The QtWidgets module extends QtGui with C++ widget functionality. - - To include the definitions of the module's classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qtwidgets.cpp 1 - - To link against the module, add this line to your \l qmake \c - .pro file: - - \snippet doc/src/snippets/code/doc_src_qtwidgets.pro 0 -*/ - diff --git a/doc/src/widgets/widgets-and-layouts/focus.qdoc b/doc/src/widgets/widgets-and-layouts/focus.qdoc deleted file mode 100644 index 60f05948b4..0000000000 --- a/doc/src/widgets/widgets-and-layouts/focus.qdoc +++ /dev/null @@ -1,186 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page focus.html - \title Keyboard Focus - \brief Keyboard focus management and handling. - \ingroup frameworks-technologies - - \keyword keyboard focus - - Qt's widgets handle keyboard focus in the ways that have become - customary in GUIs. - - The basic issue is that the user's key strokes can be directed at any - of several windows on the screen, and any of several widgets inside - the intended window. When the user presses a key, they expect it to go - to the right place, and the software must try to meet this - expectation. The system must determine which application the key stroke - is directed at, which window within that application, and which widget - within that window. - - \section1 Focus Motion - - The customs which have evolved for directing keyboard focus to a - particular widget are these: - - \list 1 - - \li The user presses \key Tab (or \key Shift+Tab). - \li The user clicks a widget. - \li The user presses a keyboard shortcut. - \li The user uses the mouse wheel. - \li The user moves the focus to a window, and the application must - determine which widget within the window should get the focus. - \endlist - - Each of these motion mechanisms is different, and different types of - widgets receive focus in only some of them. We'll cover each of them - in turn. - - \section2 Tab or Shift+Tab - - Pressing \key Tab is by far the most common way to move focus - using the keyboard. (Sometimes in data-entry applications Enter - does the same as \key{Tab}; this can easily be achieved in Qt by - implementing an \l{The Event System}{event filter}.) - - Pressing \key Tab, in all window systems in common use today, - moves the keyboard focus to the next widget in a circular - per-window list. \key Tab moves focus along the circular list in - one direction, \key Shift+Tab in the other. The order in which - \key Tab presses move from widget to widget is called the tab order. - - You can customize the tab order using QWidget::setTabOrder(). (If - you don't, \key Tab generally moves focus in the order of widget - construction.) \l{Qt Designer} provides a means of visually - changing the tab order. - - Since pressing \key Tab is so common, most widgets that can have focus - should support tab focus. The major exception is widgets that are - rarely used, and where there is some keyboard accelerator or error - handler that moves the focus. - - For example, in a data entry dialog, there might be a field that - is only necessary in one per cent of all cases. In such a dialog, - \key Tab could skip this field, and the dialog could use one of - these mechanisms: - - \list 1 - - \li If the program can determine whether the field is needed, it can - move focus there when the user finishes entry and presses \gui OK, or when - the user presses Enter after finishing the other fields. Alternately, - include the field in the tab order but disable it. Enable it if it - becomes appropriate in view of what the user has set in the other - fields. - - \li The label for the field can include a keyboard shortcut that moves - focus to this field. - - \endlist - - Another exception to \key Tab support is text-entry widgets that - must support the insertion of tabs; almost all text editors fall - into this class. Qt treats \key Ctrl+Tab as \key Tab and \key - Ctrl+Shift+Tab as \key Shift+Tab, and such widgets can - reimplement QWidget::event() and handle Tab before calling - QWidget::event() to get normal processing of all other keys. - However, since some systems use \key Ctrl+Tab for other purposes, - and many users aren't aware of \key Ctrl+Tab anyway, this isn't a - complete solution. - - \section2 The User Clicks a Widget - - This is perhaps even more common than pressing \key Tab on - computers with a mouse or other pointing device. - - Clicking to move the focus is slightly more powerful than \key - Tab. While it moves the focus \e to a widget, for editor widgets - it also moves the text cursor (the widget's internal focus) to - the spot where the mouse is clicked. - - Since it is so common and people are used to it, it's a good idea to - support it for most widgets. However, there is also an important - reason to avoid it: you may not want to remove focus from the widget - where it was. - - For example, in a word processor, when the user clicks the 'B' (bold) - tool button, what should happen to the keyboard focus? Should it - remain where it was, almost certainly in the editing widget, or should - it move to the 'B' button? - - We advise supporting click-to-focus for widgets that support text - entry, and to avoid it for most widgets where a mouse click has a - different effect. (For buttons, we also recommend adding a keyboard - shortcut: QAbstractButton and its subclasses make this very easy.) - - In Qt, only the QWidget::setFocusPolicy() function affects - click-to-focus. - - \section2 The User Presses a Keyboard Shortcut - - It's not unusual for keyboard shortcuts to move the focus. This - can happen implicitly by opening modal dialogs, but also - explicitly using focus accelerators such as those provided by - QLabel::setBuddy(), QGroupBox, and QTabBar. - - We advise supporting shortcut focus for all widgets that the user - may want to jump to. For example, a tab dialog can have keyboard - shortcuts for each of its pages, so the user can press e.g. \key - Alt+P to step to the \underline{P}rinting page. It is easy to - overdo this: there are only a few keys, and it's also important - to provide keyboard shortcuts for commands. \key Alt+P is also - used for Paste, Play, Print, and Print Here in the \l{Standard - Accelerator Keys} list, for example. - - \section2 The User Rotates the Mouse Wheel - - On Microsoft Windows, mouse wheel usage is always handled by the - widget that has keyboard focus. On Mac OS X and X11, it's handled by - the widget that gets other mouse events. - - The way Qt handles this platform difference is by letting widgets move - the keyboard focus when the wheel is used. With the right focus policy - on each widget, applications can work idiomatically correctly on - Windows, Mac OS X, and X11. - - \section2 The User Moves the Focus to This Window - - In this situation the application must determine which widget within - the window should receive the focus. - - This can be simple: If the focus has been in this window before, - then the last widget to have focus should regain it. Qt does this - automatically. - - If focus has never been in this window before and you know where - focus should start out, call QWidget::setFocus() on the widget - which should receive focus before you call QWidget::show() it. If - you don't, Qt will pick a suitable widget. -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-cde.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-cde.qdoc deleted file mode 100644 index a74cab0509..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-cde.qdoc +++ /dev/null @@ -1,133 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-cde.html - - \title CDE Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "cde" style. - -\section2 Buttons - -\table 100% -\row -\li \image cde-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image cde-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\li \image cde-pushbutton.png - \image cde-toolbutton.png - \caption The QPushButton widget provides a command button. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image cde-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image cde-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image cde-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image cde-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image cde-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image cde-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image cde-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image cde-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image cde-label.png - The QLabel widget provides a text or image display. -\li \image cde-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image cde-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image cde-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image cde-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image cde-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image cde-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image cde-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image cde-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image cde-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image cde-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image cde-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image cde-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image cde-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image cde-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable - -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-cleanlooks.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-cleanlooks.qdoc deleted file mode 100644 index bed6d0ca40..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-cleanlooks.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-cleanlooks.html - - \title Cleanlooks Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "cleanlooks" style. - -\section2 Buttons - -\table 100% -\row -\li \image cleanlooks-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image cleanlooks-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image cleanlooks-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image cleanlooks-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image cleanlooks-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image cleanlooks-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image cleanlooks-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image cleanlooks-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image cleanlooks-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image cleanlooks-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image cleanlooks-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image cleanlooks-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image cleanlooks-label.png - The QLabel widget provides a text or image display. -\li \image cleanlooks-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image cleanlooks-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image cleanlooks-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image cleanlooks-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image cleanlooks-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image cleanlooks-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image cleanlooks-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image cleanlooks-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image cleanlooks-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image cleanlooks-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image cleanlooks-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image cleanlooks-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image cleanlooks-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image cleanlooks-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-gtk.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-gtk.qdoc deleted file mode 100644 index 820f0b4140..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-gtk.qdoc +++ /dev/null @@ -1,141 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-gtk.html - - \title GTK Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "gtk" style. - - Take a look at the \l{Qt Widget Gallery} to see how Qt - applications appear in other styles. - -\section2 Buttons - -\table 100% -\row -\li \image gtk-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image gtk-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image gtk-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image gtk-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image gtk-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image gtk-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image gtk-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image gtk-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image gtk-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image gtk-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image gtk-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image gtk-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image gtk-label.png - The QLabel widget provides a text or image display. -\li \image gtk-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image gtk-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image gtk-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image gtk-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image gtk-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image gtk-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image gtk-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image gtk-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image gtk-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image gtk-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image gtk-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image gtk-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image gtk-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image gtk-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-macintosh.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-macintosh.qdoc deleted file mode 100644 index 488a3f7665..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-macintosh.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-macintosh.html - - \title Macintosh Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "macintosh" style. - -\section2 Buttons - -\table 100% -\row -\li \image macintosh-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image macintosh-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image macintosh-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image macintosh-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image macintosh-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image macintosh-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image macintosh-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image macintosh-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image macintosh-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image macintosh-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image macintosh-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image macintosh-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image macintosh-label.png - The QLabel widget provides a text or image display. -\li \image macintosh-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image macintosh-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image macintosh-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image macintosh-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image macintosh-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image macintosh-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image macintosh-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image macintosh-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image macintosh-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image macintosh-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image macintosh-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image macintosh-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image macintosh-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image macintosh-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-motif.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-motif.qdoc deleted file mode 100644 index 5cbffc5516..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-motif.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-motif.html - - \title Motif Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "motif" style. - -\section2 Buttons - -\table 100% -\row -\li \image motif-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image motif-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image motif-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image motif-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image motif-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image motif-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image motif-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image motif-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image motif-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image motif-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image motif-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image motif-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image motif-label.png - The QLabel widget provides a text or image display. -\li \image motif-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image motif-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image motif-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image motif-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image motif-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image motif-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image motif-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image motif-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image motif-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image motif-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image motif-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image motif-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image motif-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image motif-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-plastique.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-plastique.qdoc deleted file mode 100644 index 359fac8018..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-plastique.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-plastique.html - - \title Plastique Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "plastique" style. - -\section2 Buttons - -\table 100% -\row -\li \image plastique-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image plastique-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image plastique-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image plastique-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image plastique-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image plastique-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image plastique-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image plastique-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image plastique-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image plastique-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image plastique-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image plastique-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image plastique-label.png - The QLabel widget provides a text or image display. -\li \image plastique-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image plastique-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image plastique-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image plastique-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image plastique-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image plastique-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image plastique-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image plastique-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image plastique-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image plastique-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image plastique-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image plastique-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image plastique-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image plastique-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-windows.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-windows.qdoc deleted file mode 100644 index b118c845c6..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-windows.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-windows.html - - \title Windows Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "windows" style. - -\section2 Buttons - -\table 100% -\row -\li \image windows-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image windows-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image windows-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image windows-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image windows-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image windows-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image windows-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image windows-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image windows-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image windows-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image windows-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image windows-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image windows-label.png - The QLabel widget provides a text or image display. -\li \image windows-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image windows-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image windows-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image windows-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image windows-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image windows-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image windows-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image windows-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image windows-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image windows-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image windows-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image windows-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image windows-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image windows-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-windowsvista.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-windowsvista.qdoc deleted file mode 100644 index db1a7cee90..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-windowsvista.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-windowsvista.html - - \title Windows Vista Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "windowsvista" style. - -\section2 Buttons - -\table 100% -\row -\li \image windowsvista-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image windowsvista-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image windowsvista-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image windowsvista-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image windowsvista-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image windowsvista-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image windowsvista-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image windowsvista-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image windowsvista-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image windowsvista-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image windowsvista-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image windowsvista-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image windowsvista-label.png - The QLabel widget provides a text or image display. -\li \image windowsvista-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image windowsvista-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image windowsvista-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image windowsvista-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image windowsvista-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image windowsvista-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image windowsvista-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image windowsvista-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image windowsvista-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image windowsvista-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image windowsvista-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image windowsvista-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image windowsvista-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image windowsvista-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery-windowsxp.qdoc b/doc/src/widgets/widgets-and-layouts/gallery-windowsxp.qdoc deleted file mode 100644 index 2ade5681e2..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery-windowsxp.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page gallery-windowsxp.html - - \title Windows XP Style Widget Gallery - \ingroup gallery - - This page shows some of the widgets available in Qt - when configured to use the "windowsxp" style. - -\section2 Buttons - -\table 100% -\row -\li \image windowsxp-pushbutton.png - \caption The QPushButton widget provides a command button. -\li \image windowsxp-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. -\endtable - -\table 100% -\row -\li \image windowsxp-checkbox.png - \caption The QCheckBox widget provides a checkbox with a text label. -\li \image windowsxp-radiobutton.png - \caption The QRadioButton widget provides a radio button with a text or pixmap label. -\endtable - -\section2 Containers - -\table 100% -\row -\li \image windowsxp-groupbox.png - The The QGroupBox widget provides a group box frame with a title. -\li \image windowsxp-tabwidget.png - The QTabWidget class provides a stack of tabbed widgets. -\li \image windowsxp-frame.png - The QFrame widget provides a simple decorated container for other widgets. -\li \image windowsxp-toolbox.png - The QToolBox class provides a column of tabbed widget items. -\endtable - -\section2 Item Views - -\table 100% -\row -\li \image windowsxp-listview.png - The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. -\li \image windowsxp-treeview.png - The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. -\li \image windowsxp-tableview.png - The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\li -\li -\endtable - -\section2 Display Widgets - -\table 100% -\row -\li \image windowsxp-progressbar.png - The QProgressBar widget provides a horizontal progress bar. -\li \image windowsxp-label.png - The QLabel widget provides a text or image display. -\li \image windowsxp-lcdnumber.png - The QLCDNumber widget displays a number with LCD-like digits. -\endtable - -\section2 Input Widgets - -\table 100% -\row -\li \image windowsxp-lineedit.png - The QLineEdit widget is a one-line text editor. -\li \image windowsxp-dateedit.png - The QDateEdit class provides a widget for editing dates. -\li \image windowsxp-timeedit.png - The QTimeEdit class provides a widget for editing times. -\li \image windowsxp-datetimeedit.png - The QDateTimeEdit class provides a widget for editing dates and times. -\endtable - -\table 100% -\row -\li \image windowsxp-slider.png - The QSlider widget provides a vertical or horizontal slider. -\li \image windowsxp-combobox.png - The QComboBox widget is a combined button and pop-up list. -\li \image windowsxp-spinbox.png - The QSpinBox class provides a spin box widget. -\endtable - -\table 100% -\row -\li \image windowsxp-fontcombobox.png - The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. -\li \image windowsxp-doublespinbox.png - The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. -\li \image windowsxp-horizontalscrollbar.png - The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. -\endtable - -\table 100% -\row -\li \image windowsxp-dial.png - The QDial class provides a rounded range control (like a speedometer or potentiometer). -\li \image windowsxp-textedit.png - The QTextEdit class provides a widget that is used to edit and display both plain and rich text. -\li \image windowsxp-calendarwidget.png - The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. -\endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/gallery.qdoc b/doc/src/widgets/widgets-and-layouts/gallery.qdoc deleted file mode 100644 index a2f4db5a7b..0000000000 --- a/doc/src/widgets/widgets-and-layouts/gallery.qdoc +++ /dev/null @@ -1,84 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group gallery - \title Qt Widget Gallery - \brief Qt widgets shown in different styles on various platforms. - - Qt's support for widget styles and themes enables your application to fit in - with the native desktop environment. Below, you can find links to the various - widget styles that are supplied with Qt 4. - - \table - \row - \li \image plastique-tabwidget.png Plastique Style Widget Gallery - \caption \l{Plastique Style Widget Gallery} - - The Plastique style is provided by QPlastiqueStyle. - \li \image windowsxp-tabwidget.png Windows XP Style Widget Gallery - \caption \l{Windows XP Style Widget Gallery} - - The Windows XP style is provided by QWindowsXPStyle. - \li \image windows-tabwidget.png Windows Style Widget Gallery - \caption \l{Windows Style Widget Gallery} - - The Windows style is provided by QWindowsStyle. - \endtable - - \table - \row - \li \image macintosh-tabwidget.png Macintosh Style Widget Gallery - \caption \l{Macintosh Style Widget Gallery} - - The Macintosh style is provided by QMacStyle. - \li \image cleanlooks-tabwidget.png Cleanlooks Style Widget Gallery - \caption \l{Cleanlooks Style Widget Gallery} - - The Cleanlooks style is provided by QCleanlooksStyle. - \li \image windowsvista-tabwidget.png Windows Vista Style Widget Gallery - \caption \l{Windows Vista Style Widget Gallery} - - The Windows Vista style is provided by QWindowsVistaStyle. - \endtable - - \table - \row - \li \image gtk-tabwidget.png GTK Style Widget Gallery - \caption \l{GTK Style Widget Gallery} - - The GTK style is provided by QGtkStyle. - \li \image motif-tabwidget.png Motif Style Widget Gallery - \caption \l{Motif Style Widget Gallery} - - The Motif style is provided by QMotifStyle. - \li \image cde-tabwidget.png CDE Style Widget Gallery - \caption \l{CDE Style Widget Gallery} - - The Common Desktop Environment style is provided by QCDEStyle. - \endtable -*/ diff --git a/doc/src/widgets/widgets-and-layouts/layout.qdoc b/doc/src/widgets/widgets-and-layouts/layout.qdoc deleted file mode 100644 index 6e1a5f70e1..0000000000 --- a/doc/src/widgets/widgets-and-layouts/layout.qdoc +++ /dev/null @@ -1,396 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group geomanagement - \title Layout Classes -*/ - -/*! - \page layout.html - \title Layout Management - \ingroup qt-basic-concepts - \ingroup qt-gui-concepts - \brief A tour of the standard layout managers and an introduction to custom - layouts. - - \previouspage Widgets and Layouts - \contentspage Widgets and Layouts - \nextpage {Styles and Style Aware Widgets}{Styles} - - \ingroup frameworks-technologies - - The Qt layout system provides a simple and powerful way of automatically - arranging child widgets within a widget to ensure that they make good use - of the available space. - - \tableofcontents - - \section1 Introduction - - Qt includes a set of layout management classes that are used to describe - how widgets are laid out in an application's user interface. These layouts - automatically position and resize widgets when the amount of space - available for them changes, ensuring that they are consistently arranged - and that the user interface as a whole remains usable. - - All QWidget subclasses can use layouts to manage their children. The - QWidget::setLayout() function applies a layout to a widget. When a layout - is set on a widget in this way, it takes charge of the following tasks: - - \list - \li Positioning of child widgets. - \li Sensible default sizes for windows. - \li Sensible minimum sizes for windows. - \li Resize handling. - \li Automatic updates when contents change: - \list - \li Font size, text or other contents of child widgets. - \li Hiding or showing a child widget. - \li Removal of child widgets. - \endlist - \endlist - - \section1 Qt's Layout Classes - - Qt's layout classes were designed for hand-written C++ code, allowing - measurements to be specified in pixels for simplicity, so they are easy to - understand and use. The code generated for forms created using \QD also - uses the layout classes. \QD is useful to use when experimenting with the - design of a form since it avoids the compile, link and run cycle usually - involved in user interface development. - - \annotatedlist geomanagement - - \section1 Horizontal, Vertical, Grid, and Form Layouts - - The easiest way to give your widgets a good layout is to use the built-in - layout managers: QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout. - These classes inherit from QLayout, which in turn derives from QObject (not - QWidget). They take care of geometry management for a set of widgets. To - create more complex layouts, you can nest layout managers inside each other. - - \list - \li A QHBoxLayout lays out widgets in a horizontal row, from left to - right (or right to left for right-to-left languages). - \image qhboxlayout-with-5-children.png - - \li A QVBoxLayout lays out widgets in a vertical column, from top to - bottom. - \image qvboxlayout-with-5-children.png - - \li A QGridLayout lays out widgets in a two-dimensional grid. Widgets - can occupy multiple cells. - \image qgridlayout-with-5-children.png - - \li A QFormLayout lays out widgets in a 2-column descriptive label- - field style. - \image qformlayout-with-6-children.png - \endlist - - - \section2 Laying Out Widgets in Code - - The following code creates a QHBoxLayout that manages the geometry of five - \l{QPushButton}{QPushButtons}, as shown on the first screenshot above: - - \snippet doc/src/snippets/layouts/layouts.cpp 0 - \snippet doc/src/snippets/layouts/layouts.cpp 1 - \snippet doc/src/snippets/layouts/layouts.cpp 2 - \codeline - \snippet doc/src/snippets/layouts/layouts.cpp 3 - \snippet doc/src/snippets/layouts/layouts.cpp 4 - \snippet doc/src/snippets/layouts/layouts.cpp 5 - - The code for QVBoxLayout is identical, except the line where the layout is - created. The code for QGridLayout is a bit different, because we need to - specify the row and column position of the child widget: - - \snippet doc/src/snippets/layouts/layouts.cpp 12 - \snippet doc/src/snippets/layouts/layouts.cpp 13 - \snippet doc/src/snippets/layouts/layouts.cpp 14 - \codeline - \snippet doc/src/snippets/layouts/layouts.cpp 15 - \snippet doc/src/snippets/layouts/layouts.cpp 16 - \snippet doc/src/snippets/layouts/layouts.cpp 17 - - The third QPushButton spans 2 columns. This is possible by specifying 2 as - the fifth argument to QGridLayout::addWidget(). - - QFormLayout will add two widgets on a row, commonly a QLabel and a QLineEdit - to create forms. Adding a QLabel and a QLineEdit on the same row will set - the QLineEdit as the QLabel's buddy. The following code will use the - QFormLayout to place three \l{QPushButton}{QPushButtons} and a corresponding - QLineEdit on a row. - - \snippet doc/src/snippets/layouts/layouts.cpp 18 - \snippet doc/src/snippets/layouts/layouts.cpp 19 - \snippet doc/src/snippets/layouts/layouts.cpp 20 - \codeline - \snippet doc/src/snippets/layouts/layouts.cpp 21 - \snippet doc/src/snippets/layouts/layouts.cpp 22 - \snippet doc/src/snippets/layouts/layouts.cpp 23 - - - \section2 Tips for Using Layouts - - When you use a layout, you do not need to pass a parent when constructing - the child widgets. The layout will automatically reparent the widgets - (using QWidget::setParent()) so that they are children of the widget on - which the layout is installed. - - \note Widgets in a layout are children of the widget on which the layout - is installed, \e not of the layout itself. Widgets can only have other - widgets as parent, not layouts. - - You can nest layouts using \c addLayout() on a layout; the inner layout - then becomes a child of the layout it is inserted into. - - - \section1 Adding Widgets to a Layout - - When you add widgets to a layout, the layout process works as follows: - - \list 1 - \li All the widgets will initially be allocated an amount of space in - accordance with their QWidget::sizePolicy() and - QWidget::sizeHint(). - - \li If any of the widgets have stretch factors set, with a value - greater than zero, then they are allocated space in proportion to - their stretch factor (explained below). - - \li If any of the widgets have stretch factors set to zero they will - only get more space if no other widgets want the space. Of these, - space is allocated to widgets with an - \l{QSizePolicy::Expanding}{Expanding} size policy first. - - \li Any widgets that are allocated less space than their minimum size - (or minimum size hint if no minimum size is specified) are - allocated this minimum size they require. (Widgets don't have to - have a minimum size or minimum size hint in which case the stretch - factor is their determining factor.) - - \li Any widgets that are allocated more space than their maximum size - are allocated the maximum size space they require. (Widgets do not - have to have a maximum size in which case the stretch factor is - their determining factor.) - \endlist - - - \section2 Stretch Factors - \keyword stretch factor - - Widgets are normally created without any stretch factor set. When they are - laid out in a layout the widgets are given a share of space in accordance - with their QWidget::sizePolicy() or their minimum size hint whichever is - the greater. Stretch factors are used to change how much space widgets are - given in proportion to one another. - - If we have three widgets laid out using a QHBoxLayout with no stretch - factors set we will get a layout like this: - - \img layout1.png Three widgets in a row - - If we apply stretch factors to each widget, they will be laid out in - proportion (but never less than their minimum size hint), e.g. - - \img layout2.png Three widgets with different stretch factors in a row - - - \section1 Custom Widgets in Layouts - - When you make your own widget class, you should also communicate its layout - properties. If the widget has a one of Qt's layouts, this is already taken - care of. If the widget does not have any child widgets, or uses manual - layout, you can change the behavior of the widget using any or all of the - following mechanisms: - - \list - \li Reimplement QWidget::sizeHint() to return the preferred size of the - widget. - \li Reimplement QWidget::minimumSizeHint() to return the smallest size - the widget can have. - \li Call QWidget::setSizePolicy() to specify the space requirements of - the widget. - \endlist - - Call QWidget::updateGeometry() whenever the size hint, minimum size hint or - size policy changes. This will cause a layout recalculation. Multiple - consecutive calls to QWidget::updateGeometry() will only cause one layout - recalculation. - - If the preferred height of your widget depends on its actual width (e.g., - a label with automatic word-breaking), set the - \l{QSizePolicy::hasHeightForWidth()}{height-for-width} flag in the - widget's \l{QWidget::sizePolicy}{size policy} and reimplement - QWidget::heightForWidth(). - - Even if you implement QWidget::heightForWidth(), it is still a good idea to - provide a reasonable sizeHint(). - - For further guidance when implementing these functions, see the - \e{Qt Quarterly} article - \l{http://doc.qt.nokia.com/qq/qq04-height-for-width.html} - {Trading Height for Width}. - - - \section1 Layout Issues - - The use of rich text in a label widget can introduce some problems to the - layout of its parent widget. Problems occur due to the way rich text is - handled by Qt's layout managers when the label is word wrapped. - - In certain cases the parent layout is put into QLayout::FreeResize mode, - meaning that it will not adapt the layout of its contents to fit inside - small sized windows, or even prevent the user from making the window too - small to be usable. This can be overcome by subclassing the problematic - widgets, and implementing suitable \l{QWidget::}{sizeHint()} and - \l{QWidget::}{minimumSizeHint()} functions. - - In some cases, it is relevant when a layout is added to a widget. When - you set the widget of a QDockWidget or a QScrollArea (with - QDockWidget::setWidget() and QScrollArea::setWidget()), the layout must - already have been set on the widget. If not, the widget will not be - visible. - - - \section1 Manual Layout - - If you are making a one-of-a-kind special layout, you can also make a - custom widget as described above. Reimplement QWidget::resizeEvent() to - calculate the required distribution of sizes and call - \l{QWidget::}{setGeometry()} on each child. - - The widget will get an event of type QEvent::LayoutRequest when the - layout needs to be recalculated. Reimplement QWidget::event() to handle - QEvent::LayoutRequest events. - - - \section1 How to Write A Custom Layout Manager - - An alternative to manual layout is to write your own layout manager by - subclassing QLayout. The \l{layouts/borderlayout}{Border Layout} and - \l{layouts/flowlayout}{Flow Layout} examples show how to do this. - - Here we present an example in detail. The \c CardLayout class is inspired - by the Java layout manager of the same name. It lays out the items (widgets - or nested layouts) on top of each other, each item offset by - QLayout::spacing(). - - To write your own layout class, you must define the following: - \list - \li A data structure to store the items handled by the layout. Each - item is a \link QLayoutItem QLayoutItem\endlink. We will use a - QList in this example. - \li \l{QLayout::}{addItem()}, how to add items to the layout. - \li \l{QLayout::}{setGeometry()}, how to perform the layout. - \li \l{QLayout::}{sizeHint()}, the preferred size of the layout. - \li \l{QLayout::}{itemAt()}, how to iterate over the layout. - \li \l{QLayout::}{takeAt()}, how to remove items from the layout. - \endlist - - In most cases, you will also implement \l{QLayout::}{minimumSize()}. - - - \section2 The Header File (\c card.h) - - \snippet doc/src/snippets/code/doc_src_layout.cpp 0 - - - \section2 The Implementation File (\c card.cpp) - - \snippet doc/src/snippets/code/doc_src_layout.cpp 1 - - First we define \c{count()} to fetch the number of items in the list. - - \snippet doc/src/snippets/code/doc_src_layout.cpp 2 - - Then we define two functions that iterate over the layout: \c{itemAt()} - and \c{takeAt()}. These functions are used internally by the layout system - to handle deletion of widgets. They are also available for application - programmers. - - \c{itemAt()} returns the item at the given index. \c{takeAt()} removes the - item at the given index, and returns it. In this case we use the list index - as the layout index. In other cases where we have a more complex data - structure, we may have to spend more effort defining a linear order for the - items. - - \snippet doc/src/snippets/code/doc_src_layout.cpp 3 - - \c{addItem()} implements the default placement strategy for layout items. - This function must be implemented. It is used by QLayout::add(), by the - QLayout constructor that takes a layout as parent. If your layout has - advanced placement options that require parameters, you must provide extra - access functions such as the row and column spanning overloads of - QGridLayout::addItem(), QGridLayout::addWidget(), and - QGridLayout::addLayout(). - - \snippet doc/src/snippets/code/doc_src_layout.cpp 4 - - The layout takes over responsibility of the items added. Since QLayoutItem - does not inherit QObject, we must delete the items manually. In the - destructor, we remove each item from the list using \c{takeAt()}, and - then delete it. - - \snippet doc/src/snippets/code/doc_src_layout.cpp 5 - - The \c{setGeometry()} function actually performs the layout. The rectangle - supplied as an argument does not include \c{margin()}. If relevant, use - \c{spacing()} as the distance between items. - - \snippet doc/src/snippets/code/doc_src_layout.cpp 6 - - \c{sizeHint()} and \c{minimumSize()} are normally very similar in - implementation. The sizes returned by both functions should include - \c{spacing()}, but not \c{margin()}. - - \snippet doc/src/snippets/code/doc_src_layout.cpp 7 - - - \section2 Further Notes - - \list - \li This custom layout does not handle height for width. - \li We ignore QLayoutItem::isEmpty(); this means that the layout will - treat hidden widgets as visible. - \li For complex layouts, speed can be greatly increased by caching - calculated values. In that case, implement - QLayoutItem::invalidate() to mark the cached data is dirty. - \li Calling QLayoutItem::sizeHint(), etc. may be expensive. So, you - should store the value in a local variable if you need it again - later within in the same function. - \li You should not call QLayoutItem::setGeometry() twice on the same - item in the same function. This call can be very expensive if the - item has several child widgets, because the layout manager must do - a complete layout every time. Instead, calculate the geometry and - then set it. (This does not only apply to layouts, you should do - the same if you implement your own resizeEvent(), for example.) - \endlist -*/ - diff --git a/doc/src/widgets/widgets-and-layouts/styles.qdoc b/doc/src/widgets/widgets-and-layouts/styles.qdoc deleted file mode 100644 index b9e3a30333..0000000000 --- a/doc/src/widgets/widgets-and-layouts/styles.qdoc +++ /dev/null @@ -1,2102 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group appearance - \title Widget Appearance and Style - \brief Classes used for customizing UI appearance and style. -*/ - -/*! - \page style-reference.html - \title Styles and Style Aware Widgets - \ingroup qt-gui-concepts - \brief Styles and the styling of widgets. - - Styles (classes that inherit QStyle) draw on behalf of widgets - and encapsulate the look and feel of a GUI. The QStyle class is - an abstract base class that encapsulates the look and feel of a - GUI. Qt's built-in widgets use it to perform nearly all of their - drawing, ensuring that they look exactly like the equivalent - native widgets. - - Several styles are built into Qt (e.g., windows style and motif style). - Other styles are only available on specific platforms (such as - the windows XP style). Custom styles are made available as plugins - or by creating an instance of the style class in an application and - setting it with QApplication::setStyle(). - - To implement a new style, you inherit one of Qt's existing styles - - the one most resembling the style you want to create - and - reimplement a few virtual functions. This process is somewhat - involved, and we therefore provide this overview. We give a - step-by-step walkthrough of how to style individual Qt widgets. - We will examine the QStyle virtual functions, member variables, - and enumerations. - - The part of this document that does not concern the styling of - individual widgets is meant to be read sequentially because later - sections tend to depend on earlier ones. The description of the - widgets can be used for reference while implementing a style. - However, you may need to consult the Qt source code in some cases. - The sequence in the styling process should become clear after - reading this document, which will aid you in locating relevant code. - - To develop style aware widgets (i.e., widgets that conform to - the style in which they are drawn), you need to draw them using the - current style. This document shows how widgets draw themselves - and which possibilities the style gives them. - - \section1 Classes for Widget Styling - - These classes are used to customize an application's appearance and - style. - - \annotatedlist appearance - - \section1 The QStyle implementation - - The API of QStyle contains functions that draw the widgets, static - helper functions to do common and difficult tasks (e.g., - calculating the position of slider handles) and functions to do - the various calculations necessary while drawing (e.g., for the - widgets to calculate their size hints). The style also help some - widgets with the layout of their contents. In addition, it creates - a QPalette that contains \l{QBrush}es to draw with. - - QStyle draws graphical elements; an element is a widget or a - widget part like a push button bevel, a window frame, or a scroll - bar. Most draw functions now take four arguments: - - \list - \li an enum value specifying which graphical element to draw - \li a QStyleOption specifying how and where to render that element - \li a QPainter that should be used to draw the element - \li a QWidget on which the drawing is performed (optional) - \endlist - - When a widget asks a style to draw an element, it provides the style - with a QStyleOption, which is a class that contains the information - necessary for drawing. Thanks to QStyleOption, it is possible to make - QStyle draw widgets without linking in any code for the widget. This - makes it possible to use \l{QStyle}'s draw functions on any paint - device, i.e., you can draw a combobox on any widget, not just on a - QComboBox. - - The widget is passed as the last argument in case the style needs - it to perform special effects (such as animated default buttons on - Mac OS X), but it isn't mandatory. - - We will in the course of this section look at the style elements, - the style options, and the functions of QStyle. Finally, we describe - how the palette is used. - - Items in item views is drawn by \l{Delegate Classes}{delegates} in - Qt. The item view headers are still drawn by the style. Qt's - default delegate, QStyledItemDelegate, draws its items partially - through the current style; it draws the check box indicators and - calculate bounding rectangles for the elements of which the item - consists. In this document, we only describe how to implement a - QStyle subclass. If you wish to add support for other datatypes - than those supported by the QStyledItemDelegate, you need to - implement a custom delegate. Note that delegates must be set - programmatically for each individual widget (i.e., default - delegates cannot be provided as plugins). - - \section2 The Style Elements - - A style element is a graphical part of a GUI. A widget consists - of a hierarchy (or tree) of style elements. For instance, when a - style receives a request to draw a push button (from QPushButton, - for example), it draws a label (text and icon), a button bevel, - and a focus frame. The button bevel, in turn, consists of a frame - around the bevel and two other elements, which we will look at - later. Below is a conceptual illustration of the push button - element tree. We will see the actual tree for QPushButton when we - go through the individual widgets. - - \image javastyle/conceptualpushbuttontree.png - - Widgets are not necessarily drawn by asking the style to draw - only one element. Widgets can make several calls to the style to - draw different elements. An example is QTabWidget, which draws its - tabs and frame individually. - - There are three element types: primitive elements, control - elements, and complex control elements. The elements are defined - by the \l{QStyle::}{ComplexControl}, \l{QStyle::}{ControlElement}, - and \l{QStyle::}{PrimitiveElement} enums. The values of - each element enum has a prefix to identify their type: \c{CC_} for - complex elements, \c{CE_} for control elements, and \c{PE_} for - primitive elements. We will in the following three sections see what - defines the different elements and see examples of widgets that use - them. - - The QStyle class description contains a list of these elements and - their roles in styling widgets. We will see how they are used when - we style individual widgets. - - \section3 Primitive Elements - - Primitive elements are GUI elements that are common and often used - by several widgets. Examples of these are frames, button bevels, - and arrows for spin boxes, scroll bars, and combo boxes. - Primitive elements cannot exist on their own: they are always part - of a larger construct. They take no part in the interaction with - the user, but are passive decorations in the GUI. - - \section3 Control Elements - - A control element performs an action or displays information - to the user. Examples of control elements are push buttons, check - boxes, and header sections in tables and tree views. Control - elements are not necessarily complete widgets such as push - buttons, but can also be widget parts such as tab bar tabs and - scroll bar sliders. They differ from primitive elements in that - they are not passive, but fill a function in the interaction with - the user. Controls that consist of several elements often use the - style to calculate the bounding rectangles of the elements. The - available sub elements are defined by the \l{QStyle::}{SubElement} - enum. This enum is only used for calculating bounding rectangles, - and sub elements are as such not graphical elements to be drawn - like primitive, control, and complex elements. - - \section3 Complex Control Elements - - Complex control elements contain sub controls. Complex controls - behave differently depending on where the user handles them with - the mouse and which keyboard keys are pressed. This is dependent - on which sub control (if any) that the mouse is over or received a - mouse press. Examples of complex controls are scroll bars and - combo boxes. With a scroll bar, you can use the mouse to move the - slider and press the line up and line down buttons. The available - sub controls are defined by the \l{QStyle}{SubControl} enum. - - In addition to drawing, the style needs to provide the widgets - with information on which sub control (if any) a mouse press was - made on. For instance, a QScrollBar needs to know if the user - pressed the slider, the slider groove, or one of the buttons. - - Note that sub controls are not the same as the control elements - described in the previous section. You cannot use the style to - draw a sub control; the style will only calculate the bounding - rectangle in which the sub control should be drawn. It is common, - though, that complex elements use control and primitive elements - to draw their sub controls, which is an approach that is - frequently used by the built-in styles in Qt and also the Java - style. For instance, the Java style uses PE_IndicatorCheckBox to - draw the check box in group boxes (which is a sub control of - CC_GroupBox). Some sub controls have an equivalent control element, - e.g., the scroll bar slider (SC_SCrollBarSlider and - CE_ScrollBarSlider). - - \section3 Other QStyle Tasks - - The style elements and widgets, as mentioned, use the style to - calculate bounding rectangles of sub elements and sub controls, - and pixel metrics, which is a style dependent size in screen - pixels, for measures when drawing. The available rectangles and - pixel metrics are represented by three enums in QStyle: - \l{QStyle::}{SubElement}, \l{QStyle::}{SubControl}, and - \l{QStyle::}{PixelMetric}. Values of the enums can easily by - identified as they start with SE_, SC_ and PM_. - - The style also contain a set of style hints, which is - represented as values in the \l{QStyle::}{StyleHint} enum. All - widgets do not have the same functionality and look in the - different styles. For instance, when the menu items in a menu do not - fit in a single column on the screen, some styles support - scrolling while others draw more than one column to fit all items. - - A style usually has a set of standard images (such as a warning, a - question, and an error image) for message boxes, file dialogs, - etc. QStyle provides the \l{QStyle::}{StandardPixmap} enum. Its - values represent the standard images. Qt's widgets use these, so - when you implement a custom style you should supply the images - used by the style that is being implemented. - - The style calculates the spacing between widgets in layouts. There - are two ways the style can handle these calculations. You can set - the PM_LayoutHorizontalSpacing and PM_LayoutVerticalSpacing, which - is the way the java style does it (through QCommonStyle). - Alternatively, you can implement QStyle::layoutSpacing() and - QStyle::layoutSpacingImplementation() if you need more control over - this part of the layout. In these functions you can calculate the - spacing based on control types (QSizePolicy::ControlType) for - different size policies (QSizePolicy::Policy) and also the style - option for the widget in question. - - \section2 Style Options - - The sub-classes of QStyleOption contain all information necessary - to style the individual elements. Style options are instantiated - - usually on the stack - and filled out by the caller of the QStyle - function. Depending on what is drawn the style will expect - different a different style option class. For example, the - QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect - argument, and it's possible to create custom subclasses that a - custom style can use. The style options keep public variables - for performance reasons. - - The widgets can be in a number of different states, which are - defined by the \l{QStyle::}{State} enum. Some of the state flags have - different meanings depending on the widget, but others are common - for all widgets like State_Disabled. It is QStyleOption that sets - the common states with QStyleOption::initFrom(); the rest of the - states are set by the individual widgets. - - Most notably, the style options contain the palette and bounding - rectangles of the widgets to be drawn. Most widgets have - specialized style options. QPushButton and QCheckBox, for - instance, use QStyleOptionButton as style option, which contain - the text, icon, and the size of their icon. The exact contents of - all options are described when we go through individual widgets. - - When reimplementing QStyle functions that take a - QStyleOption parameter, you often need to cast the - QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For - safety, you can use qstyleoption_cast() to ensure that the - pointer type is correct. If the object isn't of the right type, - qstyleoption_cast() returns 0. For example: - - \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 0 - - The following code snippet illustrates how to use QStyle to - draw the focus rectangle from a custom widget's paintEvent(): - - \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 1 - - The next example shows how to derive from an existing style to - customize the look of a graphical element: - - \snippet doc/src/snippets/customstyle/customstyle.h 0 - \codeline - \snippet doc/src/snippets/customstyle/customstyle.cpp 2 - \snippet doc/src/snippets/customstyle/customstyle.cpp 3 - \snippet doc/src/snippets/customstyle/customstyle.cpp 4 - - \section2 QStyle Functions - - The QStyle class defines three functions for drawing the primitive, - control, and complex elements: - \l{QStyle::}{drawPrimitive()}, - \l{QStyle::}{drawControl()}, and - \l{QStyle::}{drawComplexControl()}. The functions takes the - following parameters: - - \list - \li the enum value of the element to draw - \li a QStyleOption which contains the information needed to - draw the element. - \li a QPainter with which to draw the element. - \li a pointer to a QWidget, typically the widget - that the element is painted on. - \endlist - - Not all widgets send a pointer to themselves. If the style - option sent to the function does not contain the information you - need, you should check the widget implementation to see if it - sends a pointer to itself. - - The QStyle class also provides helper functions that are used - when drawing the elements. The \l{QStyle::}{drawItemText()} - function draws text within a specified rectangle and taking a - QPalette as a parameter. The \l{QStyle::}{drawItemPixmap()} - function helps to align a pixmap within a specified bounding - rectangle. - - Other QStyle functions do various calculations for the - functions that draw. The widgets also use these functions for - calculating size hints and also for bounding rectangle - calculations if they draw several style elements themselves. - As with the functions that draw elements the helper functions - typically takes the same arguments. - - \list - \li The \l{QStyle::}{subElementRect()} function takes a - \l{QStyle::}{SubElement} enum value, and calculates a bounding - rectangle for a sub element. The style uses this function to - know where to draw the different parts of an element. This is - mainly done for reuse. If you create a new style, you can use - the same location of sub elements as the super class. - - \li The \l{QStyle::}{subControlRect()} function is used to - calculate bounding rectangles for sub controls in complex - controls. When you implement a new style, you reimplement \c - subControlRect() and calculate the rectangles that are different - from the super class. - - \li The \l{QStyle::}{pixelMetric()} function returns a pixel - metric, which is a style dependent size given in screen - pixels. It takes a value of the \l{QStyle::}{PixelMetric} enum - and returns the correct measure. Note that pixel metrics do - not necessarily have to be static measures, but can be - calculated with, for example, the style option. - - \li The \l{QStyle::}{hitTestComplexControl()} function returns the - sub control that the mouse pointer is over in a complex control. - Usually, this is simply a matter of using - \l{QStyle::}{subControlRect()} to get the bounding rectangles of - the sub controls, and see which rectangle contains the position of - the cursor. - \endlist - - QStyle also have the functions \l{QStyle::}{polish()} and - \l{QStyle::}{unpolish()}. All widgets are sent to the \c polish() - function before being shown and to \c unpolish() when they - are hidden. You can use these functions to set attributes on the - widgets or do other work that is required by your style. For - instance, if you need to know when the mouse is hovering over the - widget, you need to set the \l{Qt::}{WA_Hover} widget attribute. - The State_MouseOver state flag will then be set in the widget's - style options. - - QStyle has a few static helper functions that do some common and - difficult tasks. They can calculate the position of a slider - handle from the value of the slider and transform rectangles - and draw text considering reverse layouts; see the QStyle - class documentation for more details. - - The usual approach when one reimplements QStyle virtual - functions is to do work on elements that are different from the - super class; for all other elements, you can simply use the super - class implementation. - - \section2 The Palette - - Each style provides a color - that is, QBrush - palette that - should be used for drawing the widgets. There is one set of colors - for the different widget states (QPalette::ColorGroup): active - (widgets in the window that has keyboard focus), inactive (widgets - used for other windows), and disabled (widgets that are set - disabled). The states can be found by querying the State_Active - and State_Enabled state flags. Each set contains color certain - roles given by the QPalette::ColorRole enum. The roles describe in - which situations the colors should be used (e.g., for painting - widget backgrounds, text, or buttons). - - How the color roles are used is up to the style. For instance, if - the style uses gradients, one can use a palette color and make it - darker or lighter with QColor::darker() and QColor::lighter() to - create the gradient. In general, if you need a brush that is not - provided by the palette, you should try to derive it from one. - - QPalette, which provides the palette, stores colors for - different widget states and color roles. The palette for a style - is returned by \l{QStyle::}{standardPalette()}. The standard - palette is not installed automatically when a new style is set - on the application (QApplication::setStyle()) or widget - (QWidget::setStyle()), so you must set the palette yourself - with (QApplication::setPalette()) or (QWidget::setPalette()). - - It is not recommended to hard code colors as applications and - individual widgets can set their own palette and also use the - styles palette for drawing. Note that none of Qt's widgets set - their own palette. The java style does hard code some colors, but - its author looks past this in silence. Of course, it is not - intended that the style should look good with any palette. - - \section2 Implementation Issues - - When you implement styles, there are several issues to - consider. We will give some hints and advice on implementation - here. - - When implementing styles, it is necessary to look through the - code of the widgets and code of the base class and its ancestors. - This is because the widgets use the style differently, because the - implementation in the different styles virtual functions can - affect the state of the drawing (e.g., by altering the QPainter - state without restoring it and drawing some elements without using - the appropriate pixel metrics and sub elements). - - It is recommended that the styles do not alter the proposed size - of widgets with the QStyle::sizeFromContents() function but let - the QCommonStyle implementation handle it. If changes need to be - made, you should try to keep them small; application development - may be difficult if the layout of widgets looks considerably - different in the various styles. - - We recommend using the QPainter directly for drawing, i.e., not - use pixmaps or images. This makes it easier for the style conform - to the palette (although you can set your own color table on a - QImage with \l{QImage::}{setColorTable()}). - - It is, naturally, possible to draw elements without using the - style to draw the sub elements as intended by Qt. This is - discouraged as custom widgets may depend on these sub elements to - be implemented correctly. The widget walkthrough shows how Qt - uses the sub elements. - - \section1 Java Style - - We have implemented a style that resembles the Java default look - and feel (previously known as Metal). We have done this as it is - relatively simple to implement and we wanted to build a style for - this overview document. To keep it simple and not to extensive, we - have simplified the style somewhat, but Qt is perfectly able to - make an exact copy of the style. However, there are no concrete - plans to implement the style as a part of Qt. - - In this section we will have a look at some implementation - issues. Finally, we will see a complete example on the styling of - a Java widget. We will continue to use the java style - throughout the document for examples and widget images. The - implementation itself is somewhat involved, and it is not - intended that you should read through it. - - \section2 Design and Implementation - - The first step in designing the style was to select the base - class. We chose to subclass QWindowsStyle. This class implements - most of the functionality we need other than performing the actual - drawing. Also, windows and java share layout of sub controls for - several of the complex controls (which reduces the amount of code - required considerably). - - The style is implemented in one class. We have done this - because we find it convenient to keep all code in one file. Also, - it is an advantage with regards to optimization as we instantiate - less objects. We also keep the number of functions at a minimum by - using switches to identify which element to draw in the functions. - This results in large functions, but since we divide the code for - each element in the switches, the code should still be easy to - read. - - \section2 Limitations and Differences from Java - - We have not fully implemented every element in the Java style. - This way, we have reduced the amount and complexity of the code. - In general, the style was intended as a practical example for - this style overview document, and not to be a part of Qt - itself. - - Not all widgets have every state implemented. This goes for - states that are common, e.g., State_Disabled. Each state is, - however, implemented for at least one widget. - - We have only implemented ticks below the slider. Flat push - buttons are also left out. We do not handle the case where the - title bars and dock window titles grows to small for their - contents, but simply draw sub controls over each other. - - We have not tried to emulate the Java fonts. Java and Qt use very - different font engines, so we don't consider it worth the effort - as we only use the style as an example for this overview. - - We have hardcoded the colors (we don't use the QPalette) for - the linear gradients, which are used, for example, for button - bevels, tool bars, and check boxes. This is because the Java - palette cannot produce these colors. Java does not change these - colors based on widget color group or role anyway (they are not - dependent on the palette), so it does not present a problem in any - case. - - It is Qt's widgets that are styled. Some widgets do not exist - at all in Java, e.g., QToolBox. Others contain elements that the - Java widgets don't. The tree widget is an example of the latter in - which Java's JTree does not have a header. - - The style does not handle reverse layouts. We assume that the - layout direction is left to right. QWindowsStyle handles reverse - widgets; if we implemented reverse layouts, widgets that we change - the position of sub elements, or handle text alignment in labels - our selves would need to be updated. - - \section2 Styling Java Check Boxes - - As an example, we will examine the styling of check boxes in the - java style. We describe the complete process and print all code in - both the java style and Qt classes involved. In the rest of this - document, we will not examine the source code of the individual - widgets. Hopefully, this will give you an idea on how to search - through the code if you need to check specific implementation - details; most widgets follow the same structure as the check - boxes. We have edited the QCommonStyle code somewhat to remove - code that is not directly relevant for check box styling. - - We start with a look at how QCheckBox builds it style option, - which is QStyleOptionButton for checkboxes: - - \snippet doc/src/snippets/code/doc_src_styles.cpp 0 - - First we let QStyleOption set up the option with the information - that is common for all widgets with \c initFrom(). We will look at - this shortly. - - The down boolean is true when the user press the box down; this is - true whether the box is checked or not of the checkbox. The - State_NoChange state is set when we have a tristate checkbox and - it is partially checked. It has State_On if the box is checked and - State_Off if it is unchecked. State_MouseOver is set if the mouse - hovers over the checkbox and the widget has attribute Qt::WA_Hover - set - you set this in QStyle::polish(). In addition, the style - option also contains the text, icon, and icon size of the button. - - \l{QStyleOption::}{initFrom()} sets up the style option with the - attributes that are common for all widgets. We print its - implementation here: - - \snippet doc/src/snippets/code/doc_src_styles.cpp 1 - - The State_Enabled is set when the widget is enabled. When the - widget has focus the State_HasFocus flag is set. Equally, the - State_Active flag is set when the widget is a child of the active - window. The State_MouseOver will only be set if the widget has - the WA_HoverEnabled windows flag set. Notice that keypad - navigation must be enabled in Qt for the State_HasEditFocus to - be included; it is not included by default. - - In addition to setting state flags the QStyleOption contains - other information about the widget: \c direction is the layout - direction of the layout, \c rect is the bounding rectangle of the - widget (the area in which to draw), \c palette is the QPalette - that should be used for drawing the widget, and \c fontMetrics is - the metrics of the font that is used by the widget. - - We give an image of a checkbox and the style option to match - it. - - \image javastyle/checkboxexample.png A java style checkbox - - The above checkbox will have the following state flags in its - style option: - - \table 90% - \header - \li State flag - \li Set - \row - \li State_Sunken - \li Yes - \row - \li State_NoChange - \li No - \row - \li State_On - \li Yes - \row - \li State_Off - \li No - \row - \li State_MouseOver - \li Yes - \row - \li State_Enabled - \li Yes - \row - \li State_HasFocus - \li Yes - \row - \li State_KeyboardFocusChange - \li No - \row - \li State_Active - \li Yes - \endtable - - The QCheckBox paints itself in QWidget::paintEvent() with - style option \c opt and QStylePainter \c p. The QStylePainter - class is a convenience class to draw style elements. Most - notably, it wraps the methods in QStyle used for painting. The - QCheckBox draws itself as follows: - - \snippet doc/src/snippets/code/doc_src_styles.cpp 2 - - QCommonStyle handles the CE_CheckBox element. The QCheckBox - has two sub elements: SE_CheckBoxIndicator (the checked indicator) - and SE_CheckBoxContents (the contents, which is used for the - checkbox label). QCommonStyle also implements these sub element - bounding rectangles. We have a look at the QCommonStyle code: - - \snippet doc/src/snippets/code/doc_src_styles.cpp 3 - - As can be seen from the code extract, the common style gets - the bounding rectangles of the two sub elements of - CE_CheckBox, and then draws them. If the checkbox has focus, - the focus frame is also drawn. - - The java style draws CE_CheckBoxIndicator, while QCommonStyle - handles CE_CheckboxLabel. We will examine each implementation and - start with CE_CheckBoxLabel: - - \snippet doc/src/snippets/code/doc_src_styles.cpp 4 - - \l{QStyle::}{visualAlignment()} adjusts the alignment of text - according to the layout direction. We then draw an icon if it - exists, and adjust the space left for the text. - \l{QStyle::}{drawItemText()} draws the text taking alignment, - layout direction, and the mnemonic into account. It also uses the - palette to draw the text in the right color. - - The drawing of labels often get somewhat involved. Luckily, it - can usually be handled by the base class. The java style - implements its own push button label since Java-contrary to - windows-center button contents also when the button has an icon. - You can examine that implementation if you need an example of - reimplementing label drawing. - - We take a look at the java implementation - of CE_CheckBoxIndicator in \c drawControl(): - - \snippet doc/src/snippets/javastyle.cpp 0 - - We first save the state of the painter. This is not always - necessary but in this case the QWindowsStyle needs the painter in - the same state as it was when PE_IndicatorCheckBox was called (We - could also set the state with function calls, of course). We then - use \c drawButtonBackground() to draw the background of the check - box indicator. This is a helper function that draws the background - and also the frame of push buttons and check boxes. We take a look - at that function below. We then check if the mouse is hovering - over the checkbox. If it is, we draw the frame java checkboxes - have when the box is not pressed down and the mouse is over it. - You may note that java does not handle tristate boxes, so we have - not implemented it. - - Here we use a png image for our indicator. We could also check - here if the widget is disabled. We would then have to use - another image with the indicator in the disabled color. - - \snippet doc/src/snippets/javastyle.cpp 1 - - We have seen how check boxes are styled in the java style from the - widget gets a paint request to the style is finished painting. To - learn in detail how each widget is painted, you need to go through - the code step-by-step as we have done here. However, it is - usually enough to know which style elements the widgets draw. The - widget builds a style option and calls on the style one or more - times to draw the style elements of which it consists. Usually, - it is also sufficient to know the states a widget can be in and the - other contents of the style option, i.e., what we list in the next - section. - - \section1 Widget Walkthrough - - In this section, we will examine how most of Qt's widgets are - styled. Hopefully, this will save you some time and effort while - developing your own styles and widgets. You will not find - information here that is not attainable elsewhere (i.e., by - examining the source code or the class descriptions for the style - related classes). - - We mostly use java style widgets as examples. The java style does not - draw every element in the element trees. This is because they are - not visible for that widget in the java style. We still make sure - that all elements are implemented in a way that conforms with the - java style as custom widgets might need them (this does not - exclude leaving implementations to QWindowsStyle though). - - The following is given for each widget: - - \list - \li A table with the members (variables, etc.) of its style option. - \li A table over the state flags (QStyle::StateFlag) that - can be set on the widget and when the states are set. - \li Its element tree (see section \l{The Style Elements}). - \li An image of the widget in which the elements are outlined. - \omit This is not written yet - probably never will be - either - \li List of style hints that should be checked for the - widget. - \li List of standard pixmaps that could be used by the - elements. - \endomit - \endlist - - The element tree contains the primitive, control, and complex - style elements. By doing a top-down traversal of the element tree, - you get the sequence in which the elements should be drawn. In the - nodes, we have written the sub element rectangles, sub control - elements, and pixel metrics that should be considered when drawing - the element of the node. - - Our approach on styling center on the drawing of the widgets. The - calculations of sub elements rectangles, sub controls, and pixel - metrics used \b during drawing is only listed as contents in - the element trees. Note that there are rectangles and pixel - metrics that are only used by widgets. This leaves these - calculations untreated in the walkthrough. For instance, the - \l{QStyle::}{subControlRect()} and - \l{QStyle::}{sizeFromContents()} functions often call - \l{QStyle::}{subElementRect()} to calculate their bounding - rectangles. We could draw trees for this as well. However, how - these calculations are done is completely up to the individual - styles, and they do not have to follow a specific structure (Qt - does not impose a specific structure). You should still make sure - that you use the appropriate pixel metrics, though. To limit the - size of the document, we have therefore chosen not to include - trees or describe the calculations made by the Java (or any other) - style. - - You may be confused about how the different pixel metrics, sub - element rectangles, and sub control rectangles should be used when - examining the trees. If you are in doubt after reading the QStyle - enum descriptions, we suggest that you examine the QCommonStyle - and QWindowsStyle implementations. - - Some of the bounding rectangles that we outline in the widget - images are equal. Reasons for this are that some elements draw - backgrounds while others draw frames and labels. If in doubt, - check the description of each element in QStyle. Also, some - elements are there to layout, i.e., decide where to draw, other - elements. - - \section2 Common Widget Properties - - Some states and variables are common for all widgets. These are - set with QStyleOption::initFrom(). Not all elements use this function; - it is the widgets that create the style options, and for some - elements the information from \l{QStyleOption::}{initFrom()} is not - necessary. - - A table with the common states follows: - - \table 90% - \header - \li State - \li State Set When - \row - \li State_Enabled - \li Set if the widget is not disabled (see - QWidget::setEnabled()) - \row - \li State_Focus - \li Set if the widget has focus (see - QWidget::hasFocus()) - \row - \li State_KeyobordFocusChange - \li Set when the user changes focus with the keyboard - (see Qt::WA_KeyboardFocusChange) - \row - \li State_MouseOver - \li Set if the mouse cursor is over the widget - \row - \li State_Active - \li Set if the widget is a child of the active window. - \row - \li State_HasEditFocus - \li Set if the widget has the edit focus - \endtable - - The other common members for widgets are: - - \table 90% - \header - \li Member - \li Content - \row - \li rect - \li The bounding rectangle of the element to draw. This - is set to the widget bounding rectangle - (QWidget::rect()). - \row - \li direction - \li The layout direction; a value of the - Qt::LayoutDirection enum. - \row - \li palette - \li The QPalette to use when drawing the element. This - is set to the widgets palette (QWidget::palette()). - \row - \li fontMetrics - \li The QFontMetrics to use when drawing text on the - widget. - \endtable - - The complex style options (classes that inherit - QStyleOptionComplex) used for complex style elements share two - variables: \l{QStyleOptionComplex::}{subControls} and - \l{QStyleOptionComplex::}{activeSubControls}. Both variables are - an OR'ed combination of QStyle::SubControl enum values. They - indicate which sub controls the complex control consists of and - which of these controls are currently active. - - As mentioned, the style calculates the size of the widgets - contents, which the widgets calculate their size hints from. In - addition, complex controls also use the style to test which - sub-controls the mouse is over. - - \section2 Widget Reference - - Without further delay, we present the widget walkthrough; each - widget has its own sub-section. - - \section3 Push Buttons - - The style structure for push buttons is shown below. By doing a - top-down traversal of the tree, you get the sequence in which the - elements should be drawn. - - \image javastyle/pushbutton.png The style structure for push buttons - - The layout of the buttons, with regard element bounds, varies from - style to style. This makes it difficult to show conceptual images - of this. Also, elements may - even be intended to - have the same - bounds; the PE_PushButtonBevel, for instance, is used in - QCommonStyle to draw the elements that contains it: - PE_FrameDefaultButton, PE_FrameButtonBevel, and - PE_PanelButtonCommand, all of which have the same bounds in common - and windows style. PE_PushButtonBevel is also responsible for - drawing the menu indicator (QCommonStyle draws - PE_IndicatorArrowDown). - - An image of a push button in the java style that show the bounding - rectangles of the elements is given below. Colors are used to - separate the bounding rectangles in the image; they do not fill - any other purpose. This is also true for similar images for the - other widgets. - - \image javastyle/button.png - - The java style, as well as all other styles implemented in Qt, - does not use PE_FrameButtonBevel. It is usual that a button - with a PE_DefaultFrame adjusts the PE_PanelButtonCommand's - rectangle by PM_ButtonDefaultIndicator. The CE_PushButtonLabel - is found by adjusting the rect by PM_DefaultFrameWidth. - - We will now examine the style option for push - buttons - QStyleOptionButton. A table for the states that - QPushButton can set on the style option follows: - - \table 90% - \header - \li State - \li State Set When - \row - \li State_Sunken - \li Button is down or menu is pressed shown - \row - \li State_On - \li Button is checked - \row - \li State_Raised - \li Button is not flat and not pressed down - \endtable - - Other members of QStyleOptionButton is: - - \table 90% - \header - \li Member - \li Content - \row - \li features - \li Flags of the QStyleOptionButton::ButtonFeatures enum, - which describes various button properties (see enum) - \row - \li icon - \li The buttons QIcon (if any) - \row - \li iconSize - \li The QSize of the icon - \row - \li text - \li a QString with the buttons text - \endtable - - \section3 Check and Radio Buttons - - The structures for radio and check buttons are identical. - We show the structure using QCheckBox element and pixel - metric names: - - \image javastyle/checkbox.png - - QStyleOptionButton is used as the style option for both check - and radio buttons. We first give a table of the states that - can be set in the option: - - \table 90% - \header - \li State - \li State Set When - \row - \li State_sunken - \li The box is pressed down - \row - \li State_NoChange - \li The box is partially checked (for tristate - checkboxes.) - \row - \li State_On - \li The box is checked - \row - \li State_Off - \li The box is unchecked - \endtable - - See \l{Push Buttons} for a table over other members in the - QStyleOptionButtonClass. - - \section3 Tabs - - In Qt, QTabBar uses the style to draw its tabs. Tabs exist either - in a QTabWidget, which contains a QTabBar, or as a separate bar. - If the bar is not part of a tab widget, it draws its own base. - - QTabBar lays out the tabs, so the style does not have control over - tab placement. However, while laying out its tabs, the bar asks - the style for PM_TabBarTabHSpace and PM_TabBarTabVSpace, which is - extra width and height over the minimum size of the tab bar tab - label (icon and text). The style can also further influence the - tab size before it is laid out, as the tab bar asks for - CT_TabBarTab. The bounding rectangle of the bar is decided by the - tab widget when it is part of the widget (still considering - CT_TabBarTab). - - The tab bar is responsible for drawing the buttons that appear on - the tab bar when all tabs do not fit. Their placement is not - controlled by the style, but the buttons are \l{QToolButton}s - and are therefore drawn by the style. - - Here is the style structure for QTabWidget and QTabBar: - - \image javastyle/tab.png - - The dotted lines indicate that the QTabWidget contains a tab bar, - but does not draw it itself, that QTabBar only draws its base line - when not part of a tab widget, and that the tab bar keeps two tool - buttons that scroll the bar when all tabs do not fit; see \l{Tool - Buttons} for their element tree. Also note that since the buttons - are children of the tab bar, they are drawn after the bar. The - tabs bounding rectangles overlap the base by PM_TabBarBaseOverlap. - - Here is a tab widget in the java style: - - \image javastyle/tabwidget.png - - In the java style (and also windows), the tab bar shape and label - have the same bounding rectangle as CE_TabBarTab. Notice that the - tabs overlap with the tab widget frame. The base of the tab bar - (if drawn) is the area where the tabs and frame overlap. - - The style option for tabs (QStyleOptionTab) contains the necessary - information for drawing tabs. The option contains the position of - the tab in the tab bar, the position of the selected tab, the - shape of the tab, the text, and icon. After Qt 4.1 the option - should be cast to a QStyleOptionTabV2, which also contains the - icons size. - - As the java style tabs don't overlap, we also present an image of - a tab widget in the windows style. Note that if you want the tabs - to overlap horizontally, you do that when drawing the tabs in - CE_TabBarTabShape; the tabs bounding rectangles will not be - altered by the tab bar. The tabs are drawn from left to right in a - north tab bar shape, top to bottom in an east tab bar shape, etc. - The selected tab is drawn last, so that it is easy to draw it over - the other tabs (if it is to be bigger). - - \image javastyle/windowstabimage.png - - A table of the states a tab bar can set on its tabs follows: - - \table 90% - \header - \li State - \li State Set When - \row - \li State_Sunken - \li The tab is pressed on with the mouse. - \row - \li State_Selected - \li If it is the current tab. - \row - \li State_HasFocus - \li The tab bar has focus and the tab is selected - \endtable - - Note that individual tabs may be disabled even if the tab bar - is not. The tab will be active if the tab bar is active. - - Here follows a table of QStyleOptionTabV2's members: - - \table 90% - \header - \li Member - \li Content - \row - \li cornerWidgets - \li Is flags of the CornerWidget enum, which indicate - if and which corner widgets the tab bar has. - \row - \li icon - \li The QIcon of the tab - \row - \li iconSize - \li The QSize of the icon - \row - \li position - \li A TabPosition enum value that indicates the tabs - position on the bar relative to the other tabs. - \row - \li row - \li holds which row the tab is in - \row - \li selectedPosition - \li A value of the SelectedPosition enum that indicates - whether the selected tab is adjacent to or is the - tab. - \row - \li shape - \li A value of the QTabBar::Shape enum indication - whether the tab has rounded or triangular corners - and the orientation of the tab. - \row - \li text - \li The tab text - \endtable - - The frame for tab widgets use QStyleOptionTabWidgetFrame as - style option. We list its members here. It does not have - states set besides the common flags. - - \table 90% - \header - \li Member - \li content - \row - \li leftCornerWidgetSize - \li The QSize of the left corner widget (if any). - \row - \li rightCornerWidgetSize - \li The QSize of the right corner widget (if any). - \row - \li lineWidth - \li holds the line with for drawing the panel. - \row - \li midLineWith - \li this value is currently always 0. - \row - \li shape - \li The shape of the tabs on the tab bar. - \row - \li tabBarSize - \li The QSize of the tab bar. - \endtable - - \section3 Scroll Bars - - Here is the style structure for scrollBars: - - \image javastyle/scrollbar.png - - QScrollBar simply creates its style option and then draws - CC_ScrollBar. Some styles draw the background of add page and sub - page with PE_PanelButtonBevel and also use indicator arrows to - draw the arrows in the nest and previous line indicators; we have - not included these in the tree as their use is up to the - individual style. The style's PM_MaximumDragDistance is the - maximum distance in pixels the mouse can move from the bounds - of the scroll bar and still move the handle. - - Here is an image of a scrollbar in the java style: - - \image javastyle/scrollbarimage.png - - You may notice that the scrollbar is slightly different from - Java's as it has two line up indicators. We have done this to show - how that you can have two separate bounding rectangles for a - single sub control. The scroll bar is an example of a widget that - is entirely implemented by the java style - neither QWindowsStyle - nor QCommonStyle are involved in the drawing. - - We have a look at the different states a scroll bar can set on - the style option: - - \table 90% - \header - \li State - \li State Set When - \row - \li State_Horizontal - \li The scroll bar is horizontal - \endtable - - The style option of QScrollBar is QStyleOptionSlider. Its - members are listed in the following table. The option is used - by all \l{QAbstractSlider}s; we only describe the members - relevant for scroll bars here. - - \table 90% - \header - \li Member - \li Content - \row - \li maximum - \li the maximum value of the scroll bar - \row - \li minimum - \li the minimum value of the scroll bar - \row - \li notchTarget - \li the number of pixels between notches - \row - \li orientation - \li a value of the Qt::Orientation enum that specifies - whether the scroll bar is vertical or horizontal - \row - \li pageStep - \li the number to increase or decrease the sliders - value (relative to the size of the slider and its value - range) on page steps. - \row - \li singleStep - \li the number to increase or decrease the sliders - value on single (or line) steps - \row - \li sliderValue - \li The value of the slider - \row - \li sliderPosition - \li the position of the slider handle. This is the same - as \c sliderValue if the scroll bar is - QAbstractSlider::tracking. If not, the scroll - bar does not update its value before the mouse - releases the handle. - \row - \li upsideDown - \li holds the direction in which the scroll bar - increases its value. This is used instead of - QStyleOption::direction for all abstract sliders. - \endtable - - \section3 Sliders - - When calculating the sliders size hint, PM_SliderTickness and - PM_SliderLength is queried from the style. As with scroll bars, - the QSlider only lets the user move the handle if the mouse is - within PM_MaximumDragDistance from the slider bounds. When it - draws itself it creates the style option and calls \c - drawComplexControl() with CC_Slider: - - \image javastyle/slider.png - - We also show a picture of a slider in the java style. We show - the bounding rectangles of the sub elements as all drawing is done - in CC_Slider. - - \image javastyle/sliderimage.png - - QSlider uses QStyleOptionSlider as all \l{QAbstractSlider}s do. We - present a table with the members that affect QSlider: - - \table 90% - \header - \li Member - \li Content - \row - \li maximum - \li the maximum value of the slider - \row - \li minimum - \li the minimum value of the slider - \row - \li notchTarget - \li this is the number of pixels between each notch - \row - \li orientation - \li a Qt::Orientation enum value that gives whether the - slider is vertical or horizontal. - \row - \li pageStep - \li a number in slider value to increase or decrease - for page steps - \row - \li singleStep - \li the number to increase or decrease the sliders - value on single (or line) steps. - \row - \li sliderValue - \li the value of the slider. - \row - \li sliderPosition - \li the position of the slider given as a slider value. - This will be equal to the \c sliderValue if the - slider is \l{QAbstractSlider::}{tracking}; if - not, the sliders value will not change until the handle is - released with the mouse. - \row - \li upsideDown - \li this member is used instead of QStyleOption::direction - for all abstract sliders. - \endtable - - You should note that the slider does not use direction for - reverse layouts; it uses \c upsideDown. - - \section3 Spin Boxes - - When QSpinBox paints itself it creates a QStyleOptionSpinBox and - asks the style to draw CC_SpinBox. The edit field is a line - edit that is a child of the spin box. The dimensions of the - field is calculated by the style with SC_SpinBoxEditField. - - Here follows the style tree for spin boxes. It is not - required that a style uses the button panel primitive to paint - the indicator backgrounds. You can see an image below the tree - showing the sub elements in QSpinBox in the java style. - - \image javastyle/spinbox.png - - \image javastyle/spinboximage.png - - The QStyleOptionSpinBox, which is the style option for spin - boxes. It can set the following states on the spin box.: - - \table 90% - \header - \li State - \li State Set When - \row - \li State_Sunken - \li Is set if one of the sub controls CC_SpinUp or - CC_SpinDown is pressed on with the mouse. - \endtable - - The rest of the members in the spin boxes style options are: - - \table 90% - \header - \li Property - \li Function - \row - \li frame - \li boolean that is true if the spin box is to draw a - frame. - \row - \li buttonSymbols - \li Value of the ButtonSymbols enum that decides the - symbol on the up/down buttons. - \row - \li stepEnabled - \li A value of the StepEnabled indication which of the - spin box buttons are pressed down. - \endtable - - \section3 Title Bar - - The title bar complex control, CC_TitleBar, is used to draw - the title bars of internal windows in QMdiArea. It typically - consists of a window title and close, minimize, system menu, and - maximize buttons. Some styles also provide buttons for shading - the window, and a button for context sensitive help. - - The bar is drawn in CC_TitleBar without using any sub elements. - How the individual styles draw their buttons is individual, but - there are standard pixmaps for the buttons that the style should - provide. - - \image javastyle/titlebar.png - - In an image over a title bar in the java style, we show the - bounding rectangles of the sub elements supported by the java style - (all of which are drawn with standard pixmaps). It is usual to - draw the button backgrounds using PE_PanelButtonTool, but it's no - rule. - - \image javastyle/titlebarimage.png - - The style option for title bars is QStyleOptionTitleBar. It's - members are: - - \table 90% - \header - \li Member - \li Content - \row - \li icon - \li The title bars icon - \row - \li text - \li the text for the title bar's label - \row - \li windowFlags - \li flags of the Qt::WindowFlag enum. The window flags - used by QMdiArea for window management. - \row - \li titleBarState - \li this is the QWidget::windowState() of the window - that contains the title bar. - \endtable - - \section3 Combo Box - - A QComboBox uses the style to draw the button and label of - non-editable boxes with CC_ComboBox and CE_ComboBoxLabel. - - The list that pops up when the user clicks on the combo box is - drawn by a \l{Delegate Classes}{delegate}, which we do not cover - in this overview. You can, however, use the style to control the - list's size and position with the sub element - SC_ComboBoxListBoxPopup. The style also decides where the edit - field for editable boxes should be with SC_ComboBoxEditField; the - field itself is a QLineEdit that is a child of the combo box. - - \image javastyle/combobox.png - - We show an image over a java style combo box in which we have - outlined its sub elements and sub element rectangles: - - \image javastyle/comboboximage.png - - Java combo boxes do not use the focus rect; it changes its - background color when it has focus. The SC_ComboBoxEdit field is - used both by QComboBox to calculate the size of the edit field and - the style for calculating the size of the combo box label. - - The style option for combo boxes is QStyleOptionComboBox. It - can set the following states: - - \table 90% - \header - \li State - \li Set When - \row - \li State_Selected - \li The box is not editable and has focus - \row - \li State_Sunken - \li SC_ComboBoxArrow is active - \row - \li State_on - \li The container (list) of the box is visible - \endtable - - The style options other members are: - - \table - \header - \li Member - \li Content - \row - \li currentIcon - \li the icon of the current (selected) item of the - combo box. - \row - \li currentText - \li the text of the current item in the box. - \row - \li editable - \li holds whether the combo box is editable or not - \row - \li frame - \li holds whether the combo box has a frame or not - \row - \li iconSize - \li the size of the current items icon. - \row - \li popupRect - \li the bounding rectangle of the combo box's popup - list. - \endtable - - \section3 Group Boxes - - When calculating the size hint, QGroupBox fetches three pixel - metrics from the style: PM_IndicatorWidth, - PM_CheckBoxLabelSpacing, and PM_IndicatorHeight. QGroupBox has - the following style element tree: - - \image javastyle/groupbox.png - - Qt does not impose restrictions on how the check box is drawn; the - java style draws it with CE_IndicatorCheckBox. See \l{Check and - Radio Buttons} for the complete tree. - - We also give an image of the widget with the sub controls and - sub control rectangles drawn: - - \image javastyle/groupboximage.png - - The style option for group boxes are QStyleOptionGroupBox. The - following states can be set on it: - - \table 90% - \header - \li State - \li Set When - \row - \li State_On - \li The check box is checked - \row - \li State_Sunken - \li The checkbox is pressed down - \row - \li State_Off - \li The check box is unchecked (or there is no check box) - \endtable - - The remaining members of QStyleOptionGroupBox are: - - \table - \header - \li Member - \li Content - \row - \li features - \li flags of the QStyleOptionFrameV2::FrameFeatures - enum describing the frame of the group box. - \row - \li lineWidth - \li the line width with which to draw the panel. This - is always 1. - \row - \li text - \li the text of the group box. - \row - \li textAlignment - \li the alignment of the group box title - \row - \li textColor - \li the QColor of the text - \endtable - - \section3 Splitters - - As the structure of splitters are simple and do not contain any - sub elements, we do not include image of splitters. CE_Splitter - does not use any other elements or metrics. - - For its style option, Splitters uses the base class QStyleOption. - It can set the following state flags on it: - - \table 90% - \header - \li State - \li Set When - \row - \li State_Horizontal - \li Set if it is a horizontal splitter - \endtable - - QSplitter does not use \l{QStyleOption::}{initFrom()} to set up its - option; it sets the State_MouseOver and State_Disabled flags - itself. - - \section3 Progress Bar - - The CE_ProgressBar element is used by QProgressBar, and it is the - only element used by this widget. We start with looking at the - style structure: - - \image javastyle/progressbar.png - - Here is a progress bar in the windows style (the java style - bounding rectangles are equal): - - \image javastyle/progressbarimage.png - - The style option for QProgressBar is QStyleOptionProgressBarV2. - The bar does not set any state flags, but the other members of the - option are: - - \table 90% - \header - \li Member - \li Content - \row - \li minimum - \li The minimum value of the bar - \row - \li maximum - \li The maximum value of the bar - \row - \li progress - \li The current value of the bar - \row - \li textAlignment - \li How the text is aligned in the label - \row - \li textVisible - \li Whether the label is drawn - \row - \li text - \li The label text - \row - \li orientation - \li Progress bars can be vertical or horizontal - \row - \li invertedAppearance - \li The progress is inverted (i.e., right to left in a - horizontal bar) - \row - \li bottomToTop - \li Boolean that if true, turns the label of vertical - progress bars 90 degrees. - \endtable - - \section3 Tool Buttons - - Tool buttons exist either independently or as part of tool bars. - They are drawn equally either way. The QToolButton draws only one - style element: CC_ToolButton. - - As you must be used to by now (at least if you have read this - document sequentially), we have a tree of the widget's style - structure: - - \image javastyle/toolbutton.png - - Note that PE_FrameButtonTool and PE_IndicatorArrowDown are - included in the tree as the java style draws them, but they can - safely be omitted if you prefer it. The structure may also be - different. QWindowsStyle, for instance, draws both - PE_IndicatorButtonDropDown and PE_IndicatorArrowDown in - CE_ToolButton. - - We also have an image of a tool button where we have outlined - the sub element bounding rectangles and sub controls. - - \image javastyle/toolbuttonimage.png - - Here is the states table for tool buttons: - - \table 90% - \header - \li State - \li Set When - \row - \li State_AutoRise - \li the tool button has the autoRise property set - \row - \li State_raised - \li the button is not sunken (i.e., by being checked or - pressed on with the mouse). - \row - \li State_Sunken - \li the button is down - \row - \li State_On - \li the button is checkable and checked. - \endtable - - QStyleOptionToolButton also contains the following members: - - \table - \header - \li Member - \li Content - \row - \li arrowType - \li a Qt::ArrowType enum value, which contains the - direction of the buttons arrow (if an arrow is to - be used in place of an icon) - \row - \li features - \li flags of the QStyleOptionToolButton::ButtonFeature - enum describing if the button has an arrow, a menu, - and/or has a popup-delay. - \row - \li font - \li the QFont of the buttons label - \row - \li icon - \li the QIcon of the tool button - \row - \li iconSize - \li the icon size of the button's icon - \row - \li pos - \li the position of the button, as given by - QWidget::pos() - \row - \li text - \li the text of the button - \row - \li toolButtonStyle - \li a Qt::ToolButtonStyle enum value which decides - whether the button shows the icon, the text, or both. - \endtable - - \section3 Toolbars - - Toolbars are part of the \l{QMainWindow}{main window framework} - and cooperates with the QMainWindow to which it belongs while it - builds its style option. A main window has 4 areas that toolbars - can be placed in. They are positioned next to the four sides of - the window (i.e., north, south, west, and east). Within each area - there can be more than one line of toolbars; a line consists of - toolbars with equal orientation (vertical or horizontal) placed - next to each other. - - \l{QToolbar}{QToolbar}s in Qt consists of three elements - CE_ToolBar, PE_IndicatorToolBarHandle, and - PE_IndicatorToolBarSeparator. It is QMainWindowLayout that - calculates the bounding rectangles (i.e., position and size of the - toolbars and their contents. The main window also uses the \c - sizeHint() of the items in the toolbars when calculating the size - of the bars. - - Here is the element tree for QToolBar: - - \image javastyle/toolbar.png - - The dotted lines indicate that the QToolBar keeps an instance of - QToolBarLayout and that QToolBarSeparators are kept by - QToolBarLayout. When the toolbar is floating (i.e., has its own - window) the PE_FrameMenu element is drawn, else QToolbar draws - CE_ToolBar. - - Here is an image of a toolbar in the java style: - - \image javastyle/toolbarimage.png - - QToolBarSaparator uses QStyleOption for their style option. It - sets the State_horizontal flag if the toolbar they live in is - horizontal. Other than that, they use \l{QStyleOption::}{initFrom()}. - - The style option for QToolBar is QStyleOptionToolBar. The only - state flag set (besides the common flags) is State_Horizontal - if the bar is horizontal (i.e., in the north or south toolbar area). - The member variables of the style option are: - - \table 90% - \header - \li Member - \li Content - \row - \li features - \li Holds whether the bar is movable in a value of the - ToolBarFeature, which is either Movable or None. - \row - \li lineWidth - \li The width of the tool bar frame. - \row - \li midLineWidth - \li This variable is currently not used and is always - 0. - \row - \li positionOfLine - \li The position of the toolbar line within the toolbar - area to which it belongs. - \row - \li positionWithinLine - \li The position of the toolbar within the toolbar line. - \row - \li toolBarArea - \li The toolbar area in which the toolbar lives. - \endtable - - \section3 Menus - - Menus in Qt are implemented in QMenu. The QMenu keeps a list of - action, which it draws as menu items. When QMenu receives paint - events ,it calculates the size of each menu item and draws them - individually with CE_MenuItem. (Menu items do not have a separate - element for their label (contents), so all drawing is done in - CE_MenuItem. The menu also draws the frame of the menu with - PE_FrameMenu. It also draws CE_MenuScroller if the style supports - scrolling. CE_MenuTearOff is drawn if the menu is to large for its - bounding rectangle. - - In the style structure tree, we also include QMenu as it also does - styling related work. The bounding rectangles of menu items are - calculated for the menus size hint and when the menu is displayed - or resized. - - \image javastyle/menu.png - - The CE_MenuScroller and CE_MenuTearOff elements are handled by - QCommonStyle and are not shown unless the menu is to large to fit - on the screen. PE_FrameMenu is only drawn for pop-up menus. - - QMenu calculates rectangles based on its actions and calls - CE_MenuItem and CE_MenuScroller if the style supports that. - - It is also usual to use PE_IndicatorCheckBox (instead of using - PE_IndicatorMenuCheckMark) and PE_IndicatorRadioButton for drawing - checkable menu items; we have not included them in the style tree - as this is optional and varies from style to style. - - \image javastyle/menuimage.png - - The style option for menu items is QStyleOptionMenuItem. The - following tables describe its state flags and other members. - - \table 90% - \header - \li State - \li Set When - \row - \li State_Selected - \li The mouse is over the action and the action is not - a separator. - \row - \li State_Sunken - \li The mouse is pressed down on the menu item. - \row - \li State_DownArrow - \li Set if the menu item is a menu scroller and it scrolls - the menu downwards. - \endtable - - \table 90% - \header - \li Member - \li Content - \row - \li checkType - \li A value of the \l{QStyleOptionMenuItem::}{CheckType} enum, - which is either NotCheckable, Exclusive, or - NonExclusive. - \row - \li checked - \li Boolean that is true if the menu item is checked. - \row - \li font - \li The QFont to use for the menu item's text. - \row - \li icon - \li the QIcon of the menu item. - \row - \li maxIconWidth - \li The maximum width allowed for the icon - \row - \li menuHasChecableItem - \li Boolean which is true if at least one item in the - menu is checkable. - \row - \li menuItemType - \li The type of the menu item. This a value of the - \l{QStyleOptionMenuItem::}{MenuItemType}. - \row - \li menuRect - \li The bounding rectangle for the QMenu that the menu - item lives in. - \row - \li tabWidth - \li This is the distance between the text of the menu - item and the shortcut. - \row - \li text - \li The text of the menu item. - \endtable - - The setup of the style option for CE_MenuTearOff and - CE_MenuScroller also uses QStyleOptionMenuItem; they only set the - \c menuRect variable in addition to the common settings with - QStyleOption's \l{QStyleOption::}{initFrom()}. - - \section3 Menu Bar - - QMenuBar uses the style to draw each menu bar item and the empty - area of the menu bar. The pull-down menus themselves are - \l{QMenu}s (see \l{Menus}). The style element tree for the menu - bar follows: - - \image javastyle/menubar.png - - The panel and empty area is drawn after the menu items. The - QPainter that the QMenuBar sends to the style has the bounding - rectangles of the items clipped out (i.e., clip region), so you - don't need to worry about drawing over the items. The pixel - metrics in QMenuBar is used when the bounding rectangles of the - menu bar items are calculated. - - \image javastyle/menubarimage.png - - QStyleOptionMenuItem is used for menu bar items. The members that - are used by QMenuBar is described in the following table: - - \table - \header - \li Member - \li Content - \row - \li menuRect - \li the bounding rectangle of the entire menu bar to - which the item belongs. - \row - \li text - \li the text of the item - \row - \li icon - \li the icon of the menu item (it is not common that - styles draw this icon) - \endtable - - QStyleOptionMenuItem is also used for drawing CE_EmptyMenuBarArea. - - QStyleOptionFrame is used for drawing the panel frame The - \l{QStyleOptionFrame::}{lineWidth} is set to PM_MenuBarPanelWidth. - The \l{QStyleOptionFrame::}{midLineWidth} is currently always set - to 0. - - \section3 Item View Headers - - It is the style that draws the headers of Qt's item views. The - item views keeps the dimensions on individual sections. Also - note that the delegates may use the style to paint decorations - and frames around items. QItemDelegate, for instance, draws - PE_FrameFocusRect and PE_IndicatorViewItemCheck. - - \image javastyle/header.png - - Here is a QTableWidget showing the bounding rects of a Java - header: - - \image javastyle/headerimage.png - - The QHeaderView uses CT_HeaderSection, PM_HeaderMargin and - PM_HeaderGripMargin for size and hit test calculations. The - PM_HeaderMarkSize is currently not used by Qt. QTableView draws - the button in the top-left corner (i.e., the area where the - vertical and horizontal headers intersect) as a CE_Header. - - The style option for header views is QStyleOptionHeader. The view - paints one header section at a time, so the data is for the - section being drawn. Its contents are: - - \table 90% - \header - \li Member - \li Content - \row - \li icon - \li the icon of the header (for section that is being - drawn). - \row - \li iconAlignment - \li the alignment (Qt::Alignment) of the icon in the header. - \row - \li orientation - \li a Qt::Orientation value deciding whether the header - is the horizontal header above the view or the - vertical header on the left. - \row - \li position - \li a QStyleOptionHeader::SectionPosition value - giving the header section's position relative to - the other sections. - \row - \li section - \li holds the section that is being drawn. - \row - \li selectedPosition - \li a QStyleOptionHeader::SelectedPosition value giving - the selected section's position relative to the - section that is being painted. - \row - \li sortIndicator - \li a QStyleOptionHeader::SortIndicator value that - describes the direction in which the section's sort - indicator should be drawn. - \row - \li text - \li the text of the currently drawn section. - \row - \li textAlignment - \li the Qt::Alignment of the text within the - headersection. - \endtable - - \section3 Tree Branch Indicators - - The branch indicators in a tree view is drawn by the style with - PE_IndicatorBranch. We think of indicators here as the indicators - that describe the relationship of the nodes in the tree. The - generic QStyleOption is sent to the style for drawing this - elements. The various branch types are described by states. Since - there are no specific style option, we simply present the states - table: - - \table 90% - \header - \li State - \li Set When - \row - \li State_Sibling - \li the node in the tree has a sibling (i.e., there is - another node in the same column). - \row - \li State_Item - \li this branch indicator has an item. - \row - \li State_Children - \li the branch has children (i.e., a new sub-tree can - be opened at the branch). - \row - \li State_Open - \li the branch indicator has an opened sub-tree. - \endtable - - The tree view (and tree widget) use the style to draw the branches - (or nodes if you will) of the tree. - - QStyleOption is used as the style for PE_IndicatorBranch has state - flags set depending on what type of branch it is. - - Since there is no tree structure for branch indicators, we only - present an image of a tree in the java style. Each state is marked - in the image with a rectangle in a specific color (i.e., these - rectangles are not bounding rectangles). All combinations of - states you must be aware of are represented in the image. - - \image javastyle/branchindicatorimage.png - - \section3 Tool Boxes - - PM_SmallIconSize for sizeHints. - - QToolBox is a container that keeps a collection of widgets. It has - one tab for each widget and display one of them at a time. The - tool box lays the components it displays (the tool box buttons - and selected widget) in a QVBoxLayout. The style tree for tool - boxes looks like this: - - \image javastyle/toolbox.png - - We show an image of a tool box in the Plastique style: - - \image javastyle/toolboximage.png - - All elements have the same bounding rectangles in the - Plastique as well as the other Qt built-in styles. - - The style option for tool boxes is QStyleOptionToolBox. It - contains the text and icon of the tool box contents. The only - state set by QToolBox is State_Sunken, which is set when the user - presses a tab down with the mouse. The rest of the - QStyleOptionToolBox members are: - - \table 90% - \header - \li Member - \li Content - \row - \li icon - \li the icon on the toolbox tab - \row - \li text - \li the text on the toolbox tab - \endtable - - \section3 Size Grip - - The size grip calculates its size hint with CT_SizeGrip. The pixel - metric PM_SizeGripSize is currently unused by Qt. The element tree - for and an image in the Plastique style of QSizeGrip follows: - - \image javastyle/sizegrip.png - - \image javastyle/sizegripimage.png - - We show the size grip in a \l{QMainWindow}'s bottom right - corner. - - The size grip style option, QStyleOptionSizeGrip, have one - member except the common members from QStyleOption: - - \table 90% - \header - \li Member - \li Content - \row - \li corner - \li a Qt::Corner value that describe which corner in a - window (or equivalent) the grip is located. - \endtable - - \section3 Rubber Band - - The \l{QRubberBand}'s style tree consists of two nodes. - - \image javastyle/rubberband.png - - We present an image of a Java style window being moved in a - QMdiArea with a rubber band: - - \image javastyle/rubberbandimage.png - - The style option for rubber bands is QStyleOptionRubberBand. - Its members are: - - \table - \header - \li Member - \li Content - \row - \li opaque - \li boolean that is true if the rubber band must be - drawn in an opaque style (i.e., color) - \row - \li shape - \li a QRubberBand::Shape enum value that holds the - shape of the band (which is either a rectangle or a - line) - \endtable - - \section3 Dock Widgets - - When the dock widget lays out its contents it asks the style for - these pixel metrics: PM_DockWidgetSeparatorExtent, - PM_DockWidgetTitleBarButtonMargin, PM_DockWidgetFrameWidth, and - PM_DockWidgetTitleMargin. It also calculates the bounding - rectangles of the float and close buttons with - SE_DockWidgetCloseButton and SE_DockWidgetFloatButton. - - \image javastyle/dockwidget.png - - The dotted lines indicate that the sender keeps instances of the - recipient of the arrow (i.e., it is not a style element to draw). - The dock widget only draws PE_frameDockWidget when it is detached - from its main window (i.e., it is a top level window). If it is - docked it draws the indicator dock widget resize handle. We show a - dock widget in both docked and floating state in the plastique - style: - - \image javastyle/dockwidgetimage.png - - The style option is QStyleOptionDockWidget: - - \table 90% - \header - \li Member - \li Content - \row - \li closeable - \li boolean that holds whether the dock window can be - closed - \row - \li floatable - \li boolean that holds whether the dock window can - float (i.e., detach from the main window in which - it lives) - \row - \li movable - \li boolean that holds whether the window is movable - (i.e., can move to other dock widget areas) - \row - \li title - \li the title text of the dock window - \endtable - - For the buttons, QStyleOptionButton is used (see \l{Tool Buttons} - for content description). The dock widget resize handle has a - plain QStyleOption. -*/ diff --git a/doc/src/widgets/widgets-and-layouts/stylesheet.qdoc b/doc/src/widgets/widgets-and-layouts/stylesheet.qdoc deleted file mode 100644 index eaedb847c8..0000000000 --- a/doc/src/widgets/widgets-and-layouts/stylesheet.qdoc +++ /dev/null @@ -1,3963 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page stylesheet.html - \title Qt Style Sheets - \brief How to use style sheets to customize the appearance of widgets. - - \ingroup frameworks-technologies - \ingroup qt-basic-concepts - \ingroup qt-gui-concepts - - \previouspage {Styles and Style Aware Widgets}{Styles} - \contentspage Widgets and Layouts - \nextpage The Style Sheet Syntax - - \keyword style sheet - \keyword stylesheet - - Qt Style Sheets are a powerful mechanism that allows you to - customize the appearance of widgets, in addition to what is - already possible by subclassing QStyle. The concepts, - terminology, and syntax of Qt Style Sheets are heavily inspired - by HTML \l{http://www.w3.org/Style/CSS/}{Cascading Style Sheets - (CSS)} but adapted to the world of widgets. - - Topics: - - \list - \li \l{Overview} - \li \l{The Style Sheet Syntax} - \li \l{Qt Designer Integration} - \li \l{Customizing Qt Widgets Using Style Sheets} - \li \l{Qt Style Sheets Reference} - \li \l{Qt Style Sheets Examples} - \endlist - - \target overview - \section1 Overview - - Styles sheets are textual specifications that can be set on the - whole application using QApplication::setStyleSheet() or on a - specific widget (and its children) using - QWidget::setStyleSheet(). If several style sheets are set at - different levels, Qt derives the effective style sheet from all - of those that are set. This is called cascading. - - For example, the following style sheet specifies that all - \l{QLineEdit}s should use yellow as their background color, and - all \l{QCheckBox}es should use red as the text color: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 0 - - For this kind of customization, style sheets are much more - powerful than QPalette. For example, it might be tempting to set - the QPalette::Button role to red for a QPushButton to obtain a - red push button. However, this wasn't guaranteed to work for all - styles, because style authors are restricted by the different - platforms' guidelines and (on Windows XP and Mac OS X) by the - native theme engine. - - Style sheets let you perform all kinds of customizations that are - difficult or impossible to perform using QPalette alone. If you - want yellow backgrounds for mandatory fields, red text for - potentially destructive push buttons, or fancy check boxes, style - sheets are the answer. - - Style sheets are applied on top of the current \l{QStyle}{widget - style}, meaning that your applications will look as native as - possible, but any style sheet constraints will be taken into - consideration. Unlike palette fiddling, style sheets offer - guarantees: If you set the background color of a QPushButton to be - red, you can be assured that the button will have a red background - in all styles, on all platforms. In addition, \l{Qt Designer} - provides style sheet integration, making it easy to view the effects - of a style sheet in different \l{QStyle}{widget styles}. - - In addition, style sheets can be used to provide a distinctive - look and feel for your application, without having to subclass - QStyle. For example, you can specify arbitrary images for radio - buttons and check boxes to make them stand out. Using this - technique, you can also achieve minor customizations that would - normally require subclassing several style classes, such as - specifying a \l{QStyle::styleHint()}{style hint}. The - \l{widgets/stylesheet}{Style Sheet} example depicted below defines - two distinctive style sheets that you can try out and modify at - will. - - \table - \row \li \inlineimage stylesheet-coffee-xp.png - \li \inlineimage stylesheet-pagefold.png - \row \li Coffee theme running on Windows XP - \li Pagefold theme running on Windows XP - \endtable - - \table - \row \li \inlineimage stylesheet-coffee-cleanlooks.png - \li \inlineimage stylesheet-pagefold-mac.png - \row \li Coffee theme running on Ubuntu Linux - \li Pagefold theme running on Mac OS X - \endtable - - When a style sheet is active, the QStyle returned by QWidget::style() - is a wrapper "style sheet" style, \e not the platform-specific style. The - wrapper style ensures that any active style sheet is respected and - otherwise forwards the drawing operations to the underlying, - platform-specific style (e.g., QWindowsXPStyle on Windows XP). - - Since Qt 4.5, Qt style sheets fully supports Mac OS X. - - \warning Qt style sheets are currently not supported for custom QStyle - subclasses. We plan to address this in some future release. -*/ - -/*! - \page stylesheet-syntax.html - \contentspage {Qt Style Sheet}{Contents} - \previouspage Qt Style Sheet - \nextpage Qt Designer Integration - \title The Style Sheet Syntax - - Qt Style Sheet terminology and syntactic rules are almost - identical to those of HTML CSS. If you already know CSS, you can - probably skim quickly through this section. - - \tableofcontents - - \section1 Style Rules - - Style sheets consist of a sequence of style rules. A \e{style - rule} is made up of a selector and a declaration. The - \e{selector} specifies which widgets are affected by the rule; - the \e{declaration} specifies which properties should be set on - the widget. For example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 1 - - In the above style rule, \c QPushButton is the selector and \c{{ - color: red }} is the declaration. The rule specifies that - QPushButton and its subclasses (e.g., \c MyPushButton) should use - red as their foreground color. - - Qt Style Sheet is generally case insensitive (i.e., \c color, - \c Color, \c COLOR, and \c cOloR refer to the same property). - The only exceptions are class names, - \l{QObject::setObjectName()}{object names}, and Qt property - names, which are case sensitive. - - Several selectors can be specified for the same declaration, - using commas (\c{,}) to separate the selectors. For example, - the rule - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 2 - - is equivalent to this sequence of three rules: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 3 - - The declaration part of a style rule is a list of - \tt{\e{property}: \e{value}} pairs, enclosed in braces (\c{{}}) - and separated with semicolons. For example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 4 - - See the \l{List of Properties} section below for the list of - properties provided by Qt widgets. - - \section1 Selector Types - - All the examples so far used the simplest type of selector, the - Type Selector. Qt Style Sheets support all the - \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{selectors - defined in CSS2}. The table below summarizes the most useful - types of selectors. - - \table 100% - \header - \li Selector - \li Example - \li Explanation - - \row - \li Universal Selector - \li \c * - \li Matches all widgets. - - \row - \li Type Selector - \li \c QPushButton - \li Matches instances of QPushButton and of its subclasses. - - \row - \li Property Selector - \li \c{QPushButton[flat="false"]} - \li Matches instances of QPushButton that are not - \l{QPushButton::}{flat}. You may use this selector to test - for any Qt \l{Qt's Property System}{property} that supports - QVariant::toString() (see the \l{QVariant::}{toString()} - function documentation for details). In addition, the - special \c class property is supported, for the name of the - class. - - This selector may also be used to test dynamic properties. - For more information on customization using dynamic properties, - refer to \l{Customizing Using Dynamic Properties}. - - Instead of \c =, you can also use \c ~= to test whether a - Qt property of type QStringList contains a given QString. - - \warning If the value of the Qt property changes after the - style sheet has been set, it might be necessary to force a - style sheet recomputation. One way to achieve this is to - unset the style sheet and set it again. - - \row - \li Class Selector - \li \c .QPushButton - \li Matches instances of QPushButton, but not of its subclasses. - - This is equivalent to \c{*[class~="QPushButton"]}. - - \row - \li ID \target ID Selector - Selector - \li \c{QPushButton#okButton} - \li Matches all QPushButton instances whose - \l{QObject::objectName}{object name} is \c okButton. - - \row - \li Descendant Selector - \li \c{QDialog QPushButton} - \li Matches all instances of QPushButton that are descendants - (children, grandchildren, etc.) of a QDialog. - - \row - \li Child Selector - \li \c{QDialog > QPushButton} - \li Matches all instances of QPushButton that are direct - children of a QDialog. - \endtable - - \section1 Sub-Controls - - For styling complex widgets, it is necessary to access subcontrols of the - widget, such as the drop-down button of a QComboBox or the up and down - arrows of a QSpinBox. Selectors may contain \e{subcontrols} that make it - possible to restrict the application of a rule to specific widget - subcontrols. For example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 5 - - The above rule styles the drop-down button of all \l{QComboBox}es. - Although the double-colon (\c{::}) syntax is reminiscent of CSS3 - Pseudo-Elements, Qt Sub-Controls differ conceptually from these and have - different cascading semantics. - - Sub-controls are always positioned with respect to another element - a - reference element. This reference element could be the widget or another - Sub-control. For example, the \l{Qt Style Sheets Reference#drop-down-sub} - {::drop-down} of a QComboBox is placed, by default, in the top right corner - of the Padding rectangle of the QComboBox. The - \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} is placed, - by default, in the Center of the Contents rectangle of the - \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} Sub-control. See - the \l{List of Stylable Widgets} below for the Sub-controls to use to - style a widget and their default positions. - - The origin rectangle to be used can be changed using the - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} - property. For example, if we want to place the drop-down in the margin - rectangle of the QComboBox instead of the default Padding rectangle, we - can specify: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 6 - - The alignment of the drop-down within the Margin rectangle is changed - using \l{Qt Style Sheets Reference#subcontrol-position-prop} - {subcontrol-position} property. - - The \l{Qt Style Sheets Reference#width-prop}{width} and - \l{Qt Style Sheets Reference#height-prop}{height} properties can be used - to control the size of the Sub-control. Note that setting a - \l{Qt Style Sheets Reference#image-prop}{image} implicitly sets the size - of a Sub-control. - - The relative positioning scheme - (\l{Qt Style Sheets Reference#position-prop}{position} : relative), - allows the position of the Sub-Control to be offset from its initial - position. For example, when the QComboBox's drop-down button is - pressed, we might like the arrow inside to be offset to give a - "pressed" effect. To achieve this, we can specify: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 7 - - The absolute positioning scheme - (\l{Qt Style Sheets Reference#position-prop}{position} : absolute), - allows the position and size of the Sub-control to be changed with - respect to the reference element. - - Once positioned, they are treated the same as widgets and can be styled - using the \l{box model}. - - See the \l{List of Sub-Controls} below for a list of supported - sub-controls, and \l{Customizing the QPushButton's Menu Indicator - Sub-Control} for a realistic example. - - \note With complex widgets such as QComboBox and QScrollBar, if one - property or sub-control is customized, \b{all} the other properties or - sub-controls must be customized as well. - - \section1 Pseudo-States - - Selectors may contain \e{pseudo-states} that denote that restrict - the application of the rule based on the widget's state. - Pseudo-states appear at the end of the selector, with a colon - (\c{:}) in between. For example, the following rule applies when - the mouse hovers over a QPushButton: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 8 - - Pseudo-states can be negated using the exclamation operator. For - example, the following rule applies when the mouse does not hover - over a QRadioButton: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 9 - - Pseudo-states can be chained, in which case a logical AND is - implied. For example, the following rule applies to when the - mouse hovers over a checked QCheckBox: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 10 - - Negated Pseudo-states may appear in Pseudo-state chains. For example, - the following rule applies when the mouse hovers over a QPushButton - that is not pressed: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 11 - - If needed, logical OR can be expressed using the comma operator: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 12 - - Pseudo-states can appear in combination with subcontrols. For - example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 13 - - See the \l{List of Pseudo-States} section below for the list of - pseudo-states provided by Qt widgets. - - \section1 Conflict Resolution - - Conflicts arise when several style rules specify the same - properties with different values. Consider the following style - sheet: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 14 - - Both rules match QPushButton instances called \c okButton and - there is a conflict for the \c color property. To resolve this - conflict, we must take into account the \e specificity of the - selectors. In the above example, \c{QPushButton#okButton} is - considered more specific than \c QPushButton, because it - (usually) refers to a single object, not to all instances of a - class. - - Similarly, selectors with pseudo-states are more specific than - ones that do not specify pseudo-states. Thus, the following style - sheet specifies that a \l{QPushButton} should have white text - when the mouse is hovering over it, otherwise red text: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 15 - - Here's a tricky one: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 16 - - Here, both selectors have the same specificity, so if the mouse - hovers over the button while it is enabled, the second rule takes - precedence. If we want the text to be white in that case, we can - reorder the rules like this: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 17 - - Alternatively, we can make the first rule more specific: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 18 - - A similar issue arises in conjunction with Type Selectors. - Consider the following example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 19 - - Both rules apply to QPushButton instances (since QPushButton - inherits QAbstractButton) and there is a conflict for the - \l{Qt Style Sheets Reference#color-prop}{color} property. Because QPushButton - inherits QAbstractButton, it might be tempting to assume that - \c QPushButton is more specific than \c QAbstractButton. However, - for style sheet computations, all Type Selectors have the same - specificity, and the rule that appears last takes precedence. In - other words, \l{Qt Style Sheets Reference#color-prop}{color} is set to \c gray - for all \l{QAbstractButton}s, including \l{QPushButton}s. If we really - want \l{QPushButton}s to have red text, we can always reorder the - rules. - - For determining the specificity of a rule, Qt Style Sheets follow - the - \l{http://www.w3.org/TR/REC-CSS2/cascade.html#specificity}{CSS2 - Specification}: - - \quotation - \e{A selector's specificity is calculated as follows:} - - \list - \li \e{count the number of ID attributes in the selector (= a)} - \li \e{count the number of other attributes and pseudo-classes in the selector (= b)} - \li \e{count the number of element names in the selector (= c)} - \li \e{ignore pseudo-elements [i.e., \l{subcontrols}].} - \endlist - - \e{Concatenating the three numbers a-b-c (in a number system with a - large base) gives the specificity.} - - \e{Some examples:} - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 20 - \endquotation - - \section1 Cascading - - Style sheets can be set on the QApplication, on parent widgets, - and on child widgets. An arbitrary widget's effective style sheet - is obtained by merging the style sheets set on the widget's - ancestors (parent, grandparent, etc.), as well as any style sheet - set on the QApplication. - - When conflicts arise, the widget's own style sheet is always - preferred to any inherited style sheet, irrespective of the - specificity of the conflicting rules. Likewise, the parent - widget's style sheet is preferred to the grandparent's, etc. - - One consequence of this is that setting a style rule on a widget - automatically gives it precedence over other rules specified in - the ancestor widgets' style sheets or the QApplication style - sheet. Consider the following example. First, we set a style - sheet on the QApplication: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 21 - - Then we set a style sheet on a QPushButton object: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 22 - - The style sheet on the QPushButton forces the QPushButton (and - any child widget) to have blue text, in spite of the more - specific rule set provided by the application-wide style sheet. - - The result would have been the same if we had written - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 23 - - except that if the QPushButton had children (which is unlikely), - the style sheet would have no impact on them. - - Style sheet cascading is a complex topic. Refer to the - \l{http://www.w3.org/TR/CSS2/cascade.html#cascade}{CSS2 - Specification} for the gory details. Be aware that Qt currently - doesn't implement \c{!important}. - - \section1 Inheritance - - In classic CSS, when font and color of an item is not explicitly set, - it gets automatically inherited from the parent. When using Qt Style Sheets, - a widget does \b{not} automatically inherit its font and color setting - from its parent widget. - - For example, consider a QPushButton inside a QGroupBox: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 24 - - The QPushButton does not have an explicit color set. Hence, instead - of inheriting color of its parent QGroupBox, it has the system color. - If we want to set the color on a QGroupBox and its children, - we can write: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 25 - - In contrast, setting a font and propagate using QWidget::setFont() and - QWidget::setPalette() propagates to child widgets. - - \section1 Widgets inside C++ namespaces - - The Type Selector can be used to style widgets of a particular type. For - example, - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 26 - - Qt Style Sheet uses QObject::className() of the widget to determine - when to apply the Type Selector. When custom widgets are inside namespaces, - the QObject::className() returns ::. This conflicts - with the syntax for \l{Sub-Controls}. To overcome this problem, - when using the Type Selector for widgets inside namespaces, we must - replace the "::" with "--". For example, - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 27 - - \section1 Setting QObject properties - - From 4.3 and above, any designable Q_PROPERTY - can be set using the qproperty- syntax. - - For example, - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 28 - - If the property references an enum declared with Q_ENUMS, you should - reference its constants by name, i.e., not their numeric value. - -*/ - -/*! - \page stylesheet-designer.html - \contentspage {Qt Style Sheet}{Contents} - \previouspage The Style Sheet Syntax - \nextpage Customizing Qt Widgets Using Style Sheets - \title Qt Designer Integration - - \l{Qt Designer}{Qt Designer} is an excellent tool - to preview style sheets. You can right-click on any widget in Designer - and select \gui{Change styleSheet...} to set the style sheet. - - \image designer-stylesheet-options.png - - In Qt 4.2 and later, \l{Qt Designer}{Qt Designer} also includes a - style sheet syntax highlighter and validator. The validator indicates - if the syntax is valid or invalid, at the bottom left of the \gui{Edit - Style Sheet} dialog. - - \image designer-validator-highlighter.png - - When you click \gui{OK} or \gui{Apply}, \QD will automatically display - the widget with its new stylesheet. - - \image designer-stylesheet-usage.png - */ - -/*! - \page stylesheet-customizing.html - \contentspage {Qt Style Sheet}{Contents} - \previouspage Qt Designer Integration - \nextpage Qt Style Sheets Reference - \title Customizing Qt Widgets Using Style Sheets - - When using style sheets, every widget is treated as a box with four - concentric rectangles: the margin rectangle, the border rectangle, the - padding rectangle, and the content rectangle. The box model describes - this in further detail. - - \tableofcontents - - \target box model - \section1 The Box Model - - The four concentric rectangles appear conceptually as below: - - \image stylesheet-boxmodel.png - - \list - \li The margin falls outside the border. - \li The border is drawn between the margin and the padding. - \li The padding falls inside the border, between the border and - the actual contents. - \li The content is what is left from the original widget or - subcontrol once we have removed the margin, the border, and - the padding. - \endlist - - The \l{Qt Style Sheets Reference#margin-prop}{margin}, - \l{Qt Style Sheets Reference#border-width-prop} - {border-width}, and - \l{Qt Style Sheets Reference#padding-prop}{padding} - properties all default to zero. In that case, all four rectangles - (\c margin, \c border, \c padding, and \c content) coincide exactly. - - You can specify a background for the widget using the - \l{Qt Style Sheets Reference#background-image-prop}{background-image} - property. By default, the background-image is drawn only for the area - inside the border. This can be changed using the - \l{Qt Style Sheets Reference#background-clip-prop}{background-clip} - property. You can use - \l{Qt Style Sheets Reference#background-repeat-prop}{background-repeat} - and - \l{Qt Style Sheets Reference#background-origin-prop}{background-origin} - to control the repetition and origin of the background image. - - A background-image does not scale with the size of the widget. To provide - a "skin" or background that scales along with the widget size, one must - use - \l{Qt Style Sheets Reference#border-image-prop}{border-image}. Since the - border-image property provides an alternate background, it is not required - to specify a background-image when border-image is specified. In the case, - when both of them are specified, the border-image draws over the - background-image. - - In addition, the \l{Qt Style Sheets Reference#image-prop}{image} property - may be used to draw an image over the border-image. The image specified does - not tile or stretch and when its size does not match the size of the widget, - its alignment is specified using the - \l{Qt Style Sheets Reference#image-position-prop}{image-position} - property. Unlike background-image and border-image, one may specify a - SVG in the image property, in which case the image is scaled automatically - according to the widget size. - - The steps to render a rule are as follows: - \list - \li Set clip for entire rendering operation (border-radius) - \li Draw the background (background-image) - \li Draw the border (border-image, border) - \li Draw overlay image (image) - \endlist - - \target sub controls - \section1 Sub-controls - - A widget is considered as a hierarchy (tree) of subcontrols drawn on top - of each other. For example, the QComboBox draws the drop-down sub-control - followed by the down-arrow sub-control. A QComboBox is thus rendered as - follows: - \list - \li Render the QComboBox { } rule - \li Render the QComboBox::drop-down { } rule - \li Render the QComboBox::down-arrow { } rule - \endlist - - Sub-controls share a parent-child relationship. In the case of QComboBox, - the parent of down-arrow is the drop-down and the parent of drop-down is - the widget itself. Sub-controls are positioned within their parent using - the \l{Qt Style Sheets Reference#subcontrol-position-prop} - {subcontrol-position} and - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} - properties. - - Once positioned, sub-controls can be styled using the \l{box model}. - - \note With complex widgets such as QComboBox and QScrollBar, if one - property or sub-control is customized, \b{all} the other properties or - sub-controls must be customized as well. - -*/ - -/*! - \page stylesheet-reference.html - \contentspage {Qt Style Sheet}{Contents} - \previouspage Customizing Qt Widgets Using Style Sheets - \nextpage Qt Style Sheets Examples - \title Qt Style Sheets Reference - - Qt Style Sheets support various properties, pseudo-states, and - subcontrols that make it possible to customize the look of - widgets. - - \tableofcontents - - \section1 List of Stylable Widgets - - The following table lists the Qt widgets that can be customized - using style sheets: - - \table 100% - \header - \li Widget - \li How to Style - - \row - \li QAbstractScrollArea \target qabstractscrollarea-widget - \li Supports the \l{box model}. - - All derivatives of QAbstractScrollArea, including QTextEdit, - and QAbstractItemView (all item view classes), support - scrollable backgrounds using - \l{Qt Style Sheets Reference#background-attachment-prop} - {background-attachment}. Setting the background-attachment to - \c{fixed} provides a background-image that does not scroll with the - viewport. Setting the background-attachment to \c{scroll}, scrolls - the background-image when the scroll bars move. - - See \l{Qt Style Sheets Examples#Customizing QAbstractScrollArea} - {Customizing QAbstractScrollArea} for an example. - - \row - \li QCheckBox \target qcheckbox-widget - \li Supports the \l{box model}. The check indicator can be - styled using the \l{#indicator-sub}{::indicator} - subcontrol. By default, the indicator is placed in the Top - Left corner of the Contents rectangle of the widget. - - The \l{#spacing-prop}{spacing} property - specifies the spacing between the check indicator and - the text. - - See \l{Qt Style Sheets Examples#Customizing QCheckBox} - {Customizing QCheckBox} for an example. - - \row - \li QColumnView \target qcolumnview-widget - \li The grip can be styled be using the \l{image-prop}{image} property. - The arrow indicators can by styled using the - \l{left-arrow-sub}{::left-arrow} subcontrol and the - \l{right-arrow-sub}{::right-arrow} subcontrol. - - \row - \li QComboBox \target qcombobox-widget - \li The frame around the combobox can be styled using the - \l{box model}. The drop-down button can be styled using - the \l{#drop-down-sub}{::drop-down} subcontrol. By default, the - drop-down button is placed in the top right corner of the padding - rectangle of the widget. The arrow mark inside the drop-down button - can be styled using the \l{#down-arrow-sub}{::down-arrow} - subcontrol. By default, the arrow is placed in the center of the - contents rectangle of the drop-down subcontrol. - - See \l{Qt Style Sheets Examples#Customizing QComboBox}{Customizing QComboBox} - for an example. - - \row - \li QDateEdit \target qdateedit-widget - \li See \l{#qspinbox-widget}{QSpinBox}. - - \row - \li QDateTimeEdit \target qdatetimeedit-widget - \li See \l{#qspinbox-widget}{QSpinBox}. - - \row - \li QDialog \target qdialog-widget - \li Supports only the \l{Qt Style Sheets Reference#background-prop}{background}, - \l{#background-clip-prop}{background-clip} and - \l{#background-origin-prop}{background-origin} properties. - - \warning Make sure you define the Q_OBJECT macro for your custom - widget. - - \row - \li QDialogButtonBox \target qdialogbuttonbox-widget - \li The layout of buttons can be altered using the - \l{#button-layout-prop}{button-layout} property. - - \row - \li QDockWidget \target qdockwidget-widget - \li Supports styling of the title bar and the title bar buttons when docked. - - The dock widget border can be styled using the \l{#border-prop}{border} - property. The \l{#title-sub}{::title} subcontrol can be used to customize - the title bar. The close and float buttons are positioned with respect - to the \l{title-sub}{::title} subcontrol using the - \l{#close-button-sub}{::close-button} and - \l{#float-button-sub}{::float-button} respectively. - - When the title bar is vertical, the \l{#vertical-ps}{:vertical} pseudo - class is set. In addition, depending on QDockWidget::DockWidgetFeature, - the \l{#closable-ps}{:closable}, \l{#floatable-ps}{:floatable} and - \l{#movable-ps}{:movable} pseudo states are set. - - \note Use QMainWindow::separator to style the resize handle. - - \warning The style sheet has no effect when the QDockWidget is undocked - as Qt uses native top level windows when undocked. - - See \l{Qt Style Sheets Examples#Customizing QDockWidget} - {Customizing QDockWidget} for an example. - - \row - \li QDoubleSpinBox \target qdoublespinbox-widget - \li See \l{#qspinbox-widget}{QSpinBox}. - - \row - \li QFrame \target qframe-widget - \li Supports the \l{box model}. - - Since 4.3, setting a stylesheet on a QLabel automatically - sets the QFrame::frameStyle property to QFrame::StyledPanel. - - See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} - for an example. - - \row - \li QGroupBox \target qgroupbox-widget - \li Supports the \l{box model}. The title can be styled using the - \l{#title-sub}{::title} subcontrol. By default, the title is placed - depending on QGroupBox::textAlignment. - - In the case of a checkable QGroupBox, the title includes the - check indicator. The indicator is styled using the - the \l{#indicator-sub}{::indicator} subcontrol. The - \l{#spacing-prop}{spacing} property can be used to control - the spacing between the text and indicator. - - See \l{Qt Style Sheets Examples#Customizing QGroupBox}{Customizing QGroupBox} - for an example. - - \row - \li QHeaderView \target qheaderview-widget - \li Supports the \l{box model}. The sections of the header view are - styled using the \l{#section-sub}{::section} sub control. The - \c{section} Sub-control supports the \l{#middle-ps}{:middle}, - \l{#first-ps}{:first}, \l{#last-ps}{:last}, - \l{#only-one-ps}{:only-one}, \l{#next-selected-ps}{:next-selected}, - \l{#previous-selected-ps}{:previous-selected}, - \l{#selected-ps}{:selected}, - and \l{#checked-ps}{:checked} pseudo states. - - Sort indicator in can be styled using the - \l{#up-arrow-sub}{::up-arrow} and the - \l{#down-arrow-sub}{::down-arrow} Sub-control. - - See \l{Qt Style Sheets Examples#Customizing QHeaderView}{Customizing QHeaderView} - for an example. - - \row - \li QLabel \target qlabel-widget - \li Supports the \l{box model}. Does not support the - \l{#hover-ps}{:hover} pseudo-state. - - Since 4.3, setting a stylesheet on a QLabel automatically - sets the QFrame::frameStyle property to QFrame::StyledPanel. - - See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an - example (a QLabel derives from QFrame). - - \row - \li QLineEdit \target qlineedit-widget - \li Support the \l{box model}. - - The color and background of the selected item is styled using - \l{#selection-color-prop}{selection-color} and - \l{#selection-background-color-prop}{selection-background-color} - respectively. - - The password character can be styled using the - \l{#lineedit-password-character-prop}{lineedit-password-character} - property. - - See \l{Qt Style Sheets Examples#Customizing QLineEdit}{Customizing QLineEdit} - for an example. - - \row - \li QListView \target qlistview-widget - \li Supports the \l{box model}. When - \l{QAbstractItemView::alternatingRowColors}{alternating row colors} - is enabled, the alternating colors can be styled using the - \l{#alternate-background-color-prop}{alternate-background-color} - property. - - The color and background of the selected item is styled using - \l{#selection-color-prop}{selection-color} and - \l{#selection-background-color-prop}{selection-background-color} - respectively. - - The selection behavior is controlled by the - \l{#show-decoration-selected-prop}{show-decoration-selected} property. - - Use the \l{#item-sub}{::item} subcontrol for more fine grained - control over the items in the QListView. - - See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to - style scrollable backgrounds. - - See \l{Qt Style Sheets Examples#Customizing QListView} - {Customzing QListView} for an example. - - \row - \li QListWidget \target qlistwidget-widget - \li See \l{#qlistview-widget}{QListView}. - - \row - \li QMainWindow \target qmainwindow-widget - \li Supports styling of the separator - - The separator in a QMainWindow when using QDockWidget is styled - using the \l{#separator-sub}{::separator} subcontrol. - - See \l{Qt Style Sheets Examples#Customizing QMainWindow}{Customizing QMainWindow} - for an example. - - \row - \li QMenu \target qmenu-widget - \li Supports the \l{box model}. - - Individual items are styled using the \l{#item-sub}{::item} - subcontrol. In addition to the usually supported pseudo states, - \c{item} subcontrol supports the - \l{#selected-ps}{:selected}, \l{#default-ps}{:default}, - \l{#exclusive-ps}{:exclusive} and the - \l{#non-exclusive-ps}{non-exclusive} pseudo states. - - The indicator of checkable menu items is styled using the - \l{#indicator-sub}{::indicator} subcontrol. - - The separator is styled using the \l{#separator-sub}{::separator} - subcontrol. - - For items with a sub menu, the arrow marks are styled using the - \l{right-arrow-sub}{right-arrow} and - \l{left-arrow-sub}{left-arrow}. - - The scroller is styled using the \l{#scroller-sub}{::scroller}. - - The tear-off is styled using the \l{#tearoff-sub}{::tearoff}. - - See \l{Qt Style Sheets Examples#Customizing QMenu}{Customizing QMenu} - for an example. - - \row - \li QMenuBar \target qmenubar-widget - \li Supports the \l{box model}. The \l{#spacing-prop}{spacing} - property specifies the spacing between menu items. - Individual items are styled using the \l{#item-sub}{::item} - subcontrol. - - \warning When running on Qt/Mac, the menu bar is usually embedded into the - system-wide menu bar. In this case, the style sheet will have no effect. - - See \l{Qt Style Sheets Examples#Customizing QMenuBar}{Customizing QMenuBar} - for an example. - - \row - \li QMessageBox \target qmessagebox-widget - \li The \l{#messagebox-text-interaction-flags-prop} - {messagebox-text-interaction-flags} property can be used to alter - the interaction with text in the message box. - - \row - \li QProgressBar \target qprogressbar-widget - \li Supports the \l{box model}. The chunks of the progress bar - can be styled using the \l{#chunk-sub}{::chunk} subcontrol. - The chunk is displayed on the Contents rectangle of the widget. - - If the progress bar displays text, use the \l{text-align-prop}{text-align} - property to position the text. - - Indeterminate progress bars have the - \l{#indeterminate-ps}{:indeterminate} pseudo state set. - - See \l{Qt Style Sheets Examples#Customizing QProgressBar}{Customizing QProgressBar} - for an example. - - \row - \li QPushButton \target qpushbutton-widget - \li Supports the \l{box model}. Supports the \l{#default-ps}{:default}, - \l{#flat-ps}{:flat}, \l{#checked-ps}{:checked} pseudo states. - - For QPushButton with a menu, the menu indicator is styled - using the \l{#menu-indicator-sub}{::menu-indicator} - subcontrol. Appearance of checkable push buttons can be - customized using the \l{#open-ps}{:open} and - \l{#closed-ps}{:closed} pseudo-states. - - \warning If you only set a background-color on a QPushButton, the background - may not appear unless you set the border property to some value. This is - because, by default, the QPushButton draws a native border which completely - overlaps the background-color. For example, - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 30 - - See \l{Qt Style Sheets Examples#Customizing QPushButton}{Customizing QPushButton} - for an example. - - \row - \li QRadioButton \target qradiobutton-widget - \li Supports the \l{box model}. The check indicator can be - styled using the \l{#indicator-sub}{::indicator} - subcontrol. By default, the indicator is placed in the Top - Left corner of the Contents rectangle of the widget. - - The \l{#spacing-prop}{spacing} property - specifies the spacing between the check indicator and - the text. - - See \l{Qt Style Sheets Examples#Customizing QRadioButton} - {Customizing QRadioButton} for an example. - - \row - \li QScrollBar \target qscrollbar-widget - \li Supports the \l{box model}. The Contents rectangle of the widget - is considered to be the groove over which the slider moves. The extent - of the QScrollBar (i.e the width or the height depending on the orientation) - is set using the \l{#width-prop}{width} or \l{#height-prop}{height} property - respectively. To determine the orientation, use the - \l{#horizontal-ps}{:horizontal} and the \l{vertical-ps}{:vertical} - pseudo states. - - The slider can be styled using the \l{#handle-sub}{::handle} subcontrol. - Setting the \l{#min-width-prop}{min-width} or \l{#min-height-prop}{min-height} - provides size contraints for the slider depending on the orientation. - - The \l{add-line-sub}{::add-line} subcontrol can be used to style the - button to add a line. By default, the add-line subcontrol is placed in - top right corner of the Border rectangle of the widget. Depending on the - orientation the \l{#right-arrow-sub}{::right-arrow} or - \l{#down-arrow-sub}{::down-arrow}. By default, the arrows are placed in - the center of the Contents rectangle of the add-line subcontrol. - - The \l{sub-line-sub}{::sub-line} subcontrol can be used to style the - button to subtract a line. By default, the sub-line subcontrol is placed in - bottom right corner of the Border rectangle of the widget. Depending on the - orientation the \l{#left-arrow-sub}{::left-arrow} or - \l{#up-arrow-sub}{::up-arrow}. By default, the arrows are placed in - the center of the Contents rectangle of the sub-line subcontrol. - - The \l{sub-page-sub}{::sub-page} subcontrol can be used to style the - region of the slider that subtracts a page. The \l{add-page-sub}{::add-page} - subcontrol can be used to style the region of the slider that adds a page. - - See \l{Qt Style Sheets Examples#Customizing QScrollBar}{Customizing QScrollBar} - for an example. - - \row - \li QSizeGrip \target qsizegrip-widget - \li Supports the \l{#width-prop}{width}, - \l{#height-prop}{height}, and \l{#image-prop}{image} - properties. - - See \l{Qt Style Sheets Examples#Customizing QSizeGrip}{Customizing QSizeGrip} - for an example. - - \row - \li QSlider \target qslider-widget - \li Supports the \l{box model}. For horizontal slides, the - \l{min-width-prop}{min-width} and \l{height-prop}{height} - properties must be provided. For vertical sliders, the - \l{min-height-prop}{min-height} and \l{width-prop}{width} - properties must be provided. - - The groove of the slider is styled - using the \l{#groove-sub}{::groove}. The groove is - positioned by default in the Contents rectangle of the widget. - The thumb of the slider is styled using \l{#handle-sub}{::handle} - subcontrol. The subcontrol moves in the Contents rectangle of - the groove subcontrol. - - See \l{Qt Style Sheets Examples#Customizing QSlider}{Customizing QSlider} - for an example. - - \row - \li QSpinBox \target qspinbox-widget - \li The frame of the spin box can be styled using the \l{box - model}. - - The up button and arrow can be styled using the - \l{#up-button-sub}{::up-button} and - \l{#up-arrow-sub}{::up-arrow} subcontrols. By default, - the up-button is placed in the top right corner in the - Padding rectangle of the widget. Without an explicit size, - it occupies half the height of its reference rectangle. - The up-arrow is placed in the center of the Contents - rectangle of the up-button. - - The down button and arrow can be styled using the - \l{#down-button-sub}{::down-button} and - \l{#down-arrow-sub}{::down-arrow} subcontrols. By default, - the down-button is placed in the bottom right corner in the - Padding rectangle of the widget. Without an explicit size, - it occupies half the height of its reference rectangle. - The bottom-arrow is placed in the center of the Contents - rectangle of the bottom-button. - - See \l{Qt Style Sheets Examples#Customizing QSpinBox}{Customizing QSpinBox} - for an example. - - \row - \li QSplitter \target qsplitter-widget - \li Supports the \l{box model}. The handle of the splitter - is styled using the \l{#handle-sub}{::handle} subcontrol. - - See \l{Qt Style Sheets Examples#Customizing QSplitter}{Customizing QSplitter} - for an example. - - \row - \li QStatusBar \target qstatusbar-widget - \li Supports only the \l{Qt Style Sheets Reference#background-prop} - {background} property. - The frame for individual items can be style using the - \l{#item-sub}{::item} subcontrol. - - See \l{Qt Style Sheets Examples#Customizing QStatusBar}{Customizing QStatusBar} - for an example. - - \row - \li QTabBar \target qtabbar-widget - \li Individual tabs may be styled using the \l{#tab-sub}{::tab} subcontrol. - Close buttons using the \l{#close-button-sub}{::close-button} - The tabs support the - \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first}, - \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, - \l{#previous-selected-ps}{:previous--selected}, - \l{#next-selected-ps}{:next-selected}, - \l{#selected-ps}{:selected} pseudo states. - - The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, - \l{#bottom-ps}{:bottom} pseudo states depending on the orientation - of the tabs. - - Overlapping tabs for the selected state are created by using - negative margins or using the \c{absolute} position scheme. - - The tear indicator of the QTabBar is styled using the - \l{#tear-sub}{::tear} subcontrol. - - QTabBar used two QToolButtons for its scrollers that can be styled - using the \c{QTabBar QToolButton} selector. To specify the width - of the scroll button use the \l{#scroller-sub}{::scroller} - subcontrol. - - The alignment of the tabs within the QTabBar is styled - using the \l{#Alignment}{alignment} property. \warning - - To change the position of the QTabBar within a QTabWidget, use the - \l{#tab-bar-sub}{tab-bar} subcontrol (and set subcontrol-position). - - See \l{Qt Style Sheets Examples#Customizing QTabWidget and QTabBar}{Customizing QTabBar} - for an example. - - \row - \li QTabWidget \target qtabwidget-widget - \li The frame of the tab widget is styled using the - \l{#pane-sub}{::pane} subcontrol. The left and right - corners are styled using the \l{#left-corner-sub}{::left-corner} - and \l{#right-corner-sub}{::right-corner} respectively. - The position of the tab bar is controlled using the - \l{#tab-bar-sub}{::tab-bar} subcontrol. - - By default, the subcontrols have positions of a QTabWidget in - the QWindowsStyle. To place the QTabBar in the center, set the - subcontrol-position of the tab-bar subcontrol. - - The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, - \l{#bottom-ps}{:bottom} pseudo states depending on the orientation - of the tabs. - - See \l{Qt Style Sheets Examples#Customizing QTabWidget and QTabBar} - {Customizing QTabWidget} for an example. - - \row - \li QTableView \target qtableview-widget - \li Supports the \l{box model}. When - \l{QAbstractItemView::alternatingRowColors}{alternating row colors} - is enabled, the alternating colors can be styled using the - \l{#alternate-background-color-prop}{alternate-background-color} - property. - - The color and background of the selected item is styled using - \l{#selection-color-prop}{selection-color} and - \l{#selection-background-color-prop}{selection-background-color} - respectively. - - The corner widget in a QTableView is implemented as a QAbstractButton - and can be styled using the "QTableView QTableCornerButton::section" - selector. - - \warning If you only set a background-color on a QTableCornerButton, - the background may not appear unless you set the border property to - some value. This is because, by default, the QTableCornerButton draws a - native border which completely overlaps the background-color. - - The color of the grid can be specified using the - \l{#gridline-color-prop}{gridline-color} property. - - See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to - style scrollable backgrounds. - - See \l{Qt Style Sheets Examples#Customizing QTableView} - {Customzing QTableView} for an example. - - \row - \li QTableWidget \target qtablewidget-widget - \li See \l{#qtableview-widget}{QTableView}. - - \row - \li QTextEdit \target qtextedit-widget - \li Supports the \l{box model}. - - The color and background of selected text is styled using - \l{#selection-color-prop}{selection-color} and - \l{#selection-background-color-prop}{selection-background-color} - respectively. - - See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to - style scrollable backgrounds. - - \row - \li QTimeEdit \target qtimeedit-widget - \li See \l{#qspinbox-widget}{QSpinBox}. - - \row - \li QToolBar \target qtoolbar-widget - \li Supports the \l{box model}. - - The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, - \l{#bottom-ps}{:bottom} pseudo states depending on the area in - which the tool bar is grouped. - - The \l{#first-ps}{:first}, \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, - \l{#only-one-ps}{:only-one} pseudo states indicator the position - of the tool bar within a line group (See - QStyleOptionToolBar::positionWithinLine). - - The separator of a QToolBar is styled using the - \l{#separator-sub}{::separator} subcontrol. - - The handle (to move the toolbar) is styled using the - \l{#handle-sub}{::handle} subcontrol. - - See \l{Qt Style Sheets Examples#Customizing QToolBar}{Customizing QToolBar} - for an example. - - \row - \li QToolButton \target qtoolbutton-widget - \li Supports the \l{box model}. - - If the QToolButton has a menu, is - \l{#menu-indicator-sub}{::menu-indicator} subcontrol can be used to - style the indicator. By default, the menu-indicator is positioned - at the bottom right of the Padding rectangle of the widget. - - If the QToolButton is in QToolButton::MenuButtonPopup mode, - the \l{#menu-button-sub}{::menu-button} subcontrol is used to draw the - menu button. \l{#menu-arrow-sub}{::menu-arrow} subcontrol is used to - draw the menu arrow inside the menu-button. By default, it is - positioned in the center of the Contents rectangle of the - menu-button subcontrol. - - When the QToolButton displays arrows, the \l{#up-arrow-sub}{::up-arrow}, - \l{#down-arrow-sub}{::down-arrow}, \l{#left-arrow-sub}{::left-arrow} - and \l{#right-arrow-sub}{::right-arrow} subcontrols are used. - - \warning If you only set a background-color on a QToolButton, the background - will not appear unless you set the border property to some value. This is - because, by default, the QToolButton draws a native border which completely - overlaps the background-color. For example, - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 31 - - See \l{Qt Style Sheets Examples#Customizing QToolButton}{Customizing QToolButton} - for an example. - - \row - \li QToolBox \target qtoolbox-widget - \li Supports the \l{box model}. - - The individual tabs can by styled using the - \l{#tab-sub}{::tab} subcontrol. The tabs support the - \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first}, - \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, - \l{#previous-selected-ps}{:previous-selected}, - \l{#next-selected-ps}{:next-selected}, - \l{#selected-ps}{:selected} pseudo states. - - \row - \li QToolTip \target qtooltip-widget - \li Supports the \l{box model}. The \l{#opacity-prop}{opacity} - property controls the opacity of the tooltip. - - See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} - for an example (a QToolTip is a QFrame). - - \row - \li QTreeView \target qtreeview-widget - \li Supports the \l{box model}. When - \l{QAbstractItemView::alternatingRowColors}{alternating row colors} - is enabled, the alternating colors can be styled using the - \l{#alternate-background-color-prop}{alternate-background-color} - property. - - The color and background of the selected item is styled using - \l{#selection-color-prop}{selection-color} and - \l{#selection-background-color-prop}{selection-background-color} - respectively. - - The selection behavior is controlled by the - \l{#show-decoration-selected-prop}{show-decoration-selected} property. - - The branches of the tree view can be styled using the - \l{#branch-sub}{::branch} subcontrol. The - ::branch Sub-control supports the \l{open-ps}{:open}, - \l{closed-ps}{:closed}, \l{has-siblings-ps}{:has-sibling} and - \l{has-children-ps}{:has-children} pseudo states. - - Use the \l{#item-sub}{::item} subcontrol for more fine grained - control over the items in the QTreeView. - - See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to - style scrollable backgrounds. - - See \l{Qt Style Sheets Examples#Customizing QTreeView}{Customizing QTreeView} - for an example to style the branches. - - \row - \li QTreeWidget \target qtreewidget-widget - \li See \l{#qtreeview-widget}{QTreeView}. - - \row - \li QWidget \target qwidget-widget - \li Supports only the \l{Qt Style Sheets Reference#background-prop}{background}, - \l{#background-clip-prop}{background-clip} and - \l{#background-origin-prop}{background-origin} properties. - - If you subclass from QWidget, you need to provide a paintEvent for your - custom QWidget as below: - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 32 - - The above code is a no-operation if there is no stylesheet set. - - \warning Make sure you define the Q_OBJECT macro for your custom - widget. - - \endtable - - \section1 List of Properties - - The table below lists all the properties supported by Qt Style - Sheets. Which values can be given to an property depend on the - \l{List of Property Types}{property's type}. Unless otherwise - specified, properties below apply to all widgets. Properties - marked with an asterisk * are specific to Qt and have no equivalent - in CSS2 or CSS3. - - \table 100% - \header - \li Property - \li Type - \li Description - - \row - \li \b{\c alternate-background-color} \target alternate-background-color-prop - \li \l{#Brush}{Brush} \BR - \li The \l{QAbstractItemView::alternatingRowColors} - {alternate background color} used in QAbstractItemView subclasses. - - If this property is not set, the default value is - whatever is set for the palette's - \l{QPalette::}{AlternateBase} role. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 33 - - See also \l{Qt Style Sheets Reference#background-prop}{background} and - \l{#selection-background-color-prop}{selection-background-color}. - - \row - \li \b{\c background} \target background-prop - \li \l{#Background}{Background} - \li Shorthand notation for setting the background. Equivalent - to specifying \c background-color, \c background-image, \c - background-repeat, and/or \c background-position. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QDialog, QFrame, QGroupBox, QLabel, QLineEdit, - QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, - QTextEdit, QToolTip, and plain \l{QWidget}s. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 34 - - - Often, it is required to set a fill pattern similar to the styles - in Qt::BrushStyle. You can use the background-color property for - Qt::SolidPattern, Qt::RadialGradientPattern, Qt::LinearGradientPattern - and Qt::ConicalGradientPattern. The other patterns are easily achieved - by creating a background image that contains the pattern. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 35 - - See also \l{#background-origin-prop}{background-origin}, - \l{#selection-background-color-prop}{selection-background-color}, - \l{#background-clip-prop}{background-clip}, - \l{#background-attachment-prop}{background-attachment} - and \l{#alternate-background-color-prop}{alternate-background-color}. - - \row - \li \c background-color \target background-color-prop - \li \l{#Brush}{Brush} \BR - \li The background color used for the widget. - - Examples: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 36 - - \row - \li \c background-image \target background-image-prop - \li \l{#Url}{Url} - \li The background image used for the widget. Semi-transparent - parts of the image let the \c background-color shine - through. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 37 - - \row - \li \c background-repeat \target background-repeat-prop - \li \l{#Repeat}{Repeat} - \li Whether and how the background image is repeated to fill - the \c background-origin rectangle. - - If this property is not specified, the background image - is repeated in both directions (\c repeat). - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 38 - - \row - \li \c background-position - \li \l{#Alignment}{Alignment} - \li The alignment of the background image within the \c - background-origin rectangle. - - If this property is not specified, the alignment is \c - top \c left. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 39 - - \row - \li \b{\c background-attachment} \target background-attachment-prop - \li \l{#Attachment}{Attachment} - \li Determines whether the background-image in a QAbstractScrollArea - is scrolled or fixed with respect to the viewport. - By default, the background-image scrolls with the viewport. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 40 - - See also \l{Qt Style Sheets Reference#background-prop}{background} - - \row - \li \b{\c background-clip} \target background-clip-prop - \li \l{#Origin}{Origin} - \li The widget's rectangle, in which the \c background is drawn. - - This property specifies the rectangle to which the \c background-color - and \c background-image are clipped. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QDialog, QFrame, QGroupBox, QLabel, - QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, - and plain \l{QWidget}s. - - If this property is not specified, the default is \c - border. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 41 - - See also \l{Qt Style Sheets Reference#background-prop}{background}, - \l{#background-origin-prop}{background-origin} and \l{The Box Model}. - - \row - \li \b{\c background-origin} \target background-origin-prop - \li \l{#Origin}{Origin} - \li The widget's background rectangle, to use in conjunction - with \c background-position and \c background-image. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QDialog, QFrame, QGroupBox, QLabel, - QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, - and plain \l{QWidget}s. - - If this property is not specified, the default is \c - padding. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 42 - - See also \l{Qt Style Sheets Reference#background-prop}{background} and - \l{The Box Model}. - - \row - \li \b{\c border} \target border-prop - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's border. Equivalent - to specifying \c border-color, \c border-style, and/or - \c border-width. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, - QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, - QTextEdit, QToolTip, and plain \l{QWidget}s. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 43 - - \row - \li \c border-top - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's top border. - Equivalent to specifying \c border-top-color, \c - border-top-style, and/or \c border-top-width. - - \row - \li \c border-right - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's right border. - Equivalent to specifying \c border-right-color, \c - border-right-style, and/or \c border-right-width. - - \row - \li \c border-bottom - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's bottom border. - Equivalent to specifying \c border-bottom-color, \c - border-bottom-style, and/or \c border-bottom-width. - - \row - \li \c border-left - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's left border. - Equivalent to specifying \c border-left-color, \c - border-left-style, and/or \c border-left-width. - - \row - \li \b{\c border-color} \target border-attrs - \target border-color-prop - \li \l{#Box Colors}{Box Colors} - \li The color of all the border's edges. Equivalent to - specifying \c border-top-color, \c border-right-color, \c - border-bottom-color, and \c border-left-color. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, - QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, - QTextEdit, QToolTip, and plain \l{QWidget}s. - - If this property is not specified, it defaults to - \l{#color-prop}{color} (i.e., the widget's foreground - color). - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 44 - - See also \l{Qt Style Sheets Reference#border-style-prop}{border-style}, - \l{Qt Style Sheets Reference#border-width-prop}{border-width}, - \l{#border-image-prop}{border-image}, and \l{The Box Model}. - - \row - \li \c border-top-color - \li \l{#Brush}{Brush} \BR - \li The color of the border's top edge. - - \row - \li \c border-right-color - \li \l{#Brush}{Brush} \BR - \li The color of the border's right edge. - - \row - \li \c border-bottom-color - \li \l{#Brush}{Brush} \BR - \li The color of the border's bottom edge. - - \row - \li \c border-left-color - \li \l{#Brush}{Brush} \BR - \li The color of the border's left edge. - - \row - \li \b{\c border-image} \target border-image-prop - \li \l{#Border Image}{Border Image} - \li The image used to fill the border. The image is cut into - nine parts and stretched appropriately if necessary. See - \l{#Border Image}{Border Image} for details. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, - QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, - QTextEdit and QToolTip. - - See also \l{#border-color-prop}{border-color}, - \l{Qt Style Sheets Reference#border-style-prop}{border-style}, - \l{Qt Style Sheets Reference#border-width-prop}{border-width}, and - \l{The Box Model}. - - \row - \li \b{\c border-radius} \target border-radius-prop - \li \l{#Radius}{Radius} - \li The radius of the border's corners. Equivalent to - specifying \c border-top-left-radius, \c - border-top-right-radius, \c border-bottom-right-radius, - and \c border-bottom-left-radius. - - The border-radius clips the element's - \l{Qt Style Sheets Reference#background-prop}{background}. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, - and QToolTip. - - If this property is not specified, it defaults to 0. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 45 - - See also \l{Qt Style Sheets Reference#border-width-prop}{border-width} and - \l{The Box Model}. - - \row - \li \c border-top-left-radius - \li \l{#Radius}{Radius} - \li The radius of the border's top-left corner. - - \row - \li \c border-top-right-radius - \li \l{#Radius}{Radius} - \li The radius of the border's top-right corner. - - \row - \li \c border-bottom-right-radius - \li \l{#Radius}{Radius} - \li The radius of the border's bottom-right corner. Setting - this property to a positive value results in a rounded - corner. - - \row - \li \c border-bottom-left-radius - \li \l{#Radius}{Radius} - \li The radius of the border's bottom-left corner. Setting this - property to a positive value results in a rounded corner. - - \row - \li \b{\c border-style} \target border-style-prop - \li \l {Border Style} - \li The style of all the border's edges. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, - and QToolTip. - - If this property is not specified, it defaults to \c none. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 46 - - See also \l{#border-color-prop}{border-color}, - \l{Qt Style Sheets Reference#border-style-prop}{border-style}, - \l{#border-image-prop}{border-image}, and \l{The Box Model}. - - \row - \li \c border-top-style - \li \l{#Border Style}{Border Style} - \li The style of the border's top edge. - - \row - \li \c border-right-style - \li \l{#Border Style}{Border Style} - \li The style of the border's right edge/ - - \row - \li \c border-bottom-style - \li \l{#Border Style}{Border Style} - \li The style of the border's bottom edge. - - \row - \li \c border-left-style - \li \l{#Border Style}{Border Style} - \li The style of the border's left edge. - - \row - \li \b{\c border-width} \target border-width-prop - \li \l{#Box Lengths}{Box Lengths} - \li The width of the border. Equivalent to setting \c - border-top-width, \c border-right-width, \c - border-bottom-width, and \c border-left-width. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, - and QToolTip. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 47 - - See also \l{#border-color-prop}{border-color}, - \l{#border-radius-prop}{border-radius}, - \l{Qt Style Sheets Reference#border-style-prop}{border-style}, - \l{#border-image-prop}{border-image}, and - \l{The Box Model}. - - \row - \li \c border-top-width - \li \l{#Length}{Length} - \li The width of the border's top edge. - - \row - \li \c border-right-width - \li \l{#Length}{Length} - \li The width of the border's right edge. - - \row - \li \c border-bottom-width - \li \l{#Length}{Length} - \li The width of the border's bottom edge. - - \row - \li \c border-left-width - \li \l{#Length}{Length} - \li The width of the border's left edge. - - \row - \li \b{\c bottom} \target bottom-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the - default), moves a \l{subcontrol} by a certain offset up; - specifying \tt{bottom: \e{y}} is then equivalent to - specifying \tt{\l{Qt Style Sheets Reference#top-prop}{top}: -\e{y}}. - - If \l{#position-prop}{position} is \c absolute, the \c - bottom property specifies the subcontrol's bottom edge - in relation to the parent's bottom edge (see also - \l{Qt Style Sheets Reference#subcontrol-origin-prop} - {subcontrol-origin}). - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 48 - - See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and - \l{Qt Style Sheets Reference#top-prop}{top}. - - \row - \li \b{\c button-layout} \target button-layout-prop - \li \l{#Number}{Number} - \li The layout of buttons in a QDialogButtonBox or - a QMessageBox. The possible values are 0 - (\l{QDialogButtonBox::}{WinLayout}), 1 - (\l{QDialogButtonBox::}{MacLayout}), 2 - (\l{QDialogButtonBox::}{KdeLayout}), and 3 - (\l{QDialogButtonBox::}{GnomeLayout}). - - If this property is not specified, it defaults to the - value specified by the current style for the - \l{QStyle::}{SH_DialogButtonLayout} style hint. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 49 - - \row - \li \b{\c color} \target color-prop - \li \l{#Brush}{Brush} \BR - \li The color used to render text. - - This property is supported by all widgets that respect - the \l QWidget::palette. - - If this property is not set, the default is whatever is - set for in the widget's palette for the - QWidget::foregroundRole (typically black). - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 50 - - See also \l{Qt Style Sheets Reference#background-prop}{background} and - \l{#selection-color-prop}{selection-color}. - - \row - \li \b{\c dialogbuttonbox-buttons-have-icons} - \li \l{#Boolean}{Boolean} - \li Whether the buttons in a QDialogButtonBox show icons - - If this property is set to 1, the buttons of a QDialogButtonBox - show icons; if it is set to 0, the icons are not shown. - - See the \l{Qt Style Sheets Reference#list of icons}{List of Icons} - section for information on how to set icons. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 51 - - \note Styles defining this property must be applied before the - QDialogButtonBox is created; this means that you must apply the - style to the parent widget or to the application itself. - - \omit - \row - \li \b{\c etch-disabled-text}* - \li \l{#Boolean}{Boolean} - \li Whether disabled text is drawn etched. - - If this property is not specified, it defaults to the - value specified by the current style for the - \l{QStyle::}{SH_EtchDisabledText} style hint. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 52 - \endomit - - \row - \li \b{\c font} \target font-prop - \li \l{#Font}{Font} - \li Shorthand notation for setting the text's font. Equivalent - to specifying \c font-family, \c font-size, \c font-style, - and/or \c font-weight. - - This property is supported by all widgets that respect - the \l QWidget::font. - - If this property is not set, the default is the - QWidget::font. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 53 - - \row - \li \c font-family - \li String - \li The font family. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 54 - - \row - \li \c font-size - \li \l{#Font Size}{Font Size} - \li The font size. In this version of Qt, only pt and px metrics are - supported. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 55 - - \row - \li \c font-style - \li \l {Font Style} - \li The font style. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 56 - - \row - \li \c font-weight - \li \l{#Font Weight}{Font Weight} - \li The weight of the font. - - \row - \li \b{\c gridline-color}* \target gridline-color-prop - \li \l{#Color}{Color} \BR - \li The color of the grid line in a QTableView. - - If this property is not specified, it defaults to the - value specified by the current style for the - \l{QStyle::}{SH_Table_GridLineColor} style hint. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 57 - - \row - \li \b{\c height} \target height-prop - \li \l{#Length}{Length} - \li The height of a \l{subcontrol} (or in some case, a widget). - - If this property is not specified, it defaults to a value - that depends on the subcontrol/widget and on the current style. - - \warning Unless otherwise specified, this property has no effect - when set on widgets. If you want a widget with a fixed height, set - the \l{#min-width-prop}{min-height} and - \l{#max-width-prop}{max-height} to the same value. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 58 - - See also \l{#width-prop}{width}. - - \row - \li \b{\c icon-size} \target icon-size-prop - \li \l{#Length}{Length} - \li The width and height of the icon in a widget. - - The icon size of the following widgets can be set using this - property. - \list - \li QCheckBox - \li QListView - \li QPushButton - \li QRadioButton - \li QTabBar - \li QToolBar - \li QToolBox - \li QTreeView - \endlist - - \row - \li \b{\c image}* \target image-prop - \li \l{#Url}{Url}+ - \li The image that is drawn in the contents rectangle of a - \l{subcontrol}. - - The image property accepts a list of \l{#Url}{Url}s or - an \c{svg}. The actual image that is drawn is determined - using the same algorithm as QIcon (i.e) the image is never scaled - up but always scaled down if necessary. If a \c{svg} is specified, - the image is scaled to the size of the contents rectangle. - - Setting the image property on sub controls implicitly sets the - width and height of the sub-control (unless the image in a SVG). - - In Qt 4.3 and later, the alignment of the - image within the rectangle can be specified using - \l{image-position-prop}{image-position}. - - This property is for \l{subcontrol}s only--we don't support it for - other elements. - - \warning The QIcon SVG plugin is needed to render SVG images. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 59 - - \row - \li \b{\c image-position} \target image-position-prop - \li \l{#Alignment}{alignment} - \li In Qt 4.3 and later, the alignment of the image image's position can be specified - using relative or absolute position. - - \row - \li \b{\c left} \target left-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the - default), moves a \l{subcontrol} by a certain offset to - the right. - - If \l{#position-prop}{position} is \c absolute, the \c - left property specifies the subcontrol's left edge in - relation to the parent's left edge (see also - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}). - - If this property is not specified, it defaults to \c 0. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 60 - - See also \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and - \l{#bottom-prop}{bottom}. - - \row - \li \b{\c lineedit-password-character*} \target lineedit-password-character-prop - \li \l{#Number}{Number} - \li The QLineEdit password character as a Unicode number. - - If this property is not specified, it defaults to the - value specified by the current style for the - \l{QStyle::}{SH_LineEdit_PasswordCharacter} style hint. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 61 - - \row - \li \b{\c margin} \target margin-prop - \li \l {Box Lengths} - \li The widget's margins. Equivalent to specifying \c - margin-top, \c margin-right, \c margin-bottom, and \c - margin-left. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, - and QToolTip. - - If this property is not specified, it defaults to \c 0. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 62 - - See also \l{Qt Style Sheets Reference#padding-prop}{padding}, - \l{#spacing-prop}{spacing}, and \l{The Box Model}. - - \row - \li \c margin-top - \li \l{#Length}{Length} - \li The widget's top margin. - - \row - \li \c margin-right - \li \l{#Length}{Length} - \li The widget's right margin. - - \row - \li \c margin-bottom - \li \l{#Length}{Length} - \li The widget's bottom margin. - - \row - \li \c margin-left - \li \l{#Length}{Length} - \li The widget's left margin. - - \row - \li \b{\c max-height} \target max-height-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's maximum height. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, - QSplitter, QStatusBar, QTextEdit, and QToolTip. - - The value is relative to the contents rect in the \l{The - Box Model}{box model}. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 63 - - See also \l{#max-width-prop}{max-width}. - - \row - \li \b{\c max-width} \target max-width-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's maximum width. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, - QSplitter, QStatusBar, QTextEdit, and QToolTip. - - The value is relative to the contents rect in the \l{The - Box Model}{box model}. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 64 - - See also \l{#max-height-prop}{max-height}. - - - \row - \li \b{\c messagebox-text-interaction-flags*} \target messagebox-text-interaction-flags-prop - \li \l{#Number}{Number} - \li The interaction behavior for text in a message box. - Possible values are based on Qt::TextInteractionFlags. - - If this property is not specified, it defaults to the - value specified by the current style for the - \l{QStyle::}{SH_MessageBox_TextInteractionFlags} style - hint. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 65 - - \row - \li \b{\c min-height} \target min-height-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's minimum height. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, - QSplitter, QStatusBar, QTextEdit, and QToolTip. - - If this property is not specified, the minimum height is - derived based on the widget's contents and the style. - - The value is relative to the contents rect in the \l{The - Box Model}{box model}. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 66 - - See also \l{#min-width-prop}{min-width}. - - \row - \li \b{\c min-width} \target min-width-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's minimum width. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, - QSplitter, QStatusBar, QTextEdit, and QToolTip. - - If this property is not specified, the minimum width is - derived based on the widget's contents and the style. - - The value is relative to the contents rect in the \l{The - Box Model}{box model}. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 67 - - See also \l{#min-height-prop}{min-height}. - - \row - \li \b{\c opacity*} \target opacity-prop - \li \l{#Number}{Number} - \li The opacity for a widget. Possible values are from 0 - (transparent) to 255 (opaque). For the moment, this is - only supported for \l{QToolTip}{tooltips}. - - If this property is not specified, it defaults to the - value specified by the current style for the - \l{QStyle::}{SH_ToolTipLabel_Opacity} style hint. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 68 - - \row - \li \b{\c padding} \target padding-prop - \li \l{#Box Lengths}{Box Lengths} - \li The widget's padding. Equivalent to specifying \c - padding-top, \c padding-right, \c padding-bottom, and \c - padding-left. - - This property is supported by QAbstractItemView - subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, - QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, - and QToolTip. - - If this property is not specified, it defaults to \c 0. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 69 - - See also \l{#margin-prop}{margin}, - \l{#spacing-prop}{spacing}, and \l{The Box Model}. - - \row - \li \c padding-top - \li \l{#Length}{Length} - \li The widget's top padding. - - \row - \li \c padding-right - \li \l{#Length}{Length} - \li The widget's right padding. - - \row - \li \c padding-bottom - \li \l{#Length}{Length} - \li The widget's bottom padding. - - \row - \li \c padding-left - \li \l{#Length}{Length} - \li The widget's left padding. - - \row - \li \b{\c paint-alternating-row-colors-for-empty-area} - \target paint-alternating-row-colors-for-empty-area-prop - \li \c bool - \li Whether the QTreeView paints alternating row colors for the empty - area (i.e the area where there are no items) - - \row - \li \b{\c position} \target position-prop - \li \c relative \BR - | \c absolute - \li Whether offsets specified using \l{Qt Style Sheets Reference#left-prop}{left}, - \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and - \l{#bottom-prop}{bottom} are relative or absolute - coordinates. - - If this property is not specified, it defaults to \c - relative. - - \row - \li \b{\c right} \target right-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the - default), moves a \l{subcontrol} by a certain offset to - the left; specifying \tt{right: \e{x}} is then equivalent - to specifying \tt{\l{Qt Style Sheets Reference#left-prop}{left}: -\e{x}}. - - If \l{#position-prop}{position} is \c absolute, the \c - right property specifies the subcontrol's right edge in - relation to the parent's right edge (see also - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}). - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 70 - - See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{Qt Style Sheets Reference#top-prop}{top}, and - \l{#bottom-prop}{bottom}. - - \row - \li \b{\c selection-background-color*} \target selection-background-color-prop - \li \l{#Brush}{Brush} \BR - \li The background of selected text or items. - - This property is supported by all widgets that respect - the \l QWidget::palette and that show selection text. - - If this property is not set, the default value is - whatever is set for the palette's - \l{QPalette::}{Highlight} role. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 71 - - See also \l{#selection-color-prop}{selection-color} and - \l{Qt Style Sheets Reference#background-prop}{background}. - - \row - \li \b{\c selection-color*} \target selection-color-prop - \li \l{#Brush}{Brush} \BR - \li The foreground of selected text or items. - - This property is supported by all widgets that respect - the \l QWidget::palette and that show selection text. - - If this property is not set, the default value is - whatever is set for the palette's - \l{QPalette::}{HighlightedText} role. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 72 - - See also - \l{#selection-background-color-prop}{selection-background-color} - and \l{#color-prop}{color}. - - \row - \li \b{\c show-decoration-selected*} \target show-decoration-selected-prop - \li \l{#Boolean}{Boolean} - \li Controls whether selections in a QListView cover the - entire row or just the extent of the text. - - If this property is not specified, it defaults to the - value specified by the current style for the - \l{QStyle::}{SH_ItemView_ShowDecorationSelected} style - hint. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 73 - - \row - \li \b{\c spacing*} \target spacing-prop - \li \l{#Length}{Length} - \li Internal spacing in the widget. - - This property is supported by QCheckBox, checkable - \l{QGroupBox}es, QMenuBar, and QRadioButton. - - If this property is not specified, the default value - depends on the widget and on the current style. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 74 - - See also \l{Qt Style Sheets Reference#padding-prop}{padding} and - \l{#margin-prop}{margin}. - - \row - \li \b{\c subcontrol-origin*} \target subcontrol-origin-prop - \li \l{#Origin}{Origin} - \li The origin rectangle of the \l subcontrol within the - parent element. - - If this property is not specified, the default is \c - padding. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 75 - - See also - \l{Qt Style Sheets Reference#subcontrol-position-prop}{subcontrol-position}. - - \row - \li \b{\c subcontrol-position*} \target subcontrol-position-prop - \li \l{#Alignment}{Alignment} - \li The alignment of the \l subcontrol within the origin - rectangle specified by \l{Qt Style Sheets Reference#subcontrol-origin-prop} - {subcontrol-origin}. - - If this property is not specified, it defaults to a value - that depends on the subcontrol. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 76 - - See also - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}. - - \row - \li \b{\c text-align} \target text-align-prop - \li \l{#Alignment}{Alignment} - \li The alignment of text and icon within the contents of the widget. - - If this value is not specified, it defaults to the value - that depends on the native style. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 77 - - This property is currently supported only by QPushButton - and QProgressBar. - - \row - \li \b{\c text-decoration} - \li \c none \BR - \c underline \BR - \c overline \BR - \c line-through - \li Additional text effects - - \row - \li \b{\c top} \target top-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the - default), moves a \l{subcontrol} by a certain offset - down. - - If \l{#position-prop}{position} is \c absolute, the \c top - property specifies the subcontrol's top edge in relation - to the parent's top edge (see also - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}). - - If this property is not specified, it defaults to \c 0. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 78 - - See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and - \l{#bottom-prop}{bottom}. - - \row - \li \b{\c width} \target width-prop - \li \l{#Length}{Length} - \li The width of a \l{subcontrol} (or a widget in some cases). - - If this property is not specified, it defaults to a value - that depends on the subcontrol/widget and on the current style. - - \warning Unless otherwise specified, this property has no effect - when set on widgets. If you want a widget with a fixed width, set - the \l{#min-width-prop}{min-width} and - \l{#max-width-prop}{max-width} to the same value. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 79 - - See also \l{#height-prop}{height}. - - \endtable - - \target list of icons - \section1 List of Icons - - Icons used in Qt can be customized using the following properties. Each of - the properties listed in this section have the type \l{#Icon}{Icon}. - - Note that for icons to appear in buttons in a QDialogButtonBox, you need to - set the dialogbuttonbox-buttons-have-icons property to true. Also, to - customize the size of the icons, use the icon-size property. - - \table 100% - \header - \li Name - \li QStyle::StandardPixmap - - \row - \li backward-icon - \li QStyle::SP_ArrowBack - - \row - \li cd-icon - \li QStyle::SP_DriveCDIcon - - \row - \li computer-icon - \li QStyle::SP_ComputerIcon - - \row - \li desktop-icon - \li QStyle::SP_DesktopIcon - - \row - \li dialog-apply-icon - \li QStyle::SP_DialogApplyButton - - \row - \li dialog-cancel-icon - \li QStyle::SP_DialogCancelButton - - \row - \li dialog-close-icon - \li QStyle::SP_DialogCloseButton - - \row - \li dialog-discard-icon - \li QStyle::SP_DialogDiscardButton - - \row - \li dialog-help-icon - \li QStyle::SP_DialogHelpButton - - \row - \li dialog-no-icon - \li QStyle::SP_DialogNoButton - - \row - \li dialog-ok-icon - \li QStyle::SP_DialogOkButton - - \row - \li dialog-open-icon - \li QStyle::SP_DialogOpenButton - - \row - \li dialog-reset-icon - \li QStyle::SP_DialogResetButton - - \row - \li dialog-save-icon - \li QStyle::SP_DialogSaveButton - - \row - \li dialog-yes-icon - \li QStyle::SP_DialogYesButton - - \row - \li directory-closed-icon - \li QStyle::SP_DirClosedIcon - - \row - \li directory-icon - \li QStyle::SP_DirIcon - - \row - \li directory-link-icon - \li QStyle::SP_DirLinkIcon - - \row - \li directory-open-icon - \li QStyle::SP_DirOpenIcon - - \row - \li dockwidget-close-icon - \li QStyle::SP_DockWidgetCloseButton - - \row - \li downarrow-icon - \li QStyle::SP_ArrowDown - - \row - \li dvd-icon - \li QStyle::SP_DriveDVDIcon - - \row - \li file-icon - \li QStyle::SP_FileIcon - - \row - \li file-link-icon - \li QStyle::SP_FileLinkIcon - - \omit - \row - \li filedialog-backward-icon - \li QStyle::SP_FileDialogBack - \endomit - - \row - \li filedialog-contentsview-icon - \li QStyle::SP_FileDialogContentsView - - \row - \li filedialog-detailedview-icon - \li QStyle::SP_FileDialogDetailedView - - \row - \li filedialog-end-icon - \li QStyle::SP_FileDialogEnd - - \row - \li filedialog-infoview-icon - \li QStyle::SP_FileDialogInfoView - - \row - \li filedialog-listview-icon - \li QStyle::SP_FileDialogListView - - \row - \li filedialog-new-directory-icon - \li QStyle::SP_FileDialogNewFolder - - \row - \li filedialog-parent-directory-icon - \li QStyle::SP_FileDialogToParent - - \row - \li filedialog-start-icon - \li QStyle::SP_FileDialogStart - - \row - \li floppy-icon - \li QStyle::SP_DriveFDIcon - - \row - \li forward-icon - \li QStyle::SP_ArrowForward - - \row - \li harddisk-icon - \li QStyle::SP_DriveHDIcon - - \row - \li home-icon - \li QStyle::SP_DirHomeIcon - - \row - \li leftarrow-icon - \li QStyle::SP_ArrowLeft - - \row - \li messagebox-critical-icon - \li QStyle::SP_MessageBoxCritical - - \row - \li messagebox-information-icon - \li QStyle::SP_MessageBoxInformation - - \row - \li messagebox-question-icon - \li QStyle::SP_MessageBoxQuestion - - \row - \li messagebox-warning-icon - \li QStyle::SP_MessageBoxWarning - - \row - \li network-icon - \li QStyle::SP_DriveNetIcon - - \row - \li rightarrow-icon - \li QStyle::SP_ArrowRight - - \row - \li titlebar-contexthelp-icon - \li QStyle::SP_TitleBarContextHelpButton - - \row - \li titlebar-maximize-icon - \li QStyle::SP_TitleBarMaxButton - - \row - \li titlebar-menu-icon - \li QStyle::SP_TitleBarMenuButton - - \row - \li titlebar-minimize-icon - \li QStyle::SP_TitleBarMinButton - - \row - \li titlebar-normal-icon - \li QStyle::SP_TitleBarNormalButton - - \row - \li titlebar-shade-icon - \li QStyle::SP_TitleBarShadeButton - - \row - \li titlebar-unshade-icon - \li QStyle::SP_TitleBarUnshadeButton - - \row - \li trash-icon - \li QStyle::SP_TrashIcon - - \row - \li uparrow-icon - \li QStyle::SP_ArrowUp - - \endtable - - \section1 List of Property Types - - The following table summarizes the syntax and meaning of the - different property types. - - \table 100% - \header - \li Type - \li Syntax - \li Description - - \row - \li \b Alignment \target Alignment - \li \{ \c top \BR - | \c bottom \BR - | \c left \BR - | \c right \BR - | \c center \}* - \li Horizontal and/or vertical alignment. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 80 - - \row - \li \b Attachment \target Attachment - \li \{ \c scroll \BR - | \c fixed \}* - \li Scroll or fixed attachment. - - \row - \li \b Background \target Background - \li \{ \l{#Brush}{Brush} \BR - | \l{#Url}{Url} \BR - | \l{#Repeat}{Repeat} \BR - | \l{#Alignment}{Alignment} \}* - \li A sequence of \l{#Brush}{Brush}, \l{#Url}{Url}, - \l{#Repeat}{Repeat}, and \l{#Alignment}{Alignment}. - - \row - \li \b Boolean \target Boolean - \li 0 | 1 - \li True (\c 1) or false (\c 0). - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 81 - - \row - \li \b Border \target Border - \li \{ \l{#Border Style}{Border Style} \BR - | \l{#Length}{Length} \BR - | \l{#Brush}{Brush} \}* - \li Shorthand border property. - - \row - \li \b{Border Image} \target Border Image - \li \c none \BR - | \l{Url} \l{Number}\{4\} \BR (\c stretch | \c repeat){0,2} - \li A border image is an image that is composed of nine parts - (top left, top center, top right, center left, center, - center right, bottom left, bottom center, and bottom - right). When a border of a certain size is required, the - corner parts are used as is, and the top, right, bottom, - and left parts are stretched or repeated to produce a - border with the desired size. - - See the - \l{http://www.w3.org/TR/css3-background/#the-border-image} - {CSS3 Draft Specification} for details. - - \row - \li \b{Border Style} \target Border Style - \li \c dashed \BR - | \c dot-dash \BR - | \c dot-dot-dash \BR - | \c dotted \BR - | \c double \BR - | \c groove \BR - | \c inset \BR - | \c outset \BR - | \c ridge \BR - | \c solid \BR - | \c none - \li Specifies the pattern used to draw a border. - See the \l{http://www.w3.org/TR/css3-background/#border-style} - {CSS3 Draft Specification} for details. - - \row - \li \b{Box Colors} \target Box Colors - \li \l{#Brush}{Brush}\{1,4\} - \li One to four occurrences of \l{#Brush}{Brush}, specifying the top, - right, bottom, and left edges of a box, respectively. If - the left color is not specified, it is taken to be the - same as the right color. If the bottom color is not - specified, it is taken to be the same as the top color. If - the right color is not specified, it is taken to be the - same as the top color. - - Example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 82 - - \row - \li \b{Box Lengths} \target Box Lengths - \li \l{#Length}{Length}\{1,4\} - \li One to four occurrences of \l{#Length}{Length}, specifying the - top, right, bottom, and left edges of a box, - respectively. If the left length is not specified, it is - taken to be the same as the right length. If the bottom - length is not specified, is it taken to be the same as the - top length. If the right length is not specified, it is - taken to be the same as the top length. - - Examples: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 83 - - \row - \li \b{Brush} \target Brush - \li \l{#Color}{Color} \BR - | \l{Gradient} \BR - | \l{PaletteRole} - \li Specifies a Color or a Gradient or an entry in the Palette. - - \row - \li \b{Color} \target Color - \li \tt{rgb(\e{r}, \e{g}, \e{b})} \BR - | \tt{rgba(\e{r}, \e{g}, \e{b}, \e{a})} \BR - | \tt{hsv(\e{h}, \e{s}, \e{v})} \BR - | \tt{hsva(\e{h}, \e{s}, \e{v}, \e{a})} \BR - | \tt{#\e{rrggbb}} \BR - | \l{QColor::setNamedColor()}{Color Name} \BR - \li Specifies a color as RGB (red, green, blue) or RGBA - (red, green, blue, alpha) or HSV (hue, saturation, value) or HSVA - (hue, saturation, value, alpha) or a named color. The \c rgb() or \c rgba() - syntax can be used with integer values between 0 and 255, or with - percentages. The value of s, v, and a in \c hsv() or \c hsva() must all - be in the range 0-255; the value of h must be in the range 0-359. - - Examples: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 84 - - \note The RGB colors allowed are the same as those allowed with - CSS 2.1, as listed - \l{http://www.w3.org/TR/CSS21/syndata.html#color-units}{here}. - - \row - \li \b{Font} \target Font - \li (\l{#Font Style}{Font Style} | \l{#Font Weight}{Font Weight}){0,2} \l{#Font Size}{Font Size} String - \li Shorthand font property. - - \row - \li \b{Font Size} \target Font Size - \li \l{Length} - \li The size of a font. - - \row - \li \b{Font Style} \target Font Style - \li \c normal \BR - | \c italic \BR - | \c oblique - \li The style of a font. - - \row - \li \b{Font Weight} \target Font Weight - \li \c normal \BR - | \c bold \BR - | \c 100 \BR - | \c 200 \BR - ... \BR - | \c 900 - \li The weight of a font. - - \row - \li \b{Gradient} \target Gradient - \li \c qlineargradient \BR - | \c qradialgradient \BR - | \c qconicalgradient - \li Specifies gradient fills. There are three types of gradient fills: - - \list - \li \e{Linear} gradients interpolate colors between start and - end points. - \li \e{Radial} gradients interpolate colors between a focal - point and end points on a circle surrounding it. - \li \e{Conical} gradients interpolate colors around a center - point. - \endlist - - Gradients are specified in Object Bounding Mode. Imagine the box - in which the gradient is rendered, to have its top left corner at (0, 0) - and its bottom right corner at (1, 1). Gradient parameters are - then specified as percentages from 0 to 1. These values are - extrapolated to actual box coordinates at runtime. It is possible - specify values that lie outside the bounding box (-0.6 or 1.8, for - instance). - - \warning The stops have to appear sorted in ascending order. - - Examples: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 85 - - \row - \li \b{Icon} \target Icon - \li (\l{#Url}{Url} (\c disabled | \c active | \c normal | \c selected)? - (\c on | \c off)? )* - \li A list of url, QIcon::Mode and QIcon::State. - - Example: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 86 - - \row - \li \b{Length} \target Length - \li \l{#Number}{Number} (\c px | \c pt | \c em | \c ex)? - \li A number followed by a measurement unit. The CSS standard recommends - that user agents must - \l{http://www.w3.org/TR/CSS21/syndata.html#illegalvalues}{ignore} - a declaration with an illegal value. In Qt, it is mandatory to - specify measurement units. For compatibility with earlier versions - of Qt, numbers without measurement units are treated as pixels - in most contexts. The supported units are: - - \list - \li \c px: pixels - \li \c pt: the size of one point (i.e., 1/72 of an inch) - \li \c em: the em width of the font (i.e., the width of 'M') - \li \c ex: the ex width of the font (i.e., the height of 'x') - \endlist - - \row - \li \b{Number} \target Number - \li A decimal integer or a real number - \li Examples: \c 0, \c 18, \c +127, \c -255, \c 12.34, \c -.5, - \c 0009. - - \row - \li \b{Origin} \target Origin - \li \c margin \BR - | \c border \BR - | \c padding \BR - | \c content - \li Indicates which of four rectangles to use. - - \list - \li \c margin: The margin rectangle. The margin falls outside the border. - \li \c border: The border rectangle. This is where any border is drawn. - \li \c padding: The padding rectangle. Unlike the margins, - padding is located inside the border. - \li \c content: The content rectangle. This specifies where - the actual contents go, excluding any - padding, border, or margin. - \endlist - - See also \l{The Box Model}. - - \row - \li \b{PaletteRole} \target PaletteRole - \li \c alternate-base \BR - | \c base \BR - | \c bright-text \BR - | \c button \BR - | \c button-text \BR - | \c dark \BR - | \c highlight \BR - | \c highlighted-text \BR - | \c light \BR - | \c link \BR - | \c link-visited \BR - | \c mid \BR - | \c midlight \BR - | \c shadow \BR - | \c text \BR - | \c window \BR - | \c window-text \BR - \li These values correspond the \l{QPalette::ColorRole}{Color roles} - in the widget's QPalette. - - For example, - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 87 - - \row - \li \b{Radius} \target Radius - \li \l{#Length}{Length}\{1, 2\} - \li One or two occurrences of \l{#Length}{Length}. If only one length is - specified, it is used as the radius of the quarter circle - defining the corner. If two lengths are specified, the - first length is the horizontal radius of a quarter - ellipse, whereas the second length is the vertical radius. - - \row - \li \b{Repeat} \target Repeat - \li \c repeat-x \BR - | \c repeat-y \BR - | \c repeat \BR - | \c no-repeat - \li A value indicating the nature of repetition. - - \list - \li \c repeat-x: Repeat horizontally. - \li \c repeat-y: Repeat vertically. - \li \c repeat: Repeat horizontally and vertically. - \li \c no-repeat: Don't repeat. - \endlist - - \row - \li \b{Url} \target Url - \li \tt{url(\e{filename})} - \li \tt{\e{filename}} is the name of a file on the local disk - or stored using \l{the Qt Resource System}. Setting an - image implicitly sets the width and height of the element. - - \endtable - - \section1 List of Pseudo-States - - The following pseudo-states are supported: - - \table 100% - \header - \li Pseudo-State - \li Description - - \row \li \c :active \target active - \li This state is set when the widget resides in an active window. - - \row - \li \c :adjoins-item \target adjoins-item-ps - \li This state is set when the \l{#branch-sub}{::branch} of a QTreeView - is adjacent to an item. - - \row - \li \c :alternate \target alternate-ps - \li This state is set for every alternate row whe painting the row of - a QAbstractItemView when QAbstractItemView::alternatingRowColors() - is set to true. - - \row - \li \c :bottom \target bottom-ps - \li The item is positioned at the bottom. For example, a QTabBar - that has its tabs positioned at the bottom. - - \row - \li \c :checked \target checked-ps - \li The item is checked. For example, the - \l{QAbstractButton::checked}{checked} state of QAbstractButton. - - \row - \li \c :closable \target closable-ps - \li The items can be closed. For example, the QDockWidget has the - QDockWidget::DockWidgetClosable feature turned on. - - \row - \li \c :closed \target closed-ps - \li The item is in the closed state. For example, an non-expanded - item in a QTreeView - - \row - \li \c :default \target default-ps - \li The item is the default. For example, a - \l{QPushButton::default}{default} QPushButton or a default action - in a QMenu. - - \row - \li \c :disabled \target disabled-ps - \li The item is \l{QWidget::enabled}{disabled}. - - \row - \li \c :editable \target editable-ps - \li The QComboBox is editable. - - \row - \li \c :edit-focus \target edit-focus-ps - \li The item has edit focus (See QStyle::State_HasEditFocus). This state - is available only for Qt Extended applications. - - \row - \li \c :enabled \target enabled-ps - \li The item is \l{QWidget::enabled}{enabled}. - - \row - \li \c :exclusive \target exclusive-ps - \li The item is part of an exclusive item group. For example, a menu - item in a exclusive QActionGroup. - - \row - \li \c :first \target first-ps - \li The item is the first (in a list). For example, the first - tab in a QTabBar. - - \row - \li \c :flat \target flat-ps - \li The item is flat. For example, a - \l{QPushButton::flat}{flat} QPushButton. - - \row - \li \c :floatable \target floatable-ps - \li The items can be floated. For example, the QDockWidget has the - QDockWidget::DockWidgetFloatable feature turned on. - - \row - \li \c :focus \target focus-ps - \li The item has \l{QWidget::hasFocus()}{input focus}. - - \row - \li \c :has-children \target has-children-ps - \li The item has children. For example, an item in a - QTreeView that has child items. - - \row - \li \c :has-siblings \target has-siblings-ps - \li The item has siblings. For example, an item in a - QTreeView that siblings. - - \row - \li \c :horizontal \target horizontal-ps - \li The item has horizontal orientation - - \row - \li \c :hover \target hover-ps - \li The mouse is hovering over the item. - - \row - \li \c :indeterminate \target indeterminate-ps - \li The item has indeterminate state. For example, a QCheckBox - or QRadioButton is \l{Qt::PartiallyChecked}{partially checked}. - - \row - \li \c :last \target last-ps - \li The item is the last (in a list). For example, the last - tab in a QTabBar. - - \row - \li \c :left \target left-ps - \li The item is positioned at the left. For example, a QTabBar - that has its tabs positioned at the left. - - \row - \li \c :maximized \target maximized-ps - \li The item is maximized. For example, a maximized QMdiSubWindow. - - \row - \li \c :middle \target middle-ps - \li The item is in the middle (in a list). For example, a tab - that is not in the beginning or the end in a QTabBar. - - \row - \li \c :minimized \target minimized-ps - \li The item is minimized. For example, a minimized QMdiSubWindow. - - \row - \li \c :movable \target movable-ps - \li The item can be moved around. For example, the QDockWidget has the - QDockWidget::DockWidgetMovable feature turned on. - - \row - \li \c :no-frame \target no-frame-ps - \li The item has no frame. For example, a frameless QSpinBox - or QLineEdit. - - \row - \li \c :non-exclusive \target non-exclusive-ps - \li The item is part of a non-exclusive item group. For example, a menu - item in a non-exclusive QActionGroup. - - \row - \li \c :off \target off-ps - \li For items that can be toggled, this applies to items - in the "off" state. - - \row - \li \c :on \target on-ps - \li For items that can be toggled, this applies to widgets - in the "on" state. - - \row - \li \c :only-one \target only-one-ps - \li The item is the only one (in a list). For example, a lone tab - in a QTabBar. - - \row - \li \c :open \target open-ps - \li The item is in the open state. For example, an expanded - item in a QTreeView, or a QComboBox or QPushButton with - an open menu. - - \row - \li \c :next-selected \target next-selected-ps - \li The next item (in a list) is selected. For example, the - selected tab of a QTabBar is next to this item. - - \row - \li \c :pressed \target pressed-ps - \li The item is being pressed using the mouse. - - \row - \li \c :previous-selected \target previous-selected-ps - \li The previous item (in a list) is selected. For example, a - tab in a QTabBar that is next to the selected tab. - - \row - \li \c :read-only \target read-only-ps - \li The item is marked read only or non-editable. For example, - a read only QLineEdit or a non-editable QComboBox. - - \row - \li \c :right \target right-ps - \li The item is positioned at the right. For example, a QTabBar - that has its tabs positioned at the right. - - \row - \li \c :selected \target selected-ps - \li The item is selected. For example, the selected tab in - a QTabBar or the selected item in a QMenu. - - \row - \li \c :top \target top-ps - \li The item is positioned at the top. For example, a QTabBar - that has its tabs positioned at the top. - - \row - \li \c :unchecked \target unchecked-ps - \li The item is - \l{QAbstractButton::checked}{unchecked}. - - \row - \li \c :vertical \target vertical-ps - \li The item has vertical orientation. - - \row - \li \c :window \target window-ps - \li The widget is a window (i.e top level widget) - - \endtable - - \target subcontrols - \section1 List of Sub-Controls - - The following subcontrols are available: - - \table 100% - \header - \li Sub-Control - \li Description - - \row - \li \c ::add-line \target add-line-sub - \li The button to add a line of a QScrollBar. - - \row - \li \c ::add-page \target add-page-sub - \li The region between the handle (slider) and the \l{#add-line-sub}{add-line} - of a QScrollBar. - - \row - \li \c ::branch \target branch-sub - \li The branch indicator of a QTreeView. - - \row - \li \c ::chunk \target chunk-sub - \li The progress chunk of a QProgressBar. - - \row - \li \c ::close-button \target close-button-sub - \li The close button of a QDockWidget or tabs of QTabBar - - \row - \li \c ::corner \target corner-sub - \li The corner between two scrollbars in a QAbstractScrollArea - - \row - \li \c ::down-arrow \target down-arrow-sub - \li The down arrow of a QComboBox, QHeaderView (sort indicator), - QScrollBar or QSpinBox. - - \row - \li \c ::down-button \target down-button-sub - \li The down button of a QScrollBar or a QSpinBox. - - \row - \li \c ::drop-down \target drop-down-sub - \li The drop-down button of a QComboBox. - - \row - \li \c ::float-button \target float-button-sub - \li The float button of a QDockWidget - - \row - \li \c ::groove \target groove-sub - \li The groove of a QSlider. - - \row - \li \c ::indicator \target indicator-sub - \li The indicator of a QAbstractItemView, a QCheckBox, a QRadioButton, - a checkable QMenu item or a checkable QGroupBox. - - \row - \li \c ::handle \target handle-sub - \li The handle (slider) of a QScrollBar, a QSplitter, or a QSlider. - - \row - \li \c ::icon \target icon-sub - \li The icon of a QAbstractItemView or a QMenu. - - \row - \li \c ::item \target item-sub - \li An item of a QAbstractItemView, a QMenuBar, a QMenu, or - a QStatusBar. - - \row - \li \c ::left-arrow \target left-arrow-sub - \li The left arrow of a QScrollBar. - - \row - \li \c ::left-corner \target left-corner-sub - \li The left corner of a QTabWidget. For example, this control can be - used to control position the left corner widget in a QTabWidget. - - \row - \li \c ::menu-arrow \target menu-arrow-sub - \li The arrow of a QToolButton with a menu. - - \row - \li \c ::menu-button \target menu-button-sub - \li The menu button of a QToolButton. - - \row - \li \c ::menu-indicator \target menu-indicator-sub - \li The menu indicator of a QPushButton. - - \row - \li \c ::right-arrow \target right-arrow-sub - \li The right arrow of a QMenu or a QScrollBar. - - \row - \li \c ::pane \target pane-sub - \li The pane (frame) of a QTabWidget. - - \row - \li \c ::right-corner \target right-corner-sub - \li The right corner of a QTabWidget. For example, this control can be - used to control the position the right corner widget in a QTabWidget. - - \row - \li \c ::scroller \target scroller-sub - \li The scroller of a QMenu or QTabBar. - - \row - \li \c ::section \target section-sub - \li The section of a QHeaderView. - - \row - \li \c ::separator \target separator-sub - \li The separator of a QMenu or in a QMainWindow. - - \row - \li \c ::sub-line \target sub-line-sub - \li The button to subtract a line of a QScrollBar. - - \row - \li \c ::sub-page \target sub-page-sub - \li The region between the handle (slider) and the \l{#sub-line-sub}{sub-line} - of a QScrollBar. - - \row - \li \c ::tab \target tab-sub - \li The tab of a QTabBar or QToolBox. - - \row - \li \c ::tab-bar \target tab-bar-sub - \li The tab bar of a QTabWidget. This subcontrol exists only to - control the position of the QTabBar inside the QTabWidget. To - style the tabs using the \l{#tab-sub}{::tab} subcontrol. - - \row - \li \c ::tear \target tear-sub - \li The tear indicator of a QTabBar. - - \row - \li \c ::tearoff \target tearoff-sub - \li The tear-off indicator of a QMenu. - - \row - \li \c ::text \target text-ps - \li The text of a QAbstractItemView. - - \row - \li \c ::title \target title-sub - \li The title of a QGroupBox or a QDockWidget. - - \row - \li \c ::up-arrow \target up-arrow-sub - \li The up arrow of a QHeaderView (sort indicator), QScrollBar - or a QSpinBox. - - \row - \li \c ::up-button \target up-button-sub - \li The up button of a QSpinBox. - - \endtable - - See \l{Customizing the QPushButton's Menu Indicator Sub-Control} - for an example of how to customize a subcontrol. - */ - -/*! - \page stylesheet-examples.html - \contentspage {Qt Style Sheet}{Contents} - \previouspage Qt Style Sheets Reference - \title Qt Style Sheets Examples - - We will now see a few examples to get started with using Qt Style Sheets. - - \tableofcontents - \section1 Style Sheet Usage - - \section2 Customizing the Foreground and Background Colors - - Let's start by setting yellow as the background color of all - \l{QLineEdit}s in an application. This could be achieved like - this: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 88 - - If we want the property to apply only to the \l{QLineEdit}s that are - children (or grandchildren or grand-grandchildren) of a specific dialog, - we would rather do this: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 89 - - If we want the property to apply only to one specific QLineEdit, - we can give it a name using QObject::setObjectName() and use an - ID Selector to refer to it: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 90 - - Alternatively, we can set the - \l{Qt Style Sheets Reference#background-prop}{background-color} property directly on the - QLineEdit, omitting the selector: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 91 - - To ensure a good contrast, we should also specify a suitable - color for the text: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 92 - - It might be a good idea to change the colors used for selected - text as well: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 93 - - - \section2 Customizing Using Dynamic Properties - - There are many situations where we need to present a form that - has mandatory fields. To indicate to the user that the field is - mandatory, one effective (albeit esthetically dubious) solution - is to use yellow as the background color for those fields. It - turns out this is very easy to implement using Qt Style Sheets. - First, we would use the following application-wide style sheet: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 94 - - This means that every widget whose \c mandatoryField Qt property - is set to true would have a yellow background. - - Then, for each mandatory field widget, we would simply create a - \c mandatoryField property on the fly and set it to true. For - example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 95 - - \section2 Customizing a QPushButton Using the Box Model - - This time, we will show how to create a red QPushButton. This - QPushButton would presumably be connected to a very destructive - piece of code. - - First, we are tempted to use this style sheet: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 96 - - However, the result is a boring, flat button with no borders: - - \image stylesheet-redbutton1.png A flat red button - - What happened is this: - - \list - \li We have made a request that cannot be satisfied using the - native styles alone (e.g., the Windows XP theme engine doesn't - let us specify the background color of a button). - \li Therefore, the button is rendered using style sheets. - \li We haven't specified any values for - \l{Qt Style Sheets Reference#border-width-prop}{border-width} and - \l{Qt Style Sheets Reference#border-style-prop}{border-style}, so by default we obtain - a 0-pixel wide border of style \c none. - \endlist - - Let's improve the situation by specifying a border: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 97 - - \image stylesheet-redbutton2.png A red button with a beige border - - Things look already a lot better. But the button looks a bit - cramped. Let's specify some spacing between the border and the - text using the \l{Qt Style Sheets Reference#padding-prop}{padding}. Additionally, we will - enforce a minimum width, round the corners, and specify a larger - font to make the button look nicer: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 98 - - \image stylesheet-redbutton3.png A red button with a round beige border and big, bold text - - The only issue remaining is that the button doesn't react when we - press it. We can fix this by specifying a slightly different - background color and use a different border style. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 99 - - \section2 Customizing the QPushButton's Menu Indicator Sub-Control - - Subcontrols give access to the sub-elements of a widget. For - example, a QPushButton associated with a menu (using - QPushButton::setMenu()) has a menu indicator. Let's customize - the menu indicator for the red push button: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 100 - - By default, the menu indicator is located at the bottom-right - corner of the padding rectangle. We can change this by specifying - \l{Qt Style Sheets Reference#subcontrol-position-prop}{subcontrol-position} and - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} to anchor the - indicator differently. We can also use \l{Qt Style Sheets Reference#top-prop}{top} and - \l{Qt Style Sheets Reference#left-prop}{left} to move the indicator by a few pixels. For - example: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 101 - - This positions the \c myindicator.png to the center right of the - QPushButton's \l{Qt Style Sheets Reference#padding-prop}{padding} rectangle (see - \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} for more - information). - - \section2 Complex Selector Example - - Since red seems to be our favorite color, let's make the text in - QLineEdit red by setting the following application-wide - stylesheet: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 102 - - However, we would like to give a visual indication that a - QLineEdit is read-only by making it appear gray: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 103 - - At some point, our design team comes with the requirement that - all \l{QLineEdit}s in the registration form (with the - \l{QObject::objectName}{object name} \c registrationDialog) to be - brown: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 104 - - A few UI design meetings later, we decide that all our - \l{QDialog}s should have brown colored \l{QLineEdit}s: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 105 - - Quiz: What happens if we have a read-only QLineEdit in a QDialog? - [Hint: The \l{The Style Sheet Syntax#Conflict Resolution}{Conflict Resolution} section above explains - what happens in cases like this.] - - \section1 Customizing specific widgets - - This section provides examples to customize specific widgets using Style Sheets. - - \section2 Customizing QAbstractScrollArea - - The background of any QAbstractScrollArea (Item views, QTextEdit - and QTextBrowser) can be set using the background properties. For example, - to set a background-image that scrolls with the scroll bar: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 106 - - If the background-image is to be fixed with the viewport: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 107 - - \section2 Customizing QCheckBox - - Styling of a QCheckBox is almost identical to styling a QRadioButton. The - main difference is that a tristate QCheckBox has an indeterminate state. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 108 - - \section2 Customizing QComboBox - - We will look at an example where the drop down button of a QComboBox - appears "merged" with the combo box frame. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 109 - - The pop-up of the QComboBox is a QAbstractItemView and is styled using - the descendant selector: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 110 - - \section2 Customizing QDockWidget - - The title bar and the buttons of a QDockWidget can be customized as - follows: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 111 - - If one desires to move the dock widget buttons to the left, the following - style sheet can be used: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 112 - - \note To customize the separator (resize handle) of a QDockWidget, - use QMainWindow::separator. - - \section2 Customizing QFrame - - A QFrame is styled using the \l{The Box Model}. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 113 - - \section2 Customizing QGroupBox - - Let us look at an example that moves the QGroupBox's title to - the center. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 114 - - For a checkable QGroupBox, use the \{#indicator-sub}{::indicator} subcontrol - and style it exactly like a QCheckBox (i.e) - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 115 - - \section2 Customizing QHeaderView - - QHeaderView is customized as follows: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 116 - - \section2 Customizing QLineEdit - - The frame of a QLineEdit is styled using the \l{The Box Model}. To - create a line edit with rounded corners, we can set: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 117 - - The password character of line edits that have QLineEdit::Password - echo mode can be set using: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 118 - - The background of a read only QLineEdit can be modified as below: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 119 - - \section2 Customizing QListView - - The background color of alternating rows can be customized using the following - style sheet: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 120 - - To provide a special background when you hover over items, we can use the - \l{item-sub}{::item} subcontrol. For example, - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 121 - - \section2 Customizing QMainWindow - - The separator of a QMainWindow can be styled as follows: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 122 - - \section2 Customizing QMenu - - Individual items of a QMenu are styled using the 'item' subcontrol as - follows: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 123 - - For a more advanced customization, use a style sheet as follows: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 124 - - \section2 Customizing QMenuBar - - QMenuBar is styled as follows: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 125 - - \section2 Customizing QProgressBar - - The QProgressBar's \l{stylesheet-reference.html#border-prop}{border}, - \l{stylesheet-reference.html#chunk-sub}{chunk}, and - \l{stylesheet-reference.html#text-align-prop}{text-align} can be customized using - style sheets. However, if one property or sub-control is customized, - all the other properties or sub-controls must be customized as well. - - \image progressBar-stylesheet.png - - For example, we change the \l{stylesheet-reference.html#border-prop} - {border} to grey and the \l{stylesheet-reference.html#chunk-sub}{chunk} - to cerulean. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 126 - - This leaves the \l{stylesheet-reference.html#text-align-prop} - {text-align}, which we customize by positioning the text in the center of - the progress bar. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 127 - - A \l{stylesheet-reference.html#margin-prop}{margin} can be included to - obtain more visible chunks. - - \image progressBar2-stylesheet.png - - In the screenshot above, we use a - \l{stylesheet-reference.html#margin-prop}{margin} of 0.5 pixels. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 128 - - \section2 Customizing QPushButton - - A QPushButton is styled as follows: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 129 - - For a QPushButton with a menu, use the - \l{Qt Style Sheets Reference#menu-indicator-sub}{::menu-indicator} - subcontrol. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 130 - - Checkable QPushButton have the \l{Qt Style Sheets Reference#checked-ps} - {:checked} pseudo state set. - - \section2 Customizing QRadioButton - - The indicator of a QRadioButton can be changed using: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 131 - - \section2 Customizing QScrollBar - - The QScrollBar can be styled using its subcontrols like - \l{stylesheet-reference.html#handle-sub}{handle}, - \l{stylesheet-reference.html#add-line-sub}{add-line}, - \l{stylesheet-reference.html#sub-line-sub}{sub-line}, and so on. Note that - if one property or sub-control is customized, all the other properties or - sub-controls must be customized as well. - - \image stylesheet-scrollbar1.png - - The scroll bar above has been styled in aquamarine with a solid grey - border. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 132 - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 133 - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 134 - - The \l{stylesheet-reference.html#left-arrow-sub}{left-arrow} and - \l{stylesheet-reference.html#right-arrow-sub}{right-arrow} have a solid grey - border with a white background. As an alternative, you could also embed the - image of an arrow. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 135 - - If you want the scroll buttons of the scroll bar to be placed together - (instead of the edges) like on Mac OS X, you can use the following - stylesheet: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 136 - - The scroll bar using the above stylesheet looks like this: - \image stylesheet-scrollbar2.png - - - To customize a vertical scroll bar use a style sheet similar to the following: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 137 - - \section2 Customizing QSizeGrip - - QSizeGrip is usually styled by just setting an image. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 138 - - \section2 Customizing QSlider - - You can style horizontal slider as below: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 139 - - If you want to change the color of the slider parts before and after the handle, you can use the add-page - and sub-page subcontrols. For example, for a vertical slider: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 140 - - \section2 Customizing QSpinBox - - QSpinBox can be completely customized as below (the style sheet has commentary inline): - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 141 - - - \section2 Customizing QSplitter - - A QSplitter derives from a QFrame and hence can be styled like a QFrame. - The grip or the handle is customized using the - \l{Qt Style Sheets Reference#handle-sub}{::handle} subcontrol. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 142 - - \section2 Customizing QStatusBar - - We can provide a background for the status bar and a border for items - inside the status bar as follows: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 143 - - Note that widgets that have been added to the QStatusBar can be styled - using the descendant declaration (i.e) - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 144 - - \section2 Customizing QTabWidget and QTabBar - - \image tabWidget-stylesheet1.png - - For the screenshot above, we need a stylesheet as follows: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 145 - - Often we require the tabs to overlap to look like below: - \image tabWidget-stylesheet2.png - - For a tab widget that looks like above, we make use of - \l{http://www.communitymx.com/content/article.cfm?cid=B0029} - {negative margins}. The resulting stylesheet looks like this: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 146 - - To move the tab bar to the center (as below), we require the following stylesheet: - \image tabWidget-stylesheet3.png - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 147 - - The tear indicator and the scroll buttons can be further customized as follows: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 148 - - Since Qt 4.6 the close button can be customized as follow: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 159 - - \section2 Customizing QTableView - - Suppose we'd like our selected item in QTableView to have bubblegum pink - fade to white as its background. - - \image tableWidget-stylesheet.png - - This is possible with the - \l{stylesheet-reference.html#selection-background-color-prop} - {selection-background-color} property and the syntax required is: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 149 - - The corner widget can be customized using the following style sheet - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 150 - - \section2 Customizing QToolBar - - The background and the handle of a QToolBar is customized as below: - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 151 - - \section2 Customizing QToolBox - - The tabs of the QToolBox are customized using the 'tab' subcontrol. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 152 - - \section2 Customizing QToolButton - - There are three types of QToolButtons. - \list - \li The QToolButton has no menu. In this case, the QToolButton is styled - exactly like QPushButton. See - \l{#Customizing QPushButton}{Customizing QPushButton} for an - example. - - \li The QToolButton has a menu and has the QToolButton::popupMode set to - QToolButton::DelayedPopup or QToolButton::InstantPopup. In this case, - the QToolButton is styled exactly like a QPushButton with a menu. - See \l{#Customizing QPushButton}{Customizing QPushButton} for an - example of the usage of the menu-indicator pseudo state. - - \li The QToolButton has its QToolButton::popupMode set to - QToolButton::MenuButtonPopup. In this case, we style it as follows: - \endlist - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 153 - - - \section2 Customizing QToolTip - - QToolTip is customized exactly like a QLabel. In addition, for platforms - that support it, the opacity property may be set to adjust the opacity. - - For example, - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 154 - - \section2 Customizing QTreeView - - The background color of alternating rows can be customized using the following - style sheet: - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 155 - - To provide a special background when you hover over items, we can use the - \l{item-sub}{::item} subcontrol. For example, - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 156 - - The branches of a QTreeView are styled using the - \l{Qt Style Sheets Reference#branch-sub}{::branch} subcontrol. The - following stylesheet color codes the various states when drawing - a branch. - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 157 - - Colorful, though it is, a more useful example can be made using the - following images: - - \table - \row - \li \inlineimage stylesheet-vline.png - \li \inlineimage stylesheet-branch-more.png - \li \inlineimage stylesheet-branch-end.png - \li \inlineimage stylesheet-branch-closed.png - \li \inlineimage stylesheet-branch-open.png - \row - \li vline.png - \li branch-more.png - \li branch-end.png - \li branch-closed.png - \li branch-open.png - \endtable - - \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 158 - - The resulting tree view looks like this: - - \image stylesheet-treeview.png - - \sa {Style Sheet Example}, {Supported HTML Subset}, QStyle - - - \section1 Common mistakes - - This section lists some common mistakes when using stylesheets. - - \section2 QPushButton and images - - When styling a QPushButton, it is often desirable to use an image as the - button graphic. It is common to try the - \l{Qt Style Sheets Reference#background-image-prop}{background-image} - property, - but this has a number of drawbacks: For instance, the background will - often appear hidden behind the button decoration, because it is not - considered a background. In addition, if the button is resized, the - entire background will be stretched or tiled, which does not - always look good. - - It is better to use the - \l{Qt Style Sheets Reference#border-image-prop}{border-image} - property, as it will always display the image, - regardless of the background (you can combine it with a background if it - has alpha values in it), and it has special settings to deal with button - resizing. - - Consider the following snippet: - - \snippet doc/src/snippets/stylesheet/common-mistakes.cpp 1 - - This will produce a button looking like this: - - \image stylesheet-border-image-normal.png - - The numbers after the url gives the top, right, bottom and left number of - pixels, respectively. These numbers correspond to the border and should not - stretch when the size changes. - Whenever you resize the button, the middle part of the image will stretch - in both directions, while the pixels specified in the stylesheet - will not. This makes the borders of the button look more natural, like - this: - - \table - \row - \li \inlineimage stylesheet-border-image-stretched.png - \row - \li With borders - \endtable - - \table - \row - \li \inlineimage stylesheet-border-image-wrong.png - \row - \li Without borders - \endtable - - */ diff --git a/doc/src/widgets/widgets-and-layouts/widgets.qdoc b/doc/src/widgets/widgets-and-layouts/widgets.qdoc deleted file mode 100644 index e80b0fbec0..0000000000 --- a/doc/src/widgets/widgets-and-layouts/widgets.qdoc +++ /dev/null @@ -1,162 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page widgets-and-layouts.html - \title Widgets and Layouts - \ingroup qt-gui-concepts - \brief The primary elements for designing user interfaces in Qt. - - \section1 Widgets - - Widgets are the primary elements for creating user interfaces in Qt. - \l{The Widget Classes}{Widgets} can display data and status information, - receive user input, and provide a container for other widgets that - should be grouped together. A widget that is not embedded in a - parent widget is called a \l{Window and Dialog Widgets} {window}. - - \image parent-child-widgets.png A parent widget containing various child widgets. - - The QWidget class provides the basic capability to render to the - screen, and to handle user input events. All UI elements that Qt - provides are either subclasses of QWidget, or are used in connection - with a QWidget subclass. Creating custom widgets is done by - subclassing QWidget or a suitable subclass and reimplementing the - virtual event handlers. - - \section1 Layouts - - \l{Layout Management}{Layouts} are an elegant and flexible way to - automatically arrange child widgets within their container. Each - widget reports its size requirements to the layout through the - \l{QWidget::}{sizeHint} and \l{QWidget::}{sizePolicy} properties, - and the layout distributes the available space accordingly. - - \table - \row - \li \image qgridlayout-with-5-children.png - \li \image qformlayout-with-6-children.png - \endtable - - \l{Qt Designer Manual}{\QD} is a powerful tool for interactively creating and - arranging widgets in layouts. - - \section1 Widget Styles - - \l{Styles and Style Aware Widgets}{Styles} draw on behalf of - widgets and encapsulate the look and feel of a GUI. Qt's built-in - widgets use the QStyle class to perform nearly all of their drawing, - ensuring that they look exactly like the equivalent native widgets. - - \table - \row - \li \image windowsxp-tabwidget.png - \li \image plastique-tabwidget.png - \li \image macintosh-tabwidget.png - \endtable - - \l{Qt Style Sheets} are a powerful mechanism that allows you to customize the - appearance of widgets, in addition to what is already possible by subclassing QStyle. - - \section1 The Widget Classes - - The following sections list the widget classes. See the \l{Qt Widget - Gallery} for some examples. - - \section2 Basic Widgets - - These basic widgets (controls), e.g. buttons, comboboxes and - scroll bars, are designed for direct use. - - \table - \row - \li \image windows-label.png - \li \image windowsvista-pushbutton.png - \li \image gtk-progressbar.png - \row - \li \image plastique-combobox.png - \li \image macintosh-radiobutton.png - \li \image cde-lineedit.png - \endtable - - \annotatedlist basicwidgets - - \section2 Advanced Widgets - - Advanced GUI widgets, e.g. tab widgets and progress bars, provide - more complex user interface controls. - - \table - \row - \li \image windowsxp-treeview.png - \li \image gtk-calendarwidget.png - \li \image qundoview.png - \endtable - - \annotatedlist advanced - - \table - \row - \li \image windowsvista-tabwidget.png - \li \image macintosh-groupbox.png - \endtable - - \section2 Organizer Widgets - - Classes like splitters, tab bars, button groups, etc are used for - organizing and grouping GUI primitives into more complex - applications and dialogs. - - \annotatedlist organizers - - \section2 Abstract Widget Classes - - The abstract widget classes are base classes. They are not usable as - standalone classes but provide functionality when they are subclassed. - - \annotatedlist abstractwidgets -*/ - -/*! - \group advanced - \title Advanced Widgets -*/ - -/*! - \group abstractwidgets - \title Abstract Widget Classes -*/ - -/*! - \group basicwidgets - \title Basic Widgets -*/ - -/*! - \group organizers - \title Organizers -*/ -- cgit v1.2.3