diff --git a/stylebook/BomView-Body.jpg b/stylebook/BomView-Body.jpg new file mode 100644 index 0000000..5fbf19e Binary files /dev/null and b/stylebook/BomView-Body.jpg differ diff --git a/stylebook/ComboView-Feature-TimeBar.jpg b/stylebook/ComboView-Feature-TimeBar.jpg new file mode 100644 index 0000000..73e2a74 Binary files /dev/null and b/stylebook/ComboView-Feature-TimeBar.jpg differ diff --git a/stylebook/ComboView-Feature.jpg b/stylebook/ComboView-Feature.jpg new file mode 100644 index 0000000..11fd054 Binary files /dev/null and b/stylebook/ComboView-Feature.jpg differ diff --git a/stylebook/ComboView-Flat.jpg b/stylebook/ComboView-Flat.jpg new file mode 100644 index 0000000..034771e Binary files /dev/null and b/stylebook/ComboView-Flat.jpg differ diff --git a/stylebook/ComboView-History-of-an-Universe.md b/stylebook/ComboView-History-of-an-Universe.md new file mode 100644 index 0000000..f7c9a5c --- /dev/null +++ b/stylebook/ComboView-History-of-an-Universe.md @@ -0,0 +1,68 @@ +# ComboView - History of a Universe + +The ComboView is the most important Part beside the MDI-View. + +## History + +Working on a Model will end in a tree like structure thad define your Model. The slim ComboView itself is not able to show the tree. A slim way to show a tree and have a easy way to not miss the important references complete, is a History structure. If you work with a History you avoid to work with references on parts of a tree that not exist on a certain point. + +If you work with a clear history, you need a TimeLine as a kind of time machine. + +![TreeHistory](TreeHistory.png) + +## Naming + +Because of the closeness to historical aspects we use terms from this field. + +* Historic dependencies could be addressed by Parents and Children. + +* A collection of historic dependencies is called Era. + (We don't use Family because that term in some CAD has a different meaning) + +* Moving in the History is like using a time machine, for that we use a PresentAgeBar. + + +## Structure + +Structure View + +FlatView is a View that shows the Content in the Combo view in a pure historic view. This Historic view is identical with the order FreeCAD would calculate (if no multiprocess) +![FlatView](ComboView-Flat.jpg) + +The BOM-View shows the BOM structure. This is autogenerated by Dependencys of bodies. Her you could change the position and fill some properties. +![BodyView](BomView-Body.jpg) + +This is the FeatureView which has a focus on showing reference dependencys. + +Details se below. + +![FeatureView](ComboView-Feature.jpg) + + +![FeatureView-with-PresentAgeBar](ComboView-Feature-TimeBar.jpg) + +DocumentName + +* 📦 Model - Feature Name + The existence of this Model start with the first feature that creates it. + The Model entry contains two icons. The feature Icon and the general body Icon. + * Feature + * Sketch + * Externals and Dimensions + Such as Plane, and other geometry that used by the sketch. Also Dimensions with values. + + * SubModel + SubModels exist, if references for creating this new Model is based on another Model e.g. Sketch on a Surface of _Model - Pad 1_ and relation on other external edges. to create a new Body + + +If a body has references from another body, both Bodies are automatically merged in a MultiBody Object, this is because that way you could see at the first glance, that bodies depending on others, also it is not possible to create a mate between two bodies that already linked by sketch relations. + +## Possibilities + +* Era - (Directory) + An era defines a historical area that concerns a certain interdependent set of features. It is not possible to omit individual elements in between. Normally an Era define a specific part of a volume and all features that are needed to get it. + +* PresentAgeBar + Is a kind of Time machine that allows you to travel back in time and see how a file looks like in the past. It helps also to place references and sketch relations on geometry that are in the correct relation to the new feature. + If you modify an item the PresentAgeBar moves to the historic point where it is located and shows the shape of the body on that time. + **IMPORTANT**: It's not possible to create references and relations to geometry that exist in the Future. So References and relations could only been established to items created before the current PresentAreaBar. diff --git a/stylebook/ComboView_PartDesign.md b/stylebook/ComboView_PartDesign.md new file mode 100644 index 0000000..5065468 --- /dev/null +++ b/stylebook/ComboView_PartDesign.md @@ -0,0 +1,43 @@ +# Style Guide ComboView in PartDesign + +This document is still a work in progress. Please leave a comment in the chat or highlight some text and click on the tooltip to comment. This document is related to "Style Guide "ModernUI 23" FreeCAD" + +This document assumes the TNP problem is solved. + +The PartDesign Workbench uses a parametric, feature editing methodology, which means a basic solid is sequentially transformed by adding features on top until the final shape is obtained. + +This behavior requires a history-based approach to design. A feature may depend on one or more other features, resulting in a relationship tree. + +Even if the TNP problem is solved, it is recommended to design a flat hierarchy. + +This style guide is intended to help design the FreeCAD interface and create a simple user interface that is intuitive and easy to understand. + +1. ComboView --> DataAndHistoryPane (TreeView) +  --> See also the [MultiBodyPart vs. Assembly Problem](MultiBodyPart-VS-Assembly-problem.md) + + ![FeatureView](ComboView-Feature-TimeBar.jpg) + + ![Tree History](TreeHistory.png) + + 1. _Model_ History Tree + Contains the Body modifying History. Has a command that temporary replaces the 3D-Area with a Treeview that shows Relation between Features. + * Feature + * Sketch + * Plane (The DatumPlane, or a relation to a face) + + * Relations to other Feature, sketch or body They highlight the related objects on Mouse hover + + * PropertyPane (optional) + Allows to Split feature with a lot of settings into smaller parts, so specific settings are easier to find and modify. + + * ModelData + * Body BOM-Settings + Use as "part" or "construction", physical properties like Material and density, etc. + + * Body Properties (only if BOM-Settings are none or part) + + * Property and value table + (Label, Description, calculated weight, max dimension, etc.) + + 2. Reference List + List of data links from this document to external document. diff --git a/stylebook/FreeCAD-Window.jpg b/stylebook/FreeCAD-Window.jpg new file mode 100644 index 0000000..1e7f39b Binary files /dev/null and b/stylebook/FreeCAD-Window.jpg differ diff --git a/stylebook/MultiBodyPart-VS-Assembly-problem.md b/stylebook/MultiBodyPart-VS-Assembly-problem.md new file mode 100644 index 0000000..24a1160 --- /dev/null +++ b/stylebook/MultiBodyPart-VS-Assembly-problem.md @@ -0,0 +1,33 @@ +# What is the MultiBodyPart Vs. Assembly Problem? + +## What is an Assembly? + +An assembly is a bunch of independent objects that stick together. This Independent Objects normally are parts which either are developed to fit in several unrelated Assemblies or where third party objects. + +If you modify them you normally only use a kind of cut so it either fit into a certain place or get holes to place it or another part. + +## What is a MultiBodyPart (with external references)? + +This Problem increase in an environment with a solved TNP Problem. A MultiBodyPart is a Bunch of volumes that depending on each other by using external references. + +For example: You are creating a large machine that contains several parts, but you need to adjust the dimensions of the structure and the shell in which the parts are located to fit the contents or the planned environment. In this case, you prefer a solution where you only need to change some key values, such as length, width and height, to modify the U-beam structure and the sheet metal shell of the machine. + +## Where is the Problem? + +The Problem appear if you try to mix both. As clear the difference use-case seems. It is difficult to separate this two in real life. Especially If you are in an early stage of a new product. + +It could happen, that you create a MultiBodyPart but after that try to move a body with assembly mates to a new location. + +## Solution? + +### Use application limitation + +So you have to set up, or you get automatically a "MultiBodyPart" Object. The moment you use External references or use feature that split or merge Bodies. Bodies inside this object could not be moved independent to other Bodies of the same object except you opt-in a setting per object. + +Allow to use Assembly-Mates only in context of bodies that origin from the same feature. e.g. you split a body into two bodies, but now you need a little distant between them. In that case you could mate both bodies to have a specific distant. +Assembly mates is a feature that relocate several Bodies according to several mates. This is similar to the sketch relation inside a sketch. + +### Have trained and informed User + +User which know what they do could create really cool and easy to maintaining machines. (Sadly we could not assume that.) +With the freedom to mix assembly and MultiBody you could save a lot of time. And easy modify along planned parameters. This need a good overview about the current case. A feature-tree that shows relations in an understandable way. A help to create, removing and repairing such references as easy as possible is important. diff --git a/stylebook/PopupMenu.png b/stylebook/PopupMenu.png new file mode 100644 index 0000000..bcd3d22 Binary files /dev/null and b/stylebook/PopupMenu.png differ diff --git a/stylebook/Rules-for-Feature.md b/stylebook/Rules-for-Feature.md new file mode 100644 index 0000000..10a965b --- /dev/null +++ b/stylebook/Rules-for-Feature.md @@ -0,0 +1,41 @@ +# Rules for Feature + +Every Feature has to define what type of Input is allowed. Assume that you preselect things and after that run a feature. This feature could take the preselected content that matches a type it understands. In best cases no other selection is needed. It's not up to the Feature Designer to decide if such kind of working is possible or not. + +A good example could be a tooltip that shows possible relations that work with your selections. e.g.: [https://forum.freecad.org/viewtopic.php?p=582953#p582953](https://forum.freecad.org/viewtopic.php?p=582953#p582953) + +![PopupMenu](PopupMenu.png) + + + +If you successfully finish a new Feature the Feature is saved into the ComboView: + +* It's saved onto the place where the PresentAgeBar is located. +* This Feature contains the Script and all parameter to fulfill its purpose and allow recalculation. + +* Information has to be stored inside the Feature: + It helps to Update Feature and solve errors. + * Needed dependency like Workbenches and others. + + * Version of FreeCAD, Workbenches and this feature itself. + + * Date where this feature was created and modified + +* Modifying a feature brings back the same Task Dialog that it was used to create the Feature. + +* It has to work even a Workbench is not active which created a feature. That not means that all settings have to be available but at least: + * it has to be possible to modify and change dimensions + + * It has to be possible to repair references + + * Settings that need a loaded Workbench, shows a Menu entry to load the Workbench and after that made the settings visible for modifying (in background without left this task) + +* While modifying a Feature, it has to allow: + * Measure  + * Create temporary visual Cut to find hidden things. + * Every Feature that could increase volumes could also reduce (cut) volume and between this by a single click. + Setting could be preset and hidden, if in most use case not needed + (e.g. in Arch the wall feature) + + * Every Feature that add/remove volume could also split a body into several and also merge several bodies into one. + Setting could be preset and hidden if in most and usual use cases not needed diff --git a/stylebook/TreeHistory.png b/stylebook/TreeHistory.png new file mode 100644 index 0000000..9ed43af Binary files /dev/null and b/stylebook/TreeHistory.png differ diff --git a/stylebook/index.md b/stylebook/index.md index 72da86a..df2d844 100644 --- a/stylebook/index.md +++ b/stylebook/index.md @@ -15,152 +15,230 @@ In the long term, the book should settle down and become primarily a resource fo Note: The stylebook is a catalog of _guidelines_. These are not hard laws to be followed. The overarching principle is to make the user interface intuitive and welcoming. If blindly following a guideline does not serve that purpose, then ignoring the guideline is acceptable. However, the _right answer_ is to refine the guideline here to account for what has been learned. ## Subpages -[Glossary](./glossary.md) [Navigation](./navigation.md) [Selection](./selection.md) [Toolbars](toolbars.md) +[Glossary](./glossary.md) [Comboview](ComboView-History-of-an-Universe.md) [MultiBodyPart VS. Assembly Problem](MultiBodyPart-VS-Assembly-problem.md) [Navigation](./navigation.md) [Selection](./selection.md) [Toolbars](toolbars.md) [Task Panel](./taskpanel.md) -## Parts of the UI - -![The FreeCAD UI and its elements](ui.png) - -1. Workbench Switcher -2. Toolbars -3. Toolbar Area -4. ComboView -5. TreeView -6. Property Pane -7. The MDI View -8. The MDI Selector -9. The Report View -10. The Python Console -11. Status Bar -12. Navigation Cube - -### Workbench Switcher - -The workbench switcher is an important control to the general FreeCAD workflow. It is the primary way for the user to switch workbench contexts. - -#### Guidelines - -1. The workbench switcher should always be available to the user. It shouldn’t jump around. - -#### Problems - -1. The switcher itself has no accelerator key associated with it. The user must click with a mouse. -2. The first ten workbenches are automatically assigned an accelerator of W <#>. The user has no control over the assignment of accelerators. -3. By default, all workbenches installed in FreeCAD are shown. This includes workbenches that are of marginal value or seldom used, especially by new users. This contributes to confusion since users don’t know yet which workbenches they need to use. - -### ComboView - -The combo view contains the tree view and the task panel area. - -![UI of the LinkStage fork of FreeCAD showing a vision for the ComboView](comboview.png) - -#### Guidelines - -tbd - -#### Problems - -tbd - -### TreeView - -#### Guidelines - -tbd - -#### Problems - -tbd - -### Property Pane - -The property pane shows properties of the selected object. Properties are sorted in groups. Right clicking gives an `Autoexpand` option and a `Show All` option. The developer has discretion about which properties are automatically shown. In practice almost all options are available because the developer probably hasn’t thought about it. Many of these could probably be hidden by default to make the list shorter and less cluttered. - -#### Guidelines - -tbd - -#### Problems - -tbd - -### MDI View - -The MDI view has the most usable space. This is almost always the 3D model except for spreadsheets and the TechDraw workbench. It could be used for other tasks when the user’s focus is needed for a long time or to give a maximum view of something (raytraced image). - -#### Guidelines - -tbd - -#### Problems - -tbd - -### MDI Selector - -#### Guidelines - -tbd - -#### Problems - -tbd - -### Report View - -#### Guidelines - -tbd - -#### Problems - -tbd - -### Python Console - -#### Guidelines - -tbd - -#### Problems - -tbd - -### Status Bar - -The status bar is the only part of the UI that is always the same regardless of workbench, task or mode. That makes it special. - -#### Guidelines - -1. The real estate is very limited so it should be protected and used very sparingly and wisely. For example the mouse model switcher probably doesn’t need a label. An icon with a tooltip is sufficient and would use only 1/4 of the space it currently occupies. - -#### Problems - -tbd - -### Task View - -Each tool should put all of it’s settings in a single task box. - -Task panels should never require scrolling. - -Double clicking on an item in the tree view will show a task panel if one is available. If there was a task panel used to create an object, double clicking should show THE SAME task panel to edit the object. _(I’m looking at YOU, Draft workbench! You too, Arch)_ - -Task panels should always produce a valid output if the `OK` button is pressed. If a valid output isn’t possible, don’t enable the ‘ok’ button. -> _This is interesting but I wonder how it could be done._ - -Task panels should always start with valid defaults (e.g. the shapestring dialog should have a default font. It should preview the text in the 3D window. - -Task panels should always preview their results in the 3d window. If a preview is computationally too intense, provide an `Apply` button to generate a preview. _(I’m looking at YOU, shapestring tool!)_ - -## Context Menus - -tbd - -### Guidelines - -tbd +# Style Guide "ModernUI 23" FreeCAD + +This document is still a work in progress. Please leave a comment in the chat or highlight some text and click on the tooltip to comment. +For reference: [https://freecad.github.io/DevelopersHandbook/stylebook/](https://freecad.github.io/DevelopersHandbook/stylebook/) + +This document assumes the TNP problem is solved. + +General Rule: + +* In the Head New things are started. +* In the Left Pane old things could be found and modified. +* In the Right Pane access to external Resources is granted. +* In the MDI-View the current Main Activity is happend +* In the BottomPane Advanced user could see what happened in detail and modify on an advanced level + + +![FreeCAD Window](FreeCAD-Window.jpg) + +## User Journeys + +* [Importing 3D-Data](https://cryptpad.ccc-ch.ch/pad/#/2/pad/view/4zbaN2Oo1kq2Gy5y03VWOYCQykXtj3PBdknVQyGUZ18/) + + +## Parts of the UI + +1. _MDI-View (MDI =_ **Multiple Document Interface)**The _MDI-View_ lies between all frames. If no _Feature_ and no document is active, the _StartArea_ is shown, if no _Feature_ is active, but a document is loaded, the _3DArea_ is shown + * _3DArea_ + * Contains the 3D-Model + + * Navigation Cube + Helps user to orienting relative to the document origin + + * In any case, the center for fit body is located in the middle between the current maximal width of all surrounding Panes and Bars + + * _SettingsArea_ + * Standards + Units and other behaviors that affect appearances on data exports. + + * Settings + App and Workbench settings that do not have effect on data exports. + * Global Properties for BOM + + * Add-ons + + * Import + + * Export + Allows saving settings. Per file type + * e.g. [https://forum.freecad.org/download/file.php?id=187214](https://forum.freecad.org/download/file.php?id=187214) + + * _StartArea_ + * Contains the FreeCAD Start Screen + +2. _ToolbarArea_ + * _WorkbenchSwitcher_ + Tabs that allows switching to other _WorkbenchToolbar_ + + * Feature Area + Contains Icons for _Features_. + + * HeadupToolbar + Contains Features that modify how MDI-View present the Content. Icons there should be Workbench independant. Workbenches could add Icons but do not replace them. + * Icons should help see things either in an other way or select/mark data + + * It's not allowd to modify feature and content permanently + + * Has no influence on other data output than such made directly from the current MDI-View apperance. + + * _Feature_ + * A macro that could be run by clicking on an Icon. The Result is an additional entry in the _DataAndHistoryPane_ or a clickable object on the _3DArea_ (e.g. Sketch constrains) that allows modifying or removing the result of this macro. + + * Every Feature has a Description on wiki.freecad.org/{WorkbenchName\_FeatureName/LangCode} at least in English + + * Every Feature with a Property dialog to set up details of the command has a help page on wiki.freecad.org/{WorkbenchName\_FeatureName/LangCode} at least in English + +3. _FreeCADMenu_ + 1. Open, Save, Save as + + 2. Export + Contains the Dialog from _SettingsArea/Export_ + + 3. Settings --> _SettingsArea_ + + 4. Collect and transfer all FreeCAD data + +4. LeftPane: + 1. ComboView, Task, PropertyPane + [Details of ComboView](ComboView-History-of-an-Universe.md) + [ComboView in Context of PartDesign]() +  --> See also the [MultiBodyPart vs. Assembly Problem](MultiBodyPart-VS-Assembly-problem.md) +   + TreeView, (DataAndHistoryPane): Every tree Item could have an "Edit" button that allows to modify specific settings for SubItems, a "Zoom" button to highlight and fit the zoom to contained data (if could be seen in 3D-Area) + 1. Components + Linked Documents + + 2. _Model_ History + Contains the Model History + * A switch (beside the Title) to deactivate the absorbing of related feature and shows a pure history + + * Linked Data + * Origin (usually in sync with the document Origin) + + * TimeBar + A Line that allows to set on which point of the History a new feature has to be inserted. + + 3. ObjectList + Contain Objects and also their data. + * ObjectProperties + * BOM (Document Properties and Data e.g. for BOM-Tables) + * Bodies + + * Bodygroup (AKA. SubAssembly) + + * Mates between Models or Linked documents + + 4. Reference List + List of data links from this document to external document + + 2. _TaskPane_ (_Settings)_ + * Contain the settings of the currently active Feature + + * Contain the settings of currently selected data (Independent to active feature) + +5. _RightPane: RessourcePane_ + Access to external Resource from outside the FreeCAD Application + * Libraries + + * Webservices + +6. _StatusBar_ + * Contains nice to know data for current selections and the document itself + e.g. Length of selected data or current Volume or Weight of all bodies + +7. _PopupMenu_ + 1. _Leftclick_ + * Shows context data to currently selected data + and shows most used features for current selections + + 2. _Rightclick_ + * Shows context data to currently selected data + and shows less used features for current selections + + 3. _Middleclick_ + + 4. _CustomXclick_ + + + + +## Rules for _Features_ + +[Rules for Features](Rules-for-Feature.md) + + +## Rules for _PopupMenu_ + +### Basics + +Example: [https://forum.freecad.org/viewtopic.php?p=582953#p582953](https://forum.freecad.org/viewtopic.php?p=582953#p582953) +![Tooltip Menu](PopupMenu.png) + +* Design Possibilities: + * Placed on Mouse position: + On selecting one or more things a _PopupMenu_ appear in the up-right position of the mouse. If you increase the distant to the Popup, the popup more and more get transparent. On a certain distant the _PopupMenu_ disappear. + + * Placed as hovering Menubar + Like some Video Games use. + + +### Content + +The Content of the _PopupMenu_ depend on the current working area. e.g. Sketcher, PartDesign, Assembly, TechDraw, etc. + +The _PopupMenu_ shows _Features_ that could work with selected content. + +* The first row shows selected elements + +* The second Row shows _Feature_ that could work with the current selections. Icons should be on predictable places. + +* If more than one selection are available the features from left to right are sorted according to this rule: + 1. By the amount of selections a _Feature_ could use + + 2. By the amount a _Feature_ is used. + +* In the Example (_PopupMenu_ in Sketcher) there is no _Feature_ that could work with all three selections, so the first Icon is perpendicular. This _Feature_ could work with two selections and is the most used _Feature_ on the list. + +* Feature that could appear on _PopupMenu_ should not depend on a certain selection order. Selection Order is only allowed if the Feature UI allows to easily swap them + * It is not allowed to display a feature in the popup menu if there is a wrong selection order and this can lead to the user having to select the same selection again to complete the feature. + + +⇒ This way, in the best case it could be possible that the _ToolbarArea_ is not needed and simple models can be created completely via CTRL-Key, mouse clicks and the resulting _PopupMenu_. + +## Don't Do it + +Popup Dialogs + +Popup Dialogs are easy to use but not user-friendly. PLEASE avoid them. + +* If questions should be answered use the ComboView + +* Dialogs that show only an OK button normally do not get read by the user. + +* Dialogs that show an Abort and OK are not able to show what really would happen, also given settings normally get lost. + * Proceed further + + * Allow cancel long going Calculation + + * Show the Problem in the _ComboView_ + + * Allow saving logs of the Problem + + * Create a more user-friendly output of the log. If possible link to a help page for that case. + +* "I need space for a complex setup!" + Choose from these possibilities: + * Temporary increase the width of the _SettingsTaskPane_ + + * Replace the _3DArea_ with a settings page. + e.g. Mockup: [https://forum.freecad.org/download/file.php?id=187214](https://forum.freecad.org/download/file.php?id=187214) + If you need the 3D-Model to select something, I recommend including it as a Frame into the settings page. ## Widgets