Application¶

namespace ezgl¶

A library for creating a graphical user interface.

Typedefs

using connect_g_objects_fn = void (*)(application *app)¶

The signature of a function that connects GObject to functions via signals.

See also

application::get_object.

using setup_callback_fn = void (*)(application *app, bool new_window)¶: The signature of a setup callback function

using button_callback_fn = void (*)(GtkWidget *widget, application *app)¶: The signature of a button callback function

using mouse_callback_fn = void (*)(application *app, GdkEventButton *event, double x, double y)¶: The signature of a user-defined callback function for mouse events

using key_callback_fn = void (*)(application *app, GdkEventKey *event, char *key_name)¶: The signature of a user-defined callback function for keyboard events

using combo_box_callback_fn = void (*)(GtkComboBoxText *self, application *app)¶: The signature of a user-defined callback function for the combo-box “changed” signal

using dialog_callback_fn = void (*)(GtkDialog *self, gint response_id, application *app)¶: The signature of a user-defined callback function for a dialog window

Variables

const bool build_ui_from_file = false¶

class application¶

#include <application.hpp>

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.

Public Functions

explicit application(application::settings s)¶

Create an application.

Parameters:: s – The preconfigured settings.

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.

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.

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

The function assumes that the UI has a GtkGrid named “InnerGrid”

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. Add a button that you can click on to call its callback function.

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

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. 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”

bool destroy_button(const char *button_text_to_destroy)¶

Deletes a button by its label (displayed text)

The function assumes that the UI has a GtkGrid named “InnerGrid”

Parameters:: the – text of the button to delete
Returns:: whether the button was found and deleted

void change_button_text(const char *button_text, const char *new_button_text)¶

Change the label of the button (displayed text)

The function assumes that the UI has a GtkGrid named “InnerGrid”

Parameters:

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

void 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

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.

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

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

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.

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

void 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

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.

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

void 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

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

bool 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

GtkWidget *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

void update_message(std::string const &message)¶

Update the message in the status bar

The function assumes that the UI has a GtkStatusbar named “StatusBar”

Parameters:: message – The message that will be displayed on the status bar

void 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.

void refresh_drawing()¶

redraw the main canvas

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

renderer *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.

void 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.

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.

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.

~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.

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