Abstract base class for all dialogs. More...

#include <dialog.hpp>

Inheritance diagram for gui2::tdialog:

Collaboration diagram for gui2::tdialog:

Public Member Functions
	tdialog ()
virtual	~tdialog ()
bool	show (CVideo &video, const unsigned auto_close_time=0)
	Shows the window.
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, bool(callback_load_value)()=NULL, void(callback_save_value)(const bool value)=NULL, void(callback_change)(twidget widget)=NULL)
	Creates a new boolean field.
tfield_bool *	register_bool (const std::string &id, const bool mandatory, bool &linked_variable, void(callback_change)(twidget widget)=NULL)
	Creates a new boolean field.
tfield_integer *	register_integer (const std::string &id, const bool mandatory, int(callback_load_value)()=NULL, void(callback_save_value)(const int value)=NULL)
	Creates a new integer field.
tfield_integer *	register_integer (const std::string &id, const bool mandatory, int &linked_variable)
	Creates a new integer field.
tfield_text *	register_text (const std::string &id, const bool mandatory, std::string(callback_load_value)()=NULL, void(callback_save_value)(const std::string &value)=NULL, const bool capture_focus=false)
	Creates a new text field.
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.
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.
tfield_label *	register_image (const std::string &id, const bool mandatory, const std::string &filename)
	Registers a new control as image.
Private Member Functions
virtual const std::string &	window_id () const =0
	The id of the window to build.
twindow *	build_window (CVideo &video) const
	Builds the window.
virtual void	post_build (CVideo &, twindow &)
	Actions to be taken directly after the window is build.
virtual void	pre_show (CVideo &, twindow &)
	Actions to be taken before showing the window.
virtual void	post_show (twindow &)
	Actions to be taken after the window has been shown.
virtual void	init_fields (twindow &window)
	Initializes all fields in the dialog and set the keyboard focus.
virtual void	finalize_fields (twindow &window, const bool save_fields)
	When the dialog is closed with the OK status saves all fields.
Private Attributes
int	retval_
	Returns the window exit status, 0 means not shown.
bool	always_save_fields_
	Always save the fields upon closing.
std::vector< tfield_ * >	fields_
	Contains the automatically managed fields.
std::string	focus_
	Contains the widget that should get the focus when the window is shown.
bool	restore_
	Restore the screen after showing?
Friends
std::string	unit_test_mark_as_tested (const tdialog &dialog)
	Special helper function to get the id of the window.

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 123 of file dialog.hpp.

Constructor & Destructor Documentation

gui2::tdialog::tdialog ( ) [inline]

Definition at line 134 of file dialog.hpp.

gui2::tdialog::~tdialog ( ) [virtual]

Definition at line 27 of file dialog.cpp.

References field(), and fields_.

Here is the call graph for this function:

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 189 of file dialog.cpp.

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

Referenced by show().

Here is the call graph for this function:

Here is the caller graph for this function:

void gui2::tdialog::finalize_fields	(	twindow &	window,
		const bool	save_fields
	)			`[private, virtual]`

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 208 of file dialog.cpp.

References gui2::tfield_::detach_from_window(), field(), fields_, and gui2::tfield_::widget_finalize().

Referenced by show().

Here is the call graph for this function:

Here is the caller graph for this function:

int gui2::tdialog::get_retval ( ) const [inline]

Definition at line 162 of file dialog.hpp.

References retval_.

Here is the caller graph for this function:

void gui2::tdialog::init_fields ( twindow & window ) [private, virtual]

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

Parameters:

window

The window which has been shown.

Definition at line 194 of file dialog.cpp.

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

Referenced by show().

Here is the call graph for this function:

Here is the caller graph for this function:

virtual void gui2::tdialog::post_build	(	CVideo &	,
		twindow &
	)			`[inline, private, virtual]`

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::ttitle_screen.

Definition at line 348 of file dialog.hpp.

Referenced by show().

Here is the caller graph for this function:

virtual void gui2::tdialog::post_show ( twindow & ) [inline, private, virtual]

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::taddon_uninstall_list, gui2::taddon_connect, gui2::tcampaign_difficulty, gui2::tcampaign_selection, gui2::teditor_set_starting_position, gui2::teditor_settings, gui2::tgame_load, gui2::tlanguage_selection, gui2::tlobby_player_info, gui2::tmessage, gui2::tmp_change_control, gui2::tmp_create_game, gui2::tmp_login, gui2::tmp_method_selection, gui2::tnetwork_transmission, gui2::tsimple_item_selector, gui2::tunit_attack, gui2::tunit_create, and gui2::twml_message_.

Definition at line 370 of file dialog.hpp.

Referenced by show().

Here is the caller graph for this function:

virtual void gui2::tdialog::pre_show	(	CVideo &	,
		twindow &
	)			`[inline, private, virtual]`

Actions to be taken before showing the window.

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

Parameters:

	video	The video which contains the surface to draw upon.
	window	The window to be shown.

Reimplemented in gui2::taddon_uninstall_list, gui2::taddon_connect, gui2::taddon_list, gui2::tcampaign_difficulty, gui2::tcampaign_selection, gui2::tchat_log, gui2::tdata_manage, gui2::teditor_generate_map, gui2::teditor_resize_map, gui2::teditor_set_starting_position, gui2::teditor_settings, gui2::tformula_debugger, gui2::tgame_load, gui2::tgamestate_inspector, gui2::tlanguage_selection, gui2::tlobby_player_info, gui2::tmessage, gui2::tmp_change_control, gui2::tmp_cmd_wrapper, gui2::tmp_connect, gui2::tmp_create_game, gui2::tmp_login, gui2::tmp_method_selection, gui2::tnetwork_transmission, gui2::tsimple_item_selector, gui2::ttitle_screen, gui2::tunit_attack, gui2::tunit_create, and gui2::twml_message_.

Definition at line 360 of file dialog.hpp.

Referenced by show().

Here is the caller graph for this function:

tfield_bool * gui2::tdialog::register_bool	(	const std::string &	id,
		const bool	mandatory,
		bool(*)()	callback_load_value = `NULL`,
		void(*)(const bool value)	callback_save_value = `NULL`,
		void()(twidget widget)	callback_change = `NULL`
	)			`[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::tgame_delete::tgame_delete(), and gui2::tmp_host_game_prompt::tmp_host_game_prompt().

Here is the call graph for this function:

Here is the caller graph for this function:

tfield_bool * gui2::tdialog::register_bool	(	const std::string &	id,
		const bool	mandatory,
		bool &	linked_variable,
		void()(twidget widget)	callback_change = `NULL`
	)			`[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 91 of file dialog.cpp.

References field(), and fields_.

Here is the call graph for this function:

tfield_label* gui2::tdialog::register_image	(	const std::string &	id,
		const bool	mandatory,
		const std::string &	filename
	)			`[inline, protected]`

Registers a new control as image.

Definition at line 280 of file dialog.hpp.

References register_label().

Here is the call graph for this function:

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 122 of file dialog.cpp.

References field(), and fields_.

Here is the call graph for this function:

tfield_integer * gui2::tdialog::register_integer	(	const std::string &	id,
		const bool	mandatory,
		int(*)()	callback_load_value = `NULL`,
		void(*)(const int value)	callback_save_value = `NULL`
	)			`[protected]`

Creates a new integer field.

See register_bool for more info.

Definition at line 106 of file dialog.cpp.

References field(), and fields_.

Here is the call graph for this function:

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 prefered a widget sets its markup flag in WML, but some generice 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 174 of file dialog.cpp.

References field(), and fields_.

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

Here is the call graph for this function:

Here is the caller graph for this function:

tfield_text * gui2::tdialog::register_text	(	const std::string &	id,
		const bool	mandatory,
		std::string(*)()	callback_load_value = `NULL`,
		void(*)(const std::string &value)	callback_save_value = `NULL`,
		const bool	capture_focus = `false`
	)			`[protected]`

Creates a new text field.

See register_bool for more info.

Definition at line 135 of file dialog.cpp.

References field(), fields_, and focus_.

Here is the call graph for this function:

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 156 of file dialog.cpp.

References field(), fields_, and focus_.

Here is the call graph for this function:

void gui2::tdialog::set_always_save_fields ( const bool always_save_fields ) [inline]

Definition at line 164 of file dialog.hpp.

References always_save_fields_.

void gui2::tdialog::set_restore ( const bool restore ) [inline]

Definition at line 169 of file dialog.hpp.

References restore_.

Referenced by gui2::ttitle_screen::pre_show().

Here is the caller graph for this function:

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 quarantee 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(), events::discard(), 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_controller::change_language(), events::menu_handler::create_unit_2(), events::console_handler::do_choose_level(), events::console_handler::do_control_dialog(), events::console_handler::do_inspect(), events::console_handler::do_manage(), enter_create_mode(), enter_lobby_mode(), editor::context_manager::generate_map_dialog(), mp::ui::handle_event(), manage_addons(), game_controller::new_campaign(), open_connection(), game_controller::play_multiplayer(), turn_info::process_network_data(), events::mouse_handler::show_attack_dialog(), events::menu_handler::show_chat_log(), savegame::loadgame::show_dialog(), savegame::loadgame::show_difficulty_dialog(), game_logic::formula_debugger::show_gui(), savegame::oos_savegame::show_save_dialog(), savegame::savegame::show_save_dialog(), editor::mouse_action_map_label::up_left(), gui2::tlobby_main::user_dialog_callback(), addons_client::wait_for_transfer_done(), and WML_HANDLER_FUNCTION().

Here is the call graph for this function:

Here is the caller graph for this function:

virtual const std::string& gui2::tdialog::window_id ( ) const [private, pure virtual]

The id of the window to build.

Implemented in gui2::taddon_description, gui2::taddon_uninstall_list, gui2::taddon_connect, gui2::taddon_list, gui2::tcampaign_difficulty, gui2::tcampaign_selection, gui2::tchat_log, gui2::tdata_manage, gui2::tedit_label, gui2::teditor_generate_map, gui2::teditor_new_map, gui2::teditor_resize_map, gui2::teditor_set_starting_position, gui2::teditor_settings, gui2::tfolder_create, gui2::tformula_debugger, gui2::tgame_delete, gui2::tgame_load, gui2::tgame_save, gui2::tgame_save_message, gui2::tgame_save_oos, gui2::tgamestate_inspector, gui2::tlanguage_selection, gui2::tlobby_player_info, gui2::tmessage, 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_login, gui2::tmp_method_selection, gui2::tnetwork_transmission, gui2::tsimple_item_selector, gui2::ttitle_screen, gui2::ttransient_message, gui2::tunit_attack, gui2::tunit_create, gui2::twml_message_left, and gui2::twml_message_right.

Referenced by build_window().

Here is the caller graph for this function:

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 78 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 299 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 308 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 313 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 behaviour so they can change it in pre_show().

Definition at line 322 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 289 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

gui2::tdialog Class Reference

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