kicad/Documentation/guidelines/UIpolicies.txt

134 lines
6.1 KiB
Plaintext

** General UI Guidelines for KiCad Development
Capitalization:
For any visible text used within KiCad, follow recommendations here:
http://developer.gnome.org/hig-book/stable/design-text-labels.html.en
in the "Capitalization" section. This applies to all Menus, Titles,
Labels, Tooltips, Buttons, etc.
The capitalization for the application names is KiCad, Eeschema, CvPcb,
GerbView, and Pcbnew. All strings that have application names that are
visible to the user should be capitalized this way. It's also a good
idea use this capitalization in source code comments as well to prevent
confusion of new contributors.
Two styles of capitalization are used in GNOME user interface elements:
Header capitalization
Capitalize all words in the element, with the following exceptions:
Articles: a, an, the.
Conjunctions: and, but, for, not, so, yet ...
Prepositions of three or fewer letters: at, for, by, in, to ...
Sentence capitalization
Capitalize the first letter of the first word, and any other words
normally capitalized in sentences,such as application names.
The following table indicates the capitalization style to use for each
type of user interface element.
Table 8-3 Capitalization Style Guidelines for User Interface Elements
Element Style
Check box labels Sentence
Command button labels Header
Column heading labels Header
Desktop background object labels Header
Dialog messages Sentence
Drop-down combination box labels Sentence
Drop-down list box labels Sentence
Field labels Sentence
Filenames Sentence
Graphic equivalent text:
for example, Alt text on web pages Sentence
Group box or frame labels Header
Items in drop-down combination boxes,
drop-down list boxes, and list boxes Sentence
List box labels Sentence
Menu items Header
Menu items in applications Header
Menu titles in applications Header
Radio button labels Sentence
Slider labels Sentence
Spin box labels Sentence
Tabbed section titles Header
Text box labels Sentence
Titlebar labels Header
Toolbar button labels Header
Tooltips Sentence
Webpage titles and navigational elements Header
Dialogs:
Follow the recommendations here:
http://developer.gnome.org/hig-book/stable/design-window.html.en
paying particular attention to "initial focus", "sensible default values",
"default buttons", ESC key termination. Please note that the escape key
termination only works properly if there is a dialog button defined with
an ID of wxID_CANCEL or SetEscapeID( MY_ESCAPE_BUTTON_ID ) is called during
dialog initialization. The former is the preferred method for handling
escape key dialog termination. There is a checkbox in wxformbuilder for
the "default" control, and this is the one fired when the "enter" key
is pressed.
Use wxWidgets "sizers" in all dialogs, no matter how simple they are:
http://zetcode.com/tutorials/wxwidgetstutorial/layoutmanagement
and keep dialogs resizeable.
Configure the sizers so that as the dialog window is expanded, the most
sensible use of the increased dialog window occurs automatically by the
sizers. For example, in the DRC dialog of Pcbnew, sizers should be used to
expand the text control to use the full available free window area, so that
the user's view of the items in the text control is maximized as he/she
expands the dialog window, making it easier to read more DRC error messages.
In other dialogs without one component more important than the others, the
sizers might be configured to position the controls to sensible positions
near the perimeter of the increasingly larger dialog box, not necessarily
leaving them all bundled tightly together. The dialog box should look
nice at any size large enough to show all the components.
When using wxFormBuilder, please add the following settings to the
"Dialog" node:
subclass.name <- DIALOG_SHIM
subclass.header <- dialog_shim.h
This will provide for an override of the Show( bool ) wxWindow() function
and provide retentitive size and position for the session.
Use tooltips to explain the functionality of each non-obvious control.
This is important because the help files and the wiki often lag behind
the source code.
Avoid defining initial dialog sizes if possible. Let the sizers do their
job. After the dialog is fit to the sizers, set the minimum size to the
current size to prevent the dialog controls from being obscured when
resizing the dialog. If the labels or text of the dialog controls are,
set or changed at run time. Rerun wxWindow::Fit() to allow the dialog to
re-size and adjust for the new control widths. This can all be done after
the dialog is created but before it is shown or use class methods to
re-size the dialog as required. Reset the minimum size to the updated
dialog size.
Dialog windows shall not exceed 1024 x 768 when displayed in a 13 point font.
Note that the font used by end users is not something that you control from
within the dialog, but for testing purposes please do not exceed this dialog
size should the user have selected a font size of 13 points.
Quoting:
Filenames, paths or other text should be with single quotes ''. e.g.:
'filename.kicad_pcb'
'longpath/subdir'
'FOOTPRINTNAME'
'anything else'
Often text strings like this end up in panels which use HTML rendering, and this
can happen in the future. Previously used angle brackets only cause grief there.