mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fl_Table was missing doxygen docs for several public + protected members.

Browse Source 
Solves STR# 3381.

Also: standardized doxygen comment style in both files; 
      > /** */ doxygen commenting
      > 2 space indent

Removed some confusing non-doxygen comments, and rewrote some confusing ones.

Removed old license info Matt had imported from my original 2002 widget..
there was no reason for it to be in there; the Fl_Table code inside FLTK
is licensed under the FLTK GPL license, no need for the extra noise in the docs.




git-svn-id: file:///fltk/svn/fltk/branches/branch-1.4@12228 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Greg Ercolano 2017-04-26 20:12:34 +00:00
parent 18a84d073d
commit afd118047b
2 changed files with 581 additions and 527 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
FL/Fl_Table.H
View File

@ -113,59 +113,9 @@
LICENSE
Greg added the following license to the original distribution of Fl_Table. He
kindly gave his permission to integrate Fl_Table and Fl_Table_Row into FLTK,
allowing FLTK license to apply while his widgets are part of the library.
If used on its own, this is the license that applies:
\verbatim
Fl_Table License
December 16, 2002
The Fl_Table library and included programs are provided under the terms
of the GNU Library General Public License (LGPL) with the following
exceptions:
1. Modifications to the Fl_Table configure script, config
header file, and makefiles by themselves to support
a specific platform do not constitute a modified or
derivative work.
The authors do request that such modifications be
contributed to the Fl_Table project - send all
contributions to "erco at seriss dot com".
2. Widgets that are subclassed from Fl_Table widgets do not
constitute a derivative work.
3. Static linking of applications and widgets to the
Fl_Table library does not constitute a derivative work
and does not require the author to provide source
code for the application or widget, use the shared
Fl_Table libraries, or link their applications or
widgets against a user-supplied version of Fl_Table.
If you link the application or widget to a modified
version of Fl_Table, then the changes to Fl_Table must be
provided under the terms of the LGPL in sections
1, 2, and 4.
4. You do not have to provide a copy of the Fl_Table license
with programs that are linked to the Fl_Table library, nor
do you have to identify the Fl_Table license in your
program or documentation as required by section 6
of the LGPL.
However, programs must still identify their use of Fl_Table.
The following example statement can be included in user
documentation to satisfy this requirement:
[program/widget] is based in part on the work of
the Fl_Table project http://seriss.com/people/erco/fltk/Fl_Table/
\endverbatim
Greg kindly gave his permission to integrate Fl_Table and Fl_Table_Row
into FLTK, allowing FLTK license to apply while his widgets are part
of the library. [updated by Greg, 04/26/17]
*/
class FL_EXPORT Fl_Table : public Fl_Group {
public:
@ -317,7 +267,6 @@ protected:
int &X, int &Y, int &W, int &H);
void change_cursor(Fl_Cursor newcursor); // change mouse cursor to some other shape
TableContext cursor2rowcol(int &R, int &C, ResizeFlag &resizeflag);
// find r/c given current x/y event
int find_cell(TableContext context, // find cell's x/y/w/h given r/c
int R, int C, int &X, int &Y, int &W, int &H);
int row_col_clamp(TableContext context, int &R, int &C);
@ -440,6 +389,9 @@ protected:
long row_scroll_position(int row); // find scroll position of row (in pixels)
long col_scroll_position(int col); // find scroll position of col (in pixels)
/**
Does the table contain any child fltk widgets?
*/
int is_fltk_container() { // does table contain fltk widgets?
return( Fl_Group::children() > 3 ); // (ie. more than box and 2 scrollbars?)
}
@ -448,6 +400,10 @@ protected:
void damage_zone(int r1, int c1, int r2, int c2, int r3 = 0, int c3 = 0);
/**
Define region of cells to be redrawn by specified range of rows/cols,
and then sets damage(DAMAGE_CHILD). Extends any previously defined range to redraw.
*/
void redraw_range(int topRow, int botRow, int leftCol, int rightCol) {
if ( _redraw_toprow == -1 ) {
// Initialize redraw range
@ -462,23 +418,12 @@ protected:
if ( leftCol < _redraw_leftcol ) _redraw_leftcol = leftCol;
if ( rightCol > _redraw_rightcol ) _redraw_rightcol = rightCol;
}
// Indicate partial redraw needed of some cells
damage(FL_DAMAGE_CHILD);
}
public:
/**
The constructor for the Fl_Table.
This creates an empty table with no rows or columns,
with headers and row/column resize behavior disabled.
*/
Fl_Table(int X, int Y, int W, int H, const char *l=0);
/**
The destructor for the Fl_Table.
Destroys the table and its associated widgets.
*/
~Fl_Table();
/**
@ -486,7 +431,11 @@ public:
any widgets (table->clear()) that were added with begin()/end() or add()/insert()/etc.
\see rows(int), cols(int)
*/
virtual void clear() { rows(0); cols(0); table->clear(); }
virtual void clear() {
rows(0);
cols(0);
table->clear();
}
// \todo: add topline(), middleline(), bottomline()
@ -507,9 +456,6 @@ public:
return(table->box());
}
/**
Sets the number of rows in the table, and the table is redrawn.
*/
virtual void rows(int val); // set/get number of rows
/**
@ -519,9 +465,6 @@ public:
return(_rows);
}
/**
Set the number of columns in the table and redraw.
*/
virtual void cols(int val); // set/get number of columns
/**
@ -597,6 +540,7 @@ public:
inline int col_resize() {
return(_col_resize);
}
/**
Allows/disallows column resizing by the user.
1=allow interactive resizing, 0=disallow interactive resizing.
@ -735,12 +679,6 @@ public:
return(_col_header_color);
}
/**
Sets the height of the specified row in pixels,
and the table is redrawn.
callback() will be invoked with CONTEXT_RC_RESIZE
if the row's height was actually changed, and when() is FL_WHEN_CHANGED.
*/
void row_height(int row, int height); // set/get row height
/**
@ -750,11 +688,6 @@ public:
return((row<0 || row>=(int)_rowheights.size()) ? 0 : _rowheights[row]);
}
/**
Sets the width of the specified column in pixels, and the table is redrawn.
callback() will be invoked with CONTEXT_RC_RESIZE
if the column's width was actually changed, and when() is FL_WHEN_CHANGED.
*/
void col_width(int col, int width); // set/get a column's width
/**
@ -784,27 +717,20 @@ public:
}
}
/**
Sets the row scroll position to 'row', and causes the screen to redraw.
*/
void row_position(int row); // set/get table's current scroll position
/**
Sets the column scroll position to column 'col', and causes the screen to redraw.
*/
void col_position(int col);
/**
Returns the current row scroll position as a row number.
*/
int row_position() { // current row position
int row_position() {
return(_row_position);
}
/**
Returns the current column scroll position as a column number.
*/
int col_position() { // current col position
int col_position() {
return(_col_position);
}
@ -829,10 +755,6 @@ public:
void set_selection(int row_top, int col_left, int row_bot, int col_right);
int move_cursor(int R, int C, int shiftselect);
int move_cursor(int R, int C);
/**
Changes the size of the Fl_Table, causing it to redraw.
*/
void resize(int X, int Y, int W, int H); // fltk resize() override
void draw(void); // fltk draw() override
@ -847,11 +769,21 @@ public:
// return(Fl_Group::box());
// }
// Child group
// Child group management
/**
Resets the internal array of widget sizes and positions.
\sa Fl_Group::init_sizes()
*/
void init_sizes() {
table->init_sizes();
table->redraw();
}
/**
The specified widget is removed from its current group (if any)
and added to the end of Fl_Table's group.
*/
void add(Fl_Widget& wgt) {
table->add(wgt);
if ( table->children() > 2 ) {
@ -860,21 +792,45 @@ public:
table->hide();
}
}
/**
The specified widget is removed from its current group (if any)
and added to the end of Fl_Table's group.
*/
void add(Fl_Widget* wgt) {
add(*wgt);
}
/**
The specified widget is removed from its current group (if any)
and inserted into the Fl_Table's group at position 'n'.
*/
void insert(Fl_Widget& wgt, int n) {
table->insert(wgt,n);
}
/**
The specified widget is removed from its current group (if any)
and inserted into Fl_Table's group before widget 'w2'.
This will append if 'w2' is not in Fl_Table's group.
*/
void insert(Fl_Widget& wgt, Fl_Widget* w2) {
table->insert(wgt,w2);
}
/**
The specified widget is removed from Fl_Table's group.
*/
void remove(Fl_Widget& wgt) {
table->remove(wgt);
}
// (doxygen will substitute Fl_Group's docs here)
void begin() {
table->begin();
}
// (doxygen will substitute Fl_Group's docs here)
void end() {
table->end();
// HACK: Avoid showing Fl_Scroll; seems to erase screen
@ -887,6 +843,11 @@ public:
}
Fl_Group::current(Fl_Group::parent());
}
/**
Returns a pointer to the array of children. <I>This pointer is only
valid until the next time a child is added or removed.</I>
*/
Fl_Widget*const* array() {
return(table->array());
}
@ -920,41 +881,53 @@ public:
int children() const {
return(table->children()-2); // -2: skip Fl_Scroll's h/v scrollbar widgets
}
// (doxygen will substitute Fl_Group's docs here)
int find(const Fl_Widget *wgt) const {
return(table->find(wgt));
}
// (doxygen will substitute Fl_Group's docs here)
int find(const Fl_Widget &wgt) const {
return(table->find(wgt));
}
// CALLBACKS
/**
* Returns the current row the event occurred on.
*
* This function should only be used from within the user's callback function.
Returns the current row the event occurred on.
This function should only be used from within the user's callback function.
*/
int callback_row() {
return(_callback_row);
}
/**
* Returns the current column the event occurred on.
*
* This function should only be used from within the user's callback function.
Returns the current column the event occurred on.
This function should only be used from within the user's callback function.
*/
int callback_col() {
return(_callback_col);
}
/**
* Returns the current 'table context'.
*
* This function should only be used from within the user's callback function.
Returns the current 'table context'.
This function should only be used from within the user's callback function.
*/
TableContext callback_context() {
return(_callback_context);
}
/**
Calls the widget callback.
Saves the specified 'context', 'row', and 'col' values, so that the user's
callback can then access them with the member functions
callback_context(), callback_row() and callback_col().
*/
void do_callback(TableContext context, int row, int col) {
_callback_context = context;
_callback_row = row;

167
src/Fl_Table.cxx
View File

@ -25,7 +25,9 @@
#include <FL/fl_utf8.H> // currently only Windows and Linux
#endif
// Scroll display so 'row' is at top
/** Sets the vertical scroll position so 'row' is at the top,
and causes the screen to redraw.
*/
void Fl_Table::row_position(int row) {
if ( _row_position == row ) return; // OPTIMIZATION: no change? avoid redraw
if ( row < 0 ) row = 0;
@ -41,7 +43,10 @@ void Fl_Table::row_position(int row) {
_row_position = row; // HACK: override what table_scrolled() came up with
}
// Scroll display so 'col' is at left
/**
Sets the horizontal scroll position so 'col' is at the left,
and causes the screen to redraw.
*/
void Fl_Table::col_position(int col) {
if ( _col_position == col ) return; // OPTIMIZATION: no change? avoid redraw
if ( col < 0 ) col = 0;
@ -57,7 +62,9 @@ void Fl_Table::col_position(int col) {
_col_position = col; // HACK: override what table_scrolled() came up with
}
// Find scroll position of a row (in pixels)
/**
Returns the scroll position (in pixels) of the specified 'row'.
*/
long Fl_Table::row_scroll_position(int row) {
int startrow = 0;
long scroll = 0;
@ -74,7 +81,9 @@ long Fl_Table::row_scroll_position(int row) {
return(scroll);
}
// Find scroll position of a column (in pixels)
/**
Returns the scroll position (in pixels) of the specified column 'col'.
*/
long Fl_Table::col_scroll_position(int col) {
int startcol = 0;
long scroll = 0;
@ -91,7 +100,11 @@ long Fl_Table::col_scroll_position(int col) {
return(scroll);
}
// Ctor
/**
The constructor for Fl_Table.
This creates an empty table with no rows or columns,
with headers and row/column resize behavior disabled.
*/
Fl_Table::Fl_Table(int X, int Y, int W, int H, const char *l) : Fl_Group(X,Y,W,H,l) {
_rows = 0;
_cols = 0;
@ -156,12 +169,21 @@ Fl_Table::Fl_Table(int X, int Y, int W, int H, const char *l) : Fl_Group(X,Y,W,H
table->begin(); // leave with fltk children getting added to the scroll
}
// Dtor
/**
The destructor for Fl_Table.
Destroys the table and its associated widgets.
*/
Fl_Table::~Fl_Table() {
// The parent Fl_Group takes care of destroying scrollbars
}
// Set height of a row
/**
Sets the height of the specified row in pixels,
and the table is redrawn.
callback() will be invoked with CONTEXT_RC_RESIZE
if the row's height was actually changed, and when() is FL_WHEN_CHANGED.
*/
void Fl_Table::row_height(int row, int height) {
if ( row < 0 ) return;
if ( row < (int)_rowheights.size() && _rowheights[row] == height ) {
@ -185,7 +207,11 @@ void Fl_Table::row_height(int row, int height) {
}
}
// Set width of a column
/**
Sets the width of the specified column in pixels, and the table is redrawn.
callback() will be invoked with CONTEXT_RC_RESIZE
if the column's width was actually changed, and when() is FL_WHEN_CHANGED.
*/
void Fl_Table::col_width(int col, int width)
{
if ( col < 0 ) return;
@ -211,7 +237,11 @@ void Fl_Table::col_width(int col, int width)
}
}
// Return row/col clamped to reality
/**
Return specfied row/col values R and C to within the table's
current row/col limits.
\returns 0 if no changes were made, or 1 if they were.
*/
int Fl_Table::row_col_clamp(TableContext context, int &R, int &C) {
int clamped = 0;
if ( R < 0 ) { R = 0; clamped = 1; }
@ -237,7 +267,9 @@ int Fl_Table::row_col_clamp(TableContext context, int &R, int &C) {
return(clamped);
}
// Return bounding region for given context
/**
Returns the (X,Y,W,H) bounding region for the specified 'context'.
*/
void Fl_Table::get_bounds(TableContext context, int &X, int &Y, int &W, int &H) {
switch ( context ) {
case CONTEXT_COL_HEADER:
@ -269,11 +301,11 @@ void Fl_Table::get_bounds(TableContext context, int &X, int &Y, int &W, int &H)
//NOTREACHED
}
// Find row/col beneath cursor
//
// Returns R/C and context.
// Also returns resizeflag, if mouse is hovered over a resize boundary.
//
/**
Find row/col for the recent mouse event.
Returns the context, and the row/column values in R/C.
Also returns 'resizeflag' if mouse is hovered over a resize boundary.
*/
Fl_Table::TableContext Fl_Table::cursor2rowcol(int &R, int &C, ResizeFlag &resizeflag) {
// return values
R = C = 0;
@ -350,10 +382,12 @@ Fl_Table::TableContext Fl_Table::cursor2rowcol(int &R, int &C, ResizeFlag &resiz
return(CONTEXT_NONE);
}
// Find X/Y/W/H for cell at R/C
// If R or C are out of range, returns -1
// with X/Y/W/H set to zero.
//
/**
Find a cell's X/Y/W/H region for the specified cell in row 'R', column 'C'.
\returns
- 0 -- on success, XYWH returns the region of the specified cell.
- -1 -- if R or C are out of range, and X/Y/W/H will be set to zero.
*/
int Fl_Table::find_cell(TableContext context, int R, int C, int &X, int &Y, int &W, int &H) {
if ( row_col_clamp(context, R, C) ) { // row or col out of range? error
X=Y=W=H=0;
@ -458,7 +492,10 @@ void Fl_Table::_auto_drag_cb() {
}
}
// Recalculate the window dimensions
/**
Recalculate the dimensions of the table, and affect any children.
Internally, Fl_Group::resize() and init_sizes() are called.
*/
void Fl_Table::recalc_dimensions() {
// Recalc to* (Table Outer), ti* (Table Inner), wi* ( Widget Inner)
wix = ( x() + Fl::box_dx(box())); tox = wix; tix = tox + Fl::box_dx(table->box());
@ -494,12 +531,12 @@ void Fl_Table::recalc_dimensions() {
table->init_sizes();
}
// Recalculate internals after a scroll.
//
// Call this if table has been scrolled or resized.
// Does not handle redraw().
// TODO: Assumes ti[xywh] has already been recalculated.
//
/**
Recalculate internals after a scroll.
Call this if table has been scrolled or resized.
Does not handle redraw().
TODO: Assumes ti[xywh] has already been recalculated.
*/
void Fl_Table::table_scrolled() {
// Find top row
int y, row, voff = vscrollbar->value();
@ -537,11 +574,10 @@ void Fl_Table::table_scrolled() {
draw_cell(CONTEXT_RC_RESIZE, 0,0,0,0,0,0);
}
// Table resized: recalc internal data
// Call this whenever the window is resized.
// Recalculates the scrollbar sizes.
// Makes no assumptions about any pre-initialized data.
//
/**
Call this if table was resized, to recalculate internal data.
Calls recall_dimensions(), and recalculates scrollbar sizes.
*/
void Fl_Table::table_resized() {
table_h = row_scroll_position(rows());
table_w = col_scroll_position(cols());
@ -582,7 +618,9 @@ void Fl_Table::table_resized() {
// redraw();
}
// Someone moved a scrollbar
/**
Callback for when someone moves a scrollbar.
*/
void Fl_Table::scroll_cb(Fl_Widget*w, void *data) {
Fl_Table *o = (Fl_Table*)data;
o->recalc_dimensions(); // recalc tix, tiy, etc.
@ -590,7 +628,9 @@ void Fl_Table::scroll_cb(Fl_Widget*w, void *data) {
o->redraw();
}
// Set number of rows
/**
Sets the number of rows in the table, and the table is redrawn.
*/
void Fl_Table::rows(int val) {
int oldrows = _rows;
_rows = val;
@ -612,7 +652,9 @@ void Fl_Table::rows(int val) {
}
}
// Set number of cols
/**
Set the number of columns in the table and redraw.
*/
void Fl_Table::cols(int val) {
_cols = val;
{
@ -627,7 +669,9 @@ void Fl_Table::cols(int val) {
redraw();
}
// Change mouse cursor to different type
/**
Change mouse cursor to different type
*/
void Fl_Table::change_cursor(Fl_Cursor newcursor) {
if ( newcursor != _last_cursor ) {
fl_cursor(newcursor, FL_BLACK, FL_WHITE);
@ -635,6 +679,10 @@ void Fl_Table::change_cursor(Fl_Cursor newcursor) {
}
}
/**
Sets the damage zone to the specified row/col values.
Calls redraw_range().
*/
void Fl_Table::damage_zone(int r1, int c1, int r2, int c2, int r3, int c3) {
int R1 = r1, C1 = c1;
int R2 = r2, C2 = c2;
@ -661,6 +709,32 @@ void Fl_Table::damage_zone(int r1, int c1, int r2, int c2, int r3, int c3) {
redraw_range(R1, R2, C1, C2);
}
/**
Moves the selection cursor a relative number of rows/columns specifed by R/C.
R/C can be positive or negative, depending on the direction to move.
A value of 0 for R or C prevents cursor movement on that axis.
If shiftselect is set, the selection range is extended to the new
cursor position. If clear, the cursor is simply moved, and any previous
selection is cancelled.
Used mainly by keyboard events (e.g. Fl_Right, FL_Home, FL_End..)
to let the user keyboard navigate the selection cursor around.
The scroll positions may be modified if the selection cursor traverses
into cells off the screen's edge.
Internal variables select_row/select_col and current_row/current_col
are modified, among others.
\code
Examples:
R=1, C=0 -- moves the selection cursor one row downward.
R=5, C=0 -- moves the selection cursor 5 rows downward.
R=-5, C=0 -- moves the cursor 5 rows upward.
R=2, C=2 -- moves the cursor 2 rows down and 2 columns to the right.
\endcode
*/
int Fl_Table::move_cursor(int R, int C, int shiftselect) {
if (select_row == -1) R++;
if (select_col == -1) C++;
@ -683,6 +757,9 @@ int Fl_Table::move_cursor(int R, int C, int shiftselect) {
return 1;
}
/**
Same as move_cursor(R,C,1);
*/
int Fl_Table::move_cursor(int R, int C) {
return move_cursor(R,C,1);
}
@ -696,7 +773,9 @@ int Fl_Table::move_cursor(int R, int C) {
#define PRINTEVENT
#endif
// Handle FLTK events
/**
Handle FLTK events.
*/
int Fl_Table::handle(int event) {
PRINTEVENT;
int ret = Fl_Group::handle(event); // let FLTK group handle events first
@ -1051,9 +1130,10 @@ int Fl_Table::handle(int event) {
return(ret);
}
// Resize FLTK override
// Handle resize events if user resizes parent window.
//
/**
Handle resize events if user resizes parent window.
This changes the size of Fl_Table, causing it to redraw.
*/
void Fl_Table::resize(int X, int Y, int W, int H) {
// Tell group to resize, and recalc our own widget as well
Fl_Group::resize(X, Y, W, H);
@ -1141,10 +1221,11 @@ void Fl_Table::set_selection(int row_top, int col_left, int row_bot, int col_rig
damage_zone(current_row, current_col, select_row, select_col);
}
// Draw the entire Fl_Table
// Override the draw() routine to draw the table.
// Then tell the group to draw over us.
//
/**
Draws the entire Fl_Table.
Lets fltk widgets draw themselves first, followed by the cells
via calls to draw_cell().
*/
void Fl_Table::draw() {
int scrollsize = _scrollbar_size ? _scrollbar_size : Fl::scrollbar_size();
// Check if scrollbar size changed