UIpolicies.txt 3.92 KB
Newer Older
dickelbeck's avatar
dickelbeck committed
1

2
** General UI Guidelines for KiCad Development
dickelbeck's avatar
dickelbeck committed
3 4


5
Capitalization:
dickelbeck's avatar
dickelbeck committed
6

7
    For any visible text used within KiCad, follow recommendations here:
8 9 10
    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.
dickelbeck's avatar
dickelbeck committed
11

12 13 14 15 16 17
    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.

dickelbeck's avatar
dickelbeck committed
18

19
Dialogs:
dickelbeck's avatar
dickelbeck committed
20 21

    Follow the recommendations here:
22

23
    http://developer.gnome.org/hig-book/stable/design-window.html.en
dickelbeck's avatar
dickelbeck committed
24
    paying particular attention to "initial focus", "sensible default values",
25 26 27 28
    "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
29 30 31
    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.
32 33

    Use wxWidgets "sizers" in all dialogs, no matter how simple they are:
34
    http://zetcode.com/tutorials/wxwidgetstutorial/layoutmanagement
dickelbeck's avatar
dickelbeck committed
35
    and keep dialogs resizeable.
36

dickelbeck's avatar
dickelbeck committed
37 38
    Configure the sizers so that as the dialog window is expanded, the most
    sensible use of the increased dialog window occurs automatically by the
39
    sizers. For example, in the DRC dialog of Pcbnew, sizers should be used to
dickelbeck's avatar
dickelbeck committed
40 41 42 43 44
    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
45 46
    near the perimeter of the increasingly larger dialog box, not necessarily
    leaving them all bundled tightly together.  The dialog box should look
dickelbeck's avatar
dickelbeck committed
47
    nice at any size large enough to show all the components.
48

49 50 51 52 53 54 55 56
    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.

57
    Use tooltips to explain the functionality of each non-obvious control.
dickelbeck's avatar
dickelbeck committed
58 59
    This is important because the help files and the wiki often lag behind
    the source code.
60 61 62 63 64 65 66 67 68 69

    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.
dickelbeck's avatar
dickelbeck committed
70

dickelbeck's avatar
dickelbeck committed
71
    Dialog windows shall not exceed 1024 x 768 when displayed in a 13 point font.
dickelbeck's avatar
dickelbeck committed
72 73 74 75
    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.

76 77 78 79 80 81 82
Quoting:
    Filenames and paths should be emphasized with <> angle brackets.  Anything
    else should be emphasized with single quotes ''.  e.g.:
    <filename.kicad_pcb>
    <longpath/subdir>
    'FOOTPRINTNAME'
    'anything else'
dickelbeck's avatar
dickelbeck committed
83