Xojo Documentation Xojo Documentation

Method

Graphics.Clip(X As Double, Y As Double, Width As Double, Height As Double) As Graphics

New in 2007r4

Supported for all project types and targets.

Creates a new Graphics object in the parent Graphics object. It has the size and shape defined by the passed parameters.

Notes

Graphics calls can only draw inside the passed bounds. After creating a clip, you can draw into it, as with any other Graphics object. However the drawing will be contained within the clipping, not the parent object. Use this to prevent objects from overlapping with other objects in the parent object. Whatever is drawn to the clipped region is confined to that region.

Clip allows clipping beyond the bottom and right edges of the source. This ensures the resulting graphics object will always be the dimensions requested.

Sample Code

When you are drawing a complex image that involves many calls to Graphics methods, you may want to create non-overlapping regions within the area. You then draw into each "child" area, with the assurance that each drawing will not inadvertently overlap another object.

You create a child region within the parent area with the Clip method. You pass it the top-left corner of the child region and its width and height. It returns a new Graphics object that is the specified region inside the parent area. You can then draw into the child area just as with any other Graphics object. The only difference is that the drawing will be confined to the child area. The coordinates of each call are with respect to the top-left corner of the child area. Here is an example of how this works. This code is in the Paint event of a Canvas. Two regions at the top of the Canvas are defined by calls to the Clip method. Subsequent calls to the DrawRect method show where the clippings are. Calls to the DrawOval method draw shapes within the clipped areas. Notice that the first call attempts to draw outside the area. If you were drawing from the parent Graphics object, the first oval would bump into the second.

Sub Paint (g As Graphics)
Var myClip As Graphics = g.Clip(0, 0, 150, 15)
Var myClip2 As Graphics = g.Clip(150, 0, 150, 15)
// Draw the border of the Canvas in black
g.DrawingColor = &c000000
g.DrawRectangle(0, 0, g.Width, g.Height)
// Draw into the first area in red
myClip.DrawingColor = &cff0000
myClip.DrawRectangle(0, 0, myClip.Width, myClip.Height) // draw the border of the area.
myClip.DrawOval(0, 0, 200, 15) // try to draw outside its clip.
// Draw into the second area in blue
myClip2.DrawingColor = &c0000ff
myClip2.DrawRectangle(0, 0, myClip2.Width, myClip2.Height) // draw the border
myClip2.DrawOval(0, 0, 150, 15)

Here is the Canvas that is produced from this code.

Two regions defined by the Clip method within a Canvas control.