Migrate UseTooltipsToClarifyFunctions

3 files changed, 33 insertions, 0 deletions

diff --git a/documentation/articles/UseTooltipsToClarifyFunctions.asciidoc b/documentation/articles/UseTooltipsToClarifyFunctions.asciidoc
new file mode 100644
index 0000000000..af871a6332
--- /dev/null
+++ b/documentation/articles/UseTooltipsToClarifyFunctions.asciidoc
@@ -0,0 +1,32 @@
+[[use-tooltips-to-clarify-functions]]
+Use tooltips to clarify functions
+---------------------------------
+
+Even when clearly labelled, the action performed by a button might not
+be clear enough to the user. This is especially common when space or
+design constraints force you to keep the label very short, or use an
+icon instead of a label. This is where tooltips come in handy.
+
+image:img/tooltip.png[A tooltip]
+
+Tooltips are very easy to add to Vaadin components, although the method
+used to set them is the somewhat misleadingly named *setDescription()*:
+
+[source,java]
+....
+Button btnAttach = new Button();
+btnAttach.setIcon(new ThemeResource("icons/attach.png"));
+btnAttach.setDescription("Attach a file");
+....
+
+Of course, tooltips can be used for all kinds of UI components, not just
+buttons. An input field or even a read-only indicator can benefit from a
+tooltip. While the entire point of tooltips is to convey more
+information that would fit in the component’s caption or label, it’s
+still a good idea of try to keep the tooltip’s text as short as
+possible. Big tooltip balloons get in the way of using the UI and become
+annoying distractions instead of helpful aids.
+
+Keep in mind, however, that tooltips cannot be seen on a touch screen,
+since there is no mouse pointer to hover over the component. For input
+fields, consider using an *input prompt* instead.
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 215ade5dc2..c3d3eebd90 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -64,5 +64,6 @@ are great, too.
 - link:ValoExamples.asciidoc[Valo examples]
 - link:ReadOnlyVsDisabledFields.asciidoc[Read-only vs Disabled fields]
 - link:ValoThemeGettingStarted.asciidoc[Valo theme - Getting started]
+- link:UseTooltipsToClarifyFunctions.asciidoc[Use tooltips to clarify functions]
 - link:CreatingAUIExtension.asciidoc[Creating a UI extension]
 - link:CreatingAThemeUsingSass.asciidoc[Creating a theme using Sass]
diff --git a/documentation/articles/img/tooltip.png b/documentation/articles/img/tooltip.png
new file mode 100644
index 0000000000..1c4b1357ec
--- /dev/null
+++ b/documentation/articles/img/tooltip.png