The first part of FDCLib (Free Delphi Code Library) is out.

It contains the reusable grid view controller, a small color utility unit and three very simple demos.

The code is currently only tested under Delphi 2007, and the color utility unit implements a record with methods, so I guess that breaks older versions, but it is easy to change. I’ll probably add some conditional code for compatibility later.

Details about versions downloading can always be found at http://fdclib.fosdal.com. You can download a .zip file or grab it with SVN from the repository at SourceForge. I haven’t created a download package on SourceForge yet, but that is coming as well.

The Grid Demos
There are three very simple demos included in the demo/DemoFDCLib project. I’d like to add some more later, but I think they demonstrate the basic functionality for now.

• DemoFrameGridViewController contains the interactive bits (ie the TStringGrid, etc.)

• DemoNumbersViewClass show a series of numbers and their value squared, and also show how to use a custom static column color.

• DemoColorsViewClass shows how to implement a procedural color and contains $FFFFFF rows 🙂 Loading time is nonexistant.

• DemoDirectoryClass is a small utility class that populate a TStringList from a directory path with wildcards. DemoDirectoryViewClass implements the grid controller for showing content from that extended string list. The default directory in the demo is “%temp%\*”, but feel free to experiment with changing it in the edit box.

Let’s take a closer look at how to hijack a pristine TStringGrid and make it our playground without inheriting the grid directly. The VCL class is well designed for reuse and expose properties and event handlers that we easily can grab hold of. The OnDrawCell event is of particular interest to us. That’s a good spot to redefine how the grid retrieve and render it’s content.

You will be assimilated
This is pretty self explanatory, but what we basically do is hook the draw routine and set up the appropriate number of rows and columns, and their respective default widths.

procedure TGridViewController.Refresh;
var
  ix : Integer;
begin
  if not Assigned(Grid)
   then Exit;

  if not IsEmpty
  then begin // Set Visitor's drawing handler, row and column count
    Grid.Enabled := True;
    Grid.OnDrawCell := DrawCell;
    Grid.RowCount := RowCount + FixedRows;
    Grid.ColCount := Count;
    for ix := 0 to Count - 1  // Set column widths
     do begin
       Grid.ColWidths[ix] := (Objects[ix] as TGridViewColumn).Width;
     end;
  end
  else begin // disable drawing handler, set rows/cols to 1 and fill in 1 "blank"
    Grid.Enabled := False;
    Grid.OnDrawCell := nil;
    Grid.RowCount := 1;
    Grid.ColCount := 1;
    Grid.ColWidths[0] := 0;
    Grid.Cells[0,0] := defaultEmptyCell;
  end;
  if Grid.RowCount > 1
  then begin // Reset header and Row positions in case empty grid overrode them.
    Grid.FixedRows := FixedRows;
    Grid.Row := FixedRows;
  end;
  Grid.Invalidate; // ensure that the grid is refreshed
end;

OnDrawCell
So this is where all the action is… err… actually, not much happens here. Instead we delegate the actual rendering to the column instance.

procedure TGridViewController.DrawCell(Sender: TObject; ACol, ARow: Integer;
  Rect: TRect; State: TGridDrawState);
begin
  (Objects[aCol] as TGridViewColumn).DrawCell(Grid.Canvas, aRow, Rect, State);
end;

The column instance then again divide the draw into two sections. The outer DrawCell does basic housekeeping of canvas color settings and a little color trickery (a feature that snuck in while I was having fun – my bad).

procedure TGridViewColumn.DrawCell(Canvas: TCanvas; aRow: Integer; Rect: TRect;
  State: TGridDrawState);
var
  FG, ofg,
  BG, obg : TColor;
begin
  with Canvas
  do begin
    ofg:=Font.Color;
    obg:=Brush.Color;

    if (State = []) // Not focused/selected/etc
    then begin
      FG := ofg;
      BG := obg;

      if aRow > 0 // Not a title line
      then begin
        ForeColor(aRow, FG);
        BackColor(aRow, BG);
      end;

      if ofg  FG then Font.Color:=FG;
      if obg  BG then Brush.Color:=BG;
    end;

    DrawCellInner(Canvas, aRow - Controller.FixedRows, Rect, State); // The business happens here

    if (State = [])
    then begin
      if ofg  FG then Font.Color:=ofg;
      if obg  BG then Brush.Color:=obg;
    end;
  end;
end;

The actual content rendering happens in DrawCellInner. Note that we do an adjustment related to grid layout here. If you look at the line where DrawCellInner is called, we subtract FixedRows from aRow, ensuring that our data is zero offset based.

procedure TGridViewColumn.DrawCellInner(Canvas: TCanvas; aRow: Integer;
  Rect: TRect; State: TGridDrawState);
var
  CellText : String;
  w      : Integer; // String width
  txtAdj : Integer; // old adjust mode
begin
  if aRow < 0
  then CellText := Title
  else CellText := FormattedText(aRow);
  with Canvas
  do begin
    case FAlign of
      taCenter       : begin
                         w:=TextWidth(CellText);
                         if (w>(Rect.Right-Rect.Left))
                         then w := 2
                         else w := Round(((Rect.Right - Rect.Left) - w) / 2);
                         TextRect(Rect, Rect.Left + w,Rect.Top + 1, CellText);
                       end;
      taRightJustify : begin
                         txtAdj:=SetTextAlign(Handle, ta_Top or ta_Right);
                         TextRect(Rect, Rect.Right - 3,Rect.Top + 1, CellText);
                         SetTextAlign(Handle, txtAdj);
                       end;
               else // taLeftJustify
                       TextRect(Rect, Rect.Left+2,Rect.Top+1, CellText);
    end;
  end;
end;

In the inner draw routine we first figure out if we are drawing the title row or a data row. If it is a data row, we call the TGridViewColumn.FormattedText method.

function TGridViewTextColumn.FormattedText(aRow: Integer): String;
begin
  Result := GetTextMethod(aRow);
end;

Does GetTextMethod look familiar? It is the procedure variable which holds the method we implement in our descendant viewcontroller class and pass on when we set up the column. That is the method which actually retrieve the data from the underlying data structure as described in part 2 (GetNumber, GetNumberSquared).

The rest of DrawCellInner measures the retrieved text and ensure it is adjusted as desired and rendered within the cell region.

Magic Colors
Back to ForeColor and BackColor in the outer draw. This is the closest we come to bells and whistles. To make the grid look more sophisticated, I added support for overriding the colors as well as a very simple default rowshading algorithm.

procedure TGridViewColumn.ForeColor(aRow: Integer; var Color: TColor);
begin
  if Assigned(FGetForeColorMethod)
   then GetForeColorMethod(aRow, Color)
  else if DefaultForeColor  clNone
   then Color := DefaultForeColor;
end;

procedure TGridViewColumn.BackColor(aRow: Integer; var Color: TColor);
begin
  if Assigned(FGetBackColorMethod)
   then GetBackColorMethod(aRow, Color)
  else if DefaultBackColor  clNone
   then Color := DefaultBackColor;

  if Assigned(FGetShadeColorMethod)
  then GetShadeColorMethod(aRow, Color);
end;

Both these methods start in the same way. The default color have been retrieved from the grid itself in the outer draw. First we check if a color method have been plugged in, if not – we check if a column color override has been set.

For the background color routine, there is another feature – a pluggable shading method. The default row shader looks like this…

procedure TGridViewController.DefaultRowShader(const aRow:Integer; var Color:TColor);
begin
  if ShadeRows and (not Odd(aRow))
  then begin
    Color := Graphics.ColorToRGB(Color); // Translate theme/system colors to RGB
    if  ((Color and $FFFFFF) > $888888)  // Lazy man's luminosity adjustment
     then Color := Color - $080808
     else Color := Color + $080808;
  end;
end;

Too much flexibility? Well, maybe I broke the KISS rule, but no rule without exceptions 🙂 Now I can have static or procedural color adjustments per row as well as per column.

Next: Reusable Grid goes code complete and come with examples.

Stay tuned.

The Controller

Our basic TGridViewController will hold a list of TGridViewColumns. I could make a simple array, or I could use TStringList. TStringList is probably one of the best and one of the worst classes in Delphi. So easy to use and so easy to abuse. In this case, I will only need to manage a handful of columns, instead of thousands of lines of text – so it will be ok.

On the abuse side: before you start filling TStringList – consider adjusting the capacity. Resizing the list is EXPENSIVE. Also – fill first, sort later.

Ok, lets take a look at the initial skeleton of the controller class:

  TGridViewController = class (TStringList)
  private
    FGrid : TStringGrid;
    function GetIsEmpty:Boolean;
    function GetCurrentSelectionIndex: Integer;
  protected
    procedure DefineAttributes; virtual; abstract;
    function GetRowCount: Integer; virtual; abstract;
    procedure SetGrid(const Value: TStringGrid); virtual;
    procedure DrawCell(Sender: TObject; ACol, ARow: Integer; Rect: TRect; State: TGridDrawState);
    function MakeColumn(ColType : TGridViewColumnType; aTitle:String; aWidth:Integer; anAlign:TAlignment):TGridViewColumn;
  public
    constructor Create; virtual;
    destructor Destroy; override;
    procedure Refresh;
    function CreateTextColumn(aTitle:String; aGetText:TGetTextMethod; aWidth:Integer = 64; anAlign:TAlignment = taLeftJustify):TGridViewTextColumn;
    property CurrentSelectionIndex:Integer read GetCurrentSelectionIndex;
    property Grid: TStringGrid read FGrid write SetGrid;
    property IsEmpty: Boolean read GetIsEmpty;
    property RowCount:Integer read GetRowCount;
  end;

I won’t go into the details on the TGridViewColumn yet, but note the two abstract methods in the controller: DefineAttributes and GetRowCount. To make a working grid, these are what we need to override.

The Grid property identifies the grid that we will control and DrawCell is the method we plug into the grid onDrawCell event. MakeColumn is called by the CreateTextColumn with the appropriate TGridColumnView descendant – hiding the interaction with our parent string list. I guess you already have figured out that IsEmpty simply check the number of rows.

A simple Example

Lets consider the simplest possible example: a grid showing rows with the numbers 1 to 5, and their values squared. Note that the unit is pretty ignorant about what a grid is.

unit DemoNumbersClass;

interface

uses
  Classes, SysUtils, FDCGridViewController;

type
  TViewNumbers = class(TGridViewController)
  private
    function GetNumber(const Row: Integer): String;
    function GetNumberSquared(const Row: Integer): String;
  protected
    procedure DefineAttributes; override;
    function GetRowCount: Integer; override;
  end;

We define two columns, and refer each column to a data retrival method.

implementation

{ TViewNumbers }

procedure TViewNumbers.DefineAttributes;
begin
  CreateTextColumn('Number', GetNumber);
  CreateTextColumn('Squared', GetNumberSquared, 64, taRightJustify);
end;

function TViewNumbers.GetNumber(const Row: Integer): String;
begin
  Result := IntToStr(Row);
end;

function TViewNumbers.GetNumberSquared(const Row: Integer): String;
begin
  Result := IntToStr(SQR(Row));
end;

function TViewNumbers.GetRowCount: Integer;
begin
  Result := 5;
end;

end.

Then we create a Form, drop a string grid on it, tweak some row size settings etc., and add the controller.

unit DemoFDCGridViewController;

interface

uses
  Windows, Messages, SysUtils, Classes, Controls, Forms,
  StdCtrls, Grids, FDCGridViewController, DemoNumbersClass;

type
  TGridViewForm = class(TForm)
    StringGrid1: TStringGrid;
    procedure FormCreate(Sender: TObject);
  private
    Numbers : TViewNumbers;
  public
    { Public declarations }
  end;

var
  GridViewForm: TGridViewForm;

implementation

{$R *.dfm}

{ TGridViewForm }

procedure TGridViewForm.FormCreate(Sender: TObject);
begin
  // Create our controller
  Numbers := TViewNumbers.Create;
  // and introduce the controller to the host grid
  Numbers.Grid := StringGrid1;
end;

end.

And the result:

As you can see, there are a few tweaks that I haven’t described yet. Also, I still haven’t revealed the simple steps done to invade our host grid.

Stay tuned 🙂

A couple of years back, I set up a homepage with some forum software and tried to do some lightweight blogging – but – unfortunately the spammers really loved this free publishing mechanism and filled up my forum with trash. I ended up shutting down that project.

But, as the saying goes – publish or perish – so here I go again but this time in a hopefully better protected environment.

This is the first article in what I hope will be a series on creating lightweight reusable code, and although I have no ambitions about making this a widespread toolkit, I hope it may be of use to someone.
It certainly is of use to me 🙂

Reusable Grid View – part 1

Needful Things

Did you ever write your data to a logfile to check them out? Maybe you wrote them to a string list and showed them in a Memo? Maybe you even stuffed them into a TStringGrid and found out the hard way how expensive that can be if you have a lot of data and how poorly the numeric data display as a string. You often end up having to tweak and re-tweak the formatting to make the dump readable.

After having to implent similar gridviews in three different tasks back to back and seeing more on the horizon, I decided that I wanted to make it easier to quickly put together a gridview for a specific set of data.

There are a lot of nice custom grid controls out there, but they all come at a price – either in the form of purchase, or in the form of having to invest time in writing glue to get your data in there, or even with cost of pure payload. Some grids are so function rich that they almost are a system in their own right.

Totally ignoring the not-invented-here syndrome warning lights, I decided to make my own little quick grid viewing kit.

Design goals

• Make it ignorant to the underlying data structure
• Avoid having to adapt your data structure to this specific viewer
• Avoid duplicating data
• Make it easy to configure
• Make it easy to extend and modify

Design tradeoffs

• The underlying data must have a known number of rows
• Each column will be have one type of content
• Make it reasonably stupid
  Bells: No
  Whistles: No
  Nice to haves: Well, maybe a few 🙂

Isolating the data and the viewer

In a way, the top three goals are in conflict. How can you access content if you don’t know the format of the content? If you don’t know the format, don’t you have to convert it somehow, and don’t you have to store that conversion? If you don’t adapt the data to the viewer, how can you make a generic viewer?

Those that work with databases and web probably already know the answer: Base the solution on the Model View Controller pattern.

We need to find an effective way to encapsulate the data and present that encapsulation to the grid control. Let’s briefly look at the options for encapsulating the data here.

• Inheritance – Not good – I don’t want to force our data to be based on a type specific to my viewer
• Aggregation – I can make a class that knows both the dataset and the viewer

Aggregation allows me to write a base class that incorporate all the knowledge about the grid side of the problem, leaving only the need to implement a reasonably thin data access layer.

Since I don’t want to duplicate content into the grid, I need to find a good way to retrieve what I need on demand and to massage it into the format I need to display it on the fly. The solution is to use something along the lines of a Visitor pattern. Since grid views typically have static columns – ie all fields in a column is of the same type – I will make the visitor look at the data from a column perspective, identifying which row it is visiting. This will be the column visitor (aka TGridViewColumn). I will create different type of grid view columns for different type of data. String, boolean, integer, float, date, and even an image one – which basically is just the integer visitor with a custom draw.

The Grid Controller

To avoid having to recreate the grid from scratch, I am going to attach myself to a TStringGrid. I am not going to inherit from it, just wrap it and inject myself where it counts. Why no inheritance? Well – I might want to move this code to a more capable grid at a later point in time. Also, by wrapping it – I can attach myself to a standard grid that is dropped in at design time without having to make a new component. This will be my grid controller (aka TGridViewController).

Custom Drawing

My key point for doing all this is to be able to display the data as best as I can. Hence, I will replace the TStringGrid cell drawing routine with my own. Firstly, I need a new string drawing routine. I’m going to add center and right justify, so that it will be easy to convert a number to a string, and then draw the string right justified. Fortunately, TStringGrid.OnDrawCell allows me to do inject my custom draw without severe tampering with TStringGrid.

I wasn’t going to put in a lot of bells and whistles in my reusable grid view, but one thing that I thought would be useful was the abilty to control row color and column color. If I am viewing some sort of log – it would be nice if I could highlight a row with a problem, or a row matching some sort of highlight criteria. Again – I want to give the controller the same ability to tie together the underlying data and the color changes, so I will use the same visitor model for retrieving the customized color.

I am splitting my custom draw routine between the grid controller and the column visitor. This allow me to match the drawing customisation to the data access and conversion, both from a row as well as a column perspective. The column draw routine is actually split in a generic housekeeping outer draw routine, and a specific detail inner draw routine.

Property Getter

Initially I thought I would write descendant classes for each GridViewColumn per implementation. I.e. for each new view, I would write a class per column, inheriting the class from the appropriate column type (string, mumber etc). But then I realized that would mean quite a few extra lines of code to set up a grid.

So- how about using a pluggable visitor routine instead? That way I could actually implement the column data type column only once – and only add a single visitor routine in the custom GridViewController to retrive the actual value that is to be translated and drawn. The extra call overhead isn’t really signficant since we are not typically talking several thousands of calls, but usually just a few hundred. Hence the GridViewColumn now has it’s own property which hold the function used to retrieve the cell value from the GridViewController.

type
  TGetTextMethod = function(const row:Integer):String of object;
  TGetDoubleMethod = function(const row:Integer):Double of object;

That’s all for the first part. More to come.