Form base class. The user must inherit from this class and call one of the two constructors from its own constructor. More...

#include <form.h>

Classes
struct	form_events
	Form events. More...

Public Member Functions
	form (const std::string &caption)
	Make a form with no parent. More...

	form (const std::string &caption, form &parent)
	Make a modal form. More...

void	move (const point &point)
	Move the form. More...

void	move (const form_position &form_position)
	Move the form. More...

void	force_instance ()
	Force this instance to run even if an existing instance is found. More...

bool	create (std::string &error)
	Create the form. More...

void	close ()
	Close the form. When this is called all activity is stopped and the form is closed. More...

bool	prompt (const std::string &question)
	Prompt the user for confirmation of an action. Displays a small modal message box with yes-no buttons. More...

void	message (const std::string &message)
	Display a message to the user in the form of a small modal message box with an ok button. More...

void	update ()
	Update the form. A low resource refresh of the current page. Typically necessary only after adding a new widget at runtime to the currently displayed page to avoid a situation whereby the widget is only displayed the next time the mouse moves or the next time the tab key is pressed.

void	reload ()
	Reload the form and all its widgets. A high resource reload of the entire form's graphic resources. The following things happen when this method is called: More...

float	get_dpi_scale ()
	Get the current DPI scale. More...

void	allow_minimize ()
	Minimize the form. More...

void	restore ()
	Restore the form. More...

void	maximize ()
	Maximize the form. More...

void	hide ()
	Hide the form. Useful when using a system tray icon. More...

bool	visible ()
	Check whether the form is visible. More...

void	show ()
	Show the form. More...

bool	minimized ()
	Check whether the form is minimized. More...

void	prevent_quit ()
	Prevent the form from being closed. More...

void	allow_quit ()
	Allow the form to be closed. More...

form_events &	events ()
	Get or set form events. More...

Static Public Member Functions
static std::string	menu_form_caption ()
	A special caption used to make a menu form. More...

static std::string	tooltip_form_caption ()
	A special caption used to make a tooltip form. More...

static bool	keep_alive ()
	Keep UI responsive during lengthy calls. More...

Detailed Description

Form base class. The user must inherit from this class and call one of the two constructors from its own constructor.

Fully DPI aware, but needs to be recreated if the system DPI changes while already open to rescale properly.

Constructor & Destructor Documentation

◆ form() [1/2]

liblec::lecui::form::form ( const std::string & caption )

Make a form with no parent.

Parameters

caption The form caption, displayed on the top left. Supports formatting like any other label widget. Care has to be taken that the formatting does not result in text of excessive height since the title bar's size is fixed. Default font size is 9px when none is specified in the formatting and it is not recommended to set a size greater than this for the above mentioned reason.

◆ form() [2/2]

liblec::lecui::form::form	(	const std::string &	caption,
		form &	parent
	)

Make a modal form.

Parameters

caption	The form caption, displayed on the top left. Supports formatting like any other label widget. Care has to be taken that the formatting does not result in text of excessive height since the title bar's size is fixed. Default font size is 9px when none is specified in the formatting and it is not recommended to set a size greater than this for the above mentioned reason.
parent	The parent form. The user cannot click the parent form until the child form is closed. Useful for making input forms.

The parent form remains active in the background, with all timers running. If it so happens that the parent is closed from one of these timers, all it's children will be forcibly closed first. A child is not allowed to continue if the parent is closing.

Member Function Documentation

◆ allow_minimize()

void liblec::lecui::form::allow_minimize ( )

Minimize the form.

This method does nothing if the form is already minimized or if it doesn't have the minimize button.

◆ allow_quit()

void liblec::lecui::form::allow_quit ( )

Allow the form to be closed.

Required at some point after a call to prevent_quit else it will not be possible to close the form.

◆ close()

void liblec::lecui::form::close ( )

Close the form. When this is called all activity is stopped and the form is closed.

If called in the form_events::initialize event then the form_events::layout event never happens and the app is terminated gracefully.

◆ create()

bool liblec::lecui::form::create ( std::string & error )

Create the form.

Parameters

error Error information on fail.

Returns: True if successful, else false. If false, error information will be written to the error reference.

This is a blocking function and will only return when either the form is closed or in the event of an error during form creation.

◆ events()

form_events & liblec::lecui::form::events ( )

Get or set form events.

Returns: A reference to the form's events.

◆ force_instance()

void liblec::lecui::form::force_instance ( )

Force this instance to run even if an existing instance is found.

This method causes the create method to continue execution regardless of whether an existing instance is present. You would typically do this if you need your app to reach the form_events::initialize event without the intention of allowing it to go as far as the form_events::layout event, in which case you would call the close method within the form_events::initialize event. A typical use-case is when the app is calling itself during an update process. Not calling this method would mean the spawning of the new instance is not guaranteed since the previous may still be running when the new one reaches the instance checking logic. The best place to call this method is in the constructor of the class that inherits from this base class.

◆ get_dpi_scale()

float liblec::lecui::form::get_dpi_scale ( )

Get the current DPI scale.

Returns: The current DPI scale.

◆ hide()

void liblec::lecui::form::hide ( )

Hide the form. Useful when using a system tray icon.

Note that once called the form can only be restored through a call to the restore method. Besides that there will be no other means to make the form visible again. To manipulate a form's visibility at creation time use the controls::start_hidden method.

◆ keep_alive()

static bool liblec::lecui::form::keep_alive ( )

static

Keep UI responsive during lengthy calls.

Returns: Returns true to continue operation, and false to quit immediately.

In lengthy operations it is useful to call this method between successive steps in order to keep the UI responsive.

◆ maximize()

void liblec::lecui::form::maximize ( )

Maximize the form.

This method does nothing if the form is already maximized or if it doesn't have the maximize button.

◆ menu_form_caption()

static std::string liblec::lecui::form::menu_form_caption ( )

static

A special caption used to make a menu form.

Returns: The internally reserved caption for menu forms.

◆ message()

void liblec::lecui::form::message ( const std::string & message )

Display a message to the user in the form of a small modal message box with an ok button.

Parameters

message The message to display.

Is centered to the form, and inherits the caption from the form.

◆ minimized()

bool liblec::lecui::form::minimized ( )

Check whether the form is minimized.

Returns: Returns true if the form is minimized, else returns false.

◆ move() [1/2]

void liblec::lecui::form::move ( const form_position & form_position )

Move the form.

Parameters

form_position The predefined form position.

◆ move() [2/2]

void liblec::lecui::form::move ( const point & point )

Move the form.

Parameters

point The coordinates of the top left corner of the form, in pixels.

◆ prevent_quit()

void liblec::lecui::form::prevent_quit ( )

Prevent the form from being closed.

Typically useful when you need to perform a lengthy operation that should not or cannot be interrupted. To allow the form to be closed call the allow_quit method.

◆ prompt()

bool liblec::lecui::form::prompt ( const std::string & question )

Prompt the user for confirmation of an action. Displays a small modal message box with yes-no buttons.

Parameters

question The question to ask the user.

Returns: True if yes is selected, else no.

Is centered to the form, and inherits the caption from the form.

◆ reload()

void liblec::lecui::form::reload ( )

Reload the form and all its widgets. A high resource reload of the entire form's graphic resources. The following things happen when this method is called:

The form's graphic resources are all recreated.
The graphic resources for the currently displayed page are all recreated.
The graphic resources of all pages that have been added to the form but are not currently displayed are all recreated.

Depending on the computing platform, this can take a considerable amount of time in a large app, ranging from milliseconds to actual seconds. The better the app is designed the less time it will take, as such applications typically only create pages on-demand. However, even in a well designed app the difference with update() will be obvious if many pages are currently open. Note: this doesn't change the form's 'state', e.g. if a widget was closed it won't magically reappear. This reloads the current 'state'.

◆ restore()

void liblec::lecui::form::restore ( )

Restore the form.

If the form is minimized it will be restored. If it is maximized it will also be restored to normal size. If the form is already in normal form nothing will be done (except bring it to the foreground if it isn't already). If the form was hidded it will be shown.

◆ show()

void liblec::lecui::form::show ( )

Show the form.

Neccessary to display a form that was hidden through a call to hide.

◆ tooltip_form_caption()

static std::string liblec::lecui::form::tooltip_form_caption ( )

static

A special caption used to make a tooltip form.

Returns: The internally reserved caption for tooltip forms.

◆ visible()

bool liblec::lecui::form::visible ( )

Check whether the form is visible.

Returns: Returns true if the form is visible, even if it's minimized or not in the foreground, else returns false.

The documentation for this class was generated from the following file:

form.h

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ form() [1/2]

◆ form() [2/2]

Member Function Documentation

◆ allow_minimize()

◆ allow_quit()

◆ close()

◆ create()

◆ events()

◆ force_instance()

◆ get_dpi_scale()

◆ hide()

◆ keep_alive()

◆ maximize()

◆ menu_form_caption()

◆ message()

◆ minimized()

◆ move() [1/2]

◆ move() [2/2]

◆ prevent_quit()

◆ prompt()

◆ reload()

◆ restore()

◆ show()

◆ tooltip_form_caption()

◆ visible()