Preference Packs

From FreeCAD Documentation
Revision as of 05:07, 7 December 2021 by Chennes (talk | contribs) (Add more detail about creating new preference packs.)
Other languages:
This page documents a new feature in the 0.20 development branch. It is not available in previous releases. This documentation is a work-in-progress, please help us by improving it!

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 Apply 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 Save new... 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.

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".

Retrieved from "http://wiki.freecad.org/index.php?title=Preference_Packs&oldid=1083673"