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 and Description
    `SafeStylesBuilder()` Constructs an empty `SafeStylesBuilder`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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.