Create a CheckListboxItem

Sometimes you need a list where the items are checkable. The ItemListbox introduced in CEGUI 0.5 accepts all sorts of items, as long as they inherit ItemEntry. I'm going to teach you how to create a CheckListboxItem to put in your list.

Getting started!

I'm assuming you are just using a standard imageset, with a standard scheme (currently TaharezLook and WindowsLook are supported).

We are first going to get started by writing the looknfeel entry. This is the most important part of this tutorial, as its basically 70% of what we need to do to achieve our goal. First of all, this entry has a few states:

1. Enabled: How the item looks when the item is enabled.
2. Disabled: How the item looks when the item is disabled.
3. SelectedEnabled: How the item looks when the item is selected and is enabled.
4. SelectedDisabled: How the item looks when the item is selected and is disabled.

Writing the requirements

Open the appriopiate looknfeel file (WindowsLook.looknfeel or TaharezLook.looknfeel), and place this at the bottom (inside the Falagard tags though!)

Our start

<WidgetLook name="WindowsLook/CheckListboxItem">
</WidgetLook>

We first need to define a WidgetLook, this is where all the action happens in. It takes one attribute, name. This is simply the name of the widget you are defining. Now we are going to add the states. These states are necessary for the item to respond to certain events. For example, when the item is disabled, the state Disabled is used.

<WidgetLook name="WindowsLook/CheckListboxItem">
    <StateImagery name="Enabled">
         <Layer>
              <Section section="label">
                  <ColourProperty name="TextColour" />
              </Section>
         </Layer>
    </StateImagery>
    <StateImagery name="Disabled">
         <Layer>
              <Section section="label">
                  <ColourProperty name="TextColour" />
              </Section>
         </Layer>
    </StateImagery>
</WidgetLook>

We define a state via StateImagery. It requires the attribute name which specifies what state its in. Don't worry about Layer for now. Section is always used. This part takes care of actually changing the look. It requires a attribute section, this is actually WHAT to change, in this case the label. TextColour is a simple colour (black), we will define it below. Now as you can see the Enabled state just sets the text colour to black, thats all it does. Same goes for Disabled (remember this is an item, items are not commonly disabled).

Now we are going to take a look at the other two states.

<WidgetLook name="WindowsLook/CheckListboxItem">
    <StateImagery name="Enabled">
         <Layer>
              <Section section="label">
                  <ColourProperty name="TextColour" />
              </Section>
         </Layer>
    </StateImagery>
    <StateImagery name="Disabled">
         <Layer>
              <Section section="label">
                  <ColourProperty name="TextColour" />
              </Section>
         </Layer>
    </StateImagery>
    <StateImagery name="SelectedEnabled">
        <Layer>
            <Section section="selection" />
            <Section section="label">
                 <ColourProperty name="SelectedTextColour" />
            </Section>
        </Layer>
    </StateImagery>
    <StateImagery name="SelectedDisabled">
        <Layer>
            <Section section="selection" />
            <Section section="label">
                <ColourProperty name="SelectedTextColour" />
            </Section>
        </Layer>
    </StateImagery>
</WidgetLook>

These states pretty much speak for themselves altough there are more sections listed. Section not only defines what to change, also defines what needs to be shown. In the Enabled state we dont want it to look like its selected, so there is no selection section. Note that the order of which you put the Sections are also the Z order. In this case we are putting the selection image first, and then text. If we would do it the other way around, we wouldn't see the text.

Now we are going to add the definitions of some colors and property's.

<WidgetLook name="WindowsLook/CheckListboxItem">
    <PropertyDefinition name="TextColour" initialValue="FF000000" redrawOnWrite="true" />
    <PropertyDefinition name="SelectedTextColour" initialValue="FFFFFFFF" redrawOnWrite="true" />
    <PropertyDefinition name="SelectionBrush" initialValue="set:WindowsLook image:Background" redrawOnWrite="true" />
    <PropertyDefinition name="SelectionColour" initialValue="FF3030FF" redrawOnWrite="true" />
    <Property name="Selectable" value="True" />
    <StateImagery name="Enabled">
         <Layer>
              <Section section="label">
                  <ColourProperty name="TextColour" />
              </Section>
         </Layer>
    </StateImagery>
    <StateImagery name="Disabled">
         <Layer>
              <Section section="label">
                  <ColourProperty name="TextColour" />
              </Section>
         </Layer>
    </StateImagery>
    <StateImagery name="SelectedEnabled">
        <Layer>
            <Section section="selection" />
            <Section section="label">
                 <ColourProperty name="SelectedTextColour" />
            </Section>
        </Layer>
    </StateImagery>
    <StateImagery name="SelectedDisabled">
        <Layer>
            <Section section="selection" />
            <Section section="label">
                <ColourProperty name="SelectedTextColour" />
            </Section>
        </Layer>
    </StateImagery>
</WidgetLook>

Our first PropertyDefinition just defines a text for a colour used in the StateImagery sections. Same goes for the other PropertyDefinitions except the SelectionBrush. Instead of defining a color, it defines a image. In this case it uses the WindowsLook Background image defined in the imageset. Then we got a Property, which simply implies some sort of setting. In this case, we make it a item by adding the Property 'Selectable' and setting it to true as we want it to act like an item.