mirror of
https://github.com/material-components/material-components-ios.git
synced 2026-02-05 12:08:21 +08:00
[PageControl] Split the documentation into separate articles and run the readme generator. (#3624)
This commit is contained in:
featherless
GitHub
parent
7ebaeb51be
commit
ec4ec5fa2a
@ -3,3 +3,4 @@ component_name=Page Control
|
||||
a_component_name=a page control
|
||||
root_path=/catalog/page-controls
|
||||
color_themer_api=MDCPageControlColorThemer
|
||||
short_description=Page Control is a drop-in Material Design replacement for UIPageControl that implements Material Design animation and layout.
|
||||
|
||||
@ -3,10 +3,13 @@ title: "Page Control"
|
||||
layout: detail
|
||||
section: components
|
||||
excerpt: "Page Control is a drop-in Material Design replacement for UIPageControl that implements Material Design animation and layout."
|
||||
iconId: <#icon_id#>
|
||||
path: /catalog/page-controls/
|
||||
api_doc_root: true
|
||||
-->
|
||||
|
||||
<!-- This file was auto-generated using ./scripts/generate_readme PageControl -->
|
||||
|
||||
# Page Control
|
||||
|
||||
<div class="article__asset article__asset--screenshot">
|
||||
@ -18,60 +21,31 @@ influenced by Material Design specifications for animation and layout. The API m
|
||||
same as a `UIPageControl`, with the addition of a few key methods required to achieve the
|
||||
desired animation of the control.
|
||||
|
||||
## Design & API Documentation
|
||||
## Design & API documentation
|
||||
|
||||
<ul class="icon-list">
|
||||
<li class="icon-list-item icon-list-item--link"><a href="https://material.io/components/ios/catalog/page-controls/api-docs/Classes/MDCPageControl.html">API: MDCPageControl</a></li>
|
||||
</ul>
|
||||
|
||||
## Extensions
|
||||
## Table of contents
|
||||
|
||||
<ul class="icon-list">
|
||||
<li class="icon-list-item icon-list-item--link"><a href="docs/color-theming.md">Color Theming</a></li>
|
||||
</ul>
|
||||
- [Overview](#overview)
|
||||
- [Installation](#installation)
|
||||
- [Installation with CocoaPods](#installation-with-cocoapods)
|
||||
- [Importing](#importing)
|
||||
- [Usage](#usage)
|
||||
- [Typical use](#typical-use)
|
||||
- [Differences From UIPageControl](#differences-from-uipagecontrol)
|
||||
- [Extensions](#extensions)
|
||||
- [Color Theming](#color-theming)
|
||||
|
||||
- - -
|
||||
|
||||
## Installation
|
||||
|
||||
### Installation with CocoaPods
|
||||
|
||||
To add this component to your Xcode project using CocoaPods, add the following to your `Podfile`:
|
||||
|
||||
```bash
|
||||
pod 'MaterialComponents/PageControl'
|
||||
```
|
||||
<!--{: .code-renderer.code-renderer--install }-->
|
||||
|
||||
To add this component along with its themer and other related extensions, please add the following instead:
|
||||
```bash
|
||||
pod 'MaterialComponents/PageControl+Extensions'
|
||||
```
|
||||
|
||||
Then, run the following command:
|
||||
|
||||
```bash
|
||||
pod install
|
||||
```
|
||||
|
||||
|
||||
- - -
|
||||
|
||||
## Differences From UIPageControl
|
||||
|
||||
This page control provides an animation effect that keeps a page indicator in sync with the
|
||||
scrolling of a designated scroll view. This is in contrast to a native `UIPageControl`, which
|
||||
shows the current page indicator without any animated transitions between changes.
|
||||
|
||||
As the user scrolls, a track will be drawn with animation from the current indicator position
|
||||
towards the next indicator position that is being scrolled towards. The current indicator will
|
||||
float along this track and position itself based on the percent scrolled between the pages.
|
||||
When the scroll view finishes scrolling, the track will disappear with animation towards the
|
||||
final position of the new page.
|
||||
|
||||
|
||||
#### Example Screenshots
|
||||
## Overview
|
||||
|
||||
`MDCActivityIndicator` is a view that has two modes: indeterminate and determinate. Indeterminate
|
||||
indicators express an unspecified wait time, while determinate indicators represent the length of a
|
||||
process. Activity indicators are indeterminate by default.
|
||||
|
||||
<img src="docs/assets/MDCPageControl_screenshot-1.png" alt="screenshot-1" width="375">
|
||||
<!--{: .article__asset.article__asset--screenshot }-->
|
||||
@ -86,13 +60,28 @@ Page control showing animated track with current page indicator positioned along
|
||||
Page control showing new current page.
|
||||
|
||||
|
||||
- - -
|
||||
## Installation
|
||||
|
||||
## Usage
|
||||
<!-- Extracted from docs/../../../docs/component-installation.md -->
|
||||
|
||||
### Installation with CocoaPods
|
||||
|
||||
Add the following to your `Podfile`:
|
||||
|
||||
```bash
|
||||
pod 'MaterialComponents/PageControl'
|
||||
```
|
||||
<!--{: .code-renderer.code-renderer--install }-->
|
||||
|
||||
Then, run the following command:
|
||||
|
||||
```bash
|
||||
pod install
|
||||
```
|
||||
|
||||
### Importing
|
||||
|
||||
Before using Page Control, you'll need to import it:
|
||||
To import the component:
|
||||
|
||||
<!--<div class="material-code-render" markdown="1">-->
|
||||
#### Swift
|
||||
@ -107,10 +96,17 @@ import MaterialComponents.MaterialPageControl
|
||||
```
|
||||
<!--</div>-->
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
<!-- Extracted from docs/typical-use.md -->
|
||||
|
||||
### Typical use
|
||||
|
||||
Integrating the page control requires two steps. First, add a page control with companion scroll
|
||||
view, and second, forward the scroll view delegate methods to the page control.
|
||||
|
||||
### Step 1: Add the page control to a view
|
||||
**Step 1: Add the page control to a view**
|
||||
|
||||
Add the page control to a view and set the desired page control properties. This step is done
|
||||
similarly to a native `UIPageControl`. In addition, provide a tap gesture handler for the control to
|
||||
@ -176,7 +172,7 @@ func didChangePage(sender: MDCPageControl){
|
||||
```
|
||||
<!--</div>-->
|
||||
|
||||
### Step 2: Forwarding the required scroll view delegate methods
|
||||
**Step 2: Forwarding the required scroll view delegate methods**
|
||||
|
||||
This page control is designed to be used in conjunction with a scroll view. To achieve the desired
|
||||
page control animation effects, there are three scroll view delegate methods that must be forwarded
|
||||
@ -217,3 +213,30 @@ func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) {
|
||||
}
|
||||
```
|
||||
<!--</div>-->
|
||||
|
||||
<!-- Extracted from docs/differences-from-uipagecontrol.md -->
|
||||
|
||||
### Differences From UIPageControl
|
||||
|
||||
This page control provides an animation effect that keeps a page indicator in sync with the
|
||||
scrolling of a designated scroll view. This is in contrast to a native `UIPageControl`, which
|
||||
shows the current page indicator without any animated transitions between changes.
|
||||
|
||||
As the user scrolls, a track will be drawn with animation from the current indicator position
|
||||
towards the next indicator position that is being scrolled towards. The current indicator will
|
||||
float along this track and position itself based on the percent scrolled between the pages.
|
||||
When the scroll view finishes scrolling, the track will disappear with animation towards the
|
||||
final position of the new page.
|
||||
|
||||
|
||||
## Extensions
|
||||
|
||||
<!-- Extracted from docs/color-theming.md -->
|
||||
|
||||
### Color Theming
|
||||
|
||||
Page Control does not yet have a Material Design color system themer. The following tasks are
|
||||
tracking its development:
|
||||
|
||||
- Task: [Implement a color themer](https://www.pivotaltracker.com/story/show/157072365)
|
||||
|
||||
|
||||
50
components/PageControl/docs/README.md
Normal file
50
components/PageControl/docs/README.md
Normal file
@ -0,0 +1,50 @@
|
||||
# Page Control
|
||||
|
||||
<div class="article__asset article__asset--screenshot">
|
||||
<img src="docs/assets/page_control.png" alt="Page Control" width="375">
|
||||
</div>
|
||||
|
||||
This control is designed to be a drop-in replacement for `UIPageControl`, with a user experience
|
||||
influenced by Material Design specifications for animation and layout. The API methods are the
|
||||
same as a `UIPageControl`, with the addition of a few key methods required to achieve the
|
||||
desired animation of the control.
|
||||
|
||||
## Design & API documentation
|
||||
|
||||
* [API: MDCPageControl](https://material.io/components/ios/catalog/page-controls/api-docs/Classes/MDCPageControl.html)
|
||||
|
||||
<!-- toc -->
|
||||
|
||||
- - -
|
||||
|
||||
## Overview
|
||||
|
||||
`MDCActivityIndicator` is a view that has two modes: indeterminate and determinate. Indeterminate
|
||||
indicators express an unspecified wait time, while determinate indicators represent the length of a
|
||||
process. Activity indicators are indeterminate by default.
|
||||
|
||||
<img src="docs/assets/MDCPageControl_screenshot-1.png" alt="screenshot-1" width="375">
|
||||
<!--{: .article__asset.article__asset--screenshot }-->
|
||||
Page control showing current page in resting state.
|
||||
|
||||
<img src="docs/assets/MDCPageControl_screenshot-2.png" alt="screenshot-2" width="375">
|
||||
<!--{: .article__asset.article__asset--screenshot }-->
|
||||
Page control showing animated track with current page indicator positioned along the track.
|
||||
|
||||
<img src="docs/assets/MDCPageControl_screenshot-3.png" alt="screenshot-3" width="375">
|
||||
<!--{: .article__asset.article__asset--screenshot }-->
|
||||
Page control showing new current page.
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
- [Typical installation](../../../docs/component-installation.md)
|
||||
|
||||
## Usage
|
||||
|
||||
- [Typical use](typical-use.md)
|
||||
- [Differences from UIPageControl](differences-from-uipagecontrol.md)
|
||||
|
||||
## Extensions
|
||||
|
||||
- [Color Theming](color-theming.md)
|
||||
@ -1,12 +1,4 @@
|
||||
<!--docs:
|
||||
title: "Color Theming"
|
||||
layout: detail
|
||||
section: components
|
||||
excerpt: "How to theme Page Control using the Material Design color system."
|
||||
path: /catalog/page-controls/color-theming/
|
||||
-->
|
||||
|
||||
# Page Control Color Theming
|
||||
### Color Theming
|
||||
|
||||
Page Control does not yet have a Material Design color system themer. The following tasks are
|
||||
tracking its development:
|
||||
|
||||
@ -0,0 +1,11 @@
|
||||
### Differences From UIPageControl
|
||||
|
||||
This page control provides an animation effect that keeps a page indicator in sync with the
|
||||
scrolling of a designated scroll view. This is in contrast to a native `UIPageControl`, which
|
||||
shows the current page indicator without any animated transitions between changes.
|
||||
|
||||
As the user scrolls, a track will be drawn with animation from the current indicator position
|
||||
towards the next indicator position that is being scrolled towards. The current indicator will
|
||||
float along this track and position itself based on the percent scrolled between the pages.
|
||||
When the scroll view finishes scrolling, the track will disappear with animation towards the
|
||||
final position of the new page.
|
||||
112
components/PageControl/docs/typical-use.md
Normal file
112
components/PageControl/docs/typical-use.md
Normal file
@ -0,0 +1,112 @@
|
||||
### Typical use
|
||||
|
||||
Integrating the page control requires two steps. First, add a page control with companion scroll
|
||||
view, and second, forward the scroll view delegate methods to the page control.
|
||||
|
||||
**Step 1: Add the page control to a view**
|
||||
|
||||
Add the page control to a view and set the desired page control properties. This step is done
|
||||
similarly to a native `UIPageControl`. In addition, provide a tap gesture handler for the control to
|
||||
to fire off the `UIControlEventValueChanged` events in which the scroll view would typically be
|
||||
notified of page changes.
|
||||
|
||||
<!--<div class="material-code-render" markdown="1">-->
|
||||
#### Swift
|
||||
|
||||
```swift
|
||||
let pageControl = MDCPageControl()
|
||||
let scrollView = UIScrollView()
|
||||
let pages = NSMutableArray()
|
||||
|
||||
override func viewDidLoad() {
|
||||
super.viewDidLoad()
|
||||
|
||||
scrollView.delegate = self
|
||||
view.addSubview(scrollView)
|
||||
|
||||
pageControl.numberOfPages = 3
|
||||
|
||||
let pageControlSize = pageControl.sizeThatFits(view.bounds.size)
|
||||
pageControl.frame = CGRect(x: 0, y: view.bounds.height - pageControlSize.height, width: view.bounds.width, height: pageControlSize.height)
|
||||
|
||||
pageControl.addTarget(self, action: #selector(didChangePage), for: .valueChanged)
|
||||
pageControl.autoresizingMask = [.flexibleTopMargin, .flexibleWidth]
|
||||
view.addSubview(pageControl)
|
||||
}
|
||||
|
||||
func didChangePage(sender: MDCPageControl){
|
||||
var offset = scrollView.contentOffset
|
||||
offset.x = CGFloat(sender.currentPage) * scrollView.bounds.size.width;
|
||||
scrollView.setContentOffset(offset, animated: true)
|
||||
}
|
||||
```
|
||||
|
||||
#### Objective-C
|
||||
|
||||
```objc
|
||||
- (void)viewDidLoad {
|
||||
[super viewDidLoad];
|
||||
|
||||
self.scrollView.delegate = self;
|
||||
[self.view addSubview:self.scrollView];
|
||||
|
||||
self.pageControl.numberOfPages = 3;
|
||||
|
||||
CGSize pageControlSize = [self.pageControl sizeThatFits:self.view.bounds.size];
|
||||
self.pageControl.frame = CGRectMake(0, self.view.bounds.size.height - pageControlSize.height, self.view.bounds.size.width, pageControlSize.height);
|
||||
|
||||
[self.pageControl addTarget:self action:@selector(didChangePage:) forControlEvents: UIControlEventValueChanged];
|
||||
self.pageControl.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleTopMargin;
|
||||
[self.view addSubview:self.pageControl];
|
||||
|
||||
}
|
||||
|
||||
- (void)didChangePage:(MDCPageControl*)sender {
|
||||
CGPoint offset = self.scrollView.contentOffset;
|
||||
offset.x = (CGFloat)sender.currentPage * self.scrollView.bounds.size.width;
|
||||
[self.scrollView setContentOffset:offset animated: true];
|
||||
}
|
||||
```
|
||||
<!--</div>-->
|
||||
|
||||
**Step 2: Forwarding the required scroll view delegate methods**
|
||||
|
||||
This page control is designed to be used in conjunction with a scroll view. To achieve the desired
|
||||
page control animation effects, there are three scroll view delegate methods that must be forwarded
|
||||
to the page control (`-scrollViewDidScroll`, `-scrollViewDidEndDecelerating`, and
|
||||
`-scrollViewDidEndScrollingAnimation`). This allows the page control to keep in sync with the
|
||||
scrolling movement of the designated scroll view.
|
||||
|
||||
<!--<div class="material-code-render" markdown="1">-->
|
||||
#### Swift
|
||||
|
||||
```swift
|
||||
func scrollViewDidScroll(_ scrollView: UIScrollView) {
|
||||
pageControl.scrollViewDidScroll(scrollView)
|
||||
}
|
||||
|
||||
func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
|
||||
pageControl.scrollViewDidEndDecelerating(scrollView)
|
||||
}
|
||||
|
||||
func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) {
|
||||
pageControl.scrollViewDidEndScrollingAnimation(scrollView)
|
||||
}
|
||||
```
|
||||
|
||||
#### Objective-C
|
||||
|
||||
```objc
|
||||
- (void)scrollViewDidScroll:(UIScrollView *)scrollView {
|
||||
[self.pageControl scrollViewDidScroll:scrollView];
|
||||
}
|
||||
|
||||
- (void)scrollViewDidEndDecelerating:(UIScrollView *)scrollView {
|
||||
[self.pageControl scrollViewDidEndDecelerating:scrollView];
|
||||
}
|
||||
|
||||
- (void)scrollViewDidEndScrollingAnimation:(UIScrollView *)scrollView {
|
||||
[self.pageControl scrollViewDidEndScrollingAnimation:scrollView];
|
||||
}
|
||||
```
|
||||
<!--</div>-->
|
||||
Loading…
x
Reference in New Issue
Block a user