diff options
| -rw-r--r-- | CHANGES | 1 | ||||
| -rw-r--r-- | FL/Fl.H | 44 | ||||
| -rw-r--r-- | FL/Fl_Input_.H | 347 | ||||
| -rw-r--r-- | FL/Fl_Preferences.H | 3 | ||||
| -rw-r--r-- | FL/fl_draw.H | 2 | ||||
| -rw-r--r-- | FL/fl_types.h | 2 | ||||
| -rw-r--r-- | FL/fl_utf8.h | 3 | ||||
| -rw-r--r-- | src/Fl_Input_.cxx | 337 | ||||
| -rw-r--r-- | src/fl_utf.c | 4 |
9 files changed, 556 insertions, 187 deletions
@@ -1,5 +1,6 @@ CHANGES IN FLTK 1.3.0 + - Updated documentation for Fl_Input_ - Fixed fl_draw_image to obey the alpha channel, hoping that this has no adverse effect on existing software (OS X only) - Added OS X cursor control to Fl_Input (STR #2169) @@ -852,29 +852,29 @@ public: These functions support deletion of widgets inside callbacks. - Fl::delete_widget() should be called when deleting widgets - or complete widget trees (Fl_Group, Fl_Window, ...) inside + \c Fl::delete_widget() should be called when deleting widgets + or complete widget trees (\c Fl_Group, \c Fl_Window, ...) inside callbacks. The other functions are intended for internal use. The preferred - way to use them is by using the helper class Fl_Widget_Tracker. + way to use them is by using the helper class \c Fl_Widget_Tracker. The following is to show how it works ... There are three groups of related methods: -# scheduled widget deletion - - Fl::delete_widget() schedules widgets for deletion - - Fl::do_widget_deletion() deletes all scheduled widgets + - \c Fl::delete_widget() schedules widgets for deletion + - \c Fl::do_widget_deletion() deletes all scheduled widgets -# widget watch list ("smart pointers") - - Fl::watch_widget_pointer() adds a widget pointer to the watch list - - Fl::release_widget_pointer() removes a widget pointer from the watch list - - Fl::clear_widget_pointer() clears a widget pointer \e in the watch list + - \c Fl::watch_widget_pointer() adds a widget pointer to the watch list + - \c Fl::release_widget_pointer() removes a widget pointer from the watch list + - \c Fl::clear_widget_pointer() clears a widget pointer \e in the watch list -# the class Fl_Widget_Tracker: - - the constructor calls Fl::watch_widget_pointer() - - the destructor calls Fl::release_widget_pointer() + - the constructor calls \c Fl::watch_widget_pointer() + - the destructor calls \c Fl::release_widget_pointer() - the access methods can be used to test, if a widget has been deleted - \see Fl_Widget_Tracker. + \see \c Fl_Widget_Tracker. @{ */ // Widget deletion: @@ -937,11 +937,11 @@ public: /** This class should be used to control safe widget deletion. - You can use an Fl_Widget_Tracker object to watch another widget, if you + You can use an \c Fl_Widget_Tracker object to watch another widget, if you need to know, if this widget has been deleted during a callback. This simplifies the use of the "safe widget deletion" methods - Fl::watch_widget_pointer() and Fl::release_widget_pointer() and + \c Fl::watch_widget_pointer() and \c Fl::release_widget_pointer() and makes their use more reliable, because the destructor autmatically releases the widget pointer from the widget watch list. @@ -950,7 +950,7 @@ public: scope is left. This ensures that no stale widget pointers are left in the widget watch list (see example below). - You can also create Fl_Widget_Tracker objects with \e \b new, but then it + You can also create \c Fl_Widget_Tracker objects with \c new, but then it is your responsibility to delete the object (and thus remove the widget pointer from the watch list) when it is not needed any more. @@ -984,31 +984,31 @@ public: ~Fl_Widget_Tracker(); /** - returns a pointer to the watched widget. + Returns a pointer to the watched widget. - This pointer is NULL, if the widget has been deleted. + This pointer is \c NULL, if the widget has been deleted. */ Fl_Widget *widget() {return wp_;} /** - returns 1, if the watched widget has been deleted. + Returns 1, if the watched widget has been deleted. This is a convenience method. You can also use something like - if (wp.widget() == 0) // ... + <tt> if (wp.widget() == 0) // ...</tt> - where \e \b wp is an Fl_Widget_Tracker object. + where \p wp is an \c Fl_Widget_Tracker object. */ int deleted() {return wp_ == 0;} /** - returns 1, if the watched widget exists (has not been deleted). + Returns 1, if the watched widget exists (has not been deleted). This is a convenience method. You can also use something like - if (wp.widget() != 0) // ... + <tt> if (wp.widget() != 0) // ...</tt> - where \e \b wp is an Fl_Widget_Tracker object. + where \p wp is an \c Fl_Widget_Tracker object. */ int exists() {return wp_ != 0;} diff --git a/FL/Fl_Input_.H b/FL/Fl_Input_.H index dbddbd895..d63503f91 100644 --- a/FL/Fl_Input_.H +++ b/FL/Fl_Input_.H @@ -50,14 +50,17 @@ #define FL_MULTILINE_OUTPUT_WRAP (FL_MULTILINE_INPUT | FL_INPUT_READONLY | FL_INPUT_WRAP) /** - This is a virtual base class below Fl_Input. It has all - the same interfaces, but lacks the handle() and - draw() method. You may want to subclass it if you are + This class provides a low-overhead text input field. + + This is a virtual base class below \c Fl_Input. It has all + the same interfaces, but lacks the \c handle() and + \c draw() method. You may want to subclass it if you are one of those people who likes to change how the editing keys - work. + work. It may also be useful for adding scrollbars + to the input field. - <P>This can act like any of the subclasses of Fl_Input, by - setting type() to one of the following values:</P> + This can act like any of the subclasses of \c Fl_Input, by + setting \c type() to one of the following values: \code #define FL_NORMAL_INPUT 0 @@ -73,202 +76,364 @@ #define FL_MULTILINE_INPUT_WRAP (FL_MULTILINE_INPUT | FL_INPUT_WRAP) #define FL_MULTILINE_OUTPUT_WRAP (FL_MULTILINE_INPUT | FL_INPUT_READONLY | FL_INPUT_WRAP) \endcode + + \see \c Fl_Text_Display, \c Fl_Text_Editor for more powerful text handling widgets */ class FL_EXPORT Fl_Input_ : public Fl_Widget { + /** \internal Storage for the text field. */ const char* value_; + + /** \internal Buffer memory for expanded text. \see expand() */ char* buffer; + /** \internal Size of text in bytes in the \p value_ field. */ int size_; + + /** \internal Please document me! */ int bufsize; + + /** \internal Positin of the cursor in the document */ int position_; + + /** \internal Position of the other and of the selected text. If \p position_ equals + \p mark_, no text is selected */ int mark_; + + /** \internal Offset to text origin within wdget bounds */ int xscroll_, yscroll_; + + /** \internal Minimal update pointer. Display requirs redraw from here to the end + of the buffer. */ int mu_p; + + /** \internal Maximum size of buffer. \todo Is this really needed? */ int maximum_size_; + + /** \internal Shorcut key that will get this widget the focus. */ int shortcut_; + /** \internal This is set if no text but only the cursor needs updating. */ uchar erase_cursor_only; + + /** \internal The font used for the entire text. */ Fl_Font textfont_; + + /** \internal Height of the font used for the entire text. */ Fl_Fontsize textsize_; + + /** \internal color of the entire text */ unsigned textcolor_; + + /** \internal color of the text cursor */ unsigned cursor_color_; + /** \internal Horizontal cursor position in pixels while movin up or down. */ + static double up_down_pos; + + /** \internal Flag to remeber last cursor move. */ + static int was_up_down; + + /* Convert a given text segment into the text that will be rendered on screen. */ const char* expand(const char*, char*) const; + + /* Calculates the width in pixels of part of a text buffer. */ double expandpos(const char*, const char*, const char*, int*) const; + + /* Mark a range of characters for update. */ void minimal_update(int, int); + + /* Mark a range of characters for update. */ void minimal_update(int p); + + /* Copy the value from a possibly static entry into the internal buffer. */ void put_in_buffer(int newsize); + /* Set the current font and font size. */ void setfont() const; protected: + /* Finds the start of a word. */ int word_start(int i) const; + + /* Finds the end of a word. */ int word_end(int i) const; + + /* Finds the start of a line. */ int line_start(int i) const; + + /* Finds the end of a line. */ int line_end(int i) const; + + /* Draw the text in the passed bounding box. */ void drawtext(int, int, int, int); + + /* Move the cursor to the column given by up_down_pos. */ int up_down_position(int, int keepmark=0); + + /* Handle mouse clicks and mose moves. */ void handle_mouse(int, int, int, int, int keepmark=0); + + /* Handle all kinds of text field related events. */ int handletext(int e, int, int, int, int); + + /* Check the when() field and do a callback if indicated. */ void maybe_do_callback(); + + /** \internal Horizontal offset of text to left edge of widget. */ int xscroll() const {return xscroll_;} + + /** \internal Vertical offset of text to top edge of widget. */ int yscroll() const {return yscroll_;} + /* Return the number of lines displayed on a single page. */ + int linesPerPage(); + public: + /* Change the size of the widget. */ void resize(int, int, int, int); + /* Creator */ Fl_Input_(int, int, int, int, const char* = 0); + + /* Destructor */ ~Fl_Input_(); + /* Changes the widget text. */ int value(const char*); + + /* Changes the widget text. */ int value(const char*, int); + + /* Changes the widget text. */ int static_value(const char*); + + /* Changes the widget text. */ int static_value(const char*, int); + /** - The first form returns the current value, which is a pointer + Returns the text displayed in the widget. + + This function returns the current value, which is a pointer to the internal buffer and is valid only until the next event is handled. - - <P>The second two forms change the text and set the mark and the - point to the end of it. The string is copied to the internal - buffer. Passing NULL is the same as "". - This returns non-zero if the new value is different than the - current one. You can use the second version to directly set the - length if you know it already or want to put nul's in the - text. + + \return pointer to an internal buffer - do not \c free() this + \see \c Fl_Input_::value(const char*) */ const char* value() const {return value_;} + /** - Same as value()[n], but may be faster in plausible - implementations. No bounds checking is done. + Returns the character at index \p i. + + This function returns the utf8 character that is closest to \p i + as a ucs4 character code. + + \param [in] i index into the value field + \return the character at index \p i + \todo Not yet utf8 aware */ char index(int i) const {return value_[i];} + /** - Returns the number of characters in value(). This - may be greater than strlen(value()) if there are nul - characters in it. + Returns the number of bytes in \c value(). + + This may be greater than <tt>strlen(value())</tt> if there are + \c nul characters in the text. + + \return number of bytes in the text */ int size() const {return size_;} + + /** Sets the width and height of this widget. + \param [in] W, H new width and height + \see \c Fl_Widget::size(int, int) */ void size(int W, int H) { Fl_Widget::size(W, H); } - /** Gets the maximum length of the input field. */ + + /** Gets the maximum length of the input field. + \todo It is not clear if this function is actually required */ int maximum_size() const {return maximum_size_;} - /** Sets the maximum length of the input field. */ + + /** Sets the maximum length of the input field. + \todo It is not clear if this function is actually required */ void maximum_size(int m) {maximum_size_ = m;} - /** - The input widget maintains two pointers into the string. The - "position" is where the cursor is. The - "mark" is the other end of the selected text. If they - are equal then there is no selection. Changing this does not - affect the clipboard (use copy() to do that). - - <P>Changing these values causes a redraw(). The new - values are bounds checked. The return value is non-zero if the - new position is different than the old one. position(n) - is the same as position(n,n). mark(n) is the - same as position(position(),n). + + /** Gets the position of the text cursor. + \return the cursor position as an index + \see \c position(int, int) */ int position() const {return position_;} - /** Gets the current selection mark. mark(n) is the same as position(position(),n).*/ + + /** Gets the current selection mark. + \return index into the text */ int mark() const {return mark_;} + + /* Sets the index for the cursor and mark. */ int position(int p, int m); - /** See int Fl_Input_::position() const */ + + /** Set the cursor position and mark. + \c position(n) is the same as <tt>position(n, n)</tt>. + \param p new index for cursor and mark + \return \c 0 if no positions changed + \see \c position(int, int), \c position(), \c mark(int) + */ int position(int p) {return position(p, p);} - /** Sets the current selection mark. mark(n) is the same as position(position(),n).*/ + + /** Sets the current selection mark. + \c mark(n) is the same as <tt>position(position(),n)</tt>. + \param m new index of the mark + \return \c 0 if the mark did not change + \see \c position(), \c position(int, int) */ int mark(int m) {return position(position(), m);} + + /* Deletes text from b to e and inserts the new string text. */ int replace(int, int, const char*, int=0); + /** Deletes the current selection. - cut(n) deletes n characters after the - position(). cut(-n) deletes n - characters before the position(). cut(a,b) - deletes the characters between offsets a and - b. A, b, and n are all - clamped to the size of the string. The mark and point are left - where the deleted text was. - - <P>If you want the data to go into the clipboard, do - Fl_Input_::copy() before calling - Fl_Input_::cut(), or do Fl_Input_::copy_cuts() - afterwards. + + This function deletes the currently selected text + \e without storing it in the clipboard. To use the clipboard, + you may call \c copy() first or \c copy_cuts() after + this call. + + \return \c 0 if no data was copied */ int cut() {return replace(position(), mark(), 0);} - /** See int Fl_Input_::cut() */ + + /** + Deletes the next \p n bytes rounded to characters before or after the cursor. + + This function deletes the currently selected text + \e without storing it in the clipboard. To use the clipboard, + you may call \c copy() first or \c copy_cuts() after + this call. + + \param n number of bytes rounded to full characters and clamped to the buffer. + A negative number will cut characters to the left of the cursor. + \return \c 0 if no data was copied + */ int cut(int n) {return replace(position(), position()+n, 0);} - /** See int Fl_Input_::cut() */ + + /** + Deletes all characters between index \p a and \p b. + + This function deletes the currently selected text + \e without storing it in the clipboard. To use the clipboard, + you may call \c copy() first or \c copy_cuts() after + this call. + + \param a, b range of bytes rounded to full characters and clamped to the buffer + \return \c 0 if no data was copied + */ int cut(int a, int b) {return replace(a, b, 0);} + /** - Insert the string t at the current position, and - leave the mark and position after it. If l is not zero - then it is assumed to be strlen(t). + Inserts text at the cursor position. + + This function inserts the string in \p t at the cursor + \c position() and moves the new position and mark to + the end of the inserted text. + + \param [in] t text that will be inserted + \param [in] l length of text, or \c 0 if the string is terminated by \c NUL. + \return \c 0 if no text was inserted */ int insert(const char* t, int l=0){return replace(position_, mark_, t, l);} + + /* Put the current selection into the clipboard. */ int copy(int clipboard); + + /* Undo previous changes to the text buffer. */ int undo(); + + /* Copy the yank buffer to the clipboard. */ int copy_cuts(); - /** - The first form returns the current shortcut key for the Input. - <P>The second form sets the shortcut key to key. Setting this - overrides the use of '&' in the label(). The value is a bitwise - OR of a key and a set of shift flags, for example FL_ALT | 'a' - , FL_ALT | (FL_F + 10), or just 'a'. A value - of 0 disables the shortcut. </P> - <P>The key can be any value returned by - Fl::event_key(), but will usually be an ASCII letter. Use - a lower-case letter unless you require the shift key to be held down. </P> - <P>The shift flags can be any set of values accepted by - Fl::event_state(). If the bit is on that shift key must - be pushed. Meta, Alt, Ctrl, and Shift must be off if they are not in - the shift flags (zero for the other bits indicates a "don't care" - setting). - */ + /** Return the shortcut key associtaed with this widget. + \return shortcut keystroke + \see Fl_Button::shortcut() */ int shortcut() const {return shortcut_;} - /** See int shortcut() const */ + + /** + Sets the shortcut key associtaed with this widget. + Pressing the shortcut key gives text editing focus to this widget. + \param [in] s new shortcut keystroke + \see Fl_Button::shortcut() + */ void shortcut(int s) {shortcut_ = s;} - /** Gets the font of the text in the input field.*/ + /** Gets the font of the text in the input field. + \return the current \c Fl_Font index */ Fl_Font textfont() const {return textfont_;} - /** Sets the font of the text in the input field.*/ + + /** Sets the font of the text in the input field. + The text font defaults to \c FL_HELVETICA. + \param [in] s the new text font */ void textfont(Fl_Font s) {textfont_ = s;} - /** Gets the size of the text in the input field.*/ + + /** Gets the size of the text in the input field. + \return the text height in pixels */ Fl_Fontsize textsize() const {return textsize_;} - /** Sets the size of the text in the input field.*/ + + /** Sets the size of the text in the input field. + The text height defaults to \c FL_NORMAL_SIZE. + \param [in] s the new font height in pixel units */ void textsize(Fl_Fontsize s) {textsize_ = s;} - /** Gets the color of the text in the input field.*/ + + /** Gets the color of the text in the input field. + \return the text color + \see \c textcolor(unsigned) */ Fl_Color textcolor() const {return (Fl_Color)textcolor_;} - /** Sets the color of the text in the input field.*/ + + /** Sets the color of the text in the input field. + The text color defaults to \c FL_FOREGROUND_COLOR. + \param [in] n new text color + \see \c textcolor() */ void textcolor(unsigned n) {textcolor_ = n;} - /** Gets the color of the cursor. This is black by default.*/ + + /** Gets the color of the cursor. + \return the current cursor color */ Fl_Color cursor_color() const {return (Fl_Color)cursor_color_;} - /** Sets the color of the cursor. This is black by default.*/ + + /** Sets the color of the cursor. + The default color for the cursor is \c FL_BLACK. + \param [in] n the new cursor color */ void cursor_color(unsigned n) {cursor_color_ = n;} - /** Gets the input field type. */ + + /** Gets the input field type. + \return the current input type */ int input_type() const {return type() & FL_INPUT_TYPE; } - /** Sets the input field type. */ + + /** Sets the input field type. + A \c redraw() is required to reformat the input field. + \param [in] t new input type */ void input_type(int t) { type((uchar)(t | readonly())); } - /** Gets the read-only state of the input field. */ + + /** Gets the read-only state of the input field. + \return non-zero if this widget is read-only */ int readonly() const { return type() & FL_INPUT_READONLY; } - /** Sets the read-only state of the input field. */ + + /** Sets the read-only state of the input field. + \param [in] b if \p b is \c 0, the text in this widget can be edited by the user */ void readonly(int b) { if (b) type((uchar)(type() | FL_INPUT_READONLY)); else type((uchar)(type() & ~FL_INPUT_READONLY)); } + /** - Gets the word wrapping state of the input field. Word - wrap is only functional with multi-line input fields. + Gets the word wrapping state of the input field. + Word wrap is only functional with multi-line input fields. */ int wrap() const { return type() & FL_INPUT_WRAP; } + /** - Sets the word wrapping state of the input field. Word - wrap is only functional with multi-line input fields. + Sets the word wrapping state of the input field. + Word wrap is only functional with multi-line input fields. */ void wrap(int b) { if (b) type((uchar)(type() | FL_INPUT_WRAP)); else type((uchar)(type() & ~FL_INPUT_WRAP)); } - /** - Return the number of lines displayed on a single page. - */ - int linesPerPage(); + }; #endif diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H index e0cf1ed7c..eba771aee 100644 --- a/FL/Fl_Preferences.H +++ b/FL/Fl_Preferences.H @@ -148,7 +148,8 @@ public: operator const char *() { return data_; } ~Name(); }; - /** An entry associates a preference name to its corresponding value */ + + /** \internal An entry associates a preference name to its corresponding value */ struct Entry { char *name, *value; diff --git a/FL/fl_draw.H b/FL/fl_draw.H index 5ec841200..f0af55781 100644 --- a/FL/fl_draw.H +++ b/FL/fl_draw.H @@ -223,7 +223,7 @@ FL_EXPORT double fl_width(const char* txt, int n); /** Return the typographical width of a single character : \note if a valid fl_gc is NOT found then it uses the first window gc, or the screen gc if no fltk window is available when called. */ -FL_EXPORT double fl_width(Fl_Unichar); +FL_EXPORT double fl_width(Fl_Char); /** Determine the minimum pixel dimensions of a nul-terminated string. Usage: given a string "txt" drawn using fl_draw(txt, x, y) you would determine diff --git a/FL/fl_types.h b/FL/fl_types.h index e88cc6318..e676a621e 100644 --- a/FL/fl_types.h +++ b/FL/fl_types.h @@ -52,7 +52,7 @@ typedef char *Fl_String; typedef const char *Fl_CString; /** 24-bit Unicode character + 8-bit indicator for keyboard flags */ -typedef unsigned int Fl_Unichar; +typedef unsigned int Fl_Char; /*@}*/ /* group: Miscellaneous */ diff --git a/FL/fl_utf8.h b/FL/fl_utf8.h index 3440bd727..e7bc9010a 100644 --- a/FL/fl_utf8.h +++ b/FL/fl_utf8.h @@ -87,9 +87,6 @@ extern "C" { @{ */ -/** is this even defined anywhere? */ -int fl_unichar_to_utf8_size(Fl_Unichar); - /* F2: comes from FLTK2 */ /* OD: comes from OksiD */ diff --git a/src/Fl_Input_.cxx b/src/Fl_Input_.cxx index 1e74c309a..cd853fafe 100644 --- a/src/Fl_Input_.cxx +++ b/src/Fl_Input_.cxx @@ -25,19 +25,6 @@ // http://www.fltk.org/str.php // -/** FIXME DOX: APIs not found - fn int Fl_Input_::wordboundary(int i) const - Returns true if position i is at the start or end of a word. - - fn int Fl_Input_::lineboundary(int i) const - Returns true if position i is at the start or end of a line. - -*/ -// This is the base class for Fl_Input. You can use it directly -// if you are one of those people who like to define their own -// set of editing keys. It may also be useful for adding scrollbars -// to the input field. - #include <FL/Fl.H> #include <FL/Fl_Input_.H> #include <FL/Fl_Window.H> @@ -55,9 +42,19 @@ extern void fl_draw(const char*, int, float, float); //////////////////////////////////////////////////////////////// -// Copy string p..e to the buffer, replacing characters with ^X and \nnn -// as necessary. Truncate if necessary so the resulting string and -// null terminator fits in a buffer of size n. Return new end pointer. +/** \internal + Convert a given text segment into the text that will be rendered on screen. + + Copy the text from \p p to \p buf, replacing charcters with <tt>^X</tt> + and <tt>\\nnn</tt> as necessary. + + The destination buffer is limited to \c MAXBUF (currently at 1024). All + following text is truncated. + + \param [in] p pointer to source buffer + \param [in] buf pointer to destination buffer + \return pointer to the end of the destination buffer +*/ const char* Fl_Input_::expand(const char* p, char* buf) const { char* o = buf; char* e = buf+(MAXBUF-4); @@ -108,7 +105,17 @@ const char* Fl_Input_::expand(const char* p, char* buf) const { return p; } -// After filling in such a buffer, find the width to e +/** \internal + Calculates the width in pixels of part of a text buffer. + + This call takes a string, usually created by expand, and calculates + the width of the string when rendered with the give font. + + \param [in] p pointer to the start of the original string + \param [in] e pointer to the end of the original string + \param [in] buf pointer to the buffer as returned by \c expand() + \return width of string in pixels +*/ double Fl_Input_::expandpos( const char* p, // real string const char* e, // pointer into real string @@ -141,12 +148,20 @@ double Fl_Input_::expandpos( //////////////////////////////////////////////////////////////// -// minimal update: -// Characters from mu_p to end of widget are redrawn. -// If erase_cursor_only, small part at mu_p is redrawn. -// Right now minimal update just keeps unchanged characters from -// being erased, so they don't blink. +/** \internal + Mark a range of characters for update. + + This call marks all characters from \p to the end of the + text buffer for update. At least these chracters + will be redrawn in the next update cycle. + + Characters from \p mu_p to end of widget are redrawn. + If \p erase_cursor_only, small part at \p mu_p is redrawn. + Right now minimal update just keeps unchanged characters from + being erased, so they don't blink. + \param [in] p start of update range +*/ void Fl_Input_::minimal_update(int p) { if (damage() & FL_DAMAGE_ALL) return; // don't waste time if it won't be done if (damage() & FL_DAMAGE_EXPOSE) { @@ -159,6 +174,15 @@ void Fl_Input_::minimal_update(int p) { erase_cursor_only = 0; } +/** \internal + Mark a range of characters for update. + + This call marks a text range for update. At least all chracters + from \p p to \p q will be redrawn in the next update cycle. + + \param [in] p start of update range + \param [in] q end of update range +*/ void Fl_Input_::minimal_update(int p, int q) { if (q < p) p = q; minimal_update(p); @@ -166,18 +190,27 @@ void Fl_Input_::minimal_update(int p, int q) { //////////////////////////////////////////////////////////////// -static double up_down_pos; -static int was_up_down; +/* Horizontal cursor position in pixels while movin up or down. */ +double Fl_Input_::up_down_pos = 0; + +/* Flag to remeber last cursor move. */ +int Fl_Input_::was_up_down = 0; +/** + Set the current font and font size. +*/ void Fl_Input_::setfont() const { - fl_font(textfont(), textsize()); + fl_font(textfont(), textsize()); } /** - Draw the text in the passed bounding box. If damage() - & FL_DAMAGE_ALL is true, this assumes the area has - already been erased to color(). Otherwise it does + Draw the text in the passed bounding box. + + If <tt>damage() & FL_DAMAGE_ALL</tt> is true, this assumes the + area has already been erased to \c color(). Otherwise it does minimal update and erases the area itself. + + \param X, Y, W, H area that must be redrawn */ void Fl_Input_::drawtext(int X, int Y, int W, int H) { int do_mu = !(damage()&FL_DAMAGE_ALL); @@ -357,10 +390,24 @@ void Fl_Input_::drawtext(int X, int Y, int W, int H) { } } +/** \internal + Simple function that determins if a charcter could be part of a word. + \todo This function is not ucs4-aware. +*/ static int isword(char c) { return (c&128 || isalnum(c) || strchr("#%&-/@\\_~", c)); } +/** + Finds the end of a word. + + This call calculates the end of a word based on the given + index \p i. Calling this function repeatedly will move + forwards to the end of the text. + + \param [in] i starting index for the search + \return end of the word +*/ int Fl_Input_::word_end(int i) const { if (input_type() == FL_SECRET_INPUT) return size(); //while (i < size() && !isword(index(i))) i++; @@ -369,6 +416,16 @@ int Fl_Input_::word_end(int i) const { return i; } +/** + Finds the start of a word. + + This call calculates the start of a word based on the given + index \p i. Calling this function repeatedly will move + backwards to the beginning of the text. + + \param [in] i starting index for the search + \return start of the word +*/ int Fl_Input_::word_start(int i) const { if (input_type() == FL_SECRET_INPUT) return 0; // if (i >= size() || !isword(index(i))) @@ -378,6 +435,15 @@ int Fl_Input_::word_start(int i) const { return i; } +/** + Finds the end of a line. + + This call calculates the end of a line based on the given + index \p i. + + \param [in] i starting index for the search + \return end of the line +*/ int Fl_Input_::line_end(int i) const { if (input_type() != FL_MULTILINE_INPUT) return size(); @@ -399,6 +465,15 @@ int Fl_Input_::line_end(int i) const { } } +/** + Finds the start of a line. + + This call calculates the start of a line based on the given + index \p i. + + \param [in] i starting index for the search + \return start of the line +*/ int Fl_Input_::line_start(int i) const { if (input_type() != FL_MULTILINE_INPUT) return 0; int j = i; @@ -415,6 +490,10 @@ int Fl_Input_::line_start(int i) const { } else return j; } +/** + Handle mouse clicks and mouse moves. + \todo Add comment and parameters +*/ void Fl_Input_::handle_mouse(int X, int Y, int /*W*/, int /*H*/, int drag) { was_up_down = 0; if (!size()) return; @@ -488,7 +567,23 @@ void Fl_Input_::handle_mouse(int X, int Y, int /*W*/, int /*H*/, int drag) { position(newpos, newmark); } -/** See int Fl_Input_::position() const */ +/** + Sets the index for the cursor and mark. + + The input widget maintains two pointers into the string. The + \e position is where the cursor is. The + \e mark is the other end of the selected text. If they + are equal then there is no selection. Changing this does not + affect the clipboard (use \c copy() to do that). + + Changing these values causes a \c redraw(). The new + values are bounds checked. + + \param p index for the cursor position + \param m index for the mark + \return \c 0 if no positions changed + \see \c position(int), \c position(), \c mark(int) +*/ int Fl_Input_::position(int p, int m) { int is_same = 0; was_up_down = 0; @@ -538,10 +633,16 @@ int Fl_Input_::position(int p, int m) { } /** - Do the correct thing for arrow keys. Sets the position (and - mark if <I>keepmark</I> is zero) to somewhere in the same line - as <I>i</I>, such that pressing the arrows repeatedly will cause - the point to move up and down. + Move the cursor to the column given by \p up_down_pos. + + This function is helpful when implementing up and down + cursor movement. It moves the cursor from the beginning + of a line to the column indicated by the global variable + \p up_down_pos in pixel units. + + \param [in] i index into the beginning of a line of text + \param [in] keepmark if set, move only the cursor, but not the mark + \return index to new cursor position */ int Fl_Input_::up_down_position(int i, int keepmark) { // unlike before, i must be at the start of the line already! @@ -563,11 +664,17 @@ int Fl_Input_::up_down_position(int i, int keepmark) { } /** - Put the current selection between mark() and - position() into the specified clipboard. Does not - replace the old clipboard contents if position() and - mark() are equal. Clipboard 0 maps to the current text + Put the current selection into the clipboard. + + This function copies the current selection between \c mark() and + \c position() into the specified clipboard. This does not + replace the old clipboard contents if \c position() and + \c mark() are equal. Clipboard 0 maps to the current text selection and clipboard 1 maps to the cut/paste clipboard. + + \param clipboard the clipboard destionation \c 0 or \c 1 + \return \c 0 if no text is selected, \c 1 if the selection was copied + \see \c Fl::copy(const char *, int, int) */ int Fl_Input_::copy(int clipboard) { int b = position(); @@ -603,29 +710,36 @@ static void undobuffersize(int n) { } } -// all changes go through here, delete characters b-e and insert text: /** - This call does all editing of the text. It deletes the region - between a and b (either one may be less or - equal to the other), and then inserts the string insert - at that point and leaves the mark() and - position() after the insertion. Does the callback if - when() & FL_WHEN_CHANGED and there is a change. + Deletes text from \p b to \p e and inserts the new string \p text. + + All changes to the text buffer go through this function. + It deletes the region between \p a and \p b (either one may be less or + equal to the other), and then inserts the string \p text + at that point and moves the \c mark() and + \c position() to the end of the insertion. Does the callback if + <tt>when() & FL_WHEN_CHANGED</tt> and there is a change. - <P>Set start and end equal to not delete - anything. Set insert to NULL to not insert - anything.</P> + Set \p b and \p e equal to not delete + anything. Set insert to \c NULL to not insert + anything. - <P>length must be zero or strlen(insert), this + \p ilen must be zero or \c strlen(insert), this saves a tiny bit of time if you happen to already know the length of the insertion, or can be used to insert a portion of a - string or a string containing nul's.</P> + string or a string containing \c nul's. - <P>a and b are clamped to the - 0..size() range, so it is safe to pass any values.</P> + \p b and \p e are clamped to the + <tt>0..size()</tt> range, so it is safe to pass any values. - <P>cut() and insert() are just inline - functions that call replace(). + \c cut() and \c insert() are just inline + functions that call \c replace(). + + \param [in] b beginning index of text to be deleted + \param [in] e ending index of text to be deleted and insertion position + \param [in] text string that will be inserted + \param [in] ilen length of \p text or \c 0 for \c nul terminated strings + \return \c 0 if nothing changed */ int Fl_Input_::replace(int b, int e, const char* text, int ilen) { int ul, om, op; @@ -723,8 +837,11 @@ int Fl_Input_::replace(int b, int e, const char* text, int ilen) { } /** - Does undo of several previous calls to replace(). - Returns non-zero if any change was made. + Undo previous changes to the text buffer. + + This call undoes a number of previous calls to \c replace(). + + \return non-zero if any change was made. */ int Fl_Input_::undo() { was_up_down = 0; @@ -767,8 +884,14 @@ int Fl_Input_::undo() { } /** + Copy the \e yank buffer to the clipboard. + Copy all the previous contiguous cuts from the undo - information to the clipboard. This is used to make ^K work. + information to the clipboard. This function implemnts + the \c ^K shortcut key. + + \return \c 0 if the operation did not change the clipboard + \see \c copy(int), \c cut() */ int Fl_Input_::copy_cuts() { // put the yank buffer into the X clipboard @@ -777,12 +900,21 @@ int Fl_Input_::copy_cuts() { return 1; } +/** \internal + Check the \c when() field and do a callback if indicated. +*/ void Fl_Input_::maybe_do_callback() { if (changed() || (when()&FL_WHEN_NOT_CHANGED)) { do_callback(); } } +/** + Handle all kinds of text field related events. + + This is calle by derived classes. + \todo Add comment and parameters +*/ int Fl_Input_::handletext(int event, int X, int Y, int W, int H) { switch (event) { @@ -900,9 +1032,14 @@ int Fl_Input_::handletext(int event, int X, int Y, int W, int H) { /*------------------------------*/ /** - Creates a new Fl_Input_ widget using the given - position, size, and label string. The default boxtype is - FL_DOWN_BOX. + Creates a new \c Fl_Input_ widget. + + This function created a new \c Fl_Input_ widget and adds it to the curren + \c Fl_Group. The \c value() is set the \c NULL. + The default boxtype is \c FL_DOWN_BOX. + + \param X, Y, W, H the dimensions of the new widget + \param l an optional label text */ Fl_Input_::Fl_Input_(int X, int Y, int W, int H, const char* l) : Fl_Widget(X, Y, W, H, l) { @@ -923,6 +1060,11 @@ Fl_Input_::Fl_Input_(int X, int Y, int W, int H, const char* l) set_flag(SHORTCUT_LABEL); } +/** + Copy the value from a possibly static entry into the internal buffer. + + \param [in] len size of the current text +*/ void Fl_Input_::put_in_buffer(int len) { if (value_ == buffer && bufsize > len) { buffer[size_] = 0; @@ -957,7 +1099,25 @@ void Fl_Input_::put_in_buffer(int len) { memmove(buffer, value_, size_); buffer[size_] = 0; value_ = buffer; } -/** See int Fl_Input::static_value(const char*) */ + +/** + Changes the widget text. + + This function change the text and set the mark and the point to + the end of it. The string is \e not copied. If the user edits the + string it is copied to the internal buffer then. This can save a + great deal of time and memory if your program is rapidly + changing the values of text fields, but this will only work if + the passed string remains unchanged until either the + \c Fl_Input is destroyed or \c value() is called again. + + You can use the \p len parameter to directly set the length + if you know it already or want to put \c nul characters in the text. + + \param [in] str the new text + \param [in] len the length of the new text + \return non-zero if the new value is different than the current one +*/ int Fl_Input_::static_value(const char* str, int len) { clear_changed(); if (undowidget == this) undowidget = 0; @@ -989,41 +1149,86 @@ int Fl_Input_::static_value(const char* str, int len) { } /** - Change the text and set the mark and the point to the end of - it. The string is <I>not</I> copied. If the user edits the + Changes the widget text. + + This function change the text and set the mark and the point to + the end of it. The string is \e not copied. If the user edits the string it is copied to the internal buffer then. This can save a great deal of time and memory if your program is rapidly changing the values of text fields, but this will only work if the passed string remains unchanged until either the - Fl_Input is destroyed or value() is called - again. + \c Fl_Input is destroyed or \c value() is called again. + + \param [in] str the new text + \return non-zero if the new value is different than the current one */ int Fl_Input_::static_value(const char* str) { return static_value(str, str ? strlen(str) : 0); } -/** See const char *Fl_Input_::value() const */ + +/** + Changes the widget text. + + This function changes the text and sets the mark and the + point to the end of it. The string is copied to the internal + buffer. Passing \c NULL is the same as \c "". + + You can use the \p length parameter to directly set the length + if you know it already or want to put \c nul characters in the text. + + \param [in] str the new text + \param [in] len the length of the new text + \return non-zero if the new value is different than the current one + \see \c Fl_Input_::value(const char* str), \c Fl_Input_::value() +*/ int Fl_Input_::value(const char* str, int len) { int r = static_value(str, len); if (len) put_in_buffer(len); return r; } -/** See const char *Fl_Input_::value() const */ +/** + Changes the widget text. + + This function changes the text and sets the mark and the + point to the end of it. The string is copied to the internal + buffer. Passing \c NULL is the same as \c "". + + \param [in] str the new text + \return non-zero if the new value is different than the current one + \see \c Fl_Input_::value(const char* str, int len), \c Fl_Input_::value() +*/ int Fl_Input_::value(const char* str) { return value(str, str ? strlen(str) : 0); } +/** + Change the size of the widget. + This call updates the text layout so that the cursor is visible. + \param [in] X, Y, W, H new size of the widget + \see \c Fl_Widget::resize(int, int, int, int) +*/ void Fl_Input_::resize(int X, int Y, int W, int H) { if (W != w()) xscroll_ = 0; if (H != h()) yscroll_ = 0; Fl_Widget::resize(X, Y, W, H); } +/** + Destroys the widget. + + The destructor clears all allocated buffers and removes the widget + from the parent \c Fl_Group. +*/ Fl_Input_::~Fl_Input_() { if (undowidget == this) undowidget = 0; if (bufsize) free((void*)buffer); } +/** \internal + Return the number of lines displayed on a single page. + \return widget height divided by the font height +*/ int Fl_Input_::linesPerPage() { int n = 1; if (input_type() == FL_MULTILINE_INPUT) { diff --git a/src/fl_utf.c b/src/fl_utf.c index 1a8d398fb..f50859fd8 100644 --- a/src/fl_utf.c +++ b/src/fl_utf.c @@ -46,7 +46,7 @@ \c NULL, only the length of the utf-8 sequence is calculated \return length of the sequence in bytes */ - /* FL_EXPORT int fl_unichar_to_utf8(Fl_Unichar uc, char *text); */ + /* FL_EXPORT int fl_unichar_to_utf8(Fl_Char uc, char *text); */ /** @} */ @@ -60,7 +60,7 @@ \param[in] uc Unicode character \return length of the sequence in bytes */ - /* FL_EXPORT int fl_utf8_size(Fl_Unichar uc); */ + /* FL_EXPORT int fl_utf8_size(Fl_Char uc); */ /** @} */ #endif /* 0 */ |