gem-graph-client/include/util.h

/**
 * @file
 * utilities header
 *
 * This file is part of Gem-graph.
 *
 * @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 <stdbool.h>
#include <stddef.h>
#include <gtk-4.0/gtk/gtk.h>

#include "../include/fsm.h"

char *util_read_file (char *filename);
// Programmers using the strcat function can easily be recognized as lazy and reckless.
// (quoted from:  The GNU C Library (glibc) manual - 5.5 Concatenating Strings)
char *util_concat (const char *str, ...);


/** phantom documentation used to test the functioning of doxygen */

typedef struct pile {
    int value;           /**< value   phantom documentation */
    struct pile *prev;   /**< *prev   phantom documentation */
} pile; // structure d'un élément

void util_pile_clear  (pile **);        //  vide toute la pile
void util_pile_view   (pile *);         //  affiche la pile en commençant par le sommet
int  util_pile_push   (pile **, int);   //  ajoute une valeur sur la pile
int  util_pile_pop    (pile **);        //  retire la dernière valeur empilée
int  util_pile_length (pile *p);        //  renvoie le nombre d'éléments de la pile

//------------------------------------------------------------------------------


/** phantom documentation used to test the functioning of doxygen */

typedef struct elem {
    int value;              /**< *value   phantom documentation */
    struct elem *prev;      /**< *prev    phantom documentation */
    struct elem *next;      /**< *next    phantom documentation */
} elem;


/** phantom documentation used to test the functioning of doxygen */

typedef struct {
    elem *first;            /**< *first   phantom documentation */
    elem *last;             /**< *last    phantom documentation */
} dblist;   //  structure d'accès à la liste
            //
void util_list_2x2_init       (dblist *l);          //  initialisation
void util_list_2x2_clear      (dblist *l);          //  vide toute la liste
void util_list_2x2_view       (dblist l);           //  affiche les valeurs de toute la liste
int  util_list_2x2_push_back  (dblist *l, int val); //  ajoute une valeur en fin de liste
int  util_list_2x2_push_front (dblist *l, int val); //  ajoute une valeur en début de liste
int  util_list_2x2_pop_back   (dblist *l);          //  retire une valeur en fin de liste
int  util_list_2x2_pop_front  (dblist *l);          //  retire une valeur en début de liste
int  util_list_2x2_length     (dblist l);           //  renvoie le nombre d'éléments de la liste

//------------------------------------------------------------------------------


/** phantom documentation used to test the functioning of doxygen */

typedef struct slist {
    int value;              /**< value   phantom documentation */
    struct slist *suiv;     /**< *suiv   phantom documentation */
} slist ;

void util_sorted_list_clear  (slist **sl);          //  vide toute la liste
void util_sorted_list_view   (slist *sl);           //  affiche toute la liste
int  util_sorted_list_insert (slist **sl, int val); //  insertion d'un élément selon son rang
int  util_sorted_list_pop    (slist **sl);          //  retire la dernière valeur de la liste
int  util_sorted_list_length (slist *sl);           //  renvoie le nombre d'éléments de la liste

//------------------------------------------------------------------------------

void util_trigger_test();       //  def: util/tests.c    calls: ...
void util_test_pile();          //  called in fsm/measure.c
void util_test_double_list();   //          "       "
void util_test_sorted_list();   //          "       "

//------------------------------------------------------------------------------

/**
 *  Look for stack entry and returns stack_id
 *
 *  @param *container_widget  generally the GtkBox that contains the GLArea
 *
 *  @returns stack_id
 */
long util_gl_get_stack(void *container_widget);

/**
 *  Look for stack entry and returns stack_id
 *
 *  @param *container_widget   generally the GtkBox that contains the GLArea
 *
 *  @returns stack_id
 */
long util_gl_is_util_ready(void *container_widget);

/**
 *  Look for stack entry and initializes OpenGL for it
 *
 *  @param *container_widget  generally the GtkBox that contains the GLArea
 *
 *  @returns bool  true if success
 */
bool util_gl_init_stack(void *container_widget, GError *error_buffer);

bool util_gl_shutdown_stack(void *container_widget, GError *error_buffer);

void util_gl_clean_stack_index(void);

/**
 *  Look for stack entry and triggers OpenGL for drawing
 *
 *  @param *container_widget  generally the GtkBox that contains the GLArea
 *
 *  @returns bool  true if success
 */
bool util_gl_render_stack(GtkWidget *container_widget);

bool util_gl_update_axis(GtkWidget *container_widget, int axis, int value);

/**
 *  Look for every stack entry and shutdowns OpenGL for it
 *
 *  @param void
 *
 *  @returns bool  true if success
 */
void util_gl_shutdown_all_stacks(void);

/**
 *  Creates a slider widget
 *
 *  @param axis   meaning which axis we're building (for label)
 *
 *  @returns GtkWidget*   pointer to the new widget
 */
GtkWidget *create_axis_slider(int axis);