NAME
BQTableview - BRTT Qt graphics class for displaying data in a table
SYNOPSIS
-lbqplot -lbanner -lbrttutil $(STOCKLIB)
#include "BQ.h"
DESCRIPTION
BQTableview objects are used to display data in tables
using the
QTableView class.
This class inherits the BQConfigure class which is itself a subclass of the BUConfigure class
with extensions to process Qt colors and fonts. The configure methods are implemented
in the BUConfigure parent (see BUConfigure(3)).
This class behaves mainly like the QTableView class with a few exceptions.
-
Sorting by clicking on the headers has three states instead of two. The first click produces
ascending sort order. The second click produces descending sort order. The third click produces
original sort order. Custom sorting can be done at the application level individually on each
column.
-
There is a concept of record number, referring to the the row to data relationship as originally
produced without sorts. These record numbers can be displayed automatically in the table and are not
ambiguated by sorts. As well, sorts can be done on the record numbers.
-
There is internal support for making display changes as the mouse hovers above table cells without
button clicks or drags.
-
The Qt QAbstractTableModel table view model is implemented internally. A callback mechanism,
through sub-classing, is defined to provide a simple API for providing data and display characteristics,
such as color and alignment, to the table cells.
INHERITS FROM
QTableView,
BQConfigure
CONSTRUCTOR
BQTableview(QWidget *parent);
Where "parent" is the QWidget parent for this object.
METHODS INHERITED FROM BQConfigure
-
void configure (Pf *params);
An Antelope parameter file object pointer that contains the BQTableview object
parameters. The parameters are described below.
-
void configure (...);
A variable argument list composed entirely of character string key-value pairs with
a single NULL terminating argument. This is an alternate method for specifying
the BQTableview object parameters. The parameters are described below.
BQTableview METHODS
-
void setDimensions (int nrows, int ncolumns)
This will specify the numbers of rows and columns in the table. Calling this will cause
all of the table cells to be re-rendered. This will also cause column widths
to be reset according to the various configure parameters defined below.
If nrows is < 0, then the number
of rows will not be changed. If ncolumns is < 0, then the number
of columns will not be changed.
-
void setDimensions ()
Calling this will cause all of the table cells to be re-rendered without changing
the numbers of rows or columns. This will also cause column widths
to be reset according to the various configure parameters defined below.
-
void reset ()
Calling this will cause all of the table cells to be re-rendered without changing
the numbers of rows or columns. This is a slightly overloaded version
of QTableView::reset().
-
void totalSize (int &width, int &height)
This will return the total table size in pixels. This is typically used in sizing
the parent window to properly contain the table.
-
void setRecordTab (QList<long> record_tab)
This will set the internal conversion between sorted and unsorted record numbers.
this should not be specified when default Qt string-based sorting is done. This only
needs to be specified when the sorting is done by the application program, in which
case the Qt default sorting is disabled.
-
int getRecord (int row)
This will return the unsorted row number using the internal record tab, as set
by setRecordTab.
-
virtual QVariant callback (QStringList request)
This should be implemented in a sub-class and provides the mechanism for
specifying table cell data and display characteristics. This method will be called
with a request list consisting of request type and other parameters, such
as row and column numbers. The return is a QVariant value with the
requested information. Generally, invalid QVariant return values will cause
the action to be ignored. request[0] is always a request type string as follows.
-
headerdata
For this request request[1] will contain the column number as a string. The
return value should be a string with the column header name.
-
data
For this request request[1] will contain the row and column numbers as a
single string with the values white space separated. The
return value should be a string with the table cell display value.
-
foreground
For this request request[1] will contain the row and column numbers as a
single string with the values white space separated. The
return value should be a QColor value specifying the cell text color.
-
background
For this request request[1] will contain the row and column numbers as a
single string with the values white space separated. The
return value should be a QColor value specifying the cell background color.
-
alignment
For this request request[1] will contain the row and column numbers as a
single string with the values white space separated. The return
value should be a Qt Qt::AlignmentFlag enum value for specifying the
cell display text alignment.
-
sort
For this request request[1] will contain the column number as a string and
a string flag in request[2] indicating if the sort should be in ascending
order, for string 0, or descending order, for string 1. This request
indicates that the horizontal header cell has been clicked to produce a sort on
that column. A column value of -1 means that the sorting is in
original order. If the application program does not want to implement sorting itself,
then this can be considered as a notification requiring no application actions, in which
case the return value should be an invalid QVariant.
If the application program wants to implement sorting itself, Then this can be
used to trigger the application sorting, in which case the return value
should be the string disable_sort to notify the object to disable the
default Qt sorting for that column. If an application wants to perform its own
custom sorting in this manner, then it should also call the setSortTab
method defined above to establish a sorted to unsorted transformation for displaying
disambiguated record numbers.
-
hover
For this request request[1] will contain the row and column numbers as a
single string with the values white space separated. The return value is ignored.
This is meant to be a notification for application programs that the mouse is hovering
above the table cell.
-
accentuated
For this request request[1] will contain the row and column numbers as a
single string with the values white space separated. The return value should
be an integer 1, to indicate that the cell should be accentuated, or 0,
to indicate the cell should not be accentuated. There are separate colors and backgrounds
for accentuated cells as defined in the configuration parameters. Note that only one cell
at a time can be accentuated. If a new cell is accentuated, then if there is already
another accentuated cell, it will be de-accentuated. The accentuation cell state will
be ignored if the return value is an invalid QVariant.
-
selection_changed
For this request request[1] will contain the record number as a string. Only
one record at a time can be selected. The return value is ignored. Note that the
record number of the original data order is returned as opposed to the sorted row
number.
OBJECT CONFIGURATION PARAMETERS
-
default_cell_width default_cell_width
This specifies the default cell width in pixels. If this is "-1", then the
cell widths are either determined from the column_widths configuration
parameter or the widths are set to fit the cell contents.
This defaults to "-1".
-
column_widths column_widths_pf_string
This specifies the cell widths in pixels for each column. This should be specified as
a parameter file string with a Tbl with the name column_widths. Each entry in the Tbl
corresponds to a column in the table view. If the entry value can be parsed as an integer,
then that value is used as the width of the column in pixels. Otherwise, the entry is
treated as a string and its display font metrics are used to determine a string width which
is used to set the column width. Columns with width of -1 pixels are set to fill
the contents of the cells. If there are fewer entries than columns, then the remaining
columns use the default_cell_width value.
-
show_record_numbers show_record_numbers
Specifies whether or not the record numbers should be displayed. Specified by a Boolean.
When record numbers are shown, they are automatically displayed as integers in the
left-most first column, corresponding to the original data row numbers. These record
numbers stay consistent through sorts. Also, when record numbers are shown, the column
numbers stay consistent with the original data column numbers without the record numbers
displayed.
This defaults to "no".
-
font font
Specifies a font to use for displaying the cell text strings.
Fonts are specified as "<family>[,<size>[,<weight>[,<italic?>]]]",
where <family> is a font family name, <size> is a font size in integer pixels, <weight>
is an integer weight or can be one of Light, Normal, DemiBold, Bold or Black,
and <italic?> is a boolean (yes or no) to indicate if the font is in italics. System defaults
for <size>, <weight> and <italic?> are used if not specified. System default
for <family> is used as the system default fixed font.
-
font_size font_size
This is a convenience option that can be used to set the cell text font size without specifying
the entire font.
-
font_header font_header
Specifies a font to use for displaying the cell horizontal header text strings. This font is
also used to display record numbers.
-
default_hover_interaction default_hover_interaction
Specifies whether or not mouse hovers should automatically cause accentuated cell display.
Specified by a Boolean.
This defaults to "no".
-
color_hover color_key
Specifies a color to use for displaying cell text when accentuated.
This defaults to "black".
-
color_record_numbers_background color_record_numbers_background
Specifies a color to use for displaying record number cell backgrounds;
This defaults to "lightgray".
EXAMPLE
Following is a simple c++ example.
#include "BQ.h"
class MyTableview : public BQTableview {
public:
MyTableview (QWidget *parent) : BQTableview (parent) {}
QVariant callback (QStringList request);
};
QVariant MyTableview::callback (QStringList request) {
if (request[0] == "headerdata") {
if (request[2] == "horizontal") {
int col = request[1].toInt();
return QVariant("col "+request[1]);;
}
return QVariant();
}
if (request[0] == "data") {
return QVariant (request[1]);
}
if (request[0] == "foreground") {
auto l = request[1].split(" ");
int row = l[0].toInt();
int col = l[1].toInt();
switch ((row+col)%3) {
default:
case 0:
return QVariant();
case 1:
return QVariant(QColor("blue"));
case 2:
return QVariant(QColor("red"));
}
}
if (request[0] == "background") {
auto l = request[1].split(" ");
int row = l[0].toInt();
int col = l[1].toInt();
switch ((row+col)%3) {
default:
case 0:
return QVariant();
case 1:
return QVariant(QColor("pink"));
case 2:
return QVariant(QColor("lightblue"));
}
}
if (request[0] == "selection_changed") {
int row = request[1].toInt();
printf ("selection %d\n", row);
}
return QVariant();
}
int
main (int argc, char **argv)
{
if (argc != 3) {
fprintf (stderr, "usage: bqplot_test_tableview nrows ncols\n");
exit (1);
}
int nrows = atoi(argv[1]);
int ncols = atoi(argv[2]);
QApplication qapp(argc, argv);
qapp.setApplicationName("bqplot_test_tableview");
QWidget *widget = new QWidget();
widget->setWindowTitle("bqplot_test_tableview");
widget->show();
widget->resize (800, 400);
QGridLayout *layout = new QGridLayout (widget);
layout->setSpacing (0);
layout->setContentsMargins (0, 0, 0, 0);
widget->setLayout (layout);
MyTableview *tv = new MyTableview(widget);
tv->configure ("color_hover", "magenta", "font", "courier,18,Bold",
"font_header", "arial,14,Normal",
"default_hover_interaction", "yes",
"show_record_numbers", "yes",
NULL);
tv->setDimensions (nrows, ncols);
layout->addWidget (tv, 0, 0, 1, 1);
qapp.exec();
exit (0);
}
SEE ALSO
bqplot(3),
BQConfigure(3)
AUTHOR
Danny Harvey, BRTT