entry.dox 6.17 KB
Newer Older
Ercan Ersoy's avatar
Ercan Ersoy committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
/*
 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
*/