ConfigDataTreeModel.cpp

Go to the documentation of this file.

/****************************************************************************
 **
 ** 03-Feb-2011, KAB:  This file was copied from treemodel.cpp in the
 ** Editable Tree Model Example from Nokia (copyright notice below).
 ** See http://doc.qt.nokia.com/4.6/itemviews-editabletreemodel.html.
 ** It has been modified to add local customizations.
 **
 **
 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
 ** All rights reserved.
 ** Contact: Nokia Corporation (qt-info@nokia.com)
 **
 ** This file is part of the examples of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:LGPL$
 ** Commercial Usage
 ** Licensees holding valid Qt Commercial licenses may use this file in
 ** accordance with the Qt Commercial License Agreement provided with the
 ** Software or, alternatively, in accordance with the terms contained in
 ** a written agreement between you and Nokia.
 **
 ** 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.1, 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 have questions regarding the use of this file, please contact
 ** Nokia at qt-info@nokia.com.
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/

#include <DatabaseUtils/GUI/ConfigDataTreeModel.h>
#include <DatabaseUtils/DAQConfig/DBColumnParams.h>
#include <DatabaseUtils/DAQConfig/NamedConfigUtils.h>
#include <DatabaseUtils/SimpleParameterSet.h>
#include <NovaDAQUtilities/HexUtils.h>
#include <QtGui/QtGui>
#include <boost/lexical_cast.hpp>
#include <boost/algorithm/string.hpp>
#include <iomanip>

using namespace dbutils::daqconfig;

#define NUMBER_OF_EXTRA_COLUMNS_WHEN_SELECTORS_ARE_PRESENT 2
#define NOECWSAP 2
#define NONE_SPECIFIED_STRING "none specified"

namespace dbutils {
namespace gui {

std::string _createFEBDisplayString(const std::string& febId) {
    return ("FEB " + febId);
}

std::string _createPixelDisplayString(const std::string& pixelId) {
    return ("Pixel " + pixelId);
}

QString _createFEBDisplayString(const QString& febId) {
    return _createFEBDisplayString(febId.toStdString()).c_str();
}

QString _createPixelDisplayString(const QString& pixelId) {
    return _createPixelDisplayString(pixelId.toStdString()).c_str();
}

const int32_t INVALID_ID = -123;

int32_t _getIDFromDisplayString(const std::string& displayString) {
    int32_t result = INVALID_ID;

    std::string workString = boost::trim_copy(displayString);
    size_t pos = workString.rfind(" ");
    if (pos != std::string::npos) {
        std::string idString = workString.substr(pos);
        boost::trim(idString);
        try {
            result = boost::lexical_cast<int32_t>(idString);
        }
        catch (...) {}
    }

    return result;
}

std::string _getIDFromDisplayString2(const std::string& displayString) {
    std::string workString = boost::trim_copy(displayString);
    size_t pos = workString.rfind(" ");
    if (pos != std::string::npos) {
        workString = workString.substr(pos);
        boost::trim(workString);
    }

    return workString;
}

ConfigDataTreeModel::
ConfigDataTreeModel(QObject *parent) : QAbstractItemModel(parent)
{
}

QList<QString> ConfigDataTreeModel::
allowsInsertBefore(const QModelIndex &index) const
{
    QList<QString> EMPTY_LIST;
    std::string selectorColumn;
    if (! selectorColumnNameForIndex(index, selectorColumn)) {
        return EMPTY_LIST;
    }

    if (selectorColumn == DBColumnParams::DCMNAME_COLUMN_NAME ||
        selectorColumn == DBColumnParams::HOSTNAME_COLUMN_NAME) {
        return EMPTY_LIST;
    }

    if (selectorColumn != DBColumnParams::FEBID_COLUMN_NAME &&
        selectorColumn != DBColumnParams::PIXELID_COLUMN_NAME) {
        return EMPTY_LIST;
    }

    TreeItem *selectedItem = _getItem(index);
    std::string selectedDisplayString =
        selectedItem->data(0).toString().toStdString();
    int thisChannelId = _getIDFromDisplayString(selectedDisplayString);
    if (thisChannelId == INVALID_ID) {return EMPTY_LIST;}

    QModelIndex previousIndex = this->index(index.row()-1, index.column(),
                                            index.parent());
    int previousChannelId = -1;
    if (previousIndex.isValid()) {
        TreeItem *previousItem = _getItem(previousIndex);
        std::string previousDisplayString =
            previousItem->data(0).toString().toStdString();
        previousChannelId = _getIDFromDisplayString(previousDisplayString);
    }

    QList<QString> results;
    for (int idx = previousChannelId+1; idx < thisChannelId; ++idx) {
        QString idString = QString::number(idx);
        results.push_back(idString);
    }

    return results;
}

QList<QString> ConfigDataTreeModel::
allowsInsertAfter(const QModelIndex &index) const
{
    QList<QString> EMPTY_LIST;
    std::string selectorColumn;
    if (! selectorColumnNameForIndex(index, selectorColumn)) {
        return EMPTY_LIST;
    }

    QList<QString> results;
    if (selectorColumn == DBColumnParams::DCMNAME_COLUMN_NAME ||
        selectorColumn == DBColumnParams::HOSTNAME_COLUMN_NAME) {
        QString nameString = "unknown";
        results.push_back(nameString);
        return results;
    }

    if (selectorColumn != DBColumnParams::FEBID_COLUMN_NAME &&
        selectorColumn != DBColumnParams::PIXELID_COLUMN_NAME) {
        return EMPTY_LIST;
    }

    TreeItem *selectedItem = _getItem(index);
    std::string selectedDisplayString =
        selectedItem->data(0).toString().toStdString();
    int thisChannelId = _getIDFromDisplayString(selectedDisplayString);
    if (thisChannelId == INVALID_ID) {return EMPTY_LIST;}

    QModelIndex nextIndex = this->index(index.row()+1, index.column(),
                                        index.parent());
    int nextChannelId = -1;
    if (nextIndex.isValid()) {
        TreeItem *nextItem = _getItem(nextIndex);
        std::string nextDisplayString =
            nextItem->data(0).toString().toStdString();
        nextChannelId = _getIDFromDisplayString(nextDisplayString);
    }
    else {
        if (selectorColumn == DBColumnParams::FEBID_COLUMN_NAME) {
            nextChannelId = DBColumnParams::HIGH_FEB_ID + 1;
        }
        if (selectorColumn == DBColumnParams::PIXELID_COLUMN_NAME) {
            nextChannelId = DBColumnParams::HIGH_PIXEL_ID + 1;
        }
    }

    for (int idx = thisChannelId+1; idx < nextChannelId; ++idx) {
        QString idString = QString::number(idx);
        results.push_back(idString);
    }

    return results;
}

QList<QString> ConfigDataTreeModel::
allowsChildInsert(const QModelIndex &index) const
{
    QList<QString> EMPTY_LIST;
    std::string selectorColumn;
    if (! selectorColumnNameForChild(index, selectorColumn)) {
        return EMPTY_LIST;
    }

    QList<QString> results;
    if (selectorColumn == DBColumnParams::DCMNAME_COLUMN_NAME ||
        selectorColumn == DBColumnParams::HOSTNAME_COLUMN_NAME) {
        QString nameString = "unknown";
        results.push_back(nameString);
        return results;
    }

    if (selectorColumn != DBColumnParams::FEBID_COLUMN_NAME &&
        selectorColumn != DBColumnParams::PIXELID_COLUMN_NAME) {
        return EMPTY_LIST;
    }

    int nextChannelId = -1;
    QModelIndex childIndex = this->index(0, 0, index);
    if (childIndex.isValid()) {
        TreeItem *childItem = _getItem(childIndex);
        std::string childDisplayString =
            childItem->data(0).toString().toStdString();
        nextChannelId = _getIDFromDisplayString(childDisplayString);
    }
    else {
        if (selectorColumn == DBColumnParams::FEBID_COLUMN_NAME) {
            nextChannelId = DBColumnParams::HIGH_FEB_ID + 1;
        }
        if (selectorColumn == DBColumnParams::PIXELID_COLUMN_NAME) {
            nextChannelId = DBColumnParams::HIGH_PIXEL_ID + 1;
        }
    }

    for (int idx = 0; idx < nextChannelId; ++idx) {
        QString idString = QString::number(idx);
        results.push_back(idString);
    }

    return results;
}

bool ConfigDataTreeModel::
loadData(boost::shared_ptr<daqconfig::ConfigDataTree> dataTree)
{
    _dataTree = dataTree;

    _selectorColumnNames = _dataTree->getSelectorColumnNames();
    QVector<QVariant> rootData;
    if (_selectorColumnNames.size() > 0) {
        rootData << "Component";
        rootData << "Row Type";
    }
    _dataColumnNames = _dataTree->getDataColumnNames();
    foreach (std::string dataColumn, _dataColumnNames) {
        QString tmpQString(dataColumn.c_str());
        rootData << tmpQString;
    }
    _dataColumnTypes = _dataTree->getDataColumnTypes();

    if (_rootItem.get() != 0) {
        QModelIndex dummyIndex;
        this->removeRows(0, _rootItem->childCount(), dummyIndex);
    }
    _rootItem.reset(new TreeItem(rootData));

    _setupModelData();
    return true;
}

bool ConfigDataTreeModel::hasChanges() const
{
    std::vector<TreeItem*> modifiedItems;
    this->_getModifiedItems(_rootItem.get(), modifiedItems);
    return (modifiedItems.size() > 0);
}

bool ConfigDataTreeModel::saveChanges(const int64_t& subsystemConfigId)
{
    std::vector<dbutils::SimpleParameterSet> newDataList;

    std::vector<TreeItem*> modifiedItems;
    this->_getModifiedItems(_rootItem.get(), modifiedItems);
    for (int idx = 0; idx < (int) modifiedItems.size(); ++idx) {
        TreeItem* item = modifiedItems[idx];
        dbutils::SimpleParameterSet paramSet;
        paramSet.put(NamedConfigUtils::SUBSYSCFGID_COLUMN_NAME,
                     boost::lexical_cast<std::string>(subsystemConfigId));

        int dataColumnOffset = 0;
        if (this->hasSelectors()) {

            // build up a list of the item and its ancestors
            std::vector<TreeItem*> ancestorList;
            ancestorList.push_back(item);
            TreeItem* parent = item->parent();
            while (parent != 0) {
                ancestorList.push_back(parent);
                parent = parent->parent();
            }

            // pop off the root node and the system-wide default
            if (ancestorList.size() > 0) {ancestorList.pop_back();}
            if (ancestorList.size() > 0) {ancestorList.pop_back();}

            // save the value of each selector in the ancestry
            int selectorIndex = 0;
            while (ancestorList.size() > 0) {
                TreeItem* ancestor = ancestorList.back();
                ancestorList.pop_back();

                std::string columnName = _selectorColumnNames[selectorIndex];
                std::string value = ancestor->data(0).toString().toStdString();
                if (columnName == DBColumnParams::DCMNAME_COLUMN_NAME &&
                    value == "Full System") {
                    value = _keysForDefaultValues[selectorIndex];
                }
                if (columnName == DBColumnParams::FEBID_COLUMN_NAME ||
                    columnName == DBColumnParams::PIXELID_COLUMN_NAME) {
                    value = _getIDFromDisplayString2(value);
                }

                paramSet.put(columnName, value);
                ++selectorIndex;
            }

            // fill in default values for selectors not in the ancestry
            while (selectorIndex < (int) _selectorColumnNames.size()) {
                paramSet.put(_selectorColumnNames[selectorIndex],
                             _keysForDefaultValues[selectorIndex]);
                ++selectorIndex;
            }

            dataColumnOffset = NOECWSAP;
        }

        // fill in the data values
        int numberOfEmptyValues = 0;
        for (int jdx = dataColumnOffset; jdx < item->columnCount(); ++jdx) {
            std::string value = item->data(jdx).toString().toStdString();
            boost::trim(value);
            if (value.length() == 0 || value == NONE_SPECIFIED_STRING) {
                ++numberOfEmptyValues;
            }

            if (novadaq::HexUtils::isValidHex(value)) {
                try {
                    if (_dataColumnTypes[jdx-dataColumnOffset] == "bigint") {
                        int64_t i64Value;
                        if (novadaq::HexUtils::parse(value, i64Value)) {
                            value = boost::lexical_cast<std::string>(i64Value);
                        }
                    }
                    else if (_dataColumnTypes[jdx-dataColumnOffset] == "integer" ||
                             _dataColumnTypes[jdx-dataColumnOffset] == "int") {
                        int32_t i32Value;
                        if (novadaq::HexUtils::parse(value, i32Value)) {
                            value = boost::lexical_cast<std::string>(i32Value);
                        }
                    }
                }
                catch (...) {}
            }

            paramSet.put(_dataColumnNames[jdx-dataColumnOffset], value);
        }

        // check for empty values and react accordingly
        if (numberOfEmptyValues == 0) {
            // all values were specified - that is good
            newDataList.push_back(paramSet);
        }
        else if (item->childCount() != 0 && numberOfEmptyValues ==
                 (item->columnCount() - dataColumnOffset)) {
            // "item" corresponds to a default and all values are empty
            // --> it's OK to skip this row
        }
        else {
            // otherwise, missing values are bad
            std::string msgText = "Data Validation Error: ";
            msgText.append("Values may not be left empty ");
            msgText.append("except in new default rows that have ");
            msgText.append("new exceptions underneath them. ");
            msgText.append("(");
            msgText.append(_dataTree->getTableName());
            msgText.append(" table.)");
            QMessageBox::critical(0, "ERROR: Empty Value(s)", msgText.c_str());
            return false;
        }
    }

    if (newDataList.size() > 0) {
        if (_dataTree->saveValues(newDataList)) {
            for (int idx = 0; idx < (int) modifiedItems.size(); ++idx) {
                TreeItem* item = modifiedItems[idx];
                item->markClean();
                item->markOld();
            }
            emit dataWasSaved();
            return true;
        }
        else {
            return false;
        }
    }

    return true;
}

void ConfigDataTreeModel::_getModifiedItems(TreeItem* baseItem,
                                            std::vector<TreeItem*>& list) const
{
    // add this item to the list if it has been modified
    if (baseItem->isDirty() || baseItem->isNew()) {list.push_back(baseItem);}

    // loop over children, if any
    for (int idx = 0; idx < baseItem->childCount(); ++idx) {
        TreeItem* childItem = baseItem->child(idx);
        this->_getModifiedItems(childItem, list);
    }
}

int ConfigDataTreeModel::columnCount(const QModelIndex & /* parent */) const
{
    return _rootItem->columnCount();
}

QVariant ConfigDataTreeModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid()) {return QVariant();}
    //std::cout << "Role = " << role << std::endl;

    if (role == Qt::BackgroundRole) {
        TreeItem *item = _getItem(index);
        int comparator = this->hasSelectors() ? NOECWSAP : 0;
        if ((item->isDirty() || item->isNew()) &&
            index.column() >= comparator) {
            QColor yellow("yellow");
            QBrush brush(yellow);
            return brush;
        }
    }

    if (role != Qt::DisplayRole && role != Qt::EditRole)
        return QVariant();

    TreeItem *item = _getItem(index);

    return item->data(index.column());
}

Qt::ItemFlags ConfigDataTreeModel::flags(const QModelIndex &index) const
{
    if (!index.isValid())
        return 0;

    // the goal of this section of code is to make all "data" columns
    // editable and all "selector" columns non-editable, except for 
    // DCM names in new items
    int comparator = this->hasSelectors() ? NOECWSAP : 0;
    if (index.column() >= comparator) {
        return Qt::ItemIsEditable | Qt::ItemIsEnabled | Qt::ItemIsSelectable;
    }
    else {
        std::string selectorColumnName;
        if (index.column() == 0 &&
            this->selectorColumnNameForIndex(index, selectorColumnName) &&
            (selectorColumnName == DBColumnParams::DCMNAME_COLUMN_NAME ||
             selectorColumnName == DBColumnParams::HOSTNAME_COLUMN_NAME)) {
            TreeItem *item = _getItem(index);
            if (item->isNew()) {
                return Qt::ItemIsEditable | Qt::ItemIsEnabled |
                    Qt::ItemIsSelectable;
            }
        }
        return Qt::ItemIsEnabled;
    }
}

TreeItem *ConfigDataTreeModel::_getItem(const QModelIndex &index) const
{
    if (index.isValid()) {
        TreeItem *item = static_cast<TreeItem*>(index.internalPointer());
        if (item) return item;
    }
    return _rootItem.get();
}

QVariant ConfigDataTreeModel::
headerData(int section, Qt::Orientation orientation, int role) const
{
    if (role == Qt::ToolTipRole) {
        int selectorCount = _selectorColumnNames.size();
        if (selectorCount > 0) {
            if (section == 0) {
                std::string msg("For this table, values can be specified by ");
                for (int idx = 0; idx < selectorCount; ++idx) {
                    if (idx > 0) {
                        if (selectorCount > NOECWSAP) {
                            msg.append(",");
                        }
                        msg.append(" ");
                        if (idx == selectorCount-1) {msg.append("and ");}
                    }
                    msg.append(_selectorColumnNames[idx]);
                }
                msg.append(".");
                return QVariant(QString(msg.c_str()));
            }
            else if (section == 1) {
                std::string msg("TODO: Describe Default and Individual.");
                return QVariant(QString(msg.c_str()));
            }
        }
    }

    if (orientation == Qt::Horizontal && role == Qt::DisplayRole)
        return _rootItem->data(section);

    return QVariant();
}

QModelIndex ConfigDataTreeModel::index(int row, int column, const QModelIndex &parent) const
{
    if (parent.isValid() && parent.column() != 0) {
        return QModelIndex();
    }

    TreeItem *parentItem = _getItem(parent);

    TreeItem *childItem = parentItem->child(row);
    if (childItem)
        return createIndex(row, column, childItem);
    else
        return QModelIndex();
}

bool ConfigDataTreeModel::insertRows(int position, int rows, const QModelIndex &parent)
{
    TreeItem *parentItem = _getItem(parent);

    beginInsertRows(parent, position, position + rows - 1);

    bool status = parentItem->insertChildren(position, rows, _rootItem->columnCount());
    if (status) {
        emit aChangeWasMade();
    }

    endInsertRows();

    return status;
}

QModelIndex ConfigDataTreeModel::parent(const QModelIndex &index) const
{
    if (!index.isValid()) {return QModelIndex();}

    TreeItem *childItem = _getItem(index);
    TreeItem *parentItem = childItem->parent();

    if (parentItem == _rootItem.get())
        return QModelIndex();

    return createIndex(parentItem->childNumber(), 0, parentItem);
}

bool ConfigDataTreeModel::removeRows(int position, int rows, const QModelIndex &parent)
{
    TreeItem *parentItem = _getItem(parent);

    beginRemoveRows(parent, position, position + rows - 1);

    bool status = parentItem->removeChildren(position, rows);
    if (status) {
        emit aChangeWasMade();
    }

    endRemoveRows();

    return status;
}

int ConfigDataTreeModel::rowCount(const QModelIndex &parent) const
{
    TreeItem *parentItem = _getItem(parent);

    return parentItem->childCount();
}

bool ConfigDataTreeModel::setData(const QModelIndex &index,
                                  const QVariant &value,
                                  int role)
{
    if (role != Qt::EditRole)
        return false;

    TreeItem *item = _getItem(index);
    QVariant oldValue = item->data(index.column());
    if (value == oldValue) {
        return false;
    }

    // if this item has children (i.e. it is a default value that is
    // being set), then offer to remove the children which would be
    // over-ridden by the new default
    QMessageBox::ButtonRole userChoice = QMessageBox::YesRole;
    if (item->childCount() > 0) {
        QMessageBox choiceBox;

        std::string msgText = "You have specified a new default value. ";
        msgText.append("Typically, a new default value overrides ");
        msgText.append("all existing exceptions underneath the default. ");
        msgText.append("However, you should specify the behavior that ");
        msgText.append("you want.");
        choiceBox.setText(msgText.c_str());

        msgText = "Do you want to Keep None of the exceptions underneath ";
        msgText.append("this default, Keep the New exceptions that you ");
        msgText.append("have created or edited during this editor ");
        msgText.append("session, Keep All of the exceptions under ");
        msgText.append("this default, or Cancel your change?");
        choiceBox.setInformativeText(msgText.c_str());

        QPushButton* keepNoneButton =
            choiceBox.addButton(tr("Keep None"), QMessageBox::AcceptRole);
        QPushButton* keepNewButton =
            choiceBox.addButton(tr("Keep New"), QMessageBox::ApplyRole);
        QPushButton* keepAllButton =
            choiceBox.addButton(tr("Keep All"), QMessageBox::RejectRole);
        QPushButton* cancelButton =
            choiceBox.addButton(tr("Cancel"), QMessageBox::ResetRole);
        choiceBox.setDefaultButton(keepNewButton);
        choiceBox.exec();

        if (choiceBox.clickedButton() == cancelButton) {
            return false;
        }
        else if (choiceBox.clickedButton() == keepNoneButton) {
            userChoice = QMessageBox::AcceptRole;
        }
        else if (choiceBox.clickedButton() == keepNewButton) {
            userChoice = QMessageBox::ApplyRole;
        }
        else if (choiceBox.clickedButton() == keepAllButton) {
            userChoice = QMessageBox::RejectRole;
        }
    }

    bool result = item->setData(index.column(), value);

    if (result) {
        item->markDirty();

        if (userChoice == QMessageBox::AcceptRole) {
            // remove all children
            this->removeRows(0, item->childCount(), index);
        }
        else if (userChoice == QMessageBox::ApplyRole) {
            // remove clean (and old) children
            int childIdx = 0;
            while (childIdx < item->childCount()) {
                TreeItem *childItem = item->child(childIdx);
                if (! childItem->isDirty() && ! childItem->isNew()) {
                    this->removeRows(childIdx, 1, index);
                }
                else {
                    ++childIdx;
                }
            }
        }
        else if (userChoice == QMessageBox::RejectRole) {
            // mark all children dirty (so they get re-saved to the DB)
            for (int idx = 0; idx < item->childCount(); ++idx) {
                TreeItem *childItem = item->child(idx);
                childItem->markBranchDirty();
            }
        }

        emit dataChanged(index, index);
        emit aChangeWasMade();
    }

    return result;
}

bool ConfigDataTreeModel::setHeaderData(int section, Qt::Orientation orientation,
                                          const QVariant &value, int role)
{
    if (role != Qt::EditRole || orientation != Qt::Horizontal)
        return false;

    bool result = _rootItem->setData(section, value);

    if (result)
        emit headerDataChanged(orientation, section, section);

    return result;
}

void ConfigDataTreeModel::_setupModelData()
{
    // build the initial set of selections
    _keysForDefaultValues.clear();
    DBColumnParams& colParams = DBColumnParams::getInstance();
    for (uint32_t idx = 0; idx < _selectorColumnNames.size(); ++idx) {
        std::string keyForDefault;
        if (colParams.columnKeyToGetDefaultValue(_selectorColumnNames[idx],
                                                 keyForDefault)) {
            _keysForDefaultValues.push_back(keyForDefault);
        }
        else {
            _keysForDefaultValues.push_back(ConfigDataTree::
                                            NO_DEFAULT_KEY_STRING);
        }
    }

    // populate the tree
    _populateSubTree(_rootItem.get(), -1, _keysForDefaultValues);
}

// levels: -1 = system-wide default
//          0 = specific instance of first selector
//          1 = specific instance of second selector
//          etc.
// returns the number of non-empty items that were added to the tree
int ConfigDataTreeModel::
_populateSubTree(TreeItem* parent, int thisLevel,
                 std::vector<std::string> selectionList)
{
    int numberOfNonEmptyItems = 0;
    int selectorCount = selectionList.size();

    // add the requested item
    int newChildIndex = parent->childCount();
    parent->insertChildren(newChildIndex, 1, parent->columnCount());
    TreeItem* thisItem = parent->child(newChildIndex);
    int itemIndex = 0;
    if (selectorCount > 0) {
        if (thisLevel == -1) {
            thisItem->setData(itemIndex++, QVariant("Full System"));
            thisItem->setData(itemIndex++, QVariant("Default"));
        }
        else {
            std::string text = selectionList[thisLevel];
            if (_selectorColumnNames[thisLevel] ==
                DBColumnParams::FEBID_COLUMN_NAME) {
                text = _createFEBDisplayString(text);
            }
            else if (_selectorColumnNames[thisLevel] ==
                     DBColumnParams::PIXELID_COLUMN_NAME) {
                text = _createPixelDisplayString(text);
            }
            thisItem->setData(itemIndex++, QVariant(text.c_str()));

            if (thisLevel < (selectorCount-1)) {
                thisItem->setData(itemIndex++, QVariant("Default"));
            }
            else {
                thisItem->setData(itemIndex++, QVariant("Individual"));
            }
        }
    }
    for (uint32_t dcIdx = 0; dcIdx < _dataColumnNames.size(); ++dcIdx) {
        std::string dataColumnName = _dataColumnNames[dcIdx];
        std::string valueString = "unknown";
        bool status = false;
        switch (selectorCount) {
        case 0:
            status = _dataTree->getTrueValue(dataColumnName, valueString);
            break;
        case 1:
            status = _dataTree->getTrueValueFor1Key(selectionList[0],
                                                    dataColumnName,
                                                    valueString);
            break;
        case 2:
            status = _dataTree->getTrueValueFor2Keys(selectionList[0],
                                                     selectionList[1],
                                                     dataColumnName,
                                                     valueString);
            break;
        case 3:
            status = _dataTree->getTrueValueFor3Keys(selectionList[0],
                                                     selectionList[1],
                                                     selectionList[2],
                                                     dataColumnName,
                                                     valueString);
            break;
        default:
            std::cout << "Error: unexpected number of selectors ("
                      << selectorCount << ")" << std::endl;
        }
        if (status) {
            if (dataColumnName == "mask") {
                try {
                    if (_dataColumnTypes[dcIdx] == "bigint") {
                        valueString =
                            novadaq::HexUtils::format(valueString, 16);
                    }
                    else {
                        valueString =
                            novadaq::HexUtils::format(valueString, 8);
                    }
                }
                catch (...) {}
            }
            thisItem->setData(itemIndex++, QVariant(valueString.c_str()));
            ++numberOfNonEmptyItems;
        }
        else if (thisLevel < (selectorCount-1)) {
            thisItem->setData(itemIndex++, QVariant(NONE_SPECIFIED_STRING));
        }
    }

    // get the distinct selection values at the next level
    int nextLevel = thisLevel + 1;
    if (nextLevel >= 0 && nextLevel < selectorCount &&
        nextLevel < (int) _selectorColumnNames.size()) {
        std::vector<std::string> distinctSelectorValues = _dataTree->
            getDistinctSelectorColumnValues(_selectorColumnNames[nextLevel]);
        for (uint32_t idx = 0; idx < distinctSelectorValues.size(); ++idx) {
            if (distinctSelectorValues[idx] ==
                _keysForDefaultValues[nextLevel]) {
                continue;
            }
            selectionList[nextLevel] = distinctSelectorValues[idx];
            numberOfNonEmptyItems += _populateSubTree(thisItem, nextLevel,
                                                      selectionList);
        }
    }

    // if this item is empty, and all of its children are empty,
    // then remove this entry in the tree.  (We shouldn't have added
    // it in the first place, but we had to try in case there were
    // non-empty children.)
    if (numberOfNonEmptyItems == 0) {
        parent->removeChildren(newChildIndex, 1);
    }

    return numberOfNonEmptyItems;
}

bool ConfigDataTreeModel::
addChildRow(QModelIndex parentIndex, QString selectorColumnText,
            int position)
{
    TreeItem *parentItem = _getItem(parentIndex);

    // rebuild parentIndex, if needed, to get the column number set to zero
    // (without this, the TreeView doesn't show the added row correctly)
    if (parentIndex.column() != 0) {
        parentIndex = this->index(parentIndex.row(), 0,
                                  this->parent(parentIndex));
    }

    beginInsertRows(parentIndex, position, position);

    bool status = parentItem->insertChildren(position, 1,
                                             _rootItem->columnCount());
    if (status) {
        QModelIndex childIndex = this->index(position, 0, parentIndex);
        if (childIndex.isValid()) {
            TreeItem* childItem = _getItem(childIndex);
            int selectorLevel = _getParentCount(childIndex) - 1;

            if (selectorLevel >= 0 &&
                selectorLevel < (int) _selectorColumnNames.size()) {
                if (_selectorColumnNames[selectorLevel] ==
                    DBColumnParams::FEBID_COLUMN_NAME) {
                    selectorColumnText =
                        _createFEBDisplayString(selectorColumnText);
                }
                else if (_selectorColumnNames[selectorLevel] ==
                         DBColumnParams::PIXELID_COLUMN_NAME) {
                    selectorColumnText =
                        _createPixelDisplayString(selectorColumnText);
                }
            }
            childItem->setData(0, selectorColumnText);

            if (selectorLevel+1 == (int) _selectorColumnNames.size()) {
                childItem->setData(1, QVariant("Individual"));
            }
            else {
                childItem->setData(1, QVariant("Default"));
            }
            for (int idx = NOECWSAP; idx < parentItem->columnCount(); ++idx) {
                childItem->setData(idx, parentItem->data(idx));
            }
            childItem->markNew();
        }

        emit aChangeWasMade();
    }

    endInsertRows();

    return status;
}

bool ConfigDataTreeModel::
addRowBefore(const QModelIndex &baseIndex, QString selectorColumnText)
{
    TreeItem *baseItem = _getItem(baseIndex);
    QModelIndex parentIndex = this->parent(baseIndex);
    int baseOffset = baseItem->childNumber();
    return this->addChildRow(parentIndex, selectorColumnText, baseOffset);
}

bool ConfigDataTreeModel::
addRowAfter(const QModelIndex &baseIndex, QString selectorColumnText)
{
    TreeItem *baseItem = _getItem(baseIndex);
    QModelIndex parentIndex = this->parent(baseIndex);
    int baseOffset = baseItem->childNumber();
    return this->addChildRow(parentIndex, selectorColumnText, baseOffset+1);
}

bool ConfigDataTreeModel::
selectorColumnNameForIndex(const QModelIndex& index,
                           std::string& selectorColumnName) const
{
    return _getSelectorColumnName(index, selectorColumnName, -1);
}

bool ConfigDataTreeModel::
selectorColumnNameForChild(const QModelIndex& index,
                           std::string& selectorColumnName) const
{
    return _getSelectorColumnName(index, selectorColumnName, 0);
}

bool ConfigDataTreeModel::
dataColumnNameForIndex(const QModelIndex& index,
                       std::string& dataColumnName) const
{
    if (! index.isValid()) {return false;}

    int column = index.column();
    int fixedColumnCount = this->hasSelectors() ? NOECWSAP : 0;
    if (column < fixedColumnCount) {return false;}

    int idx = column - fixedColumnCount;
    if (idx >= 0 && idx < (int) _dataColumnNames.size()) {
        dataColumnName = _dataColumnNames[idx];
        return true;
    }

    return false;
}

bool ConfigDataTreeModel::
dataColumnTypeForIndex(const QModelIndex& index,
                       std::string& dataColumnType) const
{
    if (! index.isValid()) {return false;}

    int column = index.column();
    int fixedColumnCount = this->hasSelectors() ? NOECWSAP : 0;
    if (column < fixedColumnCount) {return false;}

    int idx = column - fixedColumnCount;
    if (idx >= 0 && idx < (int) _dataColumnTypes.size()) {
        dataColumnType = _dataColumnTypes[idx];
        return true;
    }

    return false;
}

bool ConfigDataTreeModel::
_getSelectorColumnName(const QModelIndex& index,
                       std::string& selectorColumnName,
                       int startingOffset) const
{
    if (! this->hasSelectors()) {return false;}

    int column = index.column();
    int fixedColumnCount = this->hasSelectors() ? NOECWSAP : 0;
    if (column >= fixedColumnCount) {return false;}

    int parentCount = _getParentCount(index);
    if (parentCount < 0) {return false;}
    int selectorIndex = parentCount + startingOffset;
    if (selectorIndex < 0 ||
        selectorIndex >= (int) _selectorColumnNames.size()) {
        return false;
    }
    selectorColumnName = _selectorColumnNames[selectorIndex];
    return true;
}

int ConfigDataTreeModel::_getParentCount(const QModelIndex& index) const
{
    if (!index.isValid()) {return -1;}

    int parentCount = 0;
    QModelIndex parent = this->parent(index);
    while (parent.isValid()) {
        ++parentCount;
        parent = this->parent(parent);
    }
    return parentCount;
}

} // end of namespace gui
} // end of namespace dbutils