Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
kizitonwose committed Dec 7, 2017
1 parent 7f1aaca commit 2aa0094
Showing 1 changed file with 40 additions and 26 deletions.
66 changes: 40 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,13 @@
# Android-DisposeBag

[RxSwift][rxswift-url] has an inbuilt [DisposeBag][disposebag-swift-url] container which disposes all disposables when it is deinitialized. Unfortunately, there is no reliable way to achieve the same result in Java/Kotlin. Even if we could achieve this, there's still a problem with the Android platform, Activities are created and managed by the system, using it after either `onDestroy` or `onStop` method is called will result to a crash.

This library uses the new LifecycleObserver introduced in Android Architecture Components to automatically dispose [RxJava][rxjava-url]/[RxKotlin][rxkotlin-url] streams at the right time. Internally, the DisposeBag uses a [CompositeDisposable][compositedisposable-java-url].

## Installation

Add the JitPack repository to your `build.gradle`:
[![Build Status](https://travis-ci.org/kizitonwose/android-disposebag.svg?branch=master)](https://travis-ci.org/kizitonwose/android-disposebag)
[![Coverage](https://img.shields.io/codecov/c/github/kizitonwose/android-disposebag/master.svg)](https://codecov.io/gh/kizitonwose/android-disposebag)
[![JitPack](https://jitpack.io/v/kizitonwose/android-disposebag.svg)](https://jitpack.io/#kizitonwose/android-disposebag)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/kizitonwose/android-disposebag/blob/master/LICENSE.md)

```groovy
allprojects {
repositories {
maven { url "https://jitpack.io" }
}
}
```
[RxSwift][rxswift-url] has an inbuilt [DisposeBag][disposebag-swift-url] container which disposes all disposables when it is deinitialized. Unfortunately, there is no reliable way to achieve the same result in Java/Kotlin. Even if we could achieve this, there's still a problem with the Android platform, Activities are created and managed by the system, using it after either `onDestroy` or `onStop` method is called will result to a crash.

Add the dependency to your `build.gradle`:

```groovy
dependencies {
compile 'com.github.kizitonwose:android-disposebag:1.0.0'
}
```
This library uses the new LifecycleObserver introduced in Android Architecture Components to automatically dispose [RxJava][rxjava-url]/[RxKotlin][rxkotlin-url] streams at the right time.

## Usage

Expand All @@ -32,7 +17,6 @@ Create a DisposeBag, supply your LifecycleOwner, then add all your disposbles.

The example below uses an Activity but this also works with Fragments or any other class that impements the LifecycleOwner interface.


##### Kotlin:

```kotlin
Expand All @@ -43,6 +27,8 @@ class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)

val button = findViewById<Button>(R.id.button)

button.clicks()
.subscribe {
// Handle button clicks
Expand All @@ -61,6 +47,8 @@ public final class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);

final Button button = findViewById(R.id.button);

bag.add(RxView.clicks(button)
.subscribe(o -> {
Expand All @@ -70,7 +58,7 @@ public final class MainActivity extends AppCompatActivity {
}
```

In the examples above, the DisposeBag automatically disposes all disposables when the activity is destroyed. The `clicks()` extension function and `RxView.clicks()` static method are both from [RxBinding][rxbinding-url].
In the examples above, the DisposeBag automatically disposes all disposables when the activity is destroyed. The `clicks()` extension function and `RxView.clicks()` static method are both from [RxBinding][rxbinding-url]. Internally, the DisposeBag uses a [CompositeDisposable][compositedisposable-java-url].

You can change the dipose event by specifying it when creating the DisposeBag:

Expand Down Expand Up @@ -100,6 +88,8 @@ class MainFragment : Fragment() {
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
super.onViewCreated(view, savedInstanceState)

val button = view.findViewById<Button>(R.id.button)

button.clicks()
.subscribe {
// Handle button clicks
Expand All @@ -118,7 +108,7 @@ button.clicks()
}.disposedWith(this, Lifecycle.Event.ON_STOP) // Change the dispose event
```

>Note the difference between the two: `disposedBy()` and `disposedWith()`
> Note the difference between the two: `disposedBy()` and `disposedWith()`
## Changing the default dispose event globally

Expand All @@ -129,7 +119,7 @@ In your app's Application class:
##### Kotlin:

```kotlin
class MyApp : Application(){
class MyApp : Application() {

override fun onCreate() {
super.onCreate()
Expand All @@ -139,7 +129,7 @@ class MyApp : Application(){
}
```

##### java:
##### Java:

```java
public final class MyApp extends Application {
Expand All @@ -154,8 +144,32 @@ public final class MyApp extends Application {

And from then, your app's default dispose event will be `Lifecycle.Event.ON_STOP` instead of `Lifecycle.Event.ON_DESTROY`

## Installation

Add the JitPack repository to your `build.gradle`:

```groovy
allprojects {
repositories {
maven { url "https://jitpack.io" }
}
}
```

Add the dependency to your `build.gradle`:

```groovy
dependencies {
implementation 'com.github.kizitonwose:android-disposebag:0.1.0'
}
```

## Contributing

This library is a combination of some extension functions and classes I wrote in a project of mine, improvements are welcome.

## License

Distributed under the MIT license. [See LICENSE](https://github.com/kizitonwose/android-disposebag/blob/master/LICENSE.md) for details.

[rxswift-url]: https://github.com/ReactiveX/RxSwift
Expand Down

0 comments on commit 2aa0094

Please sign in to comment.