From 36523828fe21d7df997458e44a7de8ccd203aefb Mon Sep 17 00:00:00 2001 From: Paul Gschwendtner Date: Sat, 21 Oct 2017 12:31:59 +0200 Subject: [PATCH 1/3] docs(ripple): update documentation * Improves the documentation of the `matRipple` attribute directive. References #7543. --- src/lib/core/ripple/README.md | 48 ---------------- src/lib/core/ripple/ripple.md | 102 ++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+), 48 deletions(-) delete mode 100644 src/lib/core/ripple/README.md create mode 100644 src/lib/core/ripple/ripple.md diff --git a/src/lib/core/ripple/README.md b/src/lib/core/ripple/README.md deleted file mode 100644 index 2cbcbe44a147..000000000000 --- a/src/lib/core/ripple/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# mat-ripple - -`mat-ripple` defines an area in which a ripple animates, usually in response to user action. It is used as an attribute directive, for example `
...
`. - -By default, a ripple is activated when the host element of the `mat-ripple` directive receives mouse or touch events. On a mousedown or touch start, the ripple background fades in. When the click event completes, a circular foreground ripple fades in and expands from the event location to cover the host element bounds. - -Ripples can also be triggered programmatically by getting a reference to the MatRipple directive and calling its `start` and `end` methods. - -### Global options - -Developers are able to specify options for all ripples inside of their application. - -The speed of the ripples can be adjusted and the ripples can be disabled globally as well. - -Global ripple options can be specified by setting the `MAT_RIPPLE_GLOBAL_OPTIONS` provider. - -```ts -const globalRippleConfig: RippleGlobalOptions = { - disabled: true, - baseSpeedFactor: 1.5 // Ripples will animate 50% faster than before. -} - -@NgModule({ - providers: [ - {provide: MAT_RIPPLE_GLOBAL_OPTIONS, useValue: globalRippleConfig} - ] -}) -``` - -Here are all available global options listed: - -| Name | Type | Description | -| --------------- | ------- | ----------------------------------------- | -| disabled | boolean | Whether ripples should show or not. | -| baseSpeedFactor | number | Factor to adjust ripple speed. | - -### API Summary - -Properties: - -| Name | Type | Description | -| --- | --- | --- | -| `matRippleTrigger` | Element | The DOM element that triggers the ripple when clicked. Defaults to the parent of the `mat-ripple`. -| `matRippleColor` | string | Custom color for foreground ripples -| `matRippleCentered` | boolean | If true, the ripple animation originates from the center of the `mat-ripple` bounds rather than from the location of the click event. -| `matRippleRadius` | number | Optional fixed radius of foreground ripples when fully expanded. Mainly used in conjunction with `unbounded` attribute. If not set, ripples will expand from their origin to the most distant corner of the component's bounding rectangle. -| `matRippleUnbounded` | boolean | If true, foreground ripples will be visible outside the component's bounds. -| `matRippleDisabled` | boolean | If true, click events on the trigger element will not activate ripples. The `start` and `end` methods can still be called to programmatically create ripples. diff --git a/src/lib/core/ripple/ripple.md b/src/lib/core/ripple/ripple.md new file mode 100644 index 000000000000..794f7010d05f --- /dev/null +++ b/src/lib/core/ripple/ripple.md @@ -0,0 +1,102 @@ +# matRipple + +Connect user input to screen reactions by using ripples to both indicate the point of touch, and to +confirm that touch input was received. For touch or mouse, this occurs at the point of contact. + +The `matRipple` attribute directive defines an area in which a ripple animates on user interaction. + +```html +
+ +
+``` + +By default, a ripple is activated when the host element of the `matRipple` directive receives +mouse or touch events. Once element is being pressed, a ripple starts fading in from the point +of contact and expands circularly to cover the full host element. + +As long as the user does not release the element, the ripples will not fade out. Releasing the +element, will make the present ripples fade out. + +Ripples can also be triggered programmatically by getting a reference to the MatRipple directive +and calling its `launch` method. + + +### Ripple trigger + +As mentioned previously, by default ripples will fade in on interaction with the directive's +host element. + +In some situations, developers may want to show ripples on interaction with *another* element, +but still want to have the ripples placed in another location. + +This can be done by specifying the `matRippleTrigger` option that expects a reference to a +`HTMLElement`. + +```html +
+
+ +
+ +
+
+``` + +### Manual ripples + +Ripples can be shown programmatically by getting a reference to the `MatRipple` directive. + +```ts +class MyComponent { + + /** Reference to the directive instance of the ripple. */ + @ViewChild(MatRipple) ripple: MatRipple; + + /** Shows a centered and persistent ripple. */ + launchRipple() { + const rippleRef = this.ripple.launch(0, 0, { + persistent: true, + centered: true + }); + + // Fade out the ripple later. + rippleRef.fadeOut(); + } +} +``` + +In the example above, the `x` and `y` parameters will be ignored, because the `centered` +ripple option has been set to `true`. + +Ripples that are being dispatched programmatically can be launched with the `persistent` option. +This means that the ripples will not fade out automatically, and need to be faded out using +the `RippleRef` (*useful for focus indicators*). + +### Global options + +Developers are able to specify options for all ripples inside of their application. + +The speed of the ripples can be adjusted and the ripples can be disabled globally as well. + +Global ripple options can be specified by setting the `MAT_RIPPLE_GLOBAL_OPTIONS` provider. + +```ts +const globalRippleConfig: RippleGlobalOptions = { + disabled: true, + baseSpeedFactor: 1.5 // Ripples will animate 50% faster than before. +} + +@NgModule({ + providers: [ + {provide: MAT_RIPPLE_GLOBAL_OPTIONS, useValue: globalRippleConfig} + ] +}) +``` + +All currently available global options are shown here: + +| Name | Type | Description | +| --------------- | ------- | ----------------------------------------- | +| disabled | boolean | Whether ripples should show or not. | +| baseSpeedFactor | number | Factor to adjust ripple speed. | From 6f847f7f8f1479e92ba816ce64ba3b14774da8ac Mon Sep 17 00:00:00 2001 From: Paul Gschwendtner Date: Thu, 26 Oct 2017 14:58:24 +0200 Subject: [PATCH 2/3] Address feedback --- src/lib/core/ripple/ripple.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/src/lib/core/ripple/ripple.md b/src/lib/core/ripple/ripple.md index 794f7010d05f..c22c4ec4dd64 100644 --- a/src/lib/core/ripple/ripple.md +++ b/src/lib/core/ripple/ripple.md @@ -12,11 +12,8 @@ The `matRipple` attribute directive defines an area in which a ripple animates o ``` By default, a ripple is activated when the host element of the `matRipple` directive receives -mouse or touch events. Once element is being pressed, a ripple starts fading in from the point -of contact and expands circularly to cover the full host element. - -As long as the user does not release the element, the ripples will not fade out. Releasing the -element, will make the present ripples fade out. +mouse or touch events. Upon being pressed, a ripple will begin fading in from the point of contact, +radiating to cover the host element. Each ripple will fade out only upon release of the mouse or touch. Ripples can also be triggered programmatically by getting a reference to the MatRipple directive and calling its `launch` method. @@ -24,14 +21,10 @@ and calling its `launch` method. ### Ripple trigger -As mentioned previously, by default ripples will fade in on interaction with the directive's -host element. - -In some situations, developers may want to show ripples on interaction with *another* element, -but still want to have the ripples placed in another location. - -This can be done by specifying the `matRippleTrigger` option that expects a reference to a -`HTMLElement`. +By default ripples will fade in on interaction with the directive's host element. +In some situations, developers may want to show ripples on interaction with *some other* element, +but still want to have the ripples placed in another location. This can be done by specifying +the `matRippleTrigger` option that expects a reference to an `HTMLElement`. ```html
From 5cf6b9300618d47b203c467efeb643bf2f326f2b Mon Sep 17 00:00:00 2001 From: Paul Gschwendtner Date: Thu, 26 Oct 2017 18:53:37 +0200 Subject: [PATCH 3/3] Omit matRipple header --- src/lib/core/ripple/ripple.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/lib/core/ripple/ripple.md b/src/lib/core/ripple/ripple.md index c22c4ec4dd64..9338ab4b2418 100644 --- a/src/lib/core/ripple/ripple.md +++ b/src/lib/core/ripple/ripple.md @@ -1,5 +1,3 @@ -# matRipple - Connect user input to screen reactions by using ripples to both indicate the point of touch, and to confirm that touch input was received. For touch or mouse, this occurs at the point of contact.