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

/*! \class edit edit.hpp
\brief Multi-line edit widget
*/

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

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

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

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

/*!
\fn unsigned char const __FAR* edit::get_text()
\brief get the text buffer
\returns 0 buffer empty
\returns !0 address of buffer
*/

/*!
\fn size_t edit::get_text_length() const
\brief get the number of used bytes in the buffer
\returns >=0 number of bytes used in buffer
*/

/*!
\var edit::m_caret_x
	x location of caret
*/

/*!
\var edit::m_caret_y
	y location of caret
*/

/*!
\var edit::m_sticky_caret_x
	x location of longest x caret position. Used to position caret on 
	up/down operations.
*/

/*!
\var edit::m_cursor
	current position in buffer
*/

/*!
\var edit::m_offset_x
	horizontal scroll position/offset	
*/

/*!
\var edit::m_line_top
	visible top line (vertical scroll)
*/

/*!
\var edit::m_line_top_offset
	cursor position of top line
*/

/*!
\var edit::m_lines
	total number of lines
*/

/*!
\var edit::m_gap
	gap buffer
*/


/*!
\fn void edit::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 bool edit::char_backspace()
\brief backspace
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::char_delete()
\brief delete character
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::char_insert(
        unsigned char const             i_char,
        enum cursor_mode const          i_cursor_mode)
\brief insert character
\param[in] i_char character to insert
\param[in] i_cursor_mode mode to insert (overwrite, insert)
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::char_insert_newline()
\brief insert new line character
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::cursor_down()
\brief move cursor down a line
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::cursor_end()
\brief move cursor to end of line
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::cursor_home()
\brief move cursor to end of line
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::cursor_left()
\brief move cursor left
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::cursor_right()
\brief move cursor right
\returns false does not require a redraw
\returns true requires a redraw
*/

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

/*!
\fn bool edit::cursor_up()
\brief move cursor up a line
\returns false does not require a redraw
\returns true requires a redraw
*/

/*!
\fn bool edit::move_to_offset_x(
        unsigned char __FAR*&           io_ptr,
        size_t&                         io_offset,
        int&                            io_pos_y) const
\brief move to m_offset_x cursor position
\param[in,out] io_ptr buffer address
\param[in,out] io_offset cursor position
\param[in,out] io_pos_y y position
\returns false move not valid
\returns true move was valid
*/
