Updated the Python documentation for GUI items.

1 files changed, 236 insertions, 40 deletions

diff --git a/plugins/pychrysalide/gui/panel.c b/plugins/pychrysalide/gui/panel.c
index ccc4dc5..bbcd8f8 100644
--- a/plugins/pychrysalide/gui/panel.c
+++ b/plugins/pychrysalide/gui/panel.c
@@ -35,6 +35,7 @@
 #include <plugins/dt.h>
 
 
+#include "constants.h"
 #include "editem.h"
 #include "../access.h"
 #include "../helpers.h"
@@ -62,8 +63,20 @@ static int py_panel_item_init(PyObject *self, PyObject *args, PyObject *kwds);
 /* Place un panneau dans l'ensemble affiché. */
 static PyObject *py_panel_item_dock(PyObject *, PyObject *);
 
-/* Définit les constantes pour les panneaux. */
-static bool py_panel_item_define_constants(PyTypeObject *);
+/* Supprime un panneau de l'ensemble affiché. */
+static PyObject *py_panel_item_undock(PyObject *, PyObject *);
+
+/* Fournit une indication sur la personnalité du panneau. */
+static PyObject *py_panel_item_get_personality(PyObject *, void *);
+
+/* Fournit le chemin d'accès à utiliser pour les encapsulations. */
+static PyObject *py_panel_item_get_path(PyObject *, void *);
+
+/* Définit le chemin d'accès à utiliser pour les encapsulations. */
+static int py_panel_item_set_path(PyObject *, PyObject *, void *);
+
+/* Indique si le composant repose sur un support de l'éditeur. */
+static PyObject *py_panel_item_get_docked(PyObject *, void *);
 
 
 
@@ -184,6 +197,40 @@ static int py_panel_item_init(PyObject *self, PyObject *args, PyObject *kwds)
 
     static char *kwlist[] = { "name", "widget", "personality", "lname", "dock", "path", NULL };
 
+#define PANEL_ITEM_DOC                                                          \
+    "PanelItem is an abstract class for panels available in the main GUI"       \
+    " interface.\n"                                                             \
+    "\n"                                                                        \
+    "Instances can be created using the following constructor:\n"               \
+    "\n"                                                                        \
+    "    PanelItem(name=str, widget=Gtk.Widget,"                                \
+    " personality=PanelItemPersonality, lname=str, dock=bool, path=str)"        \
+    "\n"                                                                        \
+    "Where:\n"                                                                  \
+    "* name is the displayed label on the notebook tab when docked.\n"          \
+    "* widget is the main widget inside the panel.\n"                           \
+    "* personality defines how many instances of the panels can be created"     \
+    " at the same time.\n"                                                      \
+    "* lname is the long description used for the tooltip.\n"                   \
+    "* dock defines if the panel is docked by default.\n"                       \
+    "* path states the location of the panel inside the main GUI.\n"            \
+    "\n"                                                                        \
+    "The easiest way to pass all this information is probably to use a"         \
+    " transitional dictionary inside the panel *__init__()* constructor:\n"     \
+    "\n"                                                                        \
+    "    params = {\n"                                                          \
+    "        'name' : 'Tab label',\n"                                           \
+    "        'widget' : self._my_gtk_widget,\n"                                 \
+    "        'personality' : PanelItemPersonality.PIP_SINGLETON,\n"             \
+    "        'lname' : 'Long description for tooltip',\n"                       \
+    "        'dock' : True,\n"                                                  \
+    "        'path' : 'MES'\n"                                                  \
+    "    }\n"                                                                   \
+    "    super(MyPanel, self).__init__(**params)\n"                             \
+    "\n"                                                                        \
+    "For more details about the panel path, please refer to"                    \
+    " pychrysalide.gtkext.GtkDockable."
+
     /* Récupération des paramètres */
 
     ret = PyArg_ParseTupleAndKeywords(args, kwds, "sOksps", kwlist,
@@ -251,6 +298,13 @@ static PyObject *py_panel_item_dock(PyObject *self, PyObject *args)
 {
     GPanelItem *item;                       /* Panneau à manipuler         */
 
+#define PANEL_ITEM_DOCK_METHOD PYTHON_METHOD_DEF    \
+(                                                   \
+    dock, "$self, /",                               \
+    METH_NOARGS, py_panel_item,                     \
+    "Display the panel item in the right place."    \
+)
+
     item = G_PANEL_ITEM(pygobject_get(self));
 
     g_panel_item_dock(item);
@@ -262,6 +316,179 @@ static PyObject *py_panel_item_dock(PyObject *self, PyObject *args)
 
 /******************************************************************************
 *                                                                             *
+*  Paramètres  : self = classe représentant un binaire.                       *
+*                args = arguments fournis à l'appel.                          *
+*                                                                             *
+*  Description : Supprime un panneau de l'ensemble affiché.                   *
+*                                                                             *
+*  Retour      : Py_None.                                                     *
+*                                                                             *
+*  Remarques   : -                                                            *
+*                                                                             *
+******************************************************************************/
+
+static PyObject *py_panel_item_undock(PyObject *self, PyObject *args)
+{
+    GPanelItem *item;                       /* Panneau à manipuler         */
+
+#define PANEL_ITEM_UNDOCK_METHOD PYTHON_METHOD_DEF  \
+(                                                   \
+    undock, "$self, /",                             \
+    METH_NOARGS, py_panel_item,                     \
+    "Hide the panel item from the main interface."  \
+)
+
+    item = G_PANEL_ITEM(pygobject_get(self));
+
+    g_panel_item_undock(item);
+
+    Py_RETURN_NONE;
+
+}
+
+
+/******************************************************************************
+*                                                                             *
+*  Paramètres  : self    = objet Python concerné par l'appel.                 *
+*                closure = non utilisé ici.                                   *
+*                                                                             *
+*  Description : Fournit une indication sur la personnalité du panneau.       *
+*                                                                             *
+*  Retour      : Identifiant lié à la nature du panneau.                      *
+*                                                                             *
+*  Remarques   : -                                                            *
+*                                                                             *
+******************************************************************************/
+
+static PyObject *py_panel_item_get_personality(PyObject *self, void *closure)
+{
+    PyObject *result;                       /* Valeur à retourner          */
+    GPanelItem *item;                       /* Panneau à consulter         */
+    PanelItemPersonality personality;       /* Valeur native à convertir   */
+
+#define PANEL_ITEM_PERSONALITY_ATTRIB PYTHON_GET_DEF_FULL       \
+(                                                               \
+    personality, py_panel_item,                                 \
+    "Rule for handling panel creations, as a"                   \
+    " pychrysalide.gui.PanelItem.PanelItemPersonality value."   \
+)
+
+    item = G_PANEL_ITEM(pygobject_get(self));
+    personality = gtk_panel_item_get_personality(item);
+
+    result = cast_with_constants_group_from_type(get_python_panel_item_type(), "PanelItemPersonality", personality);
+
+    return result;
+
+}
+
+
+/******************************************************************************
+*                                                                             *
+*  Paramètres  : self    = objet Python concerné par l'appel.                 *
+*                closure = non utilisé ici.                                   *
+*                                                                             *
+*  Description : Fournit le chemin d'accès à utiliser pour les encapsulations.*
+*                                                                             *
+*  Retour      : Chemin d'accès défini.                                       *
+*                                                                             *
+*  Remarques   : -                                                            *
+*                                                                             *
+******************************************************************************/
+
+static PyObject *py_panel_item_get_path(PyObject *self, void *closure)
+{
+    PyObject *result;                       /* Valeur à retourner          */
+    GPanelItem *item;                       /* Panneau à consulter         */
+    const char *path;                       /* Chemin d'accès courant      */
+
+#define PANEL_ITEM_PATH_ATTRIB PYTHON_GETSET_DEF_FULL       \
+(                                                           \
+    path, py_panel_item,                                    \
+    "Get or define the current path of the panel item."     \
+)
+
+    item = G_PANEL_ITEM(pygobject_get(self));
+    path = gtk_panel_item_get_path(item);
+
+    result = PyUnicode_FromString(path);
+
+    return result;
+
+}
+
+
+/******************************************************************************
+*                                                                             *
+*  Paramètres  : self    = objet Python concerné par l'appel.                 *
+*                value   = valeur fournie à intégrer ou prendre en compte.    *
+*                closure = adresse non utilisée ici.                          *
+*                                                                             *
+*  Description : Définit le chemin d'accès à utiliser pour les encapsulations.*
+*                                                                             *
+*  Retour      : Bilan de l'opération.                                        *
+*                                                                             *
+*  Remarques   : -                                                            *
+*                                                                             *
+******************************************************************************/
+
+static int py_panel_item_set_path(PyObject *self, PyObject *value, void *closure)
+{
+    GPanelItem *item;                       /* Panneau à manipuler         */
+    const char *path;                       /* Nouveau chemin d'accès      */
+
+    if (!PyUnicode_Check(value))
+        return -1;
+
+    item = G_PANEL_ITEM(pygobject_get(self));
+
+    path = PyUnicode_DATA(value);
+
+    gtk_panel_item_set_path(item, path);
+
+    return 0;
+
+}
+
+
+/******************************************************************************
+*                                                                             *
+*  Paramètres  : self    = objet Python concerné par l'appel.                 *
+*                closure = non utilisé ici.                                   *
+*                                                                             *
+*  Description : Indique si le composant repose sur un support de l'éditeur.  *
+*                                                                             *
+*  Retour      : True si le composant est bien incrusté quelque part.         *
+*                                                                             *
+*  Remarques   : -                                                            *
+*                                                                             *
+******************************************************************************/
+
+static PyObject *py_panel_item_get_docked(PyObject *self, void *closure)
+{
+    PyObject *result;                       /* Valeur à retourner          */
+    GPanelItem *item;                       /* Panneau à consulter         */
+    bool docked;                            /* Statut de l'ancrage         */
+
+#define PANEL_ITEM_DOCKED_ATTRIB PYTHON_GET_DEF_FULL    \
+(                                                       \
+    docked, py_panel_item,                              \
+    "Dock status of the panel item."                    \
+)
+
+    item = G_PANEL_ITEM(pygobject_get(self));
+    docked = g_panel_item_is_docked(item);
+
+    result = docked ? Py_True : Py_False;
+    Py_INCREF(result);
+
+    return result;
+
+}
+
+
+/******************************************************************************
+*                                                                             *
 *  Paramètres  : -                                                            *
 *                                                                             *
 *  Description : Fournit un accès à une définition de type à diffuser.        *
@@ -275,15 +502,15 @@ static PyObject *py_panel_item_dock(PyObject *self, PyObject *args)
 PyTypeObject *get_python_panel_item_type(void)
 {
     static PyMethodDef py_panel_item_methods[] = {
-        {
-            "dock", py_panel_item_dock,
-            METH_NOARGS,
-            "dock($self, /)\n--\n\nDisplay the panel item in the right place."
-        },
+        PANEL_ITEM_DOCK_METHOD,
+        PANEL_ITEM_UNDOCK_METHOD,
         { NULL }
     };
 
     static PyGetSetDef py_panel_item_getseters[] = {
+        PANEL_ITEM_PERSONALITY_ATTRIB,
+        PANEL_ITEM_PATH_ATTRIB,
+        PANEL_ITEM_DOCKED_ATTRIB,
         { NULL }
     };
 
@@ -296,7 +523,7 @@ PyTypeObject *get_python_panel_item_type(void)
 
         .tp_flags       = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
 
-        .tp_doc         = "PyChrysalide panel item.",
+        .tp_doc         = PANEL_ITEM_DOC,
 
         .tp_methods     = py_panel_item_methods,
         .tp_getset      = py_panel_item_getseters,
@@ -313,37 +540,6 @@ PyTypeObject *get_python_panel_item_type(void)
 
 /******************************************************************************
 *                                                                             *
-*  Paramètres  : obj_type = type dont le dictionnaire est à compléter.        *
-*                                                                             *
-*  Description : Définit les constantes pour les panneaux.                    *
-*                                                                             *
-*  Retour      : -                                                            *
-*                                                                             *
-*  Remarques   : -                                                            *
-*                                                                             *
-******************************************************************************/
-
-static bool py_panel_item_define_constants(PyTypeObject *obj_type)
-{
-    bool result;                            /* Bilan à retourner           */
-
-    result = true;
-
-    result &= PyDict_AddULongMacro(obj_type, PIP_INVALID);
-
-    result &= PyDict_AddULongMacro(obj_type, PIP_SINGLETON);
-    result &= PyDict_AddULongMacro(obj_type, PIP_BINARY_VIEW);
-    result &= PyDict_AddULongMacro(obj_type, PIP_OTHER);
-
-    result &= PyDict_AddULongMacro(obj_type, PIP_COUNT);
-
-    return result;
-
-}
-
-
-/******************************************************************************
-*                                                                             *
 *  Paramètres  : module = module dont la définition est à compléter.          *
 *                                                                             *
 *  Description : Prend en charge l'objet 'pychrysalide.gui.panels.PanelItem'. *
@@ -378,7 +574,7 @@ bool ensure_python_panel_item_is_registered(void)
                                            get_python_editor_item_type(), get_python_gtk_dockable_type(), NULL))
             return false;
 
-        if (!py_panel_item_define_constants(type))
+        if (!define_panel_item_constants(type))
             return false;
 
     }