cwac-pager


Source link: https://github.com/commonsguy/cwac-pager

CWAC-Pager: Power to the PagerAdapter

This project offers an ArrayPagerAdapter that offers another alternative PagerAdapter implementation for use with ViewPager.

This Android library project is available as a JAR or as an artifact for use with Gradle. To use that, add the following blocks to your build.gradle file:

repositories {

  maven {

url "https://s3.amazonaws.com/repo.commonsware.com"
  
}
 
}
  dependencies {

  compile 'com.commonsware.cwac:pager:0.2.6' 
}

Or, if you cannot use SSL, use http://repo.commonsware.com for the repository URL.

NOTE: The JAR name, as of v0.2.2, has a cwac- prefix, to help distinguish it from other JARs.

The two concrete PagerAdapter implementations shipped in the Android Support package -- FragmentPagerAdapter and FragmentStatePagerAdapter -- have their limitations when it comes to things like:

  • Using fragments created by those adapters in other fashions, such as in using ViewPager in portrait and columns of "pages" in landscape

  • Handling dynamically-changing contents, such as adding pages, removing pages, or reordering pages

The ArrayPagerAdapter is an attempt to provide a more flexible PagerAdapter implementation that still feels a lot like FragmentPagerAdapter in terms of its use of fragments. It also bears some resemblance to the ArrayAdapter used for AdapterView implementations like ListView, giving rise to its name.

Usage

Once you have added the JAR or AAR to your project, you can start using ArrayPagerAdapter.

Choosing the Package

There are two implementations of ArrayPagerAdapter. One, in the com.commonsware.cwac.pager package, is designed for use with native API Level 11 fragments. The other, in the com.commonsware.cwac.pager.v4 package, is designed for use with the Android Support package's backport of fragments. You will need to choose the right ArrayPagerAdapter for the type of fragments that you are using.

However, other than choosing suitable versions of classes for Fragment, etc., there is no real public API difference between the two. Hence, the documentation that follows is suitable for either implementation of ArrayPagerAdapter, so long as you use the one that matches the source of your fragment implementation.

Note that only ArrayPagerAdapter lives in the com.commonsware.cwac.pager.v4 package. The classes and interfaces that support ArrayPagerAdapter, like PageDescriptor, are implemented in com.commonsware.cwac.pager and used by both implementations of ArrayPagerAdapter.

Creating PageDescriptors

You might think that ArrayPagerAdapter would take an array of pages, much like ArrayAdapter takes an array of models.

That's not how it works.

Instead, ArrayPagerAdapter wants an ArrayList of PageDescriptor objects. PageDescriptor is an interface, requiring you to supply implementations of two methods:

  • getTitle(), which will be the title used for this page, for things like PagerTabStrip and the ViewPagerIndicator family of indicators

  • getFragmentTag(), which is a unique tag for this page's fragment

Also, PageDescriptor extends the Parcelable interface, and so any implementation of PageDescriptor must also implement the methods and CREATOR required by Parcelable.

You are welcome to create your own PageDescriptor if you wish. However, there is a built-in implementation, SimplePageDescriptor, which probably meets your needs. You just pass the tag and title into the SimplePageDescriptor constructor, and it handles everything else, including the Parcelable implementation.

Note that getFragmentTag() must return unique values compared to any other outstanding page in the adapter.

Creating and Populating the Adapter

To work with ArrayPagerAdapter, you start by creating an ArrayList of PageDescriptor objects, one for each page that is to be in your pager.

Then, create a subclass of ArrayPagerAdapter. ArrayPagerAdapter uses Java generics, requiring you to declare the type of fragment the adapter is serving up to the ViewPager. So, for example, if you have a ViewPager that will have each page be an EditorFragment, you would declare your custom ArrayPagerAdapter like so:

static class SamplePagerAdapter extends
 ArrayPagerAdapter<EditorFragment> {
 

If you will have pages come from a variety of fragments, just use the Fragment base class appropriate for your fragment source (e.g., android.app.Fragment).

Your custom ArrayPagerAdapter subclass will need to override (at minimum) one method: createFragment(). This method is responsible for instantiating fragments, as requested. You are passed the PageDescriptor for the fragment to be created -- you simply create and return that fragment.

Hence, a custom ArrayPagerAdapter can be as simple as:

static class SamplePagerAdapter extends
  ArrayPagerAdapter<EditorFragment> {

public SamplePagerAdapter(FragmentManager fragmentManager,

  ArrayList<PageDescriptor> descriptors) {

  super(fragmentManager, descriptors);

}

 @Override
protected EditorFragment createFragment(PageDescriptor desc) {

  return(EditorFragment.newInstance(desc.getTitle()));

}
 
}
 

Then, you can create an instance of your custom ArrayPagerAdapter subclass as needed, supplying the constructor with a suitable FragmentManager and your ArrayList of PageDescriptor objects. Once attached to a ViewPager, ArrayPagerAdapter behaves much like a FragmentPagerAdapter by default.

There is another flavor of the ArrayPagerAdapter constructor, one that takes a RetentionStrategy as a parameter. This will eventually allow ArrayPagerAdapter to work either like FragmentPagerAdapter (current) or FragmentStatePagerAdapter (future).

Modifying the Contents

ArrayPagerAdapter offers several methods to allow you to change the contents of the ViewPager:

  • add() takes a PageDescriptor and adds a new page at the end of the current roster of pages

  • insert() takes a PageDescriptor and an insertion point and inserts a new page before the current page at that insertion point

  • remove() takes a position and removes the page at that position

  • move() takes an old and new position and moves the page from the old position to the new position (effectively combining a remove() from the old position and an insert() of the same page into the new position

Other Useful Methods

  • getExistingFragment(), given a position, returns the existing fragment for that position in the ViewPager, if that fragment exists. Otherwise, it returns null.

  • getCurrentFragment() is like getExistingFragment(), but returns the fragment for the currently-viewed page in the ViewPager.

  • getPositionForTag() tells you the position index of the page associated with a particular tag, where the tag comes from the PageDescriptor

  • getPageDescriptor(), given a position, returns the PageDescriptor associated with that position (e.g., so you can modify data in the descriptor)

Limitations

The ViewPager used by the ArrayPagerAdapter must have the same ID in all configurations. Usually, this is not a problem, particularly if the ID is set to be the same via android:id in layouts. However, if you are dynamically creating your ViewPager instance at runtime, this is something to keep in mind.

Dependencies

This project depends on the Android Support package at compile time, if you are using the Android library project. It also depends on the Android Support Library at runtime if you are using the v4 classes. The Gradle files handle this automatically, pulling from the appropriate repositories.

Version

This is version v0.2.6 of this module, meaning it is still pretty young.

Demo

In the demo/ sub-project you will find a sample project demonstrating the use of ArrayPagerAdapter for the native API Level 11 implementation of fragments. The demo-v4/ sub-project has a similar sample for the v4 backport of fragments from the Android Support package.

Additional Documentation

The Busy Coder's Guide to Android Development contains two chapters covering ViewPager. The second chapter, on advanced ViewPager techniques, covers this library in depth.

License

The code in this project is licensed under the Apache Software License 2.0, per the terms of the included LICENSE file.

Questions

If you have questions regarding the use of this code, please post a question on Stack Overflow tagged with commonsware and android. Be sure to indicate what CWAC module you are having issues with, and be sure to include source code and stack traces if you are encountering crashes.

You are also welcome to join the CommonsWare Community and post questions and ideas to the CWAC category.

If you have encountered what is clearly a bug, or if you have a feature request, please post an issue. The contribution guidelines provide some suggestions for how to create a bug report that will get the problem fixed the fastest.

Do not ask for help via Twitter.

Also, if you plan on hacking on the code with an eye for contributing something back, please open an issue that we can use for discussing implementation details. Just lobbing a pull request over the fence may work, but it may not. Again, the contribution guidelines provide a bit of guidance here.

Release Notes

  • v0.2.6: reset Android Support Library dependency to a fixed value, vs. +
  • v0.2.5: added setTitle() to SimplePageDescriptor, getPositionForTag() and getPageDescriptor() to ArrayPagerAdapter
  • v0.2.4: updated to Android Studio 1.0 and new AAR publishing system
  • v0.2.3: added some defensive programming around state
  • v0.2.2: merged issue #5 to support List in ArrayPagerAdapter constructor
  • v0.2.1: re-fixed Parcelable classloader bug, now enforcing tag uniqueness
  • v0.2.0: added Gradle build files and published AAR
  • v0.1.2: fixed Parcelable classloader bug
  • v0.1.1: minor bug fixes in backwards-compatibility support
  • v0.1.0: initial release

Who Made This?

Resources

Project created for autolearning with Material Design and Android good practices to develop a MVP (Model View Presenter) application using a mocked list of upcoming movies as the domain of the application.

Open source project in order to implement Pinterest like list view on Android.

Easy to use package repository for Gradle and Maven projects.

JitPack builds GitHub projects on demand and provides ready-to-use packages.

android-beacon-library is an Android library providing APIs to interact with beacons.

Modification to the standard Maven plugin to be compatible with android-library projects (aar).

MapDB provides concurrent Maps, Sets and Queues backed by disk storage or off-heap memory.

Topics


2D Engines   3D Engines   9-Patch   Action Bars   Activities   ADB   Advertisements   Analytics   Animations   ANR   AOP   API   APK   APT   Architecture   Audio   Autocomplete   Background Processing   Backward Compatibility   Badges   Bar Codes   Benchmarking   Bitmaps   Bluetooth   Blur Effects   Bread Crumbs   BRMS   Browser Extensions   Build Systems   Bundles   Buttons   Caching   Camera   Canvas   Cards   Carousels   Changelog   Checkboxes   Cloud Storages   Color Analysis   Color Pickers   Colors   Comet/Push   Compass Sensors   Conferences   Content Providers   Continuous Integration   Crash Reports   Credit Cards   Credits   CSV   Curl/Flip   Data Binding   Data Generators   Data Structures   Database   Database Browsers   Date &   Debugging   Decompilers   Deep Links   Dependency Injections   Design   Design Patterns   Dex   Dialogs   Distributed Computing   Distribution Platforms   Download Managers   Drawables   Emoji   Emulators   EPUB   Equalizers &   Event Buses   Exception Handling   Face Recognition   Feedback &   File System   File/Directory   Fingerprint   Floating Action   Fonts   Forms   Fragments   FRP   FSM   Functional Programming   Gamepads   Games   Geocaching   Gestures   GIF   Glow Pad   Gradle Plugins   Graphics   Grid Views   Highlighting   HTML   HTTP Mocking   Icons   IDE   IDE Plugins   Image Croppers   Image Loaders   Image Pickers   Image Processing   Image Views   Instrumentation   Intents   Job Schedulers   JSON   Keyboard   Kotlin   Layouts   Library Demos   List View   List Views   Localization   Location   Lock Patterns   Logcat   Logging   Mails   Maps   Markdown   Mathematics   Maven Plugins   MBaaS   Media   Menus   Messaging   MIME   Mobile Web   Native Image   Navigation   NDK   Networking   NFC   NoSQL   Number Pickers   OAuth   Object Mocking   OCR Engines   OpenGL   ORM   Other Pickers   Parallax List   Parcelables   Particle Systems   Password Inputs   PDF   Permissions   Physics Engines   Platforms   Plugin Frameworks   Preferences   Progress Indicators   ProGuard   Properties   Protocol Buffer   Pull To   Purchases   Push/Pull   QR Codes   Quick Return   Radio Buttons   Range Bars   Ratings   Recycler Views   Resources   REST   Ripple Effects   RSS   Screenshots   Scripting   Scroll Views   SDK   Search Inputs   Security   Sensors   Services   Showcase Views   Signatures   Sliding Panels   Snackbars   SOAP   Social Networks   Spannable   Spinners   Splash Screens   SSH   Static Analysis   Status Bars   Styling   SVG   System   Tags   Task Managers   TDD &   Template Engines   Testing   Testing Tools   Text Formatting   Text Views   Text Watchers   Text-to   Toasts   Toolkits For   Tools   Tooltips   Trainings   TV   Twitter   Updaters   USB   User Stories   Utils   Validation   Video   View Adapters   View Pagers   Views   Watch Face   Wearable Data   Wearables   Weather   Web Tools   Web Views   WebRTC   WebSockets   Wheel Widgets   Wi-Fi   Widgets   Windows   Wizards   XML   XMPP   YAML   ZIP Codes