diff --git a/examples/widgets/doc/src/icons.qdoc b/examples/widgets/doc/src/icons.qdoc deleted file mode 100644 index 8ec062ea43..0000000000 --- a/examples/widgets/doc/src/icons.qdoc +++ /dev/null @@ -1,805 +0,0 @@ -// Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \example widgets/icons - \title Icons Example - \ingroup examples-widgets - \brief The Icons example shows how QIcon can generate pixmaps reflecting - an icon's state, mode and size. - - These pixmaps are generated from the set of pixmaps made available to the - icon, and are used by Qt widgets to show an icon representing a particular - action. - - \image icons-example.png Screenshot of the Icons example - - Contents: - - \tableofcontents - - \section1 QIcon Overview - - The QIcon class provides scalable icons in different modes and - states. An icon's state and mode are depending on the intended use - of the icon. Qt currently defines four modes: - - \table - \header \li Mode \li Description - \row - \li QIcon::Normal - \li Display the pixmap when the user is not interacting with the - icon, but the functionality represented by the icon is - available. - \row - \li QIcon::Active - \li Display the pixmap when the functionality represented by the - icon is available and the user is interacting with the icon, - for example, moving the mouse over it or clicking it. - \row - \li QIcon::Disabled - \li Display the pixmap when the functionality represented by - the icon is not available. - \row - \li QIcon::Selected - \li Display the pixmap when the icon is selected. - \endtable - - QIcon's states are QIcon::On and QIcon::Off, which will display - the pixmap when the widget is in the respective state. The most - common usage of QIcon's states are when displaying checkable tool - buttons or menu entries (see QAbstractButton::setCheckable() and - QAction::setCheckable()). When a tool button or menu entry is - checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's - \l{QIcon::}{Off}. You can, for example, use the QIcon's states to - display differing pixmaps depending on whether the tool button or - menu entry is checked or not. - - A QIcon can generate smaller, larger, active, disabled, and - selected pixmaps from the set of pixmaps it is given. Such - pixmaps are used by Qt widgets to show an icon representing a - particular action. - - \section1 Overview of the Icons Application - - With the Icons application you get a preview of an icon's - generated pixmaps reflecting its different states, modes and size. - - When an image is loaded into the application, it is converted into - a pixmap and becomes a part of the set of pixmaps available to the - icon. An image can be excluded from this set by checking off the - related checkbox. The application provides a sub directory - containing sets of images explicitly designed to illustrate how Qt - renders an icon in different modes and states. - - The application allows you to manipulate the icon size with some - predefined sizes and a spin box. The predefined sizes are style - dependent, but most of the styles have the same values. Only the - \macos style differs by using 32 pixels instead of 16 pixels - for toolbar buttons. You can navigate between the available styles - using the \uicontrol View menu. - - \image icons-view-menu.png Screenshot of the View menu - - The \uicontrol View menu also provide the option to make the application - guess the icon state and mode from an image's file name. The \uicontrol - File menu provide the options of adding an image and removing all - images. These last options are also available through a context - menu that appears if you press the right mouse button within the - table of image files. In addition, the \uicontrol File menu provide an - \uicontrol Exit option, and the \uicontrol Help menu provide information about - the example and about Qt. - - \image icons_find_normal.png Screenshot of the Find Files - - The screenshot above shows the application with one image file - loaded. The \uicontrol {Guess Image Mode/State} is enabled and the - style is Plastique. - - When QIcon is provided with only one available pixmap, that - pixmap is used for all the states and modes. In this case the - pixmap's icon mode is set to normal, and the generated pixmaps - for the normal and active modes will look the same. But in - disabled and selected mode, Qt will generate a slightly different - pixmap. - - The next screenshot shows the application with an additional file - loaded, providing QIcon with two available pixmaps. Note that the - new image file's mode is set to disabled. When rendering the \uicontrol - Disabled mode pixmaps, Qt will now use the new image. We can see - the difference: The generated disabled pixmap in the first - screenshot is slightly darker than the pixmap with the originally - set disabled mode in the second screenshot. - - \image icons_find_normal_disabled.png Screenshot of the Find Files - - When Qt renders the icon's pixmaps it searches through the set of - available pixmaps following a particular algorithm. The algorithm - is documented in QIcon, but we will describe some particular cases - below. - - \image icons_monkey_active.png Screenshot of the Find Files - - In the screenshot above, we have set \c monkey_on_32x32 to be an - Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To - render the other six mode/state combinations, QIcon uses the - search algorithm described in the table below: - - \table 100% - \header \li{2,1} Requested Pixmap \li {8,1} Preferred Alternatives (mode/state) - \header \li Mode \li State \li 1 \li 2 \li 3 \li 4 \li 5 \li 6 \li 7 \li 8 - \row \li{1,2} Normal \li Off \li \b N0 \li A0 \li N1 \li A1 \li D0 \li S0 \li D1 \li S1 - \row \li On \li N1 \li \b A1 \li N0 \li A0 \li D1 \li S1 \li D0 \li S0 - \row \li{1,2} Active \li Off \li A0 \li \b N0 \li A1 \li N1 \li D0 \li S0 \li D1 \li S1 - \row \li On \li \b A1 \li N1 \li A0 \li N0 \li D1 \li S1 \li D0 \li S0 - \row \li{1,2} Disabled \li Off \li D0 \li \b {N0'} \li A0' \li D1 \li N1' \li A1' \li S0' \li S1' - \row \li On \li D1 \li N1' \li \b {A1'} \li D0 \li N0' \li A0' \li S1' \li S0' - \row \li{1,2} Selected \li Off \li S0 \li \b {N0''} \li A0'' \li S1 \li N1'' \li A1'' \li D0'' \li D1'' - \row \li On \li S1 \li N1'' \li \b {A1''} \li S0 \li N0'' \li A0'' \li D1'' \li D0'' - \endtable - - In the table, "0" and "1" stand for "Off" and "On", respectively. - Single quotes indicates that QIcon generates a disabled ("grayed - out") version of the pixmap; similarly, double quuote indicate - that QIcon generates a selected ("blued out") version of the - pixmap. - - The alternatives used in the screenshot above are shown in bold. - For example, the Disabled/Off pixmap is derived by graying out - the Normal/Off pixmap (\c monkey_off_64x64). - - In the next screenshots, we loaded the whole set of monkey - images. By checking or unchecking file names from the image list, - we get different results: - - \table - \row - \li \inlineimage icons_monkey.png Screenshot of the Monkey Files - \li \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files - \endtable - - For any given mode/state combination, it is possible to specify - several images at different resolutions. When rendering an - icon, QIcon will automatically pick the most suitable image - and scale it down if necessary. (QIcon never scales up images, - because this rarely looks good.) - - The screenshots below shows what happens when we provide QIcon - with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c - qt_extended_48x48.png) and try to render the QIcon at various - resolutions: - - \table - \row - \li - \li \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8 - \li \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16 - \li \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17 - \row - \li - \li 8 x 8 - \li \b {16 x 16} - \li 17 x 17 - \row - \li \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32 - \li \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33 - \li \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48 - \li \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64 - \row - \li \b {32 x 32} - \li 33 x 33 - \li \b {48 x 48} - \li 64 x 64 - \endtable - - For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and - scales it down if necessary. For sizes between 17 x 17 and 32 x - 32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses - \c qt_extended_48x48.png. - - \section1 Line-by-Line Walkthrough - - The Icons example consists of four classes: - - \list - \li \c MainWindow inherits QMainWindow and is the main application - window. - \li \c IconPreviewArea is a custom widget that displays all - combinations of states and modes for a given icon. - \li \c IconSizeSpinBox is a subclass of QSpinBox that lets the - user enter icon sizes (e.g., "48 x 48"). - \li \c ImageDelegate is a subclass of QStyledItemDelegate that - provides comboboxes for letting the user set the mode and state - associated with an image. - \endlist - - We will start by reviewing the \c IconPreviewArea class before we - take a look at the \c MainWindow class. Finally, we will review the - \c IconSizeSpinBox and \c ImageDelegate classes. - - \section2 IconPreviewArea Class Definition - - An \c IconPreviewArea widget consists of a group box containing a grid of - QLabel widgets displaying headers and pixmaps. - - \image icons_preview_area.png Screenshot of IconPreviewArea. - - \snippet widgets/icons/iconpreviewarea.h 0 - - The \c IconPreviewArea class inherits QWidget. It displays the - generated pixmaps corresponding to an icon's possible states and - modes at a given size. - - \snippet widgets/icons/iconpreviewarea.cpp 42 - - We would like the table columns to be in the order QIcon::Normal, - QIcon::Active, QIcon::Disabled, QIcon::Selected and the rows in the order - QIcon::Off, QIcon::On, which does not match the enumeration. The above code - provides arrays allowing to map from enumeration value to row/column - (by using QList::indexOf()) and back by using the array index and lists - of the matching strings. Qt's containers can be easily populated by - using C++ 11 initializer lists. - - We need two public functions to set the current icon and the - icon's size. In addition the class has three private functions: We - use the \c createHeaderLabel() and \c createPixmapLabel() - functions when constructing the preview area, and we need the \c - updatePixmapLabels() function to update the preview area when - the icon or the icon's size has changed. - - The \c NumModes and \c NumStates constants reflect \l{QIcon}'s - number of currently defined modes and states. - - \section2 IconPreviewArea Class Implementation - - \snippet widgets/icons/iconpreviewarea.cpp 0 - - In the constructor we create the labels displaying the headers and - the icon's generated pixmaps, and add them to a grid layout. - - When creating the header labels, we make sure the enums \c - NumModes and \c NumStates defined in the \c .h file, correspond - with the number of labels that we create. Then if the enums at - some point are changed, the \c Q_ASSERT() macro will alert that this - part of the \c .cpp file needs to be updated as well. - - If the application is built in debug mode, the \c Q_ASSERT() - macro will expand to - - \code - if (!condition) - qFatal("ASSERT: "condition" in file ..."); - \endcode - - In release mode, the macro simply disappear. The mode can be set - in the application's \c .pro file. One way to do so is to add an - option to \c qmake when building the application: - - \code - qmake "CONFIG += debug" icons.pro - \endcode - - or - - \code - qmake "CONFIG += release" icons.pro - \endcode - - Another approach is to add this line directly to the \c .pro - file. - - \snippet widgets/icons/iconpreviewarea.cpp 1 - \codeline - \snippet widgets/icons/iconpreviewarea.cpp 2 - - The public \c setIcon() and \c setSize() functions change the icon - or the icon size, and make sure that the generated pixmaps are - updated. - - \snippet widgets/icons/iconpreviewarea.cpp 3 - \codeline - \snippet widgets/icons/iconpreviewarea.cpp 4 - - We use the \c createHeaderLabel() and \c createPixmapLabel() - functions to create the preview area's labels displaying the - headers and the icon's generated pixmaps. Both functions return - the QLabel that is created. - - \snippet widgets/icons/iconpreviewarea.cpp 5 - - We use the private \c updatePixmapLabel() function to update the - generated pixmaps displayed in the preview area. - - For each mode, and for each state, we retrieve a pixmap using the - QIcon::pixmap() function, which generates a pixmap corresponding - to the given state, mode and size. We pass the QWindows instance - obtained by calling QWidget::windowHandle() on the top level - widget (QWidget::nativeParentWidget()) in order to retrieve - the pixmap that matches best. - We format a tooltip displaying size, actual size and device pixel - ratio. - - \section2 MainWindow Class Definition - - The \c MainWindow widget consists of three main elements: an - images group box, an icon size group box and a preview area. - - \image icons-example.png Screenshot of the Icons example - - \snippet widgets/icons/mainwindow.h 0 - - The MainWindow class inherits from QMainWindow. We reimplement the - constructor, and declare several private slots: - - \list - \li The \c about() slot simply provides information about the example. - \li The \c changeStyle() slot changes the application's GUI style and - adjust the style dependent size options. - \li The \c changeSize() slot changes the size of the preview area's icon. - \li The \c changeIcon() slot updates the set of pixmaps available to the - icon displayed in the preview area. - \li The \c addSampleImages() slot allows the user to load a new image - from the samples provided into the application. - \li The \c addOtherImages() slot allows the user to load a new image from - the directory obtained by calling - QStandardPaths::standardLocations(QStandardPaths::PicturesLocation). - \li The \c screenChanged() updates the display in the \uicontrol{High DPI} - group box to correctly display the parameters of the current screen - the window is located on. - \endlist - - In addition we declare several private functions to simplify the - constructor. - - \section2 MainWindow Class Implementation - - \snippet widgets/icons/mainwindow.cpp 0 - - In the constructor we first create the main window's central - widget and its child widgets, and put them in a grid layout. Then - we create the menus with their associated entries and actions. - - We set the window title and determine the current style for the - application. We also enable the icon size spin box by clicking the - associated radio button, making the current value of the spin box - the icon's initial size. - - \snippet widgets/icons/mainwindow.cpp 1 - - The \c about() slot displays a message box using the static - QMessageBox::about() function. In this example it displays a - simple box with information about the example. - - The \c about() function looks for a suitable icon in four - locations: It prefers its parent's icon if that exists. If it - doesn't, the function tries the top-level widget containing - parent, and if that fails, it tries the active window. As a last - resort it uses the QMessageBox's Information icon. - - \snippet widgets/icons/mainwindow.cpp 2 - - In the \c changeStyle() slot we first check the slot's - parameter. If it is false we immediately return, otherwise we find - out which style to change to, i.e. which action that triggered the - slot, using the QObject::sender() function. - - This function returns the sender as a QObject pointer. Since we - know that the sender is a QAction object, we can safely cast the - QObject. We could have used a C-style cast or a C++ \c - static_cast(), but as a defensive programming technique we use a - \l qobject_cast(). The advantage is that if the object has the - wrong type, a null pointer is returned. Crashes due to null - pointers are much easier to diagnose than crashes due to unsafe - casts. - - \snippet widgets/icons/mainwindow.cpp 3 - \snippet widgets/icons/mainwindow.cpp 4 - - Once we have the action, we extract the style name using - QAction::data(). Then we create a QStyle object using the static - QStyleFactory::create() function. - - Although we can assume that the style is supported by the - QStyleFactory: To be on the safe side, we use the \c Q_ASSERT() - macro to check if the created style is valid before we use the - QApplication::setStyle() function to set the application's GUI - style to the new style. QApplication will automatically delete - the style object when a new style is set or when the application - exits. - - The predefined icon size options provided in the application are - style dependent, so we need to update the labels in the icon size - group box and in the end call the \c changeSize() slot to update - the icon's size. - - \snippet widgets/icons/mainwindow.cpp 5 - - The \c changeSize() slot sets the size for the preview area's - icon. - - It is invoked by the QButtonGroup whose members are radio buttons for - controlling the icon size. In \c createIconSizeGroupBox(), each button is - assigned a QStyle::PixelMetric value as an id, which is passed as a - parameter to the slot. - - The special value \c OtherSize indicates that the spin box is - enabled. If it is, we extract the extent of the new size from the - box. If it's not, we query the style for the metric. Then we create - a QSize object based on the extent, and use that object to set the - size of the preview area's icon. - - \snippet widgets/icons/mainwindow.cpp 12 - - The function \c addImages() is called by the slot addSampleImages() - passing the samples directory, or by the slot addOtherImages() - passing the directory obtained by querying - QStandardPaths::standardLocations(). - - The first thing we do is to show a file dialog to the user. - We initialize it to show the filters returned by - QImageReader::supportedMimeTypes(). - - For each of the files the file dialog returns, we add a row to the - table widget. The table widget is listing the images the user has - loaded into the application. - - \snippet widgets/icons/mainwindow.cpp 13 - - We retrieve the image name using the QFileInfo::baseName() - function that returns the base name of the file without the path, - and create the first table widget item in the row. - We check if a high resolution version of the image exists (identified by - the suffix \c @2x on the base name) and display that along with the size - in the tooltip. - - We add the file's complete name to the item's data. Since an item can - hold several information pieces, we need to assign the file name a role - that will distinguish it from other data. This role can be Qt::UserRole - or any value above it. - - We also make sure that the item is not editable by removing the - Qt::ItemIsEditable flag. Table items are editable by default. - - \snippet widgets/icons/mainwindow.cpp 15 - - Then we create the second and third items in the row making the - default mode Normal and the default state Off. But if the \uicontrol - {Guess Image Mode/State} option is checked, and the file name - contains "_act", "_dis", or "_sel", the modes are changed to - Active, Disabled, or Selected. And if the file name contains - "_on", the state is changed to On. The sample files in the - example's \c images subdirectory respect this naming convention. - - \snippet widgets/icons/mainwindow.cpp 18 - - In the end we add the items to the associated row, and use the - QTableWidget::openPersistentEditor() function to create - comboboxes for the mode and state columns of the items. - - Due to the connection between the table widget's \l - {QTableWidget::itemChanged()}{itemChanged()} signal and the \c - changeIcon() slot, the new image is automatically converted into a - pixmap and made part of the set of pixmaps available to the icon - in the preview area. So, corresponding to this fact, we need to - make sure that the new image's check box is enabled. - - \snippet widgets/icons/mainwindow.cpp 6 - - The \c changeIcon() slot is called when the user alters the set - of images listed in the QTableWidget, to update the QIcon object - rendered by the \c IconPreviewArea. - - We first create a QIcon object, and then we run through the - QTableWidget, which lists the images the user has loaded into the - application. - - \snippet widgets/icons/mainwindow.cpp 8 - - We also extract the image file's name using the - QTableWidgetItem::data() function. This function takes a - Qt::DataItemRole as an argument to retrieve the right data - (remember that an item can hold several pieces of information) - and returns it as a QVariant. Then we use the - QVariant::toString() function to get the file name as a QString. - - To create a pixmap from the file, we need to first create an - image and then convert this image into a pixmap using - QPixmap::fromImage(). Once we have the final pixmap, we add it, - with its associated mode and state, to the QIcon's set of - available pixmaps. - - \snippet widgets/icons/mainwindow.cpp 11 - - After running through the entire list of images, we change the - icon of the preview area to the one we just created. - - \snippet widgets/icons/mainwindow.cpp 20 - - In the \c removeAllImages() slot, we simply set the table widget's - row count to zero, automatically removing all the images the user - has loaded into the application. Then we update the set of pixmaps - available to the preview area's icon using the \c changeIcon() - slot. - - \image icons_images_groupbox.png Screenshot of the images group box - - The \c createImagesGroupBox() function is implemented to simplify - the constructor. The main purpose of the function is to create a - QTableWidget that will keep track of the images the user has - loaded into the application. - - \snippet widgets/icons/mainwindow.cpp 21 - - First we create a group box that will contain the table widget. - Then we create a QTableWidget and customize it to suit our - purposes. - - We call QAbstractItemView::setSelectionMode() to prevent the user - from selecting items. - - The QAbstractItemView::setItemDelegate() call sets the item - delegate for the table widget. We create a \c ImageDelegate that - we make the item delegate for our view. - - The QStyledItemDelegate class can be used to provide an editor for an item view - class that is subclassed from QAbstractItemView. Using a delegate - for this purpose allows the editing mechanism to be customized and - developed independently from the model and view. - - In this example we derive \c ImageDelegate from QStyledItemDelegate. - QStyledItemDelegate usually provides line editors, while our subclass - \c ImageDelegate, provides comboboxes for the mode and state - fields. - - \snippet widgets/icons/mainwindow.cpp 22 - - Then we customize the QTableWidget's horizontal header, and hide - the vertical header. - - \snippet widgets/icons/mainwindow.cpp 24 - - At the end, we connect the QTableWidget::itemChanged() signal to - the \c changeIcon() slot to ensure that the preview area is in - sync with the image table. - - \image icons_size_groupbox.png Screenshot of the icon size group box - - The \c createIconSizeGroupBox() function is called from the - constructor. It creates the widgets controlling the size of the - preview area's icon. - - \snippet widgets/icons/mainwindow.cpp 26 - - First we create a group box that will contain all the widgets; - then we create the radio buttons and the spin box. We add the - radio buttons to an instance of QButtonGroup, using the value - of the QStyle::PixelMetric they represent as an integer id. - - \snippet widgets/icons/mainwindow.cpp 40 - - We introduce an enumeration constant \c OtherSize to represent - a custom size. - - The spin box is not a regular QSpinBox but an \c IconSizeSpinBox. - The \c IconSizeSpinBox class inherits QSpinBox and reimplements - two functions: QSpinBox::textFromValue() and - QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to - handle icon sizes, e.g., "32 x 32", instead of plain integer - values. - - \snippet widgets/icons/mainwindow.cpp 27 - - Then we connect all of the radio buttons - \l{QRadioButton::toggled()}{toggled()} signals and the spin box's - \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c - changeSize() slot to make sure that the size of the preview - area's icon is updated whenever the user changes the icon size. - In the end we put the widgets in a layout that we install on the - group box. - - \snippet widgets/icons/mainwindow.cpp 28 - - In the \c createActions() function we create and customize all the - actions needed to implement the functionality associated with the - menu entries in the application. - - In particular we create the \c styleActionGroup based on the - currently available GUI styles using - QStyleFactory. QStyleFactory::keys() returns a list of valid keys, - typically including "windows" and "fusion". Depending on the platform, - "windowsvista" and "macos" may be available. - - We create one action for each key, and adds the action to the - action group. Also, for each action, we call QAction::setData() - with the style name. We will retrieve it later using - QAction::data(). - - As we go along, we create the \uicontrol File, \uicontrol View and - \uicontrol Help menus and add the actions to them. - - The QMenu class provides a menu widget for use in menu bars, - context menus, and other popup menus. We put each menu in the - application's menu bar, which we retrieve using - QMainWindow::menuBar(). - - \snippet widgets/icons/mainwindow.cpp 30 - - QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy} - property that controls how the widget should behave when the user - requests a context menu (e.g., by right-clicking). We set the - QTableWidget's context menu policy to Qt::ActionsContextMenu, - meaning that the \l{QAction}s associated with the widget should - appear in its context menu. - - Then we add the \uicontrol{Add Image} and \uicontrol{Remove All Images} - actions to the table widget. They will then appear in the table - widget's context menu. - - \snippet widgets/icons/mainwindow.cpp 31 - - In the \c checkCurrentStyle() function we go through the group of - style actions, looking for the current GUI style. - - For each action, we first extract the style name using - QAction::data(). Since this is only a QStyleFactory key (e.g., - "macos"), we cannot compare it directly to the current - style's class name. We need to create a QStyle object using the - static QStyleFactory::create() function and compare the class - name of the created QStyle object with that of the current style. - As soon as we are done with a QStyle candidate, we delete it. - - For all QObject subclasses that use the \c Q_OBJECT macro, the - class name of an object is available through its - \l{QObject::metaObject()}{meta-object}. - - We can assume that the style is supported by - QStyleFactory, but to be on the safe side we use the \c - Q_ASSERT() macro to make sure that QStyleFactory::create() - returned a valid pointer. - - \snippet widgets/icons/mainwindow.cpp 44 - - We overload the show() function to set up the updating of the - current screen in \c screenChanged(). After calling QWidget::show(), - the QWindow associated with the QWidget is created and we can - connect to its QWindow::screenChanged() signal. - - \section2 IconSizeSpinBox Class Definition - - \snippet widgets/icons/iconsizespinbox.h 0 - - The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain - QSpinBox can only handle integers. But since we want to display - the spin box's values in a more sophisticated way, we need to - subclass QSpinBox and reimplement the QSpinBox::textFromValue() - and QSpinBox::valueFromText() functions. - - \image icons_size_spinbox.png Screenshot of the icon size spinbox - - \section2 IconSizeSpinBox Class Implementation - - \snippet widgets/icons/iconsizespinbox.cpp 0 - - The constructor is trivial. - - \snippet widgets/icons/iconsizespinbox.cpp 2 - - QSpinBox::textFromValue() is used by the spin box whenever it - needs to display a value. The default implementation returns a - base 10 representation of the \c value parameter. - - Our reimplementation returns a QString of the form "32 x 32". - - \snippet widgets/icons/iconsizespinbox.cpp 1 - - The QSpinBox::valueFromText() function is used by the spin box - whenever it needs to interpret text typed in by the user. Since - we reimplement the \c textFromValue() function we also need to - reimplement the \c valueFromText() function to interpret the - parameter text and return the associated int value. - - We parse the text using a regular expression (a QRegularExpression). We - define an expression that matches one or several digits, - optionally followed by whitespace, an "x" or the times symbol, - whitespace and one or several digits again. - - The first digits of the regular expression are captured using - parentheses. This enables us to use the QRegularExpressionMatch::captured() - or QRegularExpressionMatch::capturedTexts() functions to extract the matched - characters. If the first and second numbers of the spin box value - differ (e.g., "16 x 24"), we use the first number. - - When the user presses \uicontrol Enter, QSpinBox first calls - QSpinBox::valueFromText() to interpret the text typed by the - user, then QSpinBox::textFromValue() to present it in a canonical - format (e.g., "16 x 16"). - - \section2 ImageDelegate Class Definition - - \snippet widgets/icons/imagedelegate.h 0 - - The \c ImageDelegate class is a subclass of QStyledItemDelegate. The - QStyledItemDelegate class provides display and editing facilities for - data items from a model. A single QStyledItemDelegate object is - responsible for all items displayed in a item view (in our case, - a QTableWidget). - - A QStyledItemDelegate can be used to provide an editor for an item view - class that is subclassed from QAbstractItemView. Using a delegate - for this purpose allows the editing mechanism to be customized and - developed independently from the model and view. - - \snippet widgets/icons/imagedelegate.h 1 - - The default implementation of QStyledItemDelegate creates a QLineEdit. - Since we want the editor to be a QComboBox, we need to subclass - QStyledItemDelegate and reimplement the QStyledItemDelegate::createEditor(), - QStyledItemDelegate::setEditorData() and QStyledItemDelegate::setModelData() - functions. - - \snippet widgets/icons/imagedelegate.h 2 - - The \c emitCommitData() slot is used to emit the - QImageDelegate::commitData() signal with the appropriate - argument. - - \section2 ImageDelegate Class Implementation - - \snippet widgets/icons/imagedelegate.cpp 0 - - The constructor is trivial. - - \snippet widgets/icons/imagedelegate.cpp 1 - - The default QStyledItemDelegate::createEditor() implementation returns - the widget used to edit the item specified by the model and item - index for editing. The parent widget and style option are used to - control the appearance of the editor widget. - - Our reimplementation creates and populates a combobox instead of - the default line edit. The contents of the combobox depends on - the column in the table for which the editor is requested. Column - 1 contains the QIcon modes, whereas column 2 contains the QIcon - states. - - In addition, we connect the combobox's \l - {QComboBox::activated()}{activated()} signal to the \c - emitCommitData() slot to emit the - QAbstractItemDelegate::commitData() signal whenever the user - chooses an item using the combobox. This ensures that the rest of - the application notices the change and updates itself. - - \snippet widgets/icons/imagedelegate.cpp 2 - - The QStyledItemDelegate::setEditorData() function is used by - QTableWidget to transfer data from a QTableWidgetItem to the - editor. The data is stored as a string; we use - QComboBox::findText() to locate it in the combobox. - - Delegates work in terms of models, not items. This makes it - possible to use them with any item view class (e.g., QListView, - QListWidget, QTreeView, etc.). The transition between model and - items is done implicitly by QTableWidget; we don't need to worry - about it. - - \snippet widgets/icons/imagedelegate.cpp 3 - - The QStyledItemDelegate::setEditorData() function is used by QTableWidget - to transfer data back from the editor to the \l{QTableWidgetItem}. - - \snippet widgets/icons/imagedelegate.cpp 4 - - The \c emitCommitData() slot simply emit the - QAbstractItemDelegate::commitData() signal for the editor that - triggered the slot. This signal must be emitted when the editor - widget has completed editing the data, and wants to write it back - into the model. - - \section2 The Implementation of the Function main() - - \snippet widgets/icons/main.cpp 45 - - We use QCommandLineParser to handle any command line options or parameters - passed to the application. Then, we resize the main window according - to the available screen geometry and show it. -*/ diff --git a/examples/widgets/widgets/CMakeLists.txt b/examples/widgets/widgets/CMakeLists.txt index d852233c8d..e7f59986c6 100644 --- a/examples/widgets/widgets/CMakeLists.txt +++ b/examples/widgets/widgets/CMakeLists.txt @@ -7,7 +7,6 @@ qt_internal_add_example(calendarwidget) qt_internal_add_example(charactermap) qt_internal_add_example(digitalclock) qt_internal_add_example(groupbox) -qt_internal_add_example(icons) qt_internal_add_example(imageviewer) qt_internal_add_example(lineedits) if(QT_FEATURE_movie) diff --git a/examples/widgets/widgets/widgets.pro b/examples/widgets/widgets/widgets.pro index 36d428429c..56e275020f 100644 --- a/examples/widgets/widgets/widgets.pro +++ b/examples/widgets/widgets/widgets.pro @@ -5,7 +5,6 @@ SUBDIRS = analogclock \ charactermap \ digitalclock \ groupbox \ - icons \ imageviewer \ lineedits \ movie \ diff --git a/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp b/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp index d660d605a1..ec4b5bf27f 100644 --- a/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp +++ b/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp @@ -41,3 +41,23 @@ setRange(minimum, maximum); setMinimum(minimum); setMaximum(maximum); //! [7] + +//! [8] +int IconSizeSpinBox::valueFromText(const QString &text) const +{ + static const QRegularExpression regExp(tr("(\\d+)(\\s*[xx]\\s*\\d+)?")); + Q_ASSERT(regExp.isValid()); + + const QRegularExpressionMatch match = regExp.match(text); + if (match.isValid()) + return match.captured(1).toInt(); + return 0; +} +//! [8] + +//! [9] +QString IconSizeSpinBox::textFromValue(int value) const +{ + return tr("%1 x %1").arg(value); +} +//! [9] diff --git a/src/widgets/itemviews/qitemdelegate.cpp b/src/widgets/itemviews/qitemdelegate.cpp index 79ee203aca..ad3898e8d9 100644 --- a/src/widgets/itemviews/qitemdelegate.cpp +++ b/src/widgets/itemviews/qitemdelegate.cpp @@ -282,8 +282,7 @@ QSizeF QItemDelegatePrivate::doTextLayout(int lineWidth) const the style for drawing. \sa {Delegate Classes}, QStyledItemDelegate, QAbstractItemDelegate, - {Spin Box Delegate Example}, {Settings Editor Example}, - {Icons Example} + {Spin Box Delegate Example}, {Settings Editor Example} */ /*! diff --git a/src/widgets/widgets/qspinbox.cpp b/src/widgets/widgets/qspinbox.cpp index 5178763bc1..73946d54a9 100644 --- a/src/widgets/widgets/qspinbox.cpp +++ b/src/widgets/widgets/qspinbox.cpp @@ -132,12 +132,9 @@ public: for a custom spin box that allows the user to enter icon sizes (e.g., "32 x 32"): - \snippet widgets/icons/iconsizespinbox.cpp 1 + \snippet code/src_gui_widgets_qspinbox.cpp 8 \codeline - \snippet widgets/icons/iconsizespinbox.cpp 2 - - See the \l{widgets/icons}{Icons} example for the full source - code. + \snippet code/src_gui_widgets_qspinbox.cpp 9 \sa QDoubleSpinBox, QDateTimeEdit, QSlider, {Spin Boxes Example} */ diff --git a/examples/widgets/widgets/icons/CMakeLists.txt b/tests/manual/examples/widgets/widgets/icons/CMakeLists.txt similarity index 100% rename from examples/widgets/widgets/icons/CMakeLists.txt rename to tests/manual/examples/widgets/widgets/icons/CMakeLists.txt diff --git a/examples/widgets/widgets/icons/iconpreviewarea.cpp b/tests/manual/examples/widgets/widgets/icons/iconpreviewarea.cpp similarity index 100% rename from examples/widgets/widgets/icons/iconpreviewarea.cpp rename to tests/manual/examples/widgets/widgets/icons/iconpreviewarea.cpp diff --git a/examples/widgets/widgets/icons/iconpreviewarea.h b/tests/manual/examples/widgets/widgets/icons/iconpreviewarea.h similarity index 100% rename from examples/widgets/widgets/icons/iconpreviewarea.h rename to tests/manual/examples/widgets/widgets/icons/iconpreviewarea.h diff --git a/examples/widgets/widgets/icons/icons.pro b/tests/manual/examples/widgets/widgets/icons/icons.pro similarity index 100% rename from examples/widgets/widgets/icons/icons.pro rename to tests/manual/examples/widgets/widgets/icons/icons.pro diff --git a/examples/widgets/widgets/icons/iconsizespinbox.cpp b/tests/manual/examples/widgets/widgets/icons/iconsizespinbox.cpp similarity index 100% rename from examples/widgets/widgets/icons/iconsizespinbox.cpp rename to tests/manual/examples/widgets/widgets/icons/iconsizespinbox.cpp diff --git a/examples/widgets/widgets/icons/iconsizespinbox.h b/tests/manual/examples/widgets/widgets/icons/iconsizespinbox.h similarity index 100% rename from examples/widgets/widgets/icons/iconsizespinbox.h rename to tests/manual/examples/widgets/widgets/icons/iconsizespinbox.h diff --git a/examples/widgets/widgets/icons/imagedelegate.cpp b/tests/manual/examples/widgets/widgets/icons/imagedelegate.cpp similarity index 100% rename from examples/widgets/widgets/icons/imagedelegate.cpp rename to tests/manual/examples/widgets/widgets/icons/imagedelegate.cpp diff --git a/examples/widgets/widgets/icons/imagedelegate.h b/tests/manual/examples/widgets/widgets/icons/imagedelegate.h similarity index 100% rename from examples/widgets/widgets/icons/imagedelegate.h rename to tests/manual/examples/widgets/widgets/icons/imagedelegate.h diff --git a/examples/widgets/widgets/icons/images/designer.png b/tests/manual/examples/widgets/widgets/icons/images/designer.png similarity index 100% rename from examples/widgets/widgets/icons/images/designer.png rename to tests/manual/examples/widgets/widgets/icons/images/designer.png diff --git a/examples/widgets/widgets/icons/images/find_disabled.png b/tests/manual/examples/widgets/widgets/icons/images/find_disabled.png similarity index 100% rename from examples/widgets/widgets/icons/images/find_disabled.png rename to tests/manual/examples/widgets/widgets/icons/images/find_disabled.png diff --git a/examples/widgets/widgets/icons/images/find_normal.png b/tests/manual/examples/widgets/widgets/icons/images/find_normal.png similarity index 100% rename from examples/widgets/widgets/icons/images/find_normal.png rename to tests/manual/examples/widgets/widgets/icons/images/find_normal.png diff --git a/examples/widgets/widgets/icons/images/monkey_off_128x128.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_off_128x128.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_off_128x128.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_off_128x128.png diff --git a/examples/widgets/widgets/icons/images/monkey_off_16x16.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_off_16x16.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_off_16x16.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_off_16x16.png diff --git a/examples/widgets/widgets/icons/images/monkey_off_32x32.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_off_32x32.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_off_32x32.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_off_32x32.png diff --git a/examples/widgets/widgets/icons/images/monkey_off_64x64.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_off_64x64.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_off_64x64.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_off_64x64.png diff --git a/examples/widgets/widgets/icons/images/monkey_on_128x128.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_on_128x128.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_on_128x128.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_on_128x128.png diff --git a/examples/widgets/widgets/icons/images/monkey_on_16x16.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_on_16x16.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_on_16x16.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_on_16x16.png diff --git a/examples/widgets/widgets/icons/images/monkey_on_32x32.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_on_32x32.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_on_32x32.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_on_32x32.png diff --git a/examples/widgets/widgets/icons/images/monkey_on_64x64.png b/tests/manual/examples/widgets/widgets/icons/images/monkey_on_64x64.png similarity index 100% rename from examples/widgets/widgets/icons/images/monkey_on_64x64.png rename to tests/manual/examples/widgets/widgets/icons/images/monkey_on_64x64.png diff --git a/examples/widgets/widgets/icons/images/qt_extended_16x16.png b/tests/manual/examples/widgets/widgets/icons/images/qt_extended_16x16.png similarity index 100% rename from examples/widgets/widgets/icons/images/qt_extended_16x16.png rename to tests/manual/examples/widgets/widgets/icons/images/qt_extended_16x16.png diff --git a/examples/widgets/widgets/icons/images/qt_extended_32x32.png b/tests/manual/examples/widgets/widgets/icons/images/qt_extended_32x32.png similarity index 100% rename from examples/widgets/widgets/icons/images/qt_extended_32x32.png rename to tests/manual/examples/widgets/widgets/icons/images/qt_extended_32x32.png diff --git a/examples/widgets/widgets/icons/images/qt_extended_48x48.png b/tests/manual/examples/widgets/widgets/icons/images/qt_extended_48x48.png similarity index 100% rename from examples/widgets/widgets/icons/images/qt_extended_48x48.png rename to tests/manual/examples/widgets/widgets/icons/images/qt_extended_48x48.png diff --git a/examples/widgets/widgets/icons/main.cpp b/tests/manual/examples/widgets/widgets/icons/main.cpp similarity index 100% rename from examples/widgets/widgets/icons/main.cpp rename to tests/manual/examples/widgets/widgets/icons/main.cpp diff --git a/examples/widgets/widgets/icons/mainwindow.cpp b/tests/manual/examples/widgets/widgets/icons/mainwindow.cpp similarity index 100% rename from examples/widgets/widgets/icons/mainwindow.cpp rename to tests/manual/examples/widgets/widgets/icons/mainwindow.cpp diff --git a/examples/widgets/widgets/icons/mainwindow.h b/tests/manual/examples/widgets/widgets/icons/mainwindow.h similarity index 100% rename from examples/widgets/widgets/icons/mainwindow.h rename to tests/manual/examples/widgets/widgets/icons/mainwindow.h