Package com.google.gwt.safecss.shared

## Class SafeStylesBuilder

- java.lang.Object
- - com.google.gwt.safecss.shared.SafeStylesBuilder

-     public final class SafeStylesBuilder
      extends java.lang.Object

  A builder that facilitates the building up of XSS-safe CSS attribute strings from `SafeStyles`. It is used essentially like a `StringBuilder`, but access `SafeStyles` instead of Strings.

  The accumulated XSS-safe `SafeStyles` can be obtained in the form of a `SafeStyles` via the `toSafeStyles()` method.

  This class is not thread-safe.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SafeStylesBuilder()` | Constructs an empty `SafeStylesBuilder`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `SafeStylesBuilder` | `append​(SafeStyles styles)` | Appends the contents of another `SafeStyles` object, without applying any escaping or sanitization to it.
    `SafeStylesBuilder` | `appendTrustedString​(java.lang.String styles)` | Appends `SafeStyles` constructed from a trusted string, i.e., without escaping the string.
    `SafeStylesBuilder` | `backgroundImage​(SafeUri uri)` | Append the background-image CSS property.
    `SafeStylesBuilder` | `borderStyle​(Style.BorderStyle value)` | Append the border-style CSS property.
    `SafeStylesBuilder` | `borderWidth​(double value, Style.Unit unit)` | Append the border-width css property.
    `SafeStylesBuilder` | `bottom​(double value, Style.Unit unit)` | Append the bottom css property.
    `SafeStylesBuilder` | `clear​(Style.Clear value)` | Append the 'clear' CSS property.
    `SafeStylesBuilder` | `cursor​(Style.Cursor value)` | Append the cursor CSS property.
    `SafeStylesBuilder` | `display​(Style.Display value)` | Append the display CSS property.
    `SafeStylesBuilder` | `floatprop​(Style.Float value)` | Append the float css property.
    `SafeStylesBuilder` | `fontSize​(double value, Style.Unit unit)` | Append the font-size css property.
    `SafeStylesBuilder` | `fontStyle​(Style.FontStyle value)` | Append the font-style CSS property.
    `SafeStylesBuilder` | `fontWeight​(Style.FontWeight value)` | Append the font-weight CSS property.
    `SafeStylesBuilder` | `height​(double value, Style.Unit unit)` | Append the height css property.
    `SafeStylesBuilder` | `left​(double value, Style.Unit unit)` | Append the left css property.
    `SafeStylesBuilder` | `listStyleType​(Style.ListStyleType value)` | Append the list-style-type CSS property.
    `SafeStylesBuilder` | `margin​(double value, Style.Unit unit)` | Append the margin css property.
    `SafeStylesBuilder` | `marginBottom​(double value, Style.Unit unit)` | Append the margin-bottom css property.
    `SafeStylesBuilder` | `marginLeft​(double value, Style.Unit unit)` | Append the margin-left css property.
    `SafeStylesBuilder` | `marginRight​(double value, Style.Unit unit)` | Append the margin-right css property.
    `SafeStylesBuilder` | `marginTop​(double value, Style.Unit unit)` | Append the margin-top css property.
    `SafeStylesBuilder` | `opacity​(double value)` | Append the opacity css property.
    `SafeStylesBuilder` | `overflow​(Style.Overflow value)` | Append the overflow CSS property.
    `SafeStylesBuilder` | `overflowX​(Style.Overflow value)` | Append the overflow-x CSS property.
    `SafeStylesBuilder` | `overflowY​(Style.Overflow value)` | Append the overflow-y CSS property.
    `SafeStylesBuilder` | `padding​(double value, Style.Unit unit)` | Append the padding css property.
    `SafeStylesBuilder` | `paddingBottom​(double value, Style.Unit unit)` | Append the padding-bottom css property.
    `SafeStylesBuilder` | `paddingLeft​(double value, Style.Unit unit)` | Append the padding-left css property.
    `SafeStylesBuilder` | `paddingRight​(double value, Style.Unit unit)` | Append the padding-right css property.
    `SafeStylesBuilder` | `paddingTop​(double value, Style.Unit unit)` | Append the padding-top css property.
    `SafeStylesBuilder` | `position​(Style.Position value)` | Append the position CSS property.
    `SafeStylesBuilder` | `right​(double value, Style.Unit unit)` | Append the right css property.
    `SafeStylesBuilder` | `tableLayout​(Style.TableLayout value)` | Append the table-layout CSS property.
    `SafeStylesBuilder` | `textAlign​(Style.TextAlign value)` | Append the 'text-align' CSS property.
    `SafeStylesBuilder` | `textDecoration​(Style.TextDecoration value)` | Append the text-decoration CSS property.
    `SafeStylesBuilder` | `textIndent​(double value, Style.Unit unit)` | Append the 'text-indent' CSS property.
    `SafeStylesBuilder` | `textJustify​(Style.TextJustify value)` | Append the 'text-justify' CSS3 property.
    `SafeStylesBuilder` | `textOverflow​(Style.TextOverflow value)` | Append the 'text-overflow' CSS3 property.
    `SafeStylesBuilder` | `textTransform​(Style.TextTransform value)` | Append the 'text-transform' CSS property.
    `SafeStylesBuilder` | `top​(double value, Style.Unit unit)` | Append the top css property.
    `SafeStyles` | `toSafeStyles()` | Returns the safe CSS properties accumulated in the builder as a `SafeStyles`.
    `SafeStylesBuilder` | `trustedBackgroundColor​(java.lang.String value)` | Append the trusted background color, i.e., without escaping the value.
    `SafeStylesBuilder` | `trustedBackgroundImage​(java.lang.String value)` | Append the trusted background image, i.e., without escaping the value.
    `SafeStylesBuilder` | `trustedBorderColor​(java.lang.String value)` | Append the trusted border color, i.e., without escaping the value.
    `SafeStylesBuilder` | `trustedColor​(java.lang.String value)` | Append the trusted font color, i.e., without escaping the value.
    `SafeStylesBuilder` | `trustedNameAndValue​(java.lang.String name, double value, Style.Unit unit)` | Append a `SafeStyles` constructed from a trusted name and a trusted value, i.e., without escaping the name and value.
    `SafeStylesBuilder` | `trustedNameAndValue​(java.lang.String name, java.lang.String value)` | Append a `SafeStyles` constructed from a trusted name and a trusted value, i.e., without escaping the name and value.
    `SafeStylesBuilder` | `verticalAlign​(double value, Style.Unit unit)` | Append the vertical-align CSS property.
    `SafeStylesBuilder` | `verticalAlign​(Style.VerticalAlign value)` | Append the vertical-align CSS property.
    `SafeStylesBuilder` | `visibility​(Style.Visibility value)` | Append the visibility CSS property.
    `SafeStylesBuilder` | `whiteSpace​(Style.WhiteSpace whiteSpace)` | Append the 'white-space' CSS property.
    `SafeStylesBuilder` | `width​(double value, Style.Unit unit)` | Append the width css property.
    `SafeStylesBuilder` | `zIndex​(int value)` | Append the z-index css property.

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

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

- - ### Constructor Detail

    - #### SafeStylesBuilder

          public SafeStylesBuilder()

      Constructs an empty `SafeStylesBuilder`.

  - ### Method Detail

    - #### append

          public SafeStylesBuilder append​(SafeStyles styles)

      Appends the contents of another `SafeStyles` object, without applying any escaping or sanitization to it.
      Parameters:
        `styles` - the `SafeStyles` to append
      Returns:
        a reference to this object

    - #### appendTrustedString

          public SafeStylesBuilder appendTrustedString​(java.lang.String styles)

      Appends `SafeStyles` constructed from a trusted string, i.e., without escaping the string. Only minimal checks are performed. The calling code should be carefully reviewed to ensure the argument meets the `SafeStyles` contract.

      Generally, `SafeStyles` should be of the form `cssPropertyName:value;`, where neither the name nor the value contain malicious scripts.

      `SafeStyles` may never contain literal angle brackets. Otherwise, it could be unsafe to place a `SafeStyles` into a <style> tag (where it can't be HTML escaped). For example, if the `SafeStyles` containing " `font: 'foo <style><script>evil</script>`'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

      The following example values comply with this type's contract:

      - `width: 1em;`
      - `height:1em;`
      - `width: 1em;height: 1em;`
      - `background:url('http://url');`
      In addition, the empty string is safe for use in a CSS attribute.

      The following example values do not comply with this type's contract:

      - `background: red` (missing a trailing semi-colon)
      - `background:` (missing a value and a trailing semi-colon)
      - `1em` (missing an attribute name, which provides context for the value)
      Parameters:
        `styles` - the input String
      Returns:
        a `SafeStyles` instance

    - #### backgroundImage

          public SafeStylesBuilder backgroundImage​(SafeUri uri)

      Append the background-image CSS property.
      Parameters:
        `uri` - the URI of the background image
      See Also:
        `trustedBackgroundImage(String)`

    - #### borderStyle

          public SafeStylesBuilder borderStyle​(Style.BorderStyle value)

      Append the border-style CSS property.

    - #### borderWidth

          public SafeStylesBuilder borderWidth​(double value,
                                               Style.Unit unit)

      Append the border-width css property.

    - #### bottom

          public SafeStylesBuilder bottom​(double value,
                                          Style.Unit unit)

      Append the bottom css property.

    - #### clear

          public SafeStylesBuilder clear​(Style.Clear value)

      Append the 'clear' CSS property.

    - #### cursor

          public SafeStylesBuilder cursor​(Style.Cursor value)

      Append the cursor CSS property.

    - #### display

          public SafeStylesBuilder display​(Style.Display value)

      Append the display CSS property.

    - #### floatprop

          public SafeStylesBuilder floatprop​(Style.Float value)

      Append the float css property.

      Note: This method has the suffix "prop" to avoid Java compilation errors. The term "float" is a reserved word in Java representing the primitive float.

    - #### fontSize

          public SafeStylesBuilder fontSize​(double value,
                                            Style.Unit unit)

      Append the font-size css property.

    - #### fontStyle

          public SafeStylesBuilder fontStyle​(Style.FontStyle value)

      Append the font-style CSS property.

    - #### fontWeight

          public SafeStylesBuilder fontWeight​(Style.FontWeight value)

      Append the font-weight CSS property.

    - #### height

          public SafeStylesBuilder height​(double value,
                                          Style.Unit unit)

      Append the height css property.

    - #### left

          public SafeStylesBuilder left​(double value,
                                        Style.Unit unit)

      Append the left css property.

    - #### listStyleType

          public SafeStylesBuilder listStyleType​(Style.ListStyleType value)

      Append the list-style-type CSS property.

    - #### margin

          public SafeStylesBuilder margin​(double value,
                                          Style.Unit unit)

      Append the margin css property.

    - #### marginBottom

          public SafeStylesBuilder marginBottom​(double value,
                                                Style.Unit unit)

      Append the margin-bottom css property.

    - #### marginLeft

          public SafeStylesBuilder marginLeft​(double value,
                                              Style.Unit unit)

      Append the margin-left css property.

    - #### marginRight

          public SafeStylesBuilder marginRight​(double value,
                                               Style.Unit unit)

      Append the margin-right css property.

    - #### marginTop

          public SafeStylesBuilder marginTop​(double value,
                                             Style.Unit unit)

      Append the margin-top css property.

    - #### opacity

          public SafeStylesBuilder opacity​(double value)

      Append the opacity css property.

    - #### overflow

          public SafeStylesBuilder overflow​(Style.Overflow value)

      Append the overflow CSS property.

    - #### overflowX

          public SafeStylesBuilder overflowX​(Style.Overflow value)

      Append the overflow-x CSS property.

    - #### overflowY

          public SafeStylesBuilder overflowY​(Style.Overflow value)

      Append the overflow-y CSS property.

    - #### padding

          public SafeStylesBuilder padding​(double value,
                                           Style.Unit unit)

      Append the padding css property.

    - #### paddingBottom

          public SafeStylesBuilder paddingBottom​(double value,
                                                 Style.Unit unit)

      Append the padding-bottom css property.

    - #### paddingLeft

          public SafeStylesBuilder paddingLeft​(double value,
                                               Style.Unit unit)

      Append the padding-left css property.

    - #### paddingRight

          public SafeStylesBuilder paddingRight​(double value,
                                                Style.Unit unit)

      Append the padding-right css property.

    - #### paddingTop

          public SafeStylesBuilder paddingTop​(double value,
                                              Style.Unit unit)

      Append the padding-top css property.

    - #### position

          public SafeStylesBuilder position​(Style.Position value)

      Append the position CSS property.

    - #### right

          public SafeStylesBuilder right​(double value,
                                         Style.Unit unit)

      Append the right css property.

    - #### tableLayout

          public SafeStylesBuilder tableLayout​(Style.TableLayout value)

      Append the table-layout CSS property.

    - #### textAlign

          public SafeStylesBuilder textAlign​(Style.TextAlign value)

      Append the 'text-align' CSS property.

    - #### textDecoration

          public SafeStylesBuilder textDecoration​(Style.TextDecoration value)

      Append the text-decoration CSS property.

    - #### textIndent

          public SafeStylesBuilder textIndent​(double value,
                                              Style.Unit unit)

      Append the 'text-indent' CSS property.

    - #### textJustify

          public SafeStylesBuilder textJustify​(Style.TextJustify value)

      Append the 'text-justify' CSS3 property.

    - #### textOverflow

          public SafeStylesBuilder textOverflow​(Style.TextOverflow value)

      Append the 'text-overflow' CSS3 property.

    - #### textTransform

          public SafeStylesBuilder textTransform​(Style.TextTransform value)

      Append the 'text-transform' CSS property.

    - #### top

          public SafeStylesBuilder top​(double value,
                                       Style.Unit unit)

      Append the top css property.

    - #### toSafeStyles

          public SafeStyles toSafeStyles()

      Returns the safe CSS properties accumulated in the builder as a `SafeStyles`.
      Returns:
        a `SafeStyles` instance

    - #### trustedBackgroundColor

          public SafeStylesBuilder trustedBackgroundColor​(java.lang.String value)

      Append the trusted background color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the `SafeStyles` contract when they are composed into the form: "<name>:<value>;".

      `SafeStyles` may never contain literal angle brackets. Otherwise, it could be unsafe to place a `SafeStyles` into a <style> tag (where it can't be HTML escaped). For example, if the `SafeStyles` containing " `font: 'foo <style><script>evil</script>`'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

      Parameters:
        `value` - the property value
      Returns:
        a `SafeStyles` instance

    - #### trustedBackgroundImage

          public SafeStylesBuilder trustedBackgroundImage​(java.lang.String value)

      Append the trusted background image, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the `SafeStyles` contract when they are composed into the form: "<name>:<value>;".

      `SafeStyles` may never contain literal angle brackets. Otherwise, it could be unsafe to place a `SafeStyles` into a <style> tag (where it can't be HTML escaped). For example, if the `SafeStyles` containing " `font: 'foo <style><script>evil</script>`'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

      Parameters:
        `value` - the property value
      Returns:
        a `SafeStyles` instance
      See Also:
        `backgroundImage(SafeUri)`

    - #### trustedBorderColor

          public SafeStylesBuilder trustedBorderColor​(java.lang.String value)

      Append the trusted border color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the `SafeStyles` contract when they are composed into the form: "<name>:<value>;".

      `SafeStyles` may never contain literal angle brackets. Otherwise, it could be unsafe to place a `SafeStyles` into a <style> tag (where it can't be HTML escaped). For example, if the `SafeStyles` containing " `font: 'foo <style><script>evil</script>`'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

      Parameters:
        `value` - the property value
      Returns:
        a `SafeStyles` instance

    - #### trustedColor

          public SafeStylesBuilder trustedColor​(java.lang.String value)

      Append the trusted font color, i.e., without escaping the value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the `SafeStyles` contract when they are composed into the form: "<name>:<value>;".

      `SafeStyles` may never contain literal angle brackets. Otherwise, it could be unsafe to place a `SafeStyles` into a <style> tag (where it can't be HTML escaped). For example, if the `SafeStyles` containing " `font: 'foo <style><script>evil</script>`'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

      Parameters:
        `value` - the property value
      Returns:
        a `SafeStyles` instance

    - #### trustedNameAndValue

          public SafeStylesBuilder trustedNameAndValue​(java.lang.String name,
                                                       double value,
                                                       Style.Unit unit)

      Append a `SafeStyles` constructed from a trusted name and a trusted value, i.e., without escaping the name and value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the `SafeStyles` contract when they are composed into the form: "<name>:<value>;".

      `SafeStyles` may never contain literal angle brackets. Otherwise, it could be unsafe to place a `SafeStyles` into a <style> tag (where it can't be HTML escaped). For example, if the `SafeStyles` containing " `font: 'foo <style><script>evil</script>`'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

      The name should be in hyphenated format, not camelCase format.

      Parameters:
        `name` - the property name
        `value` - the property value
      Returns:
        a `SafeStyles` instance

    - #### trustedNameAndValue

          public SafeStylesBuilder trustedNameAndValue​(java.lang.String name,
                                                       java.lang.String value)

      Append a `SafeStyles` constructed from a trusted name and a trusted value, i.e., without escaping the name and value. No checks are performed. The calling code should be carefully reviewed to ensure the argument will satisfy the `SafeStyles` contract when they are composed into the form: "<name>:<value>;".

      `SafeStyles` may never contain literal angle brackets. Otherwise, it could be unsafe to place a `SafeStyles` into a <style> tag (where it can't be HTML escaped). For example, if the `SafeStyles` containing " `font: 'foo <style><script>evil</script>`'" is used in a style sheet in a <style> tag, this could then break out of the style context into HTML.

      The name should be in hyphenated format, not camelCase format.

      Parameters:
        `name` - the property name
        `value` - the property value
      Returns:
        a `SafeStyles` instance

    - #### verticalAlign

          public SafeStylesBuilder verticalAlign​(double value,
                                                 Style.Unit unit)

      Append the vertical-align CSS property.

    - #### verticalAlign

          public SafeStylesBuilder verticalAlign​(Style.VerticalAlign value)

      Append the vertical-align CSS property.

    - #### visibility

          public SafeStylesBuilder visibility​(Style.Visibility value)

      Append the visibility CSS property.

    - #### whiteSpace

          public SafeStylesBuilder whiteSpace​(Style.WhiteSpace whiteSpace)

      Append the 'white-space' CSS property.

    - #### width

          public SafeStylesBuilder width​(double value,
                                         Style.Unit unit)

      Append the width css property.

    - #### zIndex

          public SafeStylesBuilder zIndex​(int value)

      Append the z-index css property.