Feature Rich Activities - The Vapor Android Framework

This section is an overview of the helpful features you will benefit from when you extend VaporActivity for the activities in Android apps you develop. The following will present an overview of what a VaporActivity can do, but it is recommended you experiment in code yourself, and check out the documentation to cement the topics discussed.

Special Variables

This section discusses a Vapor Activity's special variables that prove useful when developing your Android application with the Vapor Android framework.

$act

In a VaporActivity $act is a special final variable that gives you a handle to the surrounding VaporActivity context. This is useful in inline anonymous classes when this no longer references the activity: 

$.TextView(R.id.text).focus(new $$click(){

	public void onClick(View v){

		// Here 'this' refers to the enclosing $$click instance...
		// We use $act to refer to the enclosing VaporActivity 
		$act.someMethod();
	}
});
The $act handle refers to the enclosing activity in which you are writing code, whereas $.act() returns a handle to the current activity. These may not be the same if you use $act in a callback that lives beyond the lifetime of the referenced activity.

Lifecycle Methods

Lifecycle methods in the Vapor Android framework follow those defined in the standard Android lifecycle methods.

create(VaporBundle)

This method replaces the onCreate(Bundle) method used in the standard Android framework, and should contain your activity set up code. By the time create(VaporBundle) is called Vapor will have done several things for you:

  • Made sure the necessary System Hooks have been created in the Vapor Hook Engine, ready to be hooked in to by your code
  • Extracted the VaporBundle of extras passed to the VaporActivity, which developers can access by calling .extras()
  • Set up the VaporServiceBindable framework that allows you to quickly and easily bind to, and manage, Service connections
  • Converted the savedInstanceState bundle to a fluent VaporBundle
For event driven Android app development read about the different hooks in the System Hooks section

When .create(VaporBundle) is invoked you probably want to set your content view, which can be done by calling .contentView(...) from a VaporActivity. However you may want your activity to look different depending on whether it is running on a tablet or phone. In this case you can 'hook in' to a System Hook to receive notifications of such an event.

In the following example one of either the VaporActivity.DEVICE_TABLET hook, or the VaporActivity.DEVICE_PHONE hook will fire accordingly: 

$.hook(DEVICE_TABLET,DEVICE_PHONE).hookIn(

	new $$hookee<VaporActivity>(this){

		public void call(String hookName, VaporBundle args){

			if(hookName.equals(VaporActivity.ACT_DEVICE_TABLET))

				$.TextView(R.id.deviceCheck).text("You are using a Tablet!");

			else
				$.TextView(R.id.deviceCheck).text("You are using a Phone!");

		}

	}

);
You can check the device type at any time using the boolean methods $.phone() and $.tablet(), or $.device() that returns an int representing the device type - $.DEVICE_PHONE or $.DEVICE_TABLET

start()

This method replaces the .onStart() method used in standard the Android framework, and should contain code that will be executed when the activity is started.

pause()

This method replaces the .onPause() method used in standard the Android framework, and should contain code that will be executed when the activity is paused.

resume()

This method replaces the .onResume() method used in standard the Android framework, and should contain code that will be executed when the activity is resumed after being paused.

stop()

This method replaces the .onStop() method used in standard the Android framework, and should contain code that will be executed when the activity is stopped.

restart()

This method replaces the .onRestart() method used in the standard Android framework, and should contain code that will be executed when the activity is restarted after being stopped.

destroy()

This method replaces the .onDestroy() method used in the standard Android framework, and should contain code that will be executed when the activity is destroyed. After .destroy() is called Vapor will then:

  • Unbind all Services the VaporActivity is currently bound to
Each of the activity lifecycle methods also has an equivalent System Hook that will be fired accordingly. Read the System Hooks section for more details.

Helper Methods

This section details some of the helper methods defined in VaporActivity:

Binding To Services

VaporActivity implements VaporServiceBindable, an interface that provides a simple API for binding to, accessing, and unbinding from Services in Vapor. Check out the VaporServiceBindable section for more details.

Device Checking

VaporActivity includes three methods that deduce what kind of device the user is viewing your application on. The .device() method returns a specific int flag depending on whether the device being used is a phone or tablet - $.DEVICE_PHONE or $.DEVICE_TABLET.

You might find it more convenient to use an equivalent boolean method instead however; hence .phone() returns true if the device is deduced to be a phone, and likewise .tablet() returns true if the device is deduced to be a tablet.

At present there is no in-built support in Android for deducing device type so the Vapor Android framework makes a best guess based on various factors, such as screen size .device(), .phone() and .tablet() are equivalent to calling $.device(), $.phone(), $.tablet()

Orientation Checking

As well as the orientation hooks described in the System Hooks section, you can check the display orientation at any time using .orientation(). This will return a specific int flag depending on whether the display is portrait or landscape - $.ORIENTATION_PORTRAIT or $.ORIENTATION_LANDSCAPE.

Alternatively, you can use either of the boolean methods: .portrait(), which returns true only if the display is in portrait mode; or .landscape() which returns true only if the display is in landscape mode.

.orientation(), .portrait() and .landscape() are equivalent to calling $.orientation(), $.portrait(), $.landscape()

fullScreen(boolean)

You can set your activity to be displayed in full screen mode using .fullScreen(true)

You must call .fullScreen(true) before adding content if you want to hide the Title Bar as well

extras()

To retrieve a VaporBundle of extras that were passed to this VaporActivity use .extras(). This method is 'null-safe'; if the extras bundle passed to this activity was null the VaporBundle returned from .extras() will just contain no mapped data. You needn't check for a null return value from .extras() therefore.

Example

Below is a skeleton VaporActivity to give you an idea of what your code might look like.

You only need override the Vapor Android framework lifecycle methods you are interested in: 


    public class MyActivity extends VaporActivity{
        
        @Override
        protected void create(VaporBundle savedInstanceState){

            // set the content view, using one of the contentView(...) overloads
            contentView(R.layout.my_activity);
            
            // we can easily bind to any service
            $.bind(SomeService.class);

            // we can register to a hook we're interested in, 
            // in this case the orientation hook
            $.hook(ORIENTATION).hookIn(new $$hookee<VaporActivity>(this){
    
                public void call(String hookName, VaporBundle args){
                    ... // do something here
                }
            });

        }
    
        @Override
        protected void start() {
            ...
	    }

        @Override
	    protected void stop() {
            ...
	    }
        
        @Override
	    protected void pause() {
            ...
	    }

        @Override
	    protected void resume() {
            ...
	    }

        @Override
	    protected void restart() {
            ...
	    }

        @Override
	    protected void destroy() {
            ...
	    }
    }