Improve focus box drawing and documentation

Add new method
  Fl_Widget::draw_focus(Fl_Boxtype t, int x, int y, int w, int h, Fl_Color bg)

  ... with background color for correct contrast testing (in Fl_Tabs)

Draw the focus box of the "tabs" of Fl_Tabs widgets with the correct
  boxtype and background color.

Make 'unsigned int visible_focus()' const so it can be used in 'const'
  methods.

Do not draw the focus box if the per-widget focus box option is off.

1 files changed, 37 insertions, 9 deletions

diff --git a/src/Fl_Widget.cxx b/src/Fl_Widget.cxx
index 8b4de1a2a..16bf7bc5d 100644
--- a/src/Fl_Widget.cxx
+++ b/src/Fl_Widget.cxx
@@ -182,11 +182,38 @@ Fl_Widget::~Fl_Widget() {
   if (callback_ == default_callback) cleanup_readqueue(this);
 }
 
-/** Draws a focus box for the widget at the given position and size. */
+/**
+  Draws a focus box for the widget at the given position and size.
+
+  This method does nothing if
+  - the global option Fl::visible_focus() or
+  - the per-widget option visible_focus()
+  is false (off).
+
+  This means that Fl_Widget::draw_focus() or one of the more specialized
+  methods can be called without checking these visible focus options.
+
+  \note This method must only be called if the widget has the focus.
+        This is not tested internally.
+
+  The boxtype \p bt is used to calculate the inset so the focus box is drawn
+  inside the box borders.
 
-void Fl_Widget::draw_focus(Fl_Boxtype B, int X, int Y, int W, int H) const {
+  The default focus box drawing color is black. The background color \p bg
+  is used to determine a better visible color if necessary by using
+  fl_contrast() with the given background color.
+
+  \param[in]  bt        Boxtype that needs to be considered (frame width)
+  \param[in]  X,Y,W,H   Bounding box
+  \param[in]  bg        Background color
+
+  \see Fl_Widget::draw_focus()
+  \see Fl_Widget::draw_focus(Fl_Boxtype, int, int, int, int) const
+*/
+void Fl_Widget::draw_focus(Fl_Boxtype bt, int X, int Y, int W, int H, Fl_Color bg) const {
   if (!Fl::visible_focus()) return;
-  switch (B) {
+  if (!visible_focus()) return;
+  switch (bt) {
     case FL_DOWN_BOX:
     case FL_DOWN_FRAME:
     case FL_THIN_DOWN_BOX:
@@ -196,16 +223,17 @@ void Fl_Widget::draw_focus(Fl_Boxtype B, int X, int Y, int W, int H) const {
     default:
       break;
   }
-  X += Fl::box_dx(B);
-  Y += Fl::box_dy(B);
-  W -= Fl::box_dw(B)+1;
-  H -= Fl::box_dh(B)+1;
+  X += Fl::box_dx(bt);
+  Y += Fl::box_dy(bt);
+  W -= Fl::box_dw(bt)+1;
+  H -= Fl::box_dh(bt)+1;
 
-  fl_color(fl_contrast(FL_BLACK, color()));
+  Fl_Color savecolor = fl_color();
+  fl_color(fl_contrast(FL_BLACK, bg));
   fl_focus_rect(X, Y, W, H);
+  fl_color(savecolor);
 }
 
-
 void Fl_Widget::activate() {
   if (!active()) {
     clear_flag(INACTIVE);