diff options
Diffstat (limited to 'doc/src/widgets-and-layouts')
| -rw-r--r-- | doc/src/widgets-and-layouts/focus.qdoc | 200 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-cde.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-gtk.qdoc | 358 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-macintosh.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-motif.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-plastique.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-windows.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-windowsvista.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery-windowsxp.qdoc | 392 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/gallery.qdoc | 150 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/layout.qdoc | 396 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/styles.qdoc | 2123 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/stylesheet.qdoc | 3962 | ||||
| -rw-r--r-- | doc/src/widgets-and-layouts/widgets.qdoc | 187 |
15 files changed, 10512 insertions, 0 deletions
diff --git a/doc/src/widgets-and-layouts/focus.qdoc b/doc/src/widgets-and-layouts/focus.qdoc new file mode 100644 index 0000000..1cbc71b --- /dev/null +++ b/doc/src/widgets-and-layouts/focus.qdoc @@ -0,0 +1,200 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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 + + \o The user presses \key Tab (or \key Shift+Tab). + \o The user clicks a widget. + \o The user presses a keyboard shortcut. + \o The user uses the mouse wheel. + \o 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{Events and Event Filters}{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 + + \o 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. + + \o 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-and-layouts/gallery-cde.qdoc b/doc/src/widgets-and-layouts/gallery-cde.qdoc new file mode 100644 index 0000000..02dabb1 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-cde.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cde-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button. +\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cde-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cde-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cde-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cde-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cde-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cde-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc b/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc new file mode 100644 index 0000000..13c0f8f --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage cleanlooks-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage cleanlooks-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-gtk.qdoc b/doc/src/widgets-and-layouts/gallery-gtk.qdoc new file mode 100644 index 0000000..8251f04 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-gtk.qdoc @@ -0,0 +1,358 @@ +/*! + \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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-toolbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-frame.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-treeview.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-tableview.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-lineedit.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-timeedit.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage gtk-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td align="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td align="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage gtk-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-macintosh.qdoc b/doc/src/widgets-and-layouts/gallery-macintosh.qdoc new file mode 100644 index 0000000..c7efabe --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-macintosh.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage macintosh-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage macintosh-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-motif.qdoc b/doc/src/widgets-and-layouts/gallery-motif.qdoc new file mode 100644 index 0000000..1539753 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-motif.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage motif-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage motif-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage motif-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage motif-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage motif-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage motif-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage motif-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-plastique.qdoc b/doc/src/widgets-and-layouts/gallery-plastique.qdoc new file mode 100644 index 0000000..49bd13e --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-plastique.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage plastique-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage plastique-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-windows.qdoc b/doc/src/widgets-and-layouts/gallery-windows.qdoc new file mode 100644 index 0000000..2fa971c --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-windows.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windows-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windows-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windows-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windows-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windows-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windows-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windows-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc b/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc new file mode 100644 index 0000000..9ab3a2f --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsvista-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsvista-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc b/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc new file mode 100644 index 0000000..aefff65 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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. + +\raw HTML +<h2 align="center">Buttons</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-pushbutton.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-toolbutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QPushButton widget provides a command button.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-checkbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-radiobutton.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Containers</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-groupbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-tabwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-frame.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-toolbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Item Views</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-listview.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-treeview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +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.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-tableview.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Display Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-progressbar.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-lcdnumber.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-label.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QLabel widget provides a text or image display.\raw HTML +</td> +</tr> +</table> +\endraw +\raw HTML +<h2 align="center">Input Widgets</h2> + +<table align="center" cellspacing="20%" width="100%"> +<colgroup span="2"> + <col width="40%" /> + <col width="40%" /> +</colgroup> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-slider.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-lineedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-combobox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-doublespinbox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-spinbox.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-timeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QSpinBox class provides a spin box widget.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-dateedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-datetimeedit.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-textedit.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-horizontalscrollbar.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-dial.png +\raw HTML +</td> +<td align="center"> +\endraw +\inlineimage windowsxp-calendarwidget.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +</td> +<td halign="justify" valign="top"> +\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +</td> +</tr> +<tr> +<td align="center"> +\endraw +\inlineimage windowsxp-fontcombobox.png +\raw HTML +</td> +</tr><tr> +<td halign="justify" valign="top"> +\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +</td> +</tr> +</table> +\endraw +*/ diff --git a/doc/src/widgets-and-layouts/gallery.qdoc b/doc/src/widgets-and-layouts/gallery.qdoc new file mode 100644 index 0000000..cb92cb4 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery.qdoc @@ -0,0 +1,150 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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 enviroment. Below, you can find links to the various + widget styles that are supplied with Qt 4. + + \raw HTML + <table align="center" cellspacing="20%" width="100%"> + <colgroup span="2"> + <col width="40%" /> + <col width="40%" /> + </colgroup> + <tr> + <td align="center"> + \endraw + \image plastique-tabwidget.png Plastique Style Widget Gallery + + \bold{\l{Plastique Style Widget Gallery}} + + The Plastique style is provided by QPlastiqueStyle. + \raw HTML + </td> + <td align="center"> + \endraw + \image windowsxp-tabwidget.png Windows XP Style Widget Gallery + + \bold{\l{Windows XP Style Widget Gallery}} + + The Windows XP style is provided by QWindowsXPStyle. + \raw HTML + </td> + </tr> + <tr> + <td align="center"> + \endraw + \image gtk-tabwidget.png GTK Style Widget Gallery + + \bold{\l{GTK Style Widget Gallery}} + + The GTK style is provided by QGtkStyle. + \raw HTML + </td> + <td align="center"> + \endraw + \image macintosh-tabwidget.png Macintosh Style Widget Gallery + + \bold{\l{Macintosh Style Widget Gallery}} + + The Macintosh style is provided by QMacStyle. + \raw HTML + </td> + </tr> + <tr> + <td align="center"> + \endraw + \image cleanlooks-tabwidget.png Cleanlooks Style Widget Gallery + + \bold{\l{Cleanlooks Style Widget Gallery}} + + The Cleanlooks style is provided by QCleanlooksStyle. + \raw HTML + </td> + <td align="center"> + \endraw + \image windowsvista-tabwidget.png Windows Vista Style Widget Gallery + + \bold{\l{Windows Vista Style Widget Gallery}} + + The Windows Vista style is provided by QWindowsVistaStyle. + \raw HTML + </td> + </tr> + <tr> + <td align="center"> + \endraw + \image motif-tabwidget.png Motif Style Widget Gallery + + \bold{\l{Motif Style Widget Gallery}} + + The Motif style is provided by QMotifStyle. + \raw HTML + </td> + <td align="center"> + \endraw + \image windows-tabwidget.png Windows Style Widget Gallery + + \bold{\l{Windows Style Widget Gallery}} + + The Windows style is provided by QWindowsStyle. + \raw HTML + </td> + </tr> + <tr> + <td align="center"> + \endraw + \image cde-tabwidget.png CDE Style Widget Gallery + + \bold{\l{CDE Style Widget Gallery}} + + The Common Desktop Environment style is provided by QCDEStyle. + \raw HTML + </td> + </tr> + </table> + \endraw +*/ diff --git a/doc/src/widgets-and-layouts/layout.qdoc b/doc/src/widgets-and-layouts/layout.qdoc new file mode 100644 index 0000000..4622301 --- /dev/null +++ b/doc/src/widgets-and-layouts/layout.qdoc @@ -0,0 +1,396 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group geomanagement + \title Layout Classes +*/ + +/*! + \page layout.html + \title Layout Management + \brief A tour of the standard layout managers and an introduction to custom + layouts. + + \previouspage Widget Classes + \contentspage Widgets and Layouts + \nextpage {Implementing 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 + \o Positioning of child widgets. + \o Sensible default sizes for windows. + \o Sensible minimum sizes for windows. + \o Resize handling. + \o Automatic updates when contents change: + \list + \o Font size, text or other contents of child widgets. + \o Hiding or showing a child widget. + \o 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 + \o 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 + + \o A QVBoxLayout lays out widgets in a vertical column, from top to + bottom. + \image qvboxlayout-with-5-children.png + + \o A QGridLayout lays out widgets in a two-dimensional grid. Widgets + can occupy multiple cells. + \image qgridlayout-with-5-children.png + + \o 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}s, 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(). + + Finally, the code for QFormLayout is .. + + + \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 + \o All the widgets will initially be allocated an amount of space in + accordance with their QWidget::sizePolicy() and + QWidget::sizeHint(). + + \o 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). + + \o 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. + + \o 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 strech + factor is their determining factor.) + + \o 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 strech 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 + \o Reimplement QWidget::sizeHint() to return the preferred size of the + widget. + \o Reimplement QWidget::minimumSizeHint() to return the smallest size + the widget can have. + \o 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://qt.nokia.com/doc/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 + \o 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. + \o \l{QLayout::}{addItem()}, how to add items to the layout. + \o \l{QLayout::}{setGeometry()}, how to perform the layout. + \o \l{QLayout::}{sizeHint()}, the preferred size of the layout. + \o \l{QLayout::}{itemAt()}, how to iterate over the layout. + \o \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.qdoc 0 + + + \section2 The Implementation File (\c card.cpp) + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 1 + + First we define \c{count()} to fetch the number of items in the list. + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 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.qdoc 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.qdoc 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.qdoc 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.qdoc 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.qdoc 7 + + + \section2 Further Notes + + \list + \o This custom layout does not handle height for width. + \o We ignore QLayoutItem::isEmpty(); this means that the layout will + treat hidden widgets as visible. + \o 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. + \o 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. + \o 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-and-layouts/styles.qdoc b/doc/src/widgets-and-layouts/styles.qdoc new file mode 100644 index 0000000..aa51838 --- /dev/null +++ b/doc/src/widgets-and-layouts/styles.qdoc @@ -0,0 +1,2123 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group appearance + \title Widget Appearance and Style + \brief Classes used for customizing UI appearance and style. +*/ + +/*! + \page style-reference.html + \title Implementing Styles and Style Aware Widgets + \brief An overview of styles and the styling of widgets. + + \ingroup frameworks-technologies + + \previouspage Widget Classes + \contentspage Widgets and Layouts + \nextpage {Qt Style Sheets}{Style sheets} + + 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. + + \tableofcontents + + \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 + \o an enum value specifying which graphical element to draw + \o a QStyleOption specifying how and where to render that element + \o a QPainter that should be used to draw the element + \o 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. Ie 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.qdoc 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.qdoc 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 + \o the enum value of the element to draw + \o a QStyleOption which contains the information needed to + draw the element. + \o a QPainter with which to draw the element. + \o 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 + \o 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. + + \o 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. + + \o 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. + + \o 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.qdoc 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.qdoc 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 + \o State flag + \o Set + \row + \o State_Sunken + \o Yes + \row + \o State_NoChange + \o No + \row + \o State_On + \o Yes + \row + \o State_Off + \o No + \row + \o State_MouseOver + \o Yes + \row + \o State_Enabled + \o Yes + \row + \o State_HasFocus + \o Yes + \row + \o State_KeyboardFocusChange + \o No + \row + \o State_Active + \o 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.qdoc 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.qdoc 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.qdoc 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 + \o A table with the members (variables, etc.) of its style option. + \o A table over the state flags (QStyle::StateFlag) that + can be set on the widget and when the states are set. + \o Its element tree (see section \l{The Style Elements}). + \o An image of the widget in which the elements are outlined. + \omit This is not written yet - probably never will be + either + \o List of style hints that should be checked for the + widget. + \o 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 \bold 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 + \o State + \o State Set When + \row + \o State_Enabled + \o Set if the widget is not disabled (see + QWidget::setEnabled()) + \row + \o State_Focus + \o Set if the widget has focus (see + QWidget::hasFocus()) + \row + \o State_KeyobordFocusChange + \o Set when the user changes focus with the keyboard + (see Qt::WA_KeyboardFocusChange) + \row + \o State_MouseOver + \o Set if the mouse cursor is over the widget + \row + \o State_Active + \o Set if the widget is a child of the active window. + \row + \o State_HasEditFocus + \o Set if the widget has the edit focus + \endtable + + The other common members for widgets are: + + \table 90% + \header + \o Member + \o Content + \row + \o rect + \o The bounding rectangle of the element to draw. This + is set to the widget bounding rectangle + (QWidget::rect()). + \row + \o direction + \o The layout direction; a value of the + Qt::LayoutDirection enum. + \row + \o palette + \o The QPalette to use when drawing the element. This + is set to the widgets palette (QWidget::palette()). + \row + \o fontMetrics + \o 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 + \o State + \o State Set When + \row + \o State_Sunken + \o Button is down or menu is pressed shown + \row + \o State_On + \o Button is checked + \row + \o State_Raised + \o Button is not flat and not pressed down + \endtable + + Other members of QStyleOptionButton is: + + \table 90% + \header + \o Member + \o Content + \row + \o features + \o Flags of the QStyleOptionButton::ButtonFeatures enum, + which describes various button properties (see enum) + \row + \o icon + \o The buttons QIcon (if any) + \row + \o iconSize + \o The QSize of the icon + \row + \o text + \o 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 + \o State + \o State Set When + \row + \o State_sunken + \o The box is pressed down + \row + \o State_NoChange + \o The box is partially checked (for tristate + checkboxes.) + \row + \o State_On + \o The box is checked + \row + \o State_Off + \o 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 + \o State + \o State Set When + \row + \o State_Sunken + \o The tab is pressed on with the mouse. + \row + \o State_Selected + \o If it is the current tab. + \row + \o State_HasFocus + \o 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 + \o Member + \o Content + \row + \o cornerWidgets + \o Is flags of the CornerWidget enum, which indicate + if and which corner widgets the tab bar has. + \row + \o icon + \o The QIcon of the tab + \row + \o iconSize + \o The QSize of the icon + \row + \o position + \o A TabPosition enum value that indicates the tabs + position on the bar relative to the other tabs. + \row + \o row + \o holds which row the tab is in + \row + \o selectedPosition + \o A value of the SelectedPosition enum that indicates + whether the selected tab is adjacent to or is the + tab. + \row + \o shape + \o A value of the QTabBar::Shape enum indication + whether the tab has rounded or triangular corners + and the orientation of the tab. + \row + \o text + \o 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 + \o Member + \o content + \row + \o leftCornerWidgetSize + \o The QSize of the left corner widget (if any). + \row + \o rightCornerWidgetSize + \o The QSize of the right corner widget (if any). + \row + \o lineWidth + \o holds the line with for drawing the panel. + \row + \o midLineWith + \o this value is currently always 0. + \row + \o shape + \o The shape of the tabs on the tab bar. + \row + \o tabBarSize + \o 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 + \o State + \o State Set When + \row + \o State_Horizontal + \o 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 + \o Member + \o Content + \row + \o maximum + \o the maximum value of the scroll bar + \row + \o minimum + \o the minimum value of the scroll bar + \row + \o notchTarget + \o the number of pixels between notches + \row + \o orientation + \o a value of the Qt::Orientation enum that specifies + whether the scroll bar is vertical or horizontal + \row + \o pageStep + \o the number to increase or decrease the sliders + value (relative to the size of the slider and its value + range) on page steps. + \row + \o singleStep + \o the number to increase or decrease the sliders + value on single (or line) steps + \row + \o sliderValue + \o The value of the slider + \row + \o sliderPosition + \o 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 + \o upsideDown + \o 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 + \o Member + \o Content + \row + \o maximum + \o the maximum value of the slider + \row + \o minimum + \o the minimum value of the slider + \row + \o notchTarget + \o this is the number of pixels between each notch + \row + \o orientation + \o a Qt::Orientation enum value that gives whether the + slider is vertical or horizontal. + \row + \o pageStep + \o a number in slider value to increase or decrease + for page steps + \row + \o singleStep + \o the number to increase or decrease the sliders + value on single (or line) steps. + \row + \o sliderValue + \o the value of the slider. + \row + \o sliderPosition + \o 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 + \o upsideDown + \o 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 + \o State + \o State Set When + \row + \o State_Sunken + \o 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 + \o Property + \o Function + \row + \o frame + \o boolean that is true if the spin box is to draw a + frame. + \row + \o buttonSymbols + \o Value of the ButtonSymbols enum that decides the + symbol on the up/down buttons. + \row + \o stepEnabled + \o 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 + \o Member + \o Content + \row + \o icon + \o The title bars icon + \row + \o text + \o the text for the title bar's label + \row + \o windowFlags + \o flags of the Qt::WindowFlag enum. The window flags + used by QMdiArea for window management. + \row + \o titleBarState + \o 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 + \o State + \o Set When + \row + \o State_Selected + \o The box is not editable and has focus + \row + \o State_Sunken + \o SC_ComboBoxArrow is active + \row + \o State_on + \o The container (list) of the box is visible + \endtable + + The style options other members are: + + \table + \header + \o Member + \o Content + \row + \o currentIcon + \o the icon of the current (selected) item of the + combo box. + \row + \o currentText + \o the text of the current item in the box. + \row + \o editable + \o holds whether the combo box is editable or not + \row + \o frame + \o holds whether the combo box has a frame or not + \row + \o iconSize + \o the size of the current items icon. + \row + \o popupRect + \o 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 + \o State + \o Set When + \row + \o State_On + \o The check box is checked + \row + \o State_Sunken + \o The checkbox is pressed down + \row + \o State_Off + \o The check box is unchecked (or there is no check box) + \endtable + + The remaining members of QStyleOptionGroupBox are: + + \table + \header + \o Member + \o Content + \row + \o features + \o flags of the QStyleOptionFrameV2::FrameFeatures + enum describing the frame of the group box. + \row + \o lineWidth + \o the line width with which to draw the panel. This + is always 1. + \row + \o text + \o the text of the group box. + \row + \o textAlignment + \o the alignment of the group box title + \row + \o textColor + \o 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 + \o State + \o Set When + \row + \o State_Horizontal + \o 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 + \o Member + \o Content + \row + \o minimum + \o The minimum value of the bar + \row + \o maximum + \o The maximum value of the bar + \row + \o progress + \o The current value of the bar + \row + \o textAlignment + \o How the text is aligned in the label + \row + \o textVisible + \o Whether the label is drawn + \row + \o text + \o The label text + \row + \o orientation + \o Progress bars can be vertical or horizontal + \row + \o invertedAppearance + \o The progress is inverted (i.e., right to left in a + horizontal bar) + \row + \o bottomToTop + \o 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 + \o State + \o Set When + \row + \o State_AutoRise + \o the tool button has the autoRise property set + \row + \o State_raised + \o the button is not sunken (i.e., by being checked or + pressed on with the mouse). + \row + \o State_Sunken + \o the button is down + \row + \o State_On + \o the button is checkable and checked. + \endtable + + QStyleOptionToolButton also contains the following members: + + \table + \header + \o Member + \o Content + \row + \o arrowType + \o 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 + \o features + \o flags of the QStyleOptionToolButton::ButtonFeature + enum describing if the button has an arrow, a menu, + and/or has a popup-delay. + \row + \o font + \o the QFont of the buttons label + \row + \o icon + \o the QIcon of the tool button + \row + \o iconSize + \o the icon size of the button's icon + \row + \o pos + \o the position of the button, as given by + QWidget::pos() + \row + \o text + \o the text of the button + \row + \o toolButtonStyle + \o 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 + \o Member + \o Content + \row + \o features + \o Holds whether the bar is movable in a value of the + ToolBarFeature, which is either Movable or None. + \row + \o lineWidth + \o The width of the tool bar frame. + \row + \o midLineWidth + \o This variable is currently not used and is always + 0. + \row + \o positionOfLine + \o The position of the toolbar line within the toolbar + area to which it belongs. + \row + \o positionWithinLine + \o The position of the toolbar within the toolbar line. + \row + \o toolBarArea + \o 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 + \o State + \o Set When + \row + \o State_Selected + \o The mouse is over the action and the action is not + a separator. + \row + \o State_Sunken + \o The mouse is pressed down on the menu item. + \row + \o State_DownArrow + \o Set if the menu item is a menu scroller and it scrolls + the menu downwards. + \endtable + + \table 90% + \header + \o Member + \o Content + \row + \o checkType + \o A value of the \l{QStyleOptionMenuItem::}{CheckType} enum, + which is either NotCheckable, Exclusive, or + NonExclusive. + \row + \o checked + \o Boolean that is true if the menu item is checked. + \row + \o font + \o The QFont to use for the menu item's text. + \row + \o icon + \o the QIcon of the menu item. + \row + \o maxIconWidth + \o The maximum width allowed for the icon + \row + \o menuHasChecableItem + \o Boolean which is true if at least one item in the + menu is checkable. + \row + \o menuItemType + \o The type of the menu item. This a value of the + \l{QStyleOptionMenuItem::}{MenuItemType}. + \row + \o menuRect + \o The bounding rectangle for the QMenu that the menu + item lives in. + \row + \o tabWidth + \o This is the distance between the text of the menu + item and the shortcut. + \row + \o text + \o 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 + \o Member + \o Content + \row + \o menuRect + \o the bounding rectangle of the entire menu bar to + which the item belongs. + \row + \o text + \o the text of the item + \row + \o icon + \o 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 + \o Member + \o Content + \row + \o icon + \o the icon of the header (for section that is being + drawn). + \row + \o iconAlignment + \o the alignment (Qt::Alignment) of the icon in the header. + \row + \o orientation + \o a Qt::Orientation value deciding whether the header + is the horizontal header above the view or the + vertical header on the left. + \row + \o position + \o a QStyleOptionHeader::SectionPosition value + giving the header section's position relative to + the other sections. + \row + \o section + \o holds the section that is being drawn. + \row + \o selectedPosition + \o a QStyleOptionHeader::SelectedPosition value giving + the selected section's position relative to the + section that is being painted. + \row + \o sortIndicator + \o a QStyleOptionHeader::SortIndicator value that + describes the direction in which the section's sort + indicator should be drawn. + \row + \o text + \o the text of the currently drawn section. + \row + \o textAlignment + \o 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 + \o State + \o Set When + \row + \o State_Sibling + \o the node in the tree has a sibling (i.e., there is + another node in the same column). + \row + \o State_Item + \o this branch indicator has an item. + \row + \o State_Children + \o the branch has children (i.e., a new sub-tree can + be opened at the branch). + \row + \o State_Open + \o 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 + \o Member + \o Content + \row + \o icon + \o the icon on the toolbox tab + \row + \o text + \o 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 + \o Member + \o Content + \row + \o corner + \o 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 + \o Member + \o Content + \row + \o opaque + \o boolean that is true if the rubber band must be + drawn in an opaque style (i.e., color) + \row + \o shape + \o 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 + \o Member + \o Content + \row + \o closeable + \o boolean that holds whether the dock window can be + closed + \row + \o floatable + \o boolean that holds whether the dock window can + float (i.e., detach from the main window in which + it lives) + \row + \o movable + \o boolean that holds whether the window is movable + (i.e., can move to other dock widget areas) + \row + \o title + \o 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-and-layouts/stylesheet.qdoc b/doc/src/widgets-and-layouts/stylesheet.qdoc new file mode 100644 index 0000000..6a3fcb2 --- /dev/null +++ b/doc/src/widgets-and-layouts/stylesheet.qdoc @@ -0,0 +1,3962 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $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 + + \previouspage {Implementing 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 + \i \l{Overview} + \i \l{The Style Sheet Syntax} + \i \l{Qt Designer Integration} + \i \l{Customizing Qt Widgets Using Style Sheets} + \i \l{Qt Style Sheets Reference} + \i \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 \o \inlineimage stylesheet-coffee-xp.png + \o \inlineimage stylesheet-pagefold.png + \row \o Coffee theme running on Windows XP + \o Pagefold theme running on Windows XP + \endtable + + \table + \row \o \inlineimage stylesheet-coffee-cleanlooks.png + \o \inlineimage stylesheet-pagefold-mac.png + \row \o Coffee theme running on Ubuntu Linux + \o 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 + \o Selector + \o Example + \o Explanation + + \row + \o Universal Selector + \o \c * + \o Matches all widgets. + + \row + \o Type Selector + \o \c QPushButton + \o Matches instances of QPushButton and of its subclasses. + + \row + \o Property Selector + \o \c{QPushButton[flat="false"]} + \o Matches instances of QPushButton that are not + \l{QPushButton::}{flat}. You may use this selector to test + for any Qt property specified using Q_PROPERTY(). 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 + \o Class Selector + \o \c .QPushButton + \o Matches instances of QPushButton, but not of its subclasses. + + This is equivalent to \c{*[class~="QPushButton"]}. + + \row + \o ID \target ID Selector + Selector + \o \c{QPushButton#okButton} + \o Matches all QPushButton instances whose + \l{QObject::objectName}{object name} is \c okButton. + + \row + \o Descendant Selector + \o \c{QDialog QPushButton} + \o Matches all instances of QPushButton that are descendants + (children, grandchildren, etc.) of a QDialog. + + \row + \o Child Selector + \o \c{QDialog > QPushButton} + \o 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, \bold{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 + \o \e{count the number of ID attributes in the selector (= a)} + \o \e{count the number of other attributes and pseudo-classes in the selector (= b)} + \o \e{count the number of element names in the selector (= c)} + \o \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.qdoc 21 + + Then we set a style sheet on a QPushButton object: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 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.qdoc 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 \bold{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.qdoc 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.qdoc 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.qdoc 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 <namespace>::<classname>. 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.qdoc 27 + + \section1 Setting QObject properties + + From 4.3 and above, any designable Q_PROPERTY + can be set using the qproperty-<property name> 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 + \o The margin falls outside the border. + \o The border is drawn between the margin and the padding. + \o The padding falls inside the border, between the border and + the actual contents. + \o 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 + \o Set clip for entire rendering operation (border-radius) + \o Draw the background (background-image) + \o Draw the border (border-image, border) + \o 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 + \o Render the QComboBox { } rule + \o Render the QComboBox::drop-down { } rule + \o 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, \bold{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 + \o Widget + \o How to Style + + \row + \o QAbstractScrollArea \target qabstractscrollarea-widget + \o 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 + \o QCheckBox \target qcheckbox-widget + \o 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 + \o QColumnView \target qcolumnview-widget + \o 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 + \o QComboBox \target qcombobox-widget + \o 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 + \o QDateEdit \target qdateedit-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QDateTimeEdit \target qdatetimeedit-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QDialog \target qdialog-widget + \o 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 + \o QDialogButtonBox \target qdialogbuttonbox-widget + \o The layout of buttons can be altered using the + \l{#button-layout-prop}{button-layout} property. + + \row + \o QDockWidget \target qdockwidget-widget + \o 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 + \o QDoubleSpinBox \target qdoublespinbox-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QFrame \target qframe-widget + \o 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 + \o QGroupBox \target qgroupbox-widget + \o 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 + \o QHeaderView \target qheaderview-widget + \o 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} 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 + \o QLabel \target qlabel-widget + \o 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 + \o QLineEdit \target qlineedit-widget + \o 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 + \o QListView \target qlistview-widget + \o 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 + \o QListWidget \target qlistwidget-widget + \o See \l{#qlistview-widget}{QListView}. + + \row + \o QMainWindow \target qmainwindow-widget + \o 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 + \o QMenu \target qmenu-widget + \o 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{#tear-off-sub}{::tear-off}. + + See \l{Qt Style Sheets Examples#Customizing QMenu}{Customizing QMenu} + for an example. + + \row + \o QMenuBar \target qmenubar-widget + \o 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 + \o QMessageBox \target qmessagebox-widget + \o 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 + \o QProgressBar \target qprogressbar-widget + \o 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 + \o QPushButton \target qpushbutton-widget + \o 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 + \o QRadioButton \target qradiobutton-widget + \o 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 + \o QScrollBar \target qscrollbar-widget + \o 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 + \o QSizeGrip \target qsizegrip-widget + \o 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 + \o QSlider \target qslider-widget + \o 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 + \o QSpinBox \target qspinbox-widget + \o 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 + \o QSplitter \target qsplitter-widget + \o 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 + \o QStatusBar \target qstatusbar-widget + \o 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 + \o QTabBar \target qtabbar-widget + \o Individual tabs may be 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. + + 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 + \o QTabWidget \target qtabwidget-widget + \o 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 + \o QTableView \target qtableview-widget + \o 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 + \o QTableWidget \target qtablewidget-widget + \o See \l{#qtableview-widget}{QTableView}. + + \row + \o QTextEdit \target qtextedit-widget + \o 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 + \o QTimeEdit \target qtimeedit-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QToolBar \target qtoolbar-widget + \o 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 + \o QToolButton \target qtoolbutton-widget + \o 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 + \o QToolBox \target qtoolbox-widget + \o 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 + \o QToolTip \target qtooltip-widget + \o 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 + \o QTreeView \target qtreeview-widget + \o 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 + \o QTreeWidget \target qtreewidget-widget + \o See \l{#qtreeview-widget}{QTreeView}. + + \row + \o QWidget \target qwidget-widget + \o 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.qdoc 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 + \o Property + \o Type + \o Description + + \row + \o \bold{\c alternate-background-color} \target alternate-background-color-prop + \o \l{#Brush}{Brush} \BR + \o 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 + \o \bold{\c background} \target background-prop + \o \l{#Background}{Background} + \o 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 + \o \c background-color \target background-color-prop + \o \l{#Brush}{Brush} \BR + \o The background color used for the widget. + + Examples: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 36 + + \row + \o \c background-image \target background-image-prop + \o \l{#Url}{Url} + \o 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 + \o \c background-repeat \target background-repeat-prop + \o \l{#Repeat}{Repeat} + \o 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 + \o \c background-position + \o \l{#Alignment}{Alignment} + \o 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 + \o \bold{\c background-attachment} \target background-attachment-prop + \o \l{#Attachment}{Attachment} + \o 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 + \o \bold{\c background-clip} \target background-clip-prop + \o \l{#Origin}{Origin} + \o 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 + \o \bold{\c background-origin} \target background-origin-prop + \o \l{#Origin}{Origin} + \o 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 + \o \bold{\c border} \target border-prop + \o \l{#Border}{Border} + \o 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 + \o \c border-top + \o \l{#Border}{Border} + \o 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 + \o \c border-right + \o \l{#Border}{Border} + \o 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 + \o \c border-bottom + \o \l{#Border}{Border} + \o 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 + \o \c border-left + \o \l{#Border}{Border} + \o 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 + \o \bold{\c border-color} \target border-attrs + \target border-color-prop + \o \l{#Box Colors}{Box Colors} + \o 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 + \o \c border-top-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's top edge. + + \row + \o \c border-right-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's right edge. + + \row + \o \c border-bottom-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's bottom edge. + + \row + \o \c border-left-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's left edge. + + \row + \o \bold{\c border-image} \target border-image-prop + \o \l{#Border Image}{Border Image} + \o 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 + \o \bold{\c border-radius} \target border-radius-prop + \o \l{#Radius}{Radius} + \o 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 + \o \c border-top-left-radius + \o \l{#Radius}{Radius} + \o The radius of the border's top-left corner. + + \row + \o \c border-top-right-radius + \o \l{#Radius}{Radius} + \o The radius of the border's top-right corner. + + \row + \o \c border-bottom-right-radius + \o \l{#Radius}{Radius} + \o The radius of the border's bottom-right corner. Setting + this property to a positive value results in a rounded + corner. + + \row + \o \c border-bottom-left-radius + \o \l{#Radius}{Radius} + \o The radius of the border's bottom-left corner. Setting this + property to a positive value results in a rounded corner. + + \row + \o \bold{\c border-style} \target border-style-prop + \o \l {Border Style} + \o 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 + \o \c border-top-style + \o \l{#Border Style}{Border Style} + \o The style of the border's top edge. + + \row + \o \c border-right-style + \o \l{#Border Style}{Border Style} + \o The style of the border's right edge/ + + \row + \o \c border-bottom-style + \o \l{#Border Style}{Border Style} + \o The style of the border's bottom edge. + + \row + \o \c border-left-style + \o \l{#Border Style}{Border Style} + \o The style of the border's left edge. + + \row + \o \bold{\c border-width} \target border-width-prop + \o \l{#Box Lengths}{Box Lengths} + \o 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 + \o \c border-top-width + \o \l{#Length}{Length} + \o The width of the border's top edge. + + \row + \o \c border-right-width + \o \l{#Length}{Length} + \o The width of the border's right edge. + + \row + \o \c border-bottom-width + \o \l{#Length}{Length} + \o The width of the border's bottom edge. + + \row + \o \c border-left-width + \o \l{#Length}{Length} + \o The width of the border's left edge. + + \row + \o \bold{\c bottom} \target bottom-prop + \o \l{#Length}{Length} + \o 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 + \o \bold{\c button-layout} \target button-layout-prop + \o \l{#Number}{Number} + \o 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 + \o \bold{\c color} \target color-prop + \o \l{#Brush}{Brush} \BR + \o 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 + \o \bold{\c dialogbuttonbox-buttons-have-icons} + \o \l{#Boolean}{Boolean} + \o 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 + \o \bold{\c etch-disabled-text}* + \o \l{#Boolean}{Boolean} + \o 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 + \o \bold{\c font} \target font-prop + \o \l{#Font}{Font} + \o 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 + \o \c font-family + \o String + \o The font family. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 54 + + \row + \o \c font-size + \o \l{#Font Size}{Font Size} + \o 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 + \o \c font-style + \o \l {Font Style} + \o The font style. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 56 + + \row + \o \c font-weight + \o \l{#Font Weight}{Font Weight} + \o The weight of the font. + + \row + \o \bold{\c gridline-color}* \target gridline-color-prop + \o \l{#Color}{Color} \BR + \o 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 + \o \bold{\c height} \target height-prop + \o \l{#Length}{Length} + \o 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 + \o \bold{\c icon-size} \target icon-size-prop + \o \l{#Length}{Length} + \o The width and height of the icon in a widget. + + The icon size of the following widgets can be set using this + property. + \list + \i QCheckBox + \i QListView + \i QPushButton + \i QRadioButton + \i QTabBar + \i QToolBar + \i QToolBox + \i QTreeView + \endlist + + \row + \o \bold{\c image}* \target image-prop + \o \l{#Url}{Url}+ + \o 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}. + + \warning The QIcon SVG plugin is needed to render SVG images. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 59 + + \row + \o \bold{\c image-position} \target image-position-prop + \o \l{#Alignment}{alignment} + \o In Qt 4.3 and later, the alignment of the image image's position can be specified + using relative or absolute position. + + \row + \o \bold{\c left} \target left-prop + \o \l{#Length}{Length} + \o 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 + \o \bold{\c lineedit-password- \BR \c character}* \target lineedit-password-character-prop + \o \l{#Number}{Number} + \o 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 + \o \bold{\c margin} \target margin-prop + \o \l {Box Lengths} + \o 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 + \o \c margin-top + \o \l{#Length}{Length} + \o The widget's top margin. + + \row + \o \c margin-right + \o \l{#Length}{Length} + \o The widget's right margin. + + \row + \o \c margin-bottom + \o \l{#Length}{Length} + \o The widget's bottom margin. + + \row + \o \c margin-left + \o \l{#Length}{Length} + \o The widget's left margin. + + \row + \o \bold{\c max-height} \target max-height-prop + \o \l{#Length}{Length} + \o 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. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 63 + + See also \l{#max-width-prop}{max-width}. + + \row + \o \bold{\c max-width} \target max-width-prop + \o \l{#Length}{Length} + \o 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. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 64 + + See also \l{#max-height-prop}{max-height}. + + + \row + \o \bold{\c messagebox-text- \target messagebox-text-interaction-flags-prop + \BR \c interaction-flags}* + \o \l{#Number}{Number} + \o 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 + \o \bold{\c min-height} \target min-height-prop + \o \l{#Length}{Length} + \o 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. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 66 + + See also \l{#min-width-prop}{min-width}. + + \row + \o \bold{\c min-width} \target min-width-prop + \o \l{#Length}{Length} + \o 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. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 67 + + See also \l{#min-height-prop}{min-height}. + + \row + \o \bold{\c opacity}* \target opacity-prop + \o \l{#Number}{Number} + \o 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 + \o \bold{\c padding} \target padding-prop + \o \l{#Box Lengths}{Box Lengths} + \o 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 + \o \c padding-top + \o \l{#Length}{Length} + \o The widget's top padding. + + \row + \o \c padding-right + \o \l{#Length}{Length} + \o The widget's right padding. + + \row + \o \c padding-bottom + \o \l{#Length}{Length} + \o The widget's bottom padding. + + \row + \o \c padding-left + \o \l{#Length}{Length} + \o The widget's left padding. + + \row + \o \bold{\c paint-alternating-row-colors-for-empty-area} + \target paint-alternating-row-colors-for-empty-area-prop + \o \c bool + \o Whether the QTreeView paints alternating row colors for the empty + area (i.e the area where there are no items) + + \row + \o \bold{\c position} \target position-prop + \o \c relative \BR + | \c absolute + \o 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 + \o \bold{\c right} \target right-prop + \o \l{#Length}{Length} + \o 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 + \o \bold{\c selection-background-color}* \target selection-background-color-prop + \o \l{#Brush}{Brush} \BR + \o 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 + \o \bold{\c selection-color}* \target selection-color-prop + \o \l{#Brush}{Brush} \BR + \o 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 + \o \bold{\c show-decoration- \target show-decoration-selected-prop + \BR \c selected}* + \o \l{#Boolean}{Boolean} + \o 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 + \o \bold{\c spacing}* \target spacing-prop + \o \l{#Length}{Length} + \o 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 + \o \bold{\c subcontrol-origin}* \target subcontrol-origin-prop + \o \l{#Origin}{Origin} + \o 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 + \o \bold{\c subcontrol-position}* \target subcontrol-position-prop + \o \l{#Alignment}{Alignment} + \o 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 + \o \bold{\c text-align} \target text-align-prop + \o \l{#Alignment}{Alignment} + \o 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 + \o \bold{\c text-decoration} + \o \c none \BR + \c underline \BR + \c overline \BR + \c line-through + \o Additional text effects + + \row + \o \bold{\c top} \target top-prop + \o \l{#Length}{Length} + \o 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 + \o \bold{\c width} \target width-prop + \o \l{#Length}{Length} + \o 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 + \o Name + \o QStyle::StandardPixmap + + \row + \o backward-icon + \o QStyle::SP_ArrowBack + + \row + \o cd-icon + \o QStyle::SP_DriveCDIcon + + \row + \o computer-icon + \o QStyle::SP_ComputerIcon + + \row + \o desktop-icon + \o QStyle::SP_DesktopIcon + + \row + \o dialog-apply-icon + \o QStyle::SP_DialogApplyButton + + \row + \o dialog-cancel-icon + \o QStyle::SP_DialogCancelButton + + \row + \o dialog-close-icon + \o QStyle::SP_DialogCloseButton + + \row + \o dialog-discard-icon + \o QStyle::SP_DialogDiscardButton + + \row + \o dialog-help-icon + \o QStyle::SP_DialogHelpButton + + \row + \o dialog-no-icon + \o QStyle::SP_DialogNoButton + + \row + \o dialog-ok-icon + \o QStyle::SP_DialogOkButton + + \row + \o dialog-open-icon + \o QStyle::SP_DialogOpenButton + + \row + \o dialog-reset-icon + \o QStyle::SP_DialogResetButton + + \row + \o dialog-save-icon + \o QStyle::SP_DialogSaveButton + + \row + \o dialog-yes-icon + \o QStyle::SP_DialogYesButton + + \row + \o directory-closed-icon + \o QStyle::SP_DirClosedIcon + + \row + \o directory-icon + \o QStyle::SP_DirIcon + + \row + \o directory-link-icon + \o QStyle::SP_DirLinkIcon + + \row + \o directory-open-icon + \o QStyle::SP_DirOpenIcon + + \row + \o dockwidget-close-icon + \o QStyle::SP_DockWidgetCloseButton + + \row + \o downarrow-icon + \o QStyle::SP_ArrowDown + + \row + \o dvd-icon + \o QStyle::SP_DriveDVDIcon + + \row + \o file-icon + \o QStyle::SP_FileIcon + + \row + \o file-link-icon + \o QStyle::SP_FileLinkIcon + + \omit + \row + \o filedialog-backward-icon + \o QStyle::SP_FileDialogBack + \endomit + + \row + \o filedialog-contentsview-icon + \o QStyle::SP_FileDialogContentsView + + \row + \o filedialog-detailedview-icon + \o QStyle::SP_FileDialogDetailedView + + \row + \o filedialog-end-icon + \o QStyle::SP_FileDialogEnd + + \row + \o filedialog-infoview-icon + \o QStyle::SP_FileDialogInfoView + + \row + \o filedialog-listview-icon + \o QStyle::SP_FileDialogListView + + \row + \o filedialog-new-directory-icon + \o QStyle::SP_FileDialogNewFolder + + \row + \o filedialog-parent-directory-icon + \o QStyle::SP_FileDialogToParent + + \row + \o filedialog-start-icon + \o QStyle::SP_FileDialogStart + + \row + \o floppy-icon + \o QStyle::SP_DriveFDIcon + + \row + \o forward-icon + \o QStyle::SP_ArrowForward + + \row + \o harddisk-icon + \o QStyle::SP_DriveHDIcon + + \row + \o home-icon + \o QStyle::SP_DirHomeIcon + + \row + \o leftarrow-icon + \o QStyle::SP_ArrowLeft + + \row + \o messagebox-critical-icon + \o QStyle::SP_MessageBoxCritical + + \row + \o messagebox-information-icon + \o QStyle::SP_MessageBoxInformation + + \row + \o messagebox-question-icon + \o QStyle::SP_MessageBoxQuestion + + \row + \o messagebox-warning-icon + \o QStyle::SP_MessageBoxWarning + + \row + \o network-icon + \o QStyle::SP_DriveNetIcon + + \row + \o rightarrow-icon + \o QStyle::SP_ArrowRight + + \row + \o titlebar-contexthelp-icon + \o QStyle::SP_TitleBarContextHelpButton + + \row + \o titlebar-maximize-icon + \o QStyle::SP_TitleBarMaxButton + + \row + \o titlebar-menu-icon + \o QStyle::SP_TitleBarMenuButton + + \row + \o titlebar-minimize-icon + \o QStyle::SP_TitleBarMinButton + + \row + \o titlebar-normal-icon + \o QStyle::SP_TitleBarNormalButton + + \row + \o titlebar-shade-icon + \o QStyle::SP_TitleBarShadeButton + + \row + \o titlebar-unshade-icon + \o QStyle::SP_TitleBarUnshadeButton + + \row + \o trash-icon + \o QStyle::SP_TrashIcon + + \row + \o uparrow-icon + \o 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 + \o Type + \o Syntax + \o Description + + \row + \o \bold Alignment \target Alignment + \o \{ \c top \BR + | \c bottom \BR + | \c left \BR + | \c right \BR + | \c center \}* + \o Horizontal and/or vertical alignment. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 80 + + \row + \o \bold Attachment \target Attachment + \o \{ \c scroll \BR + | \c fixed \}* + \o Scroll or fixed attachment. + + \row + \o \bold Background \target Background + \o \{ \l{#Brush}{Brush} \BR + | \l{#Url}{Url} \BR + | \l{#Repeat}{Repeat} \BR + | \l{#Alignment}{Alignment} \}* + \o A sequence of \l{#Brush}{Brush}, \l{#Url}{Url}, + \l{#Repeat}{Repeat}, and \l{#Alignment}{Alignment}. + + \row + \o \bold Boolean \target Boolean + \o 0 | 1 + \o True (\c 1) or false (\c 0). + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 81 + + \row + \o \bold Border \target Border + \o \{ \l{#Border Style}{Border Style} \BR + | \l{#Length}{Length} \BR + | \l{#Brush}{Brush} \}* + \o Shorthand border property. + + \row + \o \bold{Border \target Border Image + Image} + \o \c none \BR + | \l{Url} \l{Number}\{4\} \BR (\c stretch | \c repeat){0,2} + \o 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 + \o \bold{Border \target Border Style + Style} + \o \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 + \o 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 + \o \bold{Box \target Box Colors + Colors} + \o \l{#Brush}{Brush}\{1,4\} + \o 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 + \o \bold{Box \target Box Lengths + Lengths} + \o \l{#Length}{Length}\{1,4\} + \o 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 + \o \bold Brush \target Brush + \o \l{#Color}{Color} \BR + | \l{Gradient} \BR + | \l{PaletteRole} + \o Specifies a Color or a Gradient or an entry in the Palette. + + \row + \o \bold Color \target Color + \o \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 + \o 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 + \o \bold Font \target Font + \o (\l{#Font Style}{Font Style} | \l{#Font Weight}{Font Weight}){0,2} \l{#Font Size}{Font Size} String + \o Shorthand font property. + + \row + \o \bold{Font \target Font Size + Size} + \o \l{Length} + \o The size of a font. + + \row + \o \bold{Font \target Font Style + Style} + \o \c normal \BR + | \c italic \BR + | \c oblique + \o The style of a font. + + \row + \o \bold{Font \target Font Weight + Weight} + \o \c normal \BR + | \c bold \BR + | \c 100 \BR + | \c 200 \BR + ... \BR + | \c 900 + \o The weight of a font. + + \row + \o \bold Gradient \target Gradient + \o \c qlineargradient \BR + | \c qradialgradient \BR + | \c qconicalgradient + \o Specifies gradient fills. There are three types of gradient fills: + + \list + \o \e{Linear} gradients interpolate colors between start and + end points. + \o \e{Radial} gradients interpolate colors between a focal + point and end points on a circle surrounding it. + \o \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 + \o \bold Icon \target Icon + \o (\l{#Url}{Url} (\c disabled | \c active | \c normal | \c selected)? + (\c on | \c off)? )* + \o A list of url, QIcon::Mode and QIcon::State. + + Example: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 86 + + \row + \o \bold Length \target Length + \o \l{#Number}{Number} (\c px | \c pt | \c em | \c ex)? + \o 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 + \o \c px: pixels + \o \c pt: the size of one point (i.e., 1/72 of an inch) + \o \c em: the em width of the font (i.e., the width of 'M') + \o \c ex: the ex width of the font (i.e., the height of 'x') + \endlist + + \row + \o \bold Number \target Number + \o A decimal integer or a real number + \o Examples: \c 0, \c 18, \c +127, \c -255, \c 12.34, \c -.5, + \c 0009. + + \row + \o \bold Origin \target Origin + \o \c margin \BR + | \c border \BR + | \c padding \BR + | \c content + \o Indicates which of four rectangles to use. + + \list + \o \c margin: The margin rectangle. The margin falls outside the border. + \o \c border: The border rectangle. This is where any border is drawn. + \o \c padding: The padding rectangle. Unlike the margins, + padding is located inside the border. + \o \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 + \o \bold PaletteRole \target PaletteRole + \o \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 + \o 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 + \o \bold Radius \target Radius + \o \l{#Length}{Length}\{1, 2\} + \o 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 + \o \bold Repeat \target Repeat + \o \c repeat-x \BR + | \c repeat-y \BR + | \c repeat \BR + | \c no-repeat + \o A value indicating the nature of repetition. + + \list + \o \c repeat-x: Repeat horizontally. + \o \c repeat-y: Repeat vertically. + \o \c repeat: Repeat horizontally and vertically. + \o \c no-repeat: Don't repeat. + \endlist + + \row + \o \bold Url \target Url + \o \tt{url(\e{filename})} + \o \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 + \o Pseudo-State + \o Description + + \row \o \c :active \target active + \o This state is set when the widget resides in an active window. + + \row + \o \c :adjoins-item \target adjoins-item-ps + \o This state is set when the \l{#branch-sub}{::branch} of a QTreeView + is adjacent to an item. + + \row + \o \c :alternate \target alternate-ps + \o This state is set for every alternate row whe painting the row of + a QAbstractItemView when QAbstractItemView::alternatingRowColors() + is set to true. + + \row + \o \c :bottom \target bottom-ps + \o The item is positioned at the bottom. For example, a QTabBar + that has its tabs positioned at the bottom. + + \row + \o \c :checked \target checked-ps + \o The item is checked. For example, the + \l{QAbstractButton::checked}{checked} state of QAbstractButton. + + \row + \o \c :closable \target closable-ps + \o The items can be closed. For example, the QDockWidget has the + QDockWidget::DockWidgetClosable feature turned on. + + \row + \o \c :closed \target closed-ps + \o The item is in the closed state. For example, an non-expanded + item in a QTreeView + + \row + \o \c :default \target default-ps + \o The item is the default. For example, a + \l{QPushButton::default}{default} QPushButton or a default action + in a QMenu. + + \row + \o \c :disabled \target disabled-ps + \o The item is \l{QWidget::enabled}{disabled}. + + \row + \o \c :editable \target editable-ps + \o The QComboBox is editable. + + \row + \o \c :edit-focus \target edit-focus-ps + \o The item has edit focus (See QStyle::State_HasEditFocus). This state + is available only for Qt Extended applications. + + \row + \o \c :enabled \target enabled-ps + \o The item is \l{QWidget::enabled}{enabled}. + + \row + \o \c :exclusive \target exclusive-ps + \o The item is part of an exclusive item group. For example, a menu + item in a exclusive QActionGroup. + + \row + \o \c :first \target first-ps + \o The item is the first (in a list). For example, the first + tab in a QTabBar. + + \row + \o \c :flat \target flat-ps + \o The item is flat. For example, a + \l{QPushButton::flat}{flat} QPushButton. + + \row + \o \c :floatable \target floatable-ps + \o The items can be floated. For example, the QDockWidget has the + QDockWidget::DockWidgetFloatable feature turned on. + + \row + \o \c :focus \target focus-ps + \o The item has \l{QWidget::hasFocus()}{input focus}. + + \row + \o \c :has-children \target has-children-ps + \o The item has children. For example, an item in a + QTreeView that has child items. + + \row + \o \c :has-siblings \target has-siblings-ps + \o The item has siblings. For example, an item in a + QTreeView that siblings. + + \row + \o \c :horizontal \target horizontal-ps + \o The item has horizontal orientation + + \row + \o \c :hover \target hover-ps + \o The mouse is hovering over the item. + + \row + \o \c :indeterminate \target indeterminate-ps + \o The item has indeterminate state. For example, a QCheckBox + or QRadioButton is \l{Qt::PartiallyChecked}{partially checked}. + + \row + \o \c :last \target last-ps + \o The item is the last (in a list). For example, the last + tab in a QTabBar. + + \row + \o \c :left \target left-ps + \o The item is positioned at the left. For example, a QTabBar + that has its tabs positioned at the left. + + \row + \o \c :maximized \target maximized-ps + \o The item is maximized. For example, a maximized QMdiSubWindow. + + \row + \o \c :middle \target middle-ps + \o 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 + \o \c :minimized \target minimized-ps + \o The item is minimized. For example, a minimized QMdiSubWindow. + + \row + \o \c :movable \target movable-ps + \o The item can be moved around. For example, the QDockWidget has the + QDockWidget::DockWidgetMovable feature turned on. + + \row + \o \c :no-frame \target no-frame-ps + \o The item has no frame. For example, a frameless QSpinBox + or QLineEdit. + + \row + \o \c :non-exclusive \target non-exclusive-ps + \o The item is part of a non-exclusive item group. For example, a menu + item in a non-exclusive QActionGroup. + + \row + \o \c :off \target off-ps + \o For items that can be toggled, this applies to items + in the "off" state. + + \row + \o \c :on \target on-ps + \o For items that can be toggled, this applies to widgets + in the "on" state. + + \row + \o \c :only-one \target only-one-ps + \o The item is the only one (in a list). For example, a lone tab + in a QTabBar. + + \row + \o \c :open \target open-ps + \o 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 + \o \c :next-selected \target next-selected-ps + \o The next item (in a list) is selected. For example, the + selected tab of a QTabBar is next to this item. + + \row + \o \c :pressed \target pressed-ps + \o The item is being pressed using the mouse. + + \row + \o \c :previous-selected \target previous-selected-ps + \o The previous item (in a list) is selected. For example, a + tab in a QTabBar that is next to the selected tab. + + \row + \o \c :read-only \target read-only-ps + \o The item is marked read only or non-editable. For example, + a read only QLineEdit or a non-editable QComboBox. + + \row + \o \c :right \target right-ps + \o The item is positioned at the right. For example, a QTabBar + that has its tabs positioned at the right. + + \row + \o \c :selected \target selected-ps + \o The item is selected. For example, the selected tab in + a QTabBar or the selected item in a QMenu. + + \row + \o \c :top \target top-ps + \o The item is positioned at the top. For example, a QTabBar + that has its tabs positioned at the top. + + \row + \o \c :unchecked \target unchecked-ps + \o The item is + \l{QAbstractButton::checked}{unchecked}. + + \row + \o \c :vertical \target vertical-ps + \o The item has vertical orientation. + + \row + \o \c :window \target window-ps + \o 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 + \o Sub-Control + \o Description + + \row + \o \c ::add-line \target add-line-sub + \o The button to add a line of a QScrollBar. + + \row + \o \c ::add-page \target add-page-sub + \o The region between the handle (slider) and the \l{#add-line-sub}{add-line} + of a QScrollBar. + + \row + \o \c ::branch \target branch-sub + \o The branch indicator of a QTreeView. + + \row + \o \c ::chunk \target chunk-sub + \o The progress chunk of a QProgressBar. + + \row + \o \c ::close-button \target close-button-sub + \o The close button of a QDockWidget. + + \row + \o \c ::corner \target corner-sub + \o The corner between two scrollbars in a QAbstractScrollArea + + \row + \o \c ::down-arrow \target down-arrow-sub + \o The down arrow of a QComboBox, QHeaderView (sort indicator), + QScrollBar or QSpinBox. + + \row + \o \c ::down-button \target down-button-sub + \o The down button of a QScrollBar or a QSpinBox. + + \row + \o \c ::drop-down \target drop-down-sub + \o The drop-down button of a QComboBox. + + \row + \o \c ::float-button \target float-button-sub + \o The float button of a QDockWidget + + \row + \o \c ::groove \target groove-sub + \o The groove of a QSlider. + + \row + \o \c ::indicator \target indicator-sub + \o The indicator of a QAbstractItemView, a QCheckBox, a QRadioButton, + a checkable QMenu item or a checkable QGroupBox. + + \row + \o \c ::handle \target handle-sub + \o The handle (slider) of a QScrollBar, a QSplitter, or a QSlider. + + \row + \o \c ::icon \target icon-sub + \o The icon of a QAbstractItemView or a QMenu. + + \row + \o \c ::item \target item-sub + \o An item of a QAbstractItemView, a QMenuBar, a QMenu, or + a QStatusBar. + + \row + \o \c ::left-arrow \target left-arrow-sub + \o The left arrow of a QScrollBar. + + \row + \o \c ::left-corner \target left-corner-sub + \o The left corner of a QTabWidget. For example, this control can be + used to control position the left corner widget in a QTabWidget. + + \row + \o \c ::menu-arrow \target menu-arrow-sub + \o The arrow of a QToolButton with a menu. + + \row + \o \c ::menu-button \target menu-button-sub + \o The menu button of a QToolButton. + + \row + \o \c ::menu-indicator \target menu-indicator-sub + \o The menu indicator of a QPushButton. + + \row + \o \c ::right-arrow \target right-arrow-sub + \o The right arrow of a QMenu or a QScrollBar. + + \row + \o \c ::pane \target pane-sub + \o The pane (frame) of a QTabWidget. + + \row + \o \c ::right-corner \target right-corner-sub + \o 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 + \o \c ::scroller \target scroller-sub + \o The scroller of a QMenu or QTabBar. + + \row + \o \c ::section \target section-sub + \o The section of a QHeaderView. + + \row + \o \c ::separator \target separator-sub + \o The separator of a QMenu or in a QMainWindow. + + \row + \o \c ::sub-line \target sub-line-sub + \o The button to subtract a line of a QScrollBar. + + \row + \o \c ::sub-page \target sub-page-sub + \o The region between the handle (slider) and the \l{#sub-line-sub}{sub-line} + of a QScrollBar. + + \row + \o \c ::tab \target tab-sub + \o The tab of a QTabBar or QToolBox. + + \row + \o \c ::tab-bar \target tab-bar-sub + \o 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 + \o \c ::tear \target tear-sub + \o The tear indicator of a QTabBar. + + \row + \o \c ::tear-off \target tear-off-sub + \o The tear-off indicator of a QMenu. + + \row + \o \c ::text \target text-ps + \o The text of a QAbstractItemView. + + \row + \o \c ::title \target title-sub + \o The title of a QGroupBox or a QDockWidget. + + \row + \o \c ::up-arrow \target up-arrow-sub + \o The up arrow of a QHeaderView (sort indicator), QScrollBar + or a QSpinBox. + + \row + \o \c ::up-button \target up-button-sub + \o 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.qdoc 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.qdoc 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.qdoc 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.qdoc 91 + + To ensure a good contrast, we should also specify a suitable + color for the text: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 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.qdoc 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.qdoc 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 + \o 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). + \o Therefore, the button is rendered using style sheets. + \o 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 indentical 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 + + \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 + \i The QToolButton has no menu. In this case, the QToolButton is styled + exactly like QPushButton. See + \l{#Customizing QPushButton}{Customizing QPushButton} for an + example. + + \i 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. + + \i 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 + \o \inlineimage stylesheet-vline.png + \o \inlineimage stylesheet-branch-more.png + \o \inlineimage stylesheet-branch-end.png + \o \inlineimage stylesheet-branch-closed.png + \o \inlineimage stylesheet-branch-open.png + \row + \o vline.png + \o branch-more.png + \o branch-end.png + \o branch-closed.png + \o 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 + \o \inlineimage stylesheet-border-image-stretched.png + \row + \o With borders + \endtable + + \table + \row + \o \inlineimage stylesheet-border-image-wrong.png + \row + \o Without borders + \endtable + + */ diff --git a/doc/src/widgets-and-layouts/widgets.qdoc b/doc/src/widgets-and-layouts/widgets.qdoc new file mode 100644 index 0000000..0697b94 --- /dev/null +++ b/doc/src/widgets-and-layouts/widgets.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page widgets-and-layouts.html + \title Widgets and Layouts + + \ingroup frameworks-technologies + + \nextpage Widget Classes + + The primary elements for designing user interfaces in Qt are widgets and layouts. + + \section1 Widgets + + \l{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{Application Windows and Dialogs}{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 + \o \image qgridlayout-with-5-children.png + \o \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{Implementing 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 + \o \image windowsxp-tabwidget.png + \o \image plastique-tabwidget.png + \o \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. +*/ + +/*! + \page widget-classes.html + \title Widget Classes + + \contentspage Widgets and Layouts + \nextpage Layout Management + + Below you find a list of all widget classes in Qt. You can also browse the + widget classes Qt provides in the various supported styles in the + \l{Qt Widget Gallery}. + + \tableofcontents + + \section1 Basic Widgets + + These basic widgets (controls), such as buttons, comboboxes and scroll bars, are + designed for direct use. + + \table + \row + \o \image windows-label.png + \o \image windowsvista-pushbutton.png + \o \image gtk-progressbar.png + \row + \o \image plastique-combobox.png + \o \image macintosh-radiobutton.png + \o \image cde-lineedit.png + \endtable + + \annotatedlist basicwidgets + + \section1 Advanced Widgets + + Advanced GUI widgets such as tab widgets and progress bars provide more + complex user interface controls. + + \table + \row + \o \image windowsxp-treeview.png + \o \image gtk-calendarwidget.png + \o \image qundoview.png + \endtable + + \annotatedlist advanced + + \table + \row + \o \image windowsvista-tabwidget.png + \o \image macintosh-groupbox.png + \endtable + + \section1 Organizer Widgets + + Classes like splitters, tab bars, button groups, etc are used to + organize and group GUI primitives into more complex applications or + dialogs. + + \annotatedlist organizers + + \section1 Abstract Widget Classes + + Abstract widget classes usable through subclassing. They are generally + not usable in themselves, but provide functionality that can be used + by inheriting these classes. + + \annotatedlist abstractwidgets +*/ + +/*! + \group advanced + \title Advanced Widgets +*/ + +/*! + \group abstractwidgets + \title Abstract Widget Classes +*/ + +/*! + \group basicwidgets + \title Basic Widgets +*/ + +/*! + \group organizers + \title Organizers +*/ |