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

#include <selectionwidget.h>

Inheritance diagram for SelectionWidget:

Public Slots
virtual void	sAdd ()
	Moves selected items from the "available" tree to the "selected" tree. More...

virtual void	sAddAll ()
	Moves all items from the "available" tree to the "selected" tree. More...

virtual void	sCancel ()
	Emits cancelClicked() signal. More...

virtual int	sCommitChanges ()
	Calls functions to execute the appropriate INSERT and DELETE queries. More...

virtual void	sRemove ()
	Moves selected items from the "selected" tree to the "available" tree. More...

virtual void	sRemoveAll ()
	Moves all items from the "selected" tree to the "available" tree. More...

virtual void	sSelect ()
	Emits selectClicked() signal. More...

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=0)

	~SelectionWidget ()

Q_INVOKABLE ParameterList	getAddConstraints () const

Q_INVOKABLE QList< XTreeWidgetItem * >	getAdded () const
	Returns the _added list. More...

Q_INVOKABLE XTreeWidget *	getAvail () const
	Returns the "available" tree. More...

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 () const
	Returns the _removed list. More...

Q_INVOKABLE XTreeWidget *	getSel () const
	Returns the "selected" tree. More...

Q_INVOKABLE void	hideCancel ()
	Hides the cancel button. More...

Q_INVOKABLE void	hideSelect ()
	Hides the select button. More...

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. More...

Q_INVOKABLE void	showSelect ()
	Shows the select button. More...

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. More...

Protected Member Functions
int	execAddQuery (XSqlQuery &outQry)
	Builds and executes an INSERT query for each item in the _added list. More...

int	execRemoveQuery (XSqlQuery &outQry)
	Builds and executes a DELETE query to remove all items in the _removed list. More...

bool	isSameItem (XTreeWidgetItem pXtitem1, XTreeWidgetItem pXtitem2) const
	Determines if 2 items are equal based on configured equality criteria. More...

void	move (XTreeWidgetItem *pXtitem, bool pAdd)
	Moves an item from one tree to another based on the value of pAdd. More...

Protected Attributes
ParameterList	_addConstraints
	Name value pairs indicating column names and values to insert. More...

QList< XTreeWidgetItem * >	_added
	List of items added to "available" tree since loading. More...

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

QString	_modifyTableName
	Name of table where items will be added or removed. More...

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

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

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

QList< XTreeWidgetItem * >	_removed
	List of items removed from the "selected" tree since loading. More...

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, or the name of a column in the "selected" XTreeWidget. If the parameter value matches a column name, the contents of that column will be inserted, otherwise the parameter value will be inserted directly.
- 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 = `0`
	)

◆ ~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 ( ) const

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 ( ) const

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

◆ move()

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

protected

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.

◆ 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.

◆ 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

Public Slots

Signals

Public Member Functions

Public Attributes

Protected Slots

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SelectionWidget()

◆ ~SelectionWidget()

Member Function Documentation

◆ addAllClickedAfter

◆ addAllClickedBefore

◆ addClickedAfter

◆ addClickedBefore

◆ cancelClicked

◆ execAddQuery()

◆ execRemoveQuery()

◆ getAddConstraints()

◆ getAdded()

◆ getAvail()

◆ getEqualityColumns()

◆ getModifyTableName()

◆ getRemoveByAltId()

◆ getRemoveByIdTableColName()

◆ getRemoved()

◆ getSel()

◆ hideCancel()

◆ hideSelect()

◆ isParentInTrans()

◆ isSameItem()

◆ itemAdded

◆ itemRemoved

◆ move()

◆ removeAllClickedAfter

◆ removeAllClickedBefore

◆ removeClickedAfter

◆ removeClickedBefore

◆ retranslateUi() [1/2]

◆ retranslateUi() [2/2]

◆ sAdd

◆ sAddAll

◆ sCancel

◆ sCommitChanges

◆ selectClicked

◆ setAddConstraints()

◆ setEqualityColumns()

◆ setModifyTableName()

◆ setParentInTrans()

◆ setRemoveByAltId()

◆ setRemoveByIdTableColName()

◆ setupUi() [1/2]

◆ setupUi() [2/2]

◆ sFilterDuplicates

◆ showCancel()

◆ showSelect()

◆ sRemove

◆ sRemoveAll

◆ sSelect

Member Data Documentation

◆ _add

◆ _addAll

◆ _addConstraints

◆ _added

◆ _avail

◆ _availLit

◆ _cancel

◆ _equalityColumns

◆ _modifyTableName

◆ _parentInTrans

◆ _remove

◆ _removeAll

◆ _removeByAltId

◆ _removeByIdTableColName

◆ _removed

◆ _sel

◆ _select

◆ _selLit

◆ gridLayout