From 9c0d3e80701118f50ca2b0f2d739ae27402c5907 Mon Sep 17 00:00:00 2001 From: Vincent Te Tau Date: Mon, 1 Feb 2016 16:36:23 +1300 Subject: [PATCH] Update README.md --- README.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 153 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e1a782f..2eec44a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # PeekAndPop -THIS LIBRARY IS CURRENTLY UNDER DEVELOPMENT AND NOT INTENDED TO BE USED IN PRODUCTION +### THIS LIBRARY IS CURRENTLY UNDER DEVELOPMENT AND NOT INTENDED TO BE USED IN PRODUCTION PeekAndPop is an open source Android library, inspired by Instagram's latest 3D touch feature. As 3D touch is not available for android, this library uses long hold. @@ -8,7 +8,8 @@ As 3D touch is not available for android, this library uses long hold. Peek and pop allows you to long click on a view to "peek" and see a larger view in the centre of the screen. The pop feature can be imitated using fling to action gestures or from a hold and release event. -Features: +### Features: + - Create a basic peek and pop that shows on long click and is dismissed on touch up. - Fling to action, where flinging the view upwards or downwards (sidewards in landscape) triggers an event. - Specify views within the peek view layout that can listen to long hold events (if the user holds the view for a @@ -16,7 +17,155 @@ certain amount of time). - Specify views within the peek view layout that can listen to hold and release events (where the user holds the view and then releases). -Please check the examples below to see the features in action (to be added): +### Demo (To be added): + +### Getting started: + +This library is hosted on Jitpack.io, which means to use it you will have to add the following to your root `build.gradle` file. + +``` + allprojects { + repositories { + ... + maven { url "https://jitpack.io" } + } + } +``` + +And then you will need to add the following dependency to your applications `build.gradle` file. + +``` + dependencies { + compile 'com.github.shalskar:PeekAndPop:5a012c64ac' + } +``` + +### Usage: +Basic usage is easy, simply provide an activity instance, a layout resource for the peek and pop and 1 or more views that will show the peek and pop when long clicked. + + +``` +PeekAndPop peekAndPop = new PeekAndPop.Builder(this) + .peekLayout(R.layout.peek_view) + .longClickViews(view) + .build(); +``` + + +Often you will want to have the peek and pop shown when an item in a list (or other scrollable view) is clicked on, to ensure the peek and pop works correctly, you will have to add this line of code: + + +``` + .parentViewGroupToDisallowTouchEvents(viewGroup) +``` + +#### More options: + +##### Listening for peek or pop events + +You can set an `OnGeneralActionListener` to receive `onPeek()` and `onPop()` events: + +``` + .onGeneralActionListener(new PeekAndPop.OnGeneralActionListener() { + @Override + public void onPeek(View longClickView, int position) { + + } + + @Override + public void onPop(View longClickView, int position) { + + } + }) +``` + +The parameters being the view that was long clicked and the position of that view. + +##### Listening for fling to action events + +If you provide an `OnFlingToActionListener` then you will automatically be able to fling the view upwards or downwards and listen for those events: + +``` + .onFlingToActionListener(new PeekAndPop.OnFlingToActionListener() { + @Override + public void onFlingToAction(View longClickView, int position, int direction) { + + } + }) +``` + +The parameters being the same as above and the direction in which the view was flung. (`FLUNG_UPWARDS` or `FLUNG_DOWNWARDS`.) + +If you only want to listen for one direction you can set that like so: + +``` + .flingTypes(true, false) +``` + +And if you don't want to animate the view when flinging: + +``` + .animateFling(false) +``` + +###### Listening for hold and release events + +Similar to Instagram, you can specify views inside the peek layout that will trigger events if the user releases on them: + +``` + .onHoldAndReleaseListener(new PeekAndPop.OnHoldAndReleaseListener() { + @Override + public void onHoldAndRelease(View view, int position) { + + } + }) +``` + +And then you must specify the id's of the views you would like to receive events from after you have built the PeekAndPop object: + +``` + peekAndPop.addHoldAndReleaseView(R.id.view); + peekAndPop.addHoldAndReleaseView(R.id.view2); +``` + +##### Listening for long hold events + +You can specify views inside the peek layout that will trigger an event if the user holds their finger/thumb over the view for a certain duration (default is 850ms). If `receiveMultipleEvents` is true than events will be contiuously triggered until the user moves their finger/thumb off the view: + +``` + .onLongHoldListener(new PeekAndPop.OnLongHoldListener() { + @Override + public void onLongHold(View view, int position) { + + } + }) +``` + +And then you must specify the id's of the views you would like to receive events from after you have built the PeekAndPop object, aswell as a boolean argument whether or not you want to receive multiple events: + +``` + peekAndPop.addLongHoldView(R.id.view, true); + peekAndPop.addLongHoldView(R.id.view, false); +``` + + +The second argument determines whether the view will send multiple events or not. If false, then the user must move their finger/thumb off the view then back on to trigger another event. + + +### License + +``` +Copyright 2016 Vincent Te Tau + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 -Author is Vincent Te Tau +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +```