diff options
| -rw-r--r-- | FL/Fl_File_Input.H | 2 | ||||
| -rw-r--r-- | FL/Fl_Float_Input.H | 15 | ||||
| -rw-r--r-- | FL/Fl_Input.H | 209 | ||||
| -rw-r--r-- | FL/Fl_Input_.H | 128 | ||||
| -rw-r--r-- | FL/Fl_Input_Choice.H | 104 | ||||
| -rw-r--r-- | FL/Fl_Int_Input.H | 13 | ||||
| -rw-r--r-- | FL/Fl_Multiline_Input.H | 20 | ||||
| -rw-r--r-- | FL/Fl_Secret_Input.H | 15 | ||||
| -rw-r--r-- | FL/Fl_Widget.H | 39 | ||||
| -rw-r--r-- | documentation/todo_filelist_doc.txt | 14 | ||||
| -rw-r--r-- | src/Fl_File_Input.cxx | 45 | ||||
| -rw-r--r-- | src/Fl_Input.cxx | 4 | ||||
| -rw-r--r-- | src/Fl_Input_.cxx | 79 | ||||
| -rw-r--r-- | src/Fl_Menu_add.cxx | 20 |
14 files changed, 593 insertions, 114 deletions
diff --git a/FL/Fl_File_Input.H b/FL/Fl_File_Input.H index 1d4a561fd..61b94e4de 100644 --- a/FL/Fl_File_Input.H +++ b/FL/Fl_File_Input.H @@ -51,7 +51,9 @@ public: virtual int handle(int); virtual void draw(); + /** Gets or sets the box type to use for the navigation bar. */ Fl_Boxtype down_box() const { return (Fl_Boxtype)down_box_; } + /** Gets or sets the box type to use for the navigation bar. */ void down_box(Fl_Boxtype b) { down_box_ = b; } Fl_Color errorcolor() const { return errorcolor_; } void errorcolor(Fl_Color c) { errorcolor_ = c; } diff --git a/FL/Fl_Float_Input.H b/FL/Fl_Float_Input.H index 76a7c97c1..12061cf53 100644 --- a/FL/Fl_Float_Input.H +++ b/FL/Fl_Float_Input.H @@ -25,15 +25,26 @@ // http://www.fltk.org/str.php // + #ifndef Fl_Float_Input_H #define Fl_Float_Input_H #include "Fl_Input.H" +/** + The Fl_Float_Input class is a subclass of Fl_Input + that only allows the user to type floating point numbers (sign, + digits, decimal point, more digits, 'E' or 'e', sign, digits). +*/ class Fl_Float_Input : public Fl_Input { public: - Fl_Float_Input(int X,int Y,int W,int H,const char *l = 0) - : Fl_Input(X,Y,W,H,l) {type(FL_FLOAT_INPUT);} + /** + Creates a new Fl_Float_Input widget using the given position, + size, and label string. The default boxtype is FL_DOWN_BOX. + <P> Inherited destructor destroys the widget and any value associated with it + */ + Fl_Float_Input(int X,int Y,int W,int H,const char *l = 0) + : Fl_Input(X,Y,W,H,l) {type(FL_FLOAT_INPUT);} }; #endif diff --git a/FL/Fl_Input.H b/FL/Fl_Input.H index 8e3560a5d..97fa4cc19 100644 --- a/FL/Fl_Input.H +++ b/FL/Fl_Input.H @@ -30,6 +30,215 @@ #include "Fl_Input_.H" +/** + This is the FLTK text input widget. It displays a single line + of text and lets the user edit it. Normally it is drawn with an + inset box and a white background. The text may contain any + characters (even 0), and will correctly display anything, using + ^X notation for unprintable control characters and \nnn notation + for unprintable characters with the high bit set. It assumes the + font can draw any characters in the ISO-8859-1 character set.</P> + + <CENTER><TABLE border=1 WIDTH=90% summary="Fl_Input keyboard and mouse bindings."> + + <TR><TD WIDTH=200><B>Mouse button 1</B></TD><TD>Moves the cursor to + this point. Drag selects characters. Double click selects words. + Triple click selects all text. Shift+click extends the selection. + When you select text it is automatically copied to the clipboard. + </TD></TR> + + <TR><TD><B>Mouse button 2</B></TD><TD>Insert the clipboard at + the point clicked. You can also select a region and replace it with the + clipboard by selecting the region with mouse button 2. + </TD></TR> + + <TR><TD><B>Mouse button 3</B></TD><TD>Currently acts like button 1.</TD></TR> + + <TR><TD><B>Backspace</B></TD><TD>Deletes one character to the left, or + deletes the selected region.</TD></TR> + <TR><TD><B>Enter</B></TD><TD>May cause the callback, see when().</TD></TR> + <TR><TD><B>^A or Home</B></TD><TD>Go to start of line.</TD></TR> + <TR><TD><B>^B or Left</B></TD><TD>Move left</TD></TR> + <TR><TD><B>^C</B></TD><TD>Copy the selection to the clipboard</TD></TR> + <TR><TD><B>^D or Delete</B></TD><TD>Deletes one character to the right + or deletes the selected region.</TD></TR> + <TR><TD><B>^E or End</B></TD><TD>Go to the end of line.</TD></TR> + <TR><TD><B>^F or Right</B></TD><TD>Move right</TD></TR> + <TR><TD><B>^K</B></TD><TD>Delete to the end of line (next \n character) + or deletes a single \n character. These deletions are all concatenated + into the clipboard.</TD></TR> + <TR><TD><B>^N or Down</B></TD><TD>Move down (for Fl_Multiline_Input + only, otherwise it moves to the next input field).</TD></TR> + <TR><TD><B>^P or Up</B></TD><TD>Move up (for Fl_Multiline_Input only, + otherwise it moves to the previous input field).</TD></TR> + <TR><TD><B>^U</B></TD><TD>Delete everything.</TD></TR> + <TR><TD><B>^V or ^Y</B></TD><TD>Paste the clipboard</TD></TR> + <TR><TD><B>^X or ^W</B></TD><TD>Copy the region to the clipboard and + delete it.</TD></TR> + <TR><TD><B>^Z or ^_</B></TD><TD>Undo. This is a single-level undo + mechanism, but all adjacent deletions and insertions are concatenated + into a single "undo". Often this will undo a lot more than you + expected.</TD></TR> + <TR><TD><B>Shift+move</B></TD><TD>Move the cursor but also extend the + selection.</TD></TR> + + <TR><TD><B>RightCtrl or + <BR>Compose</B></TD><TD>Start + a compose-character + sequence. The next one or two keys typed define the character to + insert (see table that follows.) + + <p>For instance, to type "á" type [compose][a]['] or [compose]['][a]. + + <P>The character "nbsp" (non-breaking space) is typed by using + [compose][space]. + + <P>The single-character sequences may be followed by a space if + necessary to remove ambiguity. For instance, if you really want to + type "ª~" rather than "ã" you must type [compose][a][space][~]. + + <p>The same key may be used to "quote" control characters into the + text. If you need a ^Q character you can get one by typing + [compose][Control+Q]. + + <p>X may have a key on the keyboard + defined as XK_Multi_key. If so this key may be used as well + as the right-hand control key. You can set this up with the program + xmodmap. + + <p>If your keyboard is set to support a foreign language you should + also be able to type "dead key" prefix characters. On X you will + actually be able to see what dead key you typed, and if you then move + the cursor without completing the sequence the accent will remain + inserted.</TD></TR> + </TABLE></CENTER> + + <!-- NEW PAGE --> + <center><table border=1 summary="Character Composition Table"> + <caption align="top">Character Composition Table</caption> + <tr> + <th>Keys</th><th>Char</th> + <th>Keys</th><th>Char</th> + <th>Keys</th><th>Char</th> + <th>Keys</th><th>Char</th> + <th>Keys</th><th>Char</th> + <th>Keys</th><th>Char</th> + + </tr><tr> + <td align=center>sp</td><td align=center><small>nbsp</small></td> + <td align=center>*</td><td align=center>°</td> + <td align=center>` A</td><td align=center>À</td> + <td align=center>D -</td><td align=center>Ð</td> + <td align=center>` a</td><td align=center>à</td> + <td align=center>d -</td><td align=center>ð</td> + </tr><tr> + <td align=center>!</td><td align=center>¡</td> + <td align=center>+ -</td><td align=center>±</td> + <td align=center>' A</td><td align=center>Á</td> + <td align=center>~ N</td><td align=center>Ñ</td> + <td align=center>' a</td><td align=center>á</td> + <td align=center>~ n</td><td align=center>ñ</td> + </tr><tr> + <td align=center>%</td><td align=center>¢</td> + <td align=center>2</td><td align=center>²</td> + <td align=center>A ^</td><td align=center>Â</td> + <td align=center>` O</td><td align=center>Ò</td> + <td align=center>^ a</td><td align=center>â</td> + <td align=center>` o</td><td align=center>ò</td> + </tr><tr> + <td align=center>#</td><td align=center>£</td> + <td align=center>3</td><td align=center>³</td> + <td align=center>~ A</td><td align=center>Ã</td> + <td align=center>' O</td><td align=center>Ó</td> + <td align=center>~ a</td><td align=center>ã</td> + <td align=center>' o</td><td align=center>ó</td> + </tr><tr> + <td align=center>$</td><td align=center>¤</td> + <td align=center>'</td><td align=center>´</td> + <td align=center>: A</td><td align=center>Ä</td> + <td align=center>^ O</td><td align=center>Ô</td> + <td align=center>: a</td><td align=center>ä</td> + <td align=center>^ o</td><td align=center>ô</td> + </tr><tr> + <td align=center>y =</td><td align=center>¥</td> + <td align=center>u</td><td align=center>µ</td> + <td align=center>* A</td><td align=center>Å</td> + <td align=center>~ O</td><td align=center>Õ</td> + <td align=center>* a</td><td align=center>å</td> + <td align=center>~ o</td><td align=center>õ</td> + </tr><tr> + <td align=center>|</td><td align=center>¦</td> + <td align=center>p</td><td align=center>¶</td> + <td align=center>A E</td><td align=center>Æ</td> + <td align=center>: O</td><td align=center>Ö</td> + <td align=center>a e</td><td align=center>æ</td> + <td align=center>: o</td><td align=center>ö</td> + </tr><tr> + <td align=center>&</td><td align=center>§</td> + <td align=center>.</td><td align=center>·</td> + <td align=center>, C</td><td align=center>Ç</td> + <td align=center>x</td><td align=center>×</td> + <td align=center>, c</td><td align=center>ç</td> + <td align=center>- :</td><td align=center>÷</td> + </tr><tr> + <td align=center>:</td><td align=center>¨</td> + <td align=center>,</td><td align=center>¸</td> + <td align=center>E `</td><td align=center>È</td> + <td align=center>O /</td><td align=center>Ø</td> + <td align=center>` e</td><td align=center>è</td> + <td align=center>o /</td><td align=center>ø</td> + </tr><tr> + <td align=center>c</td><td align=center>©</td> + <td align=center>1</td><td align=center>¹</td> + <td align=center>' E</td><td align=center>É</td> + <td align=center>` U</td><td align=center>Ù</td> + <td align=center>' e</td><td align=center>é</td> + <td align=center>` u</td><td align=center>ù</td> + </tr><tr> + <td align=center>a</td><td align=center>ª</td> + <td align=center>o</td><td align=center>º</td> + <td align=center>^ E</td><td align=center>Ê</td> + <td align=center>' U</td><td align=center>Ú</td> + <td align=center>^ e</td><td align=center>ê</td> + <td align=center>' u</td><td align=center>ú</td> + </tr><tr> + <td align=center>< <</td><td align=center>«</td> + <td align=center>> ></td><td align=center>»</td> + <td align=center>: E</td><td align=center>Ë</td> + <td align=center>^ U</td><td align=center>Û</td> + <td align=center>: e</td><td align=center>ë</td> + <td align=center>^ u</td><td align=center>û</td> + </tr><tr> + <td align=center>~</td><td align=center>¬</td> + <td align=center>1 4</td><td align=center>¼</td> + <td align=center>` I</td><td align=center>Ì</td> + <td align=center>: U</td><td align=center>Ü</td> + <td align=center>` i</td><td align=center>ì</td> + <td align=center>: u</td><td align=center>ü</td> + </tr><tr> + <td align=center>-</td><td align=center></td> + <td align=center>1 2</td><td align=center>½</td> + <td align=center>' I</td><td align=center>Í</td> + <td align=center>' Y</td><td align=center>Ý</td> + <td align=center>' i</td><td align=center>í</td> + <td align=center>' y</td><td align=center>ý</td> + </tr><tr> + <td align=center>r</td><td align=center>®</td> + <td align=center>3 4</td><td align=center>¾</td> + <td align=center>^ I</td><td align=center>Î</td> + <td align=center>T H</td><td align=center>Þ</td> + <td align=center>^ i</td><td align=center>î</td> + <td align=center>t h</td><td align=center>þ</td> + </tr><tr> + <td align=center>_</td><td align=center>¯</td> + <td align=center>?</td><td align=center>¿</td> + <td align=center>: I</td><td align=center>Ï</td> + <td align=center>s s</td><td align=center>ß</td> + <td align=center>: i</td><td align=center>ï</td> + <td align=center>: y</td><td align=center>ÿ</td> + </tr> + </table></center> +*/ class FL_EXPORT Fl_Input : public Fl_Input_ { int handle_key(); int shift_position(int p); diff --git a/FL/Fl_Input_.H b/FL/Fl_Input_.H index 7d53bbc75..dc9bd9969 100644 --- a/FL/Fl_Input_.H +++ b/FL/Fl_Input_.H @@ -46,6 +46,31 @@ #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) +/** + 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 + one of those people who likes to change how the editing keys + work. + + <P>This can act like any of the subclasses of Fl_Input, by + setting type() to one of the following values:</P> + + \code + #define FL_NORMAL_INPUT 0 + #define FL_FLOAT_INPUT 1 + #define FL_INT_INPUT 2 + #define FL_MULTILINE_INPUT 4 + #define FL_SECRET_INPUT 5 + #define FL_INPUT_TYPE 7 + #define FL_INPUT_READONLY 8 + #define FL_NORMAL_OUTPUT (FL_NORMAL_INPUT | FL_INPUT_READONLY) + #define FL_MULTILINE_OUTPUT (FL_MULTILINE_INPUT | FL_INPUT_READONLY) + #define FL_INPUT_WRAP 16 + #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 +*/ class FL_EXPORT Fl_Input_ : public Fl_Widget { const char* value_; @@ -99,45 +124,142 @@ public: int value(const char*, int); int static_value(const char*); int static_value(const char*, int); + /** + The first form 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. + */ const char* value() const {return value_;} - char index(int i) const {return value_[i];} + /** + Same as value()[n], but may be faster in plausible + implementations. No bounds checking is done. + */ +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. + */ int size() const {return size_;} void size(int W, int H) { Fl_Widget::size(W, H); } + /** Gets the maximum length of the input field. */ int maximum_size() const {return maximum_size_;} + /** Sets the maximum length of the input field. */ 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). + */ int position() const {return position_;} + /** Gets the current selection mark. mark(n) is the same as position(position(),n).*/ int mark() const {return mark_;} int position(int p, int m); + /** See int Fl_Input_::position() const */ int position(int p) {return position(p, p);} + /** Sets the current selection mark. mark(n) is the same as position(position(),n).*/ int mark(int m) {return position(position(), m);} 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. + */ int cut() {return replace(position(), mark(), 0);} + /** See int Fl_Input_::cut() */ int cut(int n) {return replace(position(), position()+n, 0);} + /** See int Fl_Input_::cut() */ 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). + */ int insert(const char* t, int l=0){return replace(position_, mark_, t, l);} int copy(int clipboard); int undo(); 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). + */ int shortcut() const {return shortcut_;} + /** See int shortcut() const */ void shortcut(int s) {shortcut_ = s;} + /** Gets the font of the text in the input field.*/ Fl_Font textfont() const {return textfont_;} + /** Sets the font of the text in the input field.*/ void textfont(Fl_Font s) {textfont_ = s;} + /** Gets the size of the text in the input field.*/ Fl_Fontsize textsize() const {return textsize_;} + /** Sets the size of the text in the input field.*/ void textsize(Fl_Fontsize s) {textsize_ = s;} + /** Gets the color of the text in the input field.*/ Fl_Color textcolor() const {return (Fl_Color)textcolor_;} + /** Sets the color of the text in the input field.*/ void textcolor(unsigned n) {textcolor_ = n;} + /** Gets the color of the cursor. This is black by default.*/ Fl_Color cursor_color() const {return (Fl_Color)cursor_color_;} + /** Sets the color of the cursor. This is black by default.*/ void cursor_color(unsigned n) {cursor_color_ = n;} - + /** Gets the input field type. */ int input_type() const {return type() & FL_INPUT_TYPE; } + /** Sets the input field type. */ void input_type(int t) { type((uchar)(t | readonly())); } + /** Gets the read-only state of the input field. */ int readonly() const { return type() & FL_INPUT_READONLY; } + /** Sets the read-only state of the input field. */ 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. + */ 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. + */ void wrap(int b) { if (b) type((uchar)(type() | FL_INPUT_WRAP)); else type((uchar)(type() & ~FL_INPUT_WRAP)); } }; diff --git a/FL/Fl_Input_Choice.H b/FL/Fl_Input_Choice.H index be502a1d3..5f9161602 100644 --- a/FL/Fl_Input_Choice.H +++ b/FL/Fl_Input_Choice.H @@ -30,6 +30,8 @@ // http://www.fltk.org/str.php // + + #ifndef Fl_Input_Choice_H #define Fl_Input_Choice_H @@ -40,6 +42,17 @@ #include <FL/fl_draw.H> #include <string.h> +/** + A combination of the input widget and a menu button. + The user can either type into the input area, or use the + menu button chooser on the right, which loads the input area + with predefined text. Normally it is drawn with an inset box + and a white background. + <P> + The application can directly access both the input and menu + widgets directly, using the menubutton() + and input() accessor methods. +*/ class Fl_Input_Choice : public Fl_Group { // Private class to handle slightly 'special' behavior of menu button class InputMenuButton : public Fl_Menu_Button { @@ -112,6 +125,11 @@ class Fl_Input_Choice : public Fl_Group { inline int menu_h() { return(h() - Fl::box_dh(box())); } public: + /** + Creates a new Fl_Input_Choice widget using the given position, size, + and label string. + <P> Inherited destructor Destroys the widget and any value associated with it. + */ Fl_Input_Choice (int x,int y,int w,int h,const char*l=0) : Fl_Group(x,y,w,h,l) { Fl_Group::box(FL_DOWN_BOX); align(FL_ALIGN_LEFT); // default like Fl_Input @@ -126,12 +144,10 @@ public: menu_->box(FL_FLAT_BOX); // cosmetic end(); } - void add(const char *s) { - menu_->add(s); - } - int changed() const { - return inp_->changed() | Fl_Widget::changed(); - } + + /** Adds an item to the menu.*/ + void add(const char *s) { menu_->add(s); } + int changed() const { return inp_->changed() | Fl_Widget::changed();} void clear_changed() { inp_->clear_changed(); Fl_Widget::clear_changed(); @@ -140,55 +156,53 @@ public: inp_->set_changed(); // no need to call Fl_Widget::set_changed() } - void clear() { - menu_->clear(); - } - Fl_Boxtype down_box() const { - return (menu_->down_box()); - } - void down_box(Fl_Boxtype b) { - menu_->down_box(b); - } - const Fl_Menu_Item *menu() { - return (menu_->menu()); - } - void menu(const Fl_Menu_Item *m) { - menu_->menu(m); - } + /** Removes all items from the menu. */ + void clear() { menu_->clear(); } + /** Gets the box type of the menu button */ + Fl_Boxtype down_box() const { return (menu_->down_box()); } + /** Sets the box type of the menu button */ + void down_box(Fl_Boxtype b) { menu_->down_box(b); } + /** Gets the Fl_Menu_Item array used for the menu. */ + const Fl_Menu_Item *menu() { return (menu_->menu()); } + /** Sets the Fl_Menu_Item array used for the menu. */ + void menu(const Fl_Menu_Item *m) { menu_->menu(m); } void resize(int X, int Y, int W, int H) { Fl_Group::resize(X,Y,W,H); inp_->resize(inp_x(), inp_y(), inp_w(), inp_h()); menu_->resize(menu_x(), menu_y(), menu_w(), menu_h()); } - Fl_Color textcolor() const { - return (inp_->textcolor()); - } - void textcolor(Fl_Color c) { - inp_->textcolor(c); - } - Fl_Font textfont() const { - return (inp_->textfont()); - } - void textfont(Fl_Font f) { - inp_->textfont(f); - } - Fl_Fontsize textsize() const { - return (inp_->textsize()); - } - void textsize(Fl_Fontsize s) { - inp_->textsize(s); - } - const char* value() const { - return (inp_->value()); - } - void value(const char *val) { - inp_->value(val); - } + /** Gets the encapsulated input text color attributes */ + Fl_Color textcolor() const { return (inp_->textcolor());} + /** Sets the encapsulated input text color attributes */ + void textcolor(Fl_Color c) { inp_->textcolor(c);} + /** Gets the encapsulated input text font attributes */ + Fl_Font textfont() const { return (inp_->textfont());} + /** Sets the encapsulated input text font attributes */ + void textfont(Fl_Font f) { inp_->textfont(f);} + /** Gets the encapsulated input size attributes */ + Fl_Fontsize textsize() const { return (inp_->textsize()); } + /** Sets the encapsulated input size attributes */ + void textsize(Fl_Fontsize s) { inp_->textsize(s); } + /** See void Fl_Input_Choice::value(const char *s) */ + const char* value() const { return (inp_->value()); } + /** + Sets or returns the input widget's current contents. The + second form sets the contents using the index into the menu + which you can set as an integer. Setting the value effectively + 'chooses' this menu item, and sets it as the new input text, + deleting the previous text. + */ + void value(const char *val) { inp_->value(val); } + /** See void Fl_Input_Choice::value(const char *s) */ void value(int val) { menu_->value(val); inp_->value(menu_->text(val)); } + /** Returns a reference to the internal Fl_Menu_Button widget. */ Fl_Menu_Button *menubutton() { return menu_; } + /** + Returns a reference to the internal Fl_Input widget.</p> + */ Fl_Input *input() { return inp_; } }; diff --git a/FL/Fl_Int_Input.H b/FL/Fl_Int_Input.H index 64ae2310d..92c91e080 100644 --- a/FL/Fl_Int_Input.H +++ b/FL/Fl_Int_Input.H @@ -30,10 +30,19 @@ #include "Fl_Input.H" +/** + The Fl_Int_Input class is a subclass of Fl_Input + that only allows the user to type decimal digits (or hex numbers of the form 0xaef). +*/ class Fl_Int_Input : public Fl_Input { public: - Fl_Int_Input(int X,int Y,int W,int H,const char *l = 0) - : Fl_Input(X,Y,W,H,l) {type(FL_INT_INPUT);} + /** + Creates a new Fl_Int_Input widget using the given position, + size, and label string. The default boxtype is FL_DOWN_BOX. + <P>Inherited destructor Destroys the widget and any value associated with it. + */ + Fl_Int_Input(int X,int Y,int W,int H,const char *l = 0) + : Fl_Input(X,Y,W,H,l) {type(FL_INT_INPUT);} }; #endif diff --git a/FL/Fl_Multiline_Input.H b/FL/Fl_Multiline_Input.H index 063d391db..2ab3cea80 100644 --- a/FL/Fl_Multiline_Input.H +++ b/FL/Fl_Multiline_Input.H @@ -25,15 +25,31 @@ // http://www.fltk.org/str.php // + #ifndef Fl_Multiline_Input_H #define Fl_Multiline_Input_H #include "Fl_Input.H" +/** + This input field displays '\n' characters as new lines rather than ^J, + and accepts the Return, Tab, and up and down arrow keys. This is for + editing multiline text. + <P>This is far from the nirvana of text editors, and is probably only + good for small bits of text, 10 lines at most. I think FLTK can be + used to write a powerful text editor, but it is not going to be a + built-in feature. Powerful text editors in a toolkit are a big source + of bloat. +*/ class Fl_Multiline_Input : public Fl_Input { public: - Fl_Multiline_Input(int X,int Y,int W,int H,const char *l = 0) - : Fl_Input(X,Y,W,H,l) {type(FL_MULTILINE_INPUT);} + /** + Creates a new Fl_Multiline_Input widget using the given + position, size, and label string. The default boxtype is FL_DOWN_BOX. + <P>Inherited destructor destroys the widget and any value associated with it. + */ + Fl_Multiline_Input(int X,int Y,int W,int H,const char *l = 0) + : Fl_Input(X,Y,W,H,l) {type(FL_MULTILINE_INPUT);} }; #endif diff --git a/FL/Fl_Secret_Input.H b/FL/Fl_Secret_Input.H index 1c955a593..8ed28752e 100644 --- a/FL/Fl_Secret_Input.H +++ b/FL/Fl_Secret_Input.H @@ -25,15 +25,26 @@ // http://www.fltk.org/str.php // + #ifndef Fl_Secret_Input_H #define Fl_Secret_Input_H #include "Fl_Input.H" +/** + The Fl_Secret_Input class is a subclass of Fl_Input + that displays its input as a string of asterisks. This subclass is + usually used to receive passwords and other "secret" information. +*/ class Fl_Secret_Input : public Fl_Input { public: - Fl_Secret_Input(int X,int Y,int W,int H,const char *l = 0) - : Fl_Input(X,Y,W,H,l) {type(FL_SECRET_INPUT);} + /** + Creates a new Fl_Secret_Input widget using the given + position, size, and label string. The default boxtype is FL_DOWN_BOX. + <P>Inherited destructor destroys the widget and any value associated with it. + */ + Fl_Secret_Input(int X,int Y,int W,int H,const char *l = 0) + : Fl_Input(X,Y,W,H,l) {type(FL_SECRET_INPUT);} }; #endif diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H index fab179f7b..b23b5ba61 100644 --- a/FL/Fl_Widget.H +++ b/FL/Fl_Widget.H @@ -532,8 +532,43 @@ public: */ void argument(long v) {user_data_ = (void*)v;} - /** Return the conditions under which the callback is called. - * \return set of flags + /** + Controls when callbacks are done. The following values are useful, + the default value is FL_WHEN_RELEASE: + + <UL> + + <LI>0: The callback is not done, but + changed() is turned on.</LI> + + <LI>FL_WHEN_CHANGED: The callback is done each + time the text is changed by the user.</LI> + + <LI>FL_WHEN_RELEASE: The callback will be done + when this widget loses the focus, including when the + window is unmapped. This is a useful value for text + fields in a panel where doing the callback on every + change is wasteful. However the callback will also + happen if the mouse is moved out of the window, which + means it should not do anything visible (like pop up an + error message). You might do better setting this to + zero, and scanning all the items for changed() + when the OK button on a panel is pressed.</LI> + + <LI>FL_WHEN_ENTER_KEY: If the user types the + Enter key, the entire text is selected, and the callback + is done if the text has changed. Normally the Enter key + will navigate to the next field (or insert a newline for + a Fl_Mulitline_Input), this changes the + behavior.</LI> + + <LI>FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The + Enter key will do the callback even if the text has not + changed. Useful for command fields.</LI> + + </UL> + Return the conditions under which the callback is called. + \return set of flags */ Fl_When when() const {return (Fl_When)when_;} diff --git a/documentation/todo_filelist_doc.txt b/documentation/todo_filelist_doc.txt index e89c0276a..d89dd77e4 100644 --- a/documentation/todo_filelist_doc.txt +++ b/documentation/todo_filelist_doc.txt @@ -17,7 +17,7 @@ In Progress Work List (add your WP and name here): - WP6 (Fabien) DONE - WP7 (Fabien) DONE - WP8 (Fabien) DONE - - WP9 (Fabien) + - WP9 (Fabien) DONE - WP10 (Fabien) - WP11 - WP12 (Albrecht) work in progress @@ -171,11 +171,8 @@ Fl_Color_Chooser.cxx Fl_Counter.H Fl_Counter.cxx Fl_Export.H -Fl_File_Input.H -Fl_File_Input.cxx Fl_Fill_Dial.H Fl_Fill_Slider.H -Fl_Float_Input.H Fl_Font.H Fl_FormsBitmap.H Fl_FormsPixmap.H @@ -185,18 +182,10 @@ Fl_Hor_Fill_Slider.H Fl_Hor_Nice_Slider.H Fl_Hor_Slider.H Fl_Hor_Value_Slider.H -Fl_Input.H -Fl_Input.cxx -Fl_Input_.H -Fl_Input_.cxx -Fl_Input_Choice.H -Fl_Int_Input.H Fl_Line_Dial.H Fl_Multi_Browser.H Fl_Multi_Label.H Fl_Multi_Label.cxx -Fl_Multiline_Input.H -Fl_Multiline_Output.H Fl_Nice_Slider.H Fl_Object.H Fl_Output.H @@ -206,7 +195,6 @@ Fl_Radio_Round_Button.H Fl_Roller.H Fl_Roller.cxx Fl_Round_Clock.H -Fl_Secret_Input.H Fl_Select_Browser.H Fl_Simple_Counter.H Fl_Slider.H diff --git a/src/Fl_File_Input.cxx b/src/Fl_File_Input.cxx index 45625b5ee..b49974c0f 100644 --- a/src/Fl_File_Input.cxx +++ b/src/Fl_File_Input.cxx @@ -48,10 +48,10 @@ #define FL_DAMAGE_BAR 0x10 -// -// 'Fl_File_Input::Fl_File_Input()' - Create a Fl_File_Input widget. -// - +/** + Creates a new Fl_File_Input widget using the given position, + size, and label string. The default boxtype is FL_DOWN_BOX. +*/ Fl_File_Input::Fl_File_Input(int X, int Y, int W, int H, const char *l) : Fl_Input(X, Y, W, H, l) { buttons_[0] = 0; @@ -62,12 +62,8 @@ Fl_File_Input::Fl_File_Input(int X, int Y, int W, int H, const char *l) down_box(FL_UP_BOX); } -// -// 'Fl_File_Input::draw_buttons()' - Draw directory buttons. -// - -void -Fl_File_Input::draw_buttons() { +/** Draw directory buttons. */ +void Fl_File_Input::draw_buttons() { int i, // Looping var X; // Current X position @@ -101,12 +97,8 @@ Fl_File_Input::draw_buttons() { } } -// -// 'Fl_File_Input::update_buttons()' - Update the sizes of the directory buttons. -// - -void -Fl_File_Input::update_buttons() { +/** Update the sizes of the directory buttons.*/ +void Fl_File_Input::update_buttons() { int i; // Looping var const char *start, // Start of path component *end; // End of path component @@ -141,9 +133,7 @@ Fl_File_Input::update_buttons() { // -// 'Fl_File_Input::value()' - Set the value of the widget... -// - +/** Sets the value of the widget given a new string value and its length, Returns non 0 on success */ int // O - TRUE on success Fl_File_Input::value(const char *str, // I - New string value int len) { // I - Length of value @@ -152,6 +142,7 @@ Fl_File_Input::value(const char *str, // I - New string value } +/** Sets the value of the widget given a new string value, Returns non 0 on success */ int // O - TRUE on success Fl_File_Input::value(const char *str) { // I - New string value damage(FL_DAMAGE_BAR); @@ -159,12 +150,8 @@ Fl_File_Input::value(const char *str) { // I - New string value } -// -// 'Fl_File_Input::draw()' - Draw the file input widget... -// - -void -Fl_File_Input::draw() { +/** Draws the file input widget */ +void Fl_File_Input::draw() { Fl_Boxtype b = box(); if (damage() & (FL_DAMAGE_BAR | FL_DAMAGE_ALL)) draw_buttons(); // this flag keeps Fl_Input_::drawtext from drawing a bogus box! @@ -178,10 +165,8 @@ Fl_File_Input::draw() { } -// -// 'Fl_File_Input::handle()' - Handle events in the widget... -// +/** Handle events in the widget, return non zero if event is handled */ int // O - TRUE if we handled event Fl_File_Input::handle(int event) // I - Event { @@ -215,10 +200,8 @@ Fl_File_Input::handle(int event) // I - Event } -// -// 'Fl_File_Input::handle_button()' - Handle button events in the widget... -// +/** Handles button events in the widget , return non zero if event is handled */ int // O - TRUE if we handled event Fl_File_Input::handle_button(int event) // I - Event { diff --git a/src/Fl_Input.cxx b/src/Fl_Input.cxx index ba10c0694..15eee0d14 100644 --- a/src/Fl_Input.cxx +++ b/src/Fl_Input.cxx @@ -465,6 +465,10 @@ int Fl_Input::handle(int event) { w()-Fl::box_dw(b), h()-Fl::box_dh(b)); } +/** + Creates a new Fl_Input widget using the given position, size, + and label string. The default boxtype is FL_DOWN_BOX. +*/ Fl_Input::Fl_Input(int X, int Y, int W, int H, const char *l) : Fl_Input_(X, Y, W, H, l) { } diff --git a/src/Fl_Input_.cxx b/src/Fl_Input_.cxx index ae4799e45..bebd08712 100644 --- a/src/Fl_Input_.cxx +++ b/src/Fl_Input_.cxx @@ -25,6 +25,14 @@ // 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 @@ -165,6 +173,12 @@ void Fl_Input_::setfont() const { 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 + minimal update and erases the area itself. +*/ void Fl_Input_::drawtext(int X, int Y, int W, int H) { int do_mu = !(damage()&FL_DAMAGE_ALL); @@ -472,6 +486,7 @@ void Fl_Input_::handle_mouse(int X, int Y, int /*W*/, int /*H*/, int drag) { position(newpos, newmark); } +/** See int Fl_Input_::position() const */ int Fl_Input_::position(int p, int m) { int is_same = 0; was_up_down = 0; @@ -520,6 +535,12 @@ int Fl_Input_::position(int p, int m) { return 1; } +/** + 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. +*/ int Fl_Input_::up_down_position(int i, int keepmark) { // unlike before, i must be at the start of the line already! @@ -539,6 +560,13 @@ int Fl_Input_::up_down_position(int i, int keepmark) { return j; } +/** + 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 + selection and clipboard 1 maps to the cut/paste clipboard. +*/ int Fl_Input_::copy(int clipboard) { int b = position(); int e = mark(); @@ -574,6 +602,29 @@ 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. + + <P>Set start and end equal to not delete + anything. Set insert to NULL to not insert + anything.</P> + + <P>length must be zero or 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> + + <P>a and b are clamped to the + 0..size() range, so it is safe to pass any values.</P> + + <P>cut() and insert() are just inline + functions that call replace(). +*/ int Fl_Input_::replace(int b, int e, const char* text, int ilen) { int ul, om, op; was_up_down = 0; @@ -669,6 +720,10 @@ int Fl_Input_::replace(int b, int e, const char* text, int ilen) { return 1; } +/** + Does undo of several previous calls to replace(). + Returns non-zero if any change was made. +*/ int Fl_Input_::undo() { was_up_down = 0; if (undowidget != this || !undocut && !undoinsert) return 0; @@ -709,6 +764,10 @@ int Fl_Input_::undo() { return 1; } +/** + Copy all the previous contiguous cuts from the undo + information to the clipboard. This is used to make ^K work. +*/ int Fl_Input_::copy_cuts() { // put the yank buffer into the X clipboard if (!yankcut || input_type()==FL_SECRET_INPUT) return 0; @@ -839,6 +898,11 @@ 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. +*/ Fl_Input_::Fl_Input_(int X, int Y, int W, int H, const char* l) : Fl_Widget(X, Y, W, H, l) { box(FL_DOWN_BOX); @@ -892,7 +956,7 @@ 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*) */ int Fl_Input_::static_value(const char* str, int len) { clear_changed(); if (undowidget == this) undowidget = 0; @@ -923,16 +987,27 @@ int Fl_Input_::static_value(const char* str, int len) { return 1; } +/** + 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 + 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. +*/ int Fl_Input_::static_value(const char* str) { return static_value(str, str ? strlen(str) : 0); } - +/** See const char *Fl_Input_::value() const */ 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 */ int Fl_Input_::value(const char* str) { return value(str, str ? strlen(str) : 0); } diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx index 7bc766948..1edb61394 100644 --- a/src/Fl_Menu_add.cxx +++ b/src/Fl_Menu_add.cxx @@ -175,6 +175,7 @@ int Fl_Menu_Item::add( if (array == local_array) local_array_size = msize; return m-array; } + /** Adds a new menu item, with a title string, shortcut int (or string), callback, argument to the callback, and flags. @@ -227,16 +228,7 @@ int Fl_Menu_Item::add( <P>No items must be added to a menu during a callback to the same menu.</P> - <h4>int Fl_Menu_::add(const char *)</H4> - - <P>The passed string is split at any '|' characters and then - add(s,0,0,0,0) is done with each section. This is - often useful if you are just using the value, and is compatible - with Forms and other GL programs. The section strings use the - same special characters as described for the long version of add()</p> - - <P>No items must be added to a menu during a callback to the same menu. -*/ + */ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) { // make this widget own the local array: if (this != fl_menu_array_owner) { @@ -283,6 +275,14 @@ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) { This is a Forms (and SGI GL library) compatible add function, it adds many menu items, with '|' seperating the menu items, and tab separating the menu item names from an optional shortcut string. + + The passed string is split at any '|' characters and then + add(s,0,0,0,0) is done with each section. This is + often useful if you are just using the value, and is compatible + with Forms and other GL programs. The section strings use the + same special characters as described for the long version of add()</p> + + <P>No items must be added to a menu during a callback to the same menu. */ int Fl_Menu_::add(const char *str) { char buf[1024]; |