Navigate_Activity

• Basic Usage
• Launch Mode Settings
• Parameter Transfer And Parsing
• Intent Flag Settings
• Enter And Exit Animation Settings
• Returns And Returns Results

Basic Usage

Add the @Destination annotation to the Activity to be navigated, set the corresponding route path, and then call the navigate method and pass in the path of the destination.

@Destination(route=Destinations.DESTINATION_TEST)
class TestActivity : AppCompatActivity()

Butterfly.of(context).navigate(Destinations.DESTINATION_TEST)

The route path can be any string constant, and usually we use a format such as scheme://path/xxx as the route address

Launch Mode Settings

Just like starting Activity with Intent, Butterfly also supports setting the startup mode of Activity, which is launched using standard mode by default By calling the singleTop and clearTop methods, you can set the mode to reuse on the top of the stack or clear the top of the stack to start.

// Set to clearTop mode, and the effect is the same as Intent.addFlags (FLAG_ACTIVITY_CLEAR_TOP)
Butterfly.of(context)
    .clearTop()
    .navigate(Destinations.DESTINATION_TEST)

// Set to singleTop mode, and the effect is the same as Intent.addFlags (FLAG_ACTIVITY_SINGLE_TOP)
Butterfly.of(context)
    .singleTop()
    .navigate(Destinations.DESTINATION_TEST)

Parameter Transfer And Parsing

Butterfly supports multiple ways to pass parameters. You can bring in additional parameters in the form of splicing paths, or manually pass in parameters by calling the params method. You can either pass in parameters when calling the navigate method, or use a combination of them.

//Stitching path input parameters
Butterfly.of(this).navigate(Destinations.DESTINATION_TEST + "?a=1&b=2&c=3")

//Call the params method
Butterfly.of(this)
    .params(
        "x" to 1,
        "y" to true,
        "z" to "test value"
    )
    .navigate(Destinations.DESTINATION_TEST)

//Pass parameters when calling navigate
Butterfly.of(this)
    .navigate(
        Destinations.DESTINATION_TEST, 
        "a" to "1"
    )

//Use multiple ways at the same time
Butterfly.of(this)
    .params(
        "x" to 1,
        "y" to true,
        "z" to "test value"
    )
    .navigate(
        Destinations.DESTINATION_TEST + "?a=1&b=2&c=3", 
        "d" to "4"
    )

The priority of the above methods is: navigate > route string > params, that is, if you encounter a parameter with the same name the parameters passed through the navigate method will override the parameters in the stitching path string, and the parameters in the stitching path string will override the parameters passed through the params method.

The parameters passed in are packaged into a Bundle object and set to the Intent object that starts Activity, so you only need to parse the Intent of the Activity to get the parameters.

@Destination(route=Destinations.DESTINATION_TEST)
class TestActivity : AppCompatActivity() {
    val a by lazy { intent.getStringExtra("a") ?: "" }
    val b by lazy { intent.getStringExtra("b") ?: "" }
    val c by lazy { intent.getStringExtra("c") ?: "" }
        //...
}

In addition to parsing parameters manually, the Bracer library can also be used for intelligent parameter parsing.

@Destination(route=Destinations.DESTINATION_TEST)
class TestActivity : AppCompatActivity() {
    val a by params<String>()
    val b by params<String>()
    val c by params<String>()
}

for more information on how to use Bracer, please see GitHub: Bracer.

Intent Flag Settings

In the process of navigating Activity, you can add additional Intent Flag parameters through the addFlag method:

Butterfly.of(context)
    .addFlag(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS)
    .addFlag(Intent.FLAG_ACTIVITY_NO_HISTORY)  // Multiple Flag can be set by calling multiple times
    .navigate(Destinations.DESTINATION_TEST)

It should be noted that Butterfly needs to use the context parameter when navigating. If Application's Context is used as a parameter, Activity is navigated. The following Flag is automatically added: Intent.addFlags(FLAG_ACTIVITY_NEW_TASK) , so there is no need to add the Flag manually.

Enter And Exit Animation Settings

In the process of navigating Activity, you can add animations of Activity entry and exit through the enterAnim and exitAnim methods:

Butterfly.of(context)
    .enterAnim(R.anim.fade_in) // fade in
    .exitAnim(R.anim.fade_out)  // fade out
    .navigate(Destinations.DESTINATION_TEST)

Returns And Returns Results

After using Butterfly to navigate Activity, if you need to return, you can use the finish method of Activity or the popBack method of Butterfly for fallback.

@Destination(route = Destinations.DESTINATION_TEST)
class TestActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
      
        binding.back.setOnClickListener {
            //Directly finish the current page
            finish()
            
            //Use popBack
            Butterfly.of(this).popBack()
        }
    }
}

If you need to bring the return value with Activity when you pop back, you can pass the return value directly using popBack. Of course, you can also use the setResult method of Activity to set the return value manually.

@Destination(route = Destinations.DESTINATION_TEST)
class TestActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        binding.back.setOnClickListener {
            //Use popBack to fallback and return a value
            Butterfly.of(this).popBack("result" to "123")
        }
    }
}

The returned result will be encapsulated as a Bundle object, and the returned result can be obtained by parsing Bundle:

Butterfly.of(context).navigate(Destinations.DESTINATION_TEST) { result ->
    if (result.isSuccess) {
        val bundle = result.getOrDefault(Bundle.EMPTY)
        val result by bundle.params<String>()
        println(result)
    }
}