/*
 LISTBOX.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 listbox.hpp
\brief contains listbox class
*/

/*! \class listbox listbox.hpp
\brief Allows the user to choose a value from a list
*/

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

/*!
\fn listbox::listbox(
        int const                       i_pos_x,
        int const                       i_pos_y,
        unsigned int const              i_len_x,
        unsigned int const              i_len_y)
\brief constructor 
\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 virtual listbox::~listbox()
\brief destructor
\returns none
*/

/*!
\fn int listbox::add(
        unsigned char const*            i_label)
\brief adds a value to the end of a list
\param[in] i_label value to add
\returns 0 success
\returns !0 failure unable to add (out of memory)
*/

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

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

/*!
\fn virtual enum event_response listbox::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 listbox::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 unsigned char const* listbox::get_item(
        size_t const                    i_slot) const
\brief retrieve an item from the listbox
\param[in] i_slot index of item to retrieve
\returns 0 item not found
\returns !0 pointer to list item
*/

/*!
\fn size_t listbox::get_count() const
\brief get number of items in listbox
\returns the number of items in listbox
*/

/*!
\fn int listbox::get_selected_first() const
\brief get the first selected item in the listbox
\returns -1 nothing is selected
\returns >=0 index to the first selected item
*/

/*!
\fn int listbox::get_selected_next(
        int const                       i_iter) const
\brief get the next selected item in the listbox
\param[in] i_iter current index 
\returns  >=0 index to the next selected itm
\returns -1 there are no more selected items
*/

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

/*!
\fn virtual void listbox::resize(
        unsigned int const              i_len_x,
        unsigned int const              i_len_y)
\brief resize the widget
\param[in] i_len_x new horizontal length
\param[in] i_len_y new vertical length
\returns none
*/

/*!
\fn void listbox::remove(
        size_t const                    i_slot)
\brief remove an item from the listbox
\param[in] i_slot index of item to remove
\returns none
*/

/*!
\fn void listbox::remove_all()
\brief remove all items from the listbox
\returns none
*/

/*!
\fn void listbox::set_label(
        unsigned char const*            i_label)
\brief set the text label of the listbox
\param[in] i_label null terminated string of label
\returns none
To unset the label use NULL.
*/

/*!
\fn void listbox::set_multiline(
        bool const                      i_multiline)
\brief set whether or not the user can select more than one item
\param[in] i_multiline whether or not multiline is in affect
\returns none
*/

/*!
\fn virtual void listbox::set_parent(
        group*const                     i_parent)
\brief set the parent group of this widget
\returns none
*/

/*!
\fn void listbox::set_response(
        int const                       i_response)
\brief set the response the widget returns when an item is selected
\param[in] i_response response id
*/

/*!
\fn void listbox::set_signal_selected(
        signal_selected_t               i_signal)
\brief set callback
\param[in] i_signal callback signal
\returns none
*/

/*!
\fn void listbox::set_selected(
        size_t const                    i_slot,
        bool const                      i_selected=true)
\brief set an item as selected or unselected
\param[in] i_slot index of item to alter
\param[in] i_selected whether or not the item is selected
\returns none
Changing the state of an item will not emit a signal
*/

/*!
\fn void listbox::unselect_all()
\brief unselect all items in the listbox
\returns none
Changing the state will not emit a signal
*/

/*!
\var listbox::m_multiline
	Indicator if multi-selection is in affect
*/

/*!
\var listbox::m_line
	Index of currently highlighted item
*/

/*!
\var listbox::m_array
	Array to hold items
*/
	
/*!
\var listbox::m_vertical
	Vertical scrollbar
*/

/*!
\var listbox::m_label
	Label of listbox
*/

/*!
\var listbox::m_response
	Response returned when an item get's selected
*/

/*!
\var listbox::m_signal_selected
	Callback when an item gets's selected
*/

/*!
\fn void listbox::select(
        size_t const                    i_slot)
\brief selects an item 
\returns none
*/

/*!
\fn static void listbox::vertical_cb(
        widget const*                   i_widget,
        void*                           io_user_data)
\brief callback for vertical scrollbar
\param[in] i_widget scrollbar widget
\param[in] io_user_data listbox widget
\returns none
*/

/*!
\fn void listbox::vertical_configure()
\brief configure vertical scrollbar for display
\returns none
*/

/*!
\fn void listbox::emit_selected()
\brief emits the selected signal
\returns none
*/

/*!
\fn void listbox::scroll_internal()
\brief called when value in the vertical scrollbar changed
*/
