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

/*! \class entry entry.hpp
\brief Allows a user to enter text.
*/


/*!
\typedef void (*entry::signal_changed_t)(
        entry const*                    i_entry,
        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
As of this writing, a signal is not emitted
*/

/*!
\enum entry::purpose
\brief indicator of the type of input the entry can accept

\var entry::purpose entry::PURPOSE_ANY
	Accept any type of input

\var entry::purpose entry::PURPOSE_ALPHA
	Accept only alphabetic characters 

\var entry::purpose entry::PURPOSE_DIGIT
	Accept only numeric characters

\var entry::purpose entry::PURPOSE_INTEGER
	Accept only numeric characters and also the negative ('-')
	character

\var entry::purpose entry::PURPOSE_FLOAT
	Accept only numeric characters and also the 
	plus ('+'), negative ('-'), period ('.'), and exponent ('E' or 'e')	
	character
*/

/*!
\fn entry::entry(
        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 entry::~entry()
\brief destructor
\returns none
*/

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

This method should not be called directly. 
\see widget::draw for details.
*/
    
/*!
\fn virtual enum event_response entry::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 void entry::focus_enter()
\brief handle entering focus
\returns none
*/

/*!
\fn virtual void entry::focus_leave()
\brief handle leaving focus
\returns none
*/

/*!
\fn  unsigned char const* entry::get_text() const
\brief get text buffer
\returns pointer to a null terminated text buffer

This routine will not return a null pointer. However,
the buffer itself could be empty.
*/

/*!
\fn size_t entry::get_text_length() const
\brief get the number of characters in the text buffer
\returns number of characters in the text buffer
*/

/*!
\fn enum purpose entry::get_purpose() const
\brief get the text entry purpose
\returns purpose
*/

/*!
\fn void entry::set_editable(
        bool const                      i_editable=true)
\brief set whether or not the entry is editable
\param[in] i_editable indicator if the user can edit the entry
\returns none
*/

/*!
\fn void entry::set_purpose(
        enum purpose const              i_purpose)
\brief set the input purpose 
\param[in] i_purpose input purpose
\returns none
*/

/*!
\fn void entry::set_text(
        unsigned char const*            i_str)
\brief set the text of the entry
\param[in] i_str null terminated string to set the entry too
\returns none
*/

/*!
\fn void entry::set_signal_changed(
        signal_changed_t                i_signal)
\brief set callback
\param[in] i_signal callback signal
\returns none
As of this writing, a signal is not emitted
*/

/*!
\var entry::m_purpose
	input purpose
*/

/*!
\var entry::m_caret
	cursor position (limited to length of entry)
*/

/*!
\var entry::m_offset
	horizontal scroll position/offset
*/

/*!
\var entry::m_slot
	physical cursor position (0..m_length)
*/

/*!
\var entry::m_length
	number of actual characters in buffer
*/

/*!
\var entry::m_block_size
	size of the memory block
*/

/*!
\var entry::m_block
	memory block/text buffer to hold content
*/

/*!
\var entry::m_editable
	indicator if text widget is editable
*/

/*!
\var entry::m_signal_changed
	signal to emit when entry has changed.
	as of this writing, a signal is not emitted
*/

/*!
\fn void entry::show_cursor()
\brief sets the cursor type/shape. Cursor shape depends on
the state of the cursor (insert/overwrite) and widget itself.
\returns none
*/

/*!
\fn void entry::grow(
        size_t const                    i_needed)
\brief grow internal buffer
\param[in] i_needed requested buffer size
\returns none
The memory block allocated is twice the size of the request.
If the buffer is already big enough to hold the request,
nothing happens.
\returns none
*/

/*!
\fn virtual void entry::get_bbox(
        struct box&                     o_bbox) const
\brief get the inner bounding box
param[out] o_bbox bounding box to fill
\returns none
This will return the normal widget box m_box

Combobox and spinner overrides this method so a down button can be
displayed.

*/

/*!
\fn int entry::pos_inc()
\brief increments position (m_caret, m_slot, m_offset)
\returns none
*/

/*!
\fn int entry::pos_dec()
\brief decrements position (m_caret, m_slot, m_offset)
\returns none
*/

/*!
\fn void entry::del()
\brief delete character at current position from the buffer
\returns none

Characters to the right of the cursor are shifted left.
*/

/*!
\fn void entry::ins(
        unsigned char const             i_char)
\brief insert character at current position into the buffer
\param[in] i_char character to insert
\returns none

Characters at the cursor position are shifted right, and then
the character is inserted.
*/

/*!
\fn void entry::ovw(
        unsigned char const             i_char)
\brief insert character at current position into the buffer
\param[in] i_char character to insert
\returns none

The character at the cursor position is replaced.
*/

/*!
\fn bool entry::validate(
        unsigned char const             i_char)
\brief validates a character against the widgets purpose
\param[in] i_char character to validate
\returns none
*/

/*!
\fn void entry::caret_set_position() const
\brief moves the cursor to the current position (m_caret)
\returns none

This routine does not alter the shape or visibility
*/

/*!
\fn void entry::emit_changed()
\brief emit the changed signal
\returns none
*/

