diff --git a/components/PageControl/.vars b/components/PageControl/.vars index abe8f5764..07e4d990c 100644 --- a/components/PageControl/.vars +++ b/components/PageControl/.vars @@ -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. diff --git a/components/PageControl/README.md b/components/PageControl/README.md index 4b430b629..b23894a55 100644 --- a/components/PageControl/README.md +++ b/components/PageControl/README.md @@ -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 --> + + # Page Control
@@ -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 -## Extensions +## Table of contents - +- [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' -``` - - -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. screenshot-1 @@ -86,13 +60,28 @@ Page control showing animated track with current page indicator positioned along Page control showing new current page. -- - - +## Installation -## Usage + + +### Installation with CocoaPods + +Add the following to your `Podfile`: + +```bash +pod 'MaterialComponents/PageControl' +``` + + +Then, run the following command: + +```bash +pod install +``` ### Importing -Before using Page Control, you'll need to import it: +To import the component: #### Swift @@ -107,10 +96,17 @@ import MaterialComponents.MaterialPageControl ``` + +## Usage + + + +### 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){ ``` -### 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) { } ``` + + + +### 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 + + + +### 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) + diff --git a/components/PageControl/docs/README.md b/components/PageControl/docs/README.md new file mode 100644 index 000000000..a8d42d9d9 --- /dev/null +++ b/components/PageControl/docs/README.md @@ -0,0 +1,50 @@ +# Page Control + +
+ Page Control +
+ +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) + + + +- - - + +## 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. + +screenshot-1 + +Page control showing current page in resting state. + +screenshot-2 + +Page control showing animated track with current page indicator positioned along the track. + +screenshot-3 + +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) diff --git a/components/PageControl/docs/color-theming.md b/components/PageControl/docs/color-theming.md index 38b1e1abe..f581e950e 100644 --- a/components/PageControl/docs/color-theming.md +++ b/components/PageControl/docs/color-theming.md @@ -1,12 +1,4 @@ - - -# 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: diff --git a/components/PageControl/docs/differences-from-uipagecontrol.md b/components/PageControl/docs/differences-from-uipagecontrol.md new file mode 100644 index 000000000..0c403d03e --- /dev/null +++ b/components/PageControl/docs/differences-from-uipagecontrol.md @@ -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. diff --git a/components/PageControl/docs/typical-use.md b/components/PageControl/docs/typical-use.md new file mode 100644 index 000000000..3c84d5f7f --- /dev/null +++ b/components/PageControl/docs/typical-use.md @@ -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. + + +#### 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]; +} +``` + + +**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. + + +#### 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]; +} +``` +