Doc: Improve the QCombobox Documentation
The purpose of this commit is to improve the QCombobox documentation. The following updates were made: - The Combobox image was udated with a better quality image. - The brief was updated to make it more understandable. - The detailed description was updated with subsection titles. - Full stops were added to the sentences that were missing them. Fixes: QTBUG-117748 Pick-to: 6.5 6.6 Change-Id: I417a720299ac0eb2be3f080f2fc0f76a27242423 Reviewed-by: Paul Wicking <paul.wicking@qt.io>bb10
Safiyyah Moosa
parent
5e158ee177
commit
48c6f7250a
Binary file not shown.
|
After Width: | Height: | Size: 6.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
|
|
@ -951,39 +951,34 @@ QComboBox::QComboBox(QComboBoxPrivate &dd, QWidget *parent)
|
|||
|
||||
/*!
|
||||
\class QComboBox
|
||||
\brief The QComboBox widget is a combined button and popup list.
|
||||
\brief The QComboBox widget combines a button with a dropdown list.
|
||||
|
||||
\ingroup basicwidgets
|
||||
\inmodule QtWidgets
|
||||
|
||||
\image windows-combobox.png
|
||||
\table
|
||||
\row
|
||||
\li \inlineimage collapsed_combobox.png
|
||||
\caption Collapsed QCombobox
|
||||
\li
|
||||
\inlineimage expanded_combobox.png
|
||||
\caption Expanded QCombobox
|
||||
\endtable
|
||||
|
||||
A QComboBox provides a means of presenting a list of options to the user
|
||||
in a way that takes up the minimum amount of screen space.
|
||||
\section1 Display Features
|
||||
A QComboBox is a compact way to present a list of options to the user.
|
||||
|
||||
A combobox is a selection widget that displays the current item,
|
||||
and can pop up a list of selectable items. A combobox may be editable,
|
||||
allowing the user to modify each item in the list.
|
||||
A combobox is a selection widget that shows the current item,
|
||||
and pops up a list of selectable items when clicked. Comboboxes can
|
||||
contain pixmaps as well as strings if the insertItem() and setItemText()
|
||||
functions are suitably overloaded.
|
||||
|
||||
Comboboxes can contain pixmaps as well as strings; the
|
||||
insertItem() and setItemText() functions are suitably overloaded.
|
||||
For editable comboboxes, the function clearEditText() is provided,
|
||||
\section1 Editing Features
|
||||
A combobox may be editable, allowing the user to modify each item in the
|
||||
list. For editable comboboxes, the function clearEditText() is provided,
|
||||
to clear the displayed string without changing the combobox's
|
||||
contents.
|
||||
|
||||
There are three signals emitted if the current item of a combobox
|
||||
changes, currentIndexChanged(), currentTextChanged() and activated().
|
||||
currentIndexChanged() and currentTextChanged() are always emitted
|
||||
regardless if the change
|
||||
was done programmatically or by user interaction, while
|
||||
activated() is only emitted when the change is caused by user
|
||||
interaction. The highlighted() signal is emitted when the user
|
||||
highlights an item in the combobox popup list. All three signals
|
||||
exist in two versions, one with a QString argument and one with an
|
||||
\c int argument. If the user selects or highlights a pixmap, only
|
||||
the \c int signals are emitted. Whenever the text of an editable
|
||||
combobox is changed the editTextChanged() signal is emitted.
|
||||
|
||||
When the user enters a new string in an editable combobox, the
|
||||
widget may or may not insert it, and it can insert it in several
|
||||
locations. The default policy is \l InsertAtBottom but you can change
|
||||
|
|
@ -1006,17 +1001,33 @@ QComboBox::QComboBox(QComboBoxPrivate &dd, QWidget *parent)
|
|||
setCompleter() and whether or not the user can add duplicates
|
||||
is set with setDuplicatesEnabled().
|
||||
|
||||
QComboBox uses the \l{Model/View Programming}{model/view
|
||||
framework} for its popup list and to store its items. By default
|
||||
a QStandardItemModel stores the items and a QListView subclass
|
||||
displays the popuplist. You can access the model and view directly
|
||||
(with model() and view()), but QComboBox also provides functions
|
||||
to set and get item data (e.g., setItemData() and itemText()). You
|
||||
can also set a new model and view (with setModel() and setView()).
|
||||
For the text and icon in the combobox label, the data in the model
|
||||
that has the Qt::DisplayRole and Qt::DecorationRole is used. Note
|
||||
that you cannot alter the \l{QAbstractItemView::}{SelectionMode}
|
||||
of the view(), e.g., by using
|
||||
\section1 Signals
|
||||
There are three signals emitted if the current item of a combobox
|
||||
changes: currentIndexChanged(), currentTextChanged(), and activated().
|
||||
currentIndexChanged() and currentTextChanged() are always emitted
|
||||
regardless if the change
|
||||
was done programmatically or by user interaction, while
|
||||
activated() is only emitted when the change is caused by user
|
||||
interaction. The highlighted() signal is emitted when the user
|
||||
highlights an item in the combobox popup list. All three signals
|
||||
exist in two versions, one with a QString argument and one with an
|
||||
\c int argument. If the user selects or highlights a pixmap, only
|
||||
the \c int signals are emitted. Whenever the text of an editable
|
||||
combobox is changed, the editTextChanged() signal is emitted.
|
||||
|
||||
\section1 Model/View Framework
|
||||
|
||||
QComboBox uses the \l{Model/View Programming}{model/view framework} for its
|
||||
popup list and to store its items. By default a QStandardItemModel stores
|
||||
the items and a QListView subclass displays the popuplist. You can access
|
||||
the model and view directly (with model() and view()), but QComboBox also
|
||||
provides functions to set and get item data, for example, setItemData() and
|
||||
itemText(). You can also set a new model and view (with setModel()
|
||||
and setView()). For the text and icon in the combobox label, the data in
|
||||
the model that has the Qt::DisplayRole and Qt::DecorationRole is used.
|
||||
|
||||
\note You cannot alter the \l{QAbstractItemView::}{SelectionMode}
|
||||
of the view(), for example, by using
|
||||
\l{QAbstractItemView::}{setSelectionMode()}.
|
||||
|
||||
\sa QLineEdit, QSpinBox, QRadioButton, QButtonGroup
|
||||
|
|
@ -1463,7 +1474,7 @@ void QComboBox::setMaxVisibleItems(int maxItems)
|
|||
|
||||
/*!
|
||||
\property QComboBox::count
|
||||
\brief the number of items in the combobox
|
||||
\brief the number of items in the combobox.
|
||||
|
||||
By default, for an empty combo box, this property has a value of 0.
|
||||
*/
|
||||
|
|
@ -1475,7 +1486,7 @@ int QComboBox::count() const
|
|||
|
||||
/*!
|
||||
\property QComboBox::maxCount
|
||||
\brief the maximum number of items allowed in the combobox
|
||||
\brief the maximum number of items allowed in the combobox.
|
||||
|
||||
\note If you set the maximum number to be less then the current
|
||||
amount of items in the combobox, the extra items will be
|
||||
|
|
@ -1508,7 +1519,7 @@ int QComboBox::maxCount() const
|
|||
|
||||
/*!
|
||||
\property QComboBox::duplicatesEnabled
|
||||
\brief whether the user can enter duplicate items into the combobox
|
||||
\brief whether the user can enter duplicate items into the combobox.
|
||||
|
||||
Note that it is always possible to programmatically insert duplicate items into the
|
||||
combobox.
|
||||
|
|
@ -1554,7 +1565,7 @@ int QComboBox::findData(const QVariant &data, int role, Qt::MatchFlags flags) co
|
|||
/*!
|
||||
\property QComboBox::insertPolicy
|
||||
\brief the policy used to determine where user-inserted items should
|
||||
appear in the combobox
|
||||
appear in the combobox.
|
||||
|
||||
The default value is \l InsertAtBottom, indicating that new items will appear
|
||||
at the bottom of the list of items.
|
||||
|
|
@ -1577,7 +1588,7 @@ void QComboBox::setInsertPolicy(InsertPolicy policy)
|
|||
/*!
|
||||
\property QComboBox::sizeAdjustPolicy
|
||||
\brief the policy describing how the size of the combobox changes
|
||||
when the content changes
|
||||
when the content changes.
|
||||
|
||||
The default value is \l AdjustToContentsOnFirstShow.
|
||||
|
||||
|
|
@ -1668,7 +1679,7 @@ void QComboBox::setIconSize(const QSize &size)
|
|||
|
||||
/*!
|
||||
\property QComboBox::placeholderText
|
||||
\brief Sets a \a placeholderText text shown when no valid index is set
|
||||
\brief Sets a \a placeholderText text shown when no valid index is set.
|
||||
|
||||
The \a placeholderText will be shown when an invalid index is set. The
|
||||
text is not accessible in the dropdown list. When this function is called
|
||||
|
|
@ -1707,7 +1718,7 @@ QString QComboBox::placeholderText() const
|
|||
|
||||
/*!
|
||||
\property QComboBox::editable
|
||||
\brief whether the combo box can be edited by the user
|
||||
\brief whether the combo box can be edited by the user.
|
||||
|
||||
By default, this property is \c false. The effect of editing depends
|
||||
on the insert policy.
|
||||
|
|
@ -3503,7 +3514,7 @@ QVariant QComboBox::inputMethodQuery(Qt::InputMethodQuery query, const QVariant
|
|||
|
||||
/*!
|
||||
\property QComboBox::frame
|
||||
\brief whether the combo box draws itself with a frame
|
||||
\brief whether the combo box draws itself with a frame.
|
||||
|
||||
|
||||
If enabled (the default) the combo box draws itself inside a
|
||||
|
|
|
|||
Loading…
Reference in New Issue