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.

2 files changed, 5 insertions, 13 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