Nana C++ Library. Reference for users.
What we need to use nana
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages
nana::textbox Class Reference

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

Inheritance diagram for nana::textbox:
nana::widget_object< category::widget_tag, drawerbase::textbox::drawer, drawerbase::textbox::textbox_events,::nana::widgets::skeletons::text_editor_scheme > nana::detail::widget_base nana::widget

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_interfacecolored_area_access ()
 
point content_origin () const
 
textboxindention (bool, std::function< std::string()> generator={})
 
textboxreset (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...
 
textboxedited_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::stringgetline (std::size_t pos) const
 Read the text from a specified line; returns an empty optional on failure. More...
 
std::optional< std::stringgetline (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...
 
textboxcaret_pos (const upoint &)
 Sets the caret position with a text position. More...
 
textboxappend (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...
 
textboxappend (const std::wstring &text, bool at_caret)
 
bool line_wrapped () const
 Determines whether the text is line wrapped. More...
 
textboxline_wrapped (bool)
 
bool multi_lines () const
 Determines whether the text is multi-line enabled. More...
 
textboxmulti_lines (bool)
 
bool editable () const
 Determines whether the textbox accepts user input. More...
 
textboxeditable (bool)
 
textboxenable_caret ()
 Enables the caret if the textbox currently is not editable. More...
 
void set_accept (std::function< bool(wchar_t)>)
 
textboxtip_string (::std::string)
 
textboxmask (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, upointselection () 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
 
textboxfrom (int)
 
textboxfrom (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)
 
textboxtext_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_typeevents () const
 
bool create (window parent_wd, bool visible)
 
bool create (window parent_wd, const rectangle &r={}, bool visible=true)
 
widget_objectborderless (bool enable)
 
bool borderless () const
 
scheme_typescheme () 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
 
widgetcaption (std::string utf8)
 
widgetcaption (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_eventsevents () const
 
void umake_event (event_handle eh) const
 Deletes an event callback by a handle. More...
 
widgetregister_shortkey (wchar_t)
 Registers a shortkey. To remove a registered key, pass 0. More...
 
widgettake_active (bool activated, window take_if_not_activated)
 
widgettooltip (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::drawerget_drawer_trigger ()
 
const drawerbase::textbox::drawerget_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::path_type = std::filesystem::path

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
wdA handle to the parent window of the widget being created.
visiblespecifying 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
windowA handle to the parent window of the widget being created.
textthe text that will be displayed.
visiblespecifying 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
windowA handle to the parent window of the widget being created.
textthe text that will be displayed.
visiblespecifying the visible after creating.
nana::textbox::textbox ( window  wd,
const rectangle r = rectangle(),
bool  visible = true 
)

The construct that creates a widget.

Parameters
windowA handle to the parent window of the widget being created.
rectanglethe size and position of the widget in its parent window coordinate.
visiblespecifying 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
generatorgenerates 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
generatorgenerates 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_enddetermines 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
lenThe 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