diff --git a/source/components/assistance/tooltip.rst b/source/components/assistance/tooltip.rst index 11fabcf..dbf95cd 100644 --- a/source/components/assistance/tooltip.rst +++ b/source/components/assistance/tooltip.rst @@ -1,71 +1,76 @@ Tooltip ======= Purpose ------- A *tooltip* is a small pop-up window that provides more information on an element under the mouse cursor, such as toolbar controls without caption or command buttons. Tooltips provide additional descriptive text including formatting and icons. Tips eliminate the need to always have descriptive text on the screen. Novice users will use hovering to show tooltips to become familiar with the interface. This time-delay mechanism makes tips very convenient, but it also reduces their discoverability. When tips are used consistently they support user’s expectation and foster predictability. Guidelines ---------- Is this the right control ~~~~~~~~~~~~~~~~~~~~~~~~~ - Use tips to label unlabeled controls and to provide additional information. - Don’t use tips for warnings. Behavior ~~~~~~~~ - Keep tips brief, typically five words or less for tool-tips. Whenever appropriate, provide keyboard short-cuts and default values. - Tooltips for a disabled control should include information regarding the disabled state of the control. Include this information even if the control is enabled. For instance: 'Go to the next unread message' in the case of enabled controls and 'Go to the next unread message (No unread messages left)' when disabled. - Consider adding small informational buttons for touch screen use. Appearance ~~~~~~~~~~ - Format and organize content in tooltips to make it easier to read and scan. The information should be: - concise: large, unformatted blocks of text are difficult to read and overwhelming - helpful: it should add information, not repeat information - supplemental: important information should be communicated using self-explanatory control labels or in-place supplemental text - static: tips should not change from one instance to the next - Do not use icons and formattings for tips of unlabeled controls. - Use tool-tips with icons and formatting - if tips describe comprehensive functions, - when content is lengthy and formatting improves readability - for tips that are implemented primarily for joy of use. Code ---- Kirigami ~~~~~~~~ - :kirigamiapi:`Kirigami: ApplicationWindow ` - `QML: MenuBar `_ Plasma components ~~~~~~~~~~~~~~~~~ - :plasmaapi:`Plasma ToolTip ` + +Qt Widgets +~~~~~~~~~~ + + - :kwidgetsaddonsapi:`QtWidgets: KToolTipWidget ` diff --git a/source/components/navigation/dialog.rst b/source/components/navigation/dialog.rst index f1ef59a..ae89959 100644 --- a/source/components/navigation/dialog.rst +++ b/source/components/navigation/dialog.rst @@ -1,87 +1,111 @@ Dialog ====== .. image:: /img/Dialog1.png :alt: Dialog :scale: 50% Purpose ------- A *dialog* is a secondary window that allows users to perform a command, asks users a question, or provides users with information or progress feedback. Dialogs can be modal and require users to complete and close before continuing with the owner window, or modeless, i.e. users can switch between dialogs and parent window. Guidelines ---------- Is this the right control? ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Use a dialog to structure the work flow. For instance, the functions Open, Save, Advanced Search need user input or confirmation. In particular, dialogs are expected by users for configuration. - Do not use dialogs if the flow must not get interrupted. In this case prefer inline controls. - Consider to use alternative ways for communication with users like :doc:`tooltip <../assistance/tooltip>` or a :doc:`inline message <../assistance/inline>`. - Always use standard dialogs, if available. Behavior ~~~~~~~~ - Do not apply dialog boxes that require the use of a scroll bar. - Do not include a menu bar or status bar in dialogs. - Do not display more than one owned choice dialog at a time from an owner choice dialog. - Always keep dialogs on top of their parent. - Set input focus on confirmation button by default. But set focus on disruptive button (Cancel, Don't apply or the like) if the dialog comprises of critical confirmation. - Avoid to nest dialogs, especially in case of modal dialogs. - Avoid dialogs that contain only one or two options. If possible, use direct selection or inline-editing instead. - Do not use dialogs to display non-critical messages which do not require any further user interaction (typically dialogs with a single "OK" or "Close" button). Consider to use :doc:`tooltip <../assistance/tooltip>` or a :doc:`inline message <../assistance/inline>`. - Use modal dialogs only if allowing interaction with other parts of the application while the window is opened could cause data loss or some other serious problem. - Provide a clear way of leaving the modal dialog, such as a Cancel button. - When the dialog is used to inform about an unexpected condition that needs interaction, follow the guidelines for :doc:`message dialogs <../assistance/message>`. Appearance ~~~~~~~~~~ - Use tabbed dialogs when you have a limited number of tabs (max. 6). If you cannot see all the tabs without scrolling or splitting them into multiple rows, you are probably using too many and should use a paged dialog instead. - Always use paged dialogs for configuration dialogs - assuming that there is more than one section of options to be configured. For other dialogs, use paged dialogs if there are too many tabs to put them into a tabbed dialog. - Dialogs should not be bigger than two thirds of the screen size and should always be resizable. Take care about high resolution displays (i.e. QXGA and more). - Save and restore user adjustments of dialog size. - Make sure there is at least one third white space, do not overload the panel. - Consider the common reading direction from left to right and top to bottom. - Dialogs are grouped in meaningful sections, for instance by :doc:`group boxes <../formating/groupbox>`. The actions are grouped along their context of use, not along technical relations. - Provide a title to each section. - Follow the guidelines for :doc:`alignment `. + +Code +---- + +Qt Widgets +~~~~~~~~~~ + + - :kwidgetsaddonsapi:`QtWidgets: KPageDialog ` + +.. code-block:: c++ + + UrlDialog::UrlDialog( QWidget *parent ) + : KPageDialog( parent ) + { + setFaceType( List ); + QLabel *label = new QLabel( "Test Page" ); + addPage( label, i18n( "My Test Page" ) ); + label = new QLabel( "Second Test Page" ); + KPageWidgetItem *page = new KPageWidgetItem( label, i18n( "My Second + Test Page" ) ); + page->setHeader( i18n( "My header string" ) ); + page->setIcon( QIcon::fromTheme( "file" ) ); + addPage( page ); + } diff --git a/source/components/navigation/menubar.rst b/source/components/navigation/menubar.rst index 09e4e94..6a7c671 100644 --- a/source/components/navigation/menubar.rst +++ b/source/components/navigation/menubar.rst @@ -1,128 +1,133 @@ 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 ~~~~~~~~ - :kirigamiapi:`Kirigami: ApplicationWindow ` - `QML: MenuBar `_ .. 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") } } } ... } + +Qt Widgets +~~~~~~~~~~ + + - :kwidgetsaddonsapi:`QtWidgets: KActionMenu `