fltk::Input Class Reference

Inherits fltk::Widget.

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

List of all members.

Public Member Functions
char	at (int i) const
bool	copy (bool clipboard=true)
bool	cut ()
bool	cut (int n)
bool	cut (int a, int b)
void	draw (const Rectangle &)
void	draw ()
int	handle (int)
int	handle (int event, const Rectangle &)
bool	handle_key ()
	Input (int, int, int, int, const char *=0)
bool	insert (const char *t)
bool	insert (const char *t, int l)
int	line_end (int i) const
int	line_start (int i) const
void	mark (int m)
int	mouse_position (const Rectangle &) const
void	position (int p, int m)
void	position (int p)
bool	replace (int a, int b, char c)
virtual bool	replace (int, int, const char *, int)
void	reserve (int newsize)
int	size () const
bool	static_text (const char *, int)
bool	static_text (const char *)
bool	text (const char *, int)
const char *	text () const
bool	text (const char *)
bool	undo ()
void	up_down_position (int position, bool extend)
int	word_end (int i) const
int	word_start (int i) const
	~Input ()
Private Member Functions
void	erase_cursor_at (int p)
const char *	expand (const char *, char *, int) const
float	expandpos (const char *, const char *, const char *, int *) const
void	minimal_update (int p)
void	minimal_update (int, int)
void	shift_position (int p)
void	shift_up_down_position (int p)

---

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 fltk::utf8decode()).

The default when() is WHEN_RELEASE. This is fine for a popup control panel where nothing happens until the panel is closed. But for most other uses of the input field you want to change it. Useful values are:

• fltk::WHEN_NEVER: The callback is not done, but changed() is turned on.
• fltk::WHEN_CHANGED: The callback is done each time the text is changed by the user.
• fltk::WHEN_ENTER_KEY: Hitting the enter key after changing the text will cause the callback.
• fltk::WHEN_ENTER_KEY_ALWAYS: The Enter key will do the callback even if the text has not changed. Useful for command fields. Also you need to do this if you want both the enter key and either fltk::WHEN_CHANGED or fltk::WHEN_RELEASE, in this case you can tell if Enter was typed by testing fltk::event_key()==fltkReturnKey.
• fltk::WHEN_RELEASE: Deprecated. The callback is done if the text has changed and the user clicks on another widget or the focus moves (which can happen due to the window this widget is on being closed).

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 fltk::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 fltk::paste(true) and fltk will send the widget a fltk::PASTE event with the text, which will cause it to be inserted.

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	(	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

(

)

[inline]

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

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 fltk::Widget.

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()&fltk::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::erase_cursor_at

(

int

p

)

[private]

Indicate that a cursor drawn a postion p must be redrawn.

const char * Input::expand	(	const char *	p,
		char *	buf,
		int	wordwrap
	)		const [private]

Copy string p to the buffer, replacing control characters with ^X. Stop at then end of the line, or truncate if necessary so the resulting string and null terminator fits in a buffer of size MAXBUF. Returns pointer to the character after the last one copied.

float Input::expandpos	(	const char *	p,
		const char *	e,
		const char *	buf,
		int *	returnn
	)		const [private]

After filling in a buffer with expand(), find the width to e.

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 fltk::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 fltk::Widget.

Reimplemented in fltk::NumericInput, and fltk::Output.

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 fltk::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 fltk::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)

void Input::minimal_update	(	int	p,
		int	q
	)		[private]

Indicate that the characters between positions p and q must be redrawn. Currently this just does minimal_update(min(p,q)).

void Input::minimal_update

(

int

p

)

[private]

Indicate that the characters after position p must be redrawn. This is done with a clip region to work with xft. The purpose is to avoid blinking, not to make draw() less expensive. A few minor attempts to make draw() not think about clipped text are implemented, though.

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	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 fltk::Widget.

void Input::position

(

int

n

)

[inline]

Same as position(n,n)

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.

Reimplemented in fltk::FloatInput, and fltk::Output.

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.

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.

void Input::shift_position

(

int

p

)

[private]

Move the point, move the mark only if shift is not held down.

void Input::shift_up_down_position

(

int

p

)

[private]

Move the point, move the mark only if shift is not held down.

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

)

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

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::text

(

const char *

str

)

Same as 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::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