STR #1742: Updated documentation to reflect the true nature of "selection()" and "value()" for Fl_Multi_Browser which can be quite surprisin for unsuspecting customers.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@5952 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

CHANGES

@@ -2,7 +2,8 @@ CHANGES IN FLTK 1.1.8
 
 	- Documentation fixes (STR #1454, STR #1455, STR #1456,
 	  STR #1457, STR #1458, STR #1460, STR #1481, STR #1578,
-	  STR #1639, STR #1645, STR #1644, STR #1792, STR #1793)
+	  STR #1639, STR #1645, STR #1644, STR #1792, STR #1793,
+	  STR #1742)
 	- Changing the window size in FLUID would not mark the 
 	  project as modified (STR #1751)
 	- Fixed fl_filename_isdir for "/"-path (STR #1761)

documentation/Fl_Browser_.html

@@ -376,8 +376,11 @@ callback function for the widget.
 <H4><A NAME="Fl_Browser_.selection">void *Fl_Browser_::selection() const</A></H4>
 
 <P>Returns the item currently selected, or NULL if there is no selection.
-For multiple selection browsers this call returns the last item that was
+
-selected.
+<P>For multiple selection browsers this call returns the currently focused item,
+even if it is not selected. To find all selected items, call 
+<TT><A href=Fl_Multi_Browser.html#Fl_Multi_Browser.select>
+Fl_Multi_Browser::selected()</A></TT> for every item in question.
 
 
 <H4><A name="Fl_Browser_.textcolor">Fl_Color Fl_Browser_::textcolor() const

documentation/Fl_Multi_Browser.html

@@ -38,23 +38,41 @@ methods to add and remove lines from the browser. </P>
 <LI><A href=#Fl_Multi_Browser.select>select</A></LI>
 <LI><A href=#Fl_Multi_Browser.value>value</A></LI>
 </UL>
+
 <H4><A name=Fl_Multi_Browser.Fl_Multi_Browser>
 Fl_Multi_Browser::Fl_Multi_Browser(int x, int y, int w, int h, const
 char *label = 0)</A></H4>
- Creates a new <TT>Fl_Multi_Browser</TT> widget using the given
+
+Creates a new <TT>Fl_Multi_Browser</TT> widget using the given
 position, size, and label string. The default boxtype is <TT>FL_DOWN_BOX</TT>
 .
+
+
 <H4><A name=Fl_Multi_Browser.~Fl_Multi_Browser>virtual
 Fl_Multi_Browser::~Fl_Multi_Browser()</A></H4>
- The destructor <I>also deletes all the items in the list</I>.
+
+The destructor <I>also deletes all the items in the list</I>.
+
+
 <H4><A name=Fl_Multi_Browser.deselect>int Fl_Browser::deselect()</A></H4>
- Deselects all lines.
+
+Deselects all lines.
+
+
 <H4><A name=Fl_Multi_Browser.select>int Fl_Browser::select(int,int=1)
 <BR> int Fl_Browser::selected(int) const</A></H4>
- Selects one or more lines or gets the current selection state of a
+
+Selects one or more lines or gets the current selection state of a
 line.
-<H4><A name=Fl_Multi_Browser.value>int Fl_Browser::value() const
+
-<BR> void Fl_Browser::value(int)</A></H4>
+
- Selects a single line or gets the last toggled line. This returns zero
+<H4><A name=Fl_Multi_Browser.value>void Fl_Browser::value(int)
-if no line has been toggled, so be aware that this can happen in a
+<BR> int Fl_Browser::value() const</A></H4>
-callback. </BODY></HTML>
+
+The first version of this call selects a single line. The second version returns 
+the currently focused item, even if it is not selected. To find all 
+selected items, call 
+<TT><A href=Fl_Multi_Browser.html#Fl_Multi_Browser.select>
+Fl_Multi_Browser::selected()</A></TT> for every item in question.
+ 
+</BODY></HTML>

src/Fl_Browser_.cxx

@@ -575,47 +575,51 @@ int Fl_Browser_::handle(int event) {
     void* l1 = selection_;
     void* l = l1; if (!l) l = top_; if (!l) l = item_first();
     if (l) {
-      if (type()==FL_HOLD_BROWSER) switch (Fl::event_key()) {
+      if (type()==FL_HOLD_BROWSER) {
-      case FL_Down:
+        switch (Fl::event_key()) {
-	while ((l = item_next(l)))
+        case FL_Down:
-	  if (item_height(l)>0) {select_only(l, when()); break;}
+          while ((l = item_next(l)))
-	return 1;
+            if (item_height(l)>0) {select_only(l, when()); break;}
-      case FL_Up:
+            return 1;
-	while ((l = item_prev(l))) if (item_height(l)>0) {
+        case FL_Up:
-	  select_only(l, when()); break;}
+          while ((l = item_prev(l))) if (item_height(l)>0) {
-	return 1;
+            select_only(l, when()); break;}
-      } else switch (Fl::event_key()) {
+          return 1;
-      case FL_Enter:
+        } 
-      case FL_KP_Enter:
+      } else  {
-	select_only(l, when());
+        switch (Fl::event_key()) {
-	return 1;
+        case FL_Enter:
-      case ' ':
+        case FL_KP_Enter:
-	selection_ = l;
+          select_only(l, when());
-	select(l, !item_selected(l), when());
+          return 1;
-	return 1;
+        case ' ':
-      case FL_Down:
+          selection_ = l;
-	while ((l = item_next(l))) {
+          select(l, !item_selected(l), when());
-	  if (Fl::event_state(FL_SHIFT|FL_CTRL))
+          return 1;
-	    select(l, l1 ? item_selected(l1) : 1, when());
+        case FL_Down:
-	  if (item_height(l)>0) goto J1;
+          while ((l = item_next(l))) {
-	}
+            if (Fl::event_state(FL_SHIFT|FL_CTRL))
-	return 1;
+              select(l, l1 ? item_selected(l1) : 1, when());
-      case FL_Up:
+            if (item_height(l)>0) goto J1;
-	while ((l = item_prev(l))) {
+          }
-	  if (Fl::event_state(FL_SHIFT|FL_CTRL))
+          return 1;
-	    select(l, l1 ? item_selected(l1) : 1, when());
+        case FL_Up:
-	  if (item_height(l)>0) goto J1;
+          while ((l = item_prev(l))) {
-	}
+            if (Fl::event_state(FL_SHIFT|FL_CTRL))
-	return 1;
+              select(l, l1 ? item_selected(l1) : 1, when());
-      J1:
+            if (item_height(l)>0) goto J1;
-	if (selection_) redraw_line(selection_);
+          }
-	selection_ = l; redraw_line(l);
+          return 1;
-	display(l);
+J1:
-	return 1;
+          if (selection_) redraw_line(selection_);
+          selection_ = l; redraw_line(l);
+          display(l);
+          return 1;
+        }
       }
     }
   }
-
+  
   if (Fl_Group::handle(event)) return 1;
   int X, Y, W, H; bbox(X, Y, W, H);
   int my;