PanesLibrary

This library makes it ridiculously easy to make native Android apps with multi-pane tablet layouts. On the phone, the app appears as a conventional app with a sliding menu and a content pane where fragments are stacked on top of each other. On the tablet, the menu and all other fragments appear in dynamically added panes of varying sizes.

Here’s a YouTube video of PanesLibrary in action.

Follow me @kenrickrilee for more!

Example

The example provided is very simple. Looking through the code there is probably the best place to start.

ExampleActivity demonstrates all the necessary configuration for using PanesActivity.

ExampleFragment uses a layout with two TextViews and a Button. The TextViews hold the index of the fragment and the length of time it’s been alive. This is used to demonstrate that fragments are correctly retained on activity restarts. The Button has a callback which creates a new fragment and adds it to the parent activity.

Using PanesLibrary

Make sure you have the most up-to-date support library and ActionBarSherlock libraries.

Have your activity extend PanesActivity. Then, add fragments to the activity using the following functions:

  • setMenuFragment(fragment): set the menu
  • addFragment(prevFragment, newFragment): adds newFragment after the prevFragment (clobbering any fragments that used to be after prevFragment)
  • clearFragments(): removes all the fragments except the menu fragment
  • getMenuFragment(): get the menu fragment
  • getTopFragment(): get the fragment on the top of the stack

You also need to provide a PaneSizer. This object allows you to programatically set the width of each pane based on the type of Fragment/View you want to place inside the pane.

You should also implement updateFragment(…). This is run whenever a fragment is added (even on activity restarts).

Fragments are added onto a stack where the 0th fragment is the menu. Here’s an example of what this means:


> setMenuFragment(A)
stack: A

> addFragment(A, B)
stack: A, B

> addFragment (B, C)
stack: A, B, C

> addFragment (C, D)
stack: A, B, C, D

> addFragment(B, E)
stack: A, B, E

>clearFragments()
stack: A

Note: PanesActivity requires you to use fragments. If you don’t use fragments, you can still use PanesLayout manually.

PanesLayout (this controls the tablet layout)

The hierarchy of a PanesLayout looks like this:

|--------------------------------|
| PanesLayout                    |
| |----------------------------| |
| | PaneScrollView             | |
| | |------------------------| | |
| | | PaneView |-----------| | | |
| | |          | (content) | | | |
| | |          |-----------| | | |
| | |------------------------| | |
| |----------------------------| |
|--------------------------------|

A PanesLayout can hold any number of panes. Each pane is made up of a PaneScrollView (which allows the pane contents to slide left & right), a PaneView (which provides padding on the left of the content), and some content (i.e. fragment).

Variables associated with each pane:

  • type: the possible values of type are defined by the user. For example, in ExampleActivity, the only possible type is DEFAULT_PANE_TYPE. This variable is used to size the pane by the PaneSizer
  • focused: if true, then PanesLayout will never intercept touch events associated with this pane.
  • index: the index of this pane— starting at 0, going to # of panes – 1.

To add/remove/get panes:

  • addPane(int type)
  • addPane(int type, boolean focused)
  • removePanes(int i): removes all panes after the ith index
  • getNumPanes(): the number of panes
  • getCurrentIndex(): the current top index
  • setIndex(int index): scroll to the pane associated with index.

Listeners/delegates:

  • PaneSizer: determines what the type/focus of a pane should be based on some associated object (i.e. Fragment or View)
  • OnIndexChangedListener: this is fired whenever the visible panes change.
Copyright 2013 Kenrick Rilee

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

   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.