public abstract class
ListScreen

extends Screen

Inheritance

Class Overview

ListScreen is a subclass of screen that provides a built-in ListView and convenience methods for manipulating the list directly in the screen class instead of having to call getListView() for every operation.

The ListScreen class is generic, so users who extend it should include the type of the items that will be stored in the list so that methods like add and remove will have the correct types. For example, 

 public class MyListScreen extends ListScreen<MyObject> { ...

Please see the documentation for ListView for more information on how arbitrary objects are displayed in the list.

When you subclass ListScreen, by default it will create a new ListView that occupies the entire width and height of the screen. If this is not what you want (for example, if you want to have a ListView alongside other widgets but still retain the convenience of methods like add(E) directly on the screen), then place an instance of ListView in your layout file with the ID listView. Then the ListScreen will use that view for all of its other methods instead of creating its own.

Note to developers coming from the traditional Android API: though similar, ListScreen is not a subclass of ListActivity, and it does not have exactly the same functionality or interface.

Summary

Public Constructors
ListScreen()
Public Methods
boolean add(E item)
Adds an item to the list view.
void add(int index, E item)
Inserts an item into the list view at the specified index.
boolean addAll(Collection<? extends E> collection)
Adds the items in the specified collection to the list view.
boolean addAll(int index, Collection<? extends E> collection)
Inserts the items in the specified collection into the list view at the specified index.
void clear()
Removes all items from the list view.
E get(int index)
Gets the element at the specified index from the list view.
final View getEmptyView()
Gets teh View that is displayed when there are no items in the list.
List<E> getList()
Gets the list of items that is managed by this list view.
final ListView<E> getListView()
Gets the ListView that holds all of the items on this screen.
E getSelectedItem()
Gets the currently selected item in the list view.
void refresh()
Refreshes the list view to update its contents from the list it manages.
E remove(int index)
Removes the item at the specified index from the list view.
boolean remove(E item)
Removes the specified item from the list view.
E set(int index, E item)
Replaces the element at the specified index from the list view with another item.
void setEmptyMessage(String message)

Sets an informational message that will be displayed on the screen when the list is empty.
Protected Methods
void afterLayoutInflated(boolean inflated)
This method is called after an attempted was made to inflate the screen's layout.
TextView createEmptyView(ListScreen<E> parent)

This factory method is used to create the View that will be displayed when the list is empty.

ListView<E> createListView(ListScreen<E> parent)
This factory method is used to create the ListView that will be contained by this screen.
void onResume()
Overridden to refresh the list view whenever the screen is about to be presented to the user, in case the underlying data model has changed due to actions on another screen.
Methods inherited from class sofia.app.Screen
void afterInitialize()
Called once the screen has been created and made visible.
void afterLayoutInflated(boolean inflated)
This method is called after an attempted was made to inflate the screen's layout.
void beforeInitialize()
Called before initialize() during the screen creation process.
boolean doInitializeAfterLayout()

Determines whether the user's initialize() method should be postponed until layout of the views has already occurred.

void finish(Object result)
Call this method when the current screen is finished and should be closed.
LayoutInflater getLayoutInflater()
ScreenMixin getScreenMixin()
Not intended to be called by users; this method is public as an implementation detail.
Object getSystemService(String service)
This method is overridden to replace the default Android layout inflater with one that supports Sofia's enhancements.
void initialize()
Called when the screen has been created and is about to be displayed on the device.
void log(String message)
Prints an informational message to the system log, tagged with the "User Log" tag so that it can be easily identified in the LogCat view.
void onActivityResult(int requestCode, int resultCode, Intent data)
Called when a sub-activity returns yielding a result.
void onCreate(Bundle savedInstanceState)
Called when the activity is created.
boolean onCreateOptionsMenu(Menu menu)
void onDestroy()
boolean onMenuItemSelected(int featureId, MenuItem item)
void onPause()
void onResume()
void onSaveInstanceState(Bundle bundle)
void onStop()
void presentActivity(Intent intent, String returnMethod)
Starts the activity with the specified intent.
void presentScreen(Class<? extends Activity> screenClass, Object... args)
Starts the activity represented by the specified Screen subclass and slides it into view.
void showAlertDialog(String title, String message)
Displays an alert dialog and waits for the user to dismiss it.
boolean showConfirmationDialog(String title, String message)
Displays a confirmation dialog and waits for the user to select an option.
Methods inherited from class java.lang.Object
Object clone()
boolean equals(Object arg0)
void finalize()
final Class<?> getClass()
int hashCode()
final void notify()
final void notifyAll()
String toString()
final void wait()
final void wait(long arg0, int arg1)
final void wait(long arg0)
Methods inherited from interface sofia.app.ScreenMethods
abstract void finish(Object result)
Call this method when the current screen is finished and should be closed.
abstract void presentActivity(Intent intent, String returnMethod)
Starts the activity with the specified intent.
abstract void presentScreen(Class<? extends Activity> screenClass, Object... args)
Starts the activity represented by the specified screen class and slides it into view.
abstract void showAlertDialog(String title, String message)
Displays an alert dialog and waits for the user to dismiss it.
abstract boolean showConfirmationDialog(String title, String message)
Displays a confirmation dialog and waits for the user to select an option.

Public Constructors

public ListScreen ()

Public Methods

public boolean add (E item)

Adds an item to the list view.

Parameters
item
the item to add to the list view
Returns

true if the item could be added, or false if it could not

public void add (int index, E item)

Inserts an item into the list view at the specified index.

Parameters
index
the index where the new item should be inserted
item
the item to add to the list view
Returns

true if the item could be added, or false if it could not

public boolean addAll (Collection<? extends E> collection)

Adds the items in the specified collection to the list view.

Parameters
collection
the items to add to the list view
Returns

rue if the items could be added, or false if they could not

public boolean addAll (int index, Collection<? extends E> collection)

Inserts the items in the specified collection into the list view at the specified index.

Parameters
index
the index where the new items should be inserted
collection
the items to add to the list view
Returns

true if the items could be added, or false if they could not

public void clear ()

Removes all items from the list view.

public E get (int index)

Gets the element at the specified index from the list view.

Parameters
index
the index of the item to retrieve
Returns

the item at the specified index

public final View getEmptyView ()

Gets teh View that is displayed when there are no items in the list.

Returns

The View that is displayed when there are no items in the list.

public List<E> getList ()

Gets the list of items that is managed by this list view. Changes made to the structure of the list returned by this method (that is, adding, removing, or replacing items) will be immediately reflected in the list view. You only need to explicitly refresh() the list if you make a change to an element inside the list without directly modifying the list itself.

Returns

the List of items managed by this list view

public final ListView<E> getListView ()

Gets the ListView that holds all of the items on this screen.

Returns

The ListView that holds all of the items on this screen.

public E getSelectedItem ()

Gets the currently selected item in the list view.

Returns

the currently selected item in the list view, or null if there is no item selected

public void refresh ()

Refreshes the list view to update its contents from the list it manages. This method does not need to be called after methods like add or remove -- it only needs to be called if you change a property of one of the elements in the list (for example, by calling a setter) without modifying the structure of the list itself.

public E remove (int index)

Removes the item at the specified index from the list view.

Parameters
index
the index of the item to be removed
Returns

the item that was removed

public boolean remove (E item)

Removes the specified item from the list view.

Parameters
item
the item to remove from the list view
Returns

true if the item was found and removed, or false if it was not

public E set (int index, E item)

Replaces the element at the specified index from the list view with another item.

Parameters
index
the index of the item to retrieve
item
the item to put into the list
Returns

the item previously at the specified index

public void setEmptyMessage (String message)

Sets an informational message that will be displayed on the screen when the list is empty.

It is only appropriate to call this method if the empty view is a TextView (or subclass of TextView). If the view is any other type, an exception will be thrown.

Parameters
message
the list
Throws
IllegalStateException
if the empty view is not a TextView (or subclass)

Protected Methods

protected void afterLayoutInflated (boolean inflated)

This method is called after an attempted was made to inflate the screen's layout. Most users will not need to call or override this method; it is provided for Sofia's own subclasses of Screen to support custom behavior depending on whether a user layout was provided or not.

Returns

true if a layout was found and inflated, otherwise false

protected TextView createEmptyView (ListScreen<E> parent)

This factory method is used to create the View that will be displayed when the list is empty. It is provided for subclass extensibility, in case a subclass of ListScreen wants to use a more specialized view.

The default implementation of this method creates a TextView with textAppearanceMedium, text horizontally and vertically centered, and a padding of 10 pixels.

Parameters
parent
The screen that will contain the view (e.g., "this")
Returns

A new View object to display when the list is empty.

protected ListView<E> createListView (ListScreen<E> parent)

This factory method is used to create the ListView that will be contained by this screen. It is provided for subclass extensibility, in case a subclass of ListScreen wants to use a more specialized ListView instance.

Parameters
parent
The screen that will contain the view (e.g., "this")
Returns

A new ListView object to use for this screen.

protected void onResume ()

Overridden to refresh the list view whenever the screen is about to be presented to the user, in case the underlying data model has changed due to actions on another screen.