Xceed Grid for WinForms v4.3 Documentation
Custom painting
Welcome to Xceed Grid for WinForms v4.3 > Advanced Concepts > Custom painting

Xceed Grid for WinForms provides 2 different ways to do custom painting:

  1. You can handle the Paint event of any grid element that derives from the VisualGridElement class. 

  2. You can derive from the grid element for which you want to provide custom painting and override the PaintForeground method, which is called to paint the foreground of the grid element; the PaintBackground method, which is called to paint the background of the grid element; and the PaintBorders method, which is called to paint the borders of the grid element.

If you choose to simply handle the grid element's Paint event, only additional painting of the grid element's foreground can be provided. The Paint event is raised after the grid element's background, foreground and borders have been drawn and allows for additional painting of the grid element's foreground. This is the easiest way to provide custom painting; however, it does not provide a lot of flexibility and control.

To have full control over the painting of a grid element, a class that derives from the grid element must be created and the PaintForeground, PaintBackground and PaintBorders methods overridden.

Painting

In all cases, there are specific rectangle regions in which you need to paint. When handling the Paint event or overriding the PaintForeground and/or PaintBackground methods, the painting must be done in either the ClientRectangle or DisplayRectangle received in the event args. Keep in mind that an empty rectangle structure signifies that the grid element is not visible. 

The diagram demonstrates the various rectangle regions of rows and cells: 

The Bounds of a visual grid element is a rectangle structure similar to the DisplayRectangle rectangle, but includes the borders. 

In the case of the PaintBorders method, the painting must be done outside of the grid element's DisplayRectangle within the borders. By default, the width of grid element's borders are set to 1 pixel for the bottom and right borders and 0 for the top and left borders. In order to change these settings, the Borders property needs be overridden to return the desired Borders structure. 

For example, if a grid element has a border with a width of 1 pixel all around and a DisplayRectangle with its dimensions set at 0 for its X coordinate, 0 for its Y coordinate, 10 for its width and 12 for its height, in order to paint the left border of the grid element, the coordinates of the left border's rectangle would be -1 for the X coordinate, -1 for the Y coordinate, 1 for the width and 14 for the height. 

When overriding the paint events, you can decide to call the base implementation already provided or you can decide to completely redo the painting. It is not obligatory to call the base implementation unless the default painting behavior is wanted.

Exceptions

There are 2 exceptions in regards to the ClientRectangle and DisplayRectangle: In the case of the grid itself, the DisplayRectangle represents the visible portion of the grid excluding the borders and scrollbars while the ClientRectangle represents the visible portion of the grid including borders and scrollbars.

In the case of the GroupMargin class, the DisplayRectangle is always the same as the ClientRectangle.

Converting points and rectangles

The following table provides a listing of all the methods that are available to convert both Points and Rectangles to and from screen, grid and client coordinates: 

Method Description
PointToClient Converts the location of the specified screen point into client coordinates.
PointToScreen Converts the location of the specified client point into screen coordinates.
RectangleToClient Converts the size and location of the specified screen rectangle in client coordinates.
RectangleToScreen Converts the size and location of the specified client rectangle in screen coordinates.
GridPointToClient Converts the location of the specified grid point into client coordinates.
ClientPointToGrid Converts the location of the specified client point into grid coordinates.
GridRectangleToClient Converts the size and location of the specified grid rectangle in client coordinates
ClientRectangleToGrid Converts the size and location of the specified client rectangle in grid coordinates