From 854e234091ab2391d3cc7a3f5e6b7780535bfaaa Mon Sep 17 00:00:00 2001 From: featherless Date: Tue, 1 May 2018 20:48:54 -0400 Subject: [PATCH] [Slider] Split the documentation into separate articles and run the readme generator. (#3626) --- components/Slider/.vars | 1 + components/Slider/README.md | 96 ++++++++++++++----- components/Slider/docs/README.md | 31 ++++++ components/Slider/docs/color-theming.md | 13 +-- .../Slider/docs/differences-from-uislider.md | 17 ++++ components/Slider/docs/stateful-apis.md | 25 +++++ components/Slider/docs/typical-use.md | 39 ++++++++ 7 files changed, 188 insertions(+), 34 deletions(-) create mode 100644 components/Slider/docs/README.md create mode 100644 components/Slider/docs/differences-from-uislider.md create mode 100644 components/Slider/docs/stateful-apis.md create mode 100644 components/Slider/docs/typical-use.md diff --git a/components/Slider/.vars b/components/Slider/.vars index 91a61cb85b9..220869c21a6 100644 --- a/components/Slider/.vars +++ b/components/Slider/.vars @@ -5,3 +5,4 @@ root_path=/catalog/sliders icon_id=slider color_themer_api=MDCSliderColorThemer themer_parameter_name=slider +short_description=The Slider component provides a Material Design control for selecting a value from a continuous range or discrete set of values. diff --git a/components/Slider/README.md b/components/Slider/README.md index a05fb10cb47..f7e3192a4e1 100644 --- a/components/Slider/README.md +++ b/components/Slider/README.md @@ -1,5 +1,5 @@ + + # Slider
@@ -17,52 +19,49 @@ api_doc_root: true The `MDCSlider` object is a Material Design control used to select a value from a continuous range or discrete set of values. -## Design & API Documentation +## Design & API documentation -## Extensions +## Table of contents - +- [Installation](#installation) + - [Installation with CocoaPods](#installation-with-cocoapods) + - [Importing](#importing) +- [Usage](#usage) + - [Typical use](#typical-use) + - [Stateful APIs](#stateful-apis) + - [Differences from UISlider](#differences-from-uislider) +- [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`: +Add the following to your `Podfile`: ```bash pod 'MaterialComponents/Slider' ``` -To add this component along with its themer and other related extensions, please add the following instead: -```bash -pod 'MaterialComponents/Slider+Extensions' -``` - Then, run the following command: ```bash pod install ``` - -- - - - - -## Usage - ### Importing -Before using Slider, you'll need to import it: +To import the component: #### Swift @@ -77,7 +76,12 @@ import MaterialComponents.MaterialSlider ``` -### Standard usage + +## Usage + + + +### Typical use MDCSlider can be be used like a standard `UIControl`. @@ -117,7 +121,9 @@ func didChangeSliderValue(senderSlider:MDCSlider) { ``` -### Stateful API + + +### Stateful APIs `MDCSlider` exposes stateful APIs to customize the colors for different control states. In order to use this API you must enable `statefulAPIEnabled` on your `MDCSlider` instances. @@ -143,7 +149,9 @@ func didChangeSliderValue(senderSlider:MDCSlider) { ``` -### The differences between the UISlider class and the MDCSlider class: + + +### Differences from UISlider Does not have api to: @@ -160,3 +168,47 @@ Same features: New features: - making the slider a snap to discrete values via property numberOfDiscreteValues + + +## Extensions + + + +### Color Theming + +You can theme a slider with your app's color scheme using the ColorThemer extension. + +You must first add the Color Themer extension to your project: + +```bash +pod 'MaterialComponents/Slider+Extensions/ColorThemer' +``` + + +#### Swift +```swift +// Step 1: Import the ColorThemer extension +import MaterialComponents.MaterialSlider_ColorThemer + +// Step 2: Create or get a color scheme +let colorScheme = MDCSemanticColorScheme() + +// Step 3: Apply the color scheme to your component +MDCSliderColorThemer.applySemanticColorScheme(colorScheme, to: component) +``` + +#### Objective-C + +```objc +// Step 1: Import the ColorThemer extension +#import "MaterialSlider+ColorThemer.h" + +// Step 2: Create or get a color scheme +id colorScheme = [[MDCSemanticColorScheme alloc] init]; + +// Step 3: Apply the color scheme to your component +[MDCSliderColorThemer applySemanticColorScheme:colorScheme + toslider:component]; +``` + + diff --git a/components/Slider/docs/README.md b/components/Slider/docs/README.md new file mode 100644 index 00000000000..b0b19fc2f73 --- /dev/null +++ b/components/Slider/docs/README.md @@ -0,0 +1,31 @@ +# Slider + +
+ Slider +
+ +The `MDCSlider` object is a Material Design control used to select a value from a continuous range +or discrete set of values. + +## Design & API documentation + +* [Material Design guidelines: Sliders](https://material.io/go/design-sliders) +* [API: MDCSlider](https://material.io/components/ios/catalog/sliders/api-docs/Classes/MDCSlider.html) + + + +- - - + +## Installation + +- [Typical installation](../../../docs/component-installation.md) + +## Usage + +- [Typical use](typical-use.md) +- [Stateful APIs](stateful-apis.md) +- [Differences from UISlider](differences-from-uislider.md) + +## Extensions + +- [Color Theming](color-theming.md) diff --git a/components/Slider/docs/color-theming.md b/components/Slider/docs/color-theming.md index 31b82dda7e4..6b6068d5868 100644 --- a/components/Slider/docs/color-theming.md +++ b/components/Slider/docs/color-theming.md @@ -1,13 +1,4 @@ - - -# Slider Color Theming +### Color Theming You can theme a slider with your app's color scheme using the ColorThemer extension. @@ -17,8 +8,6 @@ You must first add the Color Themer extension to your project: pod 'MaterialComponents/Slider+Extensions/ColorThemer' ``` -## Example code - #### Swift ```swift diff --git a/components/Slider/docs/differences-from-uislider.md b/components/Slider/docs/differences-from-uislider.md new file mode 100644 index 00000000000..17e1ee4695d --- /dev/null +++ b/components/Slider/docs/differences-from-uislider.md @@ -0,0 +1,17 @@ +### Differences from UISlider + +Does not have api to: + +- set right and left icons +- set the thumb image +- set the right and left track images (for a custom track) +- set the right (background track) color + +Same features: + +- set color for thumb via @c thumbColor +- set color of track via @c trackColor + +New features: + +- making the slider a snap to discrete values via property numberOfDiscreteValues diff --git a/components/Slider/docs/stateful-apis.md b/components/Slider/docs/stateful-apis.md new file mode 100644 index 00000000000..02c7a5e41c8 --- /dev/null +++ b/components/Slider/docs/stateful-apis.md @@ -0,0 +1,25 @@ +### Stateful APIs + +`MDCSlider` exposes stateful APIs to customize the colors for different control states. In order to use this API you must enable `statefulAPIEnabled` on your `MDCSlider` instances. + + +#### Swift + +```swift + let slider = MDCSlider() + slider.isStatefulAPIEnabled = true + + // Setting a thumb color for selected state. + slider.setThumbColor(.red, for: .selected) +``` + +#### Objective C + +```objc + MDCSlider *slider = [[MDCSlider alloc] init]; + slider.statefulAPIEnabled = YES; + + // Setting a thumb color for selected state. + [slider setThumbColor:[UIColor redColor] forState:UIControlStateSelected]; +``` + diff --git a/components/Slider/docs/typical-use.md b/components/Slider/docs/typical-use.md new file mode 100644 index 00000000000..4628c6aac3e --- /dev/null +++ b/components/Slider/docs/typical-use.md @@ -0,0 +1,39 @@ +### Typical use + +MDCSlider can be be used like a standard `UIControl`. + + +#### Swift + +```swift +override func viewDidLoad() { + super.viewDidLoad() + + let slider = MDCSlider(frame: CGRect(x: 50, y: 50, width: 100, height: 27)) + slider.addTarget(self, + action: #selector(didChangeSliderValue(senderSlider:)), + for: .valueChanged) + view.addSubview(slider) +} + +func didChangeSliderValue(senderSlider:MDCSlider) { + print("Did change slider value to: %@", senderSlider.value) +} +``` + +#### Objective C + +```objc +- (void)viewDidLoad { + MDCSlider *slider = [[MDCSlider alloc] initWithFrame:CGRectMake(50, 50, 100, 27)]; + [slider addTarget:self + action:@selector(didChangeSliderValue:) + forControlEvents:UIControlEventValueChanged]; + [self.view addSubview:slider]; +} + +- (void)didChangeSliderValue:(MDCSlider *)slider { + NSLog(@"did change %@ value: %f", NSStringFromClass([slider class]), slider.value); +} +``` +