Abstract base class for all dialogs. More...

#include <dialog.hpp>

Inherited by gui2::taddon_connect, gui2::taddon_description, gui2::taddon_filter_options, gui2::taddon_list, gui2::taddon_uninstall_list, gui2::tadvanced_graphics_options, gui2::tcampaign_difficulty, gui2::tcampaign_selection, gui2::tcampaign_settings, gui2::tchat_log, gui2::tcore_selection, gui2::tcustom_tod, gui2::tdepcheck_confirm_change, gui2::tdepcheck_select_new, gui2::tdrop_down_list, gui2::tedit_label, gui2::tedit_text, gui2::teditor_edit_label, gui2::teditor_edit_scenario, gui2::teditor_edit_side, gui2::teditor_generate_map, gui2::teditor_new_map, gui2::teditor_resize_map, gui2::teditor_set_starting_position, gui2::tfolder_create, gui2::tformula_debugger, gui2::tgame_cache_options, gui2::tgame_delete, gui2::tgame_load, gui2::tgame_save, gui2::tgame_save_message, gui2::tgame_save_oos, gui2::tgame_version, gui2::tgamestate_inspector, gui2::tlabel_settings, gui2::tlanguage_selection, gui2::tloadscreen, gui2::tlobby_main, gui2::tlobby_player_info, gui2::tlogging, gui2::tlua_interpreter, gui2::tmessage, gui2::tmp_alerts_options, gui2::tmp_change_control, gui2::tmp_cmd_wrapper, gui2::tmp_connect, gui2::tmp_create_game, gui2::tmp_create_game_set_password, gui2::tmp_host_game_prompt, gui2::tmp_join_game_password_prompt, gui2::tmp_login, gui2::tmp_method_selection, gui2::tnetwork_transmission, gui2::tpreferences, gui2::tscreenshot_notification, gui2::tselect_orb_colors, gui2::tsimple_item_selector, gui2::tsynced_choice_wait, gui2::ttheme_list, gui2::ttitle_screen, gui2::ttransient_message, gui2::tunit_attack, gui2::tunit_create, gui2::tunit_recruit, gui2::twml_error, and gui2::twml_message_.

Public Member Functions
	tdialog ()

virtual	~tdialog ()

bool	show (CVideo &video, const unsigned auto_close_time=0)
	Shows the window. More...

int	get_retval () const

void	set_always_save_fields (const bool always_save_fields)

void	set_restore (const bool restore)

Protected Member Functions
tfield_bool *	register_bool (const std::string &id, const bool mandatory, const std::function< bool()> &callback_load_value=std::function< bool()>(), const std::function< void(const bool)> &callback_save_value=std::function< void(const bool)>(), const std::function< void(twidget &)> &callback_change=std::function< void(twidget &)>())
	Creates a new boolean field. More...

tfield_bool *	register_bool (const std::string &id, const bool mandatory, bool &linked_variable, const std::function< void(twidget &)> &callback_change=std::function< void(twidget &)>())
	Creates a new boolean field. More...

tfield_integer *	register_integer (const std::string &id, const bool mandatory, const std::function< int()> &callback_load_value=std::function< int()>(), const std::function< void(const int)> &callback_save_value=std::function< void(const int)>())
	Creates a new integer field. More...

tfield_integer *	register_integer (const std::string &id, const bool mandatory, int &linked_variable)
	Creates a new integer field. More...

tfield_text *	register_text (const std::string &id, const bool mandatory, const std::function< std::string()> &callback_load_value=std::function< std::string()>(), const std::function< void(const std::string &)> &callback_save_value=std::function< void(const std::string &)>(), const bool capture_focus=false)
	Creates a new text field. More...

tfield_text *	register_text (const std::string &id, const bool mandatory, std::string &linked_variable, const bool capture_focus=false)
	Creates a new text field. More...

tfield_label *	register_label (const std::string &id, const bool mandatory, const std::string &text, const bool use_markup=false)
	Registers a new control as a label. More...

tfield_label *	register_image (const std::string &id, const bool mandatory, const std::string &filename)
	Registers a new control as image. More...

Private Member Functions
virtual const std::string &	window_id () const =0
	The id of the window to build. More...

twindow *	build_window (CVideo &video) const
	Builds the window. More...

virtual void	post_build (twindow &window)
	Actions to be taken directly after the window is build. More...

virtual void	pre_show (twindow &window)
	Actions to be taken before showing the window. More...

virtual void	post_show (twindow &window)
	Actions to be taken after the window has been shown. More...

virtual void	init_fields (twindow &window)
	Initializes all fields in the dialog and set the keyboard focus. More...

virtual void	finalize_fields (twindow &window, const bool save_fields)
	When the dialog is closed with the OK status saves all fields. More...

Private Attributes
int	retval_
	Returns the window exit status, 0 means not shown. More...

bool	always_save_fields_
	Always save the fields upon closing. More...

std::vector< tfield_ * >	fields_
	Contains the automatically managed fields. More...

std::string	focus_
	Contains the widget that should get the focus when the window is shown. More...

bool	restore_
	Restore the screen after showing? More...

Friends
std::string	unit_test_mark_as_tested (const tdialog &dialog)
	Special helper function to get the id of the window. More...

Detailed Description

Abstract base class for all dialogs.

A dialog shows a certain window instance to the user. The subclasses of this class will hold the parameters used for a certain window, eg a server connection dialog will hold the name of the selected server as parameter that way the caller doesn't need to know about the 'contents' of the window.

Usage

Simple dialogs that are shown to query user information it is recommended to add a static member called execute. The parameters to the function are:

references to in + out parameters by reference
references to the in parameters
the parameters for tdialog::show.

The 'in + out parameters' are used as initial value and final value when the OK button is pressed. The 'in parameters' are just extra parameters for showing.

When a function only has 'in parameters' it should return a void value and the function should be called display, if it has 'in + out parameters' it must return a bool value. This value indicates whether or not the OK button was pressed to close the dialog. See teditor_new_map::execute for an example.

Definition at line 121 of file dialog.hpp.

Constructor & Destructor Documentation

gui2::tdialog::tdialog ( )

inline

Definition at line 132 of file dialog.hpp.

gui2::tdialog::~tdialog ( )

virtual

Definition at line 26 of file dialog.cpp.

References field(), and fields_.

Member Function Documentation

twindow * gui2::tdialog::build_window ( CVideo & video ) const

private

Builds the window.

Every dialog shows it's own kind of window, this function should return the window to show.

Parameters

video The video which contains the surface to draw upon.

Returns: The window to show.

Definition at line 171 of file dialog.cpp.

References gui2::build(), and window_id().

Referenced by show().

void gui2::tdialog::finalize_fields	(	twindow &	window,
		const bool	save_fields
	)

privatevirtual

When the dialog is closed with the OK status saves all fields.

Saving only happens if a callback handler is installed.

Parameters

window	The window which has been shown.
save_fields	Does the value in the fields need to be saved?

Definition at line 206 of file dialog.cpp.

References field(), and fields_.

Referenced by show().

int gui2::tdialog::get_retval ( ) const

inline

Definition at line 161 of file dialog.hpp.

References retval_.

Referenced by game_launcher::change_language(), do_gameloop(), sp::enter_create_mode(), editor::context_manager::generate_map_dialog(), mp::ui::handle_event(), manage_addons(), open_connection(), game_launcher::play_multiplayer(), gui2::tmp_login::post_show(), gui2::tmp_create_game::post_show(), gui2::tlanguage_selection::post_show(), gui2::tunit_recruit::post_show(), gui2::tmp_change_control::post_show(), gui2::tunit_attack::post_show(), gui2::tselect_orb_colors::post_show(), gui2::teditor_set_starting_position::post_show(), gui2::tmp_method_selection::post_show(), gui2::taddon_uninstall_list::post_show(), gui2::tcampaign_difficulty::post_show(), gui2::taddon_connect::post_show(), gui2::tdepcheck_select_new::post_show(), gui2::ttheme_list::post_show(), gui2::tadvanced_graphics_options::post_show(), gui2::tunit_create::post_show(), gui2::tcustom_tod::post_show(), gui2::tsimple_item_selector::post_show(), events::menu_handler::recruit(), events::mouse_handler::show_attack_dialog(), savegame::loadgame::show_dialog(), savegame::loadgame::show_difficulty_dialog(), gui2::show_message(), savegame::savegame::show_save_dialog(), and savegame::oos_savegame::show_save_dialog().

void gui2::tdialog::init_fields ( twindow & window )

privatevirtual

Initializes all fields in the dialog and set the keyboard focus.

Parameters

window The window which has been shown.

Definition at line 191 of file dialog.cpp.

References field(), fields_, gui2::twindow::find(), focus_, and gui2::twindow::keyboard_capture().

Referenced by show().

void gui2::tdialog::post_build ( twindow & window )

privatevirtual

Actions to be taken directly after the window is build.

At this point the registered fields are not yet registered.

Parameters

video	The video which contains the surface to draw upon.
window	The window just created.

Reimplemented in gui2::tlobby_main, and gui2::ttitle_screen.

Definition at line 176 of file dialog.cpp.

Referenced by show().

void gui2::tdialog::post_show ( twindow & window )

privatevirtual

Actions to be taken after the window has been shown.

At this point the registered fields already stored their values (if the OK has been pressed).

Parameters

window The window which has been shown.

Reimplemented in gui2::tlobby_main, gui2::twml_message_, gui2::taddon_filter_options, gui2::tmessage, gui2::tsimple_item_selector, gui2::tcustom_tod, gui2::tnetwork_transmission, gui2::tloadscreen, gui2::teditor_edit_side, gui2::tunit_create, gui2::tpreferences, gui2::tgame_cache_options, gui2::tadvanced_graphics_options, gui2::tcampaign_selection, gui2::tcampaign_settings, gui2::tgame_load, gui2::ttheme_list, gui2::taddon_connect, gui2::tdepcheck_select_new, gui2::tlogging, gui2::taddon_uninstall_list, gui2::tcampaign_difficulty, gui2::tmp_method_selection, gui2::tcore_selection, gui2::teditor_set_starting_position, gui2::tlobby_player_info, gui2::tselect_orb_colors, gui2::tdrop_down_list, gui2::tmp_alerts_options, gui2::tunit_attack, gui2::tmp_change_control, gui2::tunit_recruit, gui2::tlanguage_selection, gui2::tmp_create_game, and gui2::tmp_login.

Definition at line 186 of file dialog.cpp.

Referenced by show().

void gui2::tdialog::pre_show ( twindow & window )

privatevirtual

Actions to be taken before showing the window.

At this point the registered fields are registered and initialized with their initial values.

Parameters

window The window to be shown.

Reimplemented in gui2::tlobby_main, gui2::twml_message_, gui2::teditor_resize_map, gui2::taddon_filter_options, gui2::tmessage, gui2::tsimple_item_selector, gui2::ttitle_screen, gui2::tcustom_tod, gui2::tgame_version, gui2::tnetwork_transmission, gui2::teditor_edit_side, gui2::tloadscreen, gui2::tunit_create, gui2::tpreferences, gui2::twml_error, gui2::tgame_cache_options, gui2::taddon_description, gui2::tmp_cmd_wrapper, gui2::tadvanced_graphics_options, gui2::tcampaign_selection, gui2::teditor_generate_map, gui2::tcampaign_settings, gui2::tgame_load, gui2::taddon_list, gui2::ttheme_list, gui2::taddon_connect, gui2::tdepcheck_select_new, gui2::tlogging, gui2::tscreenshot_notification, gui2::taddon_uninstall_list, gui2::tcampaign_difficulty, gui2::tmp_method_selection, gui2::tcore_selection, gui2::tselect_orb_colors, gui2::teditor_set_starting_position, gui2::tlobby_player_info, gui2::tdrop_down_list, gui2::tmp_alerts_options, gui2::tunit_attack, gui2::tlabel_settings, gui2::tmp_change_control, gui2::tlua_interpreter, gui2::ttransient_message, gui2::tchat_log, gui2::tunit_recruit, gui2::tgamestate_inspector, gui2::tsynced_choice_wait, gui2::tformula_debugger, gui2::tmp_connect, gui2::tlanguage_selection, gui2::tmp_create_game, and gui2::tmp_login.

Definition at line 181 of file dialog.cpp.

Referenced by show().

tfield_bool * gui2::tdialog::register_bool	(	const std::string &	id,
		const bool	mandatory,
		const std::function< bool()> &	callback_load_value = `std::function<bool()>()`,
		const std::function< void(const bool)> &	callback_save_value = `std::function<void(const bool)>()`,
		const std::function< void(twidget &)> &	callback_change = `std::function<void(twidget&)>()`
	)

protected

Creates a new boolean field.

The field created is owned by tdialog, the returned pointer can be used in the child classes as access to a field.

Parameters

id	Id of the widget, same value as in WML.
mandatory	Is the widget mandatory or mandatory.
callback_load_value	The callback function to set the initial value of the widget.
callback_save_value	The callback function to write the resulting value of the widget. Saving will only happen if the widget is enabled and the window closed with ok.
callback_change	When the value of the widget changes this callback is called.

Returns: Pointer to the created widget.

Definition at line 74 of file dialog.cpp.

References field(), and fields_.

Referenced by gui2::taddon_filter_options::register_displayed_type_field(), gui2::tgame_delete::tgame_delete(), and gui2::tmp_host_game_prompt::tmp_host_game_prompt().

tfield_bool * gui2::tdialog::register_bool	(	const std::string &	id,
		const bool	mandatory,
		bool &	linked_variable,
		const std::function< void(twidget &)> &	callback_change = `std::function<void(twidget&)>()`
	)

protected

Creates a new boolean field.

The field created is owned by tdialog, the returned pointer can be used in the child classes as access to a field.

Parameters

id	Id of the widget, same value as in WML.
mandatory	Is the widget mandatory or mandatory.
linked_variable	The variable the widget is linked to. See tfield::tfield for more information.
callback_change	When the value of the widget changes this callback is called.

Returns: Pointer to the created widget.

Definition at line 92 of file dialog.cpp.

References field(), and fields_.

tfield_label* gui2::tdialog::register_image	(	const std::string &	id,
		const bool	mandatory,
		const std::string &	filename
	)

inlineprotected

Registers a new control as image.

Definition at line 296 of file dialog.hpp.

References register_label().

tfield_integer * gui2::tdialog::register_integer	(	const std::string &	id,
		const bool	mandatory,
		const std::function< int()> &	callback_load_value = `std::function<int()>()`,
		const std::function< void(const int)> &	callback_save_value = `std::function<void(const int)>()`
	)

protected

Creates a new integer field.

See register_bool for more info.

Definition at line 104 of file dialog.cpp.

References field(), and fields_.

Referenced by gui2::teditor_edit_label::register_color_component().

tfield_integer * gui2::tdialog::register_integer	(	const std::string &	id,
		const bool	mandatory,
		int &	linked_variable
	)

protected

Creates a new integer field.

See register_bool for more info.

Definition at line 117 of file dialog.cpp.

References field(), and fields_.

tfield_label * gui2::tdialog::register_label	(	const std::string &	id,
		const bool	mandatory,
		const std::string &	text,
		const bool	use_markup = `false`
	)

protected

Registers a new control as a label.

The label is used for a control to set the 'label' since it calls the tcontrol::set_label it can also be used for the timage since there this sets the filename. (The use_markup makes no sense in an image but that's a detail.)

Note: In general it's preferred a widget sets its markup flag in WML, but some generic windows (like messages) may need different versions depending on where used.

Parameters

id	Id of the widget, same value as in WML.
mandatory	Is the widget mandatory or optional.
text	The text for the label.
use_markup	Whether or not use markup for the label.

Definition at line 160 of file dialog.cpp.

References field(), and fields_.

Referenced by register_image(), and gui2::tnetwork_transmission::tnetwork_transmission().

tfield_text * gui2::tdialog::register_text	(	const std::string &	id,
		const bool	mandatory,
		const std::function< std::string()> &	callback_load_value = `std::function<std::string()>()`,
		const std::function< void(const std::string &)> &	callback_save_value = `std::function<void(const std::string&)>()`,
		const bool	capture_focus = `false`
	)

protected

Creates a new text field.

See register_bool for more info.

Definition at line 127 of file dialog.cpp.

References field(), fields_, focus_, and gui2::id.

Referenced by gui2::tlua_interpreter::pre_show(), and gui2::teditor_generate_map::pre_show().

tfield_text * gui2::tdialog::register_text	(	const std::string &	id,
		const bool	mandatory,
		std::string &	linked_variable,
		const bool	capture_focus = `false`
	)

protected

Creates a new text field.

See register_bool for more info.

Definition at line 145 of file dialog.cpp.

References field(), fields_, focus_, and gui2::id.

void gui2::tdialog::set_always_save_fields ( const bool always_save_fields )

inline

Definition at line 166 of file dialog.hpp.

References always_save_fields_.

void gui2::tdialog::set_restore ( const bool restore )

inline

Definition at line 171 of file dialog.hpp.

References restore_.

Referenced by gui2::tlogging::pre_show(), gui2::ttitle_screen::pre_show(), gui2::twml_message_::pre_show(), gui2::show_transient_message(), gui2::tcampaign_selection::tcampaign_selection(), gui2::tgame_delete::tgame_delete(), gui2::tmp_connect::tmp_connect(), gui2::tmp_host_game_prompt::tmp_host_game_prompt(), and gui2::tnetwork_transmission::tnetwork_transmission().

bool gui2::tdialog::show	(	CVideo &	video,
		const unsigned	auto_close_time = `0`
	)

Shows the window.

Parameters

video	The video which contains the surface to draw upon.
auto_close_time	The time in ms after which the dialog will automatically close, if 0 it doesn't close.

Note: the timeout is a minimum time and there's no guarantee about how fast it closes after the minimum.

Returns: Whether the final retval_ == twindow::OK

Definition at line 34 of file dialog.cpp.

References always_save_fields_, build_window(), DOUBLE_CLICK_EVENT, CVideo::faked(), finalize_fields(), init_fields(), gui2::twindow::OK, post_build(), post_show(), pre_show(), restore_, and retval_.

Referenced by BOOST_AUTO_TEST_CASE(), game_launcher::change_language(), events::console_handler::do_choose_level(), events::console_handler::do_control_dialog(), do_gameloop(), events::console_handler::do_inspect(), sp::enter_create_mode(), enter_create_mode(), enter_lobby_mode(), gui2::tlabel_settings::execute(), editor::context_manager::generate_map_dialog(), mp::ui::handle_event(), manage_addons(), dialogs::network_transmission_dialog(), open_connection(), wb::manager::options_dlg(), game_launcher::play_multiplayer(), turn_info::process_network_data(), events::menu_handler::recruit(), ng::create_engine::select_campaign_difficulty(), events::mouse_handler::show_attack_dialog(), events::menu_handler::show_chat_log(), savegame::loadgame::show_dialog(), savegame::loadgame::show_difficulty_dialog(), lua_gui2::show_gamestate_inspector(), game_logic::formula_debugger::show_gui(), gui2::show_message(), preferences::show_preferences_dialog(), savegame::savegame::show_save_dialog(), savegame::oos_savegame::show_save_dialog(), gui2::tcampaign_selection::show_settings(), preferences::show_theme_dialog(), gui2::show_transient_message(), gui2::tcombobox::signal_handler_left_button_click(), editor::mouse_action_map_label::up_left(), gui2::tlobby_main::user_dialog_callback(), addons_client::wait_for_transfer_done(), and wait_prestart().

virtual const std::string& gui2::tdialog::window_id ( ) const

privatepure virtual

The id of the window to build.

Implemented in gui2::tlobby_main, gui2::twml_message_right, gui2::tmessage, gui2::twml_message_left, gui2::teditor_resize_map, gui2::taddon_filter_options, gui2::tnetwork_transmission, gui2::tsimple_item_selector, gui2::teditor_edit_side, gui2::ttitle_screen, gui2::tcustom_tod, gui2::tgame_save_oos, gui2::tgame_version, gui2::tloadscreen, gui2::tunit_create, gui2::tpreferences, gui2::twml_error, gui2::tmp_cmd_wrapper, gui2::tgame_load, gui2::teditor_edit_label, gui2::tedit_text, gui2::tgame_cache_options, gui2::taddon_description, gui2::tgame_save_message, gui2::teditor_edit_scenario, gui2::teditor_generate_map, gui2::tcampaign_settings, gui2::tcampaign_selection, gui2::taddon_list, gui2::ttheme_list, gui2::taddon_connect, gui2::tdepcheck_select_new, gui2::tedit_label, gui2::teditor_new_map, gui2::tlogging, gui2::tlua_interpreter, gui2::tscreenshot_notification, gui2::taddon_uninstall_list, gui2::tcampaign_difficulty, gui2::tmp_method_selection, gui2::tchat_log, gui2::tcore_selection, gui2::tfolder_create, gui2::tselect_orb_colors, gui2::teditor_set_starting_position, gui2::tlobby_player_info, gui2::tmp_create_game_set_password, gui2::tmp_join_game_password_prompt, gui2::tdepcheck_confirm_change, gui2::tdrop_down_list, gui2::tmp_alerts_options, gui2::tunit_attack, gui2::tgamestate_inspector, gui2::tformula_debugger, gui2::tlabel_settings, gui2::tmp_change_control, gui2::ttransient_message, gui2::tmp_host_game_prompt, gui2::tgame_delete, gui2::tgame_save, gui2::tunit_recruit, gui2::tsynced_choice_wait, gui2::tmp_connect, gui2::tlanguage_selection, gui2::tmp_create_game, and gui2::tmp_login.

Referenced by build_window(), and gui2::unit_test_mark_as_tested().

Friends And Related Function Documentation

std::string unit_test_mark_as_tested ( const tdialog & dialog )

friend

Special helper function to get the id of the window.

This is used in the unit tests, but these implementation details shouldn't be used in the normal code.

Definition at line 107 of file test_gui2.cpp.

Member Data Documentation

bool gui2::tdialog::always_save_fields_

private

Always save the fields upon closing.

Normally fields are only saved when the twindow::OK button is pressed. With this flag set is always saves. Be careful with the flag since it also updates upon canceling, which can be a problem when the field sets a preference.

Definition at line 315 of file dialog.hpp.

Referenced by set_always_save_fields(), and show().

std::vector<tfield_*> gui2::tdialog::fields_

private

Contains the automatically managed fields.

Since the fields are automatically managed and there are no search functions defined we don't offer access to the vector. If access is needed the creator should store a copy of the pointer.

Definition at line 324 of file dialog.hpp.

Referenced by finalize_fields(), init_fields(), register_bool(), register_integer(), register_label(), register_text(), and ~tdialog().

std::string gui2::tdialog::focus_

private

Contains the widget that should get the focus when the window is shown.

Definition at line 329 of file dialog.hpp.

Referenced by init_fields(), and register_text().

bool gui2::tdialog::restore_

private

Restore the screen after showing?

Most windows should restore the display after showing so this value defaults to true. Toplevel windows (like the titlescreen don't want this behavior so they can change it in pre_show().

Definition at line 338 of file dialog.hpp.

Referenced by set_restore(), and show().

int gui2::tdialog::retval_

private

Returns the window exit status, 0 means not shown.

Definition at line 305 of file dialog.hpp.

Referenced by get_retval(), and show().

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

gui/dialogs/dialog.hpp
gui/dialogs/dialog.cpp

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation