Input Class Reference

Inherits Widget.

Inherited by ComboBox::ComboInput, FileInput, MultiLineInput, NumericInput, Output, SecretInput, and WordwrapInput.

List of all members.

Public Types
enum	{   NORMAL, FLOAT_INPUT, INT_INPUT, SECRET,   MULTILINE, WORDWRAP }
Public Member Functions
	Input (int, int, int, int, const char *=0)
	~Input ()
void	draw ()
void	draw (const Rectangle &)
int	handle (int)
int	handle (int event, const Rectangle &)
bool	handle_key ()
bool	text (const char *)
bool	text (const char *, int)
bool	static_text (const char *)
bool	static_text (const char *, int)
const char *	text () const
char	at (int i) const
bool	value (const char *v)
bool	value (const char *v, int n)
bool	static_value (const char *v)
const char *	value () const
int	size () const
void	reserve (int newsize)
int	position () const
int	mark () const
void	position (int p, int m)
void	position (int p)
void	up_down_position (int position, bool extend)
void	mark (int m)
virtual bool	replace (int, int, const char *, int)
bool	cut ()
bool	cut (int n)
bool	cut (int a, int b)
bool	insert (const char *t)
bool	insert (const char *t, int l)
bool	replace (int a, int b, char c)
bool	copy (bool clipboard=true)
bool	undo ()
void	maybe_do_callback ()
int	word_start (int i) const
int	word_end (int i) const
int	line_start (int i) const
int	line_end (int i) const
int	mouse_position (const Rectangle &) const
int	xscroll () const
int	yscroll () const
Static Public Attributes
NamedStyle *	default_style

---

Detailed Description

This is the FLTK text input widget. It displays a single line of text and lets the user edit it. The text may contain any bytes (even '\0'). The bytes 0..31 are displayed in ^X notation, the rest are interpreted as UTF-8 (see utf8decode()).

By default the callback() is done each time the text is changed by the user. Other values for when():

• WHEN_NEVER: The callback is not done, but changed() is turned on.
• WHEN_CHANGED: The default, if set and no other flags are set the callback is done each time the text is changed by the user.
• WHEN_ENTER_KEY: If the user types the Enter key, the entire text is selected, and if the value has changed, the callback is done. The callback will also be done if the value has changed and the user clicks on another widget or the focus moves away (to another widget or program). If another widget (such as an OK button on a panel) has Enter as a shortcut, that widget will take precendence. If that widget hides or destroys the Input widget because it is dismissing a panel, the callback will be done then.
• WHEN_ENTER_KEY_ALWAYS: The Enter key will do the callback even if the text has not changed. Useful for command fields. The callback will also be done for other reasons described above, test event_key()==EnterKey to ignore these.
• WHEN_RELEASE: Depreciated. The callback is done if the text has changed and the user clicks on another widget or the focus moves away. But no special treatment of ENTER.

If you wish to restrict the text the user can type (such as limiting it to numbers, a particular length, etc), you should subclass this and override the replace() function with a version that rejects changes you don't want to allow.

If you don't like the keybindings you can override handle() to change them.

All arguments that are lengths or offsets into the strings are in bytes, not the UTF-8 characters they represent.

---

Constructor & Destructor Documentation

Input::Input (  int  x, int  y, int  w, int  h, const char *  l = 0 )

The constructor initializes: label alignment to ALIGN_LEFT (puts label to left) value to ""

Input::~Input (   )

The destructor destroys the memory used by text()

---

Member Function Documentation

char Input::at (  int  i  )  const [inline]

Same as text()[n], but may be faster in plausible implementations. No bounds checking is done.

bool Input::copy (  bool  clipboard = true  )

Put the current selection between mark() and position() into the selection or clipboard by calling copy(). If position() and mark() are equal this does nothing (ie it does not clear the clipboard). If clipboard is true the text is put into the user-visible cut & paste clipboard (this is probably what you want). If clipboard is false it is put into the less-visible selection buffer that is used to do middle-mouse paste and drag & drop. To paste the clipboard, call paste(true) and fltk will send the widget a PASTE event with the text, which will cause it to be inserted.

bool Input::cut (  int  a, int  b )  [inline]

Wrapper around replace() this deletes the characters between a and b. The values are clamped to the ends of the string, and b can be less than a.

bool Input::cut (  int  n  )  [inline]

Wrapper around replace() this deletes up to n characters after the point, or before the point if n is negative. N is bounds checked.

bool Input::cut (   )  [inline]

Wrapper around replace(), this deletes the region between the point and the mark. It does nothing if they are equal.

void Input::draw (  const Rectangle &  r  )

Draw the text, where the passed rectangle is the area the text is to be drawn into. This method is provided so a subclass can place the text into a subrectangle. If damage()&DAMAGE_ALL is true, this assummes the area has already been erased to color(). Otherwise it does minimal update and erases the area itself.

void Input::draw (  void   )  [virtual]

The default version draws the box and calls draw(x,y,w,h) with the area inside the box. It also draws any inside labels at the left of the text. Reimplemented from Widget.

int Input::handle (  int  event, const Rectangle &  r )

Default handler for all event types, where the passed rectangle is the area the text is to be drawn into. This method is provided so a subclass can place the text into a subrectangle. Handles FOCUS, UNFOCUS May do callback on HIDE Any keystrokes call handle_key() Handles PUSH, DRAG, RELEASE to select regions of text, move the cursor, and start drag & drop. Double click selects words, triple click selects lines (triple click is broken on Windows) Receives drag&drop and accepts. Handles PASTE events caused by accepting the drag&drop or by calling paste() (which handle_key() does for ^V)

int Input::handle (  int  event  )  [virtual]

Calls handle(x,y,w,h) with the area inside the box(). Reimplemented from Widget. Reimplemented in NumericInput.

bool Input::handle_key (   )

Handle KEY events. The handle() method calls this. This provides an Emacs and Windows style of editing. Most Emacs commands are first run through try_shortcut() to test if they are menu items for the program. Shift: do not move the mark when moving the point LeftKey, Ctrl+B: move left one character Ctrl+LeftKey, Alt+B: move left one word RightKey, Ctrl+F: move right one character Ctrl+RightKey, Alt+F: move right one word Ctrl+A: go to start of line, if already there select all text HomeKey: go to start of line EndKey, Ctrl+E: go to end of line Ctrl+Insert: copy Shift+Insert: paste Shift+Delete: cut Delete, Ctrl+D: delete region or one character Ctrl+Delete, Alt+D: delete region or one word BackSpace, Ctrl+H: delete region or left one character Ctrl+BackSpace, Alt+H: delete region or left one word Return, KeypadEnter: if when()&WHEN_ENTER_KEY, and no shift keys held down, this selects all and does the callback. Otherwise key is ignored. Ctrl+K: cuts from the position to the end of line Ctrl+C: copy Ctrl+T: swap the two characters around point. If point is at end swap the last two characters. Ctrl+U: delete all the text Ctrl+V: paste Ctrl+X, Ctrl+W: cut Ctrl+Y: redo Ctrl+Z, Ctrl+/: undo All printing characters are run through compose() and the result used to insert text. For the (obsolete) MULTILINE mode you can also do these: UpKey, Ctrl+P: move up one line (MULTILINE only) DownKey, Ctrl+N: move down one line (MULTILINE only) PageUpKey: move up 1 line less than the vertical widget size PageDownKey: move down 1 line less than the vertical widget size Ctrl+HomeKey, Alt+A: got to start of text Ctrl+EndKey, Alt+E: go to end of text Return, KeypadEnter: inserts a newline Ctrl+O: insert a newline and leave the cursor before it.

bool Input::insert (  const char *  text, int  n )  [inline]

Wrapper around replace(). This inserts n characters from the text (including '\0' characters!) at the point and leaves the point after it.

bool Input::insert (  const char *  text  )

Wrapper around replace(). This inserts the string at the point and leaves the point after it.

int Input::line_end (  int  i  )  const

Returns the location of the next newline or wordwrap space at or after position.

int Input::line_start (  int  i  )  const

Returns the location of the start of the line containing the position.

void Input::mark (  int  n  )  [inline]

Same as position(position(),n)

int Input::mouse_position (  const Rectangle &  r  )  const

Figure out what character the most recent mouse event would be pointing at, assumming you drew the text by calling draw() with the same rectangle. Returns 0 if the mouse is before the first character, and size() if it is after the last one.

void Input::position (  int  n  )  [inline]

Same as position(n,n)

void Input::position (  int  new_position, int  new_mark )

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 X selection, call copy() if you want that. Changing these values causes a redraw(). The new values are bounds checked and limited to the size of the string. It is up to the caller to make sure the position and mark are at the borders of UTF-8 characters! Reimplemented from Widget.

bool Input::replace (  int  a, int  b, char  c )  [inline]

Wrapper around replace(). Deletes the characters between a and b and then inserts the single byte c.

bool Input::replace (  int  b, int  e, const char *  text, int  ilen )  [virtual]

This call does all editing of the text. It deletes the region between b and e (either one may be less or equal to the other), and then inserts ilen (which may be zero) characters from the string text at that point and leaves the mark() and position() after the insertion. If the text is changed the callback is done if the when() flags indicate it should be done. Subclasses of Input can override this method to control what characters can be inserted into the text. A typical implementation will check the characters in the insertion for legality and then call Input::replace() only if they are all ok. b and e are bounds checked so don't worry about sending values outside the length of the string. Subclasses should return true if the keystroke that produced this call should be "eaten". If false is returned the keystroke is allowed to be tested as a shortcut for other widgets. In our experience it is best to return true even if you don't make changes. The base class version returns true always.

void Input::reserve (  int  len  )

Reserve the interal private buffer of at least len bytes, even if the current text() is not that long. Can be used to avoid unnecessary memory reallocations if you know you will be replacing the text() with a longer one later.

int Input::size (   )  const [inline]

Returns the number of characters in text(). This may be greater than strlen(text()) if there are NUL characters in it.

bool Input::static_text (  const char *  str, int  len )

Same as text(str,len), except it does not copy the string, instead it makes text() return a pointer to str (unless len is 0, in which case it makes it point to a zero-length string). str must point to static memory that will not be altered until at least the Input widget is destroyed or the text() is changed again. If the user attempts to edit the string it is then copied to the internal buffer and the editing done there. This can save a lot of time and memory if your program is changing the string to various constants a lot but the user rarely edits it.

bool Input::static_text (  const char *  str  )

Same as static_text(str, str ? strlen(str) : 0)

const char * Input::text (   )  const [inline]

The current string, as edited by the user. There is an extra NUL character at the end, so this returned pointer can be used directly by C functions. size() returns how many bytes are in the string, which is useful if you want to look at embedded NUL characters. Pointer is to an internal buffer and is only value until the next event is handled by the Input widget.

bool Input::text (  const char *  str, int  len )

Change the text() to return the first len bytes of str and size() to return len, and set the position() to len and the mark() to zero (thus highlighting the entire value). Returns true if the bytes in the new string are different than the old string.

bool Input::text (  const char *  str  )

Same as text(str, str ? strlen(str) : 0)

bool Input::undo (   )

If this is the most recent widget on which replace() was done on, this will undo that replace() and probably several others (ie if the user has typed a lot of text it will undo all of it even though that was probably many calls to replace()). Returns true if any change was made.

void Input::up_down_position (  int  i, bool  keepmark )

Do the correct thing for arrow keys. i must be the location of the start of a line. Sets the position (and mark if keepmark is false) to somewhere after i, such that pressing the arrows repeatedly will cause the point to move up and down.

int Input::word_end (  int  i  )  const

Returns the location of the next word boundary at or after position.

int Input::word_start (  int  i  )  const

Returns the location of the first word boundary at or before position.

---

The documentation for this class was generated from the following files:

• fltk/Input.h
• src/Input.cxx

---