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

Define a label widget (can dispaly a formated text string and images). Provides the interfaces to be operational. More...

Inheritance diagram for nana::label:
nana::widget_object< category::widget_tag, drawerbase::label::trigger > nana::detail::widget_base nana::widget

Public Types

typedef drawerbase::label::command command
- Public Types inherited from nana::widget_object< category::widget_tag, drawerbase::label::trigger >
using scheme_type = ::nana::widget_geometrics
using event_type = ::nana::general_events
- Public Types inherited from nana::widget
using native_string_type = detail::native_string_type

Public Member Functions

 label ()
 label (window, bool visible)
 label (window, const std::string &text, bool visible=true)
 label (window parent, const char *text, bool visible=true)
 label (window, const rectangle &={}, bool visible=true)
labeltransparent (bool)
 Switchs the label widget to the transparent background mode. More...
bool transparent () const noexcept
labelformat (bool)
 Switches the format mode of the widget. More...
labeladd_format_listener (std::function< void(command, const std::string &)>)
labelclick_for (window associated_window) noexcept
 as same as the HTML "for" attribute of a label More...
nana::size measure (unsigned allowed_width_in_pixel) const
labeltext_align (align horizontal_align, align_v vertical_align=align_v::top)
- Public Member Functions inherited from nana::widget_object< category::widget_tag, drawerbase::label::trigger >
 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
< 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

Static Public Member Functions

::nana::size measure (::nana::paint::graphics &, const ::std::string &, unsigned allowed_width_in_pixel, bool format_enabled, align h_align, align_v v_align)

Additional Inherited Members

- Protected Types inherited from nana::widget_object< category::widget_tag, drawerbase::label::trigger >
typedef drawerbase::label::trigger drawer_trigger_t
- Protected Member Functions inherited from nana::widget_object< category::widget_tag, drawerbase::label::trigger >
drawerbase::label::triggerget_drawer_trigger ()
const drawerbase::label::triggerget_drawer_trigger () const
- Protected Member Functions inherited from nana::widget
_m_wdg_notifier ()
virtual void _m_complete_creation ()
virtual native_string_type _m_caption () const noexcept
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 std::shared_ptr
< scroll_operation_interface
_m_scroll_operation ()
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 void _m_typeface (const nana::paint::font &font)
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
- Protected Attributes inherited from nana::detail::widget_base
window handle_ { nullptr }

Detailed Description

Define a label widget (can dispaly a formated text string and images). Provides the interfaces to be operational.

A New Label


  1. It is not efficient when the background mode of the label is transparent.
  2. If the caption of a label contains a character '\n', the label will hide the character and display the text string after '\n' in a new line.
  3. The format mode accepts the definition for displaying mutile-style text. For example.
                     label.caption(STR("Hello, <bold=true>This is a bold text</>"));
                     label.caption(STR("Hello, <bold=true, color=0xff0000>This is a bold red text</>"));
                     label.caption(STR("Hello, <bold=true, color=0xff0000, font=\"Consolas\">This is a bold red Consolas text</>"));
                     label.caption(STR("Hello, <bold=true, color=0xff0000, font=\"Consolas\", url=\"\">This is a bold red Consolas text</>"));
     The arrow mouse cursor becomes a hand when the cursor moves over the red text. Meanwhile, it is open a web browser to open the URL by clicking the red text.
     __NOTE: the url only works under Windows__
             using namespace nana::gui;
             ;//void listener(label::command cmd, const nana::string& s) //C++11
             void listener(label::command::t cmd, const nana::string& s)
                     if(label::command::click == cmd)
                             msgbox mb(STR("target clicked"));
                             mb << STR("the target \"") << s << "\" is clicked";
             int main()
                     form fm;
                     label lab(fm, nana::rectangle(0, 0, 100, 40));
                     lab.caption(STR("Click <color=0xFF, target=\"target id\">here</>"));
  4. Some reserved words: red, green, blue, white, black. It can simplify the format text and increas it readable.
             lab.caption(STR("Click <color=0xFF target=\"target id\">here</>"));
             lab.caption(STR("Click <blue target=\"target id\">here</>"));
  5. Image is supported for format mode.
             lab.caption(STR("<image=\"file.bmp\"><bold red size=20>Nana C++ Library</>"));
     As you see, the image tag has not a close-tag </>.
     Defaultly, the image is displayed with its orignal size. With specifying a size, we can get a proper size by which the image is displayed.
             label.caption(STR("<image=\"file.bmp\" size=(150,150)><bold red size=20>Nana C++ Library</>"));
     ![Specifying a proper size](label_image.png)
     `size=(150,150)` means that it stretchs the image to the specified size.
     In many situations, we want to display the image as it is if it is greater than/less than a specified size. There are two reserved words can achieve it.
     `max_limited`: stretchs the image to the specified size preserving the aspect ratio when one of its edge is beyonds the specified size.
     `min_limited`: stretchs the image to the specified size preserving the aspect ratio when one of its edge is less than the specified size.
             label.caption(STR("<image=\"file.bmp\" size=(150,150) max_limited><bold red size=20>Nana C++ Library</>"));
     ![A Proper Size](label_image_maxlimited.png) Specifying a proper size
  6. Alignments for format mode.
     Defaulty, the alignment is baseline-aligned. The library provides 4 kinds of alignment which are: *top*, *center*, *bottom* and *baseline*. 
     They are useful tools when display texts with different size in a line.
             label.caption(STR("<size=12 top>top</><size=14 center>center<size=16 bottom>bottom</><size=30>baseline</><size=10>small font by baseline</>"));
     ![Label Alignment](label_alignment.png) 
a_group_impl.cpp, background-effects.cpp, calculator.cpp, group.cpp, helloword.cpp, helloworld_demo.cpp, label_listener.cpp, MontiHall.cpp, widget_show.cpp, and widget_show2.cpp.

Member Typedef Documentation

Constructor & Destructor Documentation

nana::label::label ( )
nana::label::label ( window  wd,
bool  visible 
nana::label::label ( window  wd,
const std::string text,
bool  visible = true 
nana::label::label ( window  parent,
const char *  text,
bool  visible = true 
nana::label::label ( window  wd,
const rectangle r = {},
bool  visible = true 

Member Function Documentation

label & nana::label::add_format_listener ( std::function< void(command, const std::string &)>  f)
label & nana::label::click_for ( window  associated_window)

as same as the HTML "for" attribute of a label

label & nana::label::format ( bool  f)

Switches the format mode of the widget.

nana::size nana::label::measure ( unsigned  allowed_width_in_pixel) const

Returns the size of the text. If allowed_width_in_pixel is not zero, returns a "corrected" size that changes lines to fit the text into the specified width

::nana::size nana::label::measure ( ::nana::paint::graphics ,
const ::std::string ,
unsigned  allowed_width_in_pixel,
bool  format_enabled,
align  h_align,
align_v  v_align 
label & nana::label::text_align ( align  horizontal_align,
align_v  vertical_align = align_v::top 
label & nana::label::transparent ( bool  enabled)

Switchs the label widget to the transparent background mode.

bool nana::label::transparent ( ) const