From ef7e30c65376345df9703501b92d9e4f7a79d7a6 Mon Sep 17 00:00:00 2001 From: vocx-fc Date: Fri, 1 May 2020 19:59:50 -0500 Subject: [PATCH] Draft: update description of drafttaskpanels package --- src/Mod/Draft/drafttaskpanels/README.md | 41 +++++++++++----- src/Mod/Draft/drafttaskpanels/__init__.py | 58 +++++++++++++++++++++-- 2 files changed, 82 insertions(+), 17 deletions(-) diff --git a/src/Mod/Draft/drafttaskpanels/README.md b/src/Mod/Draft/drafttaskpanels/README.md index 404c3c764d..1455ed2532 100644 --- a/src/Mod/Draft/drafttaskpanels/README.md +++ b/src/Mod/Draft/drafttaskpanels/README.md @@ -1,19 +1,36 @@ -2020 February +# General -These files provide the logic behind the task panels of the "GuiCommands" +2020 May + +These files provide the logic behind the "task panels" of the "GuiCommands" defined in `draftguitools/`. -These files should not have code to create the task panel windows -and widgets manually. These interfaces should be properly defined -in the `.ui` files made with QtCreator and placed inside -the `Resources/ui/` directory. +These files should not have code to create the task panel widgets manually. +These interfaces should be properly defined in `.ui` files +made with Qt Designer and placed inside the `Resources/ui/` directory. -There are many commands which aren't defined in `draftguitools/`, -and which therefore don't have an individual task panel. -These commands are defined in the big `DraftTools.py` file, -and their task panels are manually written in the large `DraftGui.py` module. -Therefore, these commands should be split into individual files, -and each should have its own `.ui` file. +There are many GUI commands which are "old style" and thus don't have +an individual task panel. These commands use the task panel defined +in the big `DraftGui.py` module. This module defines many widgets +for many tools, and selectively chooses the widgets to show and to hide +depending on the command that is activated. + +A big file that controls many widgets at the same time is difficult +to handle and to maintain because changing the behavior of one widget +may affect the operation of various GUI commands. +This must be changed so that in the future each tool has its own +individual task panel file, and its own `.ui` file. +Individual files are more maintainable because changes can be done +to a single tool without affecting the rest. For more information see the thread: [[Discussion] Splitting Draft tools into their own modules](https://forum.freecadweb.org/viewtopic.php?f=23&t=38593&start=10#p341298) + +# To do + +In the future each tool should have its own individual task panel file, +and its own `.ui` file. + +This should be done by breaking `DraftGui.py`, creating many `.ui` files, +creating many task panel modules, and making sure these modules +are used correctly by the GUI commands. diff --git a/src/Mod/Draft/drafttaskpanels/__init__.py b/src/Mod/Draft/drafttaskpanels/__init__.py index ca18b3c193..99af4cf612 100644 --- a/src/Mod/Draft/drafttaskpanels/__init__.py +++ b/src/Mod/Draft/drafttaskpanels/__init__.py @@ -1,7 +1,55 @@ -"""Classes that define the task panels of GUI commands. +# *************************************************************************** +# * (c) 2020 Eliud Cabrera Castillo * +# * * +# * This file is part of the FreeCAD CAx development system. * +# * * +# * This program is free software; you can redistribute it and/or modify * +# * it under the terms of the GNU Lesser General Public License (LGPL) * +# * as published by the Free Software Foundation; either version 2 of * +# * the License, or (at your option) any later version. * +# * for detail see the LICENCE text file. * +# * * +# * FreeCAD 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 Library General Public License for more details. * +# * * +# * You should have received a copy of the GNU Library General Public * +# * License along with FreeCAD; if not, write to the Free Software * +# * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * +# * USA * +# * * +# *************************************************************************** +"""Modules that define classes that handle task panels of the GuiCommands. -These classes load `.ui` files that will be used in the task panel -of the graphical commands. -The classes define the behavior and callbacks of the different widgets -included in the `.ui` file. +These classes load `.ui` files that will be used in the task panels +of the graphical commands defined in the `draftguitools` submodules. +These classes also define the callbacks and interactions of the widgets +in the `.ui` files. + +The task panel interface should be, in the possible, not manually written +in Python. Rather a `.ui` file should be built using Qt Designer, +and should be placed in the `Resources/ui/` directory so that it is loaded +by the respective task panel class. + +:: + + class CommandTaskPanel: + def __init__(self): + ui_file = ":/ui/TaskPanel_OrthoArray.ui" + self.form = Gui.PySideUic.loadUi(ui_file) + +At the moment, most GuiCommands don't have their own `.ui` file, +nor task panel class. Instead their task panels are completely defined +by the `DraftGui` module. + +This should be changed in the future because `DraftGui` +is a very large module, and creates many different widgets +and handles many callbacks, making it difficult to extend and maintain. +This module selectively chooses the widgets to show and to hide +depending on the command that is activated. + +Individual task panel classes and `.ui` files are more maintainable +because changes can be done to a single tool without affecting the rest, +and the module size is kept small. """