Developer documentation improvements.
* Convert user interface guidelines to markdown and add to the documentation created by Doxygen. * Remove HOW_TO_CONTRIBUTE.txt. This information is covered elsewhere. * Remove wxWidgets_patch_notes.txt.
This commit is contained in:
Wayne Stambaugh
parent
fde2cfee27
commit
740f8f55d8
|
|
@ -1,27 +0,0 @@
|
||||||
Contribute to KiCad (under Linux)
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
1) make sure you have all the dependencies of KiCad and installed a copy
|
|
||||||
of kicad sources:
|
|
||||||
see <kicad>/Documentation/development/compiling.md
|
|
||||||
|
|
||||||
2) Read coding_style_policy.pdf, in <kicad>/Documentation,
|
|
||||||
and other docs.
|
|
||||||
|
|
||||||
3) Modify/add source code in kicad sources
|
|
||||||
|
|
||||||
4) Compile:
|
|
||||||
see compiling.md
|
|
||||||
|
|
||||||
5) Repeat step 3 and 4 until satisfied.
|
|
||||||
|
|
||||||
9) Create a patch file:
|
|
||||||
if you added the file foo.cpp do so:
|
|
||||||
bzr add foo.cpp
|
|
||||||
Create the patch
|
|
||||||
bzr diff > my_changes.patch
|
|
||||||
|
|
||||||
9) Send the patch file "my_changes.patch" to the KiCad developers mailing list.
|
|
||||||
in the subject of the e-mail include the keyword "[PATCH]".
|
|
||||||
in the body of the e-mail clearly explain what you have done.
|
|
||||||
|
|
||||||
|
|
@ -27,7 +27,7 @@ DOXYFILE_ENCODING = UTF-8
|
||||||
# identify the project. Note that if you do not use Doxywizard you need
|
# identify the project. Note that if you do not use Doxywizard you need
|
||||||
# to put quotes around the project name if it contains spaces.
|
# to put quotes around the project name if it contains spaces.
|
||||||
|
|
||||||
PROJECT_NAME = "KiCad Developer's Resource Documentation"
|
PROJECT_NAME = "KiCad Developer's Resource"
|
||||||
|
|
||||||
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
|
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
|
||||||
# This could be handy for archiving the generated documentation or
|
# This could be handy for archiving the generated documentation or
|
||||||
|
|
@ -650,7 +650,8 @@ INPUT = coding-style-policy.md \
|
||||||
stable-release-policy.md \
|
stable-release-policy.md \
|
||||||
road-map-r5.md \
|
road-map-r5.md \
|
||||||
road-map.md \
|
road-map.md \
|
||||||
compiling.md
|
compiling.md \
|
||||||
|
ui-policy.md
|
||||||
|
|
||||||
# This tag can be used to specify the character encoding of the source files
|
# This tag can be used to specify the character encoding of the source files
|
||||||
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
|
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
|
||||||
|
|
|
||||||
|
|
@ -4,7 +4,7 @@ of KiCad which can be found at the [download][] page on the [KiCad website][].
|
||||||
from source is not for the faint of heart and is not recommended unless you have reasonable
|
from source is not for the faint of heart and is not recommended unless you have reasonable
|
||||||
software development experience. This document contains the instructions on how to build KiCad
|
software development experience. This document contains the instructions on how to build KiCad
|
||||||
from source on the supported platforms. It is not intended as a guide for installing or building
|
from source on the supported platforms. It is not intended as a guide for installing or building
|
||||||
[library dependencies](#library_dependencies). Please consult you platforms documentation for
|
[library dependencies](#library_dependencies). Please consult your platforms documentation for
|
||||||
installing packages or the source code when building the library dependencies. Currently the
|
installing packages or the source code when building the library dependencies. Currently the
|
||||||
supported platforms are Windows Versions 7-10, just about any version of Linux, and OSX
|
supported platforms are Windows Versions 7-10, just about any version of Linux, and OSX
|
||||||
10.7-10.10. You may be able to build KiCad on other platforms but it is not supported. On
|
10.7-10.10. You may be able to build KiCad on other platforms but it is not supported. On
|
||||||
|
|
@ -95,7 +95,7 @@ abstraction library [GAL] and is always required to build KiCad.
|
||||||
|
|
||||||
## Cairo 2D Graphics Library ## {#cairo}
|
## Cairo 2D Graphics Library ## {#cairo}
|
||||||
|
|
||||||
The [Cairo][] 2D graphics library is used as a fallback rendering canvas when OpenGL is no
|
The [Cairo][] 2D graphics library is used as a fallback rendering canvas when OpenGL is not
|
||||||
available and is always required to build KiCad.
|
available and is always required to build KiCad.
|
||||||
|
|
||||||
## Python Programming Language ## {#python}
|
## Python Programming Language ## {#python}
|
||||||
|
|
@ -180,7 +180,7 @@ GitHub using the following command:
|
||||||
|
|
||||||
Here is a list of source links:
|
Here is a list of source links:
|
||||||
|
|
||||||
Stable release archive: https://launchpad.net/kicad/4.0/4.0.1/+download/kicad-4.0.1.tar.xz
|
Stable release archive: https://launchpad.net/kicad/4.0/4.0.2/+download/kicad-4.0.2.tar.xz
|
||||||
|
|
||||||
Development branch: https://code.launchpad.net/~kicad-product-committers/kicad/product
|
Development branch: https://code.launchpad.net/~kicad-product-committers/kicad/product
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,166 @@
|
||||||
|
# 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].
|
||||||
|
Please use the most recent version of wxFormBuilder possible to prevent version
|
||||||
|
issues with other developers. 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.
|
||||||
|
|
||||||
|
# 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/
|
||||||
|
[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
|
||||||
|
|
@ -1,133 +0,0 @@
|
||||||
|
|
||||||
** 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.
|
|
||||||
|
|
||||||
|
|
@ -1,17 +0,0 @@
|
||||||
--== notes about wxWidgets problems ==--
|
|
||||||
Last Revised: 28-dec-2015
|
|
||||||
|
|
||||||
Kicad needs wxWidgets, the multi platform G.U.I toolkit.
|
|
||||||
|
|
||||||
use *only* wxWidgets >= 3.0.2
|
|
||||||
|
|
||||||
Known bug on Windows:
|
|
||||||
Postscript printers print tracks like thin line.
|
|
||||||
It happens only for PS drivers, and PDF printer.
|
|
||||||
Other drivers (PCL for instance) work fine,
|
|
||||||
so it is unlikely a bug inside Kicad/wxWidgets
|
|
||||||
|
|
||||||
Window version :
|
|
||||||
The mirror mode gives a blank sheet.
|
|
||||||
This is a bug in wxWidgets 3.0.2
|
|
||||||
wxWidgets 3.0.2 must be patched (see patches/wxWidgets-3.0.2-msw-dc-orientation-fix.patch) and rebuilt.
|
|
||||||
1
Doxyfile
1
Doxyfile
|
|
@ -650,6 +650,7 @@ INPUT = Documentation/development/coding-style-policy.md \
|
||||||
Documentation/development/road-map-r5.md \
|
Documentation/development/road-map-r5.md \
|
||||||
Documentation/development/road-map.md \
|
Documentation/development/road-map.md \
|
||||||
Documentation/development/compiling.md \
|
Documentation/development/compiling.md \
|
||||||
|
Documentation/development/ui-policy.md \
|
||||||
kicad \
|
kicad \
|
||||||
pcbnew \
|
pcbnew \
|
||||||
cvpcb \
|
cvpcb \
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue