Giter Club home page Giter Club logo

direct-manipulation-swift's Introduction

Direct Manipulation for Material Motion (Swift)

Build Status codecov

Supported languages

  • Swift 3
  • Objective-C

Features

This library consists of the following plans:

  • Draggable, Pinchable, and Rotatable
  • DirectlyManipulable
  • ChangeAnchorPoint

The Draggable, Pinchable, and Rotatable plans allow a user to move, scale, and rotate a view. They each listen for deltas emitted by a gesture recognizer and add them to the target.

If a view can be dragged then it can sometimes be pinched and rotated too. To make this easy, we provide a DirectlyManipulable plan. It's equivalent to individually adding Draggable, Pinchable, and Rotatable to the same target.

The collection of Draggable, Pinchable, Rotatable, and DirectlyManipulable represent traits that can describe behavior of a target view. When any of these traits are added to a view the view's isUserInteractionEnabled is enabled. If the plan's associated gesture recognizer is not yet associated with a view then the gesture recognizer will be added to the target view.

ChangeAnchorPoint adjusts view.layer.anchorPoint while maintaining the same view.frame. This plan is emitted by DirectlyManipulable when a gesture recognizer begins.

Installation

Installation with CocoaPods

CocoaPods is a dependency manager for Objective-C and Swift libraries. CocoaPods automates the process of using third-party libraries in your projects. See the Getting Started guide for more information. You can install it with the following command:

gem install cocoapods

Add MaterialMotionDirectManipulation to your Podfile:

pod 'MaterialMotionDirectManipulation'

Then run the following command:

pod install

Usage

Import the framework:

@import MaterialMotionDirectManipulation;

You will now have access to all of the APIs.

Example apps/unit tests

Check out a local copy of the repo to access the Catalog application by running the following commands:

git clone https://github.com/material-motion/direct-manipulation-swift.git
cd direct-manipulation-swift
pod install
open MaterialMotionDirectManipulation.xcworkspace

Guides

  1. How to make a view directly manipulable
  2. How to make a view draggable
  3. How to use an existing gesture recognizer to make a view draggable

How to make a view directly manipulable

Code snippets:

In Objective-C:

[runtime addPlan:[MDMDirectlyManipulable new] to:<#Object#>];

In Swift:

runtime.addPlan(DirectlyManipulable(), to: <#Object#>)

How to make a view draggable

Code snippets:

In Objective-C:

[runtime addPlan:[MDMDraggable new] to:<#Object#>];

In Swift:

runtime.addPlan(Draggable(), to: <#Object#>)

How to use an existing gesture recognizer to make a view draggable

Code snippets:

In Objective-C:

MDMDraggable *draggable = [[MDMDraggable alloc] initWithGestureRecognizer:panGestureRecognizer];
[runtime addPlan:draggable to:<#Object#>];

In Swift:

runtime.addPlan(Draggable(withGestureRecognizer: panGestureRecognizer), to: <#Object#>)

Contributing

We welcome contributions!

Check out our upcoming milestones.

Learn more about our team, our community, and our contributor essentials.

License

Licensed under the Apache 2.0 license. See LICENSE for details.

direct-manipulation-swift's People

Contributors

rcameron avatar

Stargazers

 avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

Forkers

carabina

direct-manipulation-swift's Issues

Scale delta isn't being applied correctly to the target's scale

We should be calculating the relative scale change between each event using division, not subtraction.

E.g.

oldScale = 1.2
newScale = 1.7
difference = 0.5
current code scale = 1 + difference = 1.5
actual amount scaled = 1.7 / 1.2 = 1.41666666666667

Note the discrepancy between the actual "amount scaled" and what we apply to the view.

Add example demonstrating how to use ChangeAnchorPoint

One idea is to visualize the anchor point of the view and to allow you to change it by tapping anywhere in the view. We could include labels showing the view's position in order to show what's going on with the underlying .position value when we change the anchor point.

Objective-C usage

  • All class names need to have an @objc(MDM...) name mapping.
  • Should include an Objective-C unit test file called "ObjectiveCAPITests.m" that simply instantiates each of the public APIs. These tests are meant to flag any regression in Objective-C support. All other tests can still be written in Swift.

Write the README.md

Should include the following:

  • Installation steps. (Steal the ones from here).
  • Getting started example.

Assume that this repo is the entry-point for an application developer who has never used Material Motion before. We'll likely want to link to some form of "getting started with material motion" document. Life of a plan might be a good start, but we should have a swift version as well.

Pinchable/Rotatable/Draggable should not emit anchor point adjustment

Only DirectlyManipulable should.

Rationale being that if you are using any of Pinchable/Rotatable/Draggable then it is very unlikely that you will want to modify the anchor point each time the gesture recognizer begins. This type of behavior only makes sense if you have all three plans operating in tandem (i.e. with DirectlyManipulable).

  • Deprecate shouldAdjustAnchorPointOnGestureStart on all three APIs.
  • Emit an anchor point change from DirectlyManipulable on gesture start.

Introduce an instantly-reactive gesture recognizer for pan/pinch/rotate

UIKit's gesture recognizers include a slop region. This slop region isn't always desirable for direct manipulation scenarios.

We should explore how we might provide pinch/rotate/pan support without a slop region.

One option is to implement a new UIGestureRecognizer subclass. This means we need to implement our own velocity calculations, which poses a serious risk of deviating from UIKit's velocity calculation logic.

If we can somehow utilize the existing gesture recognizers that would be preferable.

Remove BlockGesturable type

This plan is somewhat too powerful in that it allows arbitrary blocks to be provided to it. This can leak separation of concerns back to the creator of the plan.

Example:

BlockGesturable(withGestureRecognizer: gesture) { gesture in
  // Dangerous: access internal state of the registering agent
}

DirectlyManipulable should not expose plans in its public API

This is leaking the implementation details of the plan.

Instead, let's just expose the gesture recognizers. We intentionally won't expose shouldAdjustAnchorPointOnGestureStart because we always want this property to be true for DirectlyManipulable.

Add CatalogByConvention dependency

  • Add dependency to Podfile.
  • Use CatalogByConvention view controller to instantiate the root view controller.
  • Implement breadcrumbs on each example view controller.
  • Add TableOfContents.swift file to root of catalog project.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.