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

All Methods Instance Methods Concrete Methods
`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.