nana::textbox Class Reference

Allow users to enter and edit text by typing on the keyboard. More...

Inheritance diagram for nana::textbox:

Public Types
using	colored_area_type = widgets::skeletons::colored_area_type
using	colored_area_access_interface = widgets::skeletons::colored_area_access_interface
using	text_focus_behavior = widgets::skeletons::text_focus_behavior
using	text_positions = std::vector< upoint >
using	path_type = std::filesystem::path
Public Types inherited from nana::widget_object< category::widget_tag, drawerbase::textbox::drawer, drawerbase::textbox::textbox_events,::nana::widgets::skeletons::text_editor_scheme >
using	scheme_type = ::nana::widgets::skeletons::text_editor_scheme
using	event_type = drawerbase::textbox::textbox_events
Public Types inherited from nana::widget
using	native_string_type = detail::native_string_type

Public Member Functions
	textbox ()
	The default constructor without creating the widget. More...
	textbox (window, bool visible)
	The construct that creates a widget. More...
	textbox (window, const std::string &text, bool visible=true)
	The construct that creates a widget with a specified text. More...
	textbox (window, const char *text, bool visible=true)
	The construct that creates a widget with a specified text. More...
	textbox (window, const rectangle &=rectangle(), bool visible=true)
	The construct that creates a widget. More...
void	load (const path_type &file)
	Loads a text file. When attempt to load a unicode encoded text file, be sure the file have a BOM header. More...
void	store (const path_type &file)
void	store (const path_type &file, nana::unicode encoding)
colored_area_access_interface *	colored_area_access ()
point	content_origin () const
textbox &	indention (bool, std::function< std::string()> generator={})
textbox &	reset (const std::string &text=std::string(), bool end_caret=true)
	discard the old text and set a new text More...
path_type	filename () const
	The file of last store operation. More...
bool	edited () const
	Determine whether the text was edited. More...
textbox &	edited_reset ()
	Reset the edited flag to false manually. More...
bool	saved () const
	Determine whether the changed text has been saved into the file. More...
bool	getline (std::size_t pos, std::string &) const
	Read the text from a specified line. It returns true for success. More...
bool	getline (std::size_t line_index, std::size_t offset, std::string &text) const
	Read the text from a specified line with a set offset. It returns true for success. More...
std::string	text () const
std::optional< std::string >	getline (std::size_t pos) const
	Read the text from a specified line; returns an empty optional on failure. More...
std::optional< std::string >	getline (std::size_t line_index, std::size_t offset) const
bool	caret_pos (point &pos, bool text_coordinate) const
	Gets the caret position. More...
upoint	caret_pos () const
	Gets the caret position, in text coordinate. More...
textbox &	caret_pos (const upoint &)
	Sets the caret position with a text position. More...
textbox &	append (const std::string &text, bool at_caret)
	Appends an string. If at_caret is true, the string is inserted at the position of caret, otherwise, it is appended at end of the textbox. More...
textbox &	append (const std::wstring &text, bool at_caret)
bool	line_wrapped () const
	Determines whether the text is line wrapped. More...
textbox &	line_wrapped (bool)
bool	multi_lines () const
	Determines whether the text is multi-line enabled. More...
textbox &	multi_lines (bool)
bool	editable () const
	Determines whether the textbox accepts user input. More...
textbox &	editable (bool)
textbox &	enable_caret ()
	Enables the caret if the textbox currently is not editable. More...
void	set_accept (std::function< bool(wchar_t)>)
textbox &	tip_string (::std::string)
textbox &	mask (wchar_t)
	Set a mask character. Text is displayed as mask character if a mask character is set. This is used for hiding some special text, such as password. More...
bool	selected () const
	Returns true if some text is selected. More...
bool	get_selected_points (nana::upoint &a, nana::upoint &b) const
void	select (bool)
	Selects/Deselects all text. More...
void	select_points (nana::upoint arg_a, nana::upoint arg_b)
std::pair< upoint, upoint >	selection () const
	Returns the bounds of a text selection. More...
void	copy () const
	Copies the selected text into shared memory, such as clipboard under Windows. More...
void	paste ()
	Pastes the text from shared memory. More...
void	del ()
int	to_int () const
double	to_double () const
textbox &	from (int)
textbox &	from (double)
void	clear_undo ()
void	set_highlight (const std::string &name, const ::nana::color &fgcolor, const ::nana::color &bgcolor)
void	erase_highlight (const std::string &name)
void	set_keywords (const std::string &name, bool case_sensitive, bool whole_word_match, std::initializer_list< std::wstring > kw_list)
void	set_keywords (const std::string &name, bool case_sensitive, bool whole_word_match, std::initializer_list< std::string > kw_list_utf8)
void	erase_keyword (const std::string &kw)
textbox &	text_align (::nana::align alignment)
	Sets the text alignment. More...
text_positions	text_position () const
	Returns the text position of each line that currently displays on screen. More...
rectangle	text_area () const
	Returns the rectangle of text area. More...
unsigned	line_pixels () const
	Returns the height of line in pixels. More...
void	focus_behavior (text_focus_behavior)
	Sets the behavior when textbox gets focus. More...
void	select_behavior (bool move_to_end)
void	set_undo_queue_length (std::size_t len)
	Sets the undo/redo queue length. More...
std::size_t	display_line_count () const noexcept
	Returns the number of lines that text are displayed in the screen. More...
std::size_t	text_line_count () const noexcept
	Returns the number of text lines. More...
Public Member Functions inherited from nana::widget_object< category::widget_tag, drawerbase::textbox::drawer, drawerbase::textbox::textbox_events,::nana::widgets::skeletons::text_editor_scheme >
	widget_object ()
	~widget_object ()
event_type &	events () const
bool	create (window parent_wd, bool visible)
bool	create (window parent_wd, const rectangle &r={}, bool visible=true)
widget_object &	borderless (bool enable)
bool	borderless () const
scheme_type &	scheme () const
void	filter_event (const event_code evt_code, const bool bDisabled)
void	filter_event (const std::vector< event_code > evt_codes, const bool bDisabled)
void	filter_event (const event_filter_status &evt_all_states)
bool	filter_event (const event_code evt_code)
event_filter_status	filter_event ()
void	clear_filter ()
Public Member Functions inherited from nana::detail::widget_base
window	handle () const override
	Returns the handle of window, returns 0 if window is not created. More...
Public Member Functions inherited from nana::widget
	widget ()=default
virtual	~widget ()=default
bool	empty () const
	Determines whether the manipulator is handling a window. More...
void	close ()
window	parent () const
::std::string	caption () const noexcept
::std::wstring	caption_wstring () const noexcept
native_string_type	caption_native () const noexcept
widget &	caption (std::string utf8)
widget &	caption (std::wstring)
template<typename... Args>
void	i18n (std::string msgid, Args &&...args)
void	i18n (i18n_eval)
void	cursor (nana::cursor)
nana::cursor	cursor () const
	Retrieves the shape of cursor. More...
void	typeface (const paint::font &font)
paint::font	typeface () const
bool	enabled () const
	Determines whether the window is enabled for mouse and keyboard input. More...
void	enabled (bool)
void	enable_dropfiles (bool)
	Enables/Disables a window to accept dropped files. More...
void	focus ()
bool	focused () const
std::shared_ptr < scroll_operation_interface >	scroll_operation ()
void	show ()
	Sets the window visible. More...
void	hide ()
	Sets the window invisible. More...
bool	visible () const
nana::size	size () const
void	size (const nana::size &)
void	set_capture (bool ignore_children)
	Enables the widget to grab the mouse input. More...
void	release_capture ()
	Disables the widget to grab the mouse input. More...
point	pos () const
void	move (int x, int y)
void	move (const point &)
void	move (const rectangle &)
void	fgcolor (const nana::color &)
nana::color	fgcolor () const
void	bgcolor (const nana::color &)
nana::color	bgcolor () const
general_events &	events () const
void	umake_event (event_handle eh) const
	Deletes an event callback by a handle. More...
widget &	register_shortkey (wchar_t)
	Registers a shortkey. To remove a registered key, pass 0. More...
widget &	take_active (bool activated, window take_if_not_activated)
widget &	tooltip (const ::std::string &)
	operator dummy_bool_type () const
	operator window () const

Protected Member Functions
native_string_type	_m_caption () const noexceptoverride
void	_m_caption (native_string_type &&) override
void	_m_typeface (const paint::font &) override
std::shared_ptr < scroll_operation_interface >	_m_scroll_operation () override
Protected Member Functions inherited from nana::widget_object< category::widget_tag, drawerbase::textbox::drawer, drawerbase::textbox::textbox_events,::nana::widgets::skeletons::text_editor_scheme >
drawerbase::textbox::drawer &	get_drawer_trigger ()
const drawerbase::textbox::drawer &	get_drawer_trigger () const
Protected Member Functions inherited from nana::widget
std::unique_ptr <::nana::detail::widget_notifier_interface >	_m_wdg_notifier ()
virtual void	_m_complete_creation ()
virtual nana::cursor	_m_cursor () const
virtual void	_m_cursor (nana::cursor)
virtual void	_m_close ()
virtual bool	_m_enabled () const
virtual void	_m_enabled (bool)
virtual bool	_m_show (bool)
virtual bool	_m_visible () const
virtual void	_m_size (const nana::size &)
virtual void	_m_move (int x, int y)
virtual void	_m_move (const rectangle &)
virtual nana::paint::font	_m_typeface () const
virtual void	_m_fgcolor (const nana::color &)
virtual nana::color	_m_fgcolor () const
virtual void	_m_bgcolor (const nana::color &)
virtual nana::color	_m_bgcolor () const

Additional Inherited Members
Protected Types inherited from nana::widget_object< category::widget_tag, drawerbase::textbox::drawer, drawerbase::textbox::textbox_events,::nana::widgets::skeletons::text_editor_scheme >
typedef drawerbase::textbox::drawer	drawer_trigger_t
Protected Attributes inherited from nana::detail::widget_base
window	handle_ { nullptr }

Detailed Description

Allow users to enter and edit text by typing on the keyboard.

1. The return type of the ext_event() coming with textbox, its defined as

    struct implement-specifed
    {
       nana::fn_group<void()> first_change; 
       ;//An event for the text first change after text is been opened or stored.
    };
   

   An instance of first change Some text editor programs, such as vim or *notepad++*, when the text is being modified, the caption of the window will display a special character (such as * ~ +) to indicate changing of text. To implement this feature, you can set a function to the first change for modifying the caption of your window.

2. The tip string is displayed when textbox is empty and the tip string will be hidden after textbox gets the focus.

Examples:

listbox_inline_widget.cpp, notepad.cpp, place_login.cpp, widget_show.cpp, and widget_show2.cpp.

Member Typedef Documentation

using nana::textbox::colored_area_access_interface = widgets::skeletons::colored_area_access_interface

using nana::textbox::colored_area_type = widgets::skeletons::colored_area_type

using nana::textbox::path_type = std::filesystem::path

using nana::textbox::text_focus_behavior = widgets::skeletons::text_focus_behavior

using nana::textbox::text_positions = std::vector<upoint>

Constructor & Destructor Documentation

nana::textbox::textbox

(

)

The default constructor without creating the widget.

nana::textbox::textbox	(	window	wd,
		bool	visible
	)

The construct that creates a widget.

Parameters

wd	A handle to the parent window of the widget being created.
visible	specifying the visible after creating.

nana::textbox::textbox	(	window	wd,
		const std::string &	text,
		bool	visible = true
	)

The construct that creates a widget with a specified text.

Parameters

window	A handle to the parent window of the widget being created.
text	the text that will be displayed.
visible	specifying the visible after creating.

nana::textbox::textbox	(	window	wd,
		const char *	text,
		bool	visible = true
	)

The construct that creates a widget with a specified text.

Parameters

window	A handle to the parent window of the widget being created.
text	the text that will be displayed.
visible	specifying the visible after creating.

nana::textbox::textbox	(	window	wd,
		const rectangle &	r = rectangle(),
		bool	visible = true
	)

The construct that creates a widget.

Parameters

window	A handle to the parent window of the widget being created.
rectangle	the size and position of the widget in its parent window coordinate.
visible	specifying the visible after creating.

Member Function Documentation

auto nana::textbox::_m_caption ( ) const

overrideprotectedvirtualnoexcept

Reimplemented from nana::widget.

void nana::textbox::_m_caption ( native_string_type &&  str )

overrideprotectedvirtual

Reimplemented from nana::widget.

std::shared_ptr< scroll_operation_interface > nana::textbox::_m_scroll_operation ( )

overrideprotectedvirtual

Reimplemented from nana::widget.

void nana::textbox::_m_typeface ( const paint::font &  font )

overrideprotectedvirtual

Reimplemented from nana::widget.

textbox & nana::textbox::append	(	const std::string &	text,
		bool	at_caret
	)

Appends an string. If at_caret is true, the string is inserted at the position of caret, otherwise, it is appended at end of the textbox.

textbox & nana::textbox::append	(	const std::wstring &	text,
		bool	at_caret
	)

bool nana::textbox::caret_pos	(	point &	pos,
		bool	text_coordinate
	)		const

Gets the caret position.

Gets the caret position Returns true if the caret is in the area of display, false otherwise.

upoint nana::textbox::caret_pos

(

)

const

Gets the caret position, in text coordinate.

textbox & nana::textbox::caret_pos

(

const upoint &

pos

)

Sets the caret position with a text position.

void nana::textbox::clear_undo

(

)

textbox::colored_area_access_interface * nana::textbox::colored_area_access

(

)

point nana::textbox::content_origin

(

)

const

void nana::textbox::copy

(

)

const

Copies the selected text into shared memory, such as clipboard under Windows.

void nana::textbox::del

(

)

std::size_t nana::textbox::display_line_count ( ) const

noexcept

Returns the number of lines that text are displayed in the screen.

The number of display lines may be not equal to the number of text lines when the textbox is line wrapped mode.

Returns

the number of lines that text are displayed in the screen.

bool nana::textbox::editable

(

)

const

Determines whether the textbox accepts user input.

textbox & nana::textbox::editable

(

bool

able

)

bool nana::textbox::edited

(

)

const

Determine whether the text was edited.

textbox & nana::textbox::edited_reset

(

)

Reset the edited flag to false manually.

textbox & nana::textbox::enable_caret

(

)

Enables the caret if the textbox currently is not editable.

void nana::textbox::erase_highlight

(

const std::string &

name

)

void nana::textbox::erase_keyword

(

const std::string &

kw

)

textbox::path_type nana::textbox::filename

(

)

const

The file of last store operation.

void nana::textbox::focus_behavior

(

text_focus_behavior

behavior

)

Sets the behavior when textbox gets focus.

textbox & nana::textbox::from

(

int

n

)

textbox & nana::textbox::from

(

double

d

)

bool nana::textbox::get_selected_points	(	nana::upoint &	a,
		nana::upoint &	b
	)		const

bool nana::textbox::getline	(	std::size_t	pos,
		std::string &	text
	)		const

Read the text from a specified line. It returns true for success.

bool nana::textbox::getline	(	std::size_t	line_index,
		std::size_t	offset,
		std::string &	text
	)		const

Read the text from a specified line with a set offset. It returns true for success.

std::optional< std::string > nana::textbox::getline

(

std::size_t

pos

)

const

Read the text from a specified line; returns an empty optional on failure.

std::optional< std::string > nana::textbox::getline	(	std::size_t	line_index,
		std::size_t	offset
	)		const

Read the text from a specified line with a set offset. Returns an empty optional for failure.

textbox & nana::textbox::indention	(	bool	enb,
		std::function< std::string()>	generator = {}
	)

Enables/disables the textbox to indent a line. Idents a new line when it is created by pressing enter.

Parameters

generator

generates text for identing a line. If it is empty, textbox indents the line according to last line.

Enables/disables the textbox to indent a line. Indents a new line when it is created by pressing enter.

Parameters

generator

generates text for indenting a line. If it is empty, textbox indents the line according to last line.

unsigned nana::textbox::line_pixels

(

)

const

Returns the height of line in pixels.

bool nana::textbox::line_wrapped

(

)

const

Determines whether the text is line wrapped.

Determine whether the text is auto-line changed.

textbox & nana::textbox::line_wrapped

(

bool

autl

)

void nana::textbox::load

(

const path_type &

file

)

Loads a text file. When attempt to load a unicode encoded text file, be sure the file have a BOM header.

textbox & nana::textbox::mask

(

wchar_t

ch

)

Set a mask character. Text is displayed as mask character if a mask character is set. This is used for hiding some special text, such as password.

bool nana::textbox::multi_lines

(

)

const

Determines whether the text is multi-line enabled.

textbox & nana::textbox::multi_lines

(

bool

ml

)

void nana::textbox::paste

(

)

Pastes the text from shared memory.

textbox & nana::textbox::reset	(	const std::string &	text = std::string(),
		bool	end_caret = true
	)

discard the old text and set a new text

Discards the old text and set a new text. It also clears the filename/edited flags and undo command. A workaround for reset, explicit default constructor syntax, because VC2013 incorrectly treats {} as {0}.

bool nana::textbox::saved

(

)

const

Determine whether the changed text has been saved into the file.

void nana::textbox::select

(

bool

yes

)

Selects/Deselects all text.

void nana::textbox::select_behavior

(

bool

move_to_end

)

Sets the caret move behavior when the content of textbox is selected. E.g. Whether caret moves to left of selected content or moves to left of last position when left arrow key is pressed.

Parameters

move_to_end

determines whether to move caret to left of selected_content or to left of last position.

void nana::textbox::select_points	(	nana::upoint	arg_a,
		nana::upoint	arg_b
	)

bool nana::textbox::selected

(

)

const

Returns true if some text is selected.

std::pair< upoint, upoint > nana::textbox::selection

(

)

const

Returns the bounds of a text selection.

Returns

no selection if pair.first == pair.second.

void nana::textbox::set_accept

(

std::function< bool(wchar_t)>

fn

)

void nana::textbox::set_highlight	(	const std::string &	name,
		const ::nana::color &	fgcolor,
		const ::nana::color &	bgcolor
	)

void nana::textbox::set_keywords	(	const std::string &	name,
		bool	case_sensitive,
		bool	whole_word_match,
		std::initializer_list< std::wstring >	kw_list
	)

void nana::textbox::set_keywords	(	const std::string &	name,
		bool	case_sensitive,
		bool	whole_word_match,
		std::initializer_list< std::string >	kw_list_utf8
	)

void nana::textbox::set_undo_queue_length

(

std::size_t

len

)

Sets the undo/redo queue length.

Parameters

len	The length of the queue. If this parameter is zero, the undo/redo is disabled.

void nana::textbox::store

(

const path_type &

file

)

void nana::textbox::store	(	const path_type &	file,
		nana::unicode	encoding
	)

std::string nana::textbox::text ( ) const

inline

textbox & nana::textbox::text_align

(

::nana::align

alignment

)

Sets the text alignment.

rectangle nana::textbox::text_area

(

)

const

Returns the rectangle of text area.

std::size_t nana::textbox::text_line_count ( ) const

noexcept

Returns the number of text lines.

std::vector< upoint > nana::textbox::text_position

(

)

const

Returns the text position of each line that currently displays on screen.

textbox & nana::textbox::tip_string

(

::std::string

)

double nana::textbox::to_double

(

)

const

int nana::textbox::to_int

(

)

const