Class HTMLComponent

java.lang.Object
com.codename1.ui.Component
com.codename1.ui.Container
com.codename1.ui.html.HTMLComponent
All Implemented Interfaces:
Animation, Editable, ActionListener, StyleListener, IOCallback, Iterable<Component>
public class HTMLComponent extends Container implements ActionListener, IOCallback
HTMLComponent is a Codename One Component that renders HTML documents that conform to the XHTML Mobile Profile 1.0

  • Constructor Details

    • 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 Details

    • addFont

      public static void addFont(String fontKey, Font font)

      Sets the given Codename One 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 Codename One font object

    • addSpecialKey

      public static void addSpecialKey(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

    • 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(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

    • 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(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

    • addCharEntitiesRange

      public void addCharEntitiesRange(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

    • getRequestHandler

      public DocumentRequestHandler getRequestHandler()

      Returns the document request handler

      Returns

      the document request handler

    • setRequestHandler

      public void setRequestHandler(DocumentRequestHandler handler)

      Changes the document request handler

      Parameters
      • handler: the new 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

    • 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

    • setHTMLCallback

      public void setHTMLCallback(HTMLCallback callback)

      Sets an HTMLCallback to listen to this HTMLCOmponent

      Parameters
      • callback: The HTMLCallback that will receive events

    • setDefaultFont

      public void setDefaultFont(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 Codename One 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
      • IllegalArgumentException: if the element is not contained in the current document.

    • setBodyText

      public void setBodyText(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(String htmlText, 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(String htmlText, String encoding, 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(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(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(InputStream is, DocumentInfo docInfo)

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

      Parameters

      • is: The InputStream of the document

      • docInfo: The document info

      Specified by:
      streamReady in interface IOCallback

    • setDOM

      public void setDOM(HTMLElement dom, 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
      • 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
      • IllegalStateException: if the page is still loading

    • 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
      • IllegalArgumentException: if the HTMLElement supplied is not an 'html' tag

    • refreshDOM

      public void refreshDOM()
      Refreshes the current DOM so it any changes done after loading will be rendered.

    • isEventsEnabled

      public boolean isEventsEnabled()

      Returns the current status of the events enabled flag

      Returns

      true if events are enabled, false if not

    • 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

    • 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 class: Component

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

      Returns

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

      Specified by:
      animate in interface Animation
      Overrides:
      animate in class Component

    • getTitle

      public 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 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

      Parameters
      • evt: @param evt event object describing the source of the action as well as its trigger
      }
      Specified by:
      actionPerformed in interface ActionListener

    • getPropertyNames

      public 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

      Returns

      the property names allowing mutation

      Overrides:
      getPropertyNames in class Component

    • getPropertyTypes

      public Class[] getPropertyTypes()

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

      Returns

      the types of the properties

      Overrides:
      getPropertyTypes in class Component

    • getPropertyValue

      public Object getPropertyValue(String name)

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

      Parameters
      • name: the name of the property
      Returns

      the value of said property

      Overrides:
      getPropertyValue in class Component

    • setPropertyValue

      public String setPropertyValue(String name, Object value)

      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.

      Parameters

      • name: the name of the property

      • value: new value for the property

      Returns

      error message or null

      Overrides:
      setPropertyValue in class Component

    • isSupressExceptions

      public boolean isSupressExceptions()
      Returns

      the supressExceptions

    • setSupressExceptions

      public void setSupressExceptions(boolean supressExceptions)
      Parameters
      • supressExceptions: the supressExceptions to set