Tree view: Difference between revisions

From FreeCAD Documentation
mNo edit summary
mNo edit summary
 
(26 intermediate revisions by the same user not shown)
Line 6: Line 6:


<!--T:2-->
<!--T:2-->
The [[Tree_view|tree view]] appears in the {{MenuCommand|Model}} tab of the [[Combo_view|combo view]], one of the most important panels in the [[Interface|interface]]; it shows all user defined objects that are part of a FreeCAD document. The tree view is a representation of the [[document structure|document's structure]], and indicates what information is saved to disk.
The [[Tree_view|tree view]] is one of the most important panels in the [[Interface|interface]]. It shows all user defined objects that are part of a FreeCAD document. The tree view is a representation of the [[Document_structure|document's structure]], and indicates what information is saved to disk.


<!--T:3-->
<!--T:3-->
These objects don't necessarily have to be geometrical shapes visible in the [[3D_view|3D view]], but can also be supporting data objects created with any of the [[Workbenches|workbenches]].
These objects don't necessarily have to be geometrical shapes visible in the [[3D_view|3D view]], but can also be supporting data objects created with any of the [[Workbenches|workbenches]].


</translate>
<!--T:4-->
[[File:FreeCAD_Tree_view.png]]
[[File:FreeCAD_Tree_view.png]]
<translate>


<!--T:5-->
<!--T:5-->
Line 20: Line 21:


<!--T:7-->
<!--T:7-->
By default, whenever a new object is created, it is added to the end of the list in the tree view. The tree view allows managing the objects to keep them organized; it permits creating [[Std_Group|groups]], moving objects inside groups, moving groups inside other groups, renaming objects, copying objects, deleting objects, and other operations in the context menu (right click) which depend on the currently selected object and the currently active workbench.
By default, whenever a new object is created, it is added to the end of the list in the tree view. The tree view allows managing the objects to keep them organized; it permits creating [[Std_Group|groups]], moving objects inside groups, moving groups inside other groups, relabeling objects, copying objects, deleting objects, and using options from its [[#Context_menu|context menu]].


<!--T:8-->
<!--T:8-->
Many operations create objects that are dependent on a previously existing object. In this case, the tree view shows this relationship by absorbing the older object inside the new object. Expanding and collapsing the objects in the tree view shows the parametric history of that object. Objects that are deeper inside others are older, while objects that are outside are newer, and are derived from the older objects. By modifying the interior objects, the parametric operations propagate all the way to the top, generating a new result.
Many operations create objects that are dependent on a previously existing object. In this case, the tree view shows this relationship by absorbing the older object inside the new object. Expanding and collapsing the objects in the tree view shows the parametric history of that object. Objects that are deeper inside others are older, while objects that are outside are newer, and are derived from the older objects. By modifying the interior objects, the parametric operations propagate all the way to the top, generating a new result.


</translate>
<!--T:9-->
[[File:FreeCAD_Tree_view_parametric_history.png|x300px]]
[[File:FreeCAD_Tree_view_parametric_history_1.png|x304px]] [[File:FreeCAD_Tree_view_parametric_history_2.png|x304px]]
<translate>

<!--T:10-->
[[File:FreeCAD_Tree_view_parametric_history_3.png|x304px]]


<!--T:11-->
<!--T:11-->
{{Caption|The topmost object is created by doing parametric operations on objects which themselves were created by previous operations. Expanding the tree many levels reveals the original elements that were used to create the partial solids.}}
{{Caption|The topmost object is created by doing parametric operations on objects which themselves were created by previous operations.<br>
Fully expanding the tree reveals the original elements that were used to create the partial solids.}}


=== Labels & Attributes === <!--T:44-->
=== Tree view columns === <!--T:52-->


<!--T:45-->
<!--T:53-->
In the Labels & Attributes column the labels and icons of the objects are displayed.
By default the tree view only displays a single column with the labels and icons of objects. A second column with descriptions can optionally be displayed as well, column headings are then also added.


<!--T:54-->
Selecting an object in this column and pressing {{KEY|F2}} (on Windows and Linux), or {{KEY|Enter}} (on macOS), allows to edit the object's {{PropertyData|Label}} property in situ without detour via the context menu action described below or the [[Property_editor|Property editor]].
To enable the description column right click the tree view and in the context menu select:<br>
{{MenuCommand|Tree settings → Show description column}} {{Version|0.21}}


=== Description === <!--T:46-->
=== Edit object label === <!--T:55-->


<!--T:47-->
<!--T:48-->
Select an object in the first column and press {{KEY|F2}} (on Windows and Linux), or {{KEY|Enter}} (on macOS), to edit its {{PropertyData|Label}} property. This property can also be edited via the context menu option {{MenuCommand|Rename}} or in the [[Property_editor|Property editor]].
The Description column displays further information about objects, if available.


=== Edit object description === <!--T:56-->
This information is stored in an object's {{PropertyData|Label2}} property which can be edited in situ by selecting the object in this column and pressing {{KEY|F2}} (on Windows and Linux), or {{KEY|Enter}} (on macOS), or via the [[Property_editor|Property editor]].


== Actions == <!--T:12-->
<!--T:49-->
An object can optionally have a description. This information is stored in its {{PropertyData|Label2}} property. If the description column is displayed you can edit this property by selecting an object in that column and pressing {{KEY|F2}} (on Windows and Linux), or {{KEY|Enter}} (on macOS). The property can also be changed in the [[Property_editor|Property editor]].


<!--T:16-->
=== Context menu === <!--T:57-->
Since the tree view lists objects that may be visible in the [[3D_view|3D view]], many of the actions are the same as those that can be executed from the [[3D_view|3D view]]. The actions can be started from a {{MenuCommand|Context menu}} that can be accessed by right clicking either the background or an object.


<!--T:58-->
===Application start===
The options in the context menu of the tree view depend on the selected object(s) and the currently active workbench. To display this menu right-click the background of the list, right-click an object in the list, or select multiple objects in the list and then right-click one of them.


<!--T:13-->
=== Keyboard shortcuts === <!--T:40-->
When the application starts, the default [[Start_Workbench|Start Workbench]] is active, and no document has been created, the context menu of the [[Tree_view|tree view]] has only one entry:
* {{MenuCommand|Expression actions}}. When the cursor is moved onto it, a sub-menu opens containing four commands:
** [[Std_Expressions|Copy selected]]
** [[Std_Expressions|Copy active document]]
** [[Std_Expressions|Copy all documents]]
** [[Std_Paste|Paste]]
These allow working with various documents, but are disabled if no document is present.

===New document===

<!--T:17-->
Once a new document has been created right clicking the background opens the context menu now containing two entries:
* {{MenuCommand|Expression actions}} as above but with these two entries activated:
** [[Std_Expressions|Copy active document]]
** [[Std_Expressions|Copy all documents]]
* {{MenuCommand|Link actions}} - a sub-menu with two entries:
** {{MenuCommand|Make Link group}} - another sub-menu containing three commands:
*** [[Std_LinkMakeGroup|Simple group]]
*** [[Std_LinkMakeGroup|Group with links]]
***[[Std_LinkMakeGroup|Group with transform links]]
** [[Std_LinkMake|Make Link]]

=== Selecting the document === <!--T:19-->

<!--T:20-->
If you select the document and right click, in addition to {{MenuCommand|Expression actions}} and {{MenuCommand|Link actions}}, the context menu contains the following commands:
* {{MenuCommand|Show items hidden in tree view}}: if active, the tree view will show hidden items.
* {{MenuCommand|Search}}: shows an input field to search objects inside the selected document.
* {{MenuCommand|Close document}}: closes the selected document.
* {{MenuCommand|Add dependent objects to selection}}: all dependent objects will be added to the selection. This way one can see the dependencies and e.g. delete all dependent objects at once. Only available for objects with links and for documents.
* {{MenuCommand|Skip recomputes}}: if active, the document's objects will not [[Std_Refresh|recompute]] automatically.
* {{MenuCommand|Allow partial recomputes}}: if active, the document will allow [[Std_Refresh|recompute]] of only some objects. Only available if {{MenuCommand|Skip recomputes}} is activated.
* {{MenuCommand|Mark to recompute}}: marks all objects of the document as touched, and ready for [[Std_Refresh|recompute]].
* {{MenuCommand|[[Std_Group|Create group]]}}: creates a [[Std_Group|group]] in the selected document.

=== Selecting objects === <!--T:21-->

<!--T:22-->
Once objects are added to the document right clicking them will show additional commands. These depend on the number of selected objects, their type and also on the active workbench. In most cases and with most workbenches (except the [[Start_Workbench|Start Workbench]]) the following commands are then available:
* {{MenuCommand|[[Std_SetAppearance|Appearance]]}}: launches a dialog to change the visual properties of the whole object.
* {{MenuCommand|[[Std_RandomColor|Random color]]}}: assigns a random color to the object.
* {{MenuCommand|[[Std_Cut|Cut]]}}: disabled.
* {{MenuCommand|[[Std_Copy|Copy]]}}: copies an object into memory.
* {{MenuCommand|[[Std_Paste|Paste]]}}: pastes the copied object into the document; the copy is added to the end of the tree view.
* {{MenuCommand|[[Std_Delete|Delete]]}}: removes the object from the document.
* {{MenuCommand|[[#Eye_symbol|Toggle visibility in tree view]]}}: toggles the Tree view visibility of objects.
* {{MenuCommand|Mark to recompute}}: marks the selected object as touched, and ready for [[Std_Refresh|recompute]].
* {{MenuCommand|Recompute object}}: recomputes the selected object.
* {{MenuCommand|Rename}}: starts editing the label of the selected object, not the name which is read-only. This option is only available if a single object is selected.

<!--T:24-->
As an example of context menu extension, if a [[Part_Box|Part Box]] is right clicked while the [[Part_Workbench|Part Workbench]] is active the following additional commands are available:
* {{MenuCommand|[[Std_Edit|Edit]]}}: activates the edit mode of the object.
* {{MenuCommand|[[Std_TransformManip|Transform]]}}: launches the transform widget to move or rotate the object.
* {{MenuCommand|[[Part_EditAttachment|Attachment editor]]}}: launches a dialog to attach the object to one or more other objects.
* {{MenuCommand|[[Part_FaceColors|Set colors]]}}: sets the color of selected faces of the object.
* {{MenuCommand|[[Std_ToggleVisibility|Toggle visibility]]}}: makes the object visible or invisible in the [[3D_view|3D view]].
* {{MenuCommand|[[Std_ShowSelection|Show selection]]}}: makes the selected object visible.
* {{MenuCommand|[[Std_HideSelection|Hide selection]]}}: makes the selected object invisible.
* {{MenuCommand|[[Std_ToggleSelectability|Toggle selectability]]}}: toggles the selectability of the object in the [[3D_view|3D view]].
* {{MenuCommand|[[Std_TreeSelectAllInstances|Select all instances]]}}: selects all instances of this object in the tree view.
* {{MenuCommand|[[Std_SendToPythonConsole|Send to Python Console]]}}: creates a variable in the [[Python_console|Python console]] referencing the object

=== Keyboard actions === <!--T:40-->


<!--T:41-->
<!--T:41-->
The following keyboard actions are available when the focus is on the Tree view:
The following keyboard shortcuts are available when the focus is on the tree view:
* {{KEY|Ctrl}}+{{KEY|F}}: opens a search box at the bottom of the tree, allowing to search and reach objects using their names or labels.
* {{KEY|Ctrl}}+{{KEY|F}}: opens a search box at the bottom of the tree, allowing to search and reach objects using their names or labels.
* Expand and collapse actions using {{KEY|Alt}}+{{KEY|Arrow}} combinations: {{Version|0.20}}
* Expand and collapse actions using {{KEY|Alt}}+{{KEY|Arrow}} combinations: {{Version|0.20}}
Line 133: Line 72:


<!--T:27-->
<!--T:27-->
One or more smaller overlay icons can be displayed on top of an object's default icon in the tree view. The available overlay icons and their meaning are listed below.
One or more overlay icons can be displayed on top of an object's default icon in the tree view. The available overlay icons and their meaning are listed below.


=== [[File:FreeCAD_Tree_view_recompute.png]] White check mark on blue background === <!--T:29-->
=== [[File:FreeCAD_Tree_view_recompute.png]] White check mark on blue background === <!--T:29-->
Line 139: Line 78:
<!--T:30-->
<!--T:30-->
This indicates that the object has to be [[Std_Refresh|recomputed]], due to changes made to the model or because the user marked the object in the tree view context menu to be recomputed. In most cases recomputes are triggered automatically, but sometimes they are delayed for performance reasons.
This indicates that the object has to be [[Std_Refresh|recomputed]], due to changes made to the model or because the user marked the object in the tree view context menu to be recomputed. In most cases recomputes are triggered automatically, but sometimes they are delayed for performance reasons.

=== [[File:FreeCAD_Tree_view_error.png]] White exclamation mark on red background === <!--T:38-->

<!--T:39-->
This indicates that the object has an error that needs to be fixed. After recomputing the whole document a tooltip describing the error is shown when you hover the mouse over the object in the tree view. Note: All other objects depending on an object in such an error state will not be properly recomputed, thus they may still show some old state.


=== [[File:FreeCAD_Tree_view_tip.png]] White arrow on green background === <!--T:31-->
=== [[File:FreeCAD_Tree_view_tip.png]] White arrow on green background === <!--T:31-->
Line 145: Line 89:
This indicates the so called [[PartDesign_Body#Tip|Tip]] of a body. It is usually the last feature in a [[PartDesign_Body|PartDesign Body]] and represents the whole body to the world outside of the body, e.g. when the body is exported or used in [[Part_Boolean|Part boolean]] operations. The tip can be changed by the user.
This indicates the so called [[PartDesign_Body#Tip|Tip]] of a body. It is usually the last feature in a [[PartDesign_Body|PartDesign Body]] and represents the whole body to the world outside of the body, e.g. when the body is exported or used in [[Part_Boolean|Part boolean]] operations. The tip can be changed by the user.


=== [[File:FreeCAD_Tree_view_unattached.png]] Purple chain link on white background === <!--T:33-->
=== [[File:FreeCAD_Tree_view_unattached.png]] Purple chain link === <!--T:33-->


<!--T:34-->
<!--T:34-->
Line 156: Line 100:


<!--T:37-->
<!--T:37-->
This is only used for [[Sketch|sketches]] and indicates that the sketch is not fully constrained. Inside of [[Sketcher_Workbench|Sketcher]] the number of remaining degrees of freedom is shown in the solver messages.
This is only used for [[Sketch|sketches]] and indicates that the sketch is not fully constrained. If the sketch is in [[Sketcher_EditSketch|edit mode]] the number of remaining degrees of freedom is shown in the [[Sketcher_Dialog#Solver_messages|solver messages]].

=== [[File:FreeCAD_Tree_view_error.png]] White exclamation mark on red background === <!--T:38-->

<!--T:39-->
This indicates that the object has an error that needs to be fixed. After recomputing the whole document a tooltip describing the error is shown when you hover the mouse over the object in the tree view. Note: All other objects depending on an object in such an error state will not be properly recomputed, thus they may still show some old state.


=== [[File:FreeCAD_Tree_view_hidden.png]] Eye symbol === <!--T:42-->
=== [[File:FreeCAD_Tree_view_hidden.png]] Eye symbol === <!--T:42-->
Line 167: Line 106:
<!--T:43-->
<!--T:43-->
This indicates that the object will be hidden in the Tree view if the {{MenuCommand|Show items hidden in tree view}} context menu option is unchecked.
This indicates that the object will be hidden in the Tree view if the {{MenuCommand|Show items hidden in tree view}} context menu option is unchecked.

=== [[File:FreeCAD_Tree_view_frozen.png]] Cyan ice crystal === <!--T:59-->

<!--T:60-->
{{Version|0.22}}

<!--T:61-->
This indicates a frozen object that is not recomputed when its parents change.

=== [[File:FreeCAD_Tree_view_suppressed.png]] Red backslash === <!--T:62-->

<!--T:63-->
{{Version|0.22}}

<!--T:64-->
This indicates a suppressed [[PartDesign_Workbench|PartDesign]] feature.





Latest revision as of 14:11, 14 April 2024

Introduction

The tree view is one of the most important panels in the interface. It shows all user defined objects that are part of a FreeCAD document. The tree view is a representation of the document's structure, and indicates what information is saved to disk.

These objects don't necessarily have to be geometrical shapes visible in the 3D view, but can also be supporting data objects created with any of the workbenches.

The tree view showing various elements in the document.

Working with the tree view

By default, whenever a new object is created, it is added to the end of the list in the tree view. The tree view allows managing the objects to keep them organized; it permits creating groups, moving objects inside groups, moving groups inside other groups, relabeling objects, copying objects, deleting objects, and using options from its context menu.

Many operations create objects that are dependent on a previously existing object. In this case, the tree view shows this relationship by absorbing the older object inside the new object. Expanding and collapsing the objects in the tree view shows the parametric history of that object. Objects that are deeper inside others are older, while objects that are outside are newer, and are derived from the older objects. By modifying the interior objects, the parametric operations propagate all the way to the top, generating a new result.

The topmost object is created by doing parametric operations on objects which themselves were created by previous operations.
Fully expanding the tree reveals the original elements that were used to create the partial solids.

Tree view columns

By default the tree view only displays a single column with the labels and icons of objects. A second column with descriptions can optionally be displayed as well, column headings are then also added.

To enable the description column right click the tree view and in the context menu select:
Tree settings → Show description column introduced in version 0.21

Edit object label

Select an object in the first column and press F2 (on Windows and Linux), or Enter (on macOS), to edit its DataLabel property. This property can also be edited via the context menu option Rename or in the Property editor.

Edit object description

An object can optionally have a description. This information is stored in its DataLabel2 property. If the description column is displayed you can edit this property by selecting an object in that column and pressing F2 (on Windows and Linux), or Enter (on macOS). The property can also be changed in the Property editor.

Context menu

The options in the context menu of the tree view depend on the selected object(s) and the currently active workbench. To display this menu right-click the background of the list, right-click an object in the list, or select multiple objects in the list and then right-click one of them.

Keyboard shortcuts

The following keyboard shortcuts are available when the focus is on the tree view:

  • Ctrl+F: opens a search box at the bottom of the tree, allowing to search and reach objects using their names or labels.
  • Expand and collapse actions using Alt+Arrow combinations: introduced in version 0.20
    • Alt+Left: collapses selected item(s).
    • Alt+Right: expands selected item(s).
    • Alt+Up: expands selected item(s) with all their tier-1 children collapsed (deeper children remain unchanged).
    • Alt+Down: expands selected item(s) with all their tier-1 children expanded as well (deeper children remain unchanged).

Overlay icons

One or more overlay icons can be displayed on top of an object's default icon in the tree view. The available overlay icons and their meaning are listed below.

White check mark on blue background

This indicates that the object has to be recomputed, due to changes made to the model or because the user marked the object in the tree view context menu to be recomputed. In most cases recomputes are triggered automatically, but sometimes they are delayed for performance reasons.

White exclamation mark on red background

This indicates that the object has an error that needs to be fixed. After recomputing the whole document a tooltip describing the error is shown when you hover the mouse over the object in the tree view. Note: All other objects depending on an object in such an error state will not be properly recomputed, thus they may still show some old state.

White arrow on green background

This indicates the so called Tip of a body. It is usually the last feature in a PartDesign Body and represents the whole body to the world outside of the body, e.g. when the body is exported or used in Part boolean operations. The tip can be changed by the user.

Purple chain link

This is typically shown for sketches, geometric primitives, such as box, cylinder, etc. and Datum geometry. It indicates that the object is not attached to anything. It has no Attachment Offset and gets its position and alignment solely from its Placement property.

There is a Basic Attachment Tutorial explaining how to handle such objects.

Yellow X

This is only used for sketches and indicates that the sketch is not fully constrained. If the sketch is in edit mode the number of remaining degrees of freedom is shown in the solver messages.

Eye symbol

This indicates that the object will be hidden in the Tree view if the Show items hidden in tree view context menu option is unchecked.

Cyan ice crystal

introduced in version 0.22

This indicates a frozen object that is not recomputed when its parents change.

Red backslash

introduced in version 0.22

This indicates a suppressed PartDesign feature.