Skip to content

Commit ead315f

Browse files
chenneschennes
authored
Merge pull request #26 from dirkolbrich/stylebook
Styleguide: fix image links, minor changes
2 parents 49f1f8f + 63aafda commit ead315f

File tree

1 file changed

+92
-93
lines changed

1 file changed

+92
-93
lines changed

‎stylebook/index.md

Lines changed: 92 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -9,43 +9,42 @@ layout: default
99

1010
{{page.description}}
1111

12-
This book is meant to document the general style and conventions of the FreeCAD User Interface. Guidelines, terminology, and philosophies described here will be used to justify changes in the current UI in order to make the overall user experience more consistent, predictable, intuitive, and attractive in the future.
12+
This book is meant to document the general style and conventions of the FreeCAD User Interface. Guidelines, terminology, and philosophies described here will be used to justify changes in the current UI in order to make the overall user experience more consistent, predictable, intuitive, and attractive in the future.
1313

14-
In the short term, this book will undergo massive change and reorganization. It will also serve as an important part of a larger discussion. Feel free to link to existing issues and pull requests, and projects.
15-
16-
In the long term, the book should settle down and become primarily a resource for developers and designers to refer to. Most links should be removed.
14+
In the short term, this book surely will undergo massive changes and reorganization. It will also serve as an important part of a larger discussion within the FreeCAD community. Feel free to link to existing issues and pull requests, and projects.
1715

16+
In the long term, the book should settle down and become primarily a resource for developers and designers to refer to. Most links should be removed.
1817

1918
## Parts of the UI
2019

21-
![Parts of the UI]()
20+
![The FreeCAD UI and its elements](ui.png)
2221

23-
1. Workbench switcher
22+
1. Workbench Switcher
2423
2. Toolbars
25-
3. Toolbar area
26-
4. Comboview
27-
5. Tree
24+
3. Toolbar Area
25+
4. ComboView
26+
5. TreeView
2827
6. Property Pane
29-
7. The MDI view
28+
7. The MDI View
3029
8. The MDI Selector
31-
9. The Report view
32-
10. The python console
33-
11. Status Bare
34-
12. Nav Cube
30+
9. The Report View
31+
10. The Python Console
32+
11. Status Bar
33+
12. Navigation Cube
3534

3635
### Workbench Switcher
3736

38-
The workbench switcher is an important control to general FreeCAD workflow. It is the primary way for the user to switch workbench contexts.
37+
The workbench switcher is an important control to the general FreeCAD workflow. It is the primary way for the user to switch workbench contexts.
3938

4039
#### Guidelines
4140

42-
1. The workbench switcher should always be available to the user. It shouldn’t jump around.
41+
1. The workbench switcher should always be available to the user. It shouldn’t jump around.
4342

4443
#### Problems
4544

46-
1. The switcher itself has no accelerator key associated with it. The user must click with a mouse.
47-
2. The first ten workbenches are automatically assigned an accelerator of W <#>. The user has no control over the assignment of accelerators
48-
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.
45+
1. The switcher itself has no accelerator key associated with it. The user must click with a mouse.
46+
2. The first ten workbenches are automatically assigned an accelerator of W <#>. The user has no control over the assignment of accelerators.
47+
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.
4948

5049
### Toolbars
5150

@@ -63,21 +62,21 @@ The workbench switcher is an important control to general FreeCAD workflow. It
6362
#### Guidelines
6463

6564
1. Toolbars provide convenient access to frequently used commands. They do this at the expense of permanently occupying screen real space.
66-
2. Too many toolbars creates visual clutter. All tools compete for the users attention simultaneously. They are not context aware.
67-
3. Toolbars group related commands
68-
4. Anticipate the user disable the toolbar.
69-
5. Group locally similar tools into a toolgroup
70-
6. All tools in a toolbar should have a translatable and useful tooltip
71-
7. The toolbar should have a translatable and userful tooltip
72-
8. A toolbar should contain a minimum number of tools, ideally less than seven. Longer toolbars provide fewer options for customization and often get shortened or clipped offscreen. They also increase cognitive burden since the user has to process the group as a whole.
65+
2. Too many toolbars create visual clutter. All tools compete for the users attention simultaneously. They are not context aware.
66+
3. Toolbars group related commands.
67+
4. Anticipate the user might disable the toolbar.
68+
5. Group locally similar tools into a toolgroup.
69+
6. All tools in a toolbar should have a translatable and useful tooltip.
70+
7. The toolbar itself should have a translatable and useful tooltip.
71+
8. A toolbar should contain a minimum number of tools, ideally less than seven. Longer toolbars provide fewer options for customization and often get shortened or clipped offscreen. They also increase cognitive burden since the user has to process the group as a whole.
7372

7473
#### Problems
7574

76-
1. Toolbars are the developers go-to UI element. They are simple to code and useful during development. Asa result they are often overused and visually cluttered.
75+
1. Toolbars are the developers go-to UI element. They are simple to code and useful during development. As a result they are often overused and visually cluttered.
7776

7877
### Toolbar Area
7978

80-
The toolbar area contains toolbars. Some of the toolbars are available everywhere and some are workbench specific.
79+
The toolbar area contains toolbars. Some of the toolbars are available everywhere and some are workbench specific.
8180

8281
#### Guidelines
8382

@@ -86,196 +85,196 @@ The toolbar area contains toolbars. Some of the toolbars are available everywhe
8685

8786
#### Problems
8887

89-
1. Toolbars can be rearranged on a per-workbench basis and the arrangement is meant to persist between sessions. This is intended to be a feature but often acts like a bug. The user arranges workbenchs (including those that appear on multiple workbenches) while in one bench. Then switches to anothe bench and the toolbars move to different locations.
88+
1. Toolbars can be rearranged on a per-workbench basis and the arrangement is meant to persist between sessions. This is intended to be a feature but often acts like a bug. The user arranges toolbars to his liking (including those toolbars that appear on multiple workbenches) while in one workbench. After a switch to another workbench it can happen that the toolbars rearrange in a different order.
9089

9190
### ComboView
9291

93-
![A vision for the comboview](./comboview.png)
92+
The combo view contains the tree view and the task panel area.
93+
94+
![UI of the LinkStage fork of FreeCAD showing a vision for the ComboView](comboview.png)
9495

9596
#### Guidelines
9697

97-
1. Item
98+
tbd
9899

99100
#### Problems
100101

101-
1. Item
102+
tbd
102103

103-
### Tree
104+
### TreeView
104105

105106
#### Guidelines
106107

107-
1. Item
108+
tbd
108109

109110
#### Problems
110111

111-
1. Item
112+
tbd
112113

113114
### Property Pane
114115

115-
The property pane shows properties of the selected object. Properties are in groups. Right clicking give 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.
116+
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.
116117

117118
#### Guidelines
118119

119-
1. Item
120+
tbd
120121

121122
#### Problems
122123

123-
1. Item
124+
tbd
124125

125126
### MDI View
126127

127-
The MDI view has the most usable space. This is almost always the 3D model except for spreadsheet and TechDraw. 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)
128+
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).
128129

129130
#### Guidelines
130131

131-
1. Item
132+
tbd
132133

133134
#### Problems
134135

135-
1. Item
136+
tbd
136137

137138
### MDI Selector
138139

139140
#### Guidelines
140141

141-
1. Item
142+
tbd
142143

143144
#### Problems
144145

145-
1. Item
146+
tbd
146147

147148
### Report View
148149

149150
#### Guidelines
150151

151-
1. Item
152+
tbd
152153

153154
#### Problems
154155

155-
1. Item
156+
tbd
156157

157158
### Python Console
158159

159160
#### Guidelines
160161

161-
1. Item
162+
tbd
162163

163164
#### Problems
164165

165-
1. Item
166+
tbd
166167

167168
### Status Bar
168169

169-
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.
170+
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.
170171

171172
#### Guidelines
172173

173-
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 and tooltip is sufficient and would use only 1/4 of the space it currently occupies.
174+
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.
174175

175176
#### Problems
176177

177-
1. Item
178-
178+
tbd
179179

180-
### Nav Cube
180+
### Navigation Cube
181181

182182
General
183183

184184
#### Guidelines
185185

186-
1. Item
186+
tbd
187187

188188
#### Problems
189189

190-
1. Item
191-
192-
The combo view contains the tree and the task panel area
193-
194-
Goal for combo view :
190+
tbd
195191

196-
![alt_text](images/image1.png "image_tooltip")
197-
198-
199-
### Task view
192+
### Task View
200193

201194
Each tool should put all of it’s settings in a single task box.
202195

203196
Task panels should never require scrolling.
204197

205-
Double clicking on an item in the tree 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)
198+
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)_
206199

207-
Task panels should always produce a valid output if ‘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.
200+
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._
208201

209-
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.
210-
211-
Task panels should always preview their results in the 3d window. If preview is too computationally intense, provide an ‘apply’ button to generate a preview. (I’m looking at YOU, shapestring tool!)
202+
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.
212203

204+
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!)_
213205

214206
### Selection
215207

216-
[Reference: https://wiki.freecad.org/Selection_methods](https://wiki.freecad.org/Selection_methods)
217-
208+
Reference: [FreeCAD Wiki - Selection Methods](https://wiki.freecad.org/selection_methods)
218209

219-
![The Selectionview](./selection.png)
210+
![The Selection View](selection.png)
220211

221212
#### Terms
222213

223-
1. Selection: the set of objects and subojects that the user has selected.
214+
1. Selection: the set of objects and subobjects that the user has selected
224215
2. Pre-selection: the object directly under the pointer which will be added to the selection if the user clicks
225-
3. Selection View. The panel which allows the user to see the selection items
226-
4. Greedy selection. Mode in which additional items are added to the selection without requiring a modifier key
227-
5. Selection gate Logic which can be initiated via code that controls which objects may be selected.
228-
6. Selection observer Logic which can be initiated via code that watches the selection. It can be used to trigger action under specific selection conditions.
216+
3. Selection View: The panel which allows the user to see the selection items
217+
4. Greedy selection: Mode in which additional items are added to the selection without requiring a modifier key
218+
5. Selection gate: Logic which can be initiated via code that controls which objects may be selected
219+
6. Selection observer: Logic which can be initiated via code that watches the selection. It can be used to trigger actions under specific selection conditions.
229220

230221
#### Guidelines
231222

232-
1. Selection gates and observers are powerful tools for adjusting the affordances of the GUI and providing signals. They must be used with care because they can adversely affect the performance of the GUI.
223+
1. Selection gates and observers are powerful tools for adjusting the affordances of the GUI and providing signals. They must be used with care because they can adversely affect the performance of the GUI.
233224
2. If the user is asked to select multiple features, he should be able to select by clicking them, and unselect them as well by clicking on selected features.
234225

235-
236226
## Context Menus
237227

238-
some text
228+
tbd
239229

240230
### Guidelines
241231

232+
tbd
242233

243234
## Navigation
244235

245236
### Elements
246237

247-
1. Nav Cube
238+
1. Navigation Cube
248239
2. Standard Views
249-
3. Keyboard accelerators
240+
3. Keyboard Accelerators
241+
242+
#### Navigation Cube
243+
244+
tbd
245+
246+
#### Standard Views
247+
248+
tbd
250249

251-
#### Nav cube
250+
#### Keyboard Accelerators
251+
252+
tbd
252253

253-
#### Standard views
254254
## Widgets
255255

256256
#### Guidelines
257257

258-
1. FreeCAD has a custom QT widget for displaying units. The control will convert the displayed units based on the users selected unit schema.
259-
258+
1. FreeCAD has a custom QT widget for displaying units. The control will convert the displayed units based on the users selected unit schema.
260259

261260
## Tables
262261

263-
When a table is used to display rows of items with multiple elements, such as the workbench preference page, the first column should be the icon/name of the element. This first column can be preceded by a checkbox only if it is an activation checkbox. The rest of UI elements should be put after, in an order that makes the most sense.
262+
When a table is used to display rows of items with multiple elements, such as the workbench preference page, the first column should be the icon/name of the element. This first column can be preceded by a checkbox only if it is an activation checkbox. The rest of the UI elements should follow after, in an order that makes the most sense to the user.
264263

265264
## Terminology
266265

267-
FreeCAD has a major terminology problem for new users. We have a Part workbench that doesn't make Parts and a Part Design workbench that isn't used to design Parts. We have Pads and Extrudes, Pockets and Cuts, Fuses and Unions, etc. We have a Part container and a Group container(?) but no core functions to populate a container (ex a core assembly function).
266+
FreeCAD has a major terminology problem for new users. We have a Part workbench that doesn't make Parts and a Part Design workbench that isn't used to design Parts. We have Pads and Extrudes, Pockets and Cuts, Fuses and Unions, etc. We have a Part container and a Group container(?) but no core functions to populate a container (e.g. a core assembly function).
268267

269268
## Philosophy
270-
There should be one-- and preferably only one --obvious way to do it. Developers are notorious for giving users options thinking that is a good thing. In reality, every tool takes time to understand. Given two nearly identical implementatoins of hte same thing, the user has to figure out how they differ. Don’t make the user think.
271269

270+
There should be one -- and preferably ONLY one -- obvious way to do a task. Developers are notorious for giving users options thinking that is a good thing. In reality, every tool takes time to understand. Given two nearly identical implementations of the same workflow, the user has to figure out how they differ. Don’t make the user think.
272271

273272
## Resources
274-
Decent book. It’s mostly about web usability but the core ideas are sound.
275-
[https://www.amazon.com/Dont-Make-Me-Think-Usability/dp/0321344758](https://www.amazon.com/Dont-Make-Me-Think-Usability/dp/0321344758)
276273

277-
This looks interesting
278-
[https://www.amazon.com/Laws-UX-Psychology-Products-Services-ebook/dp/B087F24RJB/ref=sr_1_12?keywords=user+interface+design&qid=1679441490&s=books&sprefix=user+interface%2Cstripbooks%2C121&sr=1-12](https://www.amazon.com/Laws-UX-Psychology-Products-Services-ebook/dp/B087F24RJB/ref=sr_1_12?keywords=user+interface+design&qid=1679441490&s=books&sprefix=user+interface%2Cstripbooks%2C121&sr=1-12)
274+
Here are some resources concerning UI/UX design.
275+
276+
[Don't Make Me Think: A Common Sense Approach to Web Usability](https://www.amazon.com/Dont-Make-Me-Think-Usability/dp/0321344758) by Steve Krug - A decent book mostly about web usability but the core ideas are sound.
277+
278+
[Laws of UX: Using Psychology to Design Better Products & Services](https://www.amazon.com/Laws-UX-Psychology-Products-Services-ebook/dp/B087F24RJB) by Jon Yablonski
279279

280-
Classic - great introduction to design concepts like affordances and signals
281-
[https://www.amazon.com/Design-Everyday-Things-Revised-Expanded-ebook/dp/B00E257T6C/ref=sr_1_17?keywords=user+interface+design&qid=1679441706&s=books&sprefix=user+interface%2Cstripbooks%2C121&sr=1-17](https://www.amazon.com/Design-Everyday-Things-Revised-Expanded-ebook/dp/B00E257T6C/ref=sr_1_17?keywords=user+interface+design&qid=1679441706&s=books&sprefix=user+interface%2Cstripbooks%2C121&sr=1-17)
280+
[The Design of Everyday Things](https://www.amazon.com/Design-Everyday-Things-Revised-Expanded-ebook/dp/B00E257T6C) by Donald A. Norman - A great introduction to design concepts like affordances and signals.

0 commit comments

Comments
 (0)