docs(tooltip): minor improvements; more examples (#9544)

src/lib/tooltip/tooltip.md

@@ -20,22 +20,46 @@ the positions `before` and `after` should be used instead of `left` and `right`,
 | `before`  | Display to the left in left-to-right layout and to the right in right-to-left layout |
 | `after`   | Display to the right in left-to-right layout and to the right in right-to-left layout|
 
+<!-- example(tooltip-position) -->
 
 ### Showing and hiding
 
-The tooltip is immediately shown when the user's mouse hovers over the element and immediately
-hides when the user's mouse leaves. A delay in showing or hiding the tooltip can be added through
-the inputs `matTooltipShowDelay` and `matTooltipHideDelay`. The default show and hide delays can be
-configured through the `MAT_TOOLTIP_DEFAULT_OPTIONS` injection token.
+By default, the tooltip will be immediately shown when the user's mouse hovers over the tooltip's
+trigger element and immediately hides when the user's mouse leaves. 
 
 On mobile, the tooltip is displayed when the user longpresses the element and hides after a
-delay of 1500ms. The longpress behavior requires HammerJS to be loaded on the page.
+delay of 1500ms. The longpress behavior requires HammerJS to be loaded on the page. To learn more
+about adding HammerJS to your app, check out the Gesture Support section of the Getting Started 
+guide.
 
-The tooltip can also be shown and hidden through the `show` and `hide` directive methods,
+#### Show and hide delays
+
+To add a delay before showing or hiding the tooltip, you can use the inputs `matTooltipShowDelay` 
+and `matTooltipHideDelay` to provide a delay time in milliseconds.
+
+The following example has a tooltip that waits one second to display after the user
+hovers over the button, and waits two seconds to hide after the user moves the mouse away.
+
+<!-- example(tooltip-delay) -->
+
+#### Changing the default delay behavior
+
+You can configure your app's tooltip default show/hide delays by configuring and providing
+your options using the `MAT_TOOLTIP_DEFAULT_OPTIONS` injection token.
+
+<!-- example(tooltip-modified-defaults) -->
+
+#### Manually calling show() and hide()
+
+To manually cause the tooltip to show or hide, you can call the `show` and `hide` directive methods,
 which both accept a number in milliseconds to delay before applying the display change.
 
-To turn off the tooltip and prevent it from showing to the user, use the `matTooltipDisabled` input
-flag.
+<!-- example(tooltip-manual) -->
+
+#### Disabling the tooltip from showing
+
+To completely disable a tooltip, set `matTooltipDisabled`. While disabled, a tooltip will never be 
+shown.
 
 ### Accessibility
 

src/material-examples/example-module.ts

@@ -119,7 +119,10 @@ import {TabsTemplateLabelExample} from './tabs-template-label/tabs-template-labe
 import {ToolbarMultirowExample} from './toolbar-multirow/toolbar-multirow-example';
 import {ToolbarOverviewExample} from './toolbar-overview/toolbar-overview-example';
 import {TooltipOverviewExample} from './tooltip-overview/tooltip-overview-example';
+import {TooltipDelayExample} from './tooltip-delay/tooltip-delay-example';
 import {TooltipPositionExample} from './tooltip-position/tooltip-position-example';
+import {TooltipManualExample} from './tooltip-manual/tooltip-manual-example';
+import {TooltipModifiedDefaultsExample} from './tooltip-modified-defaults/tooltip-modified-defaults-example';
 
 export interface LiveExample {
   title: string;
@@ -597,6 +600,18 @@ export const EXAMPLE_COMPONENTS: {[key: string]: LiveExample} = {
     title: 'Basic tooltip',
     component: TooltipOverviewExample
   },
+  'tooltip-delay': {
+    title: 'Tooltips with delay',
+    component: TooltipDelayExample
+  },
+  'tooltip-manual': {
+    title: 'Tooltips with manual show button',
+    component: TooltipManualExample
+  },
+  'tooltip-modified-defaults': {
+    title: 'Tooltips with modified default values',
+    component: TooltipModifiedDefaultsExample
+  },
   'tooltip-position': {
     title: 'Tooltip with custom position',
     component: TooltipPositionExample
@@ -718,6 +733,9 @@ export const EXAMPLE_LIST = [
   ToolbarMultirowExample,
   ToolbarOverviewExample,
   TooltipOverviewExample,
+  TooltipDelayExample,
+  TooltipManualExample,
+  TooltipModifiedDefaultsExample,
   TooltipPositionExample,
 ];
 

src/material-examples/tooltip-delay/tooltip-delay-example.css

@@ -0,0 +1,3 @@
+button {
+  margin: 8px;
+}

src/material-examples/tooltip-delay/tooltip-delay-example.html

@@ -0,0 +1,7 @@
+<button mat-raised-button matTooltip="Tooltip!" matTooltipShowDelay="1000">
+  My tooltip waits one second to show
+</button>
+
+<button mat-raised-button matTooltip="Tooltip!" matTooltipHideDelay="2000">
+  My tooltip waits two seconds to hide
+</button>

src/material-examples/tooltip-delay/tooltip-delay-example.ts

@@ -0,0 +1,11 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Tooltip with a show and hide delay
+ */
+@Component({
+  selector: 'tooltip-delay-example',
+  templateUrl: 'tooltip-delay-example.html',
+  styleUrls: ['tooltip-delay-example.css'],
+})
+export class TooltipDelayExample {}

src/material-examples/tooltip-manual/tooltip-manual-example.css

@@ -0,0 +1 @@
+/** No CSS for this example */

src/material-examples/tooltip-manual/tooltip-manual-example.html

@@ -0,0 +1,5 @@
+<button mat-raised-button (click)="tooltip.show()"> Show tooltip </button>
+
+<span matTooltip="This is the tooltip message" #tooltip="matTooltip">
+  I have a tooltip
+</span>

src/material-examples/tooltip-manual/tooltip-manual-example.ts

@@ -0,0 +1,11 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Tooltip that can be manually shown/hidden.
+ */
+@Component({
+  selector: 'tooltip-manual-example',
+  templateUrl: 'tooltip-manual-example.html',
+  styleUrls: ['tooltip-manual-example.css'],
+})
+export class TooltipManualExample {}

src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.css

@@ -0,0 +1 @@
+/** No CSS for this example */

src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.html

@@ -0,0 +1,3 @@
+<button mat-raised-button matTooltip="By default, I delay">
+  Button with delay-default tooltip
+</button>

src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.ts

@@ -0,0 +1,22 @@
+import {Component} from '@angular/core';
+import {MAT_TOOLTIP_DEFAULT_OPTIONS, MatTooltipDefaultOptions} from '@angular/material';
+
+/** Custom options the configure the tooltip's default show/hide delays. */
+export const myCustomTooltipDefaults: MatTooltipDefaultOptions = {
+  showDelay: 1000,
+  hideDelay: 1000,
+  touchendHideDelay: 1000,
+};
+
+/**
+ * @title Tooltip with a show and hide delay
+ */
+@Component({
+  selector: 'tooltip-modified-defaults-example',
+  templateUrl: 'tooltip-modified-defaults-example.html',
+  styleUrls: ['tooltip-modified-defaults-example.css'],
+  providers: [
+    {provide: MAT_TOOLTIP_DEFAULT_OPTIONS, useValue: myCustomTooltipDefaults}
+  ],
+})
+export class TooltipModifiedDefaultsExample {}