Workbench creation/fr

Introduction
Cette page vous montrera comment ajouter un nouvel atelier à l'interface FreeCAD. Les ateliers sont des conteneurs pour les commandes FreeCAD. Ils peuvent être codés en Python, en C++ ou en un mélange des deux, ce qui a l’avantage d’allier la vitesse de C++ à la souplesse de Python. Dans tous les cas, cependant, votre atelier sera lancé par un ensemble de deux fichiers Python.

La structure Atelier
Vous avez besoin d'un dossier, avec le nom de votre choix, placé dans le répertoire Mod de l'utilisateur, avec un fichier et, éventuellement, un fichier. Le fichier Init est exécuté au démarrage de FreeCAD et le fichier est exécuté immédiatement après, mais uniquement lorsque FreeCAD démarre en mode GUI. C'est tout ce dont FreeCAD a besoin pour trouver votre atelier au démarrage et l'ajouter à son interface.

Le répertoire User Mod est un sous-répertoire du répertoire de données de l'application utilisateur (vous pouvez trouver ce dernier en tapant dans la console Python):
 * Sous Linux, il s'agit généralement de.
 * Sous Windows, il s'agit de, qui est généralement.
 * Sur macOS, il s'agit généralement de.

Le répertoire Mod devrait ressembler à ceci:

Dans ces fichiers, vous pouvez faire ce que vous voulez. Ils sont généralement utilisés comme ceci :


 * Dans le fichier Init.py, vous ajoutez simplement quelques éléments utilisés même lorsque FreeCAD fonctionne en mode console, par exemple les importateurs et les exportateurs de fichiers


 * Dans le fichier InitGui.py, vous définissez généralement un atelier, qui contient un nom, une icône et une série de commandes FreeCAD (voir ci-dessous). Cet fichier Python définit également les fonctions exécutées lors du chargement de FreeCAD (essayez d'en faire le moins possible à ce niveau, afin de ne pas ralentir le démarrage). Un autre est exécuté lorsque l'atelier est activé (c'est là que vous ferez le plus du travail) et un troisième lorsque l'atelier est désactivé (vous pouvez donc supprimer des éléments si nécessaire).

La structure et le contenu des fichiers d'un atelier décrits ici constituent la manière classique de créer un nouvel atelier. Il est possible d'utiliser une légère variation dans la structure des fichiers lors de la création d'un nouvel atelier Python. Cette méthode alternative est mieux décrite comme un "atelier à espacement de noms", ouvrant la possibilité d'utiliser pip pour installer l'atelier. Les deux structures fonctionnent, il s'agit donc plutôt d'une question de préférence lors de la création d'un nouvel atelier. Le style et la structure pour les ateliers présentés ici sont disponibles dans l'espace de noms global de FreeCAD, alors que pour le style et la structure alternatifs, l'atelier réside dans un espace de noms dédié. Pour plus d'informations sur le sujet, voir En relation.

La structure d'atelier en C++
Si vous voulez coder votre atelier en python, vous n'avez pas besoin de faire très attention, vous pouvez simplement placer vos autres fichiers python avec vos fichiers Init.py et InitGui.py. Toutefois, lorsque vous travaillez avec C++, vous devez faire preuve d'une plus grande prudence et commencer par respecter une règle fondamentale de FreeCAD : la séparation de votre atelier entre une partie d'application (pouvant s'exécuter en mode console, sans aucun élément d'interface graphique) et une partie d'interface graphique qui ne sera chargé que lorsque FreeCAD s’exécutera avec son environnement graphique complet. Ainsi, lorsque vous construirez un atelier C++, vous élaborerez probablement deux modules, une application et une interface graphique. Ces deux modules doivent bien entendu être appelables depuis python. Tout module FreeCAD (App ou Gui) consiste à minima en un fichier init de module. Voici un fichier typique AppMyModuleGui.cpp :

Le fichier Init.py
Vous pouvez choisir la licence de votre choix pour votre atelier, mais sachez que si vous souhaitez que votre atelier soit intégré et distribué avec le code source de FreeCAD à un moment donné, il doit être LGPL2+, comme dans l'exemple ci-dessus. Voir Licence.

Les fonctions et  vous permettent de fournir le nom et l'extension d'un type de fichier, ainsi qu'un module Python responsable de son importation. Dans l'exemple ci-dessus, un module gérera les fichiers. Voir Extraits de codes pour plus d'exemples.

Ateliers Python
Ceci est le fichier InitGui.py:

En dehors de cela, vous pouvez faire ce que vous voulez : vous pouvez insérer tout votre code d'atelier dans le fichier InitGui.py si vous le souhaitez, mais il est généralement plus pratique de placer les différentes fonctions de votre atelier dans des fichiers séparés. Ainsi ces fichiers sont plus petits et plus faciles à lire. Ensuite, vous importerez ces fichiers dans votre fichier InitGui.py. Vous pouvez organiser ces fichiers comme bon vous semble, un bon exemple est en avoir un pour chaque commande FreeCAD que vous ajoutez.

Préférences
Vous pouvez ajouter une page Préférences pour votre atelier Python. Les pages Préférences recherchent une icône de préférence avec un nom spécifique dans le système de ressources Qt. Si votre icône ne se trouve pas dans le système de ressources ou si son nom n'est pas correct, votre icône n'apparaîtra pas sur la page Préférences.

Ajouter votre icône d'atelier :
 * l’icône des préférences doit être nommée "preferences-" + "nom du module" + ".svg" (en minuscules)
 * créez un fichier qrc contenant les noms de tous les icônes
 * dans le répertoire *.py principal, exécutez pyside-rcc -o myResources.py myqrc.qrc
 * dans InitGui.py, ajouter importer myResource(.py)
 * mettre à jour votre référentiel (git) avec myResources.py et myqrc.qrc

Vous devrez refaire les étapes si vous ajoutez/modifiez des icônes.

@kbwbe a créé un joli script pour compiler des ressources pour l'atelier A2Plus. Voir ci-dessous.

Ajouter votre/vos page(s) de préférence :
 * Vous devez compiler le plugin Qt Designer qui vous permet d’ajouter des paramètres de préférence avec Qt Designer
 * Créer un widget vide dans Qt Designer (sans boutons ni quoi que ce soit)
 * Concevez votre page de préférences, de nombreux paramètres qui doivent être enregistrés (préférences) doivent être l’un des widgets Gui::Pref* ajoutés par le plug-in)
 * Dans ces cas-là, veillez à renseigner PrefName (le nom de votre valeur de préférence) et PrefPath (ex: Mod/MyWorkbenchName), qui sauvegardera votre valeur sous BaseApp/Preferences/Mod/MyWorkbenchName
 * Enregistrez le fichier d'interface utilisateur dans votre atelier, assurez-vous qu'il est géré par cmake.
 * Dans votre atelier, par exemple dans le fichier InitGui, dans la méthode Initialize (mais tout autre endroit fonctionne également), ajoutez : FreeCADGui.addPreferencePage ("/path/to/myUiFile.ui", "MyGroup"), "MyGroup" étant l'un des groupes de préférences de la gauche. FreeCAD recherchera automatiquement un fichier "preferences-mygroup.svg" dans ses emplacements connus (que vous pouvez étendre avec FreeCADGui.addIconPath)
 * Assurez-vous que la méthode addPreferencePage n’est appelée qu’une fois, sinon votre page de préférence sera ajoutée plusieurs fois

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, 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 file called metadata.txt describing your workbench's external dependencies (on either other Addons, Workbenches, or Python modules). The format of this 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:

Ateliers en C++
Si vous voulez coder votre atelier en C++, vous souhaiterez probablement coder aussi sa définition elle-même en C++ (bien que cela ne soit pas nécessaire : vous pouvez également coder uniquement les outils en C++, et laisser la définition de de l'atelier en Python). Dans ce cas, le fichier InitGui.py devient très simple : il peut contenir une seule ligne :

où MyModule est votre atelier C++ complet, incluant les commandes et la définition de l'atelier.

Le codage des ateliers C++ fonctionne de manière assez similaire. Il s'agit d'un fichier Workbench.cpp typique à inclure dans la partie interface graphique de votre module :

Préférences
Vous pouvez également ajouter une page de préférences pour les ateliers C++. Les étapes sont similaires à celles de Python.

Commandes FreeCAD
Les commandes FreeCAD constituent le bloc de construction de base de l'interface FreeCAD. Ils peuvent apparaître sous la forme d'un bouton dans les barres d'outils et d'une entrée de menu dans les menus. Mais c'est la même commande. Une commande est une simple classe Python, qui doit contenir un couple attributs et fonctions prédéfinis, définissant le nom de la commande, son icône et l'action à effectuer lorsque la commande est activée.

Définition des commandes en C++
De la même manière, vous pouvez coder vos commandes en C++. Vous avez généralement un fichier Commands.cpp dans votre module d'interface graphique. Ceci est un fichier Commands.cpp typique :

"Compiler" votre fichier ressources
compileA2pResources.py depuis l'atelier A2Plus :

En relation

 * Traduction et ateliers externes
 * Namespaced Workbenches - discussion
 * freecad.workbench_starterkit