B4A Library LockScreen: Create your own lockscreen with just 5 lines of code

version 2.0 requires B4A version 3.80[Android-L compatible]

Introduction

One of the most wanted features since the birth of android is the lockscreen. After a long and exhausting 2 weeks research, I did not find a single complete functional lockscreen example that can address all aspects of a stable lockscreen. Just do a search in GitHub and you will understand what I mean.

The difficult part was the testing and as mentioned before, to address every single lockscreen system requirement with the minimum amount of complexity and code while keeping in mind that we are playing in B4A and not in eclipse. And in the end, offer the B4A community a fully encapsulated library that contains 100% of the lockscreen functionality (permissions, services, listeners, auto restart when killed, handling the keyguard and phone calls, waking/locking the device and so on) leaving you enough space for your creativity and app logic.

Latest package (library files and samples)
https://www.dropbox.com/s/ju1z09r90lx5m4g/lockscreen.zip

Compiled demos (APK)
sample1 (5LinesOfCode), sample2 (push button lockscreen), sample3 (slide button lockscreen), sample4 (sliding panel lockscreen)

upload_2014-8-6_16-30-37.png
upload_2014-7-29_9-7-47.png
upload_2014-7-29_8-56-1.png
upload_2014-7-29_8-56-15.png



Getting started
  • Extract the contents of the package anywhere in your hard disk
  • Copy the lockscreen.jar and lockscreen.xml to your B4A libraries folder
  • Explore the samples


Creating a lockscreen app with just 5 lines of code (based on samples\sample1)

Create 2 activities. One to be your main (configuration) activity and one that will be your actual lockscreen activity.

Copy the Assets folder from any of the samples folder to your project root and in the main activity's project attributes add the following lines:
B4X:
'Kitkat transparent status/navigation bars support with custom theme and DeviceAdmin XML
#AdditionalRes: ..\Assets

In the main activity's attributes add the following magic line:
B4X:
    #Extends: com.datasteam.b4a.system.lockscreen.MainActivity

In the lockscreen activity's attributes add the following magic line:
B4X:
    #Extends: com.datasteam.b4a.system.lockscreen.LockScreenActivity


Now let's write the actual code.

1. Declare a LockscreenController object in Sub Process_Globals of the Main activity
B4X:
Sub Process_Globals
    Dim Controller As LockScreenController
End Sub

2. Load the main layout
B4X:
Sub Activity_Create(FirstTime As Boolean)
    Activity.LoadLayout("Main")
End Sub

3. Drop a button in your main layout and create the click handler that will show the lockscreen
B4X:
Sub BtnPreview_Click
    StartActivity(LockScreen)
End Sub

4. Load the layout of the lockscreen activity
B4X:
Sub Activity_Create(FirstTime As Boolean)
    Activity.LoadLayout("LockScreen")
End Sub

5. Drop a button in your lockscreen layout and create the click handler that will unlock the lockscreen
B4X:
Sub BtnUnlock_Click
    Main.Controller.Unlock
End Sub


Done with just 5 lines of code!

Add the following text to your manifest to complete the setup.
IMPORTANT: In the meta-data node and in the android:value field, put the name of your lockscreen activity so that the library engine will find it and launch it when needed.
B4X:
AddPermission(android.permission.GET_TASKS)
AddPermission(android.permission.WAKE_LOCK)
AddPermission(android.permission.DISABLE_KEYGUARD)
AddPermission(android.permission.RECEIVE_BOOT_COMPLETED)
AddPermission(android.permission.READ_PHONE_STATE)

'IMPORTANT: The android:value of meta-data contains the *NAME* of your lockscreen activity!
AddApplicationText(
    <meta-data android:name="lockscreen_activity" android:value="LockScreen"/>)
SetActivityAttribute(
    LockScreen, "android:theme", "@style/Theme.Lockscreen")
AddApplicationText(
    <service android:name="com.datasteam.b4a.system.lockscreen.LockScreenService">
        <intent-filter >
            <action android:name="com.datasteam.b4a.system.lockscreen.LockScreenService" />
        </intent-filter >
    </service>)
AddApplicationText(
    <receiver android:name="com.datasteam.b4a.system.lockscreen.LockScreenDeviceAdminReceiver" android:permission="android.permission.BIND_DEVICE_ADMIN" >
        <meta-data
            android:name="android.app.device_admin"
            android:resource="@xml/lockscreen_admin" />
        <intent-filter>
            <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" />
        </intent-filter>
    </receiver>
    <receiver android:name="com.datasteam.b4a.system.lockscreen.LockScreenBootReceiver" >
       <intent-filter >
            <action android:name="android.intent.action.BOOT_COMPLETED" />
       </intent-filter>
    </receiver>)
AddApplicationText(
    <activity android:name="com.datasteam.b4a.system.lockscreen.LockScreenHomeResetActivity" android:label="HomeReset" android:theme="@android:style/Theme.NoDisplay" android:enabled="false" android:taskAffinity="" android:stateNotNeeded="true" android:excludeFromRecents="true" android:launchMode="singleTask" android:configChanges="keyboard|keyboardHidden|orientation">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.HOME" />
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>)
AddApplicationText(
    <activity android:name="com.datasteam.b4a.system.lockscreen.LockScreenHomeActivity" android:theme="@android:style/Theme.NoDisplay" android:enabled="false" android:taskAffinity="" android:stateNotNeeded="true" android:excludeFromRecents="true" android:configChanges="keyboard|keyboardHidden|orientation" android:label="$LABEL$ Launcher">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.HOME" />
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>)

That's all! Run your project and see your first lockscreen app in full swing!

There is only one non-visual class exposed in the library: LockScreenController. This class will be used to enable/disable the lockscreen and save/load its settings. Explore the SlideButton and SlidePanel samples to see how it is used.

If you want to wake the device from any of your services, use the LockScreenController.Wake method and the LockScreenController.Lock method from your lockscreen activity to lock the device.

The SlidePanel sample uses the excellent ClsSlidingSidebar class (included in sample4) from [B]Informatix[/B] (Frédéric Leneuf-Magaud).

Now, go get the NotificationListener library from [B]Erel[/B] and the Clocks library from [B]Agraham[/B] (or use this nice clock trick) and you will soon have the next lockscreen app hit!


Blocking the Home Button

Well-designed and top google play store Lockscreen apps block the home button by allowing the user to set the lockscreen as the home launcher (and the lockscreen will launch the actual launcher). This method is also implemented through the LockScreenController.HomeBlockerEnabled property. See sample2 for detailed usage instructions.


Known issues

Third party lockscreens rely on the stock lockscreen when it comes for security. You can set your stock lockscreen pattern or pin security and when the 3rd party lockscreen unlocks, your stock security lockscreen will appear. Custom lockscreens disable the swipe keyguard only. There is no gain in "recreating the wheel" since stock lockscreens provide proven security.

--

That's all for now folks! :D

Version history:

2.0
  • Fixed: FC and incorrect handling of phone state changes (ringing, offhook)
  • Added: HomeBlocker functionality through LockScreenController.HomeBlockerEnabled property
  • Updated: Samples, manifest code and forum tutorial
1.1
  • Renamed: LockScreenConfigurator class renamed to LockScreenController
  • Added: LockScreenController.LockNow method which uses the DeviceAdmin Api (use the latest updated manifest code)
  • Samples updated to the latest version
1.0
  • Initial version
 
Last edited:
Top