Custom Style Sheets

We've seen in a previous Curl Cue how to access the DEFAULT-STYLE-SHEET for use with a Curl application by importing the COM.CURL.GUI.STYLED library . The COM.CURL.GUI.STYLED library includes a basic StyleManager implementation called BasicStyleManager. This class implements "style sheets" for GUI objects in which DEFAULT-STYLE-SHEET provides basic styles that can be modified. In this case, you will need to create your own styles.

In a Curl application, you can create and use one or more style sheets files by defining StyleRules based on StyleSelectors. You can also create your these styles directly in the Curl code.

In general, the following statements are basic rules to follow:

• If two or more style sheet files are called, subsequent styles will overwrite previous style selector definitions
• Styles defined in-line (directly in the code) will take overwrite all imported style sheet files

Style Sheet Syntax

In Curl, a StyleSheet contains a set rules that implement a new look for all or some of the Curl GUI Toolkit controls. Each StyleRule defines a pattern, or selector, that identify the controls or control components that are specified within this pattern.

Let's examine a example style sheet definition.

let ss:StyleSheet
{StyleSheet
    {StyleRule VBox.panel-vbox
        background = "blue",
        margin = 2px,
        spacing = 4px
    }
}

where:

• ss a variable that defines the StyleSheet
• VBox.panel-vbox is the selector
• VBox is the style-element
• panel-vbox is the style-class

Note that a StyleSheet can have one or more StyleRules where each StyleRule contains one selector and declarations.

Using the Style Sheet

Once you have a StyleSheet defined, you can use the definitions after it has been installed. For example:

{install-style-sheet ss}

In our example code, each time we call VBox, we have the option of specifiying the style-class of panel-vbox. For example:

{value
    let my-panel:VBox =
        {VBox
            style-class = "panel-vbox",
            {Frame "Top content"},
            {Frame "Bottom content"}
        }
}

Using a StyleSheet in the Login Example

Let's pull together these concepts and apply them to our login example. We created a style sheet common-style-sheet that contains definitions for common properties (widths) specified in the login screen. We can use these styles by specifying the style-class.

Creating the Style Sheet File

Defining style sheet rules directly in your source code is a good approach for testing your rules. Once you are satisfied with the StyleRules, you can place them in one or more style sheet files. The default style sheet is a prime example of this implementation in which it has rules that implement a new look for all of the Curl GUI Toolkit controls. Let's first examine the the contents of the files that define the default style sheet. They are contained within two files: default-style.scurl and dss-defs.scurl (dss-defs.scurl is included in default-style.scurl). These files are located in the directory that contains the manifest for the styled controls library. Take time to examine these files on your machine.

One thing to recognize is that a style sheet in Curl is simply a file containing Curl code. The file extension is *.scurl and the last expression in this file must return a StyleSheet object. Aside from that, the file can include any Curl code that is needed to implement the style. In particular, you may need to import packages such as CURL.GUI.STANDARD in order to implement your style.

Our style sheet file resembles the following:

|| StyleSheet
{import * from CURL.GUI.STANDARD}
{StyleSheet
     {StyleRule "CommandButton.ok",
        width = 1.75cm
    },
    {StyleRule "TextField.login",
        width = 2cm
    },
    {StyleRule "PasswordField.login",
        width = 2cm
    },
    {StyleRule "GroupBox.dialog",
        width = 4.5cm
    }
}

In our login example, reference the StyleSheet file using the url.

{let common-style-sheet:StyleSheet =
   {url "styles/my-styles/common-style-b.scurl"}
}

Notice that we also use the DEFAULT-STYLE-SHEET.

Tip: You should try to limit the number of style sheets used in an application, and set the style sheet only at the top-level document in the application. If you set a style sheet in a child document, unexpected results can occur.

Customization of Login Screen

The following code defines the customization of controls displayed in the "Custom" selection of our example applet. In the following applet we have customized the look and feel using a style sheet defined in the custom-style.scurl file. This file can be viewed by selecting this link: Custom Style Sheet

For more information regarding paragraph formats, please refer to the Curl Styled Controls Library User's Guide that you installed in the Curl Documentation