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/rtfm/intro writing + cleaning details in src/
2024-11-12 17:15:12 +01:00 · 2024-11-11 23:44:02 +01:00 · 2024-11-11 23:36:02 +01:00
14 changed files with 294 additions and 137 deletions
--- a/docs/readme
+++ b/docs/readme
@ -24,8 +24,8 @@
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */


-This dossier gives you information on how to make the best use of doc.
-(a few tips for personalising it)
+This file gives you information on how best to use the doc and a few tips for
+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.
- *
- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */



--- a/docs/rtfm/intro
+++ b/docs/rtfm/intro
@ -64,7 +64,7 @@ this second model a "random walk".

 The second model (the random walk) had one state (the arrow) and two rules
 (forward/backward). Now here's a model with two states and two rules:
-the pendulum. This time, the arrow can be drawn either tilted forwards or tilted
+the "pendulum". This time, the arrow can be drawn either tilted forwards or tilted
 backwards (these are the two possible states) and the two rules switch the drawn
 arrow from one state to the other or vice versa. In the file, the states are (here)
 and the rules (here). The pendulum does not change place, but alternates between
@ -86,8 +86,8 @@ The next example shows how the same rule can be applied to a multitude of states
 The rule is the same as that used in the first model: an arrow can only be moved
 one square forward, but this time you have to check that the square forward is
 free. If it isn't, the arrow won't move. Once the rule has been modified in this
-way, it can be applied to a multitude of arrows distributed randomly in space
-(see details here).
+way (see how), it can be applied to a multitude of arrows distributed randomly in space
+(see more details here).
 When you set the model in motion, you will see all these small lines moving from
 left to right. A single rule is responsible for all these movements.
 For a small fee, we can apply the two rules of the 'random walk' model to all the
@ -121,11 +121,11 @@ limitations are.
 The main difference between gem-graph models and agent-based models is that
 gem-graph deals with situations, not agents. In a situation where several agents
 are interacting and each agent could apply a different rule, gem-graph considers
-and processes the situation. Not the agents. Whatever the state - the new
-situation - that results from his action, his decision-making process will have
-been simple and straightforward. It will therefore be easy to modify and control.
-And the diversity of possible new situations will be far greater than that
-offered by agent-based models.
+and processes the situation. Not the agents. Whatever the new situation that 
+results from his action, his decision-making process will have been simple and 
+straightforward. It will therefore be easy to modify and control. And the 
+diversity of possible new situations will be far greater than that offered by 
+agent-based models.

 ------------

@ -141,3 +141,23 @@ How can gem-graph be used to analyse and control the complexity of what it
 represents and sets in motion? This chapter introduces the gem-graph mechanism.


+------------
+
+Gem-graph can reproduce the behavior of any cellular automata. Whatever the state
+of the cellular automaton space at a given time (n), this state can be considered
+as a gem-graph state and a rule can be written to transform it into the next
+state (n+1).
+
+The difference with the cellular automaton is that this rule is not generated by
+a "micro-rule" applied cell by cell to the entire state (n). This rule must be
+written by hand and its writing requires knowledge of state (n+1).
+
+Writing all the rules that describe all the transformations that have occurred
+when a cellular automaton describes a trajectory (a story) is certainly tedious,
+but it is always possible. And the number of possible histories that gem-graph
+rules can describe is limited only by the size of the space and the number of
+symbols it contains.
+
+If a set of "micro-rules", each applied cell by cell to the entire state (n) of
+a cellular automaton, can produce all the possible states that the gem-graph can
+describe, the two representations can be considered to be equivalent in power.
--- a/docs/rtfm/intro.txt
+++ b/docs/rtfm/intro.txt
@ -16,7 +16,7 @@ To improve this model, it is possible to give the arrow the ability to move in t

 ------------

-The second model (the random walk) had one state (the arrow) and two rules (forward/backward). Now here's a model with two states and two rules: the pendulum. This time, the arrow can be drawn either tilted forwards or tilted backwards (these are the two possible states) and the two rules switch the drawn arrow from one state to the other or vice versa. In the file, the states are (here) and the rules (here). The pendulum does not change place, but alternates between left and right. Like the previous ones, you can slow down the programme so that you can observe the movements.
+The second model (the random walk) had one state (the arrow) and two rules (forward/backward). Now here's a model with two states and two rules: the "pendulum". This time, the arrow can be drawn either tilted forwards or tilted backwards (these are the two possible states) and the two rules switch the drawn arrow from one state to the other or vice versa. In the file, the states are (here) and the rules (here). The pendulum does not change place, but alternates between left and right. Like the previous ones, you can slow down the programme so that you can observe the movements.

 ------------

@ -24,7 +24,7 @@ Once you know how to write a state and a rule, you can write thousands of them:

 ------------

-The next example shows how the same rule can be applied to a multitude of states. The rule is the same as that used in the first model: an arrow can only be moved one square forward, but this time you have to check that the square forward is free. If it isn't, the arrow won't move. Once the rule has been modified in this way, it can be applied to a multitude of arrows distributed randomly in space (see details here).
+The next example shows how the same rule can be applied to a multitude of states. The rule is the same as that used in the first model: an arrow can only be moved one square forward, but this time you have to check that the square forward is free. If it isn't, the arrow won't move. Once the rule has been modified in this way (see how), it can be applied to a multitude of arrows distributed randomly in space (see more details here).
 When you set the model in motion, you will see all these small lines moving from left to right. A single rule is responsible for all these movements.
 For a small fee, we can apply the two rules of the 'random walk' model to all the arrows distributed in this space, and they will then all behave in the same way, sometimes moving forwards, sometimes backwards.

@ -39,7 +39,7 @@ The last example in this series, because it shows a multitude of diverse and sim

 ------------

-The main difference between gem-graph models and agent-based models is that gem-graph deals with situations, not agents. In a situation where several agents are interacting and each agent could apply a different rule, gem-graph considers and processes the situation. Not the agents. Whatever the state - the new situation - that results from his action, his decision-making process will have been simple and straightforward. It will therefore be easy to modify and control. And the diversity of possible new situations will be far greater than that offered by agent-based models. 
+The main difference between gem-graph models and agent-based models is that gem-graph deals with situations, not agents. In a situation where several agents are interacting and each agent could apply a different rule, gem-graph considers and processes the situation. Not the agents. Whatever the new situation that results from his action, his decision-making process will have been simple and straightforward. It will therefore be easy to modify and control. And the diversity of possible new situations will be far greater than that offered by agent-based models. 

 ------------

@ -49,3 +49,12 @@ The comparison between gem-graphs and cellular automata first comes up against a

 How can gem-graph be used to analyse and control the complexity of what it represents and sets in motion? This chapter introduces the gem-graph mechanism.

+------------
+
+Gem-graph can reproduce the behavior of any cellular automata. Whatever the state of the cellular automaton space at a given time (n), this state can be considered as a gem-graph state and a rule can be written to transform it into the next state (n+1). 
+
+The difference with the cellular automaton is that this rule is not generated by a "micro-rule" applied cell by cell to the entire state (n). This rule must be written by hand and its writing requires knowledge of state (n+1).
+
+Writing all the rules that describe all the transformations that have occurred when a cellular automaton describes a trajectory (a story) is certainly tedious, but it is always possible. And the number of possible histories that gem-graph rules can describe is limited only by the size of the space and the number of symbols it contains.
+
+If a set of "micro-rules", each applied cell by cell to the entire state (n) of a cellular automaton, can produce all the possible states that the gem-graph can describe, the two representations can be considered to be equivalent in power.
--- a/docs/showcase/E
+++ b/docs/showcase/E
--- a/include/fsm.h
+++ b/include/fsm.h
@ -1,23 +1,23 @@
 /**
 * @file
- * This file is part of Gem-graph; Client fsm (finite state machine) header.
+ * FSM (Finite State Machine) header of the Gem-graph client.
 *
 * @see readme.docs and this text below.
 *
 * ---
 *
- * The two log structures and the two enums listed below are defined in the fsm
- * header.
+ * The two log structures and the two enums needed by the logs are defined in
+ * the fsm header.
 *
 * All log functions are in dedicated files.
 *
 * The most important function: fsm_add_log() is in the file:
 * /src/fsm/log/manager.c
 *
- * This file contains the declaration of the log with the static attribute,
+ * This file contains the declaration of the log with the **static** attribute,
 * which forces all the functions that read or write it to be in it.
 * Forcing all functions that read or write to the log to be grouped together
- * help to prevent uncontrolled operations.
+ * helps to prevent uncontrolled operations.
 *
 * All events sent to the log must pass through this function, which allows them
 * to be filtered before being published in the log.
@ -109,16 +109,16 @@ 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
                 operating normally 📜️👌️ */
    DEBUG,  /**< a description of system states in sufficient detail to give
-                 developers clues as to the cause of an error 🪳️👀️🧐️ */
+                 developers clues as to the cause of an error 🪳️🧐️ */
    TRACE   /**< provides a systematic overview of code execution but comes at
                 a cost in terms of performance 🥱️ */
-};//.😮️🧐️👀️😅️😕️😱️😦️🕳️😵‍💫️
+};

 /**
 * A list of structures or states that may be involved in program events.
--- a/include/widget.h
+++ b/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);
+
--- a/src/fsm/control.c
+++ b/src/fsm/control.c
@ -1,7 +1,6 @@
 /**
 * @file
- * @brief This file is part of Gem-graph; it controls the client fsm
- * (Finite State Machine).
+ * @brief Gem-graph client FSM controls.
 *
 * @details
 *
@ -118,10 +117,10 @@ static void fsm_structures_close()


 /**
- * @brief fsm_init() is the first function called by main.c
- * It initiates the journal and calls fsm_structures_init().
+ * @brief The first function called by main();
+ * initiates the journal and calls fsm_structures_init().
 *
- * It uses the relay function fsm_relay_init_log() in src/fsm/log/manager.c to
+ * Uses the relay function fsm_relay_init_log() in src/fsm/log/manager.c to
 * reach the fsm_init_log().
 *
 * @since 2024-08
@ -152,18 +151,20 @@ void fsm_init (const char *initial_info_from_main)
 }

 /**
- * @brief fsm_close() is the last function called by main.c  It closes all that
- * was opened in reverse order before handing over to main().
+ * @brief The last function called by main();
+ * closes all that was opened in reverse order.
 *
- * @details It ensures the fsm state is saved:
- * - preferences
- * - model
+ * @details Ensures the fsm state is saved:
+ * - 'preferences'
+ * - 'model'
 *
- * Then it closes the four lists:
+ * Then closes the four lists:
 * - 'measures',
 * - 'results',
 * - 'displayables results' and
- * - 'preferences'.
+ * - 'preferences'
+ * .
+ *
 * and closes the journal
 *
 * @since 2024-08
--- a/src/fsm/log/appendix.c
+++ b/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.
 *
@ -33,8 +33,7 @@
 #include "../../../include/fsm.h"

 /**
- * remove an event;
- * the removal is a pop back
+ * Removes an event; the removal is a pop back
 *
 * @since 2024-09
 *
@ -64,7 +63,7 @@ long fsm_remove_log (fsm_log_struct *jj,


 /**
- * get log length
+ * Gets the log length
 *
 * @since 2024-09
 *
@ -85,7 +84,7 @@ int fsm_get_log_length (fsm_log_struct jj)


 /**
- * seek for an event
+ * Seek for an event
 *
 * @since 2024-09
 *
--- a/src/fsm/log/manager.c
+++ b/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.
@ -106,9 +106,10 @@ void fsm_add_log (int severity,


 /**
- * This function is only a relay: it calls fsm_init_log() and this call couldn't
- * be written in another file because the fsm_log_struct **gg_logs** it transmits
- * is **static** in src/fsm/log/manager.c
+ * Only a relay function: calls fsm_init_log(); nothing else.
+ *
+ * This call couldn't be written in another file because the fsm_log_struct
+ * **gg_logs** it transmits is **static** in src/fsm/log/manager.c
 *
 * Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.
 *
@ -127,8 +128,10 @@ void fsm_relay_init_log()


 /**
- * This function is only a relay: it calls fsm_publish_log() and fsm_clear_log()
- * and this calls couldn't be written in another file because the fsm_log_struct
+ * Only a relay function: calls fsm_publish_log() and fsm_clear_log();
+ * nothing else.
+ *
+ * These calls couldn't be written in another file because the fsm_log_struct
 * **gg_logs** they transmit is **static** in src/fsm/log/manager.c
 *
 * Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.
--- a/src/fsm/log/oper.c
+++ b/src/fsm/log/oper.c
@ -1,12 +1,11 @@
 /**
 * @file
 *
- * This file is part of Gem-graph.
+ * Gem-graph client log executive functions container.
 *
- * The log (journal) stores chronologically the events during a session.
+ * The log stores chronologically all the events occuring during an execution.
 *
- * This file contains the executive functions needed to init the log, add an
- * event and publish the log.
+ * The executive functions initialise the log, add events and publish everything.
 *
 * The log presentation is:
 * [date - rank - source file - source function - value]
@ -44,9 +43,9 @@


 /**
- * init the log: a double chained list
+ * Inits the log: a double chained list.
 *
- * first and last records are set to NULL
+ * First and last records are set to NULL
 *
 * @since 2024-09
 *
@ -60,7 +59,7 @@ void fsm_init_log (fsm_log_struct *jj)


 /**
- * removes all the log content and free each unit
+ * Deletes all the contents of the log and frees each unit.
 *
 * @since 2024-09
 *
@ -82,7 +81,7 @@ void fsm_clear_log (fsm_log_struct *jj)


 /**
- * add an event
+ * Adds a log unit (an event) to the log list.
 *
 * *new_unit = malloc (sizeof (fsm_log_unit_struct));
 *
@ -122,9 +121,9 @@ void fsm_add_log_event (fsm_log_struct *jj,
 #define LOG_MAX_LENGTH 255 /**< arbitrary */

 /**
- * publish all the logs chronologically (using the g_lib function: g_message)
+ * Publishes all the logs chronologically (using the g_lib function: g_message)
 *
- * today, simply printed in the console;  TODO: print in a file
+ * Today, simply printed in the console;  TODO: print in a file
 *
 * @since 2024-09
 *
--- a/src/main.c
+++ b/src/main.c
@ -1,8 +1,22 @@
 /**
 * @file
- * Gem-graph-client main file.
+ * Main file of the Gem-graph client; contains only the main() function.
 *
- * This file is part of Gem-graph. It contains only the main() function.
+ * The main() function
+ * - **initialise**
+ * -# the log,
+ * -# the finite state machine (fsm),
+ * -# the application,
+ * -# the windows and
+ *
+ * - **close** all the elements it opened in reverse order
+ *   before ending the program execution
+ * .
+ *
+ * The default values of the fsm initial state will be specified in:
+ * src/fsm/control(). They are user preferences.
+ *
+ * About code organization, see src/readme.dox
 *
 * @cond LICENSE
 * Copyright © 2021 Libre en Communs <contact@a-lec.org>
@ -22,33 +36,11 @@
 * 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
- *
- * ---
- *
- * The main() function
- * - **initialise**
- * -# the log,
- * -# the finite state machine (fsm),
- * -# the application,
- * -# the windows and
- *
- * - **close** all the elements it opened in reverse order
- *   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.
- *
- * About code organization, see src/readme.dox
- *
- * ---
 */

 #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
@ -80,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);
-
-    fsm_add_log (INFO, MAIN, "main",
-                       "no g signal connect (activate)",
-                       "| 🖐️   windows creation denied");
+    g_signal_connect (app, "activate", G_CALLBACK (on_windows_activation), NULL);

    status = g_application_run (G_APPLICATION (app), argc, argv);
    g_object_unref (app);
--- a/src/readme.docs.c
+++ b/src/readme.docs.c
@ -1,8 +1,6 @@
 /**
 * @file
- * Gem-graph-client src/readme.docs file
- *
- *  This file is part of Gem-graph.
+ * Gem-graph-client quick documentation (NB see also the Manual)
 *
 * @cond LICENSE
 * Copyright © 2021 Libre en Communs <contact@a-lec.org>
--- a/src/widget/main_window/design.c
+++ b/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");
+}
+
--- a/src/widget/manager.c
+++ b/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");
+}
+