From 3215c8a4264056bf4b4aa9adffe67ef596e70a35 Mon Sep 17 00:00:00 2001 From: marioalexis Date: Sun, 15 May 2022 09:59:16 -0300 Subject: [PATCH] Gui: Improve docstrings in CommandPy.xml --- src/Gui/CommandPy.xml | 109 ++++++++++++++++++--------------------- src/Gui/CommandPyImp.cpp | 46 +++++++++-------- 2 files changed, 74 insertions(+), 81 deletions(-) diff --git a/src/Gui/CommandPy.xml b/src/Gui/CommandPy.xml index 0556da17f3..2f416f5c1f 100644 --- a/src/Gui/CommandPy.xml +++ b/src/Gui/CommandPy.xml @@ -15,116 +15,107 @@ - Get a given command by name or None if it doesn't exist. -get(string) -> Command - + get(name) -> Gui.Command or None\n +Get a given command by name or None if it doesn't exist.\n +name : str\n Command name. - Update active status of all commands. -update() -> None - + update() -> None\n +Update active status of all commands. - Returns the name of all commands. -listAll() -> list of strings - + listAll() -> list of str\n +Returns the name of all commands. - Returns a list of all commands, filtered by shortcut. -listByShortcut(string, bool bUseRegExp=False) -> list of strings --- -Shortcuts are converted to uppercase and spaces removed prior to comparison. - + listByShortcut(string, useRegExp=False) -> list of str\n +Returns a list of all commands, filtered by shortcut. +Shortcuts are converted to uppercase and spaces removed +prior to comparison.\n +string : str\n Shortcut to be searched. +useRegExp : bool\n Filter using regular expression. - Runs the given command. -run() -> None - + run(item=0) -> None\n +Runs the given command.\n +item : int\n Item to be run. - Returns True if the command is active, False otherwise. -isActive() -> bool - + isActive() -> bool\n +Returns True if the command is active, False otherwise. - Returns string representing shortcut key accelerator for command. -getShortcut() -> string - + getShortcut() -> str\n +Returns string representing shortcut key accelerator for command. - Sets shortcut for given command, returns bool True for success. -setShortcut(string) -> bool - + setShortcut(string) -> bool\n +Sets shortcut for given command, returns True for success.\n +string : str\n Shortcut to be set. - Resets shortcut for given command back to the default, returns bool True for success. -resetShortcut() -> bool - + resetShortcut() -> bool\n +Resets shortcut for given command back to the default, returns True for success. - Return information about this command. -getInfo() -> list of strings --- -Usage: menuText, tooltipText, whatsThisText, statustipText, pixmapText, shortcutText. - + getInfo() -> dict\n +Return information about this command. - Return the associated QAction object. -getAction() -> list of QAction + getAction() -> list of QAction\n +Return the associated QAction object. - + - Create a custom command for a macro -createCustomCommand(macrofile, menuText, tooltipText, whatsThisText, statustipText, pixmapText, shortcutText) -> str --- -Only the macrofile argument is required, and should be the name of the macro file. All other arguments are -passed on to the command creation routines if they are provided. All arguments except the first accept None. - -Returns the name of the created custom command. - + createCustomCommand(macroFile, menuText, toolTip, whatsThis, statusTip, pixmap, shortcut) -> str\n +Create a custom command for a macro. Returns name of the created command.\n +macroFile : str\n Macro file. +menuText : str\n Menu text. Optional. +toolTip : str\n Tool tip text. Optional. +whatsThis : str\n `What's this?` text. Optional. +statusTip : str\n Status tip text. Optional. +pixmap : str\n Pixmap name. Optional. +shortcut : str\n Shortcut key sequence. Optional. - Remove the custom command if it exists -removeCustomCommand(name) -> bool --- -Given the name of a custom command, this removes that command. It is not an error -to remove a non-existent command, the function simply does nothing in that case. - -Returns True if something was removed, or False if not. - + removeCustomCommand(name) -> bool\n +Remove the custom command if it exists. +Given the name of a custom command, this removes that command. +It is not an error to remove a non-existent command, the function +simply does nothing in that case. +Returns True if something was removed, or False if not.\n +name : str\n Command name. - Find the name of a custom command, given a macro name -findCustomCommand(name) -> Optional[str] --- -Given the name of a macro, return the name of the custom command for that macro, or -None if there is no command matching that macro script name. - + findCustomCommand(name) -> str or None\n +Given the name of a macro, return the name of the custom command for that macro +or None if there is no command matching that macro script name.\n +name : str\n Macro name. diff --git a/src/Gui/CommandPyImp.cpp b/src/Gui/CommandPyImp.cpp index 527c5a8638..9a8b07fe6b 100644 --- a/src/Gui/CommandPyImp.cpp +++ b/src/Gui/CommandPyImp.cpp @@ -33,7 +33,7 @@ #include "Window.h" #include "PythonWrapper.h" -// inclusion of the generated files (generated out of AreaPy.xml) +// inclusion of the generated files (generated out of CommandPy.xml) #include "CommandPy.h" #include "CommandPy.cpp" @@ -86,8 +86,8 @@ PyObject* CommandPy::listAll(PyObject *args) PyObject* CommandPy::listByShortcut(PyObject *args) { char* shortcut_to_find; - bool bIsRegularExp = false; - if (!PyArg_ParseTuple(args, "s|b", &shortcut_to_find, &bIsRegularExp)) + PyObject* bIsRegularExp = Py_False; + if (!PyArg_ParseTuple(args, "s|O!", &shortcut_to_find, &PyBool_Type, &bIsRegularExp)) return nullptr; std::vector cmds = Application::Instance->commandManager().getAllCommands(); @@ -96,7 +96,7 @@ PyObject* CommandPy::listByShortcut(PyObject *args) Action* action = c->getAction(); if (action){ QString spc = QString::fromLatin1(" "); - if(bIsRegularExp){ + if(PyObject_IsTrue(bIsRegularExp)){ QRegExp re = QRegExp(QString::fromLatin1(shortcut_to_find)); re.setCaseSensitivity(Qt::CaseInsensitive); if (!re.isValid()){ @@ -105,7 +105,7 @@ PyObject* CommandPy::listByShortcut(PyObject *args) throw Py::RuntimeError(str.str()); } - if (re.indexIn(action->shortcut().toString().remove(spc).toUpper()) != -1){ + if (re.indexIn(action->shortcut().toString().remove(spc).toUpper()) != -1) { matches.push_back(c->getName()); } } @@ -261,7 +261,8 @@ PyObject* CommandPy::getInfo(PyObject *args) Command* cmd = this->getCommandPtr(); if (cmd) { Action* action = cmd->getAction(); - PyObject* pyList = PyList_New(6); + PyObject* pyDict = PyDict_New(); + const char* cmdName = cmd->getName(); const char* menuTxt = cmd->getMenuText(); const char* tooltipTxt = cmd->getToolTipText(); const char* whatsThisTxt = cmd->getWhatsThis(); @@ -271,19 +272,21 @@ PyObject* CommandPy::getInfo(PyObject *args) if (action) shortcutTxt = action->shortcut().toString().toStdString(); + PyObject* strCmdName = PyUnicode_FromString(cmdName); PyObject* strMenuTxt = PyUnicode_FromString(menuTxt ? menuTxt : ""); PyObject* strTooltipTxt = PyUnicode_FromString(tooltipTxt ? tooltipTxt : ""); PyObject* strWhatsThisTxt = PyUnicode_FromString(whatsThisTxt ? whatsThisTxt : ""); PyObject* strStatustipTxt = PyUnicode_FromString(statustipTxt ? statustipTxt : ""); PyObject* strPixMapTxt = PyUnicode_FromString(pixMapTxt ? pixMapTxt : ""); PyObject* strShortcutTxt = PyUnicode_FromString(!shortcutTxt.empty() ? shortcutTxt.c_str() : ""); - PyList_SetItem(pyList, 0, strMenuTxt); - PyList_SetItem(pyList, 1, strTooltipTxt); - PyList_SetItem(pyList, 2, strWhatsThisTxt); - PyList_SetItem(pyList, 3, strStatustipTxt); - PyList_SetItem(pyList, 4, strPixMapTxt); - PyList_SetItem(pyList, 5, strShortcutTxt); - return pyList; + PyDict_SetItemString(pyDict, "name", strCmdName); + PyDict_SetItemString(pyDict, "menuText", strMenuTxt); + PyDict_SetItemString(pyDict, "toolTip", strTooltipTxt); + PyDict_SetItemString(pyDict, "whatsThis", strWhatsThisTxt); + PyDict_SetItemString(pyDict, "statusTip", strStatustipTxt); + PyDict_SetItemString(pyDict, "pixmap", strPixMapTxt); + PyDict_SetItemString(pyDict, "shortcut", strShortcutTxt); + return pyDict; } else { PyErr_Format(Base::PyExc_FC_GeneralError, "No such command"); @@ -322,16 +325,18 @@ PyObject* CommandPy::getAction(PyObject *args) } -PyObject* CommandPy::createCustomCommand(PyObject* args) +PyObject* CommandPy::createCustomCommand(PyObject* args, PyObject* kw) { - const char* macroFile = nullptr; + const char* macroFile; const char* menuTxt = nullptr; const char* tooltipTxt = nullptr; const char* whatsthisTxt = nullptr; const char* statustipTxt = nullptr; const char* pixmapTxt = nullptr; const char* shortcutTxt = nullptr; - if (!PyArg_ParseTuple(args, "s|zzzzzz", ¯oFile, &menuTxt, &tooltipTxt, &whatsthisTxt, &statustipTxt, &pixmapTxt, &shortcutTxt)) + static char* kwlist[] = {"macroFile", "menuText", "toolTip", "whatsThis","statusTip", "pixmap", "shortcut", nullptr}; + if (!PyArg_ParseTupleAndKeywords(args, kw, "s|zzzzzz", kwlist, ¯oFile, &menuTxt, + &tooltipTxt, &whatsthisTxt, &statustipTxt, &pixmapTxt, &shortcutTxt)) return nullptr; auto name = Application::Instance->commandManager().newMacroName(); @@ -400,13 +405,10 @@ PyObject* CommandPy::findCustomCommand(PyObject* args) return false; }); - if (action != macros.end()) { + if (action != macros.end()) return PyUnicode_FromString((*action)->getName()); - } - else { - Py_INCREF(Py_None); - return Py_None; - } + else + Py_Return; } PyObject *CommandPy::getCustomAttributes(const char* /*attr*/) const