Workbench creation/zh-tw

Introduction
本頁將告訴你如何增加一個新的workbench到FreeCAD介面. Workbenches是一個FreeCAD指令的容器. 我們可以用Python、C++或者是混合使用前兩種語言來撰寫. 而混合使用的好處是可以擁有C++的速度和Python的 flexibility. 然而在所有的workbench都會藉由兩個檔案來開啟他們

workbench 架構
基本上這很簡單：需要再Mod資料夾裏面建立一個新的資料夾，並給資料夾一個任意的名字，並在資料夾中放入 Init.py 檔, 以及, 依照需求選擇放或不放一個 InitGui.py 檔. Init 會在FreeCAD開始的時候被執行然後通常會緊接著執行InitGui.py 檔，不過InitGui.py 檔只有在FreeCAD是在圖形化介面(GUI)模式下才會被執行 ，在 console 模式下不會被執行. 這些就是讓FreeCAD在啟動時找到你的workbench並且將他加到介面上所需要做的事情.

The user Mod directory is a sub-directory of the user application data directory (you can find the latter by typing in the Python console):
 * On Linux it is usually.
 * On Windows it is, which is usually.
 * On macOS it is usually.

The Mod directory should look like this:

在這些檔案裏面，你可以做任何你想做的事. 通常使用的方式如下


 * In the Init.py file you just add a couple of things used even when FreeCAD works in console mode, for example the file importers and exporters


 * In the InitGui.py file you usually define a workbench, which contains a name, an icon, and a series of FreeCAD commands (see below). That python file also defines functions that are executed when FreeCAD loads (you try to do as little as possible there, so you don't slow down the startup), another that gets executed when the workbench is activated (that's where you'll do most of the work), and a third one when the workbench is deactivated (so you can remove things if needed).

The structure and file content for a workbench described here is the classic way of creating a new workbench. One can use a slight variation in the structure of files when making a new Python workbench, that alternative way is best described as a "namespaced workbench", opening up the possibility to use pip to install the workbench. Both structures work, so it is more a question of preference when creating a new workbench. The style and structure for workbenches presented here are available in the global namespace of FreeCAD, whereas for the alternative style and structure the workbench resides in a dedicated namespace. For further readings on the topic see Related.

C++ workbench 架構
如果你打算要用Python來寫你的workbench程式碼，你只需要將其他Python檔案跟Init.py 和InitGui.py放在一起就好了，而不用再去煩惱其他事情. 不過當你是使用C++來撰寫workbench的時候，你必須特別留意並且遵守FreeCAD的一個基本規則：你必須將你的workbench分成App(可以在命令列介面下執行而不需要任何圖形使用者介面)和Gui(只有在FreeCAD在圖形使用者介面下執行時才會被載入)兩個部份. 所以用C++撰寫workbench你幾乎就像是在開發兩個modules，也就是App和Gui這兩個. 這兩個模組當然必須能被Python呼叫. 任何 FreeCAD module(App或Gui)至少都包含一個module的init 檔. 這是典型AppMyModuleGui.cpp檔 ：

Init.py 檔
你可以為你的workbench選擇任何你喜歡的license，不過要注意的是，如果你希望見到你的workbench被FreeCAD原始碼整合並且發佈，他必須是LGPL2+就如同上面的範例. FreeCAD.addImportType 和addEXportType 函式 allow you to give the name and extension of a file type, and a python module responsible for its import. 在上面的例子中，一個"importOwn.py" module 將會處理.own檔. 請看 Code snippets 來獲得更多的例子

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.

Preferences
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

Distribution
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 external Addons that your Workbench either depends on, is blocked by, or is intended to replace.

Optionally, you can include a 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.).

C++ workbenches
如果你要用C++來撰寫你的workbench，你可能也會想要用C++來撰寫workbench本身的定義(雖然不一定要這樣做：你也可以只用C++來寫你的工具，然後用Python來寫workbench的定義) 在這種狀況下，InitGui.py檔會變得十分簡單：他可能只有一行：

而MyModule是你整個C++ workbench，包含commands和workbench定義

用C++撰寫 workbenches的方法和用Python來撰寫的方式是十分類似的. 這是一個典型的Workbench.cpp to include in the Gui part of your module:

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

FreeCAD commands
FreeCAD commands 是FreeCAD interface的基本元素. 他可以是一個工具列上的一個按鈕，或是一個選單上的條目. 不過他們都是一樣的. 一個command是一個簡單的python類別，他必須包含幾個的預先定義的屬性和函式來定義這個command的名字，他的圖像以及當他被觸發時會做什麼.

C++ command definition
同樣地，你可以用C++編寫你的commands，通常會有一個Commands.cpp檔在你的Gui module. 這是一個典型的Commands.cpp檔

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

Related

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