org.eclipse.ercp.swt.mobile
Class MobileShell

java.lang.Object
  org.eclipse.swt.widgets.Widget
      org.eclipse.swt.widgets.Control
          org.eclipse.swt.widgets.Scrollable
              org.eclipse.swt.widgets.Composite
                  org.eclipse.swt.widgets.Canvas
                      org.eclipse.swt.widgets.Decorations
                          org.eclipse.swt.widgets.Shell
                              org.eclipse.ercp.swt.mobile.MobileShell

All Implemented Interfaces:

Drawable

public class MobileShell

extends Shell

A shell particularly suitable for devices that require dynamic change of trims at run-time.

The shell is a "top-level" window that can usually be visible and managed by the user or a window manager. Two unique features of this shell over a normal Shell are a new method changeTrim(int, int) to dynamically change Shell trim styles, and full-screen mode.

MobileShell uses the whole available application space in the normal mode. In this mode, a little screen area (title bar) is often reserved to display text with or without an icon, and optional trim information. The text shows the application name text by default. See setText(String) to change the text value and setImage(Image) to set the icon.

Outside the application screen space, mobile devices often reserve a screen space, named status area, for displaying some extra information regarding the device and other useful data. Such reserved space is usually accessable and programmable. MobileShell provides a method setStatus(String) to display text on the status area. It is up to the implementation to decide how to process the string, for example, if the content is too long to display.

Unlike a normal shell, MobileShell supports a special screen mode to use the whole device screen space, instead of the application space in the normal mode. Applications can call a method setFullScreenMode(boolean), to switch between normal and full-screen modes at run-time. This feature is often used in applications like media player and web browser, where those types of applications can request for a full-screen mode for better rendering effects.

Note: The style SWT.NO_TRIM does not force changing to full-screen mode, but is a trimming style in which usually no title bar is visible.

Trim Styles:

MobileShell inherits styles from the Shell class, including:

SHELL_TRIM

DIALOG_TRIM

NO_TRIM

TITLE

CLOSE

BORDER

Status Styles:

MobileShell introduces the concept of status pane and status pane style hints. When a status pane hint is not specified, the platform will choose a status pane style or no status pane.

NO_STATUS_PANE

SMALL_STATUS_PANE

LARGE_STATUS_PANE

See Also:

SWT.BORDER, SWT.CLOSE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, SWT.DIALOG_TRIM, SWT.MODELESS, SWT.PRIMARY_MODAL, SWT.APPLICATION_MODAL, SWT.SYSTEM_MODAL, NO_STATUS_PANE, SMALL_STATUS_PANE,

IMPORTANT: This class is not intended to be subclassed.

Field Summary

static int	LARGE_STATUS_PANE Hint show large status pane with shell
static int	NO_STATUS_PANE Hint to show no status pane
static int	SMALL_STATUS_PANE Hint to show small status pane with shell

Constructor Summary

MobileShell(Display display)
Constructs a new instance of this class given only the display to create it on.

MobileShell(Display display, int style)
Constructs a new instance of this class given the display to create it on and a style value describing its behavior and appearance.

MobileShell(Display display, int style, int statusStyle)
Constructs a new instance of this class given the display to create it on, a style value describing its behavior and appearance, and a status style describing the appearance of a status pane.

MobileShell(int style)
Constructs a new instance of this class given only the style value describing its behavior and appearance.

Method Summary

void	changeTrim(int style, int statusStyle) Changes the window trim mode.
boolean	getFullScreenMode() Gets the full-screen state.
boolean	getKeyState(int keyCode) Report whether the key has been pressed.
java.lang.String	getStatusText() Returns the status text.
void	setFullScreenMode(boolean mode) Sets the screen mode This method controls whether the shell is in normal or full-screen mode.
void	setStatusText(java.lang.String statusText) Sets the status text.

Methods inherited from class org.eclipse.swt.widgets.Shell

addShellListener, close, forceActive, getImeInputMode, getShells, open, removeShellListener, setActive, setImeInputMode

Methods inherited from class org.eclipse.swt.widgets.Decorations

getDefaultButton, getImage, getMaximized, getMenuBar, getMinimized, getText, setDefaultButton, setImage, setMaximized, setMenuBar, setMinimized, setText

Methods inherited from class org.eclipse.swt.widgets.Canvas

scroll

Methods inherited from class org.eclipse.swt.widgets.Composite

checkSubclass, getChildren, getLayout, getTabList, layout, layout, setLayout, setTabList

Methods inherited from class org.eclipse.swt.widgets.Scrollable

computeTrim, getClientArea, getHorizontalBar, getVerticalBar

Methods inherited from class org.eclipse.swt.widgets.Control

addControlListener, addFocusListener, addKeyListener, addMouseListener, addMouseMoveListener, addPaintListener, addTraverseListener, computeSize, computeSize, forceFocus, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getParent, getShell, getSize, getToolTipText, getVisible, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removePaintListener, removeTraverseListener, setBackground, setBounds, setBounds, setCapture, setEnabled, setFocus, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, update

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, setData, setData, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NO_STATUS_PANE

public static final int NO_STATUS_PANE

Hint to show no status pane

See Also:

Constant Field Values

SMALL_STATUS_PANE

public static final int SMALL_STATUS_PANE

Hint to show small status pane with shell

See Also:

Constant Field Values

LARGE_STATUS_PANE

public static final int LARGE_STATUS_PANE

Hint show large status pane with shell

See Also:

Constant Field Values

Constructor Detail

MobileShell

public MobileShell(int style)

Constructs a new instance of this class given only the style value describing its behavior and appearance. This is equivalent to calling Shell((Display) null, style).

The style value is either one of the style constants defined in class SWT which is applicable to instances of this class, or must be built by bitwise OR 'ing together (that is, using the int "|" operator) two or more of those SWT style constants. The class description lists the style constants that are applicable to the class. Style bits are also inherited from superclasses.

Parameters:

style - the style of control to construct

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

SWT.BORDER, SWT.CLOSE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, SWT.DIALOG_TRIM, SWT.MODELESS, SWT.PRIMARY_MODAL, SWT.APPLICATION_MODAL, SWT.SYSTEM_MODAL

MobileShell

public MobileShell(Display display)

Constructs a new instance of this class given only the display to create it on. It is created with style SWT.SHELL_TRIM.

Note: Currently, null can be passed in for the display argument. This has the effect of creating the shell on the currently active display if there is one. If there is no current display, the shell is created on a "default" display. Passing in null as the display argument is not considered to be good coding style, and may not be supported in a future release of SWT.

Parameters:

display - the display to create the shell on. Can be null.

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

MobileShell

public MobileShell(Display display,
                   int style)

Constructs a new instance of this class given the display to create it on and a style value describing its behavior and appearance.

The style value is either one of the style constants defined in class SWT which is applicable to instances of this class, or must be built by bitwise OR 'ing together (that is, using the int "|" operator) two or more of those SWT style constants. The class description lists the style constants that are applicable to the class. Style bits are also inherited from superclasses.

Note: Currently, null can be passed in for the display argument. This has the effect of creating the shell on the currently active display if there is one. If there is no current display, the shell is created on a "default" display. Passing in null as the display argument is not considered to be good coding style, and may not be supported in a future release of SWT.

Parameters:

display - the display to create the shell on. Can be null.

style - the style of control to construct

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

SWT.CLOSE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, SWT.DIALOG_TRIM, SWT.MODELESS, SWT.PRIMARY_MODAL, SWT.APPLICATION_MODAL, SWT.SYSTEM_MODAL

MobileShell

public MobileShell(Display display,
                   int style,
                   int statusStyle)

Constructs a new instance of this class given the display to create it on, a style value describing its behavior and appearance, and a status style describing the appearance of a status pane.

The style value is either one of the style constants defined in class SWT which is applicable to instances of this class, or must be built by bitwise OR 'ing together (that is, using the int "|" operator) two or more of those SWT style constants. The class description lists the style constants that are applicable to the class. Style bits are also inherited from superclasses.

Note: Currently, null can be passed in for the display argument. This has the effect of creating the shell on the currently active display if there is one. If there is no current display, the shell is created on a "default" display. Passing in null as the display argument is not considered to be good coding style, and may not be supported in a future release of SWT.

Parameters:

display - the display to create the shell on. Can be null.

style - the style of control to construct

statusStyle - the style of the status pane

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

SWT.CLOSE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, SWT.DIALOG_TRIM, SWT.MODELESS, SWT.PRIMARY_MODAL, SWT.APPLICATION_MODAL, SWT.SYSTEM_MODAL, NO_STATUS_PANE, SMALL_STATUS_PANE, LARGE_STATUS_PANE

Method Detail

getKeyState

public boolean getKeyState(int keyCode)

Report whether the key has been pressed. A return value of true indicates the key is pressed or has been pressed since the state of this key was last checked. A return value of false indicates the key has not been pressed since the state of this key was last checked. Only the active Shell can return true for this method. Calling this method on a Shell that is not the currently active Shell will always return false and will not clear the key's "has-been-pressed" state.

Values of keyCode that are not valid for a given platform will result in a return value of false.

An application gaining focus should call getKeyState() for each key it is nterested in polling in order to clear the key's "has-been-pressed" state.

Parameters:

keyCode - keyCode of the key to be check

Returns:

true if this shell is the active Shell and the key is pressed or has been pressed since the last time the state of this key was checked. Otherwise, return false.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setFullScreenMode

public void setFullScreenMode(boolean mode)

Sets the screen mode This method controls whether the shell is in normal or full-screen mode. If the argument is true it causes the shell to switch to the full-screen state, and if the argument is false and the shell was in full-screen state, it causes the shell to switch back to the normal state.

Parameters:

mode - the boolean value

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

changeTrim

public void changeTrim(int style,
                       int statusStyle)

Changes the window trim mode. The implementation decides how to re-layout the content if the style changes. The method will throw an IllegalArgumentException if the given style is invalid.

Parameters:

style - the trim style

statusStyle - the status pane style

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the given style is invalid

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

SWT.CLOSE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, SWT.DIALOG_TRIM, NO_STATUS_PANE, SMALL_STATUS_PANE, LARGE_STATUS_PANE

getFullScreenMode

public boolean getFullScreenMode()

Gets the full-screen state. Returns true if in full screen mode, false otherwise.

Returns:

Boolean the current screen mode.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setStatusText

public void setStatusText(java.lang.String statusText)

Sets the status text. The change will take effect immediately.

Parameters:

statusText - the status string value. It can be NULL.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getStatusText

public java.lang.String getStatusText()

Returns the status text.

Returns:

String - The current status text.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver