This library provides a clickable floating action button (FAB) with an optional speed-dial menu. The FAB can trigger a standard click listener or a open the speed-dial menu with further options. All aspects of the FAB and speed-dial menu are customisable.
You can try the demo in one of two ways:
-
Clone this repository and install the demo app from the
app/folder (you can do this with Gradle, usinggradle clean installDebug). -
Download the sample app from the Google Play Store: Floating Action Button Demo.
compile 'uk.co.markormesher:android-fab:2.0.0'
<dependency>
<groupId>uk.co.markormesher</groupId>
<artifactId>android-fab</artifactId>
<version>2.0.0</version>
<type>pom</type>
</dependency>
Note: depending on your app's configuration, you may need to add the following to your ProGuard rules:
-dontwarn java.lang.invoke.*
See app/proguard-rules.pro for an example.
Note: all of the instructions below assume that the FAB is referenced by the variable fab, i.e.
// Java
FloatingActionButton fab = (FloatingActionButton) findViewById(R.id.fab);
// Kotlin (without Android extensions)
val fab = findViewById(R.id.fab) as FloatingActionButton
The FloatingActionButton view must be placed at the root of your layout, above all other views, and with maximum width and height. This allows the semi-transparent layer to expand and cover the entire layout when the speed-dial menu is opened.
<uk.co.markormesher.android_fab.FloatingActionButton
android:id="@+id/fab"
android:layout_width="match_parent"
android:layout_height="match_parent"
/>
The FAB can be positioned in any of the four corners of the activity via XML or with fab.setButtonPosition(...). The default position is the bottom-end corner.
// Java
fab.setButtonPosition(POSITION_BOTTOM | POSITION_END);
// Kotlin
fab.setButtonPosition(POSITION_BOTTOM.or(POSITION_END))
// XML
<uk.co.markormesher.android_fab.FloatingActionButton
xmlns:app="http://schemas.android.com/apk/res-auto"
...
app:buttonPosition="bottom|end"
/>
The FAB is aware of text-direction (right-to-left or left-to-right) and adjusts the meaning of "start" and "end" positions accordingly. This functionality can be overridden using the named constants for left and right.
The icon displayed in the centre of the FAB can be set via XML using a Drawable reference or with fab.setButtonIconResource(...) using a Drawable resource ID. The icon will be centred in a 24dp x 24dp view group, as per the Android Material Design specs.
// Java
fab.setButtonIconResource(R.drawable.ic_add);
// Kotlin
fab.setButtonIconResource(R.drawable.ic_add)
// XML
<uk.co.markormesher.android_fab.FloatingActionButton
xmlns:app="http://schemas.android.com/apk/res-auto"
...
app:buttonIcon="@drawable/ic_add"
/>
The background colour of the FAB can be set via XML using a colour reference or programmatically with fab.setButtonBackgroundColour(...) using an aRGB colour value (e.g. 0xffff9900 for dark orange). Note that the second method does not take a colour resource ID, so passing in R.color.some_colour_name will not work.
// Java
fab.setButtonBackgroundColour(0xffff9900);
// Kotlin
fab.setButtonBackgroundColour(0xffff9900.toInt())
// XML
<uk.co.markormesher.android_fab.FloatingActionButton
xmlns:app="http://schemas.android.com/apk/res-auto"
...
app:buttonBackgroundColour="@color/fab_colour"
/>
A click listener can be added to the FAB in the same way as any other button. The view passed to the listener can be safely cast to a FloatingActionButton.
// Java
fab.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
// ...
}
});
// Kotlin
fab.setOnClickListener { v ->
// ...
}
The speed-dial menu is enabled by creating a class that extends SpeedDialMenuAdapter and passing it to fab.setSpeedDialMenuAdapter(...). The adapter class methods are documented in-situ.
The content cover expands from the FAB when the speed-dial menu is opened to obscure the rest of the app content and emphasise the menu. It also prevents controls in the rest of the app from being clicked on while the speed-dial menu is open; tapping outside the menu while it is open and the cover is displayed will cause the menu to close.
The colour of the content cover can be set programmatically with fab.setContentCoverColour(...) using an aRGB colour value (e.g. 0x99ff9900 for a semi-transparent dark orange). Note that this method does not take a colour resource ID, so passing in R.color.some_colour_name will not work.
// Java
fab.setContentCoverColour(0xffff9900);
// Kotlin
fab.setContentCoverColour(0xffff9900.toInt())
The cover can be enabled/disabled programmatically with fab.setContentCoverEnabled(...).
// Java
fab.setContentCoverEnabled(true);
fab.setContentCoverEnabled(false);
// Kotlin
fab.setContentCoverEnabled(true)
fab.setContentCoverEnabled(false)
State change events are fired when the speed-dial menu opens or closes, which can be received with fab.setOnSpeedDialMenuOpenListener(...) and fab.setOnSpeedDialMenuCloseListener(...).
// Java
fab.setOnSpeedDialMenuOpenListener(new SpeedDialMenuOpenListener() {
@Override
public void onOpen(FloatingActionButton floatingActionButton) {
// ...
}
});
// Kotlin
fab.setOnSpeedDialMenuOpenListener { floatingActionButton ->
// ...
}
The FAB can be hidden and shown with the fab.hide() and fab.show() methods, and the method fab.isShown() will return a boolean indicating the current state. These methods animate the FAB in and out of visibility. If the speed-dial menu is open when .hide() is called it will be closed.
The speed-dial menu can be manually opened and closed with fab.openSpeedDialMenu() and fab.closeSpeedDialMenu(). These methods will do nothing if no speed-dial menu adapter is set, if an adapter is set but disabled, if the FAB is hidden, or if they are called when the menu is already in the indicated state (i.e. fab.openSpeedDialMenu() will do nothing if the menu is already open).
As per Material Design specs, the FAB functions as a regular button or a trigger for the speed-dial menu, but not both. For this reason, the click listener and the speed-dial menu are never invoked at the same time.
The speed-dial menu is given priority: when the FAB is clicked the speed-dial menu will be shown if the speed-dial menu adapter is non-null, the adapter's isEnabled() function returns true and the adapter's getCount() returns a number greater than zero. Otherwise, the FAB's click listener will be called (if it has been set).
Setting a speed-dial menu adapter does not remove the click listener, and setting a click listener does not remove the speed-dial menu adapter. For an example of how the two operation modes interact, check the demo app's source code.
To receive state change updates when the speed-dial menu is opened or closed, use the open/close listeners described above.
The following properties are preserved when a configuration change (like a screen orientation change) happens:
- FAB hidden/shown
- FAB position
- FAB background colour
- FAB icon
- Speed-dial menu content cover colour
- Speed-dial menu content cover enabled/disabled
The following properties are not preserved and will need to be restored by the parent activity/fragment:
- FAB click listener
- Speed-dial menu adapter
- Speed-dial menu open/close listeners