update ezgl subtree to add comments and refactor code

libezgl: Updating libs/EXTERNAL/libezgl/ (external git subtree from https://github.com/mariobadr/ezgl.git master)

Author: samehattia

libs/EXTERNAL/libezgl/include/ezgl/application.hpp

@@ -132,8 +132,10 @@ class application {
     : main_ui_resource(build_ui_from_file ? "main_ui" : "/ezgl/main.ui"), window_identifier("MainWindow"), canvas_identifier("MainCanvas"), application_identifier("ezgl.app"),
       setup_callbacks(nullptr)
     {
-      // If the default application identifier is used, uniquify it by appending a time stamp
-      application_identifier = "ezgl.app.t" + std::to_string(std::time(nullptr));
+      // Uniquify the application_identifier by appending a time stamp,
+      // so that each instance of the same program has a different application ID.
+      // This allows multiple instance of the program to run independelty.
+      application_identifier += ".t" + std::to_string(std::time(nullptr));
     }
 
     /**
@@ -144,9 +146,10 @@ class application {
     : main_ui_resource(m_resource), window_identifier(w_identifier), canvas_identifier(c_identifier), application_identifier(a_identifier),
       setup_callbacks(s_callbacks)
     {
-      // If the default application identifier is used, uniquify it by appending a time stamp
-      if (application_identifier == "ezgl.app")
-        application_identifier = "ezgl.app.t" + std::to_string(std::time(nullptr));
+      // Uniquify the application_identifier by appending a time stamp,
+      // so that each instance of the same program has a different application ID.
+      // This allows multiple instance of the program to run independelty.
+      application_identifier += ".t" + std::to_string(std::time(nullptr));
     }
   };
 
@@ -413,27 +416,13 @@ class application {
   key_callback_fn key_press_callback;
 };
 
-#ifndef ECE297
 /**
  * Set the disable_event_loop flag to new_setting
  * Call with new_setting == true to make the event_loop immediately return.
- * Needed only for auto-marking
  *
  * @param new_setting The new state of disable_event_loop flag
  */
 void set_disable_event_loop(bool new_setting);
-#endif
 }
 
-#ifdef ECE297
-/**
- * Set the disable_event_loop flag to new_setting
- * Call with new_setting == true to make the event_loop immediately return.
- * Needed only for auto-marking
- *
- * @param new_setting The new state of disable_event_loop flag
- */
-void set_disable_event_loop(bool new_setting);
-#endif
-
 #endif //EZGL_APPLICATION_HPP

libs/EXTERNAL/libezgl/include/ezgl/graphics.hpp

@@ -425,10 +425,10 @@ class renderer {
    * Draw a surface
    *
    * @param surface The surface to draw
-   * @param top_left The corner point of the drawn surface.
+   * @param anchor_point The anchor_point point of the drawn surface.
    * @param scale_factor The scaling factor of the drawn surface (optional)
    */
-  void draw_surface(surface *p_surface, point2d top_left, double scale_factor = 1);
+  void draw_surface(surface *p_surface, point2d anchor_point, double scale_factor = 1);
 
   /**
    * load a png image

libs/EXTERNAL/libezgl/include/ezgl/point.hpp

@@ -27,7 +27,7 @@ namespace ezgl {
 class point2d {
 public:
   /**
-   * Create a point at (0, 0).
+   * Default constructor: Create a point at (0, 0).
    */
   point2d() : x(0.0), y(0.0)
   {

libs/EXTERNAL/libezgl/src/application.cpp

@@ -18,17 +18,11 @@
 
 #include "ezgl/application.hpp"
 
-#ifdef ECE297
-// A flag to disable event loop (default is false)
-bool disable_event_loop = false;
-#endif
-
 namespace ezgl {
 
-#ifndef ECE297
 // A flag to disable event loop (default is false)
+// This allows basic scripted testing even if the GUI is on (return immediately when the event loop is called)
 bool disable_event_loop = false;
-#endif
 
 void application::startup(GtkApplication *, gpointer user_data)
 {
@@ -39,6 +33,8 @@ void application::startup(GtkApplication *, gpointer user_data)
 
   if (!build_ui_from_file) {
     // Build the main user interface from the XML resource.
+    // The XML resource is built from an XML file using the glib-compile-resources tool.
+    // This adds an extra compilation step, but it embeds the UI description in the executable.
     GError *error = nullptr;
     if(gtk_builder_add_from_resource(ezgl_app->m_builder, main_ui_resource, &error) == 0) {
       g_error("%s.", error->message);
@@ -325,7 +321,9 @@ void application::create_button(const char *button_text,
   GtkWidget *new_button = gtk_button_new_with_label(button_text);
 
   // set can_focus property to false
+#if GTK_CHECK_VERSION (3, 20, 0)
   gtk_widget_set_focus_on_click(new_button, false);
+#endif
 
   // connect the buttons clicked event to the callback
   if(button_func != NULL) {
@@ -476,17 +474,8 @@ renderer *application::get_renderer()
   return cnv->create_animation_renderer();
 }
 
-#ifndef ECE297
-void set_disable_event_loop(bool new_setting)
-{
-  disable_event_loop = new_setting;
-}
-#endif
-}
-
-#ifdef ECE297
 void set_disable_event_loop(bool new_setting)
 {
   disable_event_loop = new_setting;
 }
-#endif
+}

libs/EXTERNAL/libezgl/src/callback.cpp

@@ -20,11 +20,24 @@
 
 namespace ezgl {
 
-// File wide static variables to track whether the mouse button used for
-// panning is currently pressed AND the old x and y positions of the mouse pointer
-bool panning_mouse_button_pressed = false;
-int last_panning_event_time = 0;
-double prev_x = 0, prev_y = 0;
+/**
+ * Provides file wide variables to support mouse panning
+ */
+struct mouse_pan {
+  /**
+   * Tracks whether the mouse button used for panning is currently pressed
+   */
+  bool panning_mouse_button_pressed = false;
+  /**
+   * Holds the timestamp of the last panning event
+   */
+  int last_panning_event_time = 0;
+  /**
+   * The old x and y positions of the mouse pointer
+   */
+  double prev_x = 0;
+  double prev_y = 0;
+} g_mouse_pan;
 
 gboolean press_key(GtkWidget *, GdkEventKey *event, gpointer data)
 {
@@ -53,9 +66,9 @@ gboolean press_mouse(GtkWidget *, GdkEventButton *event, gpointer data)
 
     // Check for mouse press to support dragging
     if(event->button == PANNING_MOUSE_BUTTON) {
-      panning_mouse_button_pressed = true;
-      prev_x = event->x;
-      prev_y = event->y;
+      g_mouse_pan.panning_mouse_button_pressed = true;
+      g_mouse_pan.prev_x = event->x;
+      g_mouse_pan.prev_y = event->y;
     }
     // Call the user-defined mouse press callback if defined
     // The user-defined callback is called for mouse buttons other than
@@ -82,10 +95,10 @@ gboolean release_mouse(GtkWidget *, GdkEventButton *event, gpointer data)
   if(event->type == GDK_BUTTON_RELEASE) {
     // Check for mouse release to support dragging
     if(event->button == PANNING_MOUSE_BUTTON) {
-      panning_mouse_button_pressed = false;
+      g_mouse_pan.panning_mouse_button_pressed = false;
 
       // Call the user-defined mouse press callback for the PANNING_MOUSE_BUTTON button only if no panning occurs
-      if(event->x == prev_x && event->y == prev_y && application->mouse_press_callback != nullptr) {
+      if(event->x == g_mouse_pan.prev_x && event->y == g_mouse_pan.prev_y && application->mouse_press_callback != nullptr) {
         ezgl::point2d const widget_coordinates(event->x, event->y);
 
         std::string main_canvas_id = application->get_main_canvas_id();
@@ -107,26 +120,26 @@ gboolean move_mouse(GtkWidget *, GdkEventButton *event, gpointer data)
   if(event->type == GDK_MOTION_NOTIFY) {
 
     // Check if the mouse button is pressed to support dragging
-    if(panning_mouse_button_pressed) {
+    if(g_mouse_pan.panning_mouse_button_pressed) {
       // drop this panning event if we have just served another one
-      if(gtk_get_current_event_time() - last_panning_event_time < 100)
+      if(gtk_get_current_event_time() - g_mouse_pan.last_panning_event_time < 100)
         return true;
 
-      last_panning_event_time = gtk_get_current_event_time();
+      g_mouse_pan.last_panning_event_time = gtk_get_current_event_time();
 
       GdkEventMotion *motion_event = (GdkEventMotion *)event;
 
       std::string main_canvas_id = application->get_main_canvas_id();
       auto canvas = application->get_canvas(main_canvas_id);
 
       point2d curr_trans = canvas->get_camera().widget_to_world({motion_event->x, motion_event->y});
-      point2d prev_trans = canvas->get_camera().widget_to_world({prev_x, prev_y});
+      point2d prev_trans = canvas->get_camera().widget_to_world({g_mouse_pan.prev_x, g_mouse_pan.prev_y});
 
       double dx = curr_trans.x - prev_trans.x;
       double dy = curr_trans.y - prev_trans.y;
 
-      prev_x = motion_event->x;
-      prev_y = motion_event->y;
+      g_mouse_pan.prev_x = motion_event->x;
+      g_mouse_pan.prev_y = motion_event->y;
 
       // Flip the delta x to avoid inverted dragging
       translate(canvas, -dx, -dy);

libs/EXTERNAL/libezgl/src/graphics.cpp

@@ -304,12 +304,14 @@ void renderer::set_text_rotation(double degrees)
 
 void renderer::set_horiz_justification(justification horiz_just)
 {
+  // Ignore illegal values for horizontal justification
   if (horiz_just != justification::top && horiz_just != justification::bottom)
     horiz_justification = horiz_just;
 }
 
 void renderer::set_vert_justification(justification vert_just)
 {
+  // Ignore illegal values for vertical justification
   if (vert_just != justification::right && vert_just != justification::left)
     vert_justification = vert_just;
 }
@@ -713,8 +715,10 @@ void renderer::draw_arc_path(point2d center,
 void renderer::draw_surface(surface *p_surface, point2d point, double scale_factor)
 {
   // Check if the surface is properly created
-  if(cairo_surface_status(p_surface) != CAIRO_STATUS_SUCCESS)
+  if(cairo_surface_status(p_surface) != CAIRO_STATUS_SUCCESS) {
+    g_warning("renderer::draw_surface: Error drawing surface at address %p; surface is not valid.", p_surface);
     return;
+  }
 
   // calculate surface width and height in screen coordinates
   double s_width = (double)cairo_image_surface_get_width(p_surface) * scale_factor;
@@ -732,6 +736,9 @@ void renderer::draw_surface(surface *p_surface, point2d point, double scale_fact
     top_left.x -= s_width/2;
   else if (horiz_justification == justification::right)
     top_left.x -= s_width;
+  // Vertical justifaction is calculated differently based on the current coordinate system
+  // Since the origin point of screen coordinates is at the top left,
+  // while the origin point of world coordinates is at the bottom left
   if (vert_justification == justification::center)
     top_left.y += (current_coordinate_system == WORLD) ? s_height/2 : -s_height/2;
   else if (vert_justification == justification::bottom)
@@ -776,10 +783,10 @@ surface *renderer::load_png(const char *file_path)
   cairo_status_t status = cairo_surface_status(png_surface);
 
   if (status == CAIRO_STATUS_FILE_NOT_FOUND) {
-    g_warning("load_png: File %s not found.", file_path);
+    g_warning("renderer::load_png: File %s not found.", file_path);
   }
   else if (status != CAIRO_STATUS_SUCCESS) {
-    g_warning("load_png: Error loading file %s.", file_path);
+    g_warning("renderer::load_png: Error loading file %s.", file_path);
   }
 
   return png_surface;