diff --git a/src/Mod/Draft/draftguitools/README.md b/src/Mod/Draft/draftguitools/README.md index 873da82419..ca4699c0df 100644 --- a/src/Mod/Draft/draftguitools/README.md +++ b/src/Mod/Draft/draftguitools/README.md @@ -1,20 +1,45 @@ -2020 February +# General + +2020 May These files define the "GuiCommands", that is, classes called in a graphical way through either buttons, menu entries, or context actions. -They don't define the graphical interfaces themselves, they just setup -tools that connect with FreeCAD's C++ code. +They don't define the graphical interfaces themselves, but set up +the interactions that allow running Python functions +when graphical data is provided, for example, when points or objects +are selected in the 3D view. -These tools should be split from the big `DraftTools.py` module. -The classes defined here internally use the GUI-less functions -defined in `Draft.py`, or in the newer modules under `draftobjects/`. +There is no need to check for the existence of the graphical interface (GUI) +when loading these classes as these classes only work with the GUI +so we must assume the interface is already available. +These command classes are normally loaded by `InitGui.py` +during the initialization of the workbench. -These tools are loaded by `InitGui.py`, and thus require the graphical -interface to exist. +These tools were previously defined in the `DraftTools.py` module, +which was very large. Now `DraftTools.py` is an auxiliary module +which just loads the individual tool classes; therefore, importing +`DraftTools.py` in `InitGui.py` is sufficient to make all commands +of the Draft Workbench accessible to the system. +Then the toolbars can be defined with the command names. -Those commands that require a "task panel" call the respective module -and class in `drafttaskpanels/`. The task panel interfaces themselves -are defined inside the `Resources/ui/` files created with QtCreator. +The classes defined here internally use the public functions provided +by `Draft.py`, which are ultimately defined in the modules +under `draftutils/`, `draftfunctions/`, and `draftmake/`. + +Those GUI commands that launch a "task panel" set up the respective widgets +in two different ways typically. +- "Old" commands set up the task panel from the `DraftGui.py` module. +- "New" commands call the respective class from a module in `drafttaskpanels/`, +which itself loads a `.ui` file (created with Qt Designer) +from `Resources/ui/`. 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, +and making sure these GUI commands use them properly. diff --git a/src/Mod/Draft/draftguitools/__init__.py b/src/Mod/Draft/draftguitools/__init__.py index 5566380aa1..d946cb3c00 100644 --- a/src/Mod/Draft/draftguitools/__init__.py +++ b/src/Mod/Draft/draftguitools/__init__.py @@ -1,6 +1,65 @@ -"""Commands that require the graphical user interface to work. +# *************************************************************************** +# * (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 the workbench GuiCommands to perform graphical actions. -These GUI commands are called by buttons, menus, contextual menus, -toolbars, or other ways that require graphical widgets. -They are normally loaded in the workbench's `InitGui.py`. +These GUI Commands or tools are called by buttons, menus, contextual menus, +toolbars, and other graphical widgets. +They are normally loaded by the workbench's `InitGui` module. +In this workbench these GUI tools are loaded by the `DraftTools` +module, which itself is loaded by `InitGui.DraftWorkbench.Initialize`. + +This means that any script or workbench that wishes to use +this workbench's tools can import the individual modules, +or just `DraftTools`, to have access to them. + +:: + + import draftguitools.gui_rectangles + import draftguitools.gui_circles + import draftguitools.gui_arcs + import DraftTools + +These modules should not be imported in a console-only session, +as they are not intended to be used without the graphical interface (GUI). +They are also not generally suitable for scripting +as they normally require graphical input in the task panel or a selection +in the 3D view (`Gui.Selection`). + +Most of these GUI tools require certain components of Draft to exist +like the `gui_snapper.Snapper`, the `WorkingPlane.Plane`, +and the `DraftGui.DraftToolBar` classes. +These classes are normally installed in the global `App` or `Gui` +namespaces, so they are accessible at all times. + +:: + + import DraftGui + import draftguitools.gui_snapper + import WorkingPlane + Gui.draftToolBar = DraftGui.DraftToolBar() + Gui.Snapper = draftguitools.gui_snapper.Snapper() + App.DraftWorkingPlane = WorkingPlane.Plane() + +These classes can be imported and initialized individually +but it is easier to set them up just by importing `DraftTools`. """