src/widget/main_window/design First visible window (with memory leaks)

To display this minimal window, three files and two functions must be
added simultaneously:

- include/widget/h
- src/manager.c
- src/main_window/design.c

main() now contains: g_signal_connect (on_windows_activation);
on_windows_activation () is in src/manager.c and calls
widget_main_window () which is in src/main_window/design.c

NB  The iconic image of E coli drawn by David S. Goodsell in 2009
is reproduced here with permission.

One goal of Gem-graph is to animate such static representations
i.e. use the best anatomy to try to achieve good physiology.

docs/readme

@@ -24,8 +24,8 @@
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 
-This dossier gives you information on how to make the best use of doc.
+This file gives you information on how best to use the doc and a few tips for
-(a few tips for personalising it)
+personalising it.
 
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
@@ -43,7 +43,6 @@ Attention
  *
  *  docstrings
  *  ----------
- * Pour chaque fonction, quelles sont les infos prioritaires ?
  *
  * @brief
  * @details
@@ -56,54 +55,11 @@ Attention
  * @param (liste des paramètres)
  * @return
 
- autres (à envisager)  @see   https://www.doxygen.nl/manual/commands.html
+---------------------------------------------------------------------------
-
---------------------------------------------------------------------------------
-git commit 2024-10-14  avant d'exécuter une commande sed
-qui remplacera tous les commentaires 'fantômes':
-/** phantom documentation used to test the functioning of doxygen */
-/**< a_variable_name           phantom documentation */
-
-
-sed -i 's/phantom documentation used to test the functioning of doxygen/\n
-* @brief \n * @details \n * @dir \n * @file \n * @date \n * @author \n
-* @callgraph \n * @see \n * @callergraph \n * @see\n * @param \n * @return \n/'
-./src/main.c   <  or any other file...
-
-NB  signal et journal n'ont pas été 'tagués'  <<<<<<<<<<
---------------------------------------------------------------------------------
-
 
+ *  TODO : valgrind  bin/gem-graph-client
+ *         sanitize
  *
- *
- *  TODO : actuellement, valgrind bin/gem-graph-client détecte :
- *
- * HEAP SUMMARY:
- *     in use at exit: 11,537,505 bytes in 42,285 blocks
- *   total heap usage: 483,548 allocs,
- *                     441,263 frees,
- *                     112,049,363 bytes allocated
- * LEAK SUMMARY:
- *    definitely lost: 40,161 bytes in 79 blocks
- *    indirectly lost: 11,233 bytes in 489 blocks
- *      possibly lost: 7,879,639 bytes in 7,844 blocks
- *    still reachable: 3,412,408 bytes in 32,248 blocks
- *         suppressed: 0 bytes in 0 blocks
- * Rerun with --leak-check=full to see details of leaked memory
- *
- * valgrind  --leak-check=full   >  ERROR SUMMARY: 1572 errors from 680 contexts
- *           --track-origins=yes    ERROR SUMMARY: 896 errors from 4 contexts
- *           --show-leak-kinds=all
- *
- * sanitize  <<
- *
- *
- *  TODO  des scripts devraient pouvoir recueillir ces informations
- *  pour produire automatiquement, à la demande, des listes comme celle qui suit.
- *  (voir le dossier 'scripts')
- *  > plutôt utiliser Doxygen.
- *
- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
 
 

include/fsm.h

@@ -1,7 +1,6 @@
 /**
  * @file
- * This file is part of Gem-graph; it is the client fsm (finite state machine)
+ * FSM (Finite State Machine) header of the Gem-graph client.
- * header.
  *
  * @see readme.docs and this text below.
  *
@@ -110,7 +109,7 @@ enum fsm_enum_log_severity {
     FATAL,  /**< (or CRITICAL) an unrecoverable failure that prevents the whole
                  application from doing any further useful work 🕳️☠️ */
     ERROR,  /**< an irremediable situation that hinders the execution of a
-                 specific operation within the application 👀️😮️ */
+                 specific operation within the application 👀️😮️! */
     WARN,   /**< something unexpected has occurred, but the application can
                  continue to function normally for the time being 😅️ */
     INFO,   /**< (or MESSAGE) a significant event occurs while the system is

include/widget.h

@@ -0,0 +1,31 @@
+/**
+ * @file
+ * Widgets hierarchy header of the Gem-graph client;
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ */
+
+
+#pragma once
+#include <gtk-4.0/gtk/gtk.h>
+
+void on_windows_activation (GtkApplication *app);
+void widget_get_main_window (GtkWindow *main_window, GtkApplication *app);
+

src/fsm/control.c

@@ -1,7 +1,6 @@
 /**
  * @file
- * @brief This file is part of Gem-graph; it controls the client fsm
+ * @brief Gem-graph client FSM controls.
- * (Finite State Machine).
  *
  * @details
  *

src/fsm/log/appendix.c

@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * This file is part of Gem-graph; it contains only auxiliary functions.
+ * Gem-graph client auxiliary log functions container.
  *
  * The log (or journal) stores chronologically the events during a session run.
  *

src/fsm/log/manager.c

@@ -1,6 +1,6 @@
 /**
  * @file
- * @brief This file is part of Gem-graph; fsm (Finite State Machine) log manager.
+ * @brief FSM manager of the Gem-graph client log main structures and functions.
  *
  * @details
  * The log (journal) is created, edited and published from here.

src/fsm/log/oper.c

@@ -1,11 +1,11 @@
 /**
  * @file
  *
- * This file is part of Gem-graph;
+ * Gem-graph client log executive functions container.
- * the log stores chronologically all the events during a run.
  *
- * This file contains the executive functions needed to initialise the log, add
+ * The log stores chronologically all the events occuring during an execution.
- * events and publish everything.
+ *
+ * The executive functions initialise the log, add events and publish everything.
  *
  * The log presentation is:
  * [date - rank - source file - source function - value]
@@ -81,7 +81,7 @@ void fsm_clear_log (fsm_log_struct *jj)
 
 
 /**
- * Adds a log unit (an event) to the list.
+ * Adds a log unit (an event) to the log list.
  *
  * *new_unit = malloc (sizeof (fsm_log_unit_struct));
  *

src/main.c

@@ -1,6 +1,6 @@
 /**
  * @file
- * This file is part of Gem-graph; it contains only the main() function.
+ * Main file of the Gem-graph client; contains only the main() function.
  *
  * The main() function
  * - **initialise**
@@ -13,9 +13,6 @@
  *   before ending the program execution
  * .
  *
- * In this commit, it does not implement g_application_activate() and has no
- * handlers connected to the 'activate' signal (which triggers an error message).
- *
  * The default values of the fsm initial state will be specified in:
  * src/fsm/control(). They are user preferences.
  *
@@ -42,7 +39,8 @@
  */
 
 #include <gtk-4.0/gtk/gtk.h>
-#include "../include/fsm.h"      //  finite state machine (fsm)
+#include "../include/fsm.h"
+#include "../include/widget.h"
 
 /**
  * @since 2024-04
@@ -74,11 +72,7 @@ int main (int argc, char **argv)
                        "| 👉️  windows creation requested");
 
 //  g_signal_connect (app, "startup",  G_CALLBACK (on_windows_startup), NULL);
-//    g_signal_connect (app, "activate", G_CALLBACK (on_windows_activation), NULL);
+    g_signal_connect (app, "activate", G_CALLBACK (on_windows_activation), NULL);
-
-    fsm_add_log (INFO, MAIN, "main",
-                       "no g signal connect (activate)",
-                       "| 🖐️   windows creation denied");
 
     status = g_application_run (G_APPLICATION (app), argc, argv);
     g_object_unref (app);

src/readme.docs.c

@@ -1,8 +1,6 @@
 /**
  * @file
- * Gem-graph-client src/readme.docs file
+ * Gem-graph-client quick documentation (NB see also the Manual)
- *
- *  This file is part of Gem-graph.
  *
  * @cond LICENSE
  * Copyright © 2021 Libre en Communs <contact@a-lec.org>

src/widget/main_window/design.c

@@ -0,0 +1,59 @@
+/**
+ * @file
+ * Gem-graph client Main Window designer.
+ *
+ * Initiates, designs and frees the Gem-graph client main window.
+ *
+ *
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ */
+
+
+
+#include "../../../include/widget.h"
+#include "../../../include/fsm.h"
+
+ /**
+ * @brief Main Window design()
+ *
+ * @param *main_window
+ * @param *app
+ */
+void widget_get_main_window (GtkWindow *main_window,
+                                GtkApplication *app)
+{
+    fsm_add_log (INFO, TOPBAR, "widget/main_window/design",
+                               "> main window", "has began");
+
+    GtkWidget *topbar = GTK_WIDGET (gtk_header_bar_new ());
+
+    char *title = "E coli   (with permission from David S. Goodsell, 2009)";
+    gtk_header_bar_set_title_widget (GTK_HEADER_BAR (topbar),
+                                     gtk_label_new (title));
+
+    gtk_window_set_child (main_window,
+                          GTK_WIDGET (gtk_picture_new_for_filename
+                          ("./docs/showcase/E coli (Goodsell).png")));
+
+    fsm_add_log (INFO, TOPBAR, "widget/main_window/design",
+                               "> main window", "has ended");
+}
+

src/widget/manager.c

@@ -0,0 +1,94 @@
+/**
+ * @file
+ * Gem-graph client Widgets general manager.
+ *
+ * Initiates, designs and frees all the Gem-graph client windows.
+ *
+ *
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ */
+
+
+
+#include "../../include/widget.h"
+#include "../../include/fsm.h"
+
+
+static GtkWindow *main_window;
+
+
+/**
+ * @brief Main Window new(app) and present()
+ *
+ * NB > on_windows_activation() is in: widget/manager  NOT in: src/signal
+ *
+ * @since 2024-06
+ *
+ * @callgraph
+ * @see widget_design_main_window()
+ * @see widget_design_dialog_window()
+ * @see widget_design_text_window()
+ * @see util_trigger_test()
+ * @see fsm_add_log()
+ *
+ * @callergraph
+ * @see main()
+ *
+ * @param *app
+ */
+void on_windows_activation (GtkApplication *app)
+{
+    fsm_add_log (INFO, WIDGETS, "widget/manager", "windows activation()", "has began");
+
+    //  on_windows_activation() is in: widget/manager  NOT in:  src/signal
+    //  g_application_activate (G_APPLICATION (app));   <   how ?   >   in main is
+    //  g_signal_connect (app, "activate", G_CALLBACK (on_windows_activation), NULL);
+
+    main_window   = GTK_WINDOW (gtk_application_window_new (app));
+    widget_get_main_window   (main_window, app);
+    gtk_window_present (GTK_WINDOW (main_window));
+
+    //  ------------------------------------------------------------------------
+    //  For the breakdown between pages, see signal  >  switch_state_rules_data()
+
+    //  NB   The rules page consists of two half-pages in a GtkPaned widget :
+    //  - on the left,  widgets for controlling or editing all the rules.
+    //  - on the right, widgets for controlling or editing the selected rule.
+
+    //  The preferred 'First Page' (the page displayed when the window is opened)
+    //  is selected in:  widget/topbar/left   window_design_topbar_left()
+    //  until it is defined in the fsm     (2024-09)
+    //  ------------------------------------------------------------------------
+ //   widget_design_main_window   (main_window, app); // def: widget/...
+
+
+    //  ------------------------------------------------------------------------
+    //  WIP  2024-09
+    //  https://github.com/ToshioCP/Gtk4-tutorial/blob/main/gfm/sec17.md
+    /*GtkApplication *app2 = GTK_APPLICATION (app);
+    GSimpleAction *act_b = g_simple_action_new ("do_b", NULL);
+    g_action_map_add_action (G_ACTION_MAP (app), G_ACTION (act_b));
+    g_signal_connect (act_b, "activate", G_CALLBACK (action_b), app2);*/
+
+    fsm_add_log (INFO, WIDGETS, "widget/manager", "windows activation()",
+                       "has ended 🧐️ | 👉️ a new session can be launched");
+}
+