//
// "$Id: Fl_Browser.cxx,v 1.104 2005/01/25 09:49:11 spitzak Exp $"
//
// Copyright 1998-2003 by Bill Spitzak and others.
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Library General Public
// License as published by the Free Software Foundation; either
// version 2 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Library General Public License for more details.
//
// You should have received a copy of the GNU Library General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
// USA.
//
// Please report all bugs and problems to "fltk-bugs@fltk.org".

#include <fltk/Browser.h>
#include <fltk/Button.h>
#include <fltk/events.h>
#include <fltk/damage.h>
#include <fltk/layout.h>
#include <fltk/Box.h>
#include <fltk/Item.h>
#include <fltk/draw.h>
#include <fltk/error.h>
#include <fltk/Cursor.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
using namespace fltk;

/*! \class fltk::Browser

  Displays a scrolling vertical list of text widgets, possibly with a
  hierachial arrangement, and lets the user select one of them.

  \image html browser.gif

  The items may be created as child widgets (usually the same widgets
  as are used to create menus: fltk::Item widgets, or fltk::ItemGroup
  widgets to make a hierarchy). Alternatively you can build simple
  text lists by using the add() method, which will create the child
  widgets for you (and even create a hierarchy if you put slashes in
  the text). You can also us an fltk::List which allows you to control
  the storage by dynamically creating a "fake" widget for the browser
  to use to draw each item.

  All the functions used to add, remove, or modify items in the list
  are defined by the base class fltk::Menu. See that for much more
  information.

  For a simple constant list you can populate the list by calling
  browser->add("text of item") once for each item.  If you give the
  browser a callback you can find out what item was selected with
  value(), the first item is zero (this is different from
  older versions of fltk that started at 1!), and will be negative if
  no item is selected. You can change the selected item with
  value(new_value).

  The subclass fltk::MultiBrowser lets the user select more than one
  item at the same time.

  The callback() is done when the user changes the selected items or
  when they open/close parents. In addition, if the user double-clicks
  a non-parent item, then it is "executed" which usually means that
  the callback() on the item itself is run. However if that is the
  default callback, the callback() of this widget is called with the
  user_data() of the item.

  You can control when callbacks are done with the when() method. The
  following values are useful, the default value is fltk::WHEN_CHANGED.

  - fltk::WHEN_NEVER - Callback is never done. changed() can be used
    to see if the user has modified the browser.

  - fltk::WHEN_CHANGED - Callback is called on every change to each
    item as it happens. The method item() will return the one that
    is being changed. Notice that selecting large numbers in a mulit
    browser will produce large numbers of callbacks.

  - fltk::WHEN_RELEASE - Callback is done when the user releases the
    mouse after some changes, and on any keystroke that
    changes the item. For a multi browser you will only be able
    to find out all the changes by scanning all the items in the callback.

  - fltk::WHEN_RELEASE_ALWAYS - Callback is done when the user
    releases the mouse even if the current item has not changed, and
    on any arrow keystroke even when at the top or bottom of the
    browser.

  - fltk::WHEN_ENTER_KEY - If you turn this on then the enter key is
    a shortcut and executes the current item like double-click.

*/

////////////////////////////////////////////////////////////////
// Compile-time style configuration options.
// For "run time configuration" copy this file, rename the widget,
// compile with your desired options, and use your renamed widget.
// Deal with it.

#define DRAW_STRIPES 0 // draw Macintosh-style stripes
#define TRIANGLE_GLYPH 0 // use Macintosh/fltk-style glyphs

/*! \fn int Browser::width() const
  The width of the longest item in the browser, measured in pixels. If
  this is changed (by adding or deleting items or opening or closing a
  parent item) then layout() must be called before this is correct.
*/

/*! \fn int Browser::height() const
  The height of all the visible items in the browser, measured in
  pixels. If this is changed (by adding or deleting items or opening
  or closing a parent item) then layout() must be called before this
  is correct.
*/

/*! \fn int Browser::box_width() const
  The width of the display area of the browser in pixels, this is w()
  minus the edges of the box() minus the width of the vertical
  scrollbar, if visible. If this is changed (by resizing the widget,
  adding or deleting items or opening or closing a parent item such
  that the scrollbar visibility changes) then layout() must be called
  before this is correct.
*/

/*! \fn int Browser::box_height() const
  The height of the display area of the browser in pixels, this is h()
  minus the edges of the box() minus the height of the horizontal
  scrollbar, if visible. If this is changed (by resizing the widget,
  adding or deleting items or opening or closing a parent item such
  that the scrollbar visibility changes) then layout() must be called
  before this is correct.
*/

/*! \fn void Browser::indented(bool v)
  Turn this on to for space to be reserved for open/close boxes drawn
  to the left of top-level items. You usually want this for a
  hierarchial browser. This should be off for a flat browser, or to
  emulate Windows Explorer where "my computer" does not have an
  open/close to the left of it. The default value is false.
*/

/*! \fn Widget *Browser::header(int col)
  Return pointer to Widget in column \a col, starting from index 0.
  If column \a col is invalid, NULL is returned.
*/
  
/*! \fn int Browser::nheader() const
  Return number of columns in browser.
*/

////////////////////////////////////////////////////////////////
// Moving between items:

// A "mark" is like a pointer to a widget somewhere in the hierarchy
// of the Browser. Actually it is an array of child indicies, and also
// the vertical position and index number (used to decide stripe color)
// of the item.

// The Browser has space to store a fixed number of marks.

// The "current item" is the one pointed to by the mark called HERE.
// A pointer to it is stored in item(). To allow List to work, this
// pointer is only valid until the next item is referenced, so don't
// copy it to any storage. You can move the current item forward and
// backward, skipping invisible items. You can also place it on any
// item, even ones that cannot be seen, by using goto_item.

/*!
  Return true if the item would be visible to the user if the browser
  was scrolled to the correct location. This means that the
  fltk::INVISIBLE flag is not set on it, and all parents of it are
  open and visible as well.
*/
bool Browser::item_is_visible() const {
  return open_level[HERE] >= item_level[HERE] && item()->visible();
}

/*! This function increases the number of levels we can store in each
  mark, and sets the level of the current mark to n. */
void Browser::set_level(int n) {
  if (n > levels) {
    if (n > 255) fatal("More than 255 levels in Browser");
    for (int i = 0; i < NUMMARKS; i++) {
      item_index[i]=(int*)realloc((void*)item_index[i],(n+1)*sizeof(int));
    }
    levels = n;
  }
  item_level[HERE] = n;
}

/*!
  Because of the hierarchial structure it is difficult to identify
  an item