diff --git a/docs/readme b/docs/readme index 04ae548..71a1cd8 100644 --- 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. - * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ diff --git a/docs/showcase/E coli (Goodsell).png b/docs/showcase/E coli (Goodsell).png new file mode 100644 index 0000000..55b14b8 Binary files /dev/null and b/docs/showcase/E coli (Goodsell).png differ diff --git a/include/fsm.h b/include/fsm.h index 15c6782..dbfcafc 100644 --- a/include/fsm.h +++ b/include/fsm.h @@ -1,7 +1,6 @@ /** * @file - * This file is part of Gem-graph; it is the client fsm (finite state machine) - * header. + * FSM (Finite State Machine) header of the Gem-graph client. * * @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 diff --git a/include/widget.h b/include/widget.h new file mode 100644 index 0000000..1900509 --- /dev/null +++ b/include/widget.h @@ -0,0 +1,31 @@ +/** + * @file + * Widgets hierarchy header of the Gem-graph client; + * + * @cond LICENSE + * Copyright © 2021 Libre en Communs + * Copyright © 2021-2024 Adrien Bourmault + * Copyright © 2021-2024 Jean Sirmai + * + * 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 . + * @endcond + */ + + +#pragma once +#include + +void on_windows_activation (GtkApplication *app); +void widget_get_main_window (GtkWindow *main_window, GtkApplication *app); + diff --git a/src/fsm/control.c b/src/fsm/control.c index 1f44784..cd0c828 100644 --- 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 * diff --git a/src/fsm/log/appendix.c b/src/fsm/log/appendix.c index 067184e..e1c01ca 100644 --- 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. * diff --git a/src/fsm/log/manager.c b/src/fsm/log/manager.c index 6920e3b..057933a 100644 --- 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. diff --git a/src/fsm/log/oper.c b/src/fsm/log/oper.c index b94e662..fcf61a0 100644 --- a/src/fsm/log/oper.c +++ b/src/fsm/log/oper.c @@ -1,11 +1,11 @@ /** * @file * - * This file is part of Gem-graph; - * the log stores chronologically all the events during a run. + * Gem-graph client log executive functions container. * - * This file contains the executive functions needed to initialise the log, add - * events and publish everything. + * The log stores chronologically all the events occuring during an execution. + * + * 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)); * diff --git a/src/main.c b/src/main.c index b1b574c..2853716 100644 --- a/src/main.c +++ b/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 -#include "../include/fsm.h" // finite state machine (fsm) +#include "../include/fsm.h" +#include "../include/widget.h" /** * @since 2024-04 @@ -73,12 +71,8 @@ int main (int argc, char **argv) "g signal connect (activate)", "| 👉️ 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, "startup", G_CALLBACK (on_windows_startup), NULL); + g_signal_connect (app, "activate", G_CALLBACK (on_windows_activation), NULL); status = g_application_run (G_APPLICATION (app), argc, argv); g_object_unref (app); diff --git a/src/readme.docs.c b/src/readme.docs.c index 00862d1..43ddac5 100644 --- 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 diff --git a/src/widget/main_window/design.c b/src/widget/main_window/design.c new file mode 100644 index 0000000..eecd53c --- /dev/null +++ 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 + * Copyright © 2021-2024 Adrien Bourmault + * Copyright © 2021-2024 Jean Sirmai + * + * 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 . + * @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"); +} + diff --git a/src/widget/manager.c b/src/widget/manager.c new file mode 100644 index 0000000..c4ff5b1 --- /dev/null +++ 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 + * Copyright © 2021-2024 Adrien Bourmault + * Copyright © 2021-2024 Jean Sirmai + * + * 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 . + * @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"); +} +