diff --git a/source/components/index.rst b/source/components/index.rst index 082d247..17bf470 100644 --- a/source/components/index.rst +++ b/source/components/index.rst @@ -1,49 +1,53 @@ Components ========== .. toctree:: :maxdepth: 1 :titlesonly: :hidden: actionbutton checkbox combobox contextdrawer contextmenu dialog dropdown globaldrawer groupbox + inline lineedit menubar + message radiobutton slider spinbox splitter statusbar tableview textedit toolbar tooltip * :doc:`actionbutton` * :doc:`checkbox` * :doc:`combobox` * :doc:`contextdrawer` * :doc:`contextmenu` * :doc:`dialog` * :doc:`dropdown` * :doc:`globaldrawer` * :doc:`groupbox` +* :doc:`inline` * :doc:`lineedit` * :doc:`menubar` +* :doc:`message` * :doc:`radiobutton` * :doc:`slider` * :doc:`spinbox` * :doc:`splitter` * :doc:`statusbar` * :doc:`tableview` * :doc:`textedit` * :doc:`toolbar` * :doc:`tooltip` diff --git a/source/components/inline.rst b/source/components/inline.rst new file mode 100644 index 0000000..a50e4ed --- /dev/null +++ b/source/components/inline.rst @@ -0,0 +1,139 @@ +Inline message +============== + +Purpose +------- + +A *inline message* is a small pop-up panel shown at top of the current +form that informs users of a non-critical problem or special condition. +The panel shows information on four levels indicated by different colors +and icons, and provides standard action that users might want to +initiate. + +.. figure:: /img/Message5.qml.png + :alt: Different levels of inline messages. + :scale: 80% + + The four different levels of inline messages. + +Examples +-------- + +.. figure:: /img/Message-example.png + :alt: + + An inline message is used for feeback after an upload has been completed. + +Guidelines +---------- + +- Use inline messages in cases of non-critical problems that user can + solve. + + - Use *negative feedback* (aka error) as a secondary indicator of + failure, e.g. if a transaction was not completed successfully + - Show the information on a warning level in case of relevant + information that do not concern the current workflow, e.g. No + Internet connection available. + - Use *positive feedback* to notify about user-initiated processes, + e.g. to indicate completion of background tasks + - Use *opportunistic interaction* (aka notification) to acknowledge + the user about options that he or she might be interested in, e.g. + "Remember password?" + +- Display the information immediately. +- When users dismiss the inline message, do not display any other UI or start + any other side effect. +- Do not add controls to the inline message other than action buttons + for opportunistic interaction. +- Consider to show a :doc:`notification` if information does not concern + the current workflow. + +Is this the right control? / Behavior +------------------------------------- + +Negative feedback +~~~~~~~~~~~~~~~~~ + +The inline message should be used as a secondary indicator of failure: +the first indicator is for instance that the action the user expected to +happen did not happen. + +Example: User fills a form, clicks "Submit". + +- Expected feedback: form closes +- First indicator of failure: form stays there +- Second indicator of failure: a inline message appears on top of the + form, explaining the error condition + +When used to provide negative feedback, an inline message should be placed +close to its context. In the case of a form, it should appear on top of +the form entries. + +An inline message should get inserted in the existing layout. Space should +not be reserved for it, otherwise it becomes "dead space", ignored by +the user. An inline message should also not appear as an overlay to prevent +blocking access to elements the user needs to interact with to fix the +failure. + +When used for negative feedback, do not offer a close button. The +message panel only closes when the problem it informs about (e.g. the +error) is fixed. + +Positive feedback +~~~~~~~~~~~~~~~~~ + +An inline message can be used for positive feedback but it shouldn't be +overused. It is often enough to provide feedback by simply showing the +results of an action. + +Examples of acceptable uses: + +- Confirm success of "critical" transactions +- Indicate completion of background tasks + +Example of wrong uses: + +- Indicate successful saving of a file +- Indicate a file has been successfully removed + +Opportunistic interaction +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Opportunistic interaction is the situation where the application +suggests to the user an action he could be interested in perform, either +based on an action the user just triggered or an event which the +application noticed. + +Example use cases: + +- A browser can propose remembering a recently entered password +- A music collection can propose ripping a CD which just got inserted +- A chat application may notify the user a "special friend" just + connected + +Appearance +---------- + +A basic inline messages consists of an icon and text. It can contain an optional +close button and :doc:`buttons `. + +.. figure:: /img/Message1.qml.png + :alt: Inline message with a custom icon and a close button. + :scale: 80% + + Inline message with a custom icon and a close button. + +.. figure:: /img/Message2.qml.png + :alt: Inline message with two buttons. + :scale: 80% + + Inline message with two buttons. + +If there is not enough space to display all the buttons, an overflow menu is shown instead. + +.. figure:: /img/Message3.qml.png + :alt: Inline message with overflow menu. + :scale: 80% + + Inline message with overflow menu. diff --git a/source/components/message.rst b/source/components/message.rst new file mode 100644 index 0000000..1a6a12d --- /dev/null +++ b/source/components/message.rst @@ -0,0 +1,108 @@ +Message +======= + +Purpose +------- + +If the processing has reached an unexpected condition that needs +interaction, a disruptive message alerts the user of a problem. Not any +disruptive message concerns a serious problem. Sometimes, the user is +just notified that proceeding is dangerous. A typical example is the +“Save changes before closing?” alert box that appears when a user tries +to close a module with modified content. The adequate presentation +method for disruptive information is a *modal message dialog*. + +A modal dialog is a secondary window that interrupts user's current +activity and blocks interaction until user either simply acknowledge the +information by clicking Ok or decides how to proceed (e.g. Yes/No). +Effective error messages inform users that a problem occurred, explain +why it happened, and provide a solution so users can fix the problem. +Users should either perform an action or change their behavior as the +result of an error message. + +Modal dialogs are error-prone. An alert dialog that appears unexpectedly +or which is dismissed automatically (because the user has developed a +habit) will not protect from the dangerous action. + +Examples +-------- + +Guidelines +---------- + +Is this the right control +~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Avoid disruptive messages; workflow maintenance and, therefore, the + prevention of errors should be the primary objective. +- Use modal dialogs only for critical or infrequent, one-off tasks that + require completion before continuing. Don’t use modal error message + dialogs at the normal work flow to inform or warn the user. +- Use an :doc:`inline message ` for non-critical messages which do not require + any further user interaction (typically dialogs with a single "OK" or + "Close" button). +- Create specific, actionable, user-centered error messages. Users + should either perform an action or change their behavior as the + result of the message. +- Provide only a short error message and complement it by a Details + button that provides more a detailed explanation in the same error + dialog. +- Follow the guidelines of :doc:`dialogs ` in general. + +Behavior +~~~~~~~~ + +Messages should be: + +- Informative and constructive: + + - Tell the user the reason for a problem and + - help on how to solve the problem. + +- Understandable: + + - Phrase your messages clearly, in non-technical terms and avoid + obscure error codes. + +- Readable: + + - User has to be able to read the message in his/her own pace, think + about it, understand it. + - It is not acceptable to add countdown timers (visible or not) or + to force user to read and understand the message within a few + seconds. + +- Specific instead of general: + + - If the message is reporting a problem concerning a specific object + or application, use the object or application name when referring + to it. + +- Polite, non-terrifying and non-blaming: + + - Avoid wording that terrifies the user ("fatal", "illegal"), blames + him for his behavior, and be polite. + +Appearance +~~~~~~~~~~ + +- Apply confirmation button labels when no further input is required: + + - To close a warning or error message that does not require further + user interaction, provide a Close button. Do not use an OK button. + Users may get confused if they are asked to confirm an error. + +- Apply confirmation button labels when further interaction is + required: + + - Use buttons which match the type of statement or question made in + the warning or error message. For example, do no ask a Yes/No + question but then provide OK/Cancel buttons. + +- Apply confirmation button labels when the user must choose between + two actions to continue: + + - Use descriptive button labels instead of standard Yes/No or + OK/Cancel buttons. For example, if the user must choose to + continue or stop an action, provide the buttons "Continue" and + "Cancel". diff --git a/source/img/Message-example.png b/source/img/Message-example.png new file mode 100644 index 0000000..8f82c42 Binary files /dev/null and b/source/img/Message-example.png differ diff --git a/source/img/Message1.qml.png b/source/img/Message1.qml.png new file mode 100644 index 0000000..f800cc4 Binary files /dev/null and b/source/img/Message1.qml.png differ diff --git a/source/img/Message2.qml.png b/source/img/Message2.qml.png new file mode 100644 index 0000000..5444d28 Binary files /dev/null and b/source/img/Message2.qml.png differ diff --git a/source/img/Message3.qml.png b/source/img/Message3.qml.png new file mode 100644 index 0000000..be4670b Binary files /dev/null and b/source/img/Message3.qml.png differ diff --git a/source/img/Message5.qml.png b/source/img/Message5.qml.png new file mode 100644 index 0000000..7c6f18a Binary files /dev/null and b/source/img/Message5.qml.png differ