Merge changes I3de30a30,I17288da2

# Floating Bubble Integration

Author: keyboardr@

Last Updated: 2017-06-06

Floating bubbles provide a lightweight means of providing interactive UI while

the user is away from the app. This document details the steps necessary to

integrate these bubbles into your app.

[TOC]

![Floating bubble](images/bubble_collapsed.png){height=400}

## Ensure Bubbles can be shown

Add the `android.permission.SYSTEM_ALERT_WINDOW` permission to your manifest.

Before you show the bubble, call `Bubble.canShowBubbles(Context)` to see if the

user has granted you permission. If not, you can start an Activity from

`Bubble.getRequestPermissionIntent(Context)` to navigate the user to the system

settings to enable drawing over other apps. This is more than just a simple

runtime permission; the user must explicitly allow you to draw over other apps

via this system setting. System apps may have this allowed by default, but be

sure to test.

## Create your initial `BubbleInfo`

Use `BubbleInfo.builder()` to populate a `BubbleInfo` with your color, main

icon, main Intent (which should navigate back to your app), starting Y position,

and a list of `Actions` to put in the drawer. Each `Action` will define its

icon, user-displayable name (used for content description), Intent to perform

when clicked, whether it is enabled (optional, default true), and whether it is

checked (optional, default false).

![Floating bubble expanded](images/bubble_expanded.png){height=400}

## Create, show, and hide the Bubble

Create the bubble using `Bubble.createBubble(Context, BubbleInfo)`. The `show()`

method is safe to call at any time. If the Bubble is already showing, it is a

no-op. `hide()` may also be called at any time and will collapse the drawer

before hiding if already open. While `show()` will show immediately, `hide()`

may need to wait for other operations or animations before the bubble is hidden.

It is unlikely you will need to keep track of this, however. The bubble will be

hidden at its next opportunity, and `hide()` will not block.

![Floating bubble with state](images/bubble_state.png){height=400}

## Update the Bubble's state

Call `Bubble.setBubbleInfo(BubbleInfo)` to update all displayed state.

`BubbleInfo`s are immutable, so to make a new one using an existing

`BubbleInfo`, use `BubbleInfo.from(BubbleInfo)` to get a `Builder` with

prepopulated info. If only the `Action` state has changed, it is more efficient

to just call `Bubble.updateActions(List<Action>)`

![Floating bubble with text](images/bubble_text.png){height=400}

## Show text

To temporarily replace the icon with a textual message, call

`Bubble.showText(CharSequence)`. The text will be displayed for several seconds

before transitioning back to the primary icon. The drawer will be closed if open

and cannot be reopened while the text is displayed. Any calls to `hide()` will

be deferred until after the text is done being displayed, so if you wish to show

an ending message of some sort you may call `hide()` immediately after

`showText(CharSequence)`.