API Docs for:
Show:

LoadingScreen Class

Defined in: loadingScreen.js:310
Module: LoadingScreen

Implements a loading screen for a webpage - that is, an opaque screen that obscures the page contents until it has finished loading, while displaying a short text message such as "Loading...".

This is implemented by adding a new <div> element to the associated document that is styled to fill the entire browser window. Any scroll bars are also disabled until the loading screen is closed.

Timeout Features

The screen features two timeout values:

  1. A close-screen button timeout which is initially hidden, but appears a number of seconds after the screen is displayed, given by the property this.close_button_timeout_in_s.
  2. A clear screen timeout after which the screen will be automatically closed. The timeout is specified as a number of seconds given by this.clear_screen_timeout_in_s.

The screen may be dismissed before the timeouts expire if the loadingIsFinished() method returns true. The default implementation of this method must be replaced to use this feature.

Typical Usage

var loading_screen = new LoadingScreen();   // applied to active document

loading_screen.default_text = "We will be with you shortly...";
loading_screen.default_bg_colour = "HotPink";
loading_screen.default_text_colour = "white";

loading_screen.loadingIsFinished = function() {
    return areAllImagesLoaded();
}

loading_screen.show();     // displays the loading screen
loading_screen.startPolling();

// ...

if( escape_key_was_pressed ) {
    // remove the loading screen in special circumstances
    // normally this method does not need to be explicitly called
    loading_screen.clear();
}

The following properties can be set to customize the behaviour of the loading screen:

  • this.default_bg_colour - the colour of the screen
  • this.default_text - the message that is displayed on the loading screen
  • this.default_text_colour - the colour of the message and close button
  • this.default_button_text - the text string that is displayed inside the close button
  • this.close_button_timeout_in_s - explained above
  • this.clear_screen_timeout_in_s - explained above
  • this.polling_frequency_in_ms - how often the timeouts are checked

Constructor

LoadingScreen

(
  • [id]
  • [doc]
)

Defined in loadingScreen.js:310

Parameters:

  • [id] Function optional

    A text id that is given to the screen's base <div> element. By default, "load_screen".

  • [doc] Function optional

    The document to which the loading screen is applied. By default, the active document.

Methods

addElementToDocument

(
  • elt_to_add
  • [id_of_elt_to_insert_before]
)
private

Defined in loadingScreen.js:564

Inserts a provided element into the associated document.

Parameters:

  • elt_to_add Element

    The Element object to add to the associated document.

  • [id_of_elt_to_insert_before] String optional

    String id of the existing element that will immediately follow the inserted element in the document order. If not specified the element is inserted at the end of the document.

clear

()

Defined in loadingScreen.js:654

Removes the loading screen from the associated document, and reinstates any scroll bars.

combineScreenElements

(
  • [text_elt]
  • [button_elt]
)
private

Defined in loadingScreen.js:407

Combines all child elements of the loading screen under a single root element, which gets returned.

Parameters:

  • [text_elt] Element optional

    A text element to use for the display text. Default is the result of calling this.createText()

  • [button_elt] Element optional

    A button element to use for the close button. Default is the result of calling this.createCloseButton()

Returns:

Root element of loading screen.

createBackground

(
  • [bg_colour]
)
private

Defined in loadingScreen.js:429

Creates the base <div> element which serves as the root of the loading screen's HTML sub-tree. The element is styled with an inline "style" attribute. The created element is returned.

Parameters:

  • [bg_colour] String optional

    CSS colour string. Defaults to value of this.default_bg_colour

Returns:

The newly-created <div> element.

createCloseButton

(
  • [pos]
  • [colour]
  • [extra_style]
  • [text]
)
private

Defined in loadingScreen.js:496

Create a new <button> element to serve as the loading Screen close button. The element is styled with an inline style attribute and returned.

Parameters:

  • [pos] List optional

    Defaults to ["50%", "50%"]. See position argument of customElementStyleString()

  • [colour] String optional

    Defaults to this.default_text_colour. See customElementStyleString()

  • [extra_style] String optional

    See extra_style argument of customElementStyleString()

  • [text] String optional

    Display text defaults to this.default_button_text.

createText

(
  • [display_text]
  • [position]
  • [text_colour]
  • [style_string]
)
private

Defined in loadingScreen.js:457

Create a new <div> element containing the display text for the loading Screen. The element is styled with an inline style attribute and returned.

Parameters:

  • [display_text] String optional

    Display text defaults to this.default_text.

  • [position] List optional

    Defaults to ["50%", "50%"]. See customElementStyleString()

  • [text_colour] String optional

    Defaults to this.default_text_colour. See colour argument of customElementStyleString()

  • [style_string] String optional

    See extra_style argument of customElementStyleString()

Returns:

The newly-created <div> element.

customElementStyleString

(
  • [position]
  • [colour]
  • [extra_style]
)
private

Defined in loadingScreen.js:536

Utility method to generate and return a valid CSS style string from the given arguments.

Parameters:

  • [position] List optional

    Position coordinates in the format [x,y], where x and y are valid CSS coordinate strings (eg. "10%" or "90px"). The position rule is omitted if not specified.

  • [colour] String optional

    CSS colour string. The colour rule is omitted if not specified.

  • [extra_style] String optional

    CSS style string is appended to the returned string if specified.

Returns:

Full CSS style string generated from the arguments.

getCloseButton

() private

Defined in loadingScreen.js:642

Utility method.

Returns:

The element implementing the loading screen close button.

pollEventHandler

() private

Defined in loadingScreen.js:606

Callback method that is invoked whever a poll event is triggered.

If the close button timeout has elapsed, this.showCloseButton() is called. If the clear screen timeout has elapsed, this.clear() is called. If this.loadingIsFinished() returns true, this.clear() is called.

setupPollEvent

() private

Defined in loadingScreen.js:592

Schedules this.pollEventHandler() to get called after a timeout given by this.polling_frequency_in_ms.

show

(
  • [id_of_element_to_insert_before]
  • [retrieve_element]
)

Defined in loadingScreen.js:385

Main method to construct and display the loading screen, and disable any scrollbars.

Parameters:

  • [id_of_element_to_insert_before] String optional

    See addElementToDocument().

  • [retrieve_element] Function optional

    A function which will return an element that will be used as the loading screen. If omitted, the loading screen element is the return value of this.combineScreenElements().

showCloseButton

() private

Defined in loadingScreen.js:630

Styles the pre-existing close button element to be visible.

startPolling

()

Defined in loadingScreen.js:582

Begins polling to check for expiration of the loading screen timeout values.