Window Framework

From CSP

Table of contents

1 Current status

2 Files

2.1 Editing xml files

3 Themes, skinning and resources

3.1 Style sheets
3.2 My first theme
3.3 String resource files and localization

4 Missing documentation

5 Classes

5.1 Control base class
5.2 Container classes
5.3 Other widgets

6 Wishlist

6.1 Framework
6.2 Windows

[edit]

Current status

[edit]

Files

All files used by the user interface is placed in folders under data/ui. There can be several types of files here:

window_document.xsd. This xml schema file can be used to validate all other xml files.
window xml. Each file represents a window used from csp. It can be the main menu, options window etc.
stylesheet xml. These files is used to set a borders, colors, font, font-size etc.
image files. Image files used as background images for controls.
localized strings stored in xml files.
python scripts handling the user interface.

[edit]

Editing xml files

Since we have an xml schema to validate all user interface files it is highly recomended that you use an editor with schema support. Here is a list of editors with that support:

eclipse with Web Tools Platform (WTP) (free)
Microsoft Visual Studio 2005 (not free)
Altova XMLSpy (not free)

[edit]

Themes, skinning and resources

Each theme has its own directory where all user interface files can be placed. Please take a look in data/ui/themes/default. Here you find the default theme for the csp project.

[edit]

Style sheets

It is possible to include style sheets to define common properties like font, border, color etc. It works something like css for html but with an other syntax. It is also possible to include several style sheets.

<WindowDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation='../../window_document.xsd'>
  <Includes>
    <StyleInclude>styles.xml</StyleInclude>
  </Includes>
  ...

A style is set in the following priority order:

CssClass is set.
Style name equals the name of the control. Examples: Window, Button, CheckBox
Style set on the current control.
Recursivly check parent controls for the style.

A control can have state also. With the following style name: ListBoxItem:selected you can have a special style for all ListBoxItem controls with the selected state. In this example you may want to have a different background color.

[edit]

My first theme

Copy the content of the default csp theme into a new directory. Now you can try to experiment by editing xml files with your favorite xml editor.

Here is a sample from the options.xml file. Please read the inline comments in the file.

<?xml version="1.0"?>
<!-- All good xml editors will handle the reference to the window_document.xsd file. 
     The editor will validate the content while you write. Hopefully you will have som 
     intellisense to... -->
<WindowDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation='../../window_document.xsd'>
  <Includes>
    <!-- This include will set the default behaviour on all controls. Without this line
         no controls will work. You MUST set default font, font size, color, borders etc 
         for each control -->
    <StyleInclude>styles.xml</StyleInclude>
  </Includes>
  <Window CssClass="window_default" SizeWidth="449" SizeHeight="420" LocationZ="30" >
    <Control>
      <!-- A window can only contain a single child control. Here we place a multi control 
           container so we can manually position the content. -->
      <MultiControlContainer>
        <Controls>
          <Label LocationX="10" LocationY="2" SizeWidth="438" SizeHeight="30" Text="Display settings" />
          <Label CssClass="stripe" LocationX="0" LocationY="30" SizeWidth="438" SizeHeight="10" />

          <Label Text="Resolution:" LocationX="25" LocationY="55" SizeHeight="25" />
          <ListBox Id="resolution" LocationX="145" LocationY="55" SizeWidth="250" SizeHeight="140">
            <Items>
              <Item Text="640x480" SizeHeight="30" />
              <Item Text="800x600" SizeHeight="30" />
              <Item Text="1024x768" SizeHeight="30" />
              <Item Text="1280x1024" SizeHeight="30" />
              <Item Text="1920x1200" SizeHeight="30" />
            </Items>
          </ListBox>

          <CheckBox Id="fullscreen" LocationX="25" LocationY="195" SizeWidth="150" SizeHeight="30" Text="Fullscreen" />

          <Label LocationX="25" LocationY="230" SizeWidth="438" SizeHeight="25" Text="Theme:" />
          <ListBox Id="theme" LocationX="145" LocationY="230" SizeWidth="250" SizeHeight="140" />

          <!-- Buttons for ok and cancel actions. -->
          <Button Id="ok" Text="OK" LocationX="180" LocationY="375" SizeWidth="120" SizeHeight="35" />
          <Button Id="cancel" Text="Cancel" LocationX="310" LocationY="375" SizeWidth="120" SizeHeight="35" />
        </Controls>
      </MultiControlContainer>
    </Control>
  </Window>
</WindowDocument>

[edit]

String resource files and localization

In the data/ui/localization folder there is xml files containing string resource files. Here is a sample of such a file:

<?xml version="1.0" ?> 
<StringTableDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../window_document.xsd">
<Strings>
  <String key="cancel">Cancel</String> 
  <String key="full_screen_mode">Fullscreen</String> 
  <String key="instant_action">Instant action</String> 
</Strings>
</StringTableDocument>

This file can be included in a theme xml file by adding the following row to the <Includes> element:

<StringTableInclude>global.xml</StringTableInclude>

Everywhere where you want to place text you can use the following syntax for displaying the strings:

${variable_name}
Ex:
<Button Id="quit" Text="${quit}" />

[edit]

Missing documentation

The following needs to be documented.

Python bindings for all objects and events.
Support for several languages. German, swedish etc.

[edit]

Classes

There is two namespaces that is in use:

csp::wf contains all base classes and controls.

[edit]

Control base class

All widgets is inheriting from the Control base class. This class defines all functionality that is shared between controls. See Control for more information.

[edit]

Container classes

The Control base class doesn't support child controls at all. In order to support child controls you must inherit from Container base class and implement some methods. There is currently several container classes that will take care of most of the situations.

Container. Base class for all controls that can have child controls. This is an abstract class.
MultiControlContainer. Container class that supports several child controls with absolute positioning.
SingleControlContainer. Container that supports a single child control.
TableControlContainer. Container with rows and columns.

[edit]