Preference Packs

A Preference Pack is a distributable collection of user preferences that can be installed as an add-on and applied as a single set. Any user parameter that can be set in the user.cfg file can be included in a Preference Pack. Applying a preference pack sets all of the variables in the supplied CFG file without modifying any other user settings. For example, these packs can be used to create "Themes" by bundling together a custom stylesheet along with a set of user preferences that sets the various colors and styles of items in FreeCAD that aren't controlled by stylesheet.

Main Preference Packs User Interface
Most user interaction with installed Preference Packs is via the general tab in the General settings section of the Preferences editor.



Applying an installed pack
To apply a Preference Pack, click the button next to its name in the General tab of the Preferences editor. The core of a Preference Pack is a set of user preferences, so choosing this item acts as though each individual preference item in that pack was manually selected, setting each preference to the value stored in the Pack. Optionally, the Pack author may have included a pre- and/or post-application macro that may also be run. Because these packs can potentially make large (and possibly undesirable) changes to your user preferences, a timestamped backup of your original preferences is taken, and stored in FREECAD_USER_DATA/SavedPreferencePacks/Backups. These backups are retained for one week.

Creating a new pack
Packs can be created by hand, or jump-started by using the  button in the  General tab of the Preferences editor. Clicking the button shows a dialog requesting a name for the new pack, and displays a set of checkboxes allowing only a subset of preferences to be stored:



Because of the way FreeCAD uses preferences internally, only items contained in these template files can be saved automatically using this procedure: items not included in the template files must be manually included in the pack's *.cfg file. There is no built-in limit to which preferences items may be included in a preference pack, but authors are strongly discouraged from changing a user's set language, or from modifying the recent files list, or from changing anything related to a temporary UI state (e.g. the saved size of a resizable window, etc.).

Included Template Details
These sections list all of the preferences variables contained in each built-in template. Right now they are focused on appearance-related items, but pull requests and forums suggestions for additional inclusions are welcome. Installed Addons may also provide their own templates (not documented here). Click "[Expand]" on the far right of each entry to see the list.

Arch Colors


 * Preferences/Mod/Arch/WallColor
 * Preferences/Mod/Arch/StructureColor
 * Preferences/Mod/Arch/RebarColor
 * Preferences/Mod/Arch/WindowColor
 * Preferences/Mod/Arch/WindowGlassColor
 * Preferences/Mod/Arch/PanelColor
 * Preferences/Mod/Arch/ColorHelpers
 * Preferences/Mod/Arch/defaultSpaceColor

Console Colors


 * Preferences/OutputWindow/colorText
 * Preferences/OutputWindow/colorLogging
 * Preferences/OutputWindow/colorWarning
 * Preferences/OutputWindow/colorError

Draft Colors 


 * Preferences/Mod/Draft/constructioncolor
 * Preferences/Mod/Draft/gridTransparency
 * Preferences/Mod/Draft/gridColor
 * Preferences/Mod/Draft/snapcolor

Editor Colors 


 * Preferences/Editor/Text
 * Preferences/Editor/Bookmark
 * Preferences/Editor/Breakpoint
 * Preferences/Editor/Keyword
 * Preferences/Editor/Comment
 * Preferences/Editor/Block comment
 * Preferences/Editor/Number
 * Preferences/Editor/String
 * Preferences/Editor/Character
 * Preferences/Editor/Class name
 * Preferences/Editor/Define name
 * Preferences/Editor/Operator
 * Preferences/Editor/Python output
 * Preferences/Editor/Python error
 * Preferences/Editor/Current line highlight

Editor Font 


 * Preferences/Editor/FontSize
 * Preferences/Editor/Font

Main Window Layout 


 * Preferences/MainWindow/DockWindows/Std_SelectionView
 * Preferences/MainWindow/DockWindows/Std_ComboView
 * Preferences/MainWindow/DockWindows/Std_ReportView
 * Preferences/MainWindow/DockWindows/Std_PythonView
 * Preferences/MainWindow/DockWindows/Std_TreeView
 * Preferences/MainWindow/DockWindows/Std_PropertyView
 * Preferences/MainWindow/DockWindows/Std_DAGView
 * Preferences/MainWindow/Toolbars/File
 * Preferences/MainWindow/Toolbars/Workbench
 * Preferences/MainWindow/Toolbars/Macro
 * Preferences/MainWindow/Toolbars/View
 * Preferences/MainWindow/Toolbars/Structure
 * Preferences/MainWindow/Toolbars/Navigation

Path Colors 


 * Preferences/Mod/Path/DefaultNormalPathColor
 * Preferences/Mod/Path/DefaultRapidPathColor
 * Preferences/Mod/Path/DefaultPathMarkerColor
 * Preferences/Mod/Path/DefaultExtentsColor
 * Preferences/Mod/Path/DefaultProbePathColor
 * Preferences/Mod/Path/DefaultHighlightPathColor
 * Preferences/Mod/Path/DefaultBBoxSelectionColor
 * Preferences/Mod/Path/DefaultBBoxNormalColor

Sketcher Colors 


 * Preferences/View/SketchEdgeColor
 * Preferences/View/SketchVertexColor
 * Preferences/View/EditedEdgeColor
 * Preferences/View/EditedVertexColor
 * Preferences/View/ConstructionColor
 * Preferences/View/ExternalColor
 * Preferences/View/InvalidSketchColor
 * Preferences/View/FullyConstrainedColor
 * Preferences/View/InternalAlignedGeoColor
 * Preferences/View/FullyConstraintElementColor
 * Preferences/View/FullyConstraintConstructionElementColor
 * Preferences/View/FullyConstraintInternalAlignmentColor
 * Preferences/View/FullyConstraintConstructionPointColor
 * Preferences/View/ConstrainedIcoColor
 * Preferences/View/NonDrivingConstrDimColor
 * Preferences/View/ConstrainedDimColor
 * Preferences/View/ExprBasedConstrDimColor
 * Preferences/View/DeactivatedConstrDimColor
 * Preferences/View/CursorTextColor
 * Preferences/View/CursorCrosshairColor
 * Preferences/View/CreateLineColor

Start Colors 


 * Preferences/Mod/Start/BackgroundColor1
 * Preferences/Mod/Start/BackgroundTextColor
 * Preferences/Mod/Start/PageColor
 * Preferences/Mod/Start/PageTextColor
 * Preferences/Mod/Start/BoxColor
 * Preferences/Mod/Start/LinkColor
 * Preferences/Mod/Start/BackgroundColor2

TechDraw Colors 


 * Preferences/Mod/TechDraw/Decorations/SectionColor
 * Preferences/Mod/TechDraw/Decorations/CenterColor
 * Preferences/Mod/TechDraw/Decorations/VertexColor
 * Preferences/Mod/TechDraw/Decorations/HighlightColor
 * Preferences/Mod/TechDraw/Colors/Hatch
 * Preferences/Mod/TechDraw/Colors/Background
 * Preferences/Mod/TechDraw/Colors/PreSelectColor
 * Preferences/Mod/TechDraw/Colors/HiddenColor
 * Preferences/Mod/TechDraw/Colors/SelectColor
 * Preferences/Mod/TechDraw/Colors/NormalColor
 * Preferences/Mod/TechDraw/Colors/CutSurfaceColor
 * Preferences/Mod/TechDraw/Colors/GeomHatch
 * Preferences/Mod/TechDraw/Colors/FaceColor
 * Preferences/Mod/TechDraw/Colors/ClearFace

Window Colors 


 * Preferences/View/BacklightColor
 * Preferences/View/BackgroundColor
 * Preferences/View/BackgroundColor2
 * Preferences/View/BackgroundColor3
 * Preferences/View/BackgroundColor4
 * Preferences/View/Simple
 * Preferences/View/Gradient
 * Preferences/View/UseBackgroundColorMid
 * Preferences/View/HighlightColor
 * Preferences/View/SelectionColor
 * Preferences/View/DefaultShapeColor
 * Preferences/View/RandomColor
 * Preferences/TreeView/TreeEditColor
 * Preferences/TreeView/TreeActiveColor
 * Preferences/MainWindow/TiledBackground
 * Preferences/MainWindow/StyleSheet

Structure of a saved Preference Pack
While the core of most Preference Packs is a single configuration file, because of their design for distribution, some auxiliary structure is also required. Four core files define a preference pack, laid out in the following directory structure (for a Preference Pack named "SamplePreferencePack")
 * package.xml
 * SamplePreferencePack/
 * SamplePreferencePack.cfg
 * pre.FCMacro
 * post.FCMacro

Other files may also be included, depending on what's required for the pack. A well-produced preference pack designed for distributing a visual theme called "DarkSide" for FreeCAD might look like:
 * package.xml
 * resources/
 * icons/
 * DarkSide.svg
 * DarkSide/
 * DarkSide.cfg
 * DarkSide.qss

Note the omission of the pre.FCMacro and post.FCMacro files, which are often unnecessary, as well as the including of an icon (for display by the Addon Manager), and the inclusion of a qss file (which will then be referenced in the DarkSide.cfg configuration data file). The format of the package.xml metadata file is described in Package_Metadata: a stub version of the file is created automatically by FreeCAD when you save a preference pack using the GUI as described above: these saved packs can be found in FREECAD_USER_DATA/SavedPreferencePacks.

The pre- and post- macro files are standard FreeCAD Python macros, and may contain any commands valid in such a macro. If the pre.FCMacro raises an exception (of any type), the application of the preference pack is cancelled. If the post.FCMacro raises an exception (of any type), the application of the pack is rolled back using the backup taken prior to its application. For example, these macros may be used to query the user for license acceptance, or to verify they are happy with the final state of their system after application.

Distributing a pack
Eventually packs will be distributed identically to External Workbenches, through the  Addon Manager. This feature is still under development. To install a pack manually, use git to clone the package repository into your FreeCAD data directory (the directory where your user.cfg file is located), in a subdirectory called "Preference Packs".