178 lines
8.5 KiB
Markdown
178 lines
8.5 KiB
Markdown
# User Interface Guidelines #
|
|
|
|
This document defines the guidelines for user interface development in
|
|
KiCad. Developers are expected to following these guidelines as closely
|
|
as possible when contributing user interface code to the KiCad project.
|
|
|
|
[TOC]
|
|
|
|
# Text Capitalization # {#capitalization}
|
|
For all visible text used within KiCad, follow recommendations in the
|
|
capitalization section in the [writing style section of the GNOME User
|
|
Interface Guidelines][gnome-ui-style]. 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.
|
|
|
|
## Capitalization Styles ## {#cap-styles}
|
|
There are two styles of capitalization are used in GNOME user interface
|
|
elements: header capitalization and sentence capitalization. This
|
|
section defines the capitalization style and when each type of capitalization
|
|
should be used.
|
|
|
|
### Header Capitalization ### {#cap-header}
|
|
|
|
When using header capitalization all words are capitalized 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 ### {#cap-sentence}
|
|
When capitalizing sentences, capitalize the first letter of the first word,
|
|
and any other words normally capitalized in sentences such as proper nouns.
|
|
|
|
## Capitalization Table ## {#cap-table}
|
|
The following table indicates the capitalization style to use for each type
|
|
of user interface element.
|
|
|
|
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
|
|
Text on web pages | Sentence
|
|
Group box and window frame labels | Header
|
|
Items in drop-down and list controls | 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 # {#dialogs}
|
|
|
|
This section defines how dialog boxes should be designed. The KiCad project
|
|
uses the [GNOME User Interface Guidelines][gnome-ui-guidelines] for laying out
|
|
dialogs. KiCad's dialogs must be designed with [wxFormBuilder][wxformbuilder].
|
|
As wxFormBuilder available in packages is likely to be a different version than
|
|
what other developers have installed, it has been decided to use the version
|
|
kept in a Github repository, branch [wxFB3.5RC-1][wxformbuilder-github] to avoid
|
|
version mismatch. When designing dialogs, follow the [visual layout section of
|
|
the GNOME User Interface Guidelines][gnome-ui-layout].
|
|
|
|
## Escape Key Termination ## {#dialogs-esc-key}
|
|
Please note that the escape key termination only works properly if there is a
|
|
dialog button defined with an ID of wxID_CANCEL or setting the escape button
|
|
ID using [wxDialog::SetEscapeID( MY_ESCAPE_BUTTON_ID )][wxdialog-setescapeid]
|
|
is called during dialog initialization. The former is the preferred method for
|
|
handling escape key dialog termination. There is a checkbox in wxFormBuilder
|
|
for setting the "default" control, and this is the one fired when the "enter"
|
|
key is pressed.
|
|
|
|
## Dialog Layout with Sizers ## {#dialogs-sizers}
|
|
Use wxWidgets "sizers" in all dialogs, no matter how simple they are. Using
|
|
absolute sizing in dialogs is forbidden in KiCad. See the [wxWidgets sizer
|
|
overview][wxwidgets-sizers] for more information on using sizers. 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 user interface elements.
|
|
|
|
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 should 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. If your dialog
|
|
exceeds this limit, please redesign the dialog using tabs or some other
|
|
paging method to reduce the size of the dialog.
|
|
|
|
## Dialog Base Class ## {#dialog-base}
|
|
The KiCad project has a base class which most if not all dialogs should be
|
|
derived from. When using wxFormBuilder, please add the following settings
|
|
to the "Dialog" tab:
|
|
|
|
* subclass.name <- DIALOG_SHIM
|
|
* subclass.header <- dialog_shim.h
|
|
|
|
This will provide for an override of the Show( bool ) wxWindow() function
|
|
and provide retentive size and position for the session. For more information,
|
|
see the [DIALOG_SHIM class source code][kicad-src-dialog-shim].
|
|
|
|
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.
|
|
|
|
## Transferring Data To and From Controls ## {#dialogs-xfer}
|
|
|
|
Dialog data must be transferred to the dialog controls on dialog initialization
|
|
and transferred from controls when the dialog is dismissed by the default
|
|
affirmative action (typically clicking the wxID_OK button) or the clicking the
|
|
wxID_APPLY button. The wxWidgets dialog framework has support for this by
|
|
using validators. Please read the [wxValidator Overview][wxwidgets-validator]
|
|
in the [wxWidgets documentation][wxwidgets-doc]. In the past, data transfer
|
|
was handled in various default button handlers virtually all of which were
|
|
broken. Do not implement default button handlers in your dialog code. Use
|
|
validators to transfer data to and from controls and allow the default dialog
|
|
button handlers work the way they were designed.
|
|
|
|
## Internationalization ## {#dialog-i18n}
|
|
|
|
To generate a list of strings occurring in a dialog, one needs to enable
|
|
'internationalize' checkbox in the project properties. Otherwise, it will not
|
|
be possible to translate the dialog.
|
|
|
|
# String Quoting # {#quoting}
|
|
Often text strings will be quoted for display which use may used in controls
|
|
that render HTML. Using angle brackets will cause grief for HTML rendering
|
|
controls so text should be quoted with single quotes ''. e.g.:
|
|
|
|
* 'filename.kicad_pcb'
|
|
* 'longpath/subdir'
|
|
* 'FOOTPRINTNAME'
|
|
* 'anything else'
|
|
|
|
[gnome-ui-guidelines]:https://developer.gnome.org/hig/stable/
|
|
[gnome-ui-layout]:https://developer.gnome.org/hig/stable/visual-layout.html.en
|
|
[gnome-ui-style]:https://developer.gnome.org/hig/stable/writing-style.html.en
|
|
[wxformbuilder]:https://sourceforge.net/projects/wxformbuilder/
|
|
[wxformbuilder-github]:https://github.com/marekr/wxFormBuilder/tree/wxFB3.5-RC1
|
|
[wxwidgets-doc]:http://docs.wxwidgets.org/3.0/
|
|
[wxdialog-setescapeid]:http://docs.wxwidgets.org/3.0/classwx_dialog.html#a585869988e308f549128a6a065f387c6
|
|
[wxwidgets-sizers]:http://docs.wxwidgets.org/3.0/overview_sizer.html
|
|
[wxwidgets-validator]:http://docs.wxwidgets.org/3.0/overview_validator.html
|
|
[kicad-src-dialog-shim]:http://bazaar.launchpad.net/~kicad-product-committers/kicad/product/view/head:/common/dialog_shim.cpp
|