diff --git a/Documentation/HOW_TO_CONTRIBUTE.txt b/Documentation/HOW_TO_CONTRIBUTE.txt deleted file mode 100644 index 4e24dd1eda..0000000000 --- a/Documentation/HOW_TO_CONTRIBUTE.txt +++ /dev/null @@ -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 /Documentation/development/compiling.md - -2) Read coding_style_policy.pdf, in /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. - diff --git a/Documentation/development/Doxyfile b/Documentation/development/Doxyfile index 96cbecc396..9dcb4de298 100644 --- a/Documentation/development/Doxyfile +++ b/Documentation/development/Doxyfile @@ -27,7 +27,7 @@ DOXYFILE_ENCODING = UTF-8 # identify the project. Note that if you do not use Doxywizard you need # 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. # This could be handy for archiving the generated documentation or @@ -650,7 +650,8 @@ INPUT = coding-style-policy.md \ stable-release-policy.md \ road-map-r5.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 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/Documentation/development/compiling.md b/Documentation/development/compiling.md index f553be84d1..aa149849b3 100644 --- a/Documentation/development/compiling.md +++ b/Documentation/development/compiling.md @@ -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 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 -[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 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 @@ -95,7 +95,7 @@ abstraction library [GAL] and is always required to build KiCad. ## 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. ## Python Programming Language ## {#python} @@ -180,7 +180,7 @@ GitHub using the following command: 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 diff --git a/Documentation/development/ui-policy.md b/Documentation/development/ui-policy.md new file mode 100644 index 0000000000..90d733d2b3 --- /dev/null +++ b/Documentation/development/ui-policy.md @@ -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 diff --git a/Documentation/guidelines/UIpolicies.txt b/Documentation/guidelines/UIpolicies.txt deleted file mode 100644 index c271e20b27..0000000000 --- a/Documentation/guidelines/UIpolicies.txt +++ /dev/null @@ -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. - diff --git a/Documentation/wxWidgets_patch_notes.txt b/Documentation/wxWidgets_patch_notes.txt deleted file mode 100644 index fb877fbd60..0000000000 --- a/Documentation/wxWidgets_patch_notes.txt +++ /dev/null @@ -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. diff --git a/Doxyfile b/Doxyfile index 7d445d4cbc..a3fb54ea12 100644 --- a/Doxyfile +++ b/Doxyfile @@ -650,6 +650,7 @@ INPUT = Documentation/development/coding-style-policy.md \ Documentation/development/road-map-r5.md \ Documentation/development/road-map.md \ Documentation/development/compiling.md \ + Documentation/development/ui-policy.md \ kicad \ pcbnew \ cvpcb \