public abstract class

Screen

extends Object
implements Keys Orientation Alignment StretchMode
java.lang.Object
   ↳ com.neomades.app.Screen
Known Direct Subclasses

Class Overview

This class is the abstract base class for all screens. A Screen can be pushed to the real device screen by calling the pushScreen(Class) method. There can be only one screen showing at each time.

Screen Life cycle

Screens in the application are managed as screen stack (managed by the controller). When a new screen is started, it is placed on the top of the stack and becomes the running screen -- the previous screen always remains below it in the stack, and will not come to the foreground again until the new screen exits.

A screen has essentially four states:
  • If a screen has been created (when the controller starts to push the screen), the onCreate() is called.
  • If a screen in the foreground of the application (at the top of the stack), it is active or running. The onResume() method is called before entering in this state
  • If a screen is completely obscured by another screen (not dialog), however, it is no longer visible to the user so its window is hidden and it will often be killed by the system when memory is needed elsewhere. The onPause() method is called before entering in this state
  • If an activity has been removed from stack. The onDestroy() method is called to clean up screen

See Also

Summary

Constants
int TITLE_BAR_STYLE_BLACK iOS TitleBar style black
int TITLE_BAR_STYLE_DEFAULT iOS TitleBar style default
[Expand]
Inherited Constants
From interface com.neomades.app.Keys
From interface com.neomades.app.Orientation
From interface com.neomades.ui.Alignment
From interface com.neomades.ui.StretchMode
Fields
protected final Controller controller navigation controller
Public Constructors
Screen()
Do not call this constructor at any time.
Public Methods
Keyboard getKeyboard()

Returns a Keyboard instance for the current Screen.

void onReceiveEvent(Event event)
Called when this screen has received an event (inside UI-Thread).
void send(Event event)
Sends an event into Application's event bus.
final void setTitle(int resId)
Sets the title of the screen, which will be displayed at the top of the screen
final void setTitle(String title)
Sets the title of the screen, which will be displayed at the top of the screen.
Protected Methods
final void applyTitleBackgroundColorToStatusBar()
Configure the color of the status bar to be the same as the title bar.
View findView(int viewId)
EventBus getApplicationEventBus()
Gets the application's eventBus if exist.
View getContent()
Gets the content of this screen.
final Controller getController()
Gets the navigation Controller instance.
final int getOrientation()
Returns the current device orientation.
ScreenParams getScreenParams()
Return the parameters.
final void hideTitleBarLeftMenuItem()
Hide the default "Home" button item that appears in the left menu of the Title Bar of the first screen in the Android version of the application.
void onContentError(ContentError error)
Called when an error has been broadcasting to this screen.
void onContentResponse(ContentResponse response)
Called when a content response has been broadcasting to this screen.
abstract void onCreate()
This method has to be overridden to initialize the screen : creation and layout of UI elements, initializations, ...
void onDestroy()
This method can be overridden to provide a specific behavior when the screen is destroyed.
void onKeyEvent(KeyEvent keyEvent)
Called when a key is dispatched to a screen.
void onMenuAction(MenuItem item)
This method can be overridden to provide a specific behavior when a item of the Menu is chosen.
void onMenuCreate(Menu menu)
This method can be overridden to retrieve the menu corresponding to this screen.
void onOrientationChanged(int orientation)
Called when the screen orientation has changed.
void onPause()
This method can be overridden to provide a specific behavior when the screen is paused.
void onResume()
This method can be overridden to provide a specific behavior when the screen is resumed, after it has been paused.
void onTouchEvent(TouchEvent touchEvent)
Called when a touch is dispatched to a screen.
void postQuery(Query query)
Posts a query to a ContentManager.
void registerContentError()
Registers this screen to receive all ContentError event's type.
void registerEvent(String type)
Registers this screen to receive the given ContentResponse event's type.
void registerEvents()
This method is deprecated. Use registerContentError() instead.
void setActivityIndicatorVisible(boolean visible)
Shows or hides the activity indicator.
final void setBackButtonText(String backButtonText)
Replaces the "Back" button text for the current screen.
final void setBackButtonTextColor(Color backButtonTextColor)
Changes the "Back" button text color for the current screen.
final void setBackground(Background background)
Set the background for this screen.
final void setBackgroundColor(Color color)
Sets the background color of the screen.
final void setBackgroundImage(int imageID)
Set the background image for this screen.
final void setBackgroundImage(Image image)
Set the background image for this screen.
void setContent(int layoutResId)
Sets the content of this screen, with the root view of the layout.
void setContent(View content)
Sets the content of this screen, with the view passed in parameter.
final void setFullscreenMode(boolean fullscreen)
Hides title bar and bottom toolbar.
final void setResult(ScreenParams result)
Close the screen and send result to the ScreenResultListener.
final void setSupportedOrientation(int orientation)
Forces the screen to be in portrait and/or landscape mode.
final void setTitleBackground(Background background)
Sets the title bar background
final void setTitleBackgroundColor(Color bgColor)
Sets the title bar background color
final void setTitleBackgroundImage(Image image)
Sets the title bar background image
final void setTitleBackgroundImage(int resImage)
Sets the title bar background image
final void setTitleBarStyle(int style)
Sets the iOS title bar style
final void setTitleBarTranslucent(boolean translucent)
Sets the title bar translucent or not
final void setTitleBarVisible(boolean visible)
Set the navigation bar (iOS), action bar (Android) or title bar visible or not without animation.
final void setTitleBarVisibleAnimated(boolean visible)
Set the navigation bar (iOS), action bar (Android) or title bar visible or not with animation.
final void setTitleColor(Color titleColor)
Sets the title text color
final void setTitleFont(Font font)
Sets the title font
void setTitleKeepNativeCase(boolean enabled)
Enables or disables the title native case.
final void setTitleView(View view)
Replaces the title view (inside the title bar) with a custom View.
void unregisterEvent(String type)
Unregisters this screen to receive the given event's type.
void unregisterEvents()
Unregisters this screen to receive all event's type.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int TITLE_BAR_STYLE_BLACK

iOS TitleBar style black

Constant Value: 1 (0x00000001)

public static final int TITLE_BAR_STYLE_DEFAULT

iOS TitleBar style default

Constant Value: 0 (0x00000000)

Fields

protected final Controller controller

navigation controller

Public Constructors

public Screen ()

Do not call this constructor at any time.
DO NOT OVERRIDE THE CONSTRUCTOR

Public Methods

public Keyboard getKeyboard ()

Returns a Keyboard instance for the current Screen.

Returns
  • Keyboard a Keyboard instance

public void onReceiveEvent (Event event)

Called when this screen has received an event (inside UI-Thread).

Prefer overriding onContentResponse(ContentResponse) or onContentError(ContentError).

By default this method switches event from Content or Error.

A typical overriden method could be: 
 public void onReceiveEvent(Event event) {
 	if (event.hasType("My Type")) {
 		// do some stuff for my special events
 
 	} else {
 		// let calling onContentResponse(ContentResponse)() or
 		// onContentError(ContentError)) for other events
 		super.onReceiveEvent(event);
 	}
 }

See Also

public void send (Event event)

Sends an event into Application's event bus.

Parameters
event the event to send
See Also

public final void setTitle (int resId)

Sets the title of the screen, which will be displayed at the top of the screen

Parameters
resId the id of the string representing the new title of the screen

public final void setTitle (String title)

Sets the title of the screen, which will be displayed at the top of the screen.

If the title parameter is null or an empty String, the title bar will be hidden.

Parameters
title the new title

Protected Methods

protected final void applyTitleBackgroundColorToStatusBar ()

Configure the color of the status bar to be the same as the title bar. This is the default behavior on iOS.

protected View findView (int viewId)

Parameters
viewId the view Id declared into the XML layout set with the setContent(int) method or in the java code
Returns
  • the found view or null if not found
Throws
IllegalArgumentException the view ID has not been recognized
IllegalStateException the method has been called before setContent() method.
See Also

protected EventBus getApplicationEventBus ()

Gets the application's eventBus if exist.

Returns
  • the event bus

protected View getContent ()

Gets the content of this screen.

Returns
  • the current content, or null if there is none

protected final Controller getController ()

Gets the navigation Controller instance.

Returns
  • the navigation controller
See Also

protected final int getOrientation ()

Returns the current device orientation.

Returns
  • the current device orientation
See Also

protected ScreenParams getScreenParams ()

Return the parameters. This method will return null if called before onCreate().

Returns
  • the associated parameters or null if none
See Also

protected final void hideTitleBarLeftMenuItem ()

Hide the default "Home" button item that appears in the left menu of the Title Bar of the first screen in the Android version of the application. In iOS, hides the default "back" button in the navigation bar.

protected void onContentError (ContentError error)

Called when an error has been broadcasting to this screen. (inside a UI-Thread)

See Also

protected void onContentResponse (ContentResponse response)

Called when a content response has been broadcasting to this screen. (inside a UI-Thread)

See Also

protected abstract void onCreate ()

This method has to be overridden to initialize the screen : creation and layout of UI elements, initializations, ...

Most screen UI initializations call setContent() methods, either with a view built programmatically or a view loaded with a XML layout.

When screen is created, it is automatically registered to listen all ContentError with registerContentError() method.
Method onContentError(ContentError) will be call for each received error.

See Also

protected void onDestroy ()

This method can be overridden to provide a specific behavior when the screen is destroyed.

When screen is destroyed, it is automatically unregistered to all event types with unregisterEvents() method.

protected void onKeyEvent (KeyEvent keyEvent)

Called when a key is dispatched to a screen.

Note: If you have long operations to perform, you should make sure to do them in other threads or asynchronously.

Performing long operations such as network access may block the whole user interface. If the UI is blocked for more than a few seconds, some platforms like Android will show a message popup to inform to the end-used that the operation is too long.

Parameters
keyEvent The object containing information about the event

protected void onMenuAction (MenuItem item)

This method can be overridden to provide a specific behavior when a item of the Menu is chosen.

Parameters
item the item that has been chosen

protected void onMenuCreate (Menu menu)

This method can be overridden to retrieve the menu corresponding to this screen. In this method, you can add items to the menu.

If the menu has no children, then the menu will not be shown for this screen.

Parameters
menu the instance of the menu corresponding to this screen
See Also

protected void onOrientationChanged (int orientation)

Called when the screen orientation has changed. If the screen orientation is locked in portrait or landscape mode, onOrientationChanged(int) will not be called.

Parameters
orientation the new orientation (PORTRAIT or LANDSCAPE)

protected void onPause ()

This method can be overridden to provide a specific behavior when the screen is paused.

A screen can enter the pause state when :

  • The application is interrupted by an external event : phone call, new message, ...
  • The user has hit a special key, interrupting the application
  • The controller has pushed or popped another screen

When a dialog is shown or hidden, this method is not called.

protected void onResume ()

This method can be overridden to provide a specific behavior when the screen is resumed, after it has been paused.

  • The application is going back from an interruption : phone call, new message, ...
  • The user has hit a special key, going back to the application
  • The controller has pushed or popped another screen

When a dialog is shown or hidden, this method is not called.

protected void onTouchEvent (TouchEvent touchEvent)

Called when a touch is dispatched to a screen.

Note: If you have long operations to perform, you should make sure to do them in other threads or asynchronously.

Performing long operations such as network access may block the whole user interface. If the UI is blocked for more than a few seconds, some platforms like Android will show a message popup to inform to the end-used that the operation is too long.

Parameters
touchEvent The object containing information about the event

protected void postQuery (Query query)

Posts a query to a ContentManager.

Parameters
query the query to post
See Also

protected void registerContentError ()

Registers this screen to receive all ContentError event's type.

This method is automatically call after onCreate().

See Also

protected void registerEvent (String type)

Registers this screen to receive the given ContentResponse event's type.

Parameters
type event's type
See Also

protected void registerEvents ()

This method is deprecated.
Use registerContentError() instead.

protected void setActivityIndicatorVisible (boolean visible)

Shows or hides the activity indicator.

Parameters
visible true to show it

protected final void setBackButtonText (String backButtonText)

Replaces the "Back" button text for the current screen.

Cross Platform Considerations

On iOS it changes the left back button of the navigation bar.

On Android this method does nothing.

See Also

protected final void setBackButtonTextColor (Color backButtonTextColor)

Changes the "Back" button text color for the current screen.

Cross Platform Considerations

On iOS it changes the left back button text color of the navigation bar.

On Android this method does nothing.

See Also

protected final void setBackground (Background background)

Set the background for this screen. If the background is null, the background of the screen will be removed.

Parameters
background the background to use
Throws
CrossThreadException if the method is called from outside the UI-Thread

protected final void setBackgroundColor (Color color)

Sets the background color of the screen. If the background color is null, the background will be removed.

Parameters
color the background color of the screen
Throws
CrossThreadException if the method is called from outside the UI-Thread

protected final void setBackgroundImage (int imageID)

Set the background image for this screen.

If the size of the image is different than the screen size, then the image will be stretched in order to fill the screen's background.

You should prefer JPG image for performance reason.

Parameters
imageID the id of the image to use for the background
Throws
CrossThreadException if the method is called from outside the UI-Thread

protected final void setBackgroundImage (Image image)

Set the background image for this screen.

If the size of the image is different than the screen size, then the image will be stretched in order to fill the screen's background.

If the background image is null, the background will be removed.

Parameters
image the image to use for the background (null to remove the current background image)
Throws
CrossThreadException if the method is called from outside the UI-Thread

protected void setContent (int layoutResId)

Sets the content of this screen, with the root view of the layout.

To get a sub view of the content,

Parameters
layoutResId Resources ID of the XML layout
Throws
ResourceNotFoundException If the layout resource ID has not been recognized
See Also

protected void setContent (View content)

Sets the content of this screen, with the view passed in parameter.

If the content parameter is null, the content of this screen will be empty.

Parameters
content the content of this screen

protected final void setFullscreenMode (boolean fullscreen)

Hides title bar and bottom toolbar. Used for splashscreens. Be careful using this feature, because in iOS, the title bar (navigation bar) has back button. Hiding the title bar could avoid the end-user going to the previous screen.

Parameters
fullscreen true to enable fullscreen mode

protected final void setResult (ScreenParams result)

Close the screen and send result to the ScreenResultListener.

Parameters
result information about result
See Also

protected final void setSupportedOrientation (int orientation)

Forces the screen to be in portrait and/or landscape mode. This method does nothing if the device cannot handle orientation changing.

By default, the requested orientation is AUTO which means PORTRAIT and LANDSCAPE

Parameters
orientation the requested orientation (AUTO by default)
See Also

protected final void setTitleBackground (Background background)

Sets the title bar background

Parameters
background the background of the title bar

protected final void setTitleBackgroundColor (Color bgColor)

Sets the title bar background color

Parameters
bgColor the background color of the title bar

protected final void setTitleBackgroundImage (Image image)

Sets the title bar background image

Parameters
image the background image of the title bar

protected final void setTitleBackgroundImage (int resImage)

Sets the title bar background image

Parameters
resImage the background image of the title bar

protected final void setTitleBarStyle (int style)

Sets the iOS title bar style

Parameters
style TITLE_BAR_STYLE_DEFAULT or TITLE_BAR_STYLE_BLACK
See Also

protected final void setTitleBarTranslucent (boolean translucent)

Sets the title bar translucent or not

protected final void setTitleBarVisible (boolean visible)

Set the navigation bar (iOS), action bar (Android) or title bar visible or not without animation.

Cross Platform considerations

In Android if action bar is activated in the application (done by using setActionBarEnabled(boolean) in the application main class), it always shows and hides with animation.

Parameters
visible true to set the title bar visible

protected final void setTitleBarVisibleAnimated (boolean visible)

Set the navigation bar (iOS), action bar (Android) or title bar visible or not with animation.

Cross Platform considerations

In iOS, the layout at the root of the Screen will be stretched to match the new screen size (if in MATCH_PARENT). This will be animated too.

In Android the action bar must be activated in the application (done by using setActionBarEnabled(boolean) in the application main class).

Before Android 4.0, the action bar will display with animation but will hide without.

Parameters
visible true to set the title bar visible

protected final void setTitleColor (Color titleColor)

Sets the title text color

Parameters
titleColor the color for the title

protected final void setTitleFont (Font font)

Sets the title font

Parameters
font the font for the title

protected void setTitleKeepNativeCase (boolean enabled)

Enables or disables the title native case.

Parameters
enabled (by default the value is true).

protected final void setTitleView (View view)

Replaces the title view (inside the title bar) with a custom View.

Parameters
view a view to replace title area inside the title bar or null to let the default behaviour

protected void unregisterEvent (String type)

Unregisters this screen to receive the given event's type.

Parameters
type event's type
See Also

protected void unregisterEvents ()

Unregisters this screen to receive all event's type.

This method is automatically call before onDestroy().

See Also