[tepl] Amtk: add amtk_init() and amtk_finalize() functions

[Sébastien Wilmet <swilmet src gnome org>]

commit 3adc94ee959836a0e47dcf0ef66742e1be8d915a
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Jul 29 12:07:16 2017 +0200

    Amtk: add amtk_init() and amtk_finalize() functions
    
    Like in Devhelp.

 amtk/Makefile.am                     |    3 +
 amtk/amtk-init.c                     |   94 ++++++++++++++++++++++++++++++++++
 amtk/amtk-init.h                     |   36 +++++++++++++
 amtk/amtk.h                          |    1 +
 docs/reference/tepl-3.0-sections.txt |    7 +++
 docs/reference/tepl-docs.xml.in      |    1 +
 po/POTFILES.in                       |    1 +
 7 files changed, 143 insertions(+), 0 deletions(-)
---
diff --git a/amtk/Makefile.am b/amtk/Makefile.am
index 65e99c6..10f5ec9 100644
--- a/amtk/Makefile.am
+++ b/amtk/Makefile.am
@@ -1,6 +1,7 @@
 @CODE_COVERAGE_RULES@
 
 AM_CPPFLAGS =                          \
+       -DDATADIR=\""$(datadir)"\"      \
        -DG_LOG_DOMAIN=\"Amtk\"         \
        -DAMTK_COMPILATION              \
        -I$(top_builddir)               \
@@ -18,6 +19,7 @@ amtk_public_headers =                         \
        amtk-application-window.h               \
        amtk-factory.h                          \
        amtk-factory-menu.h                     \
+       amtk-init.h                             \
        amtk-menu-item.h                        \
        amtk-menu-shell.h                       \
        amtk-types.h                            \
@@ -31,6 +33,7 @@ amtk_public_c_files =                         \
        amtk-application-window.c               \
        amtk-factory.c                          \
        amtk-factory-menu.c                     \
+       amtk-init.c                             \
        amtk-menu-item.c                        \
        amtk-menu-shell.c                       \
        amtk-utils.c
diff --git a/amtk/amtk-init.c b/amtk/amtk-init.c
new file mode 100644
index 0000000..e56dff2
--- /dev/null
+++ b/amtk/amtk-init.c
@@ -0,0 +1,94 @@
+/*
+ * This file is part of Amtk - Actions, Menus and Toolbars Kit
+ *
+ * Copyright 2017 - Sébastien Wilmet <swilmet gnome org>
+ *
+ * Amtk is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU Lesser General Public License as published by the
+ * Free Software Foundation; either version 2.1 of the License, or (at your
+ * option) any later version.
+ *
+ * Amtk 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 Lesser General Public
+ * License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "config.h"
+#include "amtk-init.h"
+#include <glib/gi18n-lib.h>
+#include "amtk-action-info-central-store.h"
+
+/**
+ * amtk_init:
+ *
+ * Initializes the Amtk library (e.g. for the internationalization).
+ *
+ * This function can be called several times, but is meant to be called at the
+ * beginning of main(), before any other Amtk function call.
+ *
+ * Since: 3.0
+ */
+void
+amtk_init (void)
+{
+       static gboolean done = FALSE;
+
+       if (!done)
+       {
+               gchar *locale_dir;
+
+               locale_dir = g_build_filename (DATADIR, "locale", NULL);
+               bindtextdomain (GETTEXT_PACKAGE, locale_dir);
+               g_free (locale_dir);
+
+               bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
+
+               done = TRUE;
+       }
+}
+
+/**
+ * amtk_finalize:
+ *
+ * Free the resources allocated by Amtk. For example it unrefs the singleton
+ * objects.
+ *
+ * It is not mandatory to call this function, it's just to be friendlier to
+ * memory debugging tools. This function is meant to be called at the end of
+ * main(). It can be called several times.
+ *
+ * Since: 3.0
+ */
+
+/* Another way is to use a DSO destructor, see gconstructor.h in GLib.
+ *
+ * The advantage of calling amtk_finalize() at the end of main() is that
+ * gobject-list [1] correctly reports that all Amtk* objects have been finalized
+ * when quitting the application. On the other hand a DSO destructor runs after
+ * the gobject-list's last output, so it's much less convenient, see:
+ * https://git.gnome.org/browse/gtksourceview/commit/?id=e761de9c2bee90c232875bbc41e6e73e1f63e145
+ *
+ * [1] A tool for debugging the lifetime of GObjects:
+ * https://github.com/danni/gobject-list
+ */
+void
+amtk_finalize (void)
+{
+       static gboolean done = FALSE;
+
+       /* Unref the singleton only once, even if this function is called
+        * multiple times, to see if a reference is not released correctly.
+        * Normally the singleton have a ref count of 1. If for some reason the
+        * ref count is increased somewhere, it needs to be decreased
+        * accordingly, at the right place.
+        */
+       if (!done)
+       {
+               _amtk_action_info_central_store_unref_singleton ();
+               done = TRUE;
+       }
+}
diff --git a/amtk/amtk-init.h b/amtk/amtk-init.h
new file mode 100644
index 0000000..72e8df9
--- /dev/null
+++ b/amtk/amtk-init.h
@@ -0,0 +1,36 @@
+/*
+ * This file is part of Amtk - Actions, Menus and Toolbars Kit
+ *
+ * Copyright 2017 - Sébastien Wilmet <swilmet gnome org>
+ *
+ * Amtk is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU Lesser General Public License as published by the
+ * Free Software Foundation; either version 2.1 of the License, or (at your
+ * option) any later version.
+ *
+ * Amtk 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 Lesser General Public
+ * License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef AMTK_INIT_H
+#define AMTK_INIT_H
+
+#if !defined (AMTK_H_INSIDE) && !defined (AMTK_COMPILATION)
+#error "Only <amtk/amtk.h> can be included directly."
+#endif
+
+#include <glib.h>
+
+G_BEGIN_DECLS
+
+void   amtk_init               (void);
+void   amtk_finalize           (void);
+
+G_END_DECLS
+
+#endif /* AMTK_INIT_H */
diff --git a/amtk/amtk.h b/amtk/amtk.h
index b8c94fb..145bd78 100644
--- a/amtk/amtk.h
+++ b/amtk/amtk.h
@@ -32,6 +32,7 @@
 #include <amtk/amtk-application-window.h>
 #include <amtk/amtk-factory.h>
 #include <amtk/amtk-factory-menu.h>
+#include <amtk/amtk-init.h>
 #include <amtk/amtk-menu-item.h>
 #include <amtk/amtk-menu-shell.h>
 #include <amtk/amtk-utils.h>
diff --git a/docs/reference/tepl-3.0-sections.txt b/docs/reference/tepl-3.0-sections.txt
index e917246..586ccf8 100644
--- a/docs/reference/tepl-3.0-sections.txt
+++ b/docs/reference/tepl-3.0-sections.txt
@@ -1,6 +1,13 @@
 <INCLUDE>tepl/tepl.h</INCLUDE>
 
 <SECTION>
+<FILE>amtk-init</FILE>
+<TITLE>Amtk Initialization and Finalization</TITLE>
+amtk_init
+amtk_finalize
+</SECTION>
+
+<SECTION>
 <FILE>amtk-application-window</FILE>
 AmtkApplicationWindow
 amtk_application_window_get_from_gtk_application_window
diff --git a/docs/reference/tepl-docs.xml.in b/docs/reference/tepl-docs.xml.in
index ef9cd4e..217bc95 100644
--- a/docs/reference/tepl-docs.xml.in
+++ b/docs/reference/tepl-docs.xml.in
@@ -20,6 +20,7 @@
     <chapter id="amtk">
       <title>Actions, Menus and Toolbars Kit for GTK+</title>
       <xi:include href="amtk-intro.xml"/>
+      <xi:include href="xml/amtk-init.xml"/>
       <xi:include href="xml/amtk-application-window.xml"/>
       <xi:include href="xml/amtk-action-info.xml"/>
       <xi:include href="xml/amtk-action-info-store.xml"/>
diff --git a/po/POTFILES.in b/po/POTFILES.in
index d375c79..904ac91 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -6,6 +6,7 @@ amtk/amtk-action-map.c
 amtk/amtk-application-window.c
 amtk/amtk-factory.c
 amtk/amtk-factory-menu.c
+amtk/amtk-init.c
 amtk/amtk-menu-item.c
 amtk/amtk-menu-shell.c
 amtk/amtk-utils.c