From a48ebc5db02960165bf1b9fb64443a5cdf9635d5 Mon Sep 17 00:00:00 2001
From: Albrecht Schlosser <albrechts.fltk@online.de>
Date: Tue, 14 Jan 2025 15:21:42 +0100
Subject: [PATCH] Fix return value of Fl_Table_Row::row_selected(int) (PR
#1187)
As discussed in the context of PR #1187 the previous return value '-1'
was misleading and undocumented. The docs mentioned only '1' and '0'.
User code that used the return value as documented (like a `bool`)
would make the wrong decision if the return value was '-1': true
(selected) instead false (out of range).
This commit fixes the code by doing what the docs define and clarifies
the documentation.
Further documentation improvements of Fl_Table (example code used a
method that is not defined in Fl_Table) and of Fl_Table_Row are
included as well.
Doxygen docs of two methods of Fl_Table_Row moved to the .cxx file
where they belong according to the CMP.
---
FL/Fl_Table.H | 2 +-
FL/Fl_Table_Row.H | 16 ++++-----------
src/Fl_Table_Row.cxx | 48 ++++++++++++++++++++++++++++++--------------
3 files changed, 38 insertions(+), 28 deletions(-)
diff --git a/FL/Fl_Table.H b/FL/Fl_Table.H
index 746b3a37d..7fb80cd04 100644
--- a/FL/Fl_Table.H
+++ b/FL/Fl_Table.H
@@ -351,7 +351,7 @@ protected:
fl_push_clip(X, Y, W, H);
{
// BG COLOR
- fl_color( row_selected(R) ? selection_color() : FL_WHITE);
+ fl_color(is_selected(R, C) ? selection_color() : FL_WHITE);
fl_rectf(X, Y, W, H);
// TEXT
diff --git a/FL/Fl_Table_Row.H b/FL/Fl_Table_Row.H
index ac35f333c..93f8b0e8c 100644
--- a/FL/Fl_Table_Row.H
+++ b/FL/Fl_Table_Row.H
@@ -157,19 +157,11 @@ public:
return(_selectmode);
}
- /**
- Checks to see if 'row' is selected. Returns 1 if selected, 0 if not. You can
- change the selection of a row by clicking on it, or by using
- select_row(row, flag)
- */
- int row_selected(int row); // is row selected? (0=no, 1=yes, -1=range err)
+ // Checks to see if 'row' is selected. Returns 1 if selected, 0 if not.
+ int row_selected(int row);
- /**
- Changes the selection state for 'row', depending on the value
- of 'flag'. 0=deselected, 1=select, 2=toggle existing state.
- */
- int select_row(int row, int flag=1); // select state for row: flag:0=off, 1=on, 2=toggle
- // returns: 0=no change, 1=changed, -1=range err
+ // Changes the selection state for 'row', depending on the value of 'flag'.
+ int select_row(int row, int flag = 1);
/**
This convenience function changes the selection state
diff --git a/src/Fl_Table_Row.cxx b/src/Fl_Table_Row.cxx
index e800455f8..dca5c10b7 100644
--- a/src/Fl_Table_Row.cxx
+++ b/src/Fl_Table_Row.cxx
@@ -64,10 +64,24 @@ void Fl_Table_Row::CharVector::size(int count) {
}
-// Is row selected?
+/**
+ Checks to see if 'row' is selected.
+
+ Returns 1 if selected, 0 if not. You can change the selection of a row
+ by clicking on it, or by using select_row(row, flag)
+
+ \p row \b should be a valid row. If the row is out of range the return
+ value is 0 (zero).
+
+ \param[in] row row to be checked
+
+ \return whether given row is selected
+ \retval 1 row is selected
+ \retval 0 row is not selected or \p row is out of range
+*/
int Fl_Table_Row::row_selected(int row) {
- if ( row < 0 || row >= rows() ) return(-1);
- return(_rowselect[row]);
+ if (row < 0 || row >= rows()) return 0;
+ return _rowselect[row];
}
// Change row selection type
@@ -98,18 +112,22 @@ void Fl_Table_Row::type(TableRowSelectMode val) {
}
}
-// Change selection state for row
-//
-// flag:
-// 0 - clear selection
-// 1 - set selection
-// 2 - toggle selection
-//
-// Returns:
-// 0 - selection state did not change
-// 1 - selection state changed
-// -1 - row out of range or incorrect selection mode
-//
+/**
+ Changes the selection state for \p 'row', depending on the value of \p 'flag'.
+
+ The optional \p flag can be:
+ - 0: clear selection
+ - 1: set selection (default)
+ - 2: toggle selection
+
+ \param[in] row row to be selected, deselected, or toggled
+ \param[in] flag change mode, see description
+ \return result of modification, see description
+ \retval 0: selection state did not change
+ \retval 1: selection state changed
+ \retval -1: row out of range or incorrect selection mode (\p flag)
+*/
+
int Fl_Table_Row::select_row(int row, int flag) {
int ret = 0;
if ( row < 0 || row >= rows() ) { return(-1); }
--
GitLab