TcxCustomListView.OnAdvancedCustomDrawSubItem Event

Occurs during the painting of the list view sub-items in an owner-draw list view.

Declaration

property OnAdvancedCustomDrawSubItem: TLVAdvancedCustomDrawSubItemEvent read; write;

Remarks

The OnAdvancedCustomDrawSubItem event fires for each individual sub-item of the control’s items before and after its default painting takes place. The Stage parameter enables you to identify whether item painting is about to be performed or has been completed.

If the Stage parameter returns the cdPrePaint value, sub-item painting has not been performed yet. In this case, you may perform your own painting of the processed item and its sub-items and set the DefaultDraw parameter to False. This value of the DefaultDraw parameter implies that default painting of the processed item will not be performed. Note that if you only need to perform painting before the default drawing routine is executed, you should handle the OnCustomDrawItem event instead. This event fires twice as little times as the OnAdvancedCustomDrawItem event, which results in a performance benefit.

If the Stage parameter returns the cdPostPaint value, sub-item painting has already been finished. At this time, you may perform any additional painting you like. Note that the DefaultDraw parameter is not in effect when the Stage parameter value is cdPostPaint. The reason is that no other painting will take place further anyway.

The Sender parameter of the event specifies the control whose sub-item is being painted. Use the Canvas property of the object representing this parameter to obtain the canvas used to paint. The Item parameter enables you to determine the currently processed item. Use it to get the bounding rectangle of the item (the DisplayRect method) and other information needed when painting (caption text, image indexes, etc). The State parameter can be used to determine the state of the painted item. The cdsSelected and cdsHot values included into this parameter’s value indicate that the item is selected or hot-tracked respectively.

The following code handles the OnAdvancedCustomDrawSubItem event. It paints the background of sub-items’ text labels with textures of different colors. The custom font settings are applied also:

procedure TForm1.cxListView1AdvancedCustomDrawSubItem(
 Sender: TCustomListView; Item: TListItem; SubItem: Integer;
 State: TCustomDrawState; Stage: TCustomDrawStage;
 var DefaultDraw: Boolean);
var
  ACanvas: TCanvas;
  ARect, ALabelRect, ASubRect: TRect;
  AOddPicture, AEvenPicture: TBitmap;
  ALeft, ATop, AWidth, AHeight: Integer;
begin
//loading the required bitmaps from files
  AOddPicture := TBitmap.Create;
  AEvenPicture := TBitmap.Create;
  AOddPicture.LoadFromFile('C:\IMAGES\BLUE.BMP');
  AEvenPicture.LoadFromFile('C:\IMAGES\RED.BMP');
  ACanvas := Sender.Canvas;
//ARect contains a rectangle representing the whole item area, including all subitems
  ARect := Item.DisplayRect(drBounds);
//ALabelRect contains a rectangle representing the text label of an item
  ALabelRect := Item.DisplayRect(drLabel);
//obtaining the subitem bounding rectangle
  ALeft := ALabelRect.Right;
  ATop := ARect.Top;
  AWidth := ARect.Right - ALabelRect.Right;
  AHeight := ARect.Bottom - ARect.Top;
  ASubRect := Bounds(Aleft, ATop, AWidth, AHeight);
//
  if Stage = cdPrePaint then
  begin
//background of subitems within odd rows is filled with blue texture
    if Odd(Item.Index) then ACanvas.StretchDraw(ASubRect, AOddPicture)
    else
//background of subitems within even rows is filled with red texture
      if not Odd(Item.Index) then ACanvas.StretchDraw(ASubRect, AEvenPicture);
//applying font settings for subitems: transparent background, white color and bold style
    SetBkMode(ACanvas.Handle, TRANSPARENT);
    SetTextColor(ACanvas.Handle, clWhite);
    ACanvas.Font.Style := [fsBold];
//selecting the prepared font object
    SelectObject(ACanvas.Handle, ACanvas.Font.Handle);
//drawing the subitem text using the prepared font settings
    ACanvas.TextOut(ASubRect.Left + 1, ASubRect.Top + 1, Item.SubItems[SubItem - 1]);
  end;
  AOddPicture.Free;
  AEvenPicture.Free;
end;

The following image demonstrates the result of the code execution: