Getting Started

See: An Introduction to Nana C++ Library, by Jinhao

Hello Nana

This chapter shows how to create an small graphical user interface (GUI) application using the Nana C++ Library.

Let's start with a simple program. We will study it line by line.

	1 #include <nana/gui/wvl.hpp> 
	2 #include <nana/gui/widgets/label.hpp> 
	3 int main() 
	4 { 
	5 	nana::form form; 
	6 	nana::label label(form, nana::rectangle(0, 0, 100, 20)); 
	7 	label.caption("Hello Nana"); 
	8 	form.show(); 
	9 	nana::exec(); 
	10 } 

Lines 1 and 2 include the definitions of class form and class label from namespace nana. Every GUI application written with Nana C++ Library must include the header file nana/gui/wvl.hpp.

Line 5 defines a nana::form object. It is a window. In this example it is used to place a label widget. A widget is a visual element in the user interface.

Line 6 defines the nana::label object to display a text string. The label object is created in the form.

Line 7 sets the caption of the label object. Every widget has a caption, often to display a title.

Line 8 makes the form visible.

Line 9 passes the control of the application to Nana. At this point, the program enters the event loop for waiting for, and receiving a user action, such as mouse move, mouse click and keyboard press. The function nana::exec blocks till form is destroyed. This example demonstrates that the program exits when a user closes the window.

Now, you could want to build the program on your own machine. But firstly you should have Nana C++ Library configured in your system. A method to install nana is explained in Installation 📚.

Responding An Event

The second example shows how to respond a user action. To receive a user action, an event handler should be registered to a widget. Nana waits for a user action and invokes the event handler of the corresponding event. The example application consists of a window with a button on them that the user can click to quit.

	#include <nana/gui/wvl.hpp> 
	#include <nana/gui/widgets/button.hpp> 
	int main() 
	{ 
		using namespace nana; 
		form fm; 
		button btn(fm, nana::rectangle(0, 0, 100, 20)); 
		btn.caption("Quit"); 
		btn.events().click(API::exit); 
		fm.show(); 
		exec(); 
	} 

This code is similar to Hello Nana, except that we are using a button instead of a label, and that we are registering an event handler to respond a user click. Every widget class has a family of methods to register events handlers. These methods are accessed through events(). The parameter of the member function (click() in this case) is an event handler. Here we register the function API::exit() as our event handler for the button's click event.
The exit() function is an API of the Nana C++ Library. It closes all windows of the current GUI thread and terminates the event loop. It will get called when the user clicks the button.

Threading

Nana is a thread-safe library and accessing a widget between threads is normalized. This is a great feature that makes programmer deliver the event answer to other thread easier.

#include <nana/gui/wvl.hpp>
#include <nana/threads/pool.hpp>

void foo()
{
   //This function will be "called" in other thread created by thread pool.
}
int main()
{
    using namespace nana;
    using namespace nana::threads;
    pool thrpool;
    form fm;
    fm.events().click(pool_push(thrpool, foo));
    fm.events().click(pool_push(thrpool, []{
                                              //A lambda is also allowed.
                                            }));
     fm.show();
     exec();
}

---

Next: Hello-World & Quit

See also:

Creating forms | Widgets | Events | Message box | Windows Icon

• Introduction to The Support of Bidirectional Language (June 18, 2012)
• Nana Tutorial: Creating A GUI Calculator (2013-03-03 )
• Demo of Nana C++ Library
• See the examples in this documentation.