com.sun.lwuit.html
Class HTMLComponent

java.lang.Object
  com.sun.lwuit.Component
      com.sun.lwuit.Container
          com.sun.lwuit.html.HTMLComponent

All Implemented Interfaces:

Animation, ActionListener, StyleListener, AsyncDocumentRequestHandler.IOCallback

public class HTMLComponent
extends Container
implements ActionListener, AsyncDocumentRequestHandler.IOCallback

HTMLComponent is a LWUIT Component that renders HTML documents that conform to the XHTML Mobile Profile 1.0

Field Summary

Fields inherited from class com.sun.lwuit.Component

BOTTOM, BRB_CENTER_OFFSET, BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_OTHER, CENTER, LEFT, RIGHT, TOP

Constructor Summary

HTMLComponent()
Constructs HTMLComponent

HTMLComponent(DocumentRequestHandler handler)
Constructs HTMLComponent

Method Summary

void	actionPerformed(ActionEvent evt) Invoked when an action occurred on a component
void	addCharEntitiesRange(java.lang.String[] symbols, int startcode) Adds the given symbols array to the user defined char entities table with the startcode provided as the code of the first string, startcode+1 for the second etc.
void	addCharEntity(java.lang.String symbol, int code) Adds the given symbol and code to the user defined char entities table.
static void	addFont(java.lang.String fontKey, Font font) Sets the given LWUIT font for use with HTMLComponents.
static void	addSpecialKey(java.lang.String specialKeyName, int specialKeyCode) Adds support for a special key to be used as an accesskey.
boolean	animate() Allows the animation to reduce "repaint" calls when it returns false.
void	cancel() Cancels the loading of the current page
protected void	deinitialize() If the component is taken off for any reason, makes sure access keys are not active
DocumentInfo	getDocumentInfo() Returns the DocumentInfo that currently represents the document loaded/shown
HTMLElement	getDOM() Returns the DOM representing this document
HTMLCallback	getHTMLCallback() Returns the HTMLCallback that is set on this HTMLComponent
int	getPageStatus() Returns the page status
java.lang.String	getPageURL() Returns the page's URL
java.lang.String[]	getPropertyNames() A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code
java.lang.Class[]	getPropertyTypes() Matches the property names method (see that method for further details).
java.lang.Object	getPropertyValue(java.lang.String name) Returns the current value of the property name, this method is used by the GUI builder
DocumentRequestHandler	getRequestHandler() Returns the document request handler
java.lang.String	getTitle() Returns the HTML page's title as described in its TITLE tag
protected void	initComponent() Overrides initComponent to add the key listeners to the access keys when the component is first added to the form/displayed This is useful when the component is added only after the page was read
boolean	isEventsEnabled() Returns the current status of the events enabled flag
void	layoutContainer() Performs the layout of the container if a layout is necessary
void	refreshDOM() Refreshes the current DOM so it any changes done after loading will be rendered.
void	scrollPages(int pages, boolean animate) Scrolls the HTMLComponent several pages forward/backward.
void	scrollPixels(int pixels, boolean animate) Scrolls the HTMLComponent several pixels forward/backward.
void	scrollToElement(HTMLElement element, boolean animate) Scrolls the HTMLComponent to the specified element
void	setAutoFocusOnFirstLink(boolean autoFocus) Determines whether to auto-focus on the first link after page load Note that focusing will happen only if the link is within a visible range (no scrolling is performed since this is rarely a wanted behaviour in this case)
void	setBodyText(java.lang.String htmlText) Sets the given string containing HTML code as this HTMLComponent's body
boolean	setBodyText(java.lang.String htmlText, java.lang.String encoding) Sets the given string containing HTML code as this HTMLComponent's body.
static void	setCSSSupportedMediaTypes(java.lang.String[] supportedMediaTypes) Sets the supported CSS media types to the given strings.
void	setDefaultFont(java.lang.String fontKey, Font font) Sets the default font for this HTMLComponent
void	setDOM(HTMLElement dom) Sets this HTMLComponent to render the document in the specified DOM.
void	setDOM(HTMLElement dom, java.lang.String baseURL) Sets this HTMLComponent to render the document in the specified DOM
void	setEventsEnabled(boolean enabled) Sets whether the active controls in the HTML will trigger events, and whether the DOM will change dynamically due to user input.
boolean	setHTML(java.lang.String htmlText, java.lang.String encoding, java.lang.String title, boolean isFullHTML) Sets the given string containing HTML code either as this HTMLComponent's body or as the full HTML.
void	setHTMLCallback(HTMLCallback callback) Sets an HTMLCallback to listen to this HTMLCOmponent
void	setIgnoreCSS(boolean ignore) Sets whether this HTMLComponent will ignore all CSS.directives.
static void	setMaxThreads(int threadsNum) Sets the maximum number of threads to use for image download
void	setPage(java.lang.String pageURL) Sets this HTMLComponent to render the document in the specified URL
void	setPageStyle(Style pageStyle) Sets the style of the page, allowing for example to set transparency to the main page.
void	setPageUIID(java.lang.String pageUIID) Sets the UIID of the page (the internal container) This applies not only to the current page, but rather to all pages created with this HTMLComponent instance.
void	setParser(HTMLParser parser) Sets a custom HTMLParser for this HTMLComponent By default, a new HTMLParser instance is created for each HTMLComponent, use this method if you have a custom parser.
java.lang.String	setPropertyValue(java.lang.String name, java.lang.Object value) Sets a new value to the given property, returns an error message if failed and null if successful.
void	setShowImages(boolean show) Sets whether this HTMLComponent will download and show linked images or not
void	streamReady(java.io.InputStream is, DocumentInfo docInfo) This method should be called only by AsyncDocumentRequestHandler implementations after an async fetch of a document

Methods inherited from class com.sun.lwuit.Container

addComponent, addComponent, addComponent, addComponent, animateLayout, animateLayoutAndWait, applyRTL, calcPreferredSize, contains, dragInitiated, drop, findFirstFocusable, flushReplace, getBottomGap, getComponentAt, getComponentAt, getComponentCount, getComponentIndex, getGridPosX, getGridPosY, getLayout, getLayoutHeight, getLayoutWidth, getLeadComponent, getLeadParent, getScrollIncrement, getSideGap, invalidate, isEnabled, isScrollableX, isScrollableY, keyPressed, keyReleased, paint, paintBackground, paintGlass, paramString, pointerHover, pointerPressed, refreshTheme, removeAll, removeComponent, replace, replace, replaceAndWait, replaceAndWait, replaceAndWait, revalidate, scrollComponentToVisible, setCellRenderer, setEnabled, setLayout, setLeadComponent, setScrollable, setScrollableX, setScrollableY, setScrollIncrement, setShouldCalcPreferredSize, setShouldLayout

Methods inherited from class com.sun.lwuit.Component

addFocusListener, calcScrollSize, contains, deinitializeCustomStyle, dragEnter, dragExit, draggingOver, drawDraggedImage, fireClicked, focusGained, focusLost, getAbsoluteX, getAbsoluteY, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentForm, getDirtyRegion, getDisabledStyle, getDragImage, getHeight, getLabelForComponent, getName, getNextFocusDown, getNextFocusLeft, getNextFocusRight, getNextFocusUp, getParent, getPreferredH, getPreferredSize, getPreferredW, getPressedStyle, getScrollAnimationSpeed, getScrollDimension, getScrollOpacity, getScrollOpacityChangeSpeed, getScrollX, getScrollY, getSelectCommandText, getSelectedRect, getSelectedStyle, getStyle, getTensileLength, getUIID, getUnselectedStyle, getWidth, getVisibleBounds, getX, getY, growShrink, handlesInput, hasFocus, initCustomStyle, installDefaultPainter, isAlwaysTensile, isDragActivated, isDragAndDropOperation, isDraggable, isDropTarget, isFlatten, isFocusable, isGrabsPointerEvents, isHideInPortrait, isInitialized, isRTL, isScrollable, isScrollVisible, isSelectableInteraction, isSmoothScrolling, isSnapToGrid, isTactileTouch, isTactileTouch, isTensileDragEnabled, isVisible, keyRepeated, laidOut, longKeyPress, longPointerPress, paintBackgrounds, paintBorder, paintComponent, paintComponent, paintLock, paintLockRelease, paintScrollbars, paintScrollbarX, paintScrollbarY, pointerDragged, pointerDragged, pointerHoverPressed, pointerHoverReleased, pointerPressed, pointerReleased, pointerReleased, putClientProperty, refreshTheme, removeFocusListener, repaint, repaint, requestFocus, scrollRectToVisible, scrollRectToVisible, setAlwaysTensile, setDirtyRegion, setDisabledStyle, setDraggable, setDropTarget, setFlatten, setFocus, setFocusable, setGrabsPointerEvents, setHandlesInput, setHeight, setHideInPortrait, setInitialized, setIsScrollVisible, setLabelForComponent, setName, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setPreferredH, setPreferredSize, setPreferredW, setPressedStyle, setRTL, setScrollAnimationSpeed, setScrollOpacityChangeSpeed, setScrollSize, setScrollVisible, setScrollX, setScrollY, setSelectCommandText, setSelectedStyle, setSize, setSmoothScrolling, setSnapToGrid, setTactileTouch, setTensileDragEnabled, setTensileLength, setUIID, setUnselectedStyle, setWidth, setVisible, setX, setY, styleChanged, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HTMLComponent

public HTMLComponent()

Constructs HTMLComponent

HTMLComponent

public HTMLComponent(DocumentRequestHandler handler)

Constructs HTMLComponent

Parameters:

handler - The HttpRequestHandler to which all requests for links will be sent

Method Detail

addFont

public static void addFont(java.lang.String fontKey,
                           Font font)

Sets the given LWUIT font for use with HTMLComponents. The font key can contain information about the following attributes: * The font family - i.e. Arial, Times New Roman etc. * The font size - in pixels (i.e. 12, 14 etc.) * The font style - bold, italic or both (no need to specify plain) * The font tag assignments - if this font should be used for any HTML specific tags they should be specified - i.e. h1, kbd etc. The key is just a concatenation of all attributes seperated with a dot. Examples for valid keys: arial.12 - Describes a plain font from the arial family in size 12 arial.16.bold - A bold arial font in size 16 courier.italic.bold.20 - A bold and italic courier font in size 20 arial.20.h1 - A plain arial font, size 20, that should be used for contents of the H1 tag code.kbd.samp - A font that should be used for the CODE, KBD and SAMP tags Note that the order of the attributes is not important and also that the case is ignored. This means that arial.12.bold.italic.h3 is equivalent to itALIc.H3.arial.BOLD.12 Also note that while you do not have to provide all the info for the font, but the info helps the rendering engine to reuse fonts when suitable. For example, if you have a 16px arial bold font which you want to use for H2, you can simply add it as "h2", but if you add it as "arial.16.bold.h2" then if the current font is arial.16 and the renderer encounters a B tag, it will know it can use the font you added as the bold counterpart of the current font. When adding system fonts there is no need to describe the font, the usage of setFont with system fonts is usually just to assign them for tags. The rendering engine knows to derive bold/italic/bigger/smaller fonts from other system fonts (default or tag fonts) even if not added.

Parameters:

fontKey - The font key in the format described above

font - The actual LWUIT font object

setParser

public void setParser(HTMLParser parser)

Sets a custom HTMLParser for this HTMLComponent By default, a new HTMLParser instance is created for each HTMLComponent, use this method if you have a custom parser.

Parameters:

parser - The HTMLParser to use

addCharEntity

public void addCharEntity(java.lang.String symbol,
                          int code)

Adds the given symbol and code to the user defined char entities table. Symbols do not need to include leading & and trailing ; - these will be trimmed if given as the symbol

Parameters:

symbol - The symbol to add

code - The symbol's code

addSpecialKey

public static void addSpecialKey(java.lang.String specialKeyName,
                                 int specialKeyCode)

Adds support for a special key to be used as an accesskey. The CSS property -wap-accesskey supports special keys, for example "phone-send" that may have different key codes per device. This method allows pairing between such keys to their respective key codes. Note that these keys are valid only for -wap-aceesskey in CSS files, and not for the XHTML accesskey attribute.

Parameters:

specialKeyName - The name of the special key as denoted in CSS files

specialKeyCode - The special key code

addCharEntitiesRange

public void addCharEntitiesRange(java.lang.String[] symbols,
                                 int startcode)

Adds the given symbols array to the user defined char entities table with the startcode provided as the code of the first string, startcode+1 for the second etc. Some strings in the symbols array may be null thus skipping code numbers.

Parameters:

symbols - The symbols to add

startcode - The symbol's code

setMaxThreads

public static void setMaxThreads(int threadsNum)

Sets the maximum number of threads to use for image download

Parameters:

threadsNum - the maximum number of threads to use for image download

setCSSSupportedMediaTypes

public static void setCSSSupportedMediaTypes(java.lang.String[] supportedMediaTypes)

Sets the supported CSS media types to the given strings. Usually the default media types ("all","handheld") should be suitable, but in case this runs on a device that matches another profile, the developer can specify it here.

Parameters:

supportedMediaTypes - A string array containing the media types that should be supported

getRequestHandler

public DocumentRequestHandler getRequestHandler()

Returns the document request handler

Returns:

the document request handler

getDocumentInfo

public DocumentInfo getDocumentInfo()

Returns the DocumentInfo that currently represents the document loaded/shown

Returns:

the DocumentInfo that currently represents the document loaded/shown

setHTMLCallback

public void setHTMLCallback(HTMLCallback callback)

Sets an HTMLCallback to listen to this HTMLCOmponent

Parameters:

callback - The HTMLCallback that will receive events

getHTMLCallback

public HTMLCallback getHTMLCallback()

Returns the HTMLCallback that is set on this HTMLComponent

Returns:

the HTMLCallback that is set on this HTMLComponent or null if none

setDefaultFont

public void setDefaultFont(java.lang.String fontKey,
                           Font font)

Sets the default font for this HTMLComponent

Parameters:

fontKey - The font key in the format described in setFont (Can be null for default font, but it is recommended to add a descriptive key if this is a bitmap font to enable the font engine to use it in other cases as well)

font - The actual LWUIT font object

setShowImages

public void setShowImages(boolean show)

Sets whether this HTMLComponent will download and show linked images or not

Parameters:

show - true to show images, false otherwise

setIgnoreCSS

public void setIgnoreCSS(boolean ignore)

Sets whether this HTMLComponent will ignore all CSS.directives. This includes external CSS files (which won't be downloaded), embedded CSS segmentsand style tags and attributes. By default this is false.

Parameters:

ignore - true to ignore CSS directives, false otherwise

scrollPixels

public void scrollPixels(int pixels,
                         boolean animate)

Scrolls the HTMLComponent several pixels forward/backward.

Parameters:

pixels - The number of pixels to scroll (positive for forward and negative for backward)

animate - true to animate the scrolling, false otherwise

scrollPages

public void scrollPages(int pages,
                        boolean animate)

Scrolls the HTMLComponent several pages forward/backward. TO scroll to the start or end of the document, one can provide a very big number.

Parameters:

pages - The number of pages to scroll (positive for forward and negative for backward)

animate - true to animate the scrolling, false otherwise

scrollToElement

public void scrollToElement(HTMLElement element,
                            boolean animate)

Scrolls the HTMLComponent to the specified element

Parameters:

element - The element to scroll to (must be contained in the document)

animate - true to animate the scrolling, false otherwise

Throws:

java.lang.IllegalArgumentException - if the element is not contained in the current document.

setBodyText

public void setBodyText(java.lang.String htmlText)

Sets the given string containing HTML code as this HTMLComponent's body

Parameters:

htmlText - The HTML body to set

setBodyText

public boolean setBodyText(java.lang.String htmlText,
                           java.lang.String encoding)

Sets the given string containing HTML code as this HTMLComponent's body. The string is read using the specified encoding. If the encoding is not supported it will be read without encoding

Parameters:

htmlText - The HTML body to set

encoding - The encoding to use when reading the HTML i.e. UTF8, ISO-8859-1 etc.

Returns:

true if the encoding succeeded, false otherwise

setHTML

public boolean setHTML(java.lang.String htmlText,
                       java.lang.String encoding,
                       java.lang.String title,
                       boolean isFullHTML)

Sets the given string containing HTML code either as this HTMLComponent's body or as the full HTML. The string is read using the specified encoding. If the encoding is not supported it will be read without encoding

Parameters:

htmlText - The HTML to set

encoding - The encoding to use when reading the HTML i.e. UTF8, ISO-8859-1 etc.

title - The HTML title, or null if none (Used only when isFullHTML is false)

isFullHTML - true if this is a full HTML document (with html/body tags), false if this HTML should be used as the HTMLComponent's body

Returns:

true if the encoding succeeded, false otherwise

cancel

public void cancel()

Cancels the loading of the current page

setPage

public void setPage(java.lang.String pageURL)

Sets this HTMLComponent to render the document in the specified URL

Parameters:

pageURL - The URL containing the HTML document

setPageStyle

public void setPageStyle(Style pageStyle)

Sets the style of the page, allowing for example to set transparency to the main page. This applies not only to the current page, but rather to all pages created with this HTMLComponent instance. If both a UIID and a pageStyle were set, the style overrides the UIID.

Parameters:

pageStyle - The style to set to the page

setPageUIID

public void setPageUIID(java.lang.String pageUIID)

Sets the UIID of the page (the internal container) This applies not only to the current page, but rather to all pages created with this HTMLComponent instance. If both a UIID and a pageStyle were set, the style overrides the UIID.

Parameters:

pageUIID - The UIID that should be applied to the page

streamReady

public void streamReady(java.io.InputStream is,
                        DocumentInfo docInfo)

This method should be called only by AsyncDocumentRequestHandler implementations after an async fetch of a document

Specified by:

streamReady in interface AsyncDocumentRequestHandler.IOCallback

Parameters:

is - The InputStream of the document

docInfo - The document info

setDOM

public void setDOM(HTMLElement dom)

Sets this HTMLComponent to render the document in the specified DOM. Note that relative links if any will be disabled. To allow relative links with DOM use setDOM(HTMLElement dom,String baseURL)

Parameters:

dom - An HTMLElement representing the root of the HTML document

Throws:

java.lang.IllegalArgumentException - if the HTMLElement supplied is not an 'html' tag

setDOM

public void setDOM(HTMLElement dom,
                   java.lang.String baseURL)

Sets this HTMLComponent to render the document in the specified DOM

Parameters:

dom - An HTMLElement representing the root of the HTML document

baseURL - The base URL for this DOM (Necessary if document references relative links)

Throws:

java.lang.IllegalArgumentException - if the HTMLElement supplied is not an 'html' tag

getDOM

public HTMLElement getDOM()

Returns the DOM representing this document

Returns:

An HTMLElement representing the entire current HTML document

Throws:

java.lang.IllegalStateException - if the page is still loading

refreshDOM

public void refreshDOM()

Refreshes the current DOM so it any changes done after loading will be rendered.

setEventsEnabled

public void setEventsEnabled(boolean enabled)

Sets whether the active controls in the HTML will trigger events, and whether the DOM will change dynamically due to user input. If so the events are dispatched via HTMLCallback methods actionPerformed, focusGained/Lost, selectionChanged and dataChanged The default is false in order not to add more overhead if these are not needed.

Parameters:

enabled - true to enable event dispatching, false otherwise

isEventsEnabled

public boolean isEventsEnabled()

Returns the current status of the events enabled flag

Returns:

true if events are enabled, false if not

setAutoFocusOnFirstLink

public void setAutoFocusOnFirstLink(boolean autoFocus)

Determines whether to auto-focus on the first link after page load Note that focusing will happen only if the link is within a visible range (no scrolling is performed since this is rarely a wanted behaviour in this case)

Parameters:

autoFocus - true to auto-focus, false otherwise

animate

public boolean animate()

Description copied from interface: Animation

Allows the animation to reduce "repaint" calls when it returns false. It is called once for every frame. Frames are defined by the Display class.

Specified by:

animate in interface Animation

Overrides:

animate in class Component

Returns:

true if a repaint is desired or false if no repaint is necessary

getTitle

public java.lang.String getTitle()

Returns the HTML page's title as described in its TITLE tag

Returns:

the HTML page's title as described in its TITLE tag

getPageURL

public java.lang.String getPageURL()

Returns the page's URL

Returns:

the current page's URL

getPageStatus

public int getPageStatus()

Returns the page status

Returns:

the page status (One of the STATUS_* constants in HTMLCallback)

initComponent

protected void initComponent()

Overrides initComponent to add the key listeners to the access keys when the component is first added to the form/displayed This is useful when the component is added only after the page was read

Overrides:

initComponent in class Component

deinitialize

protected void deinitialize()

If the component is taken off for any reason, makes sure access keys are not active

Overrides:

deinitialize in class Component

layoutContainer

public void layoutContainer()

Performs the layout of the container if a layout is necessary

Overrides:

layoutContainer in class Container

actionPerformed

public void actionPerformed(ActionEvent evt)

Invoked when an action occurred on a component

Specified by:

actionPerformed in interface ActionListener

Parameters:

evt - event object describing the source of the action as well as its trigger

getPropertyNames

public java.lang.String[] getPropertyNames()

Description copied from class: Component

A component may expose mutable property names for a UI designer to manipulate, this API is designed for usage internally by the GUI builder code

Overrides:

getPropertyNames in class Component

Returns:

the property names allowing mutation

getPropertyTypes

public java.lang.Class[] getPropertyTypes()

Description copied from class: Component

Matches the property names method (see that method for further details).

Overrides:

getPropertyTypes in class Component

Returns:

the types of the properties

getPropertyValue

public java.lang.Object getPropertyValue(java.lang.String name)

Description copied from class: Component

Returns the current value of the property name, this method is used by the GUI builder

Overrides:

getPropertyValue in class Component

Parameters:

name - the name of the property

Returns:

the value of said property

setPropertyValue

public java.lang.String setPropertyValue(java.lang.String name,
                                         java.lang.Object value)

Description copied from class: Component

Sets a new value to the given property, returns an error message if failed and null if successful. Notice that some builtin properties such as "$designMode" might be sent to components to indicate application state.

Overrides:

setPropertyValue in class Component

Parameters:

name - the name of the property

value - new value for the property

Returns:

error message or null