CopperSpice API: Widget Classes

List Widgets

A one dimensional list where one item will be displayed on each row, is typically displayed using a QListWidget. Each row is represented by a QListWidgetItem.

Item in a list can display a text label and an icon. The colors and font used to render the text can be changed to provide a customized appearance for items. Tooltips, status tips, and "What's This?" help can also be configured as shown on newItem3.

QListWidget *listWidget = new QListWidget(this);
 
//
QListWidgetItem *newItem1 = new QListWidgetItem;
newItem1->setText(tr("Sycamore"));
listWidget->addItem(newItem1);
 
//
QListWidgetItem *newItem2 = new QListWidgetItem;
newItem2->setText(tr("Chestnut"));
listWidget->addItem(newItem2);
 
//
QListWidgetItem *newItem3 = new QListWidgetItem;
newItem3->setText(tr("Mahogany"));
 
newItem3->setToolTip(tr("Tool Tip"));
newItem3->setStatusTip(tr("Status Hint"));
newItem3->setWhatsThis(tr("Some Help Message"));
 
listWidget->addItem(newItem3);

By default, items in a list are presented in the order of their creation. Lists of items can be sorted according to the criteria given in Qt::SortOrder to produce a list of items that is sorted in forward or reverse alphabetical order.

listWidget->sortItems(Qt::AscendingOrder);

listWidget->sortItems(Qt::DescendingOrder);

Tree Widgets

Trees or hierarchical lists of items are displayed using a QTreeWidget and QTreeWidgetItem classes. Each item in the tree widget can have child items of its own and can display multiple columns of information. Before items can be added to the tree widget the number of columns must be set. The easiest way to set up the labels for each column is to supply a string list.

QTreeWidget *treeWidget = new QTreeWidget(this);
treeWidget->setColumnCount(2);
 
QStringList headers;
headers << tr("Subject") << tr("Default");
 
treeWidget->setHeaderLabels(headers);

Top level items in the tree widget are constructed with the tree widget as their parent widget. They can be inserted in an arbitrary order or you can ensure they are listed in a particular order by specifying the previous item when constructing each item.

QTreeWidgetItem *cities = new QTreeWidgetItem(treeWidget);
cities->setText(0, tr("Cities"));
 
QTreeWidgetItem *osloItem = new QTreeWidgetItem(cities);
osloItem->setText(0, tr("San Francisco"));
osloItem->setText(1, tr("Yes"));
 
QTreeWidgetItem *planets = new QTreeWidgetItem(treeWidget, cities);

Tree widgets deal with top-level items slightly differently than other items within the tree. Items can be removed from the top level of the tree by calling takeTopLevelItem(), whereas items from lower levels are removed by calling takeChild(). Items are inserted in the top level of the tree by calling insertTopLevelItem() and lower level items are inserted using insertChild().

The following example shows how to remove the current item in the tree widget regardless of its location.

QTreeWidgetItem *parent = currentItem->parent();
int index;
 
if (parent) {
   index = parent->indexOfChild(treeWidget->currentItem());
   delete parent->takeChild(index);
 
} else {
   index = treeWidget->indexOfTopLevelItem(treeWidget->currentItem());
   delete treeWidget->takeTopLevelItem(index);
}

Inserting an item in the tree widget can be accomplished using the following code.

QTreeWidgetItem *parent = currentItem->parent();
QTreeWidgetItem *newItem;
 
if (parent) {
   newItem = new QTreeWidgetItem(parent, treeWidget->currentItem());
} else {
   newItem = new QTreeWidgetItem(treeWidget, treeWidget->currentItem());
}

Table Widgets

A table widget contains a two dimensional array of elements, similar to a spreadsheet application. QTableWidget is used to construct a table and then items are added using QTableWidgetItem. Tables can be created with a specified number of rows and columns or these can be added to an empty table as required.

Items are constructed and then added to the table widget at the required location. The following example will create a table with 8 rows and 3 columns. The rows and columns in the table are numbered starting with zero.

Horizontal and vertical headers can be added to the table by constructing items and then passing them to setHorizontalHeaderItem() or setVerticalHeaderItem().

QTableWidget *tableWidget;
tableWidget = new QTableWidget(8, 3, this);
 
QTableWidgetItem *newItem = new QTableWidgetItem(tr("%1").formatArg(pow(row, column+1)));
tableWidget->setItem(row, column, newItem);
 
QTableWidgetItem *valuesHeaderItem = new QTableWidgetItem(tr("Values"));
tableWidget->setHorizontalHeaderItem(0, valuesHeaderItem);

Hidden Items

It can be useful to hide items in a QListWidget, QTreeWidget, or a QTableWidget. Items can be hidden and then later shown again using setItemHidden(). Simply pass the item and pass true or false to inticate if the item should be displayed or hidden. To query if an item is visible use the method isItemHidden().

Selections

If an item is selectable then the user can highlight the entry. This does not guarantee the item can be modified. There are settings to adjust if a single item can be selected or multiple items at one time.

There is a property in each of the three widget classes called selectionMode. The value of this property defines how many items the user can select and whether the selection must be a continuous range of items. The value of this property is configured using the enum, QAbstractItemView::SelectionMode.

Single Item: Property is set to QAbstractItemView::SelectionMode::SingleSelection

The user can only choose a single item from the widget. The current item and the selected item are the same.

Multiple items: Property is set to QAbstractItemView::SelectionMode::MultiSelection

In this mode users can toggle the selection state of any item in the widget without changing the existing selection.

Extended: Property is set to QAbstractItemView::SelectionMode::ExtendedSelection

Users can select a continuous range of items in the widget using either the mouse or the keyboard. Complex selections involving multiple items that are not adjacent to other selected items in the widget, can also be selected if modifier keys such as CTRL are used. If the user selects an item without using a modifier key the existing selection is cleared.

A list of the selected items can be retrieved by calling selectedItems(). In the following example, the sum of all numeric values within a list of selected items is calculated.

QList<QTableWidgetItem *> selected = tableWidget->selectedItems();
QTableWidgetItem *item;
 
int number   = 0;
double total = 0;
 
for (item : selected) {
   bool ok;
   double value = item->text().toDouble(&ok);
 
   if (ok && ! item->text().isEmpty()) {
      total += value;
      ++number;
   }
}
 
return total;

Searching

It is often useful to find or search for items within a view widget. The first parameter to findItems() is the text to search for and the second parameter is a set of flags defined in the enum Qt::MatchFlags. This enum contains options to specify if the match should be exact, case sensitive, wild cards, and several others.

The following example shows how to find a string in the QTreeWidget.

QTreeWidgetItem *item;
QList<QTreeWidgetItem *> found = treeWidget->findItems("some search text", Qt::MatchWildcard);
 
for (item : found) {
   treeWidget->setItemSelected(item, true);
 
   // show the item->text(0) for each item
}

Using Widget Classes

The items in a QListWidget, QTableWidget, and QTreeWidget are constructed with slightly different defaults.

For example, a QListWidgetItem or a QTreeWidgetItem is initially constructed as enabled, checkable, or selectable and can be used as the source of a drag and drop operation. A QTableWidgetItem is constructed with the same options plus the ability to use as the target of a drag and drop operation.

The standard items are configured to support drag and drop capabilities. However you may need to enable properties in the view to enable support for drag and drop operations.

To enable item dragging set the dragEnabled property to true in the view
To allow dropping items on the view, call viewport()->setAcceptDrops(true)
To show the user where the item currently being dragged will be placed, set the property showDropIndicator on the view
To allow the user to move drag and drop items within a view, set the dragDropMode.

In the following example, all forms of drag and drop in a list widget are enabled.

QListWidget *listWidget = new QListWidget(this);
 
listWidget->setSelectionMode(QAbstractItemView::SingleSelection);
 
listWidget->setDragEnabled(true);
listWidget->viewport()->setAcceptDrops(true);
listWidget->setDropIndicatorShown(true);
listWidget->setDragDropMode(QAbstractItemView::InternalMove);

The result is a list widget which allows the items to be copied around within the view and lets the user drag items between views containing the same type of data. In both situations the items are copied rather than moved.