Add documentation for toolbar (#4907)

src/blenderbim/docs/users/user_interface.rst

@@ -18,5 +18,6 @@ The documentation doesn't cover Blender UI, but makes references to `Blender doc
 
    user_interface/topbar
    user_interface/workspace
+   user_interface/toolbar/index
    user_interface/property-editor
 

src/blenderbim/docs/users/user_interface/toolbar/annotation.rst

@@ -0,0 +1,7 @@
+.. _annotation-tool:
+
+Annotation Tool
+---------------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`Shift` + :kbd:`7`
+
+Use this to add various types of annotations to your model, such as text, dimensions, and markers.

src/blenderbim/docs/users/user_interface/toolbar/beam.rst

@@ -0,0 +1,7 @@
+.. _create-beam:
+
+Create Beam
+-----------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`0`
+
+Use this tool to add structural beam elements to your model. You can define beam profiles, lengths, and materials.

src/blenderbim/docs/users/user_interface/toolbar/column.rst

@@ -0,0 +1,7 @@
+.. _create-column:
+
+Create Column
+-------------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`9`
+
+Use this tool to add vertical structural elements like columns or pillars to your model.

src/blenderbim/docs/users/user_interface/toolbar/covering.rst

@@ -0,0 +1,7 @@
+.. _covering-tool:
+
+Covering Tool
+-------------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`Shift` + :kbd:`0`
+
+This tool is used for adding surface coverings to elements, such as wall finishes, flooring, and ceiling treatments.

src/blenderbim/docs/users/user_interface/toolbar/door.rst

@@ -0,0 +1,7 @@
+.. _create-door:
+
+Create Door
+-----------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`7`
+
+The Create Door tool allows you to insert door elements into walls. You can choose from various door types and adjust dimensions.

src/blenderbim/docs/users/user_interface/toolbar/duct.rst

@@ -0,0 +1,7 @@
+.. _create-duct:
+
+Create Duct
+-----------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`Shift` + :kbd:`2`
+
+This tool is used for creating HVAC ductwork. You can specify duct sizes, shapes, and routing.

src/blenderbim/docs/users/user_interface/toolbar/element.rst

@@ -0,0 +1,7 @@
+.. _create-element:
+
+Create Element
+--------------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`Shift` + :kbd:`6`
+
+A generic tool for creating custom IFC elements. This is useful for elements that don't have a specific creation tool.

src/blenderbim/docs/users/user_interface/toolbar/explore.rst

@@ -0,0 +1,52 @@
+Explore Tool
+============
+
+The Explore Tool is a powerful feature in BlenderBIM that enhances your ability to navigate and inspect IFC models.
+It introduces functionality commonly found in dedicated IFC viewers,
+making BlenderBIM a more comprehensive native IFC authoring and viewing tool.
+
+Shortcut
+--------
+
+:kbd:`Shift` + :kbd:`Spacebar`, :kbd:`5`
+
+Toolbar Icon
+------------
+
+.. figure:: images/toolbar_explore-tool.png
+   :alt: Explore tool icon in the BlenderBIM toolbar
+
+Tool Options
+------------
+
+.. figure:: images/property-editor_explore-tool.png
+   :alt: Explore tool options in the property editor
+
+Key Features
+------------
+
+- **Walk Mode** (Shortcut: :kbd:`Shift` + :kbd:`W`): Navigate through your model in a first-person perspective.
+   - Use :kbd:`W`, :kbd:`A`, :kbd:`S`, :kbd:`D` keys or arrow keys for movement.
+   - Provides a game-like experience for exploring interiors.
+
+- **Add Clipping Plane** (Shortcut: :kbd:`Shift` + :kbd:`C`): Create a cutting plane to view cross-sections of your model.
+   - Drag the plane to adjust its position.
+   - Add multiple clipping planes simultaneously for complex views.
+
+- **Flip Clipping Plane** (Shortcut: :kbd:`Shift` + :kbd:`F`): Reverse the direction of the active clipping plane.
+
+
+Usage
+-----
+
+1. Activate the tool from the toolbar or use the shortcut.
+2. Select the element you want to interact with.
+3. Select the desired option by pressing the corresponding shortcut.
+4. Interact with your model in the 3D viewport:
+
+   * For Walk Mode, use WASD or arrow keys to move through the model.
+   * For Clipping Plane, drag the plane to desired position and use Shift+F to flip if needed.
+
+The Explore Tool significantly enhances the model navigation and inspection capabilities of BlenderBIM.
+It's particularly useful for understanding spatial relationships, inspecting building cross-sections, and navigating through complex interiors.
+These features make BlenderBIM more comparable to dedicated IFC viewers while retaining its powerful authoring capabilities.

src/blenderbim/docs/users/user_interface/toolbar/index.rst

@@ -0,0 +1,166 @@
+=======
+Toolbar
+=======
+
+Tool System Overview
+====================
+
+BlenderBIM extends Blender's tool system, which provides a consistent way to interact with the 3D viewport. Here are some key points about the tool system:
+
+- Tools are accessed from the Toolbar, typically located on the left side of the 3D viewport.
+- Only one tool can be active per Workspace and mode.
+- Most tools are controlled using the Left Mouse Button (LMB), though some use modifier keys.
+- Press :kbd:`Shift` + :kbd:`Spacebar` to open the tool shortcut menu for quick access.
+- The Quick Favorites menu (:kbd:`Q`) allows you to gather your most-used tools for easy access.
+
+BlenderBIM integrates its tools seamlessly into this system, adding BIM-specific functionality while maintaining consistency with Blender's interface.
+
+Tool Settings Access
+--------------------
+
+.. figure:: images/toolbar_tool-settings-access.png
+
+
+Tool settings can be accessed in three different locations within the Blender interface:
+
+1. **3D Viewport**: The active tool's settings appear in the header of the 3D Viewport, providing quick access to essential options.
+
+2. **Sidebar (N panel)**: Tool settings can also be found in the Active Tool tab of the Sidebar. Access the Sidebar by pressing :kbd:`N` in the 3D Viewport.
+
+3. **Properties Editor**: The Tool tab in the Properties editor offers another place for viewing settings of the active tool.
+
+These multiple access points allow you to choose the most convenient location based on your workflow and screen layout.
+
+Tool Tab in Property Editor
+---------------------------
+
+Each tool has its own set of options and settings,
+which can be found in the Tool tab of the Properties editor.
+This tab dynamically updates based on the currently active tool,
+providing context-specific controls and parameters.
+
+.. seealso::
+   For more detailed information on Blender's tool system,
+   refer to the `Blender Manual <https://docs.blender.org/manual/en/latest/interface/tool_system.html>`_.
+
+
+BlenderBIM Tools
+================
+
+The BlenderBIM toolbar extends Blender's built-in toolbar with additional tools specific to BIM modeling.
+These tools are positioned between the Transform and Annotate sections of the standard Blender toolbar.
+
+.. tip::
+  Press :kbd:`Shift` + :kbd:`Spacebar` to open the tool shortcut menu.
+  From there, you can quickly select any tool using its corresponding number or letter key.
+
+.. figure:: images/toolbar_shortcut-menu.png
+
+.. seealso::
+
+   For more information on standard Blender toolbar,
+   see the `Toolbar section in Blender Manual <https://docs.blender.org/manual/en/latest/scene_layout/object/tools/toolbar.html>`_.
+
+
+
+
+.. container:: toc-cards
+
+   .. container:: card
+
+      :doc:`explore`
+         Navigate and inspect your BIM model with advanced viewing options.
+
+   .. container:: card
+
+      :doc:`wall`
+         Add and manipulate wall elements in your floor plan.
+
+   .. container:: card
+
+      :doc:`slab`
+         Create floor and roof slabs in your BIM model.
+
+   .. container:: card
+
+      :doc:`door`
+         Insert and customize door elements in your walls.
+
+   .. container:: card
+
+      :doc:`window`
+         Add and adjust window elements in your walls.
+
+   .. container:: card
+
+      :doc:`column`
+         Place and modify structural column elements.
+
+   .. container:: card
+
+      :doc:`beam`
+         Add and customize beam elements in your structure.
+
+   .. container:: card
+
+      :doc:`duct`
+         Design and place HVAC ductwork in your model.
+
+   .. container:: card
+
+      :doc:`element`
+         Add custom IFC elements to your BIM project.
+
+   .. container:: card
+
+      :doc:`annotation`
+         Add various types of annotations to your model and drawings.
+
+   .. container:: card
+
+      :doc:`spatial`
+         Define and manage spatial structures within your BIM model.
+
+   .. container:: card
+
+      :doc:`structural`
+         Create and edit structural elements and relationships.
+
+   .. container:: card
+
+      :doc:`covering`
+         Add surface coverings to elements in your model.
+
+
+Click on a tool to learn more about its features and how to use it effectively in your BIM workflow.
+
+
+Using the Toolbar
+=================
+
+To use any of these tools, simply select the desired tool from the toolbar.
+The options and parameters for each tool will appear in the toolbar options panel at the bottom of the toolbar.
+Adjust these settings as needed before applying the tool in your 3D viewport.
+
+Remember that many of these tools interact with the IFC data structure underlying your BIM model.
+Always ensure you're working within the correct IFC context when using these tools.
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   explore
+   wall
+   slab
+   door
+   window
+   column
+   beam
+   duct
+   element
+   annotation
+   spatial
+   structural
+   covering
+

src/blenderbim/docs/users/user_interface/toolbar/slab.rst

@@ -0,0 +1,7 @@
+.. _create-slab:
+
+Create Slab
+-----------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`6`
+
+Use this tool to add floor or roof slabs to your model. You can define the thickness, span, and structural properties.

src/blenderbim/docs/users/user_interface/toolbar/spatial.rst

@@ -0,0 +1,7 @@
+.. _spatial-tool:
+
+Spatial Tool
+------------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`Shift` + :kbd:`8`
+
+This tool helps in defining and managing spatial structures within your BIM model, such as buildings, stories, and spaces.

src/blenderbim/docs/users/user_interface/toolbar/structural.rst

@@ -0,0 +1,7 @@
+.. _structural-tool:
+
+Structural Tool
+---------------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`Shift` + :kbd:`9`
+
+Use this for creating and editing structural elements beyond basic beams, such as columns, trusses, and reinforcements.

src/blenderbim/docs/users/user_interface/toolbar/wall.rst

@@ -0,0 +1,102 @@
+Create Wall
+===========
+
+The Create Wall tool in BlenderBIM allows you to add and manipulate wall elements in your floor plan.
+It provides options for specifying wall element properties and adjusting their alignment and orientation.
+
+Toolbar Icon
+------------
+
+.. figure:: images/toolbar_create-wall.png
+   :alt: Create Wall tool icon in the BlenderBIM toolbar
+
+Tool Options
+------------
+
+.. figure:: images/property-editor_create-wall.png
+   :alt: Create Wall tool options in the property editor
+
+Shortcut
+~~~~~~~~
+
+To access the Create Wall tool, you can use the following keyboard shortcut sequence:
+
+ :kbd:`Shift` + :kbd:`Spacebar`, ???
+
+Key Features
+~~~~~~~~~~~~
+
+Add Wall
+^^^^^^^^
+
+- **Shortcut**: :kbd:`Shift` + :kbd:`A`
+- Adds a new wall segment at the 3D cursor location.
+
+Add or Modify Wall
+^^^^^^^^^^^^^^^^^^
+
+- **Height**: Set the wall height.
+- **Length**: Set the wall length.
+- **X Angle**: Adjust the angle of the wall.
+
+Modify Wall
+^^^^^^^^^^^
+
+- **Extend** (Shortcut: :kbd:`Shift` + :kbd:`E`): Extend an existing wall to another face.
+- **Butt** (Shortcut: :kbd:`Shift` + :kbd:`T`): Join wall segments end-to-end.
+- **Mitre** (Shortcut: :kbd:`Shift` + :kbd:`Y`): Create a mitre joint between two wall segments.
+- **Merge** (Shortcut: :kbd:`Shift` + :kbd:`M`): Merge two wall segments into one.
+- **Flip** (Shortcut: :kbd:`Shift` + :kbd:`F`): Flip the direction of the wall segment.
+- **Split** (Shortcut: :kbd:`Shift` + :kbd:`K`): Split a wall segment into two parts.
+- **Rotate 90** (Shortcut: :kbd:`Shift` + :kbd:`R`): Rotate the wall by 90 degrees.
+- **Regen** (Shortcut: :kbd:`Shift` + :kbd:`G`): Regenerate the wall geometry.
+- **Add Void** (Shortcut: :kbd:`Shift` + :kbd:`O`): Create an opening in the wall for doors, windows, or other elements.
+
+Change walls alignment or move walls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- **Align Exterior** (Shortcut: :kbd:`Shift` + :kbd:`X`): Align wall to the exterior face.
+- **Align Centerline** (Shortcut: :kbd:`Shift` + :kbd:`C`): Align wall to the centerline.
+- **Align Interior** (Shortcut: :kbd:`Shift` + :kbd:`V`): Align wall to the interior face.
+- **Mirror** (Shortcut: :kbd:`Shift` + :kbd:`M`): Mirror wall.
+
+Wall Mode
+^^^^^^^^^
+
+- **Void** (Shortcut: :kbd:`Alt` + :kbd:`O`): Create voids in the walls.
+- **Decomposition** (Shortcut: :kbd:`Alt` + :kbd:`D`): Decompose wall elements.
+
+
+Aggregation
+^^^^^^^^^^^
+
+- **Assign** (Shortcut: :kbd:`Ctrl` + :kbd:`P`): Assign wall elements to a specific group.
+- **Unassign** (Shortcut: :kbd:`Alt` + :kbd:`P`): Remove wall elements from a group.
+
+Calculate Quantities
+^^^^^^^^^^^^^^^^^^^^
+
+- **Calculate All Quantities** (Shortcut: :kbd:`Q`): Calculate all quantities related to the walls (e.g., area, volume).
+
+Usage
+~~~~~
+
+To use the Create Wall tool:
+
+1. **Activate the tool** from the toolbar or use the shortcut :kbd:`A`.
+2. **Select the wall type** from the dropdown menu, or create a new wall type (which represents the wall thickness) and set other desired parameters.
+3. **Set the 3D cursor** to the desired starting location for the wall by holding :kbd:`Shift` and left-clicking in the 3D viewport.
+4. **Add the wall** by pressing :kbd:`Shift` + :kbd:`A`.
+5. **Adjust the length** of the wall segment by dragging the "Length" parameter or entering a numeric value.
+6. **Set the 3D cursor** to the new location for the next wall segment, enabling snapping to ensure the segments butt together properly.
+7. **Add the next wall segment** by pressing :kbd:`Shift` + :kbd:`A` again.
+8. **Rotate** the new wall segment if needed by pressing :kbd:`Shift` + :kbd:`R` and adjusting the angle.
+9. **Adjust the length** of the new segment as required.
+10. **Repeat steps 6-9**, setting the 3D cursor to the desired location, adding new wall segments, rotating, and adjusting lengths, until the complete wall perimeter is created.
+11. **Modify wall segments** using the various shortcuts (e.g., extend, butt, mitre, merge, flip, split, rotate) as needed to refine the wall layout.
+12. **Align and adjust** walls using the alignment options.
+13. **Add voids** by clicking "Add Void" and placing openings where necessary.
+14. **Calculate quantities** by pressing :kbd:`Q` to ensure accurate measurements.
+
+The Create Wall tool in BlenderBIM enables precise and flexible wall creation and management,
+enhancing your ability to develop detailed floor plans efficiently.

src/blenderbim/docs/users/user_interface/toolbar/window.rst

@@ -0,0 +1,8 @@
+
+.. _create-window:
+
+Create Window
+-------------
+Shortcut: :kbd:`Shift` + :kbd:`Spacebar`, :kbd:`8`
+
+Similar to the door tool, this allows you to add windows to your walls. You can specify window types, sizes, and placement.