View source for LMDThemes GradientRenderer

= The new gradient theme renderer =

== Overview ==

=== New units ===

The new gradient theme engine was intended to implement themes imitating Office 2007 look. Actually it allows to build and use a wider variety of themes. It uses universal and 

flexible architecture of gradient fillers which allows to combine complex configurations of gradients.

These configurations, from the simplest to complex are:<br>
- Solid filler;<br>
- Gradient filler;<br>
- Composition of fillers (any number of rectangular areas);<br>
- Mix of fillers, where each filler in a blend has its weight;<br>
- Mix of composition of fillers.<br>

In order to implement the new renderer, we added several new graphical units, which can also be used separately. These are:
LMDFillers, LMDFigures, LMDGradientFrames.

==== LMDFillers ====

LMDFillers unit contains base TLMDFiller class and its descendants for painting surfaces and borders of figures:<br> - TLMDSolidFiller (floodfills figure with given color);<br>- TLMDVerticalGradient, TLMDHorizontalGradient, TLMDEllipseFiller, TLMDRoundFiller, TLMDLineFiller, TLMDRectangleFiller, TLMDBandFiller (floodfills figure with a given gradient);<br>- TLMDCompositeFiller (floodfilles rectangular areas with given gradients);<br>- TLMDMixedFillers (floodfills figure with a blend of gradients).

==== LMDFigures ====

LMDFigures unit contains TLMDFigure class and its descendants:<br> -TLMDRectangle, TLMDCustomCutRectangle, TLMDRoundRectangle;<br>-TLMDLine;<br>-TLMDEllipse, TLMDCircle;<br>-TLMDUnionFigure, TLMDSubtractionFigure.

==== LMDGradientFrames ====

LMDGradientFrames unit contains TLMDBaseGradientFrame class and its descendants for painting different gradient frames:

-TLMDGradientRectFrame draws rectangular frames consisting of three parts (outer border, inner space, inner border). These frames can have three types of corners: rectangular,

round and line. Each corner of a frame can have its own cut type.<br>
-TLMDGradientCircleFrame draws round frames consisting of three parts (outer border, inner space, inner border).<br>
-TLMDGradientCmpFrame draws complex frames consisting of three sets of parts: outer borders parts, inner space parts and inner border parts, each set of parts consists of 4 sides 

and 4 corners. This class  is not used for rendering Office2007-like themes.<br>


=== Functionality ===

The new renderer<br>
- implements interface declared in TLMDThemeServices class (LMDThemes unit);<br>
- allows to use Office2007-like themes (three built-in color schemes: blue, metallic, black);<br>
- allows to get access to its settings via helper properties;<br>
- allows to change colors and brightness for several elements at a time;<br>
- can store themes in XML file;<br>
- can read themes from XML file and from CAB file (if it contains XML theme file).<br>

=== Structure ===

Each themed element has two arrays of corresponding descriptors, array of fill descriptors and array of frame descriptors:<br>

<pre class="brush:delphi">
ButtonFill:  array[TThemedButton] of TLMDGradientThemeFillDescriptor;
ButtonFrame: array[TThemedButton] of TLMDGradientThemeFrameDescriptor;
</pre>

Also, themed element can have array of text descriptors, but in current version text descriptor is used only for setting colors of font in tab text (for teTab element).<br>
A gradient theme descriptor is a record that consists of parameters section and filler section:

<pre class="brush:delphi">
type
  TLMDGradientThemeFillDescriptor = record
    Params: TLMDGradientThemeFillParams;
    Fillers: array[TLMDGradientFillPart] of TLMDFiller;
  end;

type
  TLMDGradientThemeFrameDescriptor = record
    Params: TLMDGradientThemeFrameParams;
    Fillers: array[TLMDGradientSFramePart] of TLMDFiller;
  end;
</pre>

A fill descriptor determines how element's inner surface is painted, whereas a frame descriptor determines how element's frame is painted.<br>

== Usage ==

=== Loading and activating ===

Nothing was changed here: in order to use the new renderer you have to put a reference to LMDThemesGradientThemeRenderer unit somewhere in your application. Initialization section of this unit registers renderer so that application can use it for painting controls with ThemeMode = ttmNative. When renderer is active, active theme and color scheme can be changed by loading theme from file

 LMDThemeServices.ActivateTheme('Office2007.cab', 'Metallic');

or by activating built-in color scheme:

 LMDThemeServices.ActivateColorScheme('Black');

Usually you do not have to deactivate theme directly, it is performed automatically when needed.

=== Changing colors and other params in run-time ===

==== Mass changing methods ====

There are three methods that allow to change colors for several themed elements/details at a time:
<pre class="brush:delphi">procedure ChangeBrightness(aPercent: integer; aElements: TThemedElementSet = []; aDetailNameMask: string = ''; aFillParts: TLMDGradientFillParts = cGradientFillAllParts; aFrameParts: TLMDGradientSFrameParts = cGradientSFrameAllParts; aIndex: integer = -1);

procedure ReplaceColor(aOldColor, aNewColor: TColor; aElements: TThemedElementSet = []; aDetailNameMask: string = ''; aFillParts: TLMDGradientFillParts = cGradientFillAllParts; aFrameParts: TLMDGradientSFrameParts = cGradientSFrameAllParts; aIndex: integer = -1);

procedure SetNewColor(aNewColor: TColor; aElements: TThemedElementSet = []; aDetailNameMask: string = ''; aFillParts: TLMDGradientFillParts = cGradientFillAllParts; aFrameParts: TLMDGradientSFrameParts = cGradientSFrameAllParts; aIndex: integer = 0);</pre>
Each of these methods walks through all fillers for given element, given detail name mask, fill or frame part and performs required change. <br>

'''Note''': '''ChangeBrightness''' and '''ReplaceColor''' apply change for all color entries starting from given index , whereas SetNewColor changes one color entry with a given index.<br>

Examples:
<pre class="brush:delphi">//walks through all fillers for teTab element, for details like 'ttTopTabItem*' 
 //and sets new color for each FixedColors entry with index 0
 SetNewColor($0000FFFF, [teTab], 'ttTopTabItemHot*', [gfpMain], [], 0);

 //replaces each color entry with value $00F8E0CE by a new value $00F8D0BE
 ReplaceColor($00F8E0CE, $00F8D0BE);

 //Changes brightness of all colors: 
 ChangeBrightness(-10, []);</pre>

=== Direct access to colors and filler properties ===

Properties like *FillFiller, *FrameFiller allow to get direct access to fillers. Using them requires knowledge of how the filler is structured. Filler structure can be browsed in XML file. For 

Office2007-like themes a filler is usually either solid filler, vertical/horizontal/elliptic gradient, composite filler of a mixed filler.<br>

==== Changing colors ====

For example, this is how we can change start gradient color for teTab element, detail ttTopTabItemHot:
<pre class="brush:delphi">with CThemeRenderer do
 TLMDCompositeFiller(TLMDMixedFiller(TabFillFiller[ttTopTabItemHot, gfpMain]).Item[0]).Item[0].FixedColors[0]&nbsp;:= clRed;</pre>
This is rather complex construction because the filler in this case is a mix of composite filler and elliptic gradient:
<pre class="brush:xml">&lt;FillDescriptor&gt;
 &lt;Params&gt;
 &lt;gflpRenderMode Value="4"/&gt;
 &lt;/Params&gt;
 &lt;Fillers&gt;
 &lt;Filler Class="TLMDMixedFiller" Part="gfpMain" ItemCount="2"&gt;
 &lt;UseRelativeUnits Value="1"/&gt;
 &lt;Item Index="0" Weight="255"&gt;
 &lt;Filler Class="TLMDCompositeFiller" ItemCount="2"&gt;
 &lt;UseRelativeUnits Value="1"/&gt;
 &lt;Item Index="0"&gt;
 &lt;FillerRect Left="0" Top="0" Right="100" Bottom="45"/&gt;
 &lt;Filler Class="TLMDVerticalGradient"&gt;
 &lt;Colors ColorCount="2"&gt;
 &lt;Color0 Value="$00FEDDC4"/&gt;
 &lt;Color1 Value="clWhite"/&gt;
 &lt;/Colors&gt;
 &lt;/Filler&gt;
 &lt;/Item&gt;
 &lt;Item Index="1"&gt;
 &lt;FillerRect Left="0" Top="45" Right="100" Bottom="100"/&gt;
 &lt;Filler Class="TLMDVerticalGradient"&gt;
 &lt;Colors ColorCount="2"&gt;
 &lt;Color0 Value="$00FEDDC4"/&gt;
 &lt;Color1 Value="clWhite"/&gt;
 &lt;/Colors&gt;
 &lt;/Filler&gt;
 &lt;/Item&gt;
 &lt;/Filler&gt;
 &lt;/Item&gt;
 &lt;Item Index="1" Weight="255"&gt;
 &lt;Filler Class="TLMDEllipseFiller"&gt;
 &lt;UseRelativeUnits Value="1"/&gt;
 &lt;BasePoint X="50" Y="0"/&gt;
 &lt;Axis1 Value="80"/&gt;
 &lt;Axis2 Value="80"/&gt;
 &lt;FirstAxisDirection X="1" Y="0"/&gt;
 &lt;Colors ColorCount="2"&gt;
 &lt;Color0 Value="$00FEDDC4"/&gt;
 &lt;Color1 Value="$0098D1E3"/&gt;
 &lt;/Colors&gt;
 &lt;/Filler&gt;
 &lt;/Item&gt;
 &lt;/Filler&gt;
 &lt;/Fillers&gt;
&lt;/FillDescriptor&gt;</pre>
So, we have to take filler for main fill part (gfpMain index), ttTopTabItemHot detail:<br>
<pre>TabFillFiller[ttTopTabItemHot, gfpMain]</pre>
then cast it to TLMDMixedFiller and take the first item, which is a composite filler:
<pre>TLMDMixedFiller( * ).Item[0])</pre>
then cast it to TLMDCompositeFiller and take the first item which is a vertical gradient, and change the first color:
<pre>TLMDCompositeFiller( * ).Item[0].FixedColors[0]&nbsp;:= clRed;</pre>

====Changing other filler properties====

Each filler has BasePoint property which determines the coordinate origin for filler.
Example:<br>
<pre class="brush:delphi">
    with CThemeRenderer do
      begin
        //This will change base point of ellipse gradient filler (bottom part of the filler)
        //Coordinates are relative to rectangle of the element: (100, 100) is
        //the bottom right corner
        TLMDCompositeFiller(ButtonFillFiller[tbPushButtonPressed, gfpMain]).Item[1].BasePoint := Point(100, 100);
        TLMDCompositeFiller(ButtonFillFiller[tbPushButtonHot, gfpMain]).Item[1].BasePoint := Point(0, 100);
       end;
</pre>

===Parameters - detailed description===

Parameters section is a simple one for fill descriptors and rather complex for frame descriptors. However, each parameter is a byte.

==== Fill descriptors ====

Here we have one parameter: gflpRenderMode (prefix gflp: gradient fill parameter)
<pre class="brush:delphi">type
 TLMDGradientThemeFillParam = (gflpRenderMode);</pre><pre>Bits 0..1: 0 - standard, 1 - sketch, 2 and 3 - reserved
 Bit 2 - antialiasing for gfpMain
 Bits 3..6 - antialiasing for gfpDeco1..gfpDeco4
 
 Standard value is 4: 0000 0010</pre>

==== Frame descriptors ====

Here we have a lot of parameters (prefix gfrp: gradient frame parameter).<br>Most of frame parameters relate to determining how corners of a frame should look. For custom cut rectangle, CutX and CutY are the values that, along with corner cut type, determine how corner looks. E.g. here is a round-cut corner with its CutX and CutY values:<br>[[Image:Cutxy.PNG|Image:cutxy.PNG]]

<br>Since there are three possible areas of a frame (outer border, inner space and inner border), each of which can have its own corners description, the number of parameters section of a frame descriptor is about 40:
<pre class="brush:delphi">type
 TLMDGradientThemeFrameParam =
 ( 
 //gfrpRenderMode
 //bits 0..1: 0 - standard, 1 - sketch, 2 and 3 - reserved
 //bit 2: outerborder antialasing flag - 4
 //bit 3: outerborder soft edge flag - 8
 //bit 4: innerspace antialasing flag - 16
 //bit 5: innerspace soft edge flag - 32
 //bit 6: innerborder antialasing flag - 64
 //bit 7: innerborder soft edge flag - 128
 //---------------- bits 7654 3210
 //standard value is 84: 0101 0100
 gfrpRenderMode, 

 //determine what sides of the border should be drawn
 gfrpOuterBorderSides, 
 gfrpInnerBorderSides,

 //determine edge width - each of border areas can have edges. Not used for Office2007-like themes
 gfrpOuterBorderEdgeWidth, 
 gfrpInnerBorderEdgeWidth,
 gfrpSpaceEdgeWidth,

 //determine border areas width
 gfrpOuterBorderWidth, gfrpInnerBorderWidth,
 //determines gap width between border area and innerspace area
 gfrpOuterBorderGap, gfrpInnerBorderGap,

 //determine inner space widths
 gfrpTopSpaceWidth, gfrpRightSpaceWidth,
 gfrpBottomSpaceWidth, gfrpLeftSpaceWidth,

 //determines how cut values are calculated
 //Possible values are 
 //cvuBoth - both cut values are used
 //cvuXOnly - only CutX value is used
 //cvuYOnly - only CutY value is used
 //cvuMin - minimum of CutX and CutY values is used
 //cvuMax - maximum of CutX and CutY values is used 
 //cvuAverage - average of CutX and CutY values is used
 gfrpCutValueUsage,

 //determine inner and outer cut type for outer border
 //Possible values are ctNone (rectangular corner), ctLine (line-cut corner), ctRound (rounded corner)
 gfrpOuterBorderInnerCutType, gfrpOuterBorderOuterCutType,

 //CutX and CutY values for inner and outer corners of outer border
 gfrpOuterBorderInnerCutX, gfrpOuterBorderInnerCutY,
 gfrpOuterBorderOuterCutX, gfrpOuterBorderOuterCutY,

 //value types for outer border cut values
 //Possible values are vtAbsolute, vtPercent
 gfrpOuterBorderInnerCutXValueType, gfrpOuterBorderInnerCutYValueType,
 gfrpOuterBorderOuterCutXValueType, gfrpOuterBorderOuterCutYValueType,

 //determine inner and outer cut type for inner space
 gfrpInnerSpaceInnerCutType, gfrpInnerSpaceOuterCutType,

 //CutX and CutY values for inner and outer corners of inner space
 gfrpInnerSpaceInnerCutX, gfrpInnerSpaceInnerCutY,
 gfrpInnerSpaceOuterCutX, gfrpInnerSpaceOuterCutY,

 //value types for inner space cut values
 gfrpInnerSpaceInnerCutXValueType, gfrpInnerSpaceInnerCutYValueType,
 gfrpInnerSpaceOuterCutXValueType, gfrpInnerSpaceOuterCutYValueType,

 //determine inner and outer cut type for inner border
 gfrpInnerBorderOuterCutType, gfrpInnerBorderInnerCutType,

 //CutX and CutY values for inner and outer corners of inner border
 gfrpInnerBorderOuterCutX, gfrpInnerBorderOuterCutY,
 gfrpInnerBorderInnerCutX, gfrpInnerBorderInnerCutY,

 //value types for inner border cut values
 gfrpInnerBorderOuterCutXValueType, gfrpInnerBorderOuterCutYValueType,
 gfrpInnerBorderInnerCutXValueType, gfrpInnerBorderInnerCutYValueType);</pre>

== Screenshots ==

=== Predefined color schemes ===

'''Blue'''<br>[[Image:Office2007blue.png|Image:office2007blue.png]]<br>'''Metallic'''<br>[[Image:Office2007metallic.png|Image:office2007metallic.png]]<br>'''Black'''<br>[[Image:Office2007black.png|Image:office2007black.png]]<br>

=== ElXTree, ElToolBar and LMDButtonBar ===
'''With blue color scheme'''<br>[[Image:Office2007blue elpack.png|Image:office2007blue_elpack.png]]<br>
'''With black color scheme'''<br>[[Image:Office2007black elpack.png|Image:office2007black_elpack.png]]<br>

=== Changing colors at runtime ===

'''Third gradient area added for push buttons, tab colors modified'''<br>[[Image:Office2007blue changecolors.png|Image:office2007blue_changecolors.png]]<br>'''Base point changed for push buttons'''<br>[[Image:Office2007darkblue bpchanged.png|Image:office2007darkblue_bpchanged.png]]<br>'''Dark blue scheme (brightness -30%)'''<br>[[Image:Office2007darkblue moregrads.png|Image:office2007darkblue_moregrads.png]]<br>