diff --git a/source/components/navigation/actionbutton.rst b/source/components/navigation/actionbutton.rst index 07714db..c092c73 100644 --- a/source/components/navigation/actionbutton.rst +++ b/source/components/navigation/actionbutton.rst @@ -1,67 +1,102 @@ Primary Action Button ===================== .. figure:: /img/Actionbutton1.png :figclass: border :alt: Primary Action Button Primary action, create a new address book entry. When to use ----------- Use a Primary Action Button whenever there is a primary action for a certain page of your application or for the whole application, which is executed frequently. Typical primary actions are "Create New", "Edit,", "Save" or "Send". Aditionally you can opt to define two secondary primary actions that are placed left and right to the main primary button. .. figure:: /img/Actionbutton2.png :figclass: border :alt: Primary Action Button with two secondary buttons Call, message and write an email as primary actions. If there is no primary action, you may opt to use the Primary Action Button as a shortcut to navigate back to the application's main page instead of omitting it completely. Do that if - navigating back to the main page is a frequent action in your application - or you use Primary Action buttons on some pages and would like to keep the layout consistent across pages - or drawers are frequently used - and the space occupied by the button is not urgently needed for the content If the primary action is clearly associated with a specific element on the user interface, place controls within the content instead. How to use ---------- - Provide a clear icon for the Primary Action Button since it has no text label - If the Primary Action Button changes its action within a page (for example switching to "save" when editing, change its icon as well - If you use the Primary Action Button as a shortcut for going to the main page, use the "go-home" icon from the actions category for it. Desktop-specific ~~~~~~~~~~~~~~~~ If your application is using :doc:`column-based navigation ` - If there is a global Primary Action, associate it with the first column - If there is a Primary action for the context of a specific column, associated with the respective page .. figure:: /img/Actionbutton3.png :figclass: border :alt: Primary Action Buttons on Desktop Primary Action Buttons are placed in a :doc:`toolbar ` + +Code +---- + +Kirigami +^^^^^^^^ + +.. code-block:: qml + + ... + import QtQuick.Controls 2.2 as Controls + import org.kde.kirigami 2.4 as Kirigami + ... + + Kirigami.ApplicationWindow { + ... + pageStack.initialPage: Kirigami.ScrollablePage { + ... + actions { + left: Kirigami.Action { + iconName: "mail-message" + text: i18n("&Write mail") + } + main: Kirigami.Action { + iconName: "call-start" + text: i18n("&Make call") + } + right: Kirigami.Action { + iconName: "kmouth-phrase-new" + text: i18n("&Write SMS") + } + } + } + ... + } diff --git a/source/components/navigation/contextdrawer.rst b/source/components/navigation/contextdrawer.rst index 52a1ff1..e8c1af8 100644 --- a/source/components/navigation/contextdrawer.rst +++ b/source/components/navigation/contextdrawer.rst @@ -1,46 +1,104 @@ Context drawer ============== .. figure:: /img/Context_drawer.jpg :scale: 50 % :alt: Examples of a context drawer Examples of a context drawer Purpose ------- The Context Drawer is used to access controls that depend on the current context. This can be, for example, controls that affect a selected element in a list or that navigate through an opened document. Is this the right control? -------------------------- Use a Context Drawer if your application has any functions which are only relevant in specific contexts, and which are not central enough to the application's main purpose to put them in the main user interface or in a toolbar. For actions which are always available, use the :doc:`Global Drawer `. Guidelines ---------- - The Context Drawer is opened by swiping in from the left or right edge of the screen (depending on a system-wide setting) and closed by swiping in the other direction or tapping outside of it. - At the top of the drawer, state which object the controls affect (e.g. "Selected email") - By default, the Context Drawer simply contains a vertical list of action buttons which affect the currently selected/opened element - Center the list vertically instead of top-aligning, to allow an easier reach with the thumb - If needed, other controls related to the current context can be put in the Context Drawer - Try to keep the content of the context drawer in one page. If there two distinct "modes" of contextual actions (for example navigating through a PDF either by table of contents or thumbnails), consider using two :doc:`Tabs ` to separate them, but never use more than two tabs. + +Code +---- + +Kirigami +^^^^^^^^ + +.. code-block:: qml + + ... + import QtQuick.Controls 2.2 as Controls + import org.kde.kirigami 2.4 as Kirigami + ... + + Kirigami.ApplicationWindow { + ... + pageStack.initialPage: Kirigami.ScrollablePage { + ... + actions { + ... + contextualActions: [ + Kirigami.Action { + iconName: "favorite" + text: i18n("&Select as favorite") + }, + Kirigami.Action { + iconName: "document-share" + text: i18n("&Share") + }, + Kirigami.Action { + iconName: "document-edit" + text: i18n("&Edit") + }, + Kirigami.Action { + iconName: "edit-image-face-add" + text: i18n("&Choose photo") + }, + Kirigami.Action { + iconName: "im-kick-user" + text: i18n("&Block number") + }, + Kirigami.Action { + iconName: "delete" + text: i18n("&Delete contact") + }, + Kirigami.Action { + iconName: "edit-clear-history" + text: i18n("&Delete history") + } + ] + ... + } + } + ... + contextDrawer: Kirigami.ContextDrawer { + } + ... + } diff --git a/source/components/navigation/globaldrawer.rst b/source/components/navigation/globaldrawer.rst index 3c14a1e..87fcd33 100644 --- a/source/components/navigation/globaldrawer.rst +++ b/source/components/navigation/globaldrawer.rst @@ -1,53 +1,95 @@ Global drawer ============= .. figure:: /img/Menu_Drawer.png :alt: Examples of different global drawers Examples of different global drawers Purpose ------- The Global Drawer is a standard element in KDE mobile applications. It contains an application's main menu, and any functions which are not part of the application's main usecases but are not specific to the current context either. Is this the right control? -------------------------- Use a Global Drawer whenever your application has any functions which are not central enough to the application's main purpose to put them in the main user interface, and which are not dependent on the current context. For context-specific actions (e.g. those affecting a selected item), use the :doc:`Context Drawer ` Guidelines ---------- The Global Drawer is opened by swiping in from the left or right edge of the screen (depending on a system-wide setting) and closed by swiping in the other direction or tapping outside of it. A Global Drawer may contain the following controls: - :doc:`Tabs ` - A main menu - :doc:`Push Buttons ` to execute non-contextual actions - :doc:`Checkboxes <../editing/checkbox>` or :doc:`Radio Buttons <../editing/radiobutton>` to change settings which are commonly changed The main menu - Must not have more than three levels - Should if possible not contain more elements than fit on the screen - Should contain an entry :doc:`Settings ` in the last position if the application has settings which are not commonly changed - Selecting an entry in the menu either executes an action or goes down one level, replacing the menu with the items in the selected submenu - In lower menu levels, below the entries there is a button to go up one level. Do not use the Menu Drawer for navigation purposes. + +Code +---- + +Kirigami +^^^^^^^^ + +.. code-block:: qml + + ... + import QtQuick.Controls 2.2 as Controls + import org.kde.kirigami 2.4 as Kirigami + ... + + Kirigami.ApplicationWindow { + ... + globalDrawer: Kirigami.GlobalDrawer { + actions: [ + Kirigami.Action { + iconName: "list-import-user" + text: i18n("&Import") + }, + Kirigami.Action { + iconName: "list-export-user" + text: i18n("&Export") + }, + Kirigami.Action { + iconName: "user-group-delete" + text: i18n("&Merge contacts") + }, + Kirigami.Action { + iconName: "user-group-new" + text: i18n("&Search dupplicate contacts") + }, + Kirigami.Action { + iconName: "configure" + text: i18n("&Settings") + } + ] + } + ... + } diff --git a/source/components/navigation/menubar.rst b/source/components/navigation/menubar.rst index 288a99a..c9607a2 100644 --- a/source/components/navigation/menubar.rst +++ b/source/components/navigation/menubar.rst @@ -1,82 +1,125 @@ Menu bar ======== Purpose ------- A *menu bar* appears at the top of an application's main window. It provides access to all commands and most of the settings available in an application. Users refer frequently to the menu bar, especially when they are seeking a function for which they know of no other interface. Ensuring that menus are well organized, are worded clearly, and behave correctly is crucial to the user’s ability to explore and access the functionality of the application. Examples -------- Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - A menu bar is mandatory for applications that have a :doc:`very complex command structure `, such as those used for content creation or editing, file manipulation, or other productivity work. - Menu bars are optional for simple apps that are able to expose all functionality using visible buttons and toolbars. If any functionality is not visible by default, err on the side of providing a menu bar. - Do not display a menu bar in secondary or internal windows, like the settings dialog or file dialog. Very small main windows are likewise usually poor candidates for menu bars. - Do not include a menu bar in a convergent application's mobile user interface. Behavior ~~~~~~~~ - Do not have more than nine menu categories within a menu bar. Too many categories are overwhelming and makes the menu bar difficult to use. - At the minimum, all windows should have File, Edit, Settings, and Help menus. If they apply, the window can also have View, Insert, Format, Tools and, Window menus. - Do not put more than 12 items within a single level of a menu. Add separators between logical groups within a menu. Organize the menu items into groups of seven or fewer strongly related items. - Assign shortcut keys to the most frequently used menu items. Use `KStandardAction `_ and `KStandardShortcut `_ items for common functions, which will result in menu items automatically receiving consistent names, icons, and shortcut keys. Any tool or function that is accessible using a keyboard shortcut must have an item in the menu bar so that users can discover it. - Do not hide the menu bar by default. If this is configurable, users should easily be able to make the menu bar viewable again. - Use submenus cautiously. Submenus add complexity to the interface and are physically more difficult to use, so you should take care not to overuse them. Appearance ~~~~~~~~~~ - Place the most frequently used items at the top of the menu. - Provide icons for all menu items. Do not re-use the same icon for multiple items. - For your menu items' text, follow the :doc:`general label guidelines `. - Do not change menu items' labels dynamically. - Choose single word names for menu categories. Using multiple words makes the separation between categories confusing. - Disable menu items that don't apply to the current context instead of removing them from view. **Exception:** It is acceptable to hide menu items completely if they are permanently unavailable on the user's system due to missing hardware capabilities. - Assign :doc:`shortcut keys ` to the most frequently used menu items (Ctrl+). For well-known shortcut keys, use standard assignments. Use function keys for commands that have a small-scale effect (F2 = Rename) and ctrl key for large-scale effect (Ctrl+S = Save). - For menu items that toggle some state on or off, always use the positive form. For example, use the text 'Show hidden files' instead of 'Hide hidden files', and do not change the text when hidden files are shown. +Code +---- + +Kirigami +^^^^^^^^ + +.. code-block:: qml + + ... + import QtQuick.Controls 2.2 as Controls + import org.kde.kirigami 2.4 as Kirigami + ... + + Kirigami.ApplicationWindow { + ... + menuBar: MenuBar { + Menu { + title: i18n("&File") + Action { text: i18n("&New...") } + Action { text: i18n("&Import") } + Action { text: i18n("&Export") } + } + Menu { + title: i18n("&Edit") + Action { text: i18n("&Merge contacts") } + Action { text: i18n("&Search dupplicate contacts") } + Action { text: i18n("&Export") } + } + Menu { + title: i18n("&Settings") + Action { text: i18n("&Settings") } + Action { text: i18n("&Configure shortcuts") } + } + Menu { + title: i18n("&Help") + Action { text: i18n("&Report Bug...") } + Action { text: i18n("&Donate") } + Action { text: i18n("&About Addressbook") } + Action { text: i18n("&About KDE") } + } + } + ... + } diff --git a/source/components/navigation/toolbar.rst b/source/components/navigation/toolbar.rst index fdb7941..9bb1843 100644 --- a/source/components/navigation/toolbar.rst +++ b/source/components/navigation/toolbar.rst @@ -1,96 +1,159 @@ Toolbar ======= .. figure:: /img/Actionbutton3.png :figclass: border :alt: Primary Action Buttons on Desktop Toolbar with the most important actions :doc:`toolbar ` Purpose ------- A *toolbar* is a graphical presentation of commands optimized for fast access. A toolbar can be either be defined for a whole application or as part of another component. As an application toolbar it contains buttons that correspond to items in the application's menu, providing direct access to application's most frequently used functions. A good menu bar is a comprehensive catalog of all the available top-level commands, whereas a good toolbar gives quick, convenient access to frequently used commands. As part of another component, like a card or an inline mesage, it is used to allow quick access to the most important commands for a single, focused content item. Guidelines for application -------------------------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - For standard applications, show a toolbar by default. - Provide a toolbar in addition to the menu bar, but do not replace the menu bar. Behavior ~~~~~~~~ - A toolbar should contain only a few, frequently used operations. If the number of operations is above 5 they have to be grouped with separators. Not more than 3 of those sections should be implemented. - Do not abuse the toolbar to expose application's features. Only the most frequently functions should be add to the toolbar. - Execute operations immediately; do not require additional input. - Try to avoid using :doc:`split buttons ` or :doc:`toggle buttons <../editing/togglebutton>` in order to keep the interaction with all buttons in the toolbar consistent. - Do not hide toolbars by default. If configurable, users should easily be able to make the toolbar viewable again. - Disable buttons that do not apply to the current context. - Consider to provide customization for toolbars in respect to position and content. - Providing a label for each action is a good practice but define a meaningful icon too because the label could be hidden in mobile mode or if there isn't enough space when the window is resized. Guidelines for components ------------------------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a toolbar only if an item has few actions or few frequently used actions. - Embed a toolbar only in another control that is clearly visually seperated like a card or an inline message. Behavior ~~~~~~~~ - A toolbar should contain only a few, frequently used operations. The number of operations should not exceed 3. - Do not group with separators. - Execute operations immediately; do not require additional input. - Do not hide toolbars or make them configurable. - Toolbars can be responsive. If there is not enough space to display all the buttons, an overflow menu is shown instead. .. raw:: html Appearance ---------- - Do not change the button style from the default, which is :doc:`text beside icons `. - Use and design toolbar icons with special care. Users remember location of an object but rely as well on icon properties. - A distinct association between the underlying function and its visual depiction is crucial. Follow the advices for :doc:`icon design `. - Do not simulate Microsoft's ribbon controls. KDE stays plain and simple.Microsoft's ribbon controls. KDE stays plain and simple. + +Code +---- + +Kirigami +~~~~~~~~ + +Application toolbar +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: qml + + ... + import QtQuick.Controls 2.2 as Controls + import org.kde.kirigami 2.4 as Kirigami + ... + + Kirigami.ApplicationWindow { + ... + pageStack.initialPage: Kirigami.ScrollablePage { + ... + actions { + left: Kirigami.Action { + iconName: "mail-message" + text: i18n("&Write mail") + } + main: Kirigami.Action { + iconName: "call-start" + text: i18n("&Make call") + } + right: Kirigami.Action { + iconName: "kmouth-phrase-new" + text: i18n("&Write SMS") + } + } + } + ... + } + +Component toolbar +^^^^^^^^^^^^^^^^^ + +.. code-block:: qml + + ... + import QtQuick.Controls 2.2 as Controls + import org.kde.kirigami 2.4 as Kirigami + ... + Kirigami.ActionToolBar { + ... + actions: [ + Kirigami.Action { + iconName: "favorite" + text: i18n("&Select as favorite") + }, + Kirigami.Action { + iconName: "document-share" + text: i18n("&Share") + } + ] + ... + } + ...