com.google.gwt.dom.client

## Class StyleInjector

- java.lang.Object
- - com.google.gwt.dom.client.StyleInjector

-     public class StyleInjector
      extends java.lang.Object

  Used to add stylesheets to the document. The one-argument versions of `inject(java.lang.String)`, `injectAtEnd(java.lang.String)`, and `injectAtStart(java.lang.String)` use `Scheduler.scheduleFinally(com.google.gwt.core.client.Scheduler.RepeatingCommand)` to minimize the number of individual style elements created.

  The api here is a bit redundant, with similarly named methods returning either `void` or `StyleElement` — e.g., `void inject(String)` v. `StyleElement injectStylesheet(String)`. The methods that return `StyleElement` are not guaranteed to work as expected on Internet Explorer. Because they are still useful to developers on other browsers they are not deprecated, but IE developers should avoid the methods with `StyleElement` return values (at least up until, and excluding, IE10).

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `StyleInjector.StyleInjectorImpl` The DOM-compatible way of adding stylesheets.
    `static class` | `StyleInjector.StyleInjectorImplIE` IE doesn't allow manipulation of a style element through DOM methods.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `flush()` Flushes any pending stylesheets to the document.
    `static void` | `inject(java.lang.String css)` Add a stylesheet to the document.
    `static void` | `inject(java.lang.String css, boolean immediate)` Add a stylesheet to the document.
    `static void` | `injectAtEnd(java.lang.String css)` Add stylesheet data to the document as though it were declared after all stylesheets previously created by `inject(String)`.
    `static void` | `injectAtEnd(java.lang.String css, boolean immediate)` Add stylesheet data to the document as though it were declared after all stylesheets previously created by `inject(String)`.
    `static void` | `injectAtStart(java.lang.String css)` Add stylesheet data to the document as though it were declared before all stylesheets previously created by `inject(String)`.
    `static void` | `injectAtStart(java.lang.String css, boolean immediate)` Add stylesheet data to the document as though it were declared before all stylesheets previously created by `inject(String)`.
    `static StyleElement` | `injectStylesheet(java.lang.String contents)` Add a stylesheet to the document.
    `static StyleElement` | `injectStylesheetAtEnd(java.lang.String contents)` Add stylesheet data to the document as though it were declared after all stylesheets previously created by `injectStylesheet(String)`.
    `static StyleElement` | `injectStylesheetAtStart(java.lang.String contents)` Add stylesheet data to the document as though it were declared before any stylesheet previously created by `injectStylesheet(String)`.
    `static void` | `setContents(StyleElement style, java.lang.String contents)` Replace the contents of a previously-injected stylesheet.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### flush

          public static void flush()

      Flushes any pending stylesheets to the document.

      This can be useful if you used CssResource.ensureInjected but now in the same event loop want to measure widths based on the new styles.

      Note that calling this method excessively will decrease performance.

    - #### inject

          public static void inject(java.lang.String css)

      Add a stylesheet to the document.
      Parameters:
        `css` - the CSS contents of the stylesheet

    - #### inject

          public static void inject(java.lang.String css,
                                    boolean immediate)

      Add a stylesheet to the document.
      Parameters:
        `css` - the CSS contents of the stylesheet
        `immediate` - if `true` the DOM will be updated immediately instead of just before returning to the event loop. Using this option excessively will decrease performance, especially if used with an inject-css-on-init coding pattern

    - #### injectAtEnd

          public static void injectAtEnd(java.lang.String css)

      Add stylesheet data to the document as though it were declared after all stylesheets previously created by `inject(String)`.
      Parameters:
        `css` - the CSS contents of the stylesheet

    - #### injectAtEnd

          public static void injectAtEnd(java.lang.String css,
                                         boolean immediate)

      Add stylesheet data to the document as though it were declared after all stylesheets previously created by `inject(String)`.
      Parameters:
        `css` - the CSS contents of the stylesheet
        `immediate` - if `true` the DOM will be updated immediately instead of just before returning to the event loop. Using this option excessively will decrease performance, especially if used with an inject-css-on-init coding pattern

    - #### injectAtStart

          public static void injectAtStart(java.lang.String css)

      Add stylesheet data to the document as though it were declared before all stylesheets previously created by `inject(String)`.
      Parameters:
        `css` - the CSS contents of the stylesheet

    - #### injectAtStart

          public static void injectAtStart(java.lang.String css,
                                           boolean immediate)

      Add stylesheet data to the document as though it were declared before all stylesheets previously created by `inject(String)`.
      Parameters:
        `css` - the CSS contents of the stylesheet
        `immediate` - if `true` the DOM will be updated immediately instead of just before returning to the event loop. Using this option excessively will decrease performance, especially if used with an inject-css-on-init coding pattern

    - #### injectStylesheet

          public static StyleElement injectStylesheet(java.lang.String contents)

      Add a stylesheet to the document.

      The returned StyleElement cannot be implemented consistently across all browsers. Specifically, applications that need to run on Internet Explorer should not use this method. Call `inject(String)` instead.

      Parameters:
        `contents` - the CSS contents of the stylesheet
      Returns:
        the StyleElement that contains the newly-injected CSS (unreliable on Internet Explorer)

    - #### injectStylesheetAtEnd

          public static StyleElement injectStylesheetAtEnd(java.lang.String contents)

      Add stylesheet data to the document as though it were declared after all stylesheets previously created by `injectStylesheet(String)`.

      The returned StyleElement cannot be implemented consistently across all browsers. Specifically, applications that need to run on Internet Explorer should not use this method. Call `injectAtEnd(String)` instead.

      Parameters:
        `contents` - the CSS contents of the stylesheet
      Returns:
        the StyleElement that contains the newly-injected CSS (unreliable on Internet Explorer)

    - #### injectStylesheetAtStart

          public static StyleElement injectStylesheetAtStart(java.lang.String contents)

      Add stylesheet data to the document as though it were declared before any stylesheet previously created by `injectStylesheet(String)`.

      The returned StyleElement cannot be implemented consistently across all browsers. Specifically, applications that need to run on Internet Explorer should not use this method. Call `injectAtStart(String, boolean)` instead.

      Parameters:
        `contents` - the CSS contents of the stylesheet
      Returns:
        the StyleElement that contains the newly-injected CSS (unreliable on Internet Explorer)

    - #### setContents

          public static void setContents(StyleElement style,
                                         java.lang.String contents)

      Replace the contents of a previously-injected stylesheet. Updating the stylesheet in-place is typically more efficient than removing a previously-created element and adding a new one.

      This method should be used with some caution as StyleInjector may recycle StyleElements on certain browsers. Specifically, applications that need to run on Internet Explorer should not use this method.

      Parameters:
        `style` - a StyleElement previously-returned from `injectStylesheet(String)`.
        `contents` - the new contents of the stylesheet.