Preference Packs: Difference between revisions
(→Distributing a pack: add interlink) |
(Add the beginnings of more detailed explanation.) |
||
| Line 1: | Line 1: | ||
<languages/> |
|||
<translate> |
|||
{{VeryImportantMessage|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! |
{{VeryImportantMessage|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. |
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|Preferences editor]]. |
|||
[[File:PreferencePacks MainInterface.png|500px]] |
|||
=== Applying an installed pack === |
=== Applying an installed pack === |
||
To apply a Preference Pack, click the {{Button|Apply}} button next to its name in the '''General''' tab of the [[Preferences_Editor|Preferences editor]]. |
To apply a Preference Pack, click the {{Button|Apply}} button next to its name in the '''General''' tab of the [[Preferences_Editor|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 === |
=== Creating a new pack === |
||
Packs can be created by hand, or jump-started by using the {{Button|Save new...}} button in the '''General''' tab of the [[Preferences_Editor|Preferences editor]]. |
Packs can be created by hand, or jump-started by using the {{Button|Save new...}} button in the '''General''' tab of the [[Preferences_Editor|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: |
||
[[File:PreferencePacks SaveNewPack.png|400px]] |
|||
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. |
|||
==== Included Template Details ==== |
|||
These sections list all of the preferences variables contained in each built-in template. Installed Addons may also provide their own templates (not documented here). Click "[Expand]" on the far right of each entry to see the list. |
|||
</translate> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Arch Colors''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Console Colors''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* Preferences/OutputWindow/colorText |
|||
* Preferences/OutputWindow/colorLogging |
|||
* Preferences/OutputWindow/colorWarning |
|||
* Preferences/OutputWindow/colorError |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Draft Colors ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* Preferences/Mod/Draft/constructioncolor |
|||
* Preferences/Mod/Draft/gridTransparency |
|||
* Preferences/Mod/Draft/gridColor |
|||
* Preferences/Mod/Draft/snapcolor |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Editor Colors ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Editor Font ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* Preferences/Editor/FontSize |
|||
* Preferences/Editor/Font |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Main Window Layout ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Path Colors ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Sketcher Colors ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Start Colors ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''TechDraw Colors ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<div class="mw-collapsible mw-collapsed toccolours"> |
|||
<translate> |
|||
'''Window Colors ''' |
|||
</translate> |
|||
<div class="mw-collapsible-content"> |
|||
* 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 |
|||
</div> |
|||
</div> |
|||
<translate> |
|||
=== Distributing a pack === |
=== Distributing a pack === |
||
Eventually packs will be distributed identically to [[External_workbenches|External Workbenches]], through the [[Image:Std_AddonMgr.svg|24px|link=Std_AddonMgr]] [[Std_AddonMgr|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". |
Eventually packs will be distributed identically to [[External_workbenches|External Workbenches]], through the [[Image:Std_AddonMgr.svg|24px|link=Std_AddonMgr]] [[Std_AddonMgr|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". |
||
</translate> |
|||
Revision as of 04:40, 7 December 2021
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.
Included Template Details
These sections list all of the preferences variables contained in each built-in template. 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
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".