SelectionWidget Class Reference

Widget used to pick items from one list and add them to another. More...

#include <selectionwidget.h>

Public Slots
virtual void	sAdd ()
	Moves selected items from the "available" tree to the "selected" tree.
virtual void	sAddAll ()
	Moves all items from the "available" tree to the "selected" tree.
virtual void	sCancel ()
	Emits cancelClicked() signal.
virtual int	sCommitChanges ()
	Calls functions to execute the appropriate INSERT and DELETE queries.
virtual void	sMove (XTreeWidgetItem *pXtitem, bool pAdd)
	Moves an item from one tree to another based on the value of pAdd.
virtual void	sRemove ()
	Moves selected items from the "selected" tree to the "available" tree.
virtual void	sRemoveAll ()
	Moves all items from the "selected" tree to the "available" tree.
virtual void	sSelect ()
	Emits selectClicked() signal.

Signals
void	addAllClickedAfter ()
void	addAllClickedBefore ()
void	addClickedAfter ()
void	addClickedBefore ()
void	cancelClicked ()
void	itemAdded (int id)
void	itemRemoved (int id)
void	removeAllClickedAfter ()
void	removeAllClickedBefore ()
void	removeClickedAfter ()
void	removeClickedBefore ()
void	selectClicked ()

Public Member Functions
	SelectionWidget (QWidget *parent=0, Qt::WindowFlags fl=QFlags< Qt::WindowType >())
	~SelectionWidget ()
Q_INVOKABLE ParameterList	getAddConstraints () const
Q_INVOKABLE QList< XTreeWidgetItem * > *	getAdded ()
	Returns the _added list.
Q_INVOKABLE XTreeWidget *	getAvail () const
	Returns the "available" tree.
Q_INVOKABLE ParameterList	getEqualityColumns () const
Q_INVOKABLE QString	getModifyTableName () const
Q_INVOKABLE bool	getRemoveByAltId () const
Q_INVOKABLE QString	getRemoveByIdTableColName () const
Q_INVOKABLE QList< XTreeWidgetItem * > *	getRemoved ()
	Returns the _removed list.
Q_INVOKABLE XTreeWidget *	getSel () const
	Returns the "selected" tree.
Q_INVOKABLE void	hideCancel ()
	Hides the cancel button.
Q_INVOKABLE void	hideSelect ()
	Hides the select button.
Q_INVOKABLE bool	isParentInTrans () const
void	retranslateUi (QWidget *SelectionWidget)
void	retranslateUi (QWidget *SelectionWidget)
Q_INVOKABLE void	setAddConstraints (ParameterList constraints)
Q_INVOKABLE void	setEqualityColumns (ParameterList columns)
Q_INVOKABLE void	setModifyTableName (QString name)
Q_INVOKABLE void	setParentInTrans (bool parInTrans=true)
Q_INVOKABLE void	setRemoveByAltId (bool useAlt=true)
Q_INVOKABLE void	setRemoveByIdTableColName (QString name)
void	setupUi (QWidget *SelectionWidget)
void	setupUi (QWidget *SelectionWidget)
Q_INVOKABLE void	showCancel ()
	Shows the cancel button.
Q_INVOKABLE void	showSelect ()
	Shows the select button.

Public Attributes
QPushButton *	_add
QPushButton *	_addAll
XTreeWidget *	_avail
QLabel *	_availLit
QPushButton *	_cancel
QPushButton *	_remove
QPushButton *	_removeAll
XTreeWidget *	_sel
QPushButton *	_select
QLabel *	_selLit
QGridLayout *	gridLayout
QSpacerItem *	verticalSpacer
QSpacerItem *	verticalSpacer_2
QSpacerItem *	verticalSpacer_3

Protected Slots
void	sFilterDuplicates ()
	Removes items from the "available" tree that are already in the "selected" tree.

Protected Member Functions
int	execAddQuery (XSqlQuery &outQry)
	Builds and executes an INSERT query for each item in the _added list.
int	execRemoveQuery (XSqlQuery &outQry)
	Builds and executes a DELETE query to remove all items in the _removed list.
bool	isSameItem (XTreeWidgetItem *pXtitem1, XTreeWidgetItem *pXtitem2) const
	Determines if 2 items are equal based on configured equality criteria.

Protected Attributes
ParameterList	_addConstraints
	Name value pairs indicating column names and values to insert.
QList< XTreeWidgetItem * >	_added
	List of items added to "available" tree since loading.
ParameterList	_equalityColumns
	Name Value pairs indicating pairs of columns to be compared for equality.
QString	_modifyTableName
	Name of table where items will be added or removed.
bool	_parentInTrans
	When true, insert and delete statements will not be wrapped in a transaction block.
bool	_removeByAltId
	When true, delete statements use the item's altId instead of id.
QString	_removeByIdTableColName
	Column name used as a key by the delete statement to remove records.
QList< XTreeWidgetItem * >	_removed
	List of items removed from the "selected" tree since loading.

Detailed Description

Widget used to pick items from one list and add them to another.

The selection widget incorporates 2 XTreeWidgets, one as a source (or available) and one as a destination (or selected). Each tree will be populated from a different query but the data should be compatible with the fields on both trees otherwise moving items back and forth doesn't make sense.

The widget was designed to be adaptable and thus requires some configuration first. The following must be done before the widget will function properly:

• Tree Setup:
  The internal trees are exposed via the getAvail() and getSel() functions. Once you have pointers to the trees, they must be configured as is usual for XTreeWidgets.

• Equality Columns:
  Since each of the trees may present different attributes of the underlying data, there needs to be a way to determine equality between items on different trees. A list of name-value pairs must be passed to the setEqualityColumns() function. Each pair will contain the XTreeWidget column names to be considered equivalent. When the trees first load, any items in the "available" tree that are already present in the "selected" tree (based on the equality columns) will be filtered out of the available list.

• Select and Cancel Buttons:
  Select and cancel buttons can be shown or hidden depending on your use case with the hideCancel(), showCancel() and hideSelect(), showSelect(). These buttons don't do anything other than emit a clicked signal when clicked. They are shown by default.

The widget can either be automatic or handled manually depending on the situation.

• Manual:
  With the above setup in place, the widget will function properly and track selections. Various signals are emitted by the widget when buttons are clicked and before/after items are moved in either direction. At any point you can retrieve a list of changes from the getAdded() and getRemoved() functions. The getAdded function will return a list of items that are currently in the "selected" tree that were not there when the widget first loaded. getRemoved() returns items that were in the "selected" tree when the widget first loaded and are no longer there. Between the accessor functions and the signals, you can process the changes in whatever way suits your needs.

• Automatic:
  The widget can automatically build and execute SQL queries to add and remove items from the underlying table. In order to do that, the following must be configured:

  • Set Modification Table:
    The table where new items will be added (and from which removed items will be deleted) must be passed to setModifyTableName(). Ideally this will be the table from which the "selected" tree was populated though this is not necessary. The only requirement is that calling id() or altId() on the XTreeWidget item will return an id that is sufficient to identify a single record in the table passed to setModifyTableName().

  • Set Insert Criteria:
    In order to insert records into an arbitrary table, a list of column names and values to insert must be provided. A parameter list must be passed to setAddConstraints(). This list will contain one entry for each column to be populated and must, at a minimum, contain entries for each required column in the table passed to setModifyTableName(). In each entry, the parameter name must be the table column name. The parameter value can either be a literal value, the name of a column in the "selected" XTreeWidget, or the strings "id" or "altId". If the parameter value is the string "id", then the id of the row will be inserted, and if the parameter value is the string "altId", then the altId of the row will be inserted. If the parameter value matches a column name other than "id" or "altId", the contents of that column will be inserted. Otherwise the parameter value will be inserted directly. Do not name any columns to be inserted "id" or "altId" in the XTreeWidget because the id or altId of the row will be inserted instead.

  • Set Delete Criteria:
    In order to delete records from an arbitrary table, a column name must be passed to setRemoveByIdTableColName() to be used as a key to identify a specific record. The widget will create a delete query which will remove records if the value returned by the XTreeWidgetItem's id() or altId() function matches the value in the column provided. id() is used by default and can be changed by calling the setRemoveByAltId() function.

Todo

• add a way to add a new item directly to the "selected" tree.
• replace queries with metasql

Constructor & Destructor Documentation

SelectionWidget()

SelectionWidget::SelectionWidget	(	QWidget *	parent = 0,
		Qt::WindowFlags	fl = QFlags<Qt::WindowType>() )

~SelectionWidget()

SelectionWidget::~SelectionWidget

(

)

Member Function Documentation

addAllClickedAfter

void SelectionWidget::addAllClickedAfter ( )

signal

addAllClickedBefore

void SelectionWidget::addAllClickedBefore ( )

signal

addClickedAfter

void SelectionWidget::addClickedAfter ( )

signal

addClickedBefore

void SelectionWidget::addClickedBefore ( )

signal

cancelClicked

void SelectionWidget::cancelClicked ( )

signal

execAddQuery()

int SelectionWidget::execAddQuery ( XSqlQuery & outQry )

protected

Builds and executes an INSERT query for each item in the _added list.

This function builds INSERT statements using _modifyTableName and _addConstraints in order to create flexible queries for any table needed. Values to be inserted are bound to "parameterN" for N = 0 to addConstraints.count() - 1. Returns the query executed to allow for error reporting outside of a transaction block.
The entries in _addConstraints will determine how the query is built. For each entry in _addConstraints, the parameter name specifies the column where the value will be inserted. the parameter value will either be a column name in the "available" tree or a literal value. If the parameter value matches a column name, the value in that column will be inserted, otherwise the parameter value itself will be inserted directly.

Parameters

[out]

outQry

returns the last executed query before either detecting an error or completing.

execRemoveQuery()

int SelectionWidget::execRemoveQuery ( XSqlQuery & outQry )

protected

Builds and executes a DELETE query to remove all items in the _removed list.

This function builds a DELETE statement using _modifyTableName and _removeByIdTableColName in order to create flexible queries for any table needed. Ids to be deleted are bound to "parameterN" for N = 0 to _removed.count() - 1 Returns the last query executed to allow for error reporting outside of a transaction block.
The delete statement will use the value returned by calling id() on each item in the _removed list to identify which records to remove. If the _removeByAltId flag is set to true, the statement will instead use the result of calling altId().

Parameters

[out]

outQry

returns the executed query.

getAddConstraints()

Q_INVOKABLE ParameterList SelectionWidget::getAddConstraints ( ) const

inline

getAdded()

Q_INVOKABLE QList< XTreeWidgetItem * > * SelectionWidget::getAdded ( )

inline

Returns the _added list.

getAvail()

Q_INVOKABLE XTreeWidget * SelectionWidget::getAvail ( ) const

inline

Returns the "available" tree.

getEqualityColumns()

Q_INVOKABLE ParameterList SelectionWidget::getEqualityColumns ( ) const

inline

getModifyTableName()

Q_INVOKABLE QString SelectionWidget::getModifyTableName ( ) const

inline

getRemoveByAltId()

Q_INVOKABLE bool SelectionWidget::getRemoveByAltId ( ) const

inline

getRemoveByIdTableColName()

Q_INVOKABLE QString SelectionWidget::getRemoveByIdTableColName ( ) const

inline

getRemoved()

Q_INVOKABLE QList< XTreeWidgetItem * > * SelectionWidget::getRemoved ( )

inline

Returns the _removed list.

getSel()

Q_INVOKABLE XTreeWidget * SelectionWidget::getSel ( ) const

inline

Returns the "selected" tree.

hideCancel()

void SelectionWidget::hideCancel

(

)

Hides the cancel button.

hideSelect()

void SelectionWidget::hideSelect

(

)

Hides the select button.

isParentInTrans()

Q_INVOKABLE bool SelectionWidget::isParentInTrans ( ) const

inline

isSameItem()

bool SelectionWidget::isSameItem ( XTreeWidgetItem * pXtitem1, XTreeWidgetItem * pXtitem2 ) const

protected

Determines if 2 items are equal based on configured equality criteria.

This function checks the _equalityColumns list. For each name value pair entry, it checks the contents of the corresponding columns in each tree item and returns true only if they are the same for all entries in the list

itemAdded

void SelectionWidget::itemAdded ( int id )

signal

itemRemoved

void SelectionWidget::itemRemoved ( int id )

signal

removeAllClickedAfter

void SelectionWidget::removeAllClickedAfter ( )

signal

removeAllClickedBefore

void SelectionWidget::removeAllClickedBefore ( )

signal

removeClickedAfter

void SelectionWidget::removeClickedAfter ( )

signal

removeClickedBefore

void SelectionWidget::removeClickedBefore ( )

signal

retranslateUi() [1/2]

void Ui_SelectionWidget::retranslateUi ( QWidget * SelectionWidget )

inlineinherited

retranslateUi() [2/2]

void Ui_SelectionWidget::retranslateUi ( QWidget * SelectionWidget )

inlineinherited

sAdd

void SelectionWidget::sAdd ( )

virtualslot

Moves selected items from the "available" tree to the "selected" tree.

Emits addClickedBefore() and addClickedAfter() before and after moving an item respectively. Emits itemAdded() after each item is moved

sAddAll

void SelectionWidget::sAddAll ( )

virtualslot

Moves all items from the "available" tree to the "selected" tree.

Emits addAllClickedBefore() and addAllClickedAfter() before and after moving an item respectively. Emits itemAdded() after each item is moved.

sCancel

void SelectionWidget::sCancel ( )

virtualslot

Emits cancelClicked() signal.

sCommitChanges

int SelectionWidget::sCommitChanges ( )

virtualslot

Calls functions to execute the appropriate INSERT and DELETE queries.

This function will call execAddQuery() and execRemoveQuery() then clear the _added and _removed lists. If the _parentInTrans flag is false, the calls to these functions will be wrapped in a transaction block to ensure atomicity. It is left to the caller to ensure that the _parentInTrans flag is set appropriately.

selectClicked

void SelectionWidget::selectClicked ( )

signal

setAddConstraints()

Q_INVOKABLE void SelectionWidget::setAddConstraints ( ParameterList constraints )

inline

setEqualityColumns()

Q_INVOKABLE void SelectionWidget::setEqualityColumns ( ParameterList columns )

inline

setModifyTableName()

Q_INVOKABLE void SelectionWidget::setModifyTableName ( QString name )

inline

setParentInTrans()

Q_INVOKABLE void SelectionWidget::setParentInTrans ( bool parInTrans = true )

inline

setRemoveByAltId()

Q_INVOKABLE void SelectionWidget::setRemoveByAltId ( bool useAlt = true )

inline

setRemoveByIdTableColName()

Q_INVOKABLE void SelectionWidget::setRemoveByIdTableColName ( QString name )

inline

setupUi() [1/2]

void Ui_SelectionWidget::setupUi ( QWidget * SelectionWidget )

inlineinherited

setupUi() [2/2]

void Ui_SelectionWidget::setupUi ( QWidget * SelectionWidget )

inlineinherited

sFilterDuplicates

void SelectionWidget::sFilterDuplicates ( )

protectedslot

Removes items from the "available" tree that are already in the "selected" tree.

This function iterates through the items in the "available" tree and for each, uses the isSameItem() function to find any items in the "selected" tree that match. If it finds any, the item is removed from the "available" tree.

showCancel()

void SelectionWidget::showCancel

(

)

Shows the cancel button.

showSelect()

void SelectionWidget::showSelect

(

)

Shows the select button.

sMove

void SelectionWidget::sMove ( XTreeWidgetItem * pXtitem, bool pAdd )

virtualslot

Moves an item from one tree to another based on the value of pAdd.

Based on the value of pAdd, one tree is designated as a source, the other as a destination. Likewise _added and _removed are designated as either a check list or an append list. pXtitem is removed from the source tree. If pXtitem is NOT in the check list, it means this is a new change we must track. pXtitem is then added to the append list. If pXtitem IS present in the check list, it means the item was previously moved, and this move is merely undoing that action. Therefore, pXtitem is only removed from the check list and not added to the append list. Finally, pXtitem is added to the destination tree. The key idea here is that depending on pAdd, the append and check lists will switch places. So the list we add an item to in one direction, will be the list we check against when going in the opposite direction.

Parameters

pXtitem	XTreeWidgetItem to be moved from one tree to another.
pAdd	True when moving from "available" tree to "selected" tree, false otherwise.

sRemove

void SelectionWidget::sRemove ( )

virtualslot

Moves selected items from the "selected" tree to the "available" tree.

Emits removeClickedBefore() and removeClickedAfter() before and after moving an item respectively. Emits itemRemoved() after each item is moved.

sRemoveAll

void SelectionWidget::sRemoveAll ( )

virtualslot

Moves all items from the "selected" tree to the "available" tree.

Emits removeAllClickedBefore() and removeAllClickedAfter() before and after moving an item respectively. Emits itemRemoved() after each item is moved.

sSelect

void SelectionWidget::sSelect ( )

virtualslot

Emits selectClicked() signal.

Member Data Documentation

_add

QPushButton * Ui_SelectionWidget::_add

inherited

_addAll

QPushButton * Ui_SelectionWidget::_addAll

inherited

_addConstraints

ParameterList SelectionWidget::_addConstraints

protected

Name value pairs indicating column names and values to insert.

_added

QList<XTreeWidgetItem*> SelectionWidget::_added

protected

List of items added to "available" tree since loading.

_avail

XTreeWidget * Ui_SelectionWidget::_avail

inherited

_availLit

QLabel * Ui_SelectionWidget::_availLit

inherited

_cancel

QPushButton * Ui_SelectionWidget::_cancel

inherited

_equalityColumns

ParameterList SelectionWidget::_equalityColumns

protected

Name Value pairs indicating pairs of columns to be compared for equality.

_modifyTableName

QString SelectionWidget::_modifyTableName

protected

Name of table where items will be added or removed.

_parentInTrans

bool SelectionWidget::_parentInTrans

protected

When true, insert and delete statements will not be wrapped in a transaction block.

_remove

QPushButton * Ui_SelectionWidget::_remove

inherited

_removeAll

QPushButton * Ui_SelectionWidget::_removeAll

inherited

_removeByAltId

bool SelectionWidget::_removeByAltId

protected

When true, delete statements use the item's altId instead of id.

_removeByIdTableColName

QString SelectionWidget::_removeByIdTableColName

protected

Column name used as a key by the delete statement to remove records.

_removed

QList<XTreeWidgetItem*> SelectionWidget::_removed

protected

List of items removed from the "selected" tree since loading.

_sel

XTreeWidget * Ui_SelectionWidget::_sel

inherited

_select

QPushButton * Ui_SelectionWidget::_select

inherited

_selLit

QLabel * Ui_SelectionWidget::_selLit

inherited

gridLayout

QGridLayout * Ui_SelectionWidget::gridLayout

inherited

verticalSpacer

QSpacerItem * Ui_SelectionWidget::verticalSpacer

inherited

verticalSpacer_2

QSpacerItem * Ui_SelectionWidget::verticalSpacer_2

inherited

verticalSpacer_3

QSpacerItem * Ui_SelectionWidget::verticalSpacer_3

inherited

---

The documentation for this class was generated from the following files:

• selectionwidget.h
• selectionwidget.cpp