Java tutorial
/* * Copyright 2008 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.google.gwt.resources.client; import com.google.gwt.resources.ext.DefaultExtensions; import com.google.gwt.resources.ext.ResourceGeneratorType; import com.google.gwt.resources.rg.CssResourceGenerator; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Aggregates and minifies CSS stylesheets. A CssResource represents a regular * CSS file with GWT-specific at-rules. * <p> * Currently-supported accessor functions: * * <ul> * <li>{@code String someClassName();} will allow the css class * <code>.someClassName</code> to be obfuscated at runtime. The function will * return the obfuscated class name.</li> * <li>{@code <primitive numeric type or String> someDefName();} will allow * access to the values defined by {@literal @def} rules within the CSS file. * The defined value must be a raw number, a CSS length, or a percentage value * if it is to be returned as a numeric type. * </ul> * * <p> * Currently-supported rules: * * <ul> * <li>{@code @def NAME replacement-expression; .myClass background: NAME;} * Define a static constant. The replacement expression may be any CSS that * would be valid in a property value context. A {@code @def} may refer to * previously-defined rules, but no forward-references will be honored.</li> * <li>{@code @eval NAME Java-expression; .myClass background: NAME;} Define a * constant based on a Java expression.</li> * <li>{@code @external class-name, class-name, ...;} Disable obfuscation for * specific class selectors and exclude those class selectors from strictness * requirements.</li> * <li><code>{@literal @if} [!]property list of values {ruleBlock}</code> Include or * exclude CSS rules based on the value of a deferred-binding property. Also * {@code @elif} and {@code @else} follow the same pattern.<br/> * This might look like {@code @if user.agent ie6 safari ...}.</li> * <li><code>{@literal @if} (Java-expression) {ruleBlock}</code> Include or exclude * CSS rules based on a boolean Java expression.</li> * <li><code>{@literal @noflip} { rules }</code> will suppress the automatic * right-to-left transformation applied to the CSS when the module is compiled * for an RTL language.</li> * <li> * <code>{@literal @}sprite .any .selector {gwt-image: "imageResourceFunction";}</code> * . The appearance, size, and height of the sprite will be affected by any * {@link ImageResource.ImageOptions} annotations present on the related * {@link ImageResource} accessor function. Additional properties may be * specified in the rule block.</li> * <li>{@code @url NAME siblingDataResource; .myClass background: NAME * repeat-x;} Use a {@link DataResource} to generate a <code>url('...'}</code> value.</li> * </ul> * * <p> * Currently-supported CSS functions: * * <ul> * <li>{@code literal("expression")} substitutes a property value that does not * conform to CSS2 parsing rules. The escape sequences {@code \"} and {@code \\} * will be replaced with {@code "} and {@code \} respectively. * <li>{@code value("bundleFunction.someFunction[.other[...]]" [, "suffix"])} * substitute the value of a sequence of named zero-arg function invocations. An * optional suffix will be appended to the return value of the function. The * first name is resolved relative to the bundle interface passed to * {@link com.google.gwt.core.client.GWT#create(Class)}. An example: * * <pre> * .bordersTheSizeOfAnImage { * border-left: value('leftBorderImageResource.getWidth', 'px') solid blue; * } * </pre> * </li> * </ul> * * <p> * Any class selectors that do not correspond with a String accessor method in * the return type will trigger a compilation error. This ensures that the * CssResource does not contribute any unobfuscated class selectors into the * global CSS namespace. Strict mode can be disabled by annotating the * ClientBundle method declaration with {@link NotStrict}, however this is only * recommended for interacting with legacy CSS. * * <p> * Given these interfaces: * * <pre> * interface MyCss extends CssResource { * String someClass(); * } * * interface MyBundle extends ClientBundle { * {@literal @Source("my.css")} * MyCss css(); * } * </pre> * * the source CSS will fail to compile if it does not contain exactly the one * class selector defined in the MyCss type. * <p> * The {@code @external} at-rule can be used in strict mode to indicate that * certain class selectors are exempt from the strict semantics. Class selectors * marked as external will not be obfuscated and are not required to have string * accessor functions. Consider the following example in conjunction with the * above <code>MyCss</code> interface: * * <pre> * {@literal @external} .foo, .bar; * .foo .someClass .bar { .... } * </pre> * * The resulting CSS would look like: * * <pre> * .foo .A1234 .bar { .... } * </pre> * * If a <code>String foo()</code> method were defined in <code>MyCss</code>, it * would return the string value "<code>foo</code>". * <p> * The utility tool <code>com.google.gwt.resources.css.InterfaceGenerator</code> * can be used to automatically generate a Java interface from a * CssResource-compatible CSS file. * * @see <a href="http://code.google.com/p/google-web-toolkit/wiki/CssResource" * >CssResource design doc</a> */ @DefaultExtensions(value = { ".css" }) @ResourceGeneratorType(CssResourceGenerator.class) public interface CssResource extends CssResourceBase { /** * The original CSS class name specified in the resource. This allows CSS * classes that do not correspond to Java identifiers to be mapped onto * obfuscated class accessors. * * <pre> * .some-non-java-ident { background: blue; } * * interface MyCssResource extends CssResource { * {@literal @}ClassName("some-non-java-ident") * String classAccessor(); * } * </pre> */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface ClassName { String value(); } /** * Makes class selectors from other CssResource types available in the raw * source of a CssResource. String accessor methods can be referred to using * the value of the imported type's {@link ImportedWithPrefix} value. * <p> * This is an example of creating a descendant selector with two unrelated * types: * * <pre> *{@literal @ImportedWithPrefix}("some-prefix") * interface ToImport extends CssResource { * String widget(); * } * *{@literal @ImportedWithPrefix}("other-import") * interface OtherImport extends CssResource { * String widget(); * } * * interface Resources extends ClientBundle { * {@literal @Import}(value = {ToImport.class, OtherImport.class}) * {@literal @Source}("my.css") * CssResource usesImports(); * } * * my.css: * // Now I can refer to these classes defined elsewhere with no * // fear of name collisions * .some-prefix-widget .other-import-widget {...} * </pre> * * If the imported CssResource type is lacking an {@link ImportedWithPrefix} * annotation, the simple name of the type will be used instead. In the above * example, without the annotation on <code>ToImport</code>, the class * selector would have been <code>.ToImport-widget</code>. Notice also that * both interfaces defined a method called <code>widget()</code>, which would * prevent meaningful composition of the original interfaces. * <p> * It is an error to import multiple classes with the same prefix into one * CssResource. */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface Import { Class<? extends CssResource>[] value(); } /** * Specifies the string prefix to use when one CssResource is imported into * the scope of another CssResource. * * @see Import */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface ImportedWithPrefix { String value(); } /** * The presence of this annotation on a CssResource accessor method indicates * that any class selectors that do not correspond with a String accessor * method in the return type or an {@code @external} declaration should not * trigger a compilation error. This annotation is not recommended for new * code. * * <pre> * interface Resources extends ClientBundle { * {@literal @NotStrict} * {@literal @Source}("legacy.css") * CssResource css(); * } * </pre> */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface NotStrict { } /** * Indicates that the String accessor methods defined in a CssResource will * return the same values across all implementations of that type. * <p> * This is an example of "stateful" class selectors being used: * * <pre> *{@literal @Shared} * interface FocusCss extends CssResource { * String focused(); * String unfocused(); * } * * interface PanelCss extends CssResource, FocusCss { * String widget(); * } * * interface InputCss extends CssResource, FocusCss { * String widget(); * } * * input.css: * *.focused .widget {border: thin solid blue;} * * Application.java: * myPanel.add(myInputWidget); * myPanel.addStyleName(instanceOfPanelCss.focused()); * </pre> * * Because the <code>FocusCss</code> interface is tagged with {@code @Shared}, * the <code>focused()</code> method on the instance of <code>PanelCss</code> * will match the <code>.focused</code> parent selector in * <code>input.css</code>. * <p> * The effect of inheriting an {@code Shared} interface can be replicated by * use use of the {@link Import} annotation (e.g. {@code .FocusCss-focused * .widget}), however the use of state-bearing descendant selectors is common * enough to warrant an easier use-case. */ @Documented @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Shared { } /** * This annotation is a no-op. * * @deprecated Strict mode is now the default behavior for CssResource */ @Deprecated @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) public @interface Strict { } /** * Calls * {@link com.google.gwt.dom.client.StyleInjector#injectStylesheet(String)} to * inject the contents of the CssResource into the DOM. Repeated calls to this * method on an instance of a CssResources will have no effect. * * @return <code>true</code> if this method mutated the DOM. */ boolean ensureInjected(); /** * Provides the contents of the CssResource. */ String getText(); }