Android Tutorial PreferenceActivity tutorial

Discussion in 'Tutorials & Examples' started by Erel, Aug 3, 2011.

  1. Erel

    Erel Administrator Staff Member Licensed User

    This tutorial explains how to use the new PreferenceActivity library. This library allows you to create the "standard" settings screen.

    The settings screen is hosted in its own activity. As this is an external activity its declaration should be manually added to the manifest file.
    I will take this opportunity to give some tips about manual modification of the manifest file which is sometimes required.

    Editing AndroidManifest.xml (general overview)
    As of Basic4android v1.8 it is no longer required to manually maintain the manifest file. Instead the manifest editor allows you to add extra elements as needed.
    See this link for more information: http://www.basic4ppc.com/forum/showthread.php?p=78136
    For PreferenceActivity you should add the following code to the manifest editor:
    Code:
    AddApplicationText(<activity android:name="anywheresoftware.b4a.objects.preferenceactivity"/>)
    Back to PreferenceActivity

    [​IMG]

    * This image was taken on a Samsung Galaxy Tab device. On other devices the screen will look a bit different based on their default style.

    PreferenceActivity library includes two main objects: PreferenceScreen and PreferenceManager.
    PreferenceScreen is responsible for building the settings UI. PreferenceManager allows you to read the settings and also modify them by code.
    Both these objects should usually be declared in Sub Process_Globals.
    The settings are saved in a file in the internal files folder. File handling is done automatically. Note that when you reinstall an application (without uninstalling it) the files are kept so the settings will also be kept.

    Each preference entry is stored as a key/value pair. The key is a string (case sensitive) and the value can be either a string or a boolean value.
    Each entry must have a unique key.

    Building the UI
    In order to build the UI we start with a PreferenceScreen object and add entries to this object directly or to PreferenceCategory which can hold other entries.
    In the above screenshot you can see a PreferenceScreen with two categories holding other entries.
    Note that a PreferenceScreen can also hold secondary PreferenceScreens. In this case when the user presses on the secondary entry a new screen will appear with its entries.
    There are three types of preference entries:
    - Checkbox
    - EditText - Opens an input dialog when the user presses on it.
    - List - Open a list dialog when the user presses on it, allowing the user to select a single item.
    The code that creates the above UI is:
    Code:
    Sub CreatePreferenceScreen
        
    screen.Initialize("Settings""")
        
    'create two categories
        Dim cat1, cat2 As PreferenceCategory
        cat1.Initialize(
    "Category 1")
        cat1.AddCheckBox(
    "check1""Checkbox1""This is Checkbox1"True)
        cat1.AddCheckBox(
    "check2""Checkbox2""This is Checkbox2"False)
        cat1.AddEditText(
    "edit1""EditText1""This is EditText1""Hello!")
      
        cat2.Initialize(
    "Category 2")
        cat2.AddList(
    "list1""List1""This is List1""Black", _
            
    Array As String("Black""Red""Green""Blue"))
          
        
    'add the categories to the main screen
        screen.AddPreferenceCategory(cat1)
        
    screen.AddPreferenceCategory(cat2)
    End Sub
    The first string in the Add methods is the entry key followed by the title, summary and default value.
    The default value is used if the key does not yet exist.

    To show the preferences we use this code:
    Code:
    Sub btn_Click
        
    StartActivity(screen.CreateIntent)
    End Sub
    Reading the settings
    Reading the settings is done with PreferenceManager.
    To retrieve the value of a specific key you should use Manager.GetString or Manager.GetBoolean with this key.
    You can get a Map with all the stored keys and values by calling Manager.GetAll
    If you want to only handle updated settings then you can call Manager.GetUpdatedKeys. This will return a List with the keys that were updated since the last call to this method.
    Usually you will want to handle settings updated in Activity_Resume. Activity_Resume will be called right after Activity_Create when you start your program and also when the user closes the preferences screen.
    Whether you want to handle all keys or just the updated keys depends on your application.

    Tip:
    The default values set in the PreferenceScreen.Add calls have no effect till the user actually sees the screen. It is recommended to explicitly set the default values if they do not already exist.
    A simple way to do it is with code similar to:
    Code:
    Sub Activity_Create(FirstTime As Boolean)
        
    If FirstTime Then
            CreatePreferenceScreen
            
    If manager.GetAll.Size = 0 Then SetDefaults
        
    End If
    End Sub

    Sub SetDefaults
        
    'defaults are only set on the first run.
        manager.SetBoolean("check1"True)
        manager.SetBoolean(
    "check2"False)
        manager.SetString(
    "edit1""Hello!")
        manager.SetString(
    "list1""Black")
    End Sub
    This way our code in Activity_Resume will work correctly whether it is the first time the program runs or after the user has closed the settings page.

    The program is attached.
     

    Attached Files:

    Last edited: Oct 13, 2013
    Mashiane, dost, GGSoft and 4 others like this.
  2. Erel

    Erel Administrator Staff Member Licensed User

    The attached file was updated. The manifest file was located in the wrong folder in the previous zip file.
     
  3. Erel

    Erel Administrator Staff Member Licensed User

    Last tip regarding the manifest file. The manifest file created each time is generated by a template. The template is located in the program folder (C:\Program Files\Anywhere Software\Basic4android) and is named AndroidManifest-template.xml.

    Changes to the template will affect all the generated manifest files. If you are working on a single project you can in some cases add the changes to the template file and then let the IDE create the manifest file automatically. It is not always possible as sometimes you need to change values which are part of the dynamic content. In the case of PreferenceActivity it is possible to apply the change to the template file and then let the IDE create it each time.
     
  4. Cableguy

    Cableguy Expert Licensed User

    This is a very good tip and leads me to a "wish"....Wich I will post on the wish thread...hehehe
     
  5. pinoy_ako

    pinoy_ako Member Licensed User

    i run the sample in htc wildfire S. it is 10minutes now but display is still "Waiting for IDE debugger to connect". :confused:
     
  6. Erel

    Erel Administrator Staff Member Licensed User

    You should either disable debugging or add the INTERNET permission to the manifest file: <uses-permission android:name="android.permission.INTERNET" />
     
  7. andrewtheart

    andrewtheart Member Licensed User

  8. nacnud

    nacnud Member Licensed User

    Quick question, as this has always bugged me about some Android apps.

    I want to see the value of the setting reflected in the settings list, and some programs do it, but, most notabley, they actual OS very rarely does. It just says something like "Vibration Intensity" and then a "tool tip" like "Set your touch feedback vibration intensity"

    It does not mention the actual value that it stored there.

    So I took your wonderful example and move the list creation stuff to the button click

    If manager.GetAll.Size = 0 Then SetDefaults
    CreatePreferenceScreen
    StartActivity(screen.CreateIntent)

    So that we always create the Activity from scratch.

    In the Create I amended a line to suck the value from the Manager

    cat2.AddList("list1", "List1", "Value(" & manager.GetString("list1") & ")", "", _
    Array As String("Black", "Red", "Green", "Blue"))

    So now I at least see (Black) or some other string.

    My question is "how do i trap the event" that says "single setting updated" so that I can update my screen as soon as the user has made a new selection? Right now I have to press "back" to go to the main screen and then press "Settings" again.

    Do you expose those kind of events?

    Thanks.
    And again, great work.:sign0142:

    Duncan
     
  9. andrewtheart

    andrewtheart Member Licensed User

    Second question - can event handlers be attached to radio boxes being selected in a PreferenceCategory?

    For instance, in the example you provided, I may want to run a custom method when I select the "Green" value in list1.

    If this is not possible, I think it should be added.
     
    bryantm1122 likes this.
  10. Erel

    Erel Administrator Staff Member Licensed User

    Currently no events are available. Events can be added in the future. However you will need to handle the events from a service as your activity is paused when the preferences are displayed. This makes it a bit cumbersome.
     
    bryantm1122 likes this.
  11. pinoy_ako

    pinoy_ako Member Licensed User

    thanks erel. i added the internet permission then i got this:
    http://i51.tinypic.com/4hf7u1.jpg

    but when i click the button, i got this:
    http://i56.tinypic.com/2mh7sdk.jpg

    i run the sample as provided. pls. advice.

    thanks erel for the support
     
  12. andrewtheart

    andrewtheart Member Licensed User

    Thanks for the info. In place of this, a settings popup menu would suffice for me - see my first post on this thread -

     
  13. andrewtheart

    andrewtheart Member Licensed User

    Did you add the string

    Code:
    <activity android:name="anywheresoftware.b4a.objects.preferenceactivity"/>
    right before the </application> line in the manifest file?

    Did you make the manifest file read-only after changing it and before compiling and running the example? If you have B4a 1.6 you can use "Do not overwrite manifest file" in the Project menu to achieve this.
     
  14. pinoy_ako

    pinoy_ako Member Licensed User

    thanks for those details andrewtheart.

    i'll try that. :sign0104:
     
  15. andrewtheart

    andrewtheart Member Licensed User

  16. Erel

    Erel Administrator Staff Member Licensed User

    I get a "page not found" from your link.
     
  17. andrewtheart

    andrewtheart Member Licensed User

    Last edited: Aug 17, 2011
  18. Erel

    Erel Administrator Staff Member Licensed User

  19. Shay

    Shay Well-Known Member Licensed User

    there is missing code and files in the zip file, can you please fix
     
  20. Erel

    Erel Administrator Staff Member Licensed User

    Which error do you get?
     
Loading...