Workbench creation/pl

Wprowadzenie
Ta strona pokaże Ci, jak dodać nowe środowisko pracy do interfejsu programu FreeCAD. Środowiska pracy są kontenerami dla poleceń FreeCAD. Mogą być zakodowane w Pythonie, w C++ lub w mieszance obu tych języków, co ma tę zaletę, że łączy szybkość C++ z elastycznością Pythona. We wszystkich przypadkach jednak Twoje środowisko pracy będzie uruchamiane przez zestaw dwóch plików Python. Mogą to być "wewnętrzne" środowiska, dołączone do dystrybucji programu FreeCAD, lub "zewnętrzne", dystrybuowane za pomocą Menadżera dodatków lub instalowane ręcznie przez pobranie z jakiegoś repozytorium online. Wewnętrzne środowiska pracy mogą być napisane w C++, środowisku Python lub kombinacji tych dwóch środowisk, podczas gdy zewnętrzne środowiska pracy muszą być napisane wyłącznie w środowisku Python.



Struktura środowiska pracy
Potrzebny jest folder o dowolnej nazwie, umieszczony w katalogu Mod użytkownika, z plikiem i opcjonalnie plikiem. Plik Init jest wykonywany podczas uruchamiania FreeCAD, a plik jest wykonywany natychmiast po nim, ale tylko wtedy, gdy FreeCAD uruchamia się w trybie GUI. To wszystko, czego potrzebuje FreeCAD, aby znaleźć środowisko pracy podczas uruchamiania i dodać je do swojego interfejsu.

Katalog Mod użytkownika jest podkatalogiem katalogu danych aplikacji użytkownika (można go znaleźć wpisując w konsoli Python):
 * W systemie Linux jest to zazwyczaj  lub.
 * W systemie Windows jest to, który zwykle jest.
 * Na macOS jest to zazwyczaj.

Katalog Mod powinien wyglądać następująco:

Wewnątrz tych plików można robić, co się chce. Zazwyczaj są one używane w ten sposób:


 * W pliku Init.py wystarczy dodać kilka rzeczy używanych nawet wtedy, gdy FreeCAD działa w trybie konsoli, na przykład importerów i eksporterów plików.


 * W pliku InitGui.py zazwyczaj definiuje się środowisko pracy, które zawiera nazwę, ikonę i serię poleceń FreeCAD (patrz poniżej). Ten plik Pythona definiuje również funkcje, które są wykonywane podczas ładowania FreeCAD (starasz się robić tam jak najmniej, aby nie spowalniać uruchamiania), kolejną, która jest wykonywana, gdy środowisko pracy jest aktywowane (to tam będziesz wykonywał większość pracy), a trzecią, gdy środowisko pracy jest dezaktywowane (dzięki czemu możesz usuwać rzeczy w razie potrzeby).

Opisana tutaj struktura i zawartość plików środowiska pracy jest klasycznym sposobem tworzenia nowego środowiska pracy. Można użyć niewielkiej odmiany w strukturze plików podczas tworzenia nowego środowiska pracy w Pythonie, ten alternatywny sposób najlepiej opisać jako "środowisko pracy z przestrzenią nazw", otwierając możliwość użycia narzędzia pip do zainstalowania środowiska pracy. Obie struktury działają, więc jest to bardziej kwestia preferencji podczas tworzenia nowego środowiska roboczego. Przedstawiony tutaj styl i struktura środowiska roboczego są dostępne w globalnej przestrzeni nazw FreeCAD, podczas gdy w przypadku alternatywnego stylu i struktury środowisko robocze znajduje się w dedykowanej przestrzeni nazw. Więcej informacji na ten temat można znaleźć w sekcji Powiązane.



C++ struktura środowiska pracy
Jeśli zamierzasz zakodować swoje środowisko pracy w Pythonie, nie musisz zachować szczególnej ostrożności i możesz po prostu umieścić inne pliki Python razem z plikami Init.py i InitGui.py. Podczas pracy z C++ należy jednak zachować większą ostrożność i zacząć od przestrzegania jednej podstawowej zasady FreeCAD: Rozdzielenie środowiska pracy na część aplikacji (która może działać w trybie konsoli, bez żadnego elementu GUI) i część Gui, która zostanie załadowana tylko wtedy, gdy FreeCAD działa z pełnym środowiskiem GUI. Tak więc podczas tworzenia środowiska pracy C++, najprawdopodobniej utworzysz dwa moduły, App i Gui. Te dwa moduły muszą być oczywiście wywoływalne z Pythona. Każdy moduł FreeCAD (App lub Gui) składa się co najmniej z pliku inicjującego moduł. Jest to typowy plik AppMyModuleGui.cpp:



Plik Init.py
Możesz wybrać dowolną licencję dla swojego środowiska pracy, ale pamiętaj, że jeśli chcesz, aby Twoje środowisko pracy było w pewnym momencie zintegrowane z kodem źródłowym FreeCAD i rozpowszechniane z nim, musi to być LGPL2+, jak w powyższym przykładzie. Zobacz stronę wyjaśniającą zagadnienia Licencji.

The and  functions allow you to give the name and extension of a file type, and a Python module responsible for its import. In the example above, an module will handle  files. See Code snippets for more examples.

Python workbenches
This is the InitGui.py file:

Other than that, you can do anything you want: you could put your whole workbench code inside the InitGui.py if you want, but it is usually more convenient to place the different functions of your workbench in separate files. So those files are smaller and easier to read. Then you import those files into your InitGui.py file. You can organize those files the way you want, a good example is one for each FreeCAD command you add.

Ustawienia
You can add a Preferences page for your Python workbench. The Preferences pages look for a preference icon with a specific name in the Qt Resource system. If your icon isn't in the resource system or doesn't have the correct name, your icon won't appear on the Preferences page.

Adding your workbench icon:
 * the preferences icon needs to be named "preferences-" + "modulename" + ".svg" (all lowercase)
 * make a qrc file containing all icon names
 * in the main *.py directory, run pyside-rcc -o myResources.py myqrc.qrc
 * in InitGui.py, add import myResource(.py)
 * update your repository(git) with myResources.py and myqrc.qrc

You'll need to redo the steps if you add/change icons.

@kbwbe has created a nice script to compile resources for the A2Plus workbench. See below.

Adding your preference page(s):
 * You need to compile the Qt designer plugin that allows you to add preference settings with Qt Designer
 * Create a blank widget in Qt Designer (no buttons or anything)
 * Design your preference page, any setting that must be saved (preferences) must be one of the Gui::Pref* widgets that were added by the plugin)
 * In any of those, make sure you fill the PrefName (the name of your preference value) and PrefPath (ex: Mod/MyWorkbenchName), which will save your value under BaseApp/Preferences/Mod/MyWorkbenchName
 * Save the ui file in your workbench, make sure it's handled by cmake
 * In your workbench, for ex. inside the InitGui file, inside the Initialize method (but any other place works too), add: FreeCADGui.addPreferencePage("/path/to/myUiFile.ui","MyGroup"), "MyGroup" being one of the preferences groups on the left. FreeCAD will automatically look for a "preferences-mygroup.svg" file in its known locations (which you can extend with FreeCADGui.addIconPath)
 * Make sure the addPreferencePage method is called only once, otherwise your pref page will be added several times

Dystrybucja
To distribute your Python workbench, you may either simply host the files in some location and instruct your users to download them and place them in their Mod directory manually, or you may host them in an online git repository (GitHub, GitLab, Framagit, and Debian Salsa are currently supported locations) and configure them for the Addon Manager to install. Instructions for inclusion on FreeCAD's official Addons list can be found on the FreeCAD Addons GitHub repository. To use the Addon Manager, a package.xml metadata file should be included, which instructs the Addon Manager how to find your workbench's icon, and allows display of a description, version number, etc. It can also be used to specify other workbenches or Python packages that your Workbench either depends on, is blocked by, or is intended to replace.

For a quick guide on how to create a basic package.xml file and add a workbench to the Addon Manager see: Add Workbench to Addon Manager.

Optionally, you can include a separate metadata file describing your Python dependencies. This may be either a file called metadata.txt describing your workbench's external dependencies (on either other Addons, Workbenches, or Python modules), or a requirements.txt describing your Python dependencies. Note that if using a requirements.txt file, only the names of the specified packages are used for dependency resolution: pip command options, include options and version information are not supported by the Addon Manager. Users may manually run the requirements file using pip if those features are required.

The format of the metadata.txt file is plain text, with three optional lines:

Each line should consist of a comma-separated list of items your Workbench depends on. Workbenches may be either an internal FreeCAD Workbench, e.g. "FEM", or an external Addon, for example "Curves". The required and optional Python libraries should be specified with their canonical Python names, such as you would use with. For example:

You may also include a script that is run when your package is uninstalled. This is a file called "uninstall.py" located at the top level of your Addon. It is executed when a user uninstalls your Addon using the Addon Manager. Use it to clean up anything your Addon may have done to the users system that should not persist when the Addon is gone (e.g. removing cache files, etc.).

To ensure that your addon is being read correctly by the Addon Manager, you can enable a "developer mode" in which the Addon Manager examines all available addons and ensures their metadata contains the required elements. To enable this mode select:, see Preferences Editor.

C++ workbenches
If you are going to code your workbench in C++, you will probably want to code the workbench definition itself in C++ too (although it is not necessary: you could also code only the tools in C++, and leave the workbench definition in Python). In that case, the InitGui.py file becomes very simple: It might contain just one line:

where MyModule is your complete C++ workbench, including the commands and workbench definition.

Coding C++ workbenches works in a pretty similar way. This is a typical Workbench.cpp file to include in the Gui part of your module:

Ustawienia
You can add a Preferences page for C++ workbenches too. The steps are similar to those for Python.

Dystrybucja
There are two options to distribute a C++ workbench, you can either host precompiled versions for the different operating systems yourself, or you can request for your code to be merged into the FreeCAD source code. As mentioned above this requires a LGPL2+ license, and you must first present your workbench to the community in the FreeCAD forum for review.

FreeCAD commands
FreeCAD commands are the basic building block of the FreeCAD interface. They can appear as a button on toolbars, and as a menu entry in menus. But it is the same command. A command is a simple Python class, that must contain a couple of predefined attributes and functions, that define the name of the command, its icon, and what to do when the command is activated.

C++ command definition
Similarly, you can code your commands in C++, typically in a Commands.cpp file in your Gui module. This is a typical Commands.cpp file:

"Compiling" your resource file
compileA2pResources.py from the A2Plus workbench:

Powiązane

 * Translating an external workbench
 * Forum discussion: Namespaced Workbenches
 * freecad.workbench_starterkit