JarCastingGrid-based reorderable view like Android home screen
Download
If you are using Android Studio, add the following line to the dependencies section in your module-level build.gradle.
implementation 'net.kyu_mu:pigeonholeview:1.0.4'
Usage
An example app is available at app directory. To run the example app, open this top-level directory in Android Studio and press the "Run" button.
The instructions below are a complete guide to integrate PigeonholeView in your app.
First, define a class that holds the data for a single cell. Include an int instance variable which stores a view position in PigeonholeView.
MyData.java:
/**
* Data for a single cell.
*/
public class MyData {
private String name;
private int imageResourceId;
private int viewPosition; // view position in PigeonholeView
public MyData(String name, int imageResourceId, int viewPosition) {
this.name = name;
this.imageResourceId = imageResourceId;
this.viewPosition = viewPosition;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getImageResourceId() {
return imageResourceId;
}
public void setImageResourceId(int imageResourceId) {
this.imageResourceId = imageResourceId;
}
public int getViewPosition() {
return viewPosition;
}
public void setViewPosition(int viewPosition) {
this.viewPosition = viewPosition;
}
}
Then, create an Activity that contains PigeonholeView. In the example below, all parameters prefixed with custom: are optional. In order to use custom: attributes, you have to add xmlns:custom="http://schemas.android.com/apk/res-auto" to the root element. For details of the attributes, see XML Attributes.
activity_main.xml:
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:custom="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MainActivity">
<net.kyu_mu.pigeonholeview.PigeonholeView
android:id="@+id/my_pigeonhole_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
custom:cellHeight="88dp"
custom:cellWidth="80dp"
custom:dragStartAnimationDuration="100"
custom:dropAreaText="Drop here to edit"
custom:dropAreaTopPadding="10dp"
custom:editable="true"
custom:topSpaceHeight="?attr/actionBarSize" />
</RelativeLayout>
Include v7 appcompat Android Support Library in module-level build.gradle.
dependencies {
compile 'net.kyu_mu:pigeonholeview:1.0.4'
compile "com.android.support:appcompat-v7:27.1.1"
}
Edit values/styles.xml and add a custom style (CustomActionBarTheme) that enables ActionBar overlay:
<resources xmlns:tools="http://schemas.android.com/tools">
<style name="CustomActionBarTheme" parent="@style/Theme.AppCompat.Light.DarkActionBar">
<item name="android:windowActionBarOverlay" tools:ignore="NewApi">true</item>
<!-- Support library compatibility -->
<item name="windowActionBarOverlay">true</item>
</style>
</resources>
Edit AndroidManifest.xml and apply CustomActionBarTheme to the Activity using android:theme attribute.
<activity
android:name=".MainActivity"
android:label="@string/app_name"
android:theme="@style/CustomActionBarTheme">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
Set up the view in the code.
MainActivity.java:
public class MainActivity extends AppCompatActivity implements
PigeonholeView.PigeonholeViewListener<MyData> {
private PigeonholeView<MyData> pigeonholeView;
private ArrayList<MyData> myDataList;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Test data
myDataList = new ArrayList<>();
myDataList.add(new MyData("Button 1", android.R.drawable.ic_menu_myplaces, 0));
myDataList.add(new MyData("Button 2", android.R.drawable.ic_menu_rotate, 1));
myDataList.add(new MyData("Button 3", android.R.drawable.ic_menu_mapmode, 2));
pigeonholeView = (PigeonholeView<MyData>) findViewById(R.id.my_pigeonhole_view);
// This is the bridge between PigeonholeView and your data
pigeonholeView.setDataProvider(new PigeonholeView.DataProvider<MyData>() {
/**
* Return the view position for the item.
*/
@Override
public int getViewPosition(MyData item) {
return item.getViewPosition();
}
/**
* Store the view position for the item.
*/
@Override
public void setViewPosition(MyData item, int viewPosition) {
item.setViewPosition(viewPosition);
// You don't need to persist the view positions here. Instead,
// save them in onReorder() to minimize the overhead.
}
/**
* Return the view for the item.
*/
@Override
public View getView(View cellView, MyData item) {
// Reuse the existing view if cellView is not null.
// Otherwise, instantiate a view.
if (cellView == null) {
LayoutInflater inflater = LayoutInflater.from(MainActivity.this);
cellView = inflater.inflate(R.layout.list_item, pigeonholeView, false);
}
// Update the image
ImageView imageView = (ImageView) cellView.findViewById(R.id.item_image);
imageView.setImageResource(item.getImageResourceId());
// Update the name
TextView nameTextView = (TextView) cellView.findViewById(R.id.item_name);
nameTextView.setText(item.getName());
return cellView;
}
/**
* Return the iterator for the list of cells.
*/
@Override
public Iterator<MyData> iterator() {
return myDataList.iterator();
}
});
pigeonholeView.setOnCellClickListener(new PigeonholeView.OnCellClickListener<MyData>() {
@Override
public void onClick(PigeonholeView.CellData<MyData> cellData) {
// Retrieve the target data
MyData myData = cellData.getObject();
Toast.makeText(MainActivity.this, myData.getName() + " is clicked", Toast.LENGTH_SHORT).show();
}
});
// Receive events from PigeonholeView
pigeonholeView.setListener(this);
}
private void hideActionBar() {
ActionBar actionBar = getSupportActionBar();
if (actionBar != null) {
actionBar.hide();
}
}
private void showActionBar() {
ActionBar actionBar = getSupportActionBar();
if (actionBar != null) {
actionBar.show();
}
}
/**
* Called when the dragging has started.
*/
@Override
public void onDragStart() {
hideActionBar();
}
/**
* Called when the dragging has ended.
*/
@Override
public void onDragEnd() {
showActionBar();
}
/**
* Called when the user dropped a button to the drop area.
*/
@Override
public void onEditObject(MyData myData) {
// To update the cell data:
myData.setName("Updated");
myData.setImageResourceId(android.R.drawable.ic_menu_edit);
pigeonholeView.updateEditingObject();
// // To delete the cell:
// myDataList.remove(myData);
// pigeonholeView.deleteEditingObject();
// // To cancel edit:
// pigeonholeView.cancelEdit();
}
/**
* Called when reordering has happened in the PigeonholeView.
*/
@Override
public void onReorder() {
// You should persist the view positions here.
}
}
Put list_item.xml in res/layout. This is the layout for a single cell.
Now you can run your app and see PigeonholeView in action.
Adding a button dynamically
If you call pigeonholeView.addObject() with a MyData instance, smallest-avialable view position will be assigned to it.
MyData newData = new MyData("New Button", android.R.drawable.ic_menu_zoom, 0);
myDataList.add(newData);
pigeonholeView.addObject(newData);
To check whether the PigeonholeView is full:
if (pigeonholeView.isFull()) {
Toast.makeText(this, "Can't add more buttons", Toast.LENGTH_SHORT).show();
} else {
// Add a button
}
Changing edit mode
To disable edit mode dynamically:
pigeonholeView.setEditable(false);
To enable edit mode dynamically:
pigeonholeView.setEditable(true);
To disable edit mode in xml, add custom:editable="false" attribute to PigeonholeView element. Edit mode is enabled by default.
XML attributes
| Attribute | Description | Type (default value) |
|---|---|---|
custom:editable |
If true, long click is enabled | boolean (true) |
custom:cellWidth |
Width of a cell | dimension (80px) |
custom:cellHeight |
Height of a cell | dimension (90px) |
custom:topSpaceHeight |
(See the image below) | dimension (0px) |
custom:dropAreaTopPadding |
(See the image below) | dimension (20px) |
custom:dropAreaText |
Text for drop area | string (@string/drop_area__text) |
custom:dragStartAnimationDuration |
Duration of drag start animation in milliseconds | integer (200) |
License
Copyright 2015 Nao Iizuka
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.