From 55935908085677432f746f8378e600f4fd8234b0 Mon Sep 17 00:00:00 2001 From: Cyrille Bagard Date: Sat, 11 Jan 2020 12:39:32 +0100 Subject: Written a proper documentation for the Python gui.core module. --- plugins/pychrysalide/core/module.c | 2 +- plugins/pychrysalide/gui/core/items.c | 135 +++++++++++++-------------------- plugins/pychrysalide/gui/core/items.h | 7 +- plugins/pychrysalide/gui/core/module.c | 13 +++- plugins/pychrysalide/gui/core/panels.c | 21 +++-- 5 files changed, 80 insertions(+), 98 deletions(-) diff --git a/plugins/pychrysalide/core/module.c b/plugins/pychrysalide/core/module.c index 27113a0..11cd8ed 100644 --- a/plugins/pychrysalide/core/module.c +++ b/plugins/pychrysalide/core/module.c @@ -59,7 +59,7 @@ bool add_core_module(PyObject *super) "This module provides access to the Chrysalide core properties through" \ " the Python bindings.\n" \ "\n" \ - "Most of these features are singleton objects.\n" \ + "Some of these features are singleton objects.\n" \ "\n" \ "As attributes are not allowed for Python modules, all these" \ " property accesses are handled with methods." diff --git a/plugins/pychrysalide/gui/core/items.c b/plugins/pychrysalide/gui/core/items.c index bc5bbd6..f60cd93 100644 --- a/plugins/pychrysalide/gui/core/items.c +++ b/plugins/pychrysalide/gui/core/items.c @@ -71,6 +71,16 @@ static PyObject *py_items_change_current_content(PyObject *self, PyObject *args) GLoadedContent *content; /* Instance GLib correspondante*/ int ret; /* Bilan de lecture des args. */ +#define ITEMS_CHANGE_CURRENT_CONTENT_METHOD PYTHON_METHOD_DEF \ +( \ + change_current_content, "content", \ + METH_VARARGS, py_items, \ + "Change the current loaded content in the GUI." \ + "\n" \ + "The new content has to be a pychrysalide.analysis.LoadedContent" \ + " instance." \ +) + ret = PyArg_ParseTuple(args, "O&", convert_to_loaded_content, &content); if (!ret) return NULL; @@ -99,6 +109,16 @@ static PyObject *py_items_change_current_view(PyObject *self, PyObject *args) GLoadedPanel *panel; /* Instance GLib correspondante*/ int ret; /* Bilan de lecture des args. */ +#define ITEMS_CHANGE_CURRENT_VIEW_METHOD PYTHON_METHOD_DEF \ +( \ + change_current_view, "view", \ + METH_VARARGS, py_items, \ + "Change the current view in the GUI." \ + "\n" \ + "The new content has to be a pychrysalide.glibext.LoadedPanel" \ + " instance." \ +) + ret = PyArg_ParseTuple(args, "O&", convert_to_loaded_panel, &panel); if (!ret) return NULL; @@ -127,6 +147,16 @@ static PyObject *py_items_update_current_view(PyObject *self, PyObject *args) GLoadedPanel *panel; /* Instance GLib correspondante*/ int ret; /* Bilan de lecture des args. */ +#define ITEMS_UPDATE_CURRENT_VIEW_METHOD PYTHON_METHOD_DEF \ +( \ + update_current_view, "view", \ + METH_VARARGS, py_items, \ + "Update the current view in the GUI." \ + "\n" \ + "The new view has to be a pychrysalide.glibext.LoadedPanel" \ + " instance." \ +) + ret = PyArg_ParseTuple(args, "O&", convert_to_loaded_panel, &panel); if (!ret) return NULL; @@ -137,8 +167,6 @@ static PyObject *py_items_update_current_view(PyObject *self, PyObject *args) } - - /****************************************************************************** * * * Paramètres : self = classe représentant un binaire. * @@ -157,6 +185,16 @@ static PyObject *py_items_update_project(PyObject *self, PyObject *args) GStudyProject *project; /* Instance GLib correspondante*/ int ret; /* Bilan de lecture des args. */ +#define ITEMS_UPDATE_PROJECT_METHOD PYTHON_METHOD_DEF \ +( \ + update_project, "project", \ + METH_VARARGS, py_items, \ + "Update the GUI for the current project." \ + "\n" \ + "The provided project has to be an instance (or a subclass)" \ + " of pychrysalide.analysis.StudyProject." \ +) + ret = PyArg_ParseTuple(args, "O&", convert_to_study_project, &project); if (!ret) return NULL; @@ -171,70 +209,7 @@ static PyObject *py_items_update_project(PyObject *self, PyObject *args) * * * Paramètres : - * * * -* Description : Fournit un accès à une définition de type à diffuser. * -* * -* Retour : Définition d'objet pour Python. * -* * -* Remarques : - * -* * -******************************************************************************/ - -PyTypeObject *get_python_items_type(void) -{ - static PyMethodDef py_items_methods[] = { - { - "change_current_content", py_items_change_current_content, - METH_VARARGS | METH_STATIC, - "change_current_content($self, content/)\n--\n\nChange the current loaded content in the GUI." - }, - { - "change_current_view", py_items_change_current_view, - METH_VARARGS | METH_STATIC, - "change_current_view($self, view/)\n--\n\nChange the current view in the GUI." - }, - { - "update_current_view", py_items_update_current_view, - METH_VARARGS | METH_STATIC, - "update_current_view($self, view/)\n--\n\nUpdate the current view in the GUI." - }, - { - "update_project", py_items_update_project, - METH_VARARGS | METH_STATIC, - "update_project($self, view/)\n--\n\nUpdate the GUI for the current project." - }, - { NULL } - }; - - static PyGetSetDef py_items_getseters[] = { - { NULL } - }; - - static PyTypeObject py_items_type = { - - PyVarObject_HEAD_INIT(NULL, 0) - - .tp_name = "pychrysalide.gui.core.items", - .tp_basicsize = sizeof(PyObject), - - .tp_flags = Py_TPFLAGS_DEFAULT, - - .tp_doc = "Dealing with items of the GUI.", - - .tp_methods = py_items_methods, - .tp_getset = py_items_getseters - - }; - - return &py_items_type; - -} - - -/****************************************************************************** -* * -* Paramètres : module = module dont la définition est à compléter. * -* * -* Description : Prend en charge l'objet 'pychrysalide.gui.core.items'. * +* Description : Définit une extension du module 'gui.core' à compléter. * * * * Retour : Bilan de l'opération. * * * @@ -242,27 +217,23 @@ PyTypeObject *get_python_items_type(void) * * ******************************************************************************/ -bool ensure_python_items_is_registered(void) +bool populate_gui_core_module_with_items(void) { - PyTypeObject *type; /* Type Python de 'items' */ + bool result; /* Bilan à retourner */ PyObject *module; /* Module à recompléter */ - type = get_python_items_type(); - - if (!PyType_HasFeature(type, Py_TPFLAGS_READY)) - { - type->tp_new = PyType_GenericNew; - - if (PyType_Ready(type) != 0) - return false; - - module = get_access_to_python_module("pychrysalide.gui.core"); + static PyMethodDef py_items_methods[] = { + ITEMS_CHANGE_CURRENT_CONTENT_METHOD, + ITEMS_CHANGE_CURRENT_VIEW_METHOD, + ITEMS_UPDATE_CURRENT_VIEW_METHOD, + ITEMS_UPDATE_PROJECT_METHOD, + { NULL } + }; - if (!register_python_module_object(module, type)) - return false; + module = get_access_to_python_module("pychrysalide.gui.core"); - } + result = register_python_module_methods(module, py_items_methods); - return true; + return result; } diff --git a/plugins/pychrysalide/gui/core/items.h b/plugins/pychrysalide/gui/core/items.h index 1e73263..0ad602e 100644 --- a/plugins/pychrysalide/gui/core/items.h +++ b/plugins/pychrysalide/gui/core/items.h @@ -31,11 +31,8 @@ -/* Fournit un accès à une définition de type à diffuser. */ -PyTypeObject *get_python_items_type(void); - -/* Prend en charge l'objet 'pychrysalide.gui.core.items'. */ -bool ensure_python_items_is_registered(void); +/* Définit une extension du module 'gui.core' à compléter. */ +bool populate_gui_core_module_with_items(void); diff --git a/plugins/pychrysalide/gui/core/module.c b/plugins/pychrysalide/gui/core/module.c index 47c35b1..23a769d 100644 --- a/plugins/pychrysalide/gui/core/module.c +++ b/plugins/pychrysalide/gui/core/module.c @@ -52,12 +52,21 @@ bool add_gui_core_module(PyObject *super) bool result; /* Bilan à retourner */ PyObject *module; /* Sous-module mis en place */ +#define PYCHRYSALIDE_CORE_DOC \ + "This module provides access to the Chrysalide GUI core properties" \ + " through the Python bindings.\n" \ + "\n" \ + "Some of these features are singleton objects.\n" \ + "\n" \ + "As attributes are not allowed for Python modules, all these" \ + " property accesses are handled with methods." + static PyModuleDef py_chrysalide_gui_core_module = { .m_base = PyModuleDef_HEAD_INIT, .m_name = "pychrysalide.gui.core", - .m_doc = "Python module for Chrysalide.gui.core", + .m_doc = PYCHRYSALIDE_CORE_DOC, .m_size = -1, @@ -90,8 +99,8 @@ bool populate_gui_core_module(void) result = true; - if (result) result = ensure_python_items_is_registered(); if (result) result = populate_gui_core_module_with_global(); + if (result) result = populate_gui_core_module_with_items(); if (result) result = populate_gui_core_module_with_panels(); assert(result); diff --git a/plugins/pychrysalide/gui/core/panels.c b/plugins/pychrysalide/gui/core/panels.c index 3a3001c..a0bf853 100644 --- a/plugins/pychrysalide/gui/core/panels.c +++ b/plugins/pychrysalide/gui/core/panels.c @@ -39,7 +39,7 @@ /* Enregistre un panneau comme partie intégrante de l'éditeur. */ -static PyObject *py_panels_register_item(PyObject *, PyObject *); +static PyObject *py_panels_register_panel(PyObject *, PyObject *); @@ -56,12 +56,22 @@ static PyObject *py_panels_register_item(PyObject *, PyObject *); * * ******************************************************************************/ -static PyObject *py_panels_register_item(PyObject *self, PyObject *args) +static PyObject *py_panels_register_panel(PyObject *self, PyObject *args) { GPanelItem *item; /* Panneau à traiter */ GGenConfig *config; /* Configuration à consulter */ int ret; /* Bilan de lecture des args. */ +#define PANELS_REGISTER_PANEL_METHOD PYTHON_METHOD_DEF \ +( \ + register_panel, "panel", \ + METH_VARARGS, py_panels, \ + "Register a panel for the GUI." \ + "\n" \ + "The provided panel has to be a pychrysalide.gui.PanelItem" \ + " instance." \ +) + config = NULL; ret = PyArg_ParseTuple(args, "O&", convert_to_panel_item, &item); @@ -104,13 +114,8 @@ bool populate_gui_core_module_with_panels(void) PyObject *module; /* Module à recompléter */ static PyMethodDef py_panels_methods[] = { - - { "register_panel", py_panels_register_item, - METH_VARARGS, - "register_panel(item, config, /)\n--\n\nRegister a panel for the GUI." - }, + PANELS_REGISTER_PANEL_METHOD, { NULL } - }; module = get_access_to_python_module("pychrysalide.gui.core"); -- cgit v0.11.2-87-g4458