Add documentation about the Tools and ToolHandles

CURA-7502

9 files changed, 86 insertions, 0 deletions

diff --git a/docs/scene/images/mirror_tool.jpg b/docs/scene/images/mirror_tool.jpg
new file mode 100644
index 0000000000..e3d485008e
--- /dev/null
+++ b/docs/scene/images/mirror_tool.jpg
diff --git a/docs/scene/images/per_objectsettings_tool.jpg b/docs/scene/images/per_objectsettings_tool.jpg
new file mode 100644
index 0000000000..0634177d4b
--- /dev/null
+++ b/docs/scene/images/per_objectsettings_tool.jpg
diff --git a/docs/scene/images/rotate_tool.jpg b/docs/scene/images/rotate_tool.jpg
new file mode 100644
index 0000000000..4e10569678
--- /dev/null
+++ b/docs/scene/images/rotate_tool.jpg
diff --git a/docs/scene/images/scale_tool.jpg b/docs/scene/images/scale_tool.jpg
new file mode 100644
index 0000000000..c413aa0caf
--- /dev/null
+++ b/docs/scene/images/scale_tool.jpg
diff --git a/docs/scene/images/selection_tool.jpg b/docs/scene/images/selection_tool.jpg
new file mode 100644
index 0000000000..c9058de526
--- /dev/null
+++ b/docs/scene/images/selection_tool.jpg
diff --git a/docs/scene/images/support_blocker_tool.jpg b/docs/scene/images/support_blocker_tool.jpg
new file mode 100644
index 0000000000..bdc4b118c2
--- /dev/null
+++ b/docs/scene/images/support_blocker_tool.jpg
diff --git a/docs/scene/images/tools_tool-handles_class_diagram.jpg b/docs/scene/images/tools_tool-handles_class_diagram.jpg
new file mode 100644
index 0000000000..cd58fad066
--- /dev/null
+++ b/docs/scene/images/tools_tool-handles_class_diagram.jpg
diff --git a/docs/scene/images/translate_tool.jpg b/docs/scene/images/translate_tool.jpg
new file mode 100644
index 0000000000..80886a7f17
--- /dev/null
+++ b/docs/scene/images/translate_tool.jpg
diff --git a/docs/scene/tools.md b/docs/scene/tools.md
new file mode 100644
index 0000000000..eff7e7a701
--- /dev/null
+++ b/docs/scene/tools.md
@@ -0,0 +1,86 @@
+# Tools
+
+Tools are plugin objects which are used to manipulate or interact with the scene and the objects (node) in the scene. 
+
+![Class diagram of tools in the scene](images/tools_tool-handles_class_diagram.jpg)
+
+Tools live inside the Controller of the Application and may be associated with ToolHandles. Some of them interact with the scene as a whole (such as the Camera), while others interact with the objects (nodes) in the Scene (selection tool, rotate tool, scale tool etc.). The tools that are available in Cura (excluding the ones provided by downloadable plugins) are the following:
+
+  * [CameraTool](#cameratool)
+  * [SelectionTool](#selectiontool)
+  * [TranslateTool](#translatetool)
+  * [ScaleTool](#scaletool)
+  * [RotateTool](#rotatetool)
+  * [MirrorTool](#mirrortool)
+  * [PerObjectSettingsTool](#perobjectsettingstool)
+  * [SupportEraserTool](#supporteraser)
+
+*****
+
+### CameraTool
+
+The CameraTool is the tool that allows the user to manipulate the Camera. It provides the functions of moving, zooming, and rotating the Camera. This tool does not contain a handle.
+
+### SelectionTool
+This tool allows the user to select objects and groups of objects in the scene. The selected objects gain a blue outline and become available in the code through the Selection class. 
+
+![Selection Tool](images/selection_tool.jpg)
+
+This tool does not contain a handle.
+
+### TranslateTool
+
+This tool allows the user to move the object around the build plate. The TranslateTool is activated once the user presses the Move icon in the tool sidebar or hits the shortcut (T) while an object is selected. 
+
+![Translate Tool](images/translate_tool.jpg)
+
+The TranslateTool contains the TranslateToolHandle, which draws the arrow handles on the selected object(s). The TranslateTool generates TranslateOperations whenever the object is moved around the build plate.
+
+
+### ScaleTool
+
+This tool allows the user to scale the selected object(s). The ScaleTool is activated once the user presses the Scale icon in the tool sidebar or hits the shortcut (S) while an object is selected. 
+
+![Scale Tool](images/scale_tool.jpg)
+
+The ScaleTool contains the ScaleToolHandle, which draws the box handles on the selected object(s). The ScaleTool generates ScaleOperations whenever the object is scaled.
+
+### RotateTool
+
+This tool allows the user to rotate the selected object(s). The RotateTool is activated once the user presses the Rotate icon in the tool sidebar or hits the shortcut (R) while an object is selected. 
+
+![Rotate Tool](images/rotate_tool.jpg)
+
+The RotateTool contains the RotateToolHandle, which draws the donuts (tori) and arrow handles on the selected object(s). The RotateTool generates RotateOperations whenever the object is rotated.
+
+
+### MirrorTool
+
+This tool allows the user to mirror the selected object(s) in the required direction. The MirrorTool is activated once the user presses the Mirror icon in the tool sidebar or hits the shortcut (M) while an object is selected. 
+
+![Mirror Tool](images/mirror_tool.jpg)
+
+The MirrorTool contains the MirrorToolHandle, which draws pyramid handles on the selected object(s). The MirrorTool generates MirrorOperations whenever the object is mirrored against an axis.
+
+### PerObjectSettingsTool
+
+This tool allows the user to change the mesh type of the object into one of the following:
+
+  * Normal Model
+  * Print as support
+  * Modify settings for overlaps
+     - Infill mesh only
+     - Cutting mesh
+  * Don't support overlaps
+
+![Per object settings tool](images/per_objectsettings_tool.jpg)
+
+Contrary to other tools, this tool doesn't have any handles and it does not generate any operations. This means that once an object's type is changed it cannot be undone/redone using the OperationStack. This tool adds a [SettingOverrideDecorator](scene.md#settingoverridedecorator) on the object's node instead, which allows the user to change certain settings only for this mesh.
+
+### SupportEraser tool
+
+This tool allows the user to add support blockers on the selected model. The SupportEraserTool is activated once the user pressed the Support Blocker icon in the tool sidebar or hits the shortcut (E) while an object is selected. With this tool active, the user can add support blockers (cubes) on the object by clicking on various places on the selected mesh.
+
+![Support Eraser Tool](images/support_blocker_tool.jpg)
+
+The SupportEraser uses a GroupOperation to add a new CuraSceneNode (the eraser) in the scene and set the selected model as the parent of the eraser. This means that the addition of Erasers in the scene can be undone/redone. The SupportEraser does not have any tool handles.
\ No newline at end of file