Custom Drawing

• Apr 02, 2024
• 4 minutes to read

This topic describes how to custom draw the scheduler control’s elements. The examples in this topic are based on the ExpressScheduler CustomDrawDemo that ships with this product.

There are two alternatives that allow developers to customize the scheduler control’s appearance – by using styles or performing custom drawing. The first is easy to implement but not so flexible, the latter is much more flexible but requires coding.

The following image shows the scheduler’s elements:

Note: the scheduling area‘s background is only visible in the Day View that occupies a part of the scheduling area along the y-axis (the vertical scrollbar in the scheduling area disappears). For example, to make this available the following conditions should be met: the View’s TimeScale property is set to 60 and the scheduler’s parent is big enough to allow the scheduler control to show its content without the scrollbar. The Date Navigator‘s background can be visible if the scheduler’s OptionsCustomize.IntegralSizing property is set to False. The following images show the scheduling area’s and Date Navigator’s backgrounds:

As for custom drawing, the scheduler control exposes the following events, which are fired when painting specific scheduler elements.

Event	Description
TcxScheduler.OnCustomDrawBackground	Allows you to custom paint the scheduling area’s background. Note: the background is only visible in the Day View that occupies a part of the scheduling area along the y-axis (the vertical scrollbar in the scheduling area disappears).
TcxScheduler.OnCustomDrawButton	Allows you to custom paint the “more events” button, that end-users can use to scroll to user events outside of the current boundaries of the scheduling area or a day’s cell in the Week, Weeks, Year or TimeGrid View).
TcxScheduler.OnCustomDrawContent	Allows you to custom paint time blocks in the scheduling area.
TcxScheduler.OnCustomDrawDayHeader	Allows you to custom paint the day’s header.
TcxScheduler.OnCustomDrawEvent	Allows you to custom paint a user event scheduled in the scheduling area.
TcxScheduler.OnCustomDrawGroupSeparator	Allows you to custom paint the group separator in the scheduling area (a bar that visually divides groups of schedules when schedules grouped).
TcxScheduler.OnCustomDrawResourceHeader	Allows you to custom paint the resource’s header in the scheduling area.
TcxSchedulerDayView.OnCustomDrawContainer	Allows you to custom paint the all-day event area located on the top of a day.
TcxSchedulerDayView.OnCustomDrawTimeRuler	Allows you to custom paint the time ruler(s).
TcxSchedulerTimeGridView.OnCustomDrawMajorUnit	Allows you to custom paint the major time scale.
TcxSchedulerTimeGridView.OnCustomDrawMinorUnit	Allows you to custom paint the minor time scale.
TcxSchedulerTimeGridView.OnCustomDrawSelectionBar	Allows you to custom paint the time selection bar.
TcxSchedulerDateNavigator.OnCustomDrawBackground	Allows you to custom paint the Date Navigator’s background. Note: this background is displayed if the scheduler’s OptionsCustomize.IntegralSizing property is set to False.
TcxSchedulerDateNavigator.OnCustomDrawContent	Allows you to custom paint the Date Navigator month(s)’ background.
TcxSchedulerDateNavigator.OnCustomDrawDayCaption	Allows you to custom paint day captions in the Date Navigator.
TcxSchedulerDateNavigator.OnCustomDrawDayNumber	Allows you to custom paint dates in the Date Navigator.
TcxSchedulerDateNavigator.OnCustomDrawHeader	Allows you to custom paint the Date Navigator’s month(s) header.
TcxSchedulerResourceNavigator.OnCustomDrawButton	Allows you to custom paint resource navigation buttons.

Parameters, provided with these events, are unified to facilitate the task of developing custom code:

Sender – specifies the time View shown in the scheduling area, for the TcxScheduler, TcxSchedulerTimeGridView, and TcxSchedulerDayView events. As for the TcxSchedulerDateNavigator events, Sender references the Date Navigator instance.

ACanvas – specifies the drawing surface.

AViewInfo – provides rendering information (a ViewInfo object).

ADone – specifies whether default painting is required. If ADone is True, it prevents the default repainting after custom rendering has been finished.

The following examples show how to handle the TcxSchedulerDateNavigator events listed above.

Note

the output as shown below is produced only if the LookAndFeel.NativeStyle property is set to False and the lfFlat flag on the LookAndFeel.Kind property is active.

OnCustomDrawBackground

// ...
  ACanvas.Brush.Color := $FFCCCC;
  ACanvas.FillRect(ABounds);
  ADone := True;

OnCustomDrawContent

// ...
var
  AColor: TColor;
begin
  case AViewInfo.Month of
    3..5: AColor := $D0FFD0;  // spring
    6..8: AColor := $9988FE;  // summer
    9..11: AColor := $D0FFFF; // autumn
  else
    AColor := clWhite;        // winter
  end;
  ACanvas.Brush.Color := AColor;
end;

OnCustomDrawDayCaption

// ...
  if AViewInfo.Index in [0, 6] then  // Sunday and Saturday are off days
    ACanvas.Font.Color := clRed
  end;

OnCustomDrawDayNumber

// implementing the OnCustomDrawDayNumber event handler in this example is optional. The OnCustomDrawContent event handler (described above) does all the work necessary because the day numbers should be colored in the same way as the month's background in this context. The code that implements the painting of the day numbers is for demonstration purposes only.

Delphi

// ...
  if AViewInfo.Selected then Exit;
  AViewInfo.Transparent := True;
  case MonthOf(AViewInfo.Date) of // specify the cxDateUtils unit in the uses clause
    1,2,12: ACanvas.Brush.Color := clWhite;
    3..5: ACanvas.Brush.Color := $80FF80;
    6..8: ACanvas.Brush.Color := $A0A0FF;
    9..11: ACanvas.Brush.Color := $80FFFF;
  end;

OnCustomDrawHeader

// ...
  ACanvas.Brush.Color := $80FFFF;

This is the result when default drawing is used:

Here is the result when all the event handlers mentioned above are applied: