Skip to content

Commit 89cd08d

Browse files
yarneoyarneo
authored
[Ink] Update Readme to use the script generator and move migration guide. (#7370)
Ink readme wasn't using the script generator and ready templates we already use in our other components. This fixes that and moves the migration guide from Ripple to Ink.
1 parent 3c46c3e commit 89cd08d

File tree

7 files changed

+283
-104
lines changed

7 files changed

+283
-104
lines changed

‎components/Ink/.vars

+1
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@ component_name=Ink
33
a_component_name=ink
44
root_path=/catalog/ink
55
icon_id=ripple
6+
short_description=The Ink component provides a radial action in the form of a visual ripple expanding outward from the user's touch.

‎components/Ink/README.md

+124-13
Original file line numberDiff line numberDiff line change
@@ -8,29 +8,54 @@ path: /catalog/ink/
88
api_doc_root: true
99
-->
1010

11+
<!-- This file was auto-generated using scripts/generate_readme Ink -->
12+
1113
# Ink
1214

15+
[![Open bugs badge](https://img.shields.io/badge/dynamic/json.svg?label=open%20bugs&url=https%3A%2F%2Fapi.github.com%2Fsearch%2Fissues%3Fq%3Dis%253Aopen%2Blabel%253Atype%253ABug%2Blabel%253A%255BInk%255D&query=%24.total_count)](https://github.com/material-components/material-components-ios/issues?q=is%3Aopen+is%3Aissue+label%3Atype%3ABug+label%3A%5BInk%5D)
16+
1317
The Ink component provides a radial action in the form of a visual ripple expanding outward from
1418
the user's touch.
1519

1620
<img src="docs/assets/ink.gif" alt="An animation showing a Material ink ripple on multiple surfaces." width="210">
1721

18-
## Design & API Documentation
22+
## Design & API documentation
1923

2024
<ul class="icon-list">
21-
<li class="icon-list-item icon-list-item--spec"><a href="https://material.io/guidelines/animation/responsive-interaction.html#responsive-interaction-radial-action">Material Design guidelines: Radial Action</a></li>
22-
<li class="icon-list-item icon-list-item--link"><a href="https://material.io/components/ios/catalog/ink/api-docs/Classes/MDCInkGestureRecognizer.html">API: MDCInkGestureRecognizer</a></li>
23-
<li class="icon-list-item icon-list-item--link"><a href="https://material.io/components/ios/catalog/ink/api-docs/Classes/MDCInkTouchController.html">API: MDCInkTouchController</a></li>
24-
<li class="icon-list-item icon-list-item--link"><a href="https://material.io/components/ios/catalog/ink/api-docs/Classes/MDCInkView.html">API: MDCInkView</a></li>
25+
<li class="icon-list-item icon-list-item--link">Class: <a href="https://material.io/components/ios/catalog/ink/api-docs/Classes/MDCInkGestureRecognizer.html">MDCInkGestureRecognizer</a></li>
26+
<li class="icon-list-item icon-list-item--link">Class: <a href="https://material.io/components/ios/catalog/ink/api-docs/Classes/MDCInkTouchController.html">MDCInkTouchController</a></li>
27+
<li class="icon-list-item icon-list-item--link">Class: <a href="https://material.io/components/ios/catalog/ink/api-docs/Classes/MDCInkView.html">MDCInkView</a></li>
28+
<li class="icon-list-item icon-list-item--link">Protocol: <a href="https://material.io/components/ios/catalog/ink/api-docs/Protocols/MDCInkTouchControllerDelegate.html">MDCInkTouchControllerDelegate</a></li>
29+
<li class="icon-list-item icon-list-item--link">Protocol: <a href="https://material.io/components/ios/catalog/ink/api-docs/Protocols/MDCInkViewDelegate.html">MDCInkViewDelegate</a></li>
30+
<li class="icon-list-item icon-list-item--link">Enumeration: <a href="https://material.io/components/ios/catalog/ink/api-docs/Enums.html">Enumerations</a></li>
31+
<li class="icon-list-item icon-list-item--link">Enumeration: <a href="https://material.io/components/ios/catalog/ink/api-docs/Enums/MDCInkStyle.html">MDCInkStyle</a></li>
2532
</ul>
2633

34+
## Table of contents
35+
36+
- [Overview](#overview)
37+
- [Installation](#installation)
38+
- [Installation with CocoaPods](#installation-with-cocoapods)
39+
- [Importing](#importing)
40+
- [Usage](#usage)
41+
- [MDCInkTouchController](#mdcinktouchcontroller)
42+
- [MDCInkView](#mdcinkview)
43+
- [Migration guides](#migration-guides)
44+
- [Migration guide: Ink to Ripple](#migration-guide-ink-to-ripple)
45+
2746
- - -
2847

48+
## Overview
49+
50+
Ink is a material design implementation of touch feedback.
51+
2952
## Installation
3053

54+
<!-- Extracted from docs/../../../docs/component-installation.md -->
55+
3156
### Installation with CocoaPods
3257

33-
To add this component to your Xcode project using CocoaPods, add the following to your `Podfile`:
58+
Add the following to your `Podfile`:
3459

3560
```bash
3661
pod 'MaterialComponents/Ink'
@@ -43,19 +68,14 @@ Then, run the following command:
4368
pod install
4469
```
4570

46-
47-
- - -
48-
49-
## Usage
50-
5171
### Importing
5272

53-
Before using Ink, you'll need to import it:
73+
To import the component:
5474

5575
<!--<div class="material-code-render" markdown="1">-->
5676
#### Swift
5777
```swift
58-
import MaterialComponents
78+
import MaterialComponents.MaterialInk
5979
```
6080

6181
#### Objective-C
@@ -65,6 +85,11 @@ import MaterialComponents
6585
```
6686
<!--</div>-->
6787

88+
89+
## Usage
90+
91+
<!-- Extracted from docs/typical-use.md -->
92+
6893
The Ink component exposes two interfaces that you can use to add material-like
6994
feedback to the user:
7095

@@ -193,3 +218,89 @@ inkView.inkColor = [UIColor redColor];
193218
[inkView startTouchEndedAnimationAtPoint:touchPoint completion:nil];
194219
```
195220
<!--</div>-->
221+
222+
223+
## Migration guides
224+
225+
<!-- Extracted from docs/migration-guide-ink-to-ripple.md -->
226+
227+
### Migration guide: Ink to Ripple
228+
229+
Ink and Ripple provide similar APIs: a view (`MDCInkView`, `MDCRippleView`), and a touch controller (`MDCInkTouchController`, `MDCRippleTouchController`).
230+
231+
While Ripple and Ink’s implementations slightly vary, the public APIs are nearly identical. Furthermore, Ripple’s API does not produce additional side effects and can be used interchangeably.
232+
233+
These two notions make the migration path from Ink to Ripple relatively simple.
234+
235+
For guidance, these are the current naming differences that you need to pay attention to when migrating:
236+
237+
**`MDCInkView` vs `MDCRippleView`:**
238+
239+
|`MDCInkView`|`MDCRippleView`|
240+
|---|---|
241+
|`animationDelegate`|`rippleViewDelegate`|
242+
|`maxRippleRadius`|`maximumRadius`|
243+
|`startTouchBeganAtPoint:animated:completion:`|`beginRippleTouchDownAtPoint:animated:completion:`|
244+
|`startTouchEndAtPoint:animated:completion:`|`beginRippleTouchUpAnimated:completion:`|
245+
|`inkAnimationDidStart:inkView`|`rippleTouchDownAnimationDidBegin:rippleView`|
246+
|`inkAnimationDidEnd:inkView`|`rippleTouchUpAnimationDidEnd:rippleView`|
247+
|`inkStyle`|`rippleStyle`|
248+
|`inkColor`|`rippleColor`|
249+
|`cancelAllAnimationsAnimated:`|`cancelAllRipplesAnimated:completion:`|
250+
251+
**`MDCInkTouchController` vs `MDCRippleTouchController`:**
252+
253+
|`MDCInkTouchController`|`MDCRippleTouchController`|
254+
|---|---|
255+
|`defaultInkView`|`rippleView`|
256+
|`initWithView:` → `addInkView`|`init` → `addRippleToView:`\*|
257+
|`view`|`view`|
258+
|`delegate`|`delegate`|
259+
|`gestureRecognizer`|`gestureRecognizer`|
260+
|`inkTouchController:insertInkView:intoView:`|`rippleTouchController:insertRippleView:intoView:`|
261+
|`inkTouchController:shouldProcessInkTouchesAtTouchLocation:`|`rippleTouchController:shouldProcessRippleTouchesAtTouchLocation:`|
262+
|`inkTouchController:didProcessInkTouchesAtTouchLocation:`|`rippleTouchController:didProcessRippleTouchesAtTouchLocation:`|
263+
264+
*\*Ripple provides a more convenient API if the ink's initialized view is the view that the ink is then added to. All you need is to initialize the ripple with `initWithView:` and there is no need to use an equivalent `addInkView` afterwards.*
265+
266+
**Based on the above guidance, the overall strategy to migrate Ink to Ripple in each component is as follows:**
267+
268+
<ul class="icon-list">
269+
<li class="icon-list-item icon-list-item">Provide an enableRippleBehavior bool property to allow to opt-in to use Ripple instead of Ink (where the default to this property is NO).</li>
270+
</ul>
271+
272+
Component Header:
273+
```objc
274+
/*
275+
This property determines if an @c <#INSERT CLASS NAME> should use the @c MDCRippleView behavior or not.
276+
By setting this property to @c YES, @c MDCRippleView is used to provide the user visual
277+
touch feedback, instead of the legacy @c MDCInkView.
278+
@note Defaults to @c NO.
279+
*/
280+
@property(nonatomic, assign) BOOL enableRippleBehavior;
281+
```
282+
283+
Component Implementation Setter:
284+
```objc
285+
- (void)setEnableRippleBehavior:(BOOL)enableRippleBehavior {
286+
_enableRippleBehavior = enableRippleBehavior;
287+
288+
if (enableRippleBehavior) {
289+
[self.inkView removeFromSuperview];
290+
self.rippleView.frame = self.bounds;
291+
[self insertSubview:self.rippleView belowSubview:X];
292+
} else {
293+
[self.rippleView removeFromSuperview];
294+
[self insertSubview:self.inkView belowSubview:X];
295+
}
296+
}
297+
```
298+
299+
<ul class="icon-list">
300+
<li class="icon-list-item icon-list-item">Add the RippleView/RippleTouchController APIs beside their InkView/InkTouchController counterparts.</li>
301+
</ul>
302+
303+
<ul class="icon-list">
304+
<li class="icon-list-item icon-list-item">If the component itself has public APIs that use the term "Ink" like “InkStyle” or “InkColor”, the developer should add APIs to use the term “Ripple” instead. When Ink will eventually be deprecated, these APIs will be deprecated as part of that process. Another option instead of exposing specific Ripple APIs is to expose the `MDCRippleView` property in the public API.</li>
305+
</ul>
306+

‎components/Ink/docs/README.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Ink
2+
3+
<!-- badges -->
4+
5+
The Ink component provides a radial action in the form of a visual ripple expanding outward from
6+
the user's touch.
7+
8+
<img src="docs/assets/ink.gif" alt="An animation showing a Material ink ripple on multiple surfaces." width="210">
9+
10+
<!-- design-and-api -->
11+
12+
<!-- toc -->
13+
14+
- - -
15+
16+
## Overview
17+
18+
Ink is a material design implementation of touch feedback.
19+
20+
## Installation
21+
22+
- [Typical installation](../../../docs/component-installation.md)
23+
24+
## Usage
25+
26+
- [Typical use](typical-use.md)
27+
28+
## Migration guides
29+
30+
- [Migration guide: Ink to Ripple](migration-guide-ink-to-ripple.md)

‎components/Ripple/docs/migration-guide-ink-to-ripple.md renamed to ‎components/Ink/docs/migration-guide-ink-to-ripple.md

File renamed without changes.

‎components/Ink/docs/typical-use.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
The Ink component exposes two interfaces that you can use to add material-like
2+
feedback to the user:
3+
4+
1. `MDCInkView` is a subclass of `UIView` that draws and animates ink ripples
5+
and can be placed anywhere in your view hierarchy.
6+
2. `MDCInkTouchController` bundles an `MDCInkView` instance with a
7+
`UITapGestureRecognizer` instance to conveniently drive the ink ripples from the
8+
user's touches.
9+
10+
### MDCInkTouchController
11+
12+
The simplest method of using ink in your views is to use a
13+
`MDCInkTouchController`:
14+
15+
<!--<div class="material-code-render" markdown="1">-->
16+
#### Swift
17+
```swift
18+
let myButton = UIButton(type: .system)
19+
myButton.setTitle("Tap Me", for: .normal)
20+
let inkTouchController = MDCInkTouchController(view: myButton)
21+
inkTouchController.addInkView()
22+
```
23+
24+
#### Objective-C
25+
```objc
26+
UIButton *myButton = [UIButton buttonWithType:UIButtonTypeSystem];
27+
[myButton setTitle:@"Tap me" forState:UIControlStateNormal];
28+
MDCInkTouchController *inkTouchController = [[MDCInkTouchController alloc] initWithView:myButton];
29+
[inkTouchController addInkView];
30+
```
31+
<!--</div>-->
32+
33+
34+
35+
The `MDCInkTouchControllerDelegate` gives you control over aspects of the
36+
ink/touch relationship, such as how the ink view is created, where it is
37+
inserted in view hierarchy, etc. For example, to temporarily disable ink
38+
touches, the following code uses the delegate's
39+
`inkTouchController:shouldProcessInkTouchesAtTouchLocation:` method:
40+
41+
<!--<div class="material-code-render" markdown="1">-->
42+
43+
#### Swift
44+
```swift
45+
class MyDelegate: NSObject, MDCInkTouchControllerDelegate {
46+
47+
func inkTouchController(_ inkTouchController: MDCInkTouchController, shouldProcessInkTouchesAtTouchLocation location: CGPoint) -> Bool {
48+
// Determine if we want to display the ink
49+
return true
50+
}
51+
52+
}
53+
54+
...
55+
56+
let myButton = UIButton(type: .system)
57+
myButton.setTitle("Tap Me", for: .normal)
58+
59+
let myDelegate = MyDelegate()
60+
61+
let inkTouchController = MDCInkTouchController(view: myButton)
62+
inkTouchController.delegate = myDelegate
63+
inkTouchController.addInkView()
64+
65+
```
66+
67+
#### Objective-C
68+
```objc
69+
@interface MyDelegate: NSObject <MDCInkTouchControllerDelegate>
70+
@end
71+
72+
@implementation MyDelegate
73+
74+
- (BOOL)inkTouchController:(MDCInkTouchController *)inkTouchController
75+
shouldProcessInkTouchesAtTouchLocation:(CGPoint)location {
76+
return YES;
77+
}
78+
79+
@end
80+
81+
...
82+
83+
UIButton *myButton = [UIButton buttonWithType:UIButtonTypeSystem];
84+
[myButton setTitle:@"Tap me" forState:UIControlStateNormal];
85+
MyDelegate *myDelegate = [[MyDelegate alloc] init];
86+
MDCInkTouchController *inkTouchController = [[MDCInkTouchController alloc] initWithView:myButton];
87+
inkTouchController.delegate = myDelegate;
88+
[inkTouchController addInkView];
89+
```
90+
<!--</div>-->
91+
92+
**NOTE:** The ink touch controller does not keep a strong reference to the view to which it is attaching the ink view.
93+
An easy way to prevent the ink touch controller from being deallocated prematurely is to make it a property of a view controller (like in these examples.)
94+
95+
### MDCInkView
96+
97+
Alternatively, you can use MCDInkView directly to display ink ripples using your
98+
own touch processing:
99+
100+
<!--<div class="material-code-render" markdown="1">-->
101+
#### Swift
102+
```swift
103+
let myCustomView = MyCustomView(frame: CGRect.zero)
104+
let inkView = MDCInkView()
105+
inkView.inkColor = UIColor.red
106+
myCustomView.addSubview(inkView)
107+
...
108+
// When the touches begin, there is one animation
109+
inkView.startTouchBeganAnimation(at: touchPoint, completion: nil)
110+
...
111+
// When the touches end, there is another animation
112+
inkView.startTouchEndedAnimation(at: touchPoint, completion: nil)
113+
```
114+
115+
#### Objective-C
116+
```objc
117+
MyCustomView *myCustomView = [[MyCustomView alloc] initWithFrame:CGRectZero];
118+
MDCInkView *inkView = [[MDCInkView alloc] init];
119+
inkView.inkColor = [UIColor redColor];
120+
[myCustomView addSubview:inkView];
121+
...
122+
// When the touches begin, there is one animation
123+
[inkView startTouchBeganAnimationAtPoint:touchPoint completion:nil];
124+
...
125+
// When the touches end, there is another animation
126+
[inkView startTouchEndedAnimationAtPoint:touchPoint completion:nil];
127+
```
128+
<!--</div>-->

0 commit comments

Comments
 (0)