/*
vim:expandtab:softtabstop=4:tabstop=4:shiftwidth=4:nowrap:ruler
*/
/*
 TREEITEM.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 treeitem.hpp
\brief contains treeitem widget class
*/

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

A tree item, which consists of a label and possible children. A tree item
can be connected to other tree items to form a hierarchy.

Internal links such as \a m_parent, \a m_next and \a m_prev are deferred.
Once a tree has been created or modified, the links are set through a 
call to ::set_links. The ::tree class does this automatically when a root 
tree item is attached.

*/

/*!
\fn treeitem::treeitem(
        unsigned char const*            i_str,
        void *const                     io_user_data= 0)
\brief constructor - create a tree item
\param[in] i_str label of item
\param[in,out] io_user_data user defined data for signal
\returns none
*/

/*!
\fn bool treeitem::add(
        unsigned char const*            i_str,
        void *const                     io_user_data= 0)
\brief add a child item to the tree
\param[in] i_str label of item
\param[in,out] io_user_data user defined data for signal
\returns false item was not added (out of memory)
\returns true item was added to tree
*/

/*!
\fn bool treeitem::add(
        treeitem*const                  io_item)
\brief add a tree item (sibling) to tree
\param[in,out] io_item item to add
\returns false item was not added (out of memory)
\returns true item was added to tree

\a io_item will become owned by the tree. It must not already
be in the tree or anyother tree.
*/

/*!
\fn treeitem*const treeitem::next() const
\brief returns the next item
\returns 0 end of tree
\returns !0 pointer to next item
*/

/*!
\fn treeitem*const treeitem::prev() const
\brief returns the previous item
\returns 0 end of tree
\returns !0 pointer to previous item
*/

/*!
\fn static void treeitem::set_links(
        treeitem*const                  io_item,
        treeitem*const                  io_parent,
        treeitem*const                  io_prev,
        unsigned int const              i_level)
\brief sets linkage between tree items
\param[in,out] io_item tree item to link
\param[in,out] io_parent parent of tree item
\param[in,out] io_prev tree item the precedes io_item
\param[in] i_level level of tree item (0...N)
\returns none

Internal links such as \a m_parent, \a m_next and \a m_prev are deferred.
This routine will establish the relationship between tree items.

\code
	treeitem* root= new treeitem(reinterpret_cast<unsigned char const*>("ROOT"));
	root->add(reinterpret_cast<unsigned char const*>("1"));
	root->add(reinterpret_cast<unsigned char const*>("2"));
	treeitem* sibling= new treeitem(reinterpret_cast<unsigned char const*>("SIBLING"));
	sibling->add(reinterpret_cast<unsigned char const*>("1"));
	sibling->add(reinterpret_cast<unsigned char const*>("2"));
	root->add(sibling);

	treeitem::set_links(root, 0, 0, 0);
\endcode

*/

/*!
\fn virtual treeitem::~treeitem()
\brief destructor
*/

/*!
\var treeitem::m_open
	indicator if item is open or closed
*/

/*!
\var treeitem::m_text
	label text
*/

/*!
\var treeitem::m_len
	length of m_text
*/

/*!
\var treeitem::m_pos_y
	y position of tree item
*/

/*!
\var treeitem::m_user_data
	user data
*/

/*!
\var treeitem::m_child
	array of child tree items
*/

/*!
\var treeitem::m_parent
	parent 
*/

/*!
\var treeitem::m_next
	next item 
*/

/*!
\var treeitem::m_prev
	previous item
*/

/*!
\var treeitem::m_level
	level/depth of tree item
*/

