# Interface HTMLCallback

All Superinterfaces:
  `ParserCallback`

All Known Implementing Classes:
  `Ads, DefaultHTMLCallback`

public interface HTMLCallback extends ParserCallback
HTMLCallback is used to dispatch document lifecycle events. Most methods are called on the EDT thread, except parsingError, getAutoComplete and getLinkProperties

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ERROR_CONNECTING`
  Error code denoting that a connection to the resource provider/server could not be made
  `static final int`
  `ERROR_CSS_ATTIBUTE_VALUE_INVALID`
  Error code denoting that an invalid attribute value was found in the CSS
  `static final int`
  `ERROR_CSS_ATTRIBUTE_NOT_SUPPORTED`
  Error code denoting that an unsupported CSS attribute (by XHTML-MP 1.0 standards) was found in the HTML or external CSS files
  `static final int`
  `ERROR_CSS_NO_BASE_URL`
  Error code denoting that a relative URL was referenced from a document with no base URL (A document that was loaded via setBody/setHTML/setDOM and not via setPage) In this case the return value of parsingError is not considered - parsing continues and the resource at the URL (CSS file/image) is ignored
  `static final int`
  `ERROR_CSS_NOT_FOUND`
  Error code denoting that a CSS file referenced from the HTML or from another external CSS file was not found
  `static final int`
  `ERROR_IMAGE_BAD_FORMAT`
  Error code denoting that an image referenced from the HTML could not be loaded
  `static final int`
  `ERROR_IMAGE_NOT_FOUND`
  Error code denoting that an image referenced from the HTML was not found
  `static final int`
  `ERROR_INVALID_TAG_HIERARCHY`
  Error code denoting that a tag contains tags it shouldn't, or that a tag doesn't have the parent tag it should have
  `static final int`
  `ERROR_NO_BASE_URL`
  Error code denoting that a relative URL was referenced from a document with no base URL (A document that was loaded via setBody/setHTML/setDOM and not via setPage) In this case the return value of parsingError is not considered - parsing continues and the resource at the URL (CSS file/image) is ignored
  `static final int`
  `FIELD_PASSWORD`
  A password field
  `static final int`
  `FIELD_TEXT`
  A text field
  `static final int`
  `LINK_FORBIDDEN`
  A forbidden link (not to be rendered as a link but as a regular label)
  `static final int`
  `LINK_REGULAR`
  A regular link
  `static final int`
  `LINK_VISTED`
  A link that was visited before
  `static final int`
  `STATUS_CANCELLED`
  The page loading was cancelled before it could be completed
  `static final int`
  `STATUS_COMPLETED`
  The page and all of its referenced images and CSS files were loaded completely
  `static final int`
  `STATUS_CONNECTED`
  The stream was received
  `static final int`
  `STATUS_DISPLAYED`
  The page was displayed on screen - but at this stage some images and CSS files may still be loading in the background
  `static final int`
  `STATUS_ERROR`
  The page couldn't load completely because of parsing errors
  `static final int`
  `STATUS_NONE`
  This is returned in the page status if no page has been set to the HTMLComponent
  `static final int`
  `STATUS_PARSED`
  The page was parsed
  `static final int`
  `STATUS_REDIRECTED`
  The page was redirected to another URL
  `static final int`
  `STATUS_REQUESTED`
  The page was requested from the request handler

  ### Fields inherited from interface ParserCallback

  `ERROR_ATTIBUTE_VALUE_INVALID, ERROR_ATTRIBUTE_NOT_SUPPORTED, ERROR_ENCODING, ERROR_MULTIPLE_ROOTS, ERROR_NO_CLOSE_TAG, ERROR_NO_ROOTS, ERROR_TAG_NOT_SUPPORTED, ERROR_UNEXPECTED_CHARACTER, ERROR_UNEXPECTED_TAG_CLOSING, ERROR_UNRECOGNIZED_CHAR_ENTITY`
  Modifier and Type
  Field
  Description
  `static final int`
  `ERROR_ATTIBUTE_VALUE_INVALID`
  Error code denoting that an invalid attribute value was found in the XML
  `static final int`
  `ERROR_ATTRIBUTE_NOT_SUPPORTED`
  Error code denoting that an unsupported attribute was found in the XML
  `static final int`
  `ERROR_ENCODING`
  Error code denoting that the encoding the page needed according to its charset (usually specified in the content-type response header) is unsupported in the device
  `static final int`
  `ERROR_MULTIPLE_ROOTS`
  Error code denoting that the document had more than one root element
  `static final int`
  `ERROR_NO_CLOSE_TAG`
  Error code denoting that a tag was not closed properly in the XML
  `static final int`
  `ERROR_NO_ROOTS`
  Error code denoting that the document had no root element at all (empty document or seriously malformed XML)
  `static final int`
  `ERROR_TAG_NOT_SUPPORTED`
  Error code denoting that an unsupported tag was found in the XML
  `static final int`
  `ERROR_UNEXPECTED_CHARACTER`
  Error code denoting that the parser bumped into an unexpected character
  `static final int`
  `ERROR_UNEXPECTED_TAG_CLOSING`
  Error code denoting that a tag was not closed prematurely
  `static final int`
  `ERROR_UNRECOGNIZED_CHAR_ENTITY`
  Error code denoting that an invalid character entity was found A character entity is XML codes that start with an ampersand and end with semicolon and denote special/reserved chars

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `actionPerformed(ActionEvent evt, HTMLComponent htmlC, HTMLElement element)`
  Called whenever an ActionEvent is triggered in one of the controls in the HTMLComponent For example, button press, checkbox/radiobutton check etc.
  `void`
  `dataChanged(int type, int index, HTMLComponent htmlC, TextField textField, HTMLElement element)`
  Called when the user types in a TextField inside the HTMLComponent This method will be called only if HTMLComponent.isEventsEnabled() is true
  `String`
  `fieldSubmitted(HTMLComponent htmlC, TextArea ta, String actionURL, String id, String value, int type, String errorMsg)`
  Called whenever a field is submitted to a form.
  `void`
  `focusGained(Component cmp, HTMLComponent htmlC, HTMLElement element)`
  Called when one of the controls in the HTMLComponent obtained focus This method will be called only if HTMLComponent.isEventsEnabled() is true
  `void`
  `focusLost(Component cmp, HTMLComponent htmlC, HTMLElement element)`
  Called when one of the controls in the HTMLComponent lost focus This method will be called only if HTMLComponent.isEventsEnabled() is true
  `String`
  `getAutoComplete(HTMLComponent htmlC, String actionURL, String id)`
  Called on form creation and enabled implementations of this method to return a value to preset in a form field.
  `int`
  `getLinkProperties(HTMLComponent htmlC, String url)`
  Returns properties about the given link to indicate to HTMLComponent how to render it Note that this method is always called NOT on the EDT thread.
  `boolean`
  `linkClicked(HTMLComponent htmlC, String url)`
  Called when a link is clicked.
  `void`
  `pageStatusChanged(HTMLComponent htmlC, int status, String url)`
  Called when the page status has been changed
  `boolean`
  `parsingError(int errorId, String tag, String attribute, String value, String description)`
  Called when encountering an error while parsing the HTML document.
  `void`
  `selectionChanged(int oldSelected, int newSelected, HTMLComponent htmlC, List list, HTMLElement element)`
  Called when the user selects an item in a List inside the HTMLComponent Note: Selection is traversing through the items - once the user has actually decided, an ActionEvent will be sent as well This method will be called only if HTMLComponent.isEventsEnabled() is true
  `void`
  `titleUpdated(HTMLComponent htmlC, String title)`
  Called when the page's title is updated

  ### Methods inherited from interface ParserCallback

  `parsingError`
  Modifier and Type
  Method
  Description
  `boolean`
  `parsingError(int errorId, String tag, String attribute, String value, String description)`
  Called when encountering an error while parsing the XML document.

- ## Field Details

  - ### ERROR_CONNECTING

    static final int ERROR_CONNECTING
    Error code denoting that a connection to the resource provider/server could not be made
    See Also:
      - Constant Field Values

  - ### ERROR_IMAGE_NOT_FOUND

    static final int ERROR_IMAGE_NOT_FOUND
    Error code denoting that an image referenced from the HTML was not found
    See Also:
      - Constant Field Values

  - ### ERROR_IMAGE_BAD_FORMAT

    static final int ERROR_IMAGE_BAD_FORMAT
    Error code denoting that an image referenced from the HTML could not be loaded
    See Also:
      - Constant Field Values

  - ### ERROR_NO_BASE_URL

    static final int ERROR_NO_BASE_URL
    Error code denoting that a relative URL was referenced from a document with no base URL (A document that was loaded via setBody/setHTML/setDOM and not via setPage) In this case the return value of parsingError is not considered - parsing continues and the resource at the URL (CSS file/image) is ignored
    See Also:
      - Constant Field Values

  - ### ERROR_INVALID_TAG_HIERARCHY

    static final int ERROR_INVALID_TAG_HIERARCHY
    Error code denoting that a tag contains tags it shouldn't, or that a tag doesn't have the parent tag it should have
    See Also:
      - Constant Field Values

  - ### STATUS_NONE

    static final int STATUS_NONE
    This is returned in the page status if no page has been set to the HTMLComponent
    See Also:
      - Constant Field Values

  - ### STATUS_ERROR

    static final int STATUS_ERROR
    The page couldn't load completely because of parsing errors
    See Also:
      - Constant Field Values

  - ### STATUS_CANCELLED

    static final int STATUS_CANCELLED
    The page loading was cancelled before it could be completed
    See Also:
      - Constant Field Values

  - ### STATUS_REQUESTED

    static final int STATUS_REQUESTED
    The page was requested from the request handler
    See Also:
      - Constant Field Values

  - ### STATUS_CONNECTED

    static final int STATUS_CONNECTED
    The stream was received
    See Also:
      - Constant Field Values

  - ### STATUS_PARSED

    static final int STATUS_PARSED
    The page was parsed
    See Also:
      - Constant Field Values

  - ### STATUS_DISPLAYED

    static final int STATUS_DISPLAYED
    The page was displayed on screen - but at this stage some images and CSS files may still be loading in the background
    See Also:
      - Constant Field Values

  - ### STATUS_COMPLETED

    static final int STATUS_COMPLETED
    The page and all of its referenced images and CSS files were loaded completely
    See Also:
      - Constant Field Values

  - ### STATUS_REDIRECTED

    static final int STATUS_REDIRECTED
    The page was redirected to another URL
    See Also:
      - Constant Field Values

  - ### FIELD_TEXT

    static final int FIELD_TEXT
    A text field
    See Also:
      - Constant Field Values

  - ### FIELD_PASSWORD

    static final int FIELD_PASSWORD
    A password field
    See Also:
      - Constant Field Values

  - ### LINK_REGULAR

    static final int LINK_REGULAR
    A regular link
    See Also:
      - Constant Field Values

  - ### LINK_VISTED

    static final int LINK_VISTED
    A link that was visited before
    See Also:
      - Constant Field Values

  - ### LINK_FORBIDDEN

    static final int LINK_FORBIDDEN
    A forbidden link (not to be rendered as a link but as a regular label)
    See Also:
      - Constant Field Values

  - ### ERROR_CSS_ATTRIBUTE_NOT_SUPPORTED

    static final int ERROR_CSS_ATTRIBUTE_NOT_SUPPORTED
    Error code denoting that an unsupported CSS attribute (by XHTML-MP 1.0 standards) was found in the HTML or external CSS files
    See Also:
      - Constant Field Values

  - ### ERROR_CSS_ATTIBUTE_VALUE_INVALID

    static final int ERROR_CSS_ATTIBUTE_VALUE_INVALID
    Error code denoting that an invalid attribute value was found in the CSS
    See Also:
      - Constant Field Values

  - ### ERROR_CSS_NOT_FOUND

    static final int ERROR_CSS_NOT_FOUND
    Error code denoting that a CSS file referenced from the HTML or from another external CSS file was not found
    See Also:
      - Constant Field Values

  - ### ERROR_CSS_NO_BASE_URL

    static final int ERROR_CSS_NO_BASE_URL
    Error code denoting that a relative URL was referenced from a document with no base URL (A document that was loaded via setBody/setHTML/setDOM and not via setPage) In this case the return value of parsingError is not considered - parsing continues and the resource at the URL (CSS file/image) is ignored
    See Also:
      - Constant Field Values

- ## Method Details

  - ### titleUpdated

    void titleUpdated(HTMLComponent htmlC, String title)

    Called when the page's title is updated

    ###### Parameters

    - `htmlC`: The HTMLComponent that triggered the event

    - `title`: The new title

  - ### pageStatusChanged

    void pageStatusChanged(HTMLComponent htmlC, int status, String url)

    Called when the page status has been changed

    ###### Parameters

    - `htmlC`: The HTMLComponent in which the status change occured

    - `status`: The new status, one of the STATUS_* constants

    - `url`: The URL of the page

  - ### fieldSubmitted

    String fieldSubmitted(HTMLComponent htmlC, TextArea ta, String actionURL, String id, String value, int type, String errorMsg)

    Called whenever a field is submitted to a form. This can be used to perform sanity checks and/or to store values for auto complete.

    ###### Parameters

    - `htmlC`: The HTMLComponent in which this event occured

    - `ta`: The TextArea/TextField of this field

    - `actionURL`: The action URL of the form

    - `id`: The ID of the field

    - `value`: The value entered

    - `type`: The type of the field, one of the FIELD_* constants

    - `errorMsg`: The error message if any error occured (i.e. input validation error) or null if no error occured

    ###### Returns

    The string to submit to the form (Should return value if nothing changed)

  - ### getAutoComplete

    String getAutoComplete(HTMLComponent htmlC, String actionURL, String id)

    Called on form creation and enabled implementations of this method to return a value to preset in a form field. This can be used to auto complete previously entered value Note that this method is always called NOT on the EDT thread.

    ###### Parameters

    - `htmlC`: The HTMLComponent in which this event occured

    - `actionURL`: The action URL of the form

    - `id`: The ID of the field

    ###### Returns

    The string to place in the indicated field

  - ### getLinkProperties

    int getLinkProperties(HTMLComponent htmlC, String url)

    Returns properties about the given link to indicate to HTMLComponent how to render it Note that this method is always called NOT on the EDT thread.

    ###### Parameters

    - `htmlC`: The HTMLComponent

    - `url`: The Link URL

    ###### Returns

    LINK_REGULAR or LINK_VISITED or LINK_FORBIDDEN or a mask of those

  - ### linkClicked

    boolean linkClicked(HTMLComponent htmlC, String url)

    Called when a link is clicked. This can be used to process links that needs additional/alternate handling than fetching an HTML.

    ###### Parameters

    - `htmlC`: The HTMLComponent

    - `url`: The Link URL

    ###### Returns

    true if regular link processing should continue, false otherwise

  - ### actionPerformed

    void actionPerformed(ActionEvent evt, HTMLComponent htmlC, HTMLElement element)

    Called whenever an ActionEvent is triggered in one of the controls in the HTMLComponent For example, button press, checkbox/radiobutton check etc. This method will be called only if HTMLComponent.isEventsEnabled() is true

    ###### Parameters

    - `evt`: The event triggered, the component can be extracted using getSource

    - `htmlC`: The HTMLComponent

    - `element`: The element associated with the component that triggered the event

  - ### focusGained

    void focusGained(Component cmp, HTMLComponent htmlC, HTMLElement element)

    Called when one of the controls in the HTMLComponent obtained focus This method will be called only if HTMLComponent.isEventsEnabled() is true

    ###### Parameters

    - `cmp`: The component that triggered the event

    - `htmlC`: The HTMLComponent

    - `element`: The element associated with the component that triggered the event

  - ### focusLost

    void focusLost(Component cmp, HTMLComponent htmlC, HTMLElement element)

    Called when one of the controls in the HTMLComponent lost focus This method will be called only if HTMLComponent.isEventsEnabled() is true

    ###### Parameters

    - `cmp`: The component that triggered the event

    - `htmlC`: The HTMLComponent

    - `element`: The element associated with the component that triggered the event

  - ### selectionChanged

    void selectionChanged(int oldSelected, int newSelected, HTMLComponent htmlC, List list, HTMLElement element)

    Called when the user selects an item in a List inside the HTMLComponent Note: Selection is traversing through the items - once the user has actually decided, an ActionEvent will be sent as well This method will be called only if HTMLComponent.isEventsEnabled() is true

    ###### Parameters

    - `oldSelected`: old selected index in list model

    - `newSelected`: new selected index in list model

    - `htmlC`: The HTMLComponent

    - `list`: The list that triggered the event (Usually a ComboBox but not always)

    - `element`: The element associated with the component that triggered the event (Should be TAG_SELECT)

  - ### dataChanged

    void dataChanged(int type, int index, HTMLComponent htmlC, TextField textField, HTMLElement element)

    Called when the user types in a TextField inside the HTMLComponent This method will be called only if HTMLComponent.isEventsEnabled() is true

    ###### Parameters

    - `type`: the type data change; REMOVED, ADDED or CHANGED

    - `index`: item index in a list model

    - `htmlC`: The HTMLComponent

    - `textField`: The TextField that triggerd the event

    - `element`: The element associated with the component that triggered the event (Should be TAG_INPUT with type text/password)

  - ### parsingError

    boolean parsingError(int errorId, String tag, String attribute, String value, String description)

    Called when encountering an error while parsing the HTML document. When implementing this, the developer should return true if the error should be ignored and the document needs to be further parsed, or false to stop parsing and issue an error to the user Note that this method is always called NOT on the EDT thread.

    ###### Parameters

    - `errorId`: The error ID, one of the ERROR_* constants

    - `tag`: The tag in which the error occured (Can be null for non-tag related errors)

    - `attribute`: The attribute in which the error occured (Can be null for non-attribute related errors)

    - `value`: The value in which the error occured (Can be null for non-value related errors)

    - `description`: A verbal description of the error

    ###### Returns

    true to continue parsing, false to stop