gp_widget_tbox.h File Reference

A textbox widget. More...

#include <utils/gp_seek.h>
#include <utils/gp_utf_pos.h>

Go to the source code of this file.

Enumerations
enum	gp_widget_tbox_type {   GP_WIDGET_TBOX_NONE , GP_WIDGET_TBOX_HIDDEN , GP_WIDGET_TBOX_URL , GP_WIDGET_TBOX_PATH ,   GP_WIDGET_TBOX_FILENAME , GP_WIDGET_TBOX_MAX }
	Text box type. More...
enum	gp_widget_tbox_event_type {   GP_WIDGET_TBOX_TRIGGER , GP_WIDGET_TBOX_PRE_FILTER , GP_WIDGET_TBOX_POST_FILTER , GP_WIDGET_TBOX_EDIT ,   GP_WIDGET_TBOX_SET , GP_WIDGET_TBOX_PASTE }
	A gp_widget_event::sub_type for tbox widget events. More...

Functions
gp_widget *	gp_widget_tbox_new (const char *text, gp_widget_tattr tattr, unsigned int len, unsigned int max_len, const char *filter, enum gp_widget_tbox_type type)
	Create a tbox widget.
int	gp_widget_tbox_printf (gp_widget *self, const char *fmt,...) __attribute__((format(printf
	A printf-like function to set a tbox text.
int void	gp_widget_tbox_set (gp_widget *self, const char *str)
	Sets a tbox text.
void	gp_widget_tbox_clear (gp_widget *self)
	Clears the tbox text.
const char *	gp_widget_tbox_text (gp_widget *self)
	Returns a tbox string.
static int	gp_widget_tbox_is_empty (gp_widget *self)
	Returns true if tbox is empty.
gp_utf8_pos	gp_widget_tbox_cursor_get (gp_widget *self)
	Returns current cursor postion.
void	gp_widget_tbox_cursor_set (gp_widget *self, ssize_t off, enum gp_seek_whence whence)
	Moves a cursor to a defined position.
void	gp_widget_tbox_ins (gp_widget *self, ssize_t off, enum gp_seek_whence whence, const char *str)
	Inserts a string into a tbox.
static void	gp_widget_tbox_append (gp_widget *self, const char *str)
	Appends a string to the textbox.
void	gp_widget_tbox_del (gp_widget *self, ssize_t off, enum gp_seek_whence whence, size_t len)
	Deletes a len characters from a tbox.
void	gp_widget_tbox_sel_set (gp_widget *self, ssize_t off, enum gp_seek_whence whence, size_t len)
	Sets selection.
void	gp_widget_tbox_sel_all (gp_widget *self)
	Selects whole textbox text.
void	gp_widget_tbox_sel_clr (gp_widget *self)
	Clears selection.
void	gp_widget_tbox_sel_del (gp_widget *self)
	Deletes selected characters.
gp_utf8_pos	gp_widget_tbox_sel_len (gp_widget *self)
	Returns selection lenght.
gp_utf8_pos	gp_widget_tbox_sel_off (gp_widget *self)
	Returns selection offset, i.e. first character.
static int	gp_widget_tbox_sel (gp_widget *self)
	Returns true if text is selected.
void	gp_widget_tbox_sel_delim_set (gp_widget *self, const char *delim)
	Sets textbox selection delimiters.
void	gp_widget_tbox_type_set (gp_widget *self, enum gp_widget_tbox_type type)
	Sets textbox type.
void	gp_widget_tbox_help_set (gp_widget *self, const char *help)
	Sets textbox help text.
void	gp_widget_tbox_clear_on_input (gp_widget *self)
	Sets one time flag that clears the text on next input event.
void	gp_widget_tbox_filter_set (gp_widget *self, const char *filter)
	Sets a textbox filter string.

Detailed Description

A textbox widget.

Tbox widget JSON attributes

Attribute	Type	Default	Description
text	string	""	Initial textbox text.
help	string	""	Help text, shown when textbox is empty.
ttype	string	"none"	One of "none", "hidden", "URL", "path", "filename". See gp_widget_tbox_type.
len	uint		Number of characters the texbox should be able to fit to display.
max_len	uint		Maximal number of unicode characters the textbox can hold.
tattr	string	normal	A text attribute, parsed by gp_widget_tattr_parse().
sel_delim	string	whitespaces	If set any character from the string is selection delimiter.

Definition in file gp_widget_tbox.h.

Enumeration Type Documentation

gp_widget_tbox_event_type

enum gp_widget_tbox_event_type

A gp_widget_event::sub_type for tbox widget events.

Enumerator
GP_WIDGET_TBOX_TRIGGER	Emitted when enter is pressed.
GP_WIDGET_TBOX_PRE_FILTER	Emitted to filter out a character before text was modified. The unicode character to be added to the text box is passed in gp_widget_event::val and the text box text is unmodified. By returning 0 from the gp_widget::on_event callback the change is approved and can proceed further.
GP_WIDGET_TBOX_POST_FILTER	Emitted to filter out a character after text modified. The unicode character that has been added to the text box is passed in gp_widget_event::val and the text box text has this character inserted at the cursor position. The cursor is not moved to a next position until the filter approves the character insertion. By returning 0 from the gp_widget::on_event callback the change is approved and can proceed further. Otherwise the changes to text box text are undone.
GP_WIDGET_TBOX_EDIT	Emitted after text is entered. This event is set each time a text box text is modified.
GP_WIDGET_TBOX_SET	Emitted when text box is modified. Emitted after text is set by: gp_widget_tbox_set() gp_widget_tbox_printf() gp_widget_tbox_clear() or modified by: gp_widget_tbox_ins() gp_widget_tbox_append() and gp_widget_tbox_del()
GP_WIDGET_TBOX_PASTE	Emitted before text is pasted. The text is then added one character at atime and filter events are generated for each character.

Definition at line 73 of file gp_widget_tbox.h.

gp_widget_tbox_type

enum gp_widget_tbox_type

Text box type.

Text box type modifies the way textbox is rendered or behaves.

Enumerator
GP_WIDGET_TBOX_NONE	No type, this is default.
GP_WIDGET_TBOX_HIDDEN	Hidden text, e.g. password. When set the text box shows asterisks or circles instead of characters.
GP_WIDGET_TBOX_URL	An URL. When set the selection delimiters is set to "/".
GP_WIDGET_TBOX_PATH	A filesystem path. When set the selection delimiters is set to "/".
GP_WIDGET_TBOX_FILENAME	A file name. When set the selection delimiters is set to ".".

Definition at line 38 of file gp_widget_tbox.h.

Function Documentation

gp_widget_tbox_append()

static void gp_widget_tbox_append ( gp_widget *  self, const char *  str  )

inlinestatic

Appends a string to the textbox.

Parameters

self	A tbox widget.
str	A string to append.

Definition at line 244 of file gp_widget_tbox.h.

References gp_widget_tbox_ins().

gp_widget_tbox_clear()

void gp_widget_tbox_clear

(

gp_widget *

self

)

Clears the tbox text.

Parameters

self	A tbox widget.

gp_widget_tbox_clear_on_input()

void gp_widget_tbox_clear_on_input

(

gp_widget *

self

)

Sets one time flag that clears the text on next input event.

Parameters

self	A tbox widget.

gp_widget_tbox_cursor_get()

gp_utf8_pos gp_widget_tbox_cursor_get

(

gp_widget *

self

)

Returns current cursor postion.

Parameters

self	A tbox widget.

Returns

Current cursor position.

gp_widget_tbox_cursor_set()

void gp_widget_tbox_cursor_set	(	gp_widget *	self,
		ssize_t	off,
		enum gp_seek_whence	whence
	)

Moves a cursor to a defined position.

The whence works exactly as it would have for lseek(2). E.g. to move the cursor one character back the whence would be set to GP_SEEK_CUR and off to -1.

Parameters

self	A tbox widget.
off	An offset.
whence	Whence for the offset.

gp_widget_tbox_del()

void gp_widget_tbox_del	(	gp_widget *	self,
		ssize_t	off,
		enum gp_seek_whence	whence,
		size_t	len
	)

Deletes a len characters from a tbox.

The whence works exactly as it would have for lseek(2).

If we are deleting a text before cursor, the cursor moves as well. If text is deleted after cursor, the cursor stays on its position.

Parameters

self	A tbox widget.
off	An offset.
whence	A whence for the offset.
len	A number of characters to delete.

gp_widget_tbox_filter_set()

void gp_widget_tbox_filter_set	(	gp_widget *	self,
		const char *	filter
	)

Sets a textbox filter string.

If filter string is set only characters from the filter can be entered into the textbox.

Parameters

self	A textbox widget.
filter	A filter string.

gp_widget_tbox_help_set()

void gp_widget_tbox_help_set	(	gp_widget *	self,
		const char *	help
	)

Sets textbox help text.

Passing NULL as text will clear the help text.

The help is shown as gray text inside the textbox when it's empty.

Parameters

self	A tbox widget.
help	An utf8 help text.

gp_widget_tbox_ins()

void gp_widget_tbox_ins	(	gp_widget *	self,
		ssize_t	off,
		enum gp_seek_whence	whence,
		const char *	str
	)

Inserts a string into a tbox.

The whence works exactly as it would have for lseek(2).

If we are inserting a text before cursor, the cursor moves as well. If text is inserted after cursor, the cursor stays on its position.

Parameters

self	A tbox widget.
off	An offset.
whence	A whence for the offset.
str	A string.

Referenced by gp_widget_tbox_append().

gp_widget_tbox_is_empty()

static int gp_widget_tbox_is_empty ( gp_widget *  self )

inlinestatic

Returns true if tbox is empty.

Parameters

self	A tbox widget.

Returns

Non-zero if tbox is empty zero otherwise.

Definition at line 189 of file gp_widget_tbox.h.

References gp_widget_tbox_text().

gp_widget_tbox_new()

gp_widget * gp_widget_tbox_new	(	const char *	text,
		gp_widget_tattr	tattr,
		unsigned int	len,
		unsigned int	max_len,
		const char *	filter,
		enum gp_widget_tbox_type	type
	)

Create a tbox widget.

Parameters

text	Initial tbox text, pass NULL for empty text box.
tattr	A text attribute e.g. monospace font.
len	Expected text length, used for widget size computation.
max_len	Maximal number of characters, can be used as a hard limit.
filter	If set only characters from the string can be typed into the tbox.
type	Text box type.

Returns

A newly allocate and initialized tbox widget.

gp_widget_tbox_printf()

int gp_widget_tbox_printf	(	gp_widget *	self,
		const char *	fmt,
			...
	)

A printf-like function to set a tbox text.

Parameters

self	A tbox widget.
fmt	A printf-like format string.
...	A printf-like parameters.

Returns

A tbox string lenght or -1 on a failure.

gp_widget_tbox_sel()

static int gp_widget_tbox_sel ( gp_widget *  self )

inlinestatic

Returns true if text is selected.

Parameters

self	A tbox widget.

Returns

Non-zero if text is selected.

Definition at line 325 of file gp_widget_tbox.h.

References gp_utf8_pos::bytes, and gp_widget_tbox_sel_len().

gp_widget_tbox_sel_all()

void gp_widget_tbox_sel_all

(

gp_widget *

self

)

Selects whole textbox text.

When selection is set the cursor is moved to the end of the selection.

Parameters

self	A tbox widget.

gp_widget_tbox_sel_clr()

void gp_widget_tbox_sel_clr

(

gp_widget *

self

)

Clears selection.

Parameters

self	A tbox widget.

gp_widget_tbox_sel_del()

void gp_widget_tbox_sel_del

(

gp_widget *

self

)

Deletes selected characters.

Parameters

self	A tbox widget.

gp_widget_tbox_sel_delim_set()

void gp_widget_tbox_sel_delim_set	(	gp_widget *	self,
		const char *	delim
	)

Sets textbox selection delimiters.

Any of the characters from delim will limit selection on double click.

Default delimiters are whitespaces. For some textbox types delimiters are set as well e.g. for GP_WIDGET_TYPE_PATH the delimiters are set to "/".

Parameters

self	A tbox widget.
delim	A string containing delimiters.

gp_widget_tbox_sel_len()

gp_utf8_pos gp_widget_tbox_sel_len

(

gp_widget *

self

)

Returns selection lenght.

Parameters

self	A tbox widget.

Returns

A text selection lenght, 0 when no text is selected.

Referenced by gp_widget_tbox_sel().

gp_widget_tbox_sel_off()

gp_utf8_pos gp_widget_tbox_sel_off

(

gp_widget *

self

)

Returns selection offset, i.e. first character.

Parameters

self	A tbox widget.

Returns

A text selection offset, 0 when no text is selected.

gp_widget_tbox_sel_set()

void gp_widget_tbox_sel_set	(	gp_widget *	self,
		ssize_t	off,
		enum gp_seek_whence	whence,
		size_t	len
	)

Sets selection.

When selection is set the cursor is moved to the end of the selection.

Parameters

self	A tbox widget.
off	An offset.
whence	A whence for the offset.
len	A selection length.

gp_widget_tbox_set()

int void gp_widget_tbox_set	(	gp_widget *	self,
		const char *	str
	)

Sets a tbox text.

Parameters

self	A tbox widget.
str	A string.

gp_widget_tbox_text()

const char * gp_widget_tbox_text

(

gp_widget *

self

)

Returns a tbox string.

Parameters

self	A tbox widget.

Returns

Texbox widget string.

Referenced by gp_widget_tbox_is_empty().

gp_widget_tbox_type_set()

void gp_widget_tbox_type_set	(	gp_widget *	self,
		enum gp_widget_tbox_type	type
	)

Sets textbox type.

Textbox type changes default behaviors, e.g. if type is set to hidden asterisks are shown instead of letters.

Other types set the selection delimiter lists, etc.

Parameters

self	A tbox widget.
type	A tbox type.