The core application. More...

#include <application.hpp>

Classes
struct	settings
	Configuration settings for the application. More...

Public Member Functions
	application (application::settings s)
	Create an application. More...

canvas *	add_canvas (std::string const &canvas_id, draw_canvas_fn draw_callback, rectangle coordinate_system, color background_color=WHITE)
	Add a canvas to the application. More...

void	create_button (const char *button_text, int left, int top, int width, int height, button_callback_fn button_func)
	Add a button that you can click on to call its callback function. More...

void	create_button (const char *button_text, int insert_row, button_callback_fn button_func)
	Add a button convenience Adds a button at a given row index (assuming buttons in the right bar use 1 row each, with the top button at row 0) by inserting a row in the grid and adding the button. More...

bool	destroy_button (const char *button_text_to_destroy)
	Deletes a button by its label (displayed text) More...

void	change_button_text (const char button_text, const char new_button_text)
	Change the label of the button (displayed text) More...

void	create_label (int insert_row, const char *label_text)
	Creates a label object (a text label) in the Inner Grid. More...

void	create_label (int left, int top, int width, int height, const char *label_text)
	Create a label object in Inner Grid at specified position/dimensions. More...

void	create_combo_box_text (const char *id_string, int insert_row, combo_box_callback_fn combo_box_fn, std::vector< std::string > options)
	Creates a GTK combo box object in Inner Grid A combo box is a dropdown menu with different options. More...

void	create_combo_box_text (const char *id_string, int left, int top, int width, int height, combo_box_callback_fn combo_box_fn, std::vector< std::string > options)
	Create a combo box text object. More...

void	change_combo_box_text_options (const char *name, std::vector< std::string > new_options)
	changes list of options to new given vector. More...

void	create_dialog_window (dialog_callback_fn cbk_fn, const char dialog_title, const char window_text)
	Creates a simple dialog window with "OK" and "CANCEL" buttons. More...

void	create_popup_message (const char title, const char message)
	Creates a popup message with a "DONE" button. More...

void	create_popup_message_with_callback (dialog_callback_fn cbk_fn, const char title, const char message)
	Creates a popup message with a "DONE" button. More...

bool	destroy_widget (const char *widget_name)
	Destroys widget. More...

GtkWidget *	find_widget (const char *widget_name)
	Searches inner grid for widget with given name. More...

void	update_message (std::string const &message)
	Update the message in the status bar. More...

void	change_canvas_world_coordinates (std::string const &canvas_id, rectangle coordinate_system)
	Change the coordinate system of a previously created canvas. More...

void	refresh_drawing ()
	redraw the main canvas More...

renderer *	get_renderer ()
	Get a renderer that can be used to draw on top of the main canvas. More...

void	flush_drawing ()
	Flush the drawing done by the renderer to the on-screen buffer. More...

int	run (setup_callback_fn initial_setup_user_callback, mouse_callback_fn mouse_press_user_callback, mouse_callback_fn mouse_move_user_callback, key_callback_fn key_press_user_callback)
	Run the application. More...

	~application ()
	Destructor.

	application (application const &)=delete
	Copies are disabled.

application &	operator= (application const &)=delete
	Copies are disabled.

	application (application &&)=default
	Ownership of an application is transferrable.

application &	operator= (application &&)=default
	Ownership of an application is transferrable.

canvas *	get_canvas (std::string const &canvas_id) const
	Retrieve a pointer to a canvas that was previously added to the application. More...

GObject *	get_object (gchar const *name) const
	Retrieve a GLib Object (i.e., a GObject). More...

std::string	get_main_window_id () const
	Get the ID of the main window.

std::string	get_main_canvas_id () const
	Get the ID of the main canvas.

void	quit ()
	Quit the application.

Public Attributes
setup_callback_fn	initial_setup_callback

mouse_callback_fn	mouse_press_callback

mouse_callback_fn	mouse_move_callback

key_callback_fn	key_press_callback

Detailed Description

The core application.

The GUI of an application is created from an XML file. Widgets created in the XML file can be retrieved from an application object, but only after the object has been initialized by GTK via application::run. application is a singleton class: only create one.

Constructor & Destructor Documentation

◆ application()

ezgl::application::application ( application::settings s )

explicit

Create an application.

Parameters

s	The preconfigured settings.

Member Function Documentation

◆ add_canvas()

canvas* ezgl::application::add_canvas	(	std::string const &	canvas_id,
		draw_canvas_fn	draw_callback,
		rectangle	coordinate_system,
		color	background_color = `WHITE`
	)

Add a canvas to the application.

If the canvas has already been added, it will not be overwritten and a warning will be displayed.

Parameters

canvas_id	The id of the GtkDrawingArea in the ui XML file.
draw_callback	The function to call that draws to this canvas.
coordinate_system	The initial coordinate system of this canvas. coordinate_system.first gives the (x,y) world coordinates of the lower left corner, and coordinate_system.second gives the (x,y) coordinates of the upper right corner.
background_color	(OPTIONAL) The color of the canvas background. Default is WHITE.

Returns: A pointer to the newly created canvas.

◆ change_button_text()

void ezgl::application::change_button_text	(	const char *	button_text,
		const char *	new_button_text
	)

Change the label of the button (displayed text)

Parameters

button_text	the old text of the button
new_button_text	the new button text

The function assumes that the UI has a GtkGrid named "InnerGrid"

◆ change_canvas_world_coordinates()

void ezgl::application::change_canvas_world_coordinates	(	std::string const &	canvas_id,
		rectangle	coordinate_system
	)

Change the coordinate system of a previously created canvas.

This changes the current visible world (as set_visible_world would) and also changes the saved initial coordinate_system so that Zoom Fit shows the proper area.

Parameters

canvas_id	The id of the GtkDrawingArea in the XML file, e.g. "MainCanvas"
coordinate_system	The new coordinate system of this canvas.

◆ change_combo_box_text_options()

void ezgl::application::change_combo_box_text_options	(	const char *	name,
		std::vector< std::string >	new_options
	)

changes list of options to new given vector.

Erases all old options.

This will call your callback function. Make sure you have some check that returns/ends the function if your combo box has no active id (this occurs while erasing the old options)

Parameters

id_string	identifying string of GtkComboBoxText, given in creation
new_options	new string vector of options

◆ create_button() [1/2]

void ezgl::application::create_button	(	const char *	button_text,
		int	insert_row,
		button_callback_fn	button_func
	)

Add a button convenience Adds a button at a given row index (assuming buttons in the right bar use 1 row each, with the top button at row 0) by inserting a row in the grid and adding the button.

Uses the default width of 3 and height of 1

Parameters

button_text	the new button text
insert_row	the row in the right bar to insert the button. If there is already a button there, it and the following buttons shift down 1 row.
button_func	callback function for the button fn prototype: void fn_name(GtkButton* self, ezgl::application* app); The function assumes that the UI has a GtkGrid named "InnerGrid"

◆ create_button() [2/2]

void ezgl::application::create_button	(	const char *	button_text,
		int	left,
		int	top,
		int	width,
		int	height,
		button_callback_fn	button_func
	)

Add a button that you can click on to call its callback function.

Note: The following functions create UI Elements and add them to the Gtk Grid "InnerGrid". The example main.ui file already includes a grid called "InnerGrid", as well as the Zoom and pan buttons. As long a GtkGrid called "InnerGrid" exists, the functions will work and add the UI elements to that grid.

Parameters

button_text	the new button text
left	the column number to attach the left side of the new button to
top	the row number to attach the top side of the new button to
width	the number of columns that the button will span
height	the number of rows that the button will span
button_func	callback function for the button

The function assumes that the UI has a GtkGrid named "InnerGrid"

◆ create_combo_box_text() [1/2]

void ezgl::application::create_combo_box_text	(	const char *	id_string,
		int	insert_row,
		combo_box_callback_fn	combo_box_fn,
		std::vector< std::string >	options
	)

Creates a GTK combo box object in Inner Grid A combo box is a dropdown menu with different options.

EZGL provides functions to modify the options in your combo box, and you can connect a callback function to the signal sent when the selected option is changed

GTK Combo Box convenience function. Creates a combo box at the row id given by insert_row. Assumes default height of 1 and width of 3

Parameters

id_string	A id string used to track combo box. Can be any UNIQUE string, not a label/not visible used to identify widget to destroy/modify it.
insert_row	the row in the right bar to insert the button. If there is already a button there, it and the following buttons shift down 1 row.
combo_box_fn	Callback function for "changed" signal, emmitted when a new option is selected. fn prototype: void fn_name(GtkComboBoxText* self, ezgl::application* app);
options	A string vector containing the options to be contained in the combo box. String at index 0 is set as default

◆ create_combo_box_text() [2/2]

void ezgl::application::create_combo_box_text	(	const char *	id_string,
		int	left,
		int	top,
		int	width,
		int	height,
		combo_box_callback_fn	combo_box_fn,
		std::vector< std::string >	options
	)

Create a combo box text object.

Creates a GtkComboBox at the given location. A combo box is a dropdown menu with different options. EZGL provides functions to modify the options in your combo box, and you can connect a callback function to the signal sent when the selected option is changed

Parameters

id_string	A id string used to track combo box. Can be any UNIQUE string, not a label/not visible used to identify widget to destroy/modify it.
left	the column number to attach the left side of the new button to
top	the row number to attach the top side of the new button to
width	the number of columns that the button will span
height	the number of rows that the button will span
combo_box_fn	Callback function for "changed" signal, emmitted when a new option is selected. fn prototype: void fn_name(GtkComboBoxText* self, ezgl::application* app);
options	A string vector containing the options to be contained in the combo box. String at index 0 is set as default

◆ create_dialog_window()

void ezgl::application::create_dialog_window	(	dialog_callback_fn	cbk_fn,
		const char *	dialog_title,
		const char *	window_text
	)

Creates a simple dialog window with "OK" and "CANCEL" buttons.

This function creates a dialog window with three buttons that send the following response_ids: OK - GTK_RESPONSE_ACCEPT CANCEL - GTK_RESPONSE_REJECT X - GTK_RESPONSE_DELETE_EVENT It is dynamically created and shown through this function. Hitting any option in the dialog will run the attached cbk fn. Follow the given fn prototype and use the response_id to act accordingly. you must call gtk_widget_destroy(ptr to dialog window) in your cbk function.

Parameters

cbk_fn	Dialog callback function. Function prototype: void dialog_cbk(GtkDialog* self, gint response_id, application* app);
dialog_title	Title of the window to be created
window_text	Message to be contained in a label in the window

◆ create_label() [1/2]

void ezgl::application::create_label	(	int	insert_row,
		const char *	label_text
	)

Creates a label object (a text label) in the Inner Grid.

Label convenience function. Assumes default height of 1 and width of 3. Creates Label object at insert_row in Inner Grid. Also sets name of label to text. If you ever need to delete or find the widget, use find_widget with the label_text

Parameters

insert_row	Row where label will be placed
label_text	Text of Label

◆ create_label() [2/2]

void ezgl::application::create_label	(	int	left,
		int	top,
		int	width,
		int	height,
		const char *	label_text
	)

Create a label object in Inner Grid at specified position/dimensions.

Creates a label and sets its name to given text, which can be used with find_widget to access it

Parameters

left	the column number to attach the left side of the new button to
top	the row number to attach the top side of the new button to
width	the number of columns that the button will span
height	the number of rows that the button will span
label_text	Text of Label

◆ create_popup_message()

void ezgl::application::create_popup_message	(	const char *	title,
		const char *	message
	)

Creates a popup message with a "DONE" button.

This version has a default callback

Creates a popup window that will hold focus until user hits done button. This version has a default callback function that will just close the dialog window. popup is destroyed when user presses "DONE"

Parameters

title	Popup Message Title
message	Popup Message Body

◆ create_popup_message_with_callback()

void ezgl::application::create_popup_message_with_callback	(	dialog_callback_fn	cbk_fn,
		const char *	title,
		const char *	message
	)

Creates a popup message with a "DONE" button.

This version takes a callback function

Creates a popup window that will hold focus until user hits done button. You can pass a callback function, which is called when user hits DONE. This dialog window only has one button. Make sure to call gtk_widget_destroy(ptr to popup) to close the popup in the cbk fn

Parameters

cbk_fn	Popup Callback Function
title	Popup Message Title
message	Popup Message Body

◆ destroy_button()

bool ezgl::application::destroy_button ( const char * button_text_to_destroy )

Deletes a button by its label (displayed text)

Parameters

the	text of the button to delete

Returns: whether the button was found and deleted

The function assumes that the UI has a GtkGrid named "InnerGrid"

◆ destroy_widget()

bool ezgl::application::destroy_widget ( const char * widget_name )

Destroys widget.

Parameters

widget_name The ID given in Glade/Name set in creation function

Returns: true if widget found and destroyed, false if not found

◆ find_widget()

GtkWidget* ezgl::application::find_widget ( const char * widget_name )

Searches inner grid for widget with given name.

This function will search the inner grid (sidebar) for the widget with the given name/id. It will return a Widget ptr to it. This function is powerful; it will search through, in this order: String IDs created in Glade for widgets Names set using ezgl::application method functions that make widgets (i.e create_combo_box) Button labels set using application::create_button

Parameters

widget_name string to be searched for

Returns: GtkWidget* Pointer to GtkWidget. Can be cast to appropriate type

◆ flush_drawing()

void ezgl::application::flush_drawing ( )

Flush the drawing done by the renderer to the on-screen buffer.

The flushing is done immediately. Useful when you are drawing an animation and need the graphics to update immediatey, instead of the usual allowing them to be buffered until user in put is requested.

◆ get_canvas()

canvas* ezgl::application::get_canvas ( std::string const & canvas_id ) const

Retrieve a pointer to a canvas that was previously added to the application.

Calling this function before application::run results in undefined behaviour.

Parameters

canvas_id The key used when the canvas was added (e.g. "MainCanvas")

Returns: A non-owning pointer, or nullptr if not found.

See also: application::get_object

◆ get_object()

GObject* ezgl::application::get_object ( gchar const * name ) const

Retrieve a GLib Object (i.e., a GObject).

This is useful for retrieving GUI elements specified in your ui XML file(s). You should only call this function after the application has been run, otherwise the GUI elements will have not been created yet.

Parameters

name	The ID of the object.

Returns: The object with the ID, or NULL if it could not be found.

See also: application::run

◆ get_renderer()

renderer* ezgl::application::get_renderer ( )

Get a renderer that can be used to draw on top of the main canvas.

Most common usage is to get a renderer in an animation callback.

◆ refresh_drawing()

void ezgl::application::refresh_drawing ( )

redraw the main canvas

Useful to force an immediate redraw when you want a different graphics display

◆ run()

int ezgl::application::run	(	setup_callback_fn	initial_setup_user_callback,
		mouse_callback_fn	mouse_press_user_callback,
		mouse_callback_fn	mouse_move_user_callback,
		key_callback_fn	key_press_user_callback
	)

Run the application.

Once this is called, the application will be initialized first. Initialization will build the GUI based on the XML resource given in the constructor. Once the GUI has been created, the function initial_setup_user_callback will be called; you can use that callback to create additional widgets and/or connect additional signals.

After initialization, control of the program will be given to GTK. You will only regain control for the signals that you have registered callbacks for.

Parameters

initial_setup_user_callback	A user-defined function that is called before application activation
mouse_press_user_callback	The user-defined callback function for mouse press
mouse_move_user_callback	The user-defined callback function for mouse move
key_press_user_callback	The user-defined callback function for keyboard press

Returns: The exit status.

◆ update_message()

void ezgl::application::update_message ( std::string const & message )

Update the message in the status bar.

Parameters

message The message that will be displayed on the status bar

The function assumes that the UI has a GtkStatusbar named "StatusBar"

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

application.hpp

Classes

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ application()

Member Function Documentation

◆ add_canvas()

◆ change_button_text()

◆ change_canvas_world_coordinates()

◆ change_combo_box_text_options()

◆ create_button() [1/2]

◆ create_button() [2/2]

◆ create_combo_box_text() [1/2]

◆ create_combo_box_text() [2/2]

◆ create_dialog_window()

◆ create_label() [1/2]

◆ create_label() [2/2]

◆ create_popup_message()

◆ create_popup_message_with_callback()

◆ destroy_button()

◆ destroy_widget()

◆ find_widget()

◆ flush_drawing()

◆ get_canvas()

◆ get_object()

◆ get_renderer()

◆ refresh_drawing()

◆ run()

◆ update_message()