/*
vim:expandtab:softtabstop=4:tabstop=4:shiftwidth=4:nowrap:ruler
*/
/*
 TREE.DOX

 License CC0 PUBLIC DOMAIN

 To the extent possible under law, Mark J. Olesen has waived all copyright
 and related or neighboring rights to FDOSTUI Library. This work is published
 from: United States.
*/

/*! \file tree.hpp
\brief contains tree widget class
*/

/*! \class tree tree.hpp
\brief tree widget class

A tree consists of a hierarchy of treeitems. The tree widget class
manages the treeitems.

\code

    treeitem* root= new treeitem(reinterpret_cast<unsigned char const*>("Capital"));

    treeitem* state= new treeitem(reinterpret_cast<unsigned char const*>("NY"));
    state->add(reinterpret_cast<unsigned char const*>("Albany"));
    root->add(state);

    state= new treeitem(reinterpret_cast<unsigned char const*>("UT"));
    state->add(reinterpret_cast<unsigned char const*>("Salt Lake City"));
    root->add(state);

    state= new treeitem(reinterpret_cast<unsigned char const*>("NV"));
    state->add(reinterpret_cast<unsigned char const*>("Carson City"));
    root->add(state);

    tree* mytree= new tree(0, 0, 20, 10);
    mytree->attach(root);

\endcode

*/

/*!
\typedef void (*tree::signal_selected_t)(
        tree const*const                i_tree,
        void*                           io_user_data)
\brief function prototype to recieve signal
\param[in] i_tree tree widget
\param[in,out] io_user_data user defined
\returns none
*/

/*!
\fn tree::tree(
        int const                       i_pos_x,
        int const                       i_pos_y,
        unsigned int const              i_len_x,
        unsigned int const              i_len_y)
\brief construct an empty tree widget
\param[in] i_pos_x x position to place widget
\param[in] i_pos_y y position to place widget
\param[in] i_len_x x length of widget
\param[in] i_len_y y length of widget
\returns none
*/

/*!
\fn void tree::attach(
        treeitem*const                  io_root)
\brief attach a treeitem to this tree
\param[in,out] io_root valid treeitem. takes ownership of object.
\returns none

If an object is already attached, it will be deleted.
*/

/*!
\fn virtual void tree::draw() const
\brief draws the widget

This method should not be called directly. 
\see widget::draw for details.
*/

/*!    
\fn virtual tree::~tree()
\brief desctructor
\returns none

*/

/*!
\fn virtual enum event_response tree::event_key(
        struct event_key const&         i_event)
\brief handle key event
\param[in] i_event key event to handle    
\returns response how event was handled
*/
    
/!
\fn  virtual enum event_response tree::event_mouse(
        struct event_mouse const&       i_event)
\brief handle mouse event
\param[in] i_event mouse event to handle
\returns response how event was handled
*/

/*!
\fn virtual void tree::move(
        int const                       i_pos_x,
        int const                       i_pos_y)
\brief move the widget to a new position
\param[in] i_pos_x relative x position to move the widget
\param[in] i_pos_y relative y position to move the widget
\returns none
*/

/*
\fn virtual void tree::resize(
        unsigned int const              i_len_x,
        unsigned int const              i_len_y)
\brief resize the widget
\param[in] i_len_x new length of widget
\param[in] i_len_y new height of widget
\returns none

This method does not redraw the widget
*/

/*!
\var tree::m_root
	root treeitem (owned and managed by object)
*/

/*!
\var tree::m_selected
	selected treeitem 
*/

/*!
\var tree::m_signal_selected
	selected signal 
*/

/*!
\var tree::m_horizontal
	horizontal scrollbar
*/

/*!
\var tree::m_vertical
	vertical scrollbar
*/

/*!
\fn unsigned int tree::draw(
        treeitem *const                 io_item,
        unsigned int const              i_pos_x,
        unsigned int const              i_pos_y) const
\brief draw a treeitem
\param[in,out] io_item item to draw
\param[in] i_pos_x x position of level
\param[in] i_pos_y y position of level
\returns last y position
*/

/*!
\fn void tree::emit_selected()
\brief emit selected signal
\returns none
*/

/*!
\fn bool tree::event_hit(
        treeitem*const                  io_item,
        unsigned int const              i_pos_y)
\brief test if event is in item or it's children
\param[in,out] io_item item to test
\param[in] i_pos_y y position of event
\returns true event is in item
\returns false event is not in item

emits signal and toggles item open flag if event is in item or it's children.
*/

/*!
\fn void tree::key_down()
\brief handle key down event
*/

/*!
 \fn void tree::key_up()
\brief handle key up event
*/

/*!
\fn void tree::scrollbar_configure()
\brief configure horizontal and veritcal scrollbars
*/

/*!
\fn void tree::scrollbar_configure(
        unsigned int&                   io_height,
        unsigned int&                   io_width,
        treeitem const&                 i_item,
        unsigned int const              i_pos_y)
\brief configure horizontal and veritcal scrollbars
\param[in,out] io_height height tracker
\param[in,out] io_width width tracker
\param[in] i_item current item
\param[in] i_pos_y y position tracker
*/
