This reference the explains Freestyle from a designer's perspective. It summarizes the Freestyle's CSS3 support, and the style-able iOS native controls and their properties.
Freestyle styles native iOS controls using CSS. The runtime is built on a scalable vector graphics engine, a standards-based CSS styling language, and a lightweight library for interacting with iOS native controls.
Freestyle has tailored the familiar CSS3 language for the styling needs of native mobile components. Freestyle CSS is "full CSS" with the exception of not supporting pseudo-elements and a few minor differences noted in this document.
Let's begin with an overview of a Freestyle-based application. At application start-up, Freestyle looks for your application's CSS in a file named default.css
, which can be located anywhere within your project. The default.css file can include other CSS files by using @import
.
CSS rules are applied using a control's element name
, class
, id
or other attributes. This information is represented at runtime by properties on Objective-C objects.
The element name
is determined by the type of control. For example, all UIButton controls have the button
element name. The control descriptions (see Native iOS Controls) lists the element name for each iOS control.
class
and id
are determined by the styleClass
and styleId
properties respectively of individual control instances. By convention, styleClass
is shared by all controls with a related function or layout in the application, perhaps members within the same view. styleId
is expected to be unique across the application. These conventions are not enforced by the Freestyle, and setting of these properties is not required unless you want to select controls using these properties. These properties are typically set by the application developer.
Application developers can style a specific control by setting the control's styleCSS
property. This property is analogous to the style property of web CSS.
CSS Specificity determines which rules apply to controls. Freestyle follows standard CSS specificity rules.
Tip: Specificity is not simple and is usually the reason why your CSS-rules don't apply to some controls in the way you think they should. Some excellent Specificity tutorials are available, including: CSS Specificity: Things You Should Know.
@media
rules use CSS media queries to conditionally apply styles for different devices, screen resolutions, and orientations.
The following media expressions are allowed:
Media types (e.g., 'print') are not supported. Use 'and' to join multiple media expressions.
Below are example uses of the @media
rule:
/* Rule sets apply only when the device is in portrait orientation */
@media (orientation:portrait) { }
/* Rule sets apply if the device's height (ignores orientation)
is at least 1000 pixels and if the device has a retina display. */
@media (min-device-height:1000px) and (scale:2) { }
/* Apply rules to iPad Mini in landscape mode. */
@media (orientation:landscape) and (device:ipad-mini) { }
iPod and iPhone devices appear the same and are both targeted using device:iphone. The iPad-Mini form factor is not supported in the simulator so it appears as an iPad in the simulator.
Finally, note that CSS does not support @import
statements within @media
rules.
The @import
rule allows importing style rules from other style sheets. The @import
statement must be followed by a URL that references a file within the application bundle or the device's Documents folder. The following statements are equivalent.
@import url("style.css")
@import "style.css"
Note that the @import
does not support the CSS3 @media
rule for specifying conditional style sheets or alternative style sheets. Also @import
is not supported within an @media
statement. This restriction is silently enforced.
Media assets are accessed using the url function and must be contained within the Application's bundle or on the device filesystem. Resources in the application bundle can be accessed using bundle://, files on the device are acessessed using file://, and resources in the device documents folder can be accessed using documents://. If no protocol is specified, the resources will be searched for first in the documents folder then in the resource bundle.
/* search in documents folder and application bundle for resource */
background-image: url(star.svg);
/* search for resource in a subfolder of Documents */
background-image: url(documents://myResources/star.svg);
/* search for resource in a subfolder of */
background-image: url(file://images/star.svg);
/* search for resource in application bundle */
background-image: url(bundle://star.svg);
The Freestyle engine allows you to customize some of its behavior, using CSS and a custom configuration element. You can access the configuration element by referencing it with the freestyle-config
selector. For example:
freestyle-config {
parse-error-destination: console;
cache-styles: auto;
image-cache-count: 100;
}
In the example above, adding this snippet to default.css
would send parse errors to the console, set up default cache settings, and bump the image cache count to 100 images.
Property | Value |
---|---|
parse-error-destination |
Setting it to |
cache-styles |
Used to toggle caching and to set limits for those caches. This property accepts a comma-delimited list of the preceding values. Values are processed in order and are accumulated. |
image-cache-count |
Determines how many images we be retained in the image cache, assuming it has been turned on with |
image-cache-size |
Determines how many bytes of image data are retained in the image cache. A value of |