bncs_listview_extended

Description

This is a single-selection listview control with suitable wrapper for using with the BNCS Visual Designer.

This control is contained within bncs_listview_extended.dll.

Cells

The extended BNCS listview allows PNGs to be displayed along with allowing the setting of foreground and background colours per cell.

This can be set at design-time with the following embedded formatting, or else use the "methods" described in the commands table below.

The Syntax used for doing this is as follows.

@pixmap=pictureName~text=textToDisplay~fg=foreColour~bg=backgroundColour@

It is a tilde(~) separated key value pair list, which must start and end with a @.

e.g.

@pixmap=myImage~text=myText~fg=#008000~bg=#ffffff@

The values that can be set this way are (any may be ommitted)

Value | Notes
pixmap= | The image to display, this will be a png stored in "panels/images/" Path and ".png" extension are implicit and should not be included
text= | The text to display this will be displayed to the right of any image displayed
fg= | The foreground colour of the text
bg= | The background colour of the text

Tags

Tags are runtime parameters that can be added to a row.

It can contain any information you want, it will not be shown in the row.

Settings

You can pass any of the following settings to this control in the format:

<parameter>=<value>

Default values (those when a new listview is created or when a reset command issued) are shown in bold.

Note that the row and column indexes are from 0.

Text Gets

Parameter | Return | Notes
selected | Row Text | Returns the text of the currently selected item or empty string if nothing is currently selected
selectedindex | Row Index, Starting at 0 | will return the value of the currently selected item or –1 if there is no item selected
count | Count of rows | Will return the number of the items in the listview
row.<row> | coloumn1;column2;column3; | Will return the text of the specified row (semicolon separated values of the cells) or empty string if the row doesn’t exist; e.g. row.3
tag.<row> | Row Tag or empty | Will return the tag of the specified row or empty string if the row doesn’t exist; e.g. tag.3
column.<value> | row1;row2;row3;row4; | Will return the text of the specified column (semicolon separated values of the cells excluding the column header) or empty string if the column doesn’t exist; e.g. column.2
columns | header1;header2;header3; | Will return the semicolon separated list of the column header texts
columnWidth.<value> | Column Width as number | Will return the width of the specified column or -1 if it is not specified(means set automatically based on the cell contents); e.g. columnWidth.0
columnAlign.<value> | Qt::Top | Qt::Left
cell.<row>.<column> | Cell Text | Will return the text of the specified cell or empty string if the column or row doesn’t exist; e.g. return=cell.0.3
cellPixmapTag.<tag>.<column> | icon_test | Will return the pixmap name of the specified cell or empty string if the column or row doesn’t exist; e.g. return=cellPixmapTag.tagName.3
cellPixmap.<row>.<column> | icon_test | Will return the pixmap name of the specified cell or empty string if the column or row doesn’t exist; e.g. return=cellPixmap.0.3
cellFGTag.<tag>.<column> | #000000 | Will return the Foreground colour of the specified cell or empty string if the column or tag doesn’t exist; e.g. return=cellFG.0.3
cellFG.<row>.<column> | #000000 | Will return the Foreground colour of the specified cell or empty string if the column or row doesn’t exist; e.g. return=cellFG.0.3
cellBGTag.<tag>.<column> | #ffffff | Will return the Background of the specified cell or empty string if the column or tag doesn’t exist; e.g. return=cellBG.0.3
cellBG.<row>.<column> | #ffffff | Will return the Background of the specified cell or empty string if the column or row doesn’t exist; e.g. return=cellBG.0.3
cellTextTag.<tag>.<column> | Only Displayed cell text | Will return the text of the specified cell or empty string if the column or tag doesn’t exist; e.g. return= cellTEXT.0.3
cellText.<row>.<column> | Only Displayed cell text | Will return the text of the specified cell or empty string if the column or row doesn’t exist; e.g. return= cellTEXT.0.3
colour.text | Default Foreground Colour | Will return the text colour or empty string if the default colour is used, any cell that has an overridden colour can be gotten separately
colour.background | Default Background Colour | Will return the text colour or empty string if the default colour is used, any cell that has an overridden colour can be gotten separately
notify.selection | selected,changed,none | Will return the state of the selection change notification
notify.cell_selection | selected,changed,none | Will return the state of the cell selection change notification
notify.tag_selection | selected,changed,none | Will return the state of the tag selection change notification
font.face | font | Will return the current font face set or empty string if the default is used
font.size | font size | Will return the current font size or empty string if the default is used
stylesheet | stylesheet | Will return the style sheet of the control or empty string if it is not specified
tags.<delimiter> | tags | Will return a complete list of (non-null) tags for this control delimited by commas or the optional delimiter specified

Commands

Parameter | Value | Notes
reset |  | Used to reset all the parameters of this control back to their default state
hideHeader | true, false | Hides/shows the listview header
enableSorting | true , false | Enables sorting so the user can sort columns by clicking on the column headers
enableColumnResize | true , false | Enables column resize so the user can modify the column width manually
enableColumnMoving | true , false | Sets whether the header sections can be moved
colour.text colour.background | Any valid Qt colour or nothing. | Set colour of the specified parameter. e.g. the following two examples are equivalent: colour.led=red colour.led=#ff0000 Setting the value to zero length string (see example) sets the colour back to the default colour specified in the skin. This is the default for these settings. e.g. colour.background= colour.text=
notify.selection | true | Enables notification on the specified events
font.face | any valid font face | The current font face. If no font face is specified (the default) then the standard font face as defined in the skin is used.
font.size | e.g.: 10 –2 +3 | The current font size to use. If the value is signed than it is an offset from the default skin font size. Otherwise it is the absolute font size.
font.style | Any combination of bold, italic, underline, overline, strikeout | The current font style.
stylesheet |  | Stylesheet entry to use for this listview (the stylesheet entry is an external list of any combination of the above settings)
columnsWidth | Semicolon separated values | Semicolon separated list of column widths. -1 means automatic value based on the cell texts. e.g.: “columnsWidth=25;-1;-1;50”
columnWidth.<column> |  | Sets the width of a specified column. -1 means automatic value based on the cell texts. e.g.: “columnWidth.4=50”
columnsAlign | Semicolon separated values | Semicolon separated list of column alignments. If this parameter is not specified than then the alignment of the stylesheet will be used or ‘left’ if no alignment is defined in the stylesheet. The alignment values are defined below e.g.: “columnsAlign=17;34” sets the first column alignment to top left, and the second column alignment to bottom right.
columnAlign.<column> |  | Sets the alignment for a specified column. e.g.: “columnAlign.2=17”
addColumn |  | Adds new column to the listview with the specified header text. e.g.: “addColumn=New column”
renameColumn.<column> |  | Renames header text for a specified column. e.g.: “renameColumn.0=Modified header”
removeColumn |  | Removes the specified column. e.g.: “removeColumn=2”
add | Semicolon separated values Col1;Col2;Col3;#TAG= | Adds new item to the end of the listview. Sorting is switched off before adding. This function also allow you to add the tag. This should be a value after the last column starting with #TAG= The texts are separated by semicolon. e.g. “add=ListView;control;is;nice!”
removeRow |  | Removes the specified row. e.g.: “removeRow=2”
removeTag |  | Removes the row with the specified tag. e.g.: “removeTag=2”
cell.<row>.<column> |  | Sets text for a specified cell. e.g.: “cell.0.0=Top left cell”
cellPixmapTag.<tag>.<column> | icon_help | Sets Pixmap for a specified cell. Looks for images in the panel/images folder. Ending in png. e.g.: “cellPixmap.tag.0=icon_help”
cellPixmap.<row>.<column> | icon_help | Sets Pixmap for a specified cell. Looks for images in the panel/images folder. Ending in png. e.g.: “cellPixmap.0.0=icon_help”
cellFGTag.<tag>.<column> | #000000 | Sets Foreground colour for a specified cell. e.g.: “cellFG.tag.0=#000000”
cellFG.<row>.<column> | #000000 | Sets Foreground colour for a specified cell. e.g.: “cellFG.0.0=Top left cell”
rowFG.<row> | #000000 | Set the foreground colour (text) for the whole of the specified row e.g. "rowFG.1=red"
columnFG.<row> |  | Set the foreground colour (text) for the whole of the specified column e.g. "columnFG.1=red"
cellBGTag.<tag>.<column> | #ffffff | Sets Background colour for a specified cell. e.g.: “cellBG.tag.0=#ffffff”
cellBG.<row>.<column> | #ffffff | Sets Background colour for a specified cell. e.g.: “cellBG.0.0=#ffffff”
columnBG.<column> | Set the background colour for the whole of the specified column e.g. "columnBG.1=red"
rowBG.<row> |  | Set the background colour for the whole of the specified row e.g. "rowBG.1=red"
cellTextTag.<tag>.<column> | Text | Sets text for a specified cell. This option should be used if the over overrides (Pixmap, FG, BG) are being used. e.g.: “cellText.tag.0=Top left cell”
cellText.<tag>.<column> | Text | Sets text for a specified cell. This option should be used if the over overrides (Pixmap, FG, BG) are being used. e.g.: “cellText.tag.0=Cell and Column with Tag name”
tagRow.<tagName> tagRow.<tagName>.add | tagRow.tagName=Top Row C1;Top Row C2;#TAG=Hello | Sets text for a row with this tag It will only change the row if it exists unless "add" is appended to the command as shown This function also allow you to modify the tag. This should be a value after the last column starting with #TAG=
row.<row> | row.0=Top Row C1;Top Row C2;#TAG=Hello | Set text for a row It will only change the row if it exists This function also allow you to add the tag. This should be a value after the last column starting with #TAG=
rowTag.<row> |  | Set tag for a row e.g: “tag.0=Top Row C1;Top Row C2” It will only change the row if it exists
selectRow |  | Selects a specified row. e.g.: “selectRow=2”
selectTag |  | Selects a specified tag e.g “selectTag=id12”
clearSelection |  | Clears listview selection.
moveColumn | <from>;<to> | Moves a specified column to a new position. e.g.: “moveColumn=0;3”
moveRow | <from>;<to> | Moves a specified row to a new position. e.g.: “moveRow=2;1”
sort | <column> Or <column>;<ascending> | Sorts the specified column. The default sorting is ascending. e.g.: “sort=2” “sort=2;false”
clear |  | Clears the contents of the listview.

Alignment Values

Horizontal Alignment:

Left = 1
Right = 2,
HCenter = 4

Vertical Alignment:

Top = 16
Bottom = 32,
VCenter = 64

You can add together values for vertical and horizontal - e.g. bottom right would be 34 (32+2))

Notifications

Notifications are also in the format:

<parameter>=<value>
Parameter | Value | Notes
selection. | text value of current selection; the text of the cells are separated by ‘;’ | The notification can be set to notify on Selection, on Selection Changed.
cell_selection..=value | Text value of the currently selected cell. | The notification can be set to notify on Selection, on Selection Changed.
tag_selection.=tag | The Tag held by the row | The notification can be set to notify on Selection, on Selection Changed.

Version Control

Version | Date | Author | Comments
1.0.0.1 |  |  | ?
1.0.0.2 |  |  | ?
1.0.3.0 |  |  | crash fix on selecting no item in the edit-time listview
1.0.4.0 |  |  | enableSorting now set on design-time dialog from the value used
1.0.5.0 |  |  | column alignment now actually sets the alignment on the control
1.0.6.0 |  |  | now supports return value for tags or tags.
1.0.7.0 |  |  | merely setting the sort column isn't enough to force a sort if it's already set to that column - so force a sort if the column turns out to be the same one as we already had
1.0.8.0 |  |  | overrides the text() call that's used to set the width of the cell so that it uses the text not the text plus formatting chars
1.0.9.0 |  |  | now has rowFG and rowBG to set entire row colours, also column equivalent with columnFG and columnBG
1.0.10.0 |  |  | tagRow now has option to force add of non-existent entry if we didn't find it
1.0.11.0 |  |  | new "removeTag" command now will remove a row by tag name
1.0.12.0 |  |  | fix to default value for notify selection
 | 27/02/2017 | David Yates | Conversion to markdown minor revisions
1.0.13.0 | 09/04/2018 | David Yates | Fix to tagRow..add so that it adds to the end of the list not the beginning
1.0.14.0 | 23/04/2018 | David Yates | Fix to tagRow..add so that it sets the tag as it adds
Build: master 3798 615debad Atos © 2018