Graphics

From Xojo Documentation

Revision as of 18:55, 19 November 2009 by 10.0.1.5 (talk) (Examples)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Description

Graphics class objects are used for drawing text, lines, rectangles, ovals, and pictures. Normally you use a graphics object in response to a Paint event, but you can also perform direct drawing by using the Graphics property of a Canvas control. Alternatively, you can create vector graphics using the subclasses of the Object2D class. You cannot create a meaningful Graphics object via the New command.

On Windows, the Graphics class will use GDI+ if the Application.UseGDIPlus property is set to True.


Super Class

 Object

Properties

Name Type Parameters Description
Bold Boolean If True, text will appear in bold when using the DrawString method.
Copies
Integer The value in the Copies field of the Print dialog box.

This property is only meaningful when the graphics object was created by the OpenPrinterDialog function.

FirstPage
Integer The value in the From field of the Print dialog box.

This property is meaningful only when the graphics object was created by the OpenPrinterDialog function.

ForeColor Color The currently selected color for the Graphics object. This color is used by the various drawing methods.
Handle
Introduced 2005R5
 Integer Type as Integer Gets the OS Handle for the passed Type. Pass a Graphics class constant to specify the Type.

The class constants are as follows:
1-HandleTypeHDC. Gets the HDC on Windows.
2-HandleTypeCGrafPtr. Gets the QuickDraw CGrafPtr on Macintosh.
3-HandleTypeGdkDrawablePtr. Gets the GdkDrawable * on Linux.
4-HandleTypeGdkGCPtr. Gets the GdkGC * on Linux.
5-HandleTypeCGContextRef
6-HandleTypeGDIPlusGraphics. Obtains a handle to a GDI+ graphics handle. This requires that App.UseGDIPlus is enabled.Introduced 2009r4
Handle will return zero if the requested handle Type is not available or is not supported.

Height
Integer The height in pixels of the parent object, typically a Canvas control or a Window.

For example, if the graphics class object is in a Canvas control, Height returns the height of the control.

Italic Boolean If True, text will appear in italic when using the DrawString method.
LastPage
Integer The value in the "To" field of the Print dialog box.

This property is meaningful only when the graphics object was created by the OpenPrinterDialog function.

PenHeight Integer The height in pixels used when drawing lines, ovals, and rectangles.
PenWidth Integer The width in pixels used when drawing lines, ovals, and rectangles.
Pixel Color X as Integer,

Y as Integer

Used to get and set the color of a particular pixel.
TextAscent
Integer Returns the ascent of a line of text drawn with the current font.
TextFont String Used to get and set the current font.

You use the name of the font or REALbasic's two metafonts, "System" and "SmallSystem." The System font is the font used by the system software as its default font. Different operating systems use different default fonts. If the system software supports both a large and small System font, you can specify the "SmallSystem" font as your TextFont. On Macintosh, "SmallSystem" specifies the OS's smaller system font. On Windows and Linux, "SmallSystem" is the same as "System."

TextHeight
Integer Contains the height of a line of text drawn with the current font.
TextSize Single
Changed 2009r4
Used to get and set the current font size in points.

If you use zero as the TextSize, REALbasic will choose the font size that works best for the platform on which the application is running.

Underline Boolean If True, text will appear in underline when using the DrawString method.
UseOldRenderer
Changed 5.5
Boolean If True, rendering under Mac OS X is done via QuickDraw rather than Quartz and text drawing is done via QuickDraw in Mac OS X. The default is False.

The QuickDraw rendering engine is generally faster than Quartz, but Quartz provides the 'native' Mac OS X look. If you need faster drawing and are not concerned about Mac OS X anti-aliasing, consider using UseOldRenderer. The property can be modified at runtime. The default for a new object is False. This property may also be useful if you need to make your graphics look exactly the same on Mac OS X as it would on Mac OS 9. (REALbasic 2007 Release 4 and above no longer support Mac OS 9 builds.)

Width
Integer The width in pixels of the parent object, typically a Canvas control or a Window.

For example, if the graphics class object is in a Canvas control, Width returns the width of the control.

Methods

The X and Y parameters of the methods are the horizontal and vertical coordinates of the left-top corner of the object being drawn or cleared. The origin (0,0) is the top-left corner of the control or window in which the drawing is being done. For example 50,50 is 50 pixels to the right and 50 pixels down from the top-left of the window or control.

Name Parameters Return Type Description
ClearRect X as Integer,

Y as Integer,
Width as Integer,
Height as Integer

Clears the rectangle described by the parameters passed by filling it with the background color of the parent window.
Clip
Introduced 2007r4
X as Integer,

Y as Integer,
Width as Integer,
Height as Integer

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

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.

DrawCautionIcon X as Integer,

Y as Integer

Draws the operating system's Caution icon at the coordinates specified.
DrawLine X1 as Integer,

Y1 as Integer,
X2 as Integer,
Y2 as Integer

Draws a line from X1, Y1 to X2, Y2 in the current color. The current color is set with the ForeColor property.
DrawNoteIcon X as Integer,

Y as Integer

Draws the operating system's Note icon at the coordinates specified. X and Y are the coordinates of the top-left corner.
DrawObject Object as Object2D,

[DeltaX as Integer,
DeltaY as Integer]

Draws the passed Object2D object. The optional parameters DeltaX and DeltaY are offsets from the top-left corner of the Graphics object.
DrawOval X as Integer,

Y as Integer,
Width as Integer,
Height as Integer

Draws the outline of an oval in the current color. The current color is set with the ForeColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the oval.

DrawPicture Image as Picture,

X as Integer,
Y as Integer 
[,DestWidth as Integer ]
[, DestHeight as Integer ]
[, SourceX as Integer ]
[, SourceY as Integer ]
[, SourceWidth as Integer ]
[, SourceHeight as Integer]

Draws the picture at the specified location. The picture can be shown at full size, cropped, or scaled. All units are pixels.

X and Y are the distances from the top-left corner of the control or window from which the 0,0 point of the image will be drawn. The optional parameters are used to copy a portion of the picture (cropping) and for scaling the picture. If you are cropping, then DestWidth and DestHeight are also required. If you are doing scaling, then all of the optional parameters are required. You scale an image by making the destination width and height different from the source width and height. The parameters SourceX, SourceY, SourceWidth, and SourceHeight describe the portion of the image that will be scaled. DestWidth and DestHeight are used to change the scaling of the picture when SourceWidth and SourceHeight are provided. SourceX and SourceY default to 0 and are used to determine the upper-left coordinate you wish to copy from. Please see the examples of full-size, 50% scaled, and cropped in the Examples section. DrawPicture uses GDI+ to draw the picture if Application.UseGDIPlus is enabled.

DrawPolygon Points() as Integer Draws a polygon using the values in the 1-based array passed as the X and Y coordinates. The polygon is drawn in the current color. The current color is set with the ForeColor property.

Odd numbered array elements are X coordinates and even numbered array elements are Y coordinates.

DrawRect X as Integer,

Y as Integer,
Width as Integer,
Height as Integer

Draws the outline of a rectangle in the current color. The current color is set with the ForeColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the rectangle.

DrawRoundRect X as Integer,

Y as Integer,
Width as Integer,
Height as Integer,
ArcWidth as Integer,
ArcHeight as Integer

Draws the outline of a rounded rectangle in the current color. The current color is set with the ForeColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the round rectangle. ArcWidth and ArcHeight control the shape of the corners in the horizontal and vertical axes, respectively. They are the distance (in pixels) from the corner at which the arc begins. Setting them to zero results in a rectangle with sharp corners.

DrawStopIcon X as Integer,

Y as Integer

Draws the operating system's Stop icon at the coordinates specified. X and Y are the coordinates of the top-left corner.
DrawString
Changed 2005r1
Text as String,

X as Integer,
Y as Integer
[,WrapWidth as Integer ]
[,Condense as Boolean ]

Draws the text at the specified location and in the current color. The current color is set with the ForeColor property.

The X parameter specifies the distance from the left of the Graphics object in pixels. The Y parameter specifies the baseline for the text. The optional WrapWidth parameter specifies the width (in pixels) at which Text should wrap. The Text will wrap if WrapWidth is provided and Condense is False (The default is False). If WrapWidth is omitted, then Text will print on one line, event if the window or RectControl is too narrow to contain the text. If the optional Condense property is True, DrawString truncates the string to fit into the space specified by WrapWidth and uses an ellipsis ("...") to indicate that there is additional text that is not shown. The default values of WrapWidth and Condense are zero and False, respectively. The default behavior is to print the string on one line.

FillOval X as Integer,

Y as Integer,
Width as Integer,
Height as Integer

Draws an oval filled with the current color. The current color is set with the ForeColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the oval.

FillPolygon Points() as Integer Draws a polygon using the values in the 1-based array passed as the x and y coordinates.

Odd numbered array elements are X coordinates and even numbered array elements are Y coordinates. The polygon is filled with the current color. The current color is set with the ForeColor property.

FillRect X as Integer,

Y as Integer,
Width as Integer,
Height as Integer

Draws a rectangle filled with the current color. The current color is set with the ForeColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the rectangle.

FillRoundRect X as Integer,

Y as Integer,
Width as Integer,
Height as Integer,
ArcWidth as Integer,
ArcHeight as Integer

Draws a rounded rectangle filled with the current color. The current color is set with the ForeColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the round rectangle. ArcWidth and ArcHeight control the shape of the corners in the horizontal and vertical axes, respectively. They are the distance (in pixels) from the corner at which the arc begins. Setting them to zero results in a rectangle with sharp corners.

NextPage When printing a graphics object, this method will cause the current page to be printed and a new page to be created.
StringDirection
Introduced 2005r1
Text as String Integer Returns an Integer that indicates the direction in which the text is written.

This is useful for non-Roman systems, especially Middle-Eastern languages. If you pass an empty string, it returns the system default string direction. If REALbasic doesn't support this function on the user's system, it will return -1; otherwise it will return either 0 for left to right or 1 or right to left. There are three class constants that you can use to test the string direction: TextDirectionUnknown: -1
TextDirectionLeftToRight: 0
TextDirectionRightToLeft: 1

StringHeight Text as String,

WrapWidth as Integer

Integer Returns as an Integer the height of the text based on the current font and font size (in pixels) and the passed WrapWidth (also in pixels).

The WrapWidth parameter specifies the width (in pixels) at which text should wrap.

StringWidth Text as String Double Returns as a Double the width of the text (based on the current font and font size) in pixels.

Prior to version 2007 Release 2, StringWidth returned an Integer. Currently, only Mac OS X supports fractional widths. In the future, fractional widths may be supported on other platforms.

Class Constants

Handle

The following class constants can be used to specify value of the Type parameter of the Handle property.

Class Constant Description
HandleTypeHDC Gets the HDC on Windows.
HandleTypeCGrafPtr Gets the port of the graphics object on Macintosh.
HandleTypeGdkDrawablePtr Gets the GdkDrawable * on Linux.
HandleTypeGdkCGPtr Gets the GdkGC * on Linux


StringDirection

The following class constants can be used to test the value of the StringDirection property.

Class Constant Value
TextDirectionUnknown -1
TextDirectionLeftToRight 0
TextDirectionRightToLeft 1

Notes

By default, REALbasic uses the Quartz graphics engine on Mac OS X when you call methods of the Graphics class such as DrawLine, DrawRect, DrawOval, and so forth. The Quartz graphics engine uses anti-aliasing to make lines look smoother. The disadvantage is that it is slower than line drawing using the older Apple technology. For most applications, the Quartz engine will be fast enough and it does produce more attractive results on Mac OS X. However, if you need more speed, you can improve the performance of the drawing methods under Mac OS X by turning off the Quartz graphics engine and using the QuickDraw engine instead. Do this by setting the UseOldRenderer property of the Graphics class to True before you begin drawing.


Examples

This example uses the Paint event handler of a Canvas control to draw the text "The quick brown fox" in Helvetica bold, italic, 18 point, 50 pixels from the top of and 10 pixels from the left side of the control.

Sub Paint(g As Graphics)
g.Bold=True
g.Italic=True
g.TextFont="Helvetica"
g.TextSize=18
g.DrawString "The quick brown fox", 10, 50


This example assigns the color of a particular pixel in a Canvas control to a variable.

Dim c as Color
c=Canvas1.Graphics.Pixel(10,10)


This example sets a particular pixel of a Canvas control to a specific RGB value.

Canvas1.Graphics.Pixel(10,10)=RGB(100,105,225)


This is example draws a triangle in a Canvas control. It is placed in the Paint event. The parameter g as Graphics is passed into this event.

Dim Points() as Integer
Points=Array(10,10,100,50,10,200,10,10)
g.ForeColor=RGB(100,200,255)
g.FillPolygon Points


The following example assumes that you have imported a resource file into the Project Editor that contains a PICT resource whose ID is 129. The following line of code in the Canvas control's Open event handler assigns the picture to the control's Backdrop property:

Me.backdrop=app.resourceFork.getpicture(129)

Note: Access to the resourcefork is supported only on Macintosh. Check the value of the TargetMacOS constant before attempting to access the resourcefork.

This example uses the Clip method to define child Graphics items within the parent Canvas. The code is in the Paint event of a Canvas. The two clippings define regions at the top of the canvas and the DrawOval method draws object in each one. Notice that the first call tries to draw an oval that is wider than the region. It is truncated in the drawing.

Dim myclip as Graphics = g.clip(0,0,150,15)
Dim myclip2 as Graphics=g.clip(150,0,150,15)

//draw the border of the Canvas..
g.forecolor=&c000000
g.DrawRect(0,0,g.width,g.height)

//draw into the first area...
myclip.ForeColor=&cff0000
myclip.DrawRect(0,0,myclip.width,myclip.height) //draw the border of the area..
myclip.DrawOval(0,0,200,15) //the oval does not appear outside the region
//despite the call


//draw into the second area...
myclip2.ForeColor=&c0000ff
myclip2.DrawRect(0,0,myclip2.width,myclip2.height) //draw the border of the area
myclip2.DrawOval(0,0,150,15)


Using DrawPicture

The following example scales an image by 50%. The image, myImage, has been added to the Project Editor. Its size is 600 x 915. Note that the destination width and height are half the original width and height. The code is in the Paint event of a Canvas. A call to DrawRect adds a black border around the Canvas.

g.ForeColor= &c000000
g.DrawRect 0,0,Me.width,Me.height
g.DrawPicture(myImage,0,0,300,457,0,0,600,915)


The following code crops the image. It copies only the top 150 pixels of the original image at full size:

g.DrawPicture(myImage,0,0,600,150)


The following code crops and scales the image. The top half of the image is retained and the DestWidth and DestHeight parameters specify a 50% reduction.

g.DrawPicture(myImage,0,0,300,228,0,0,600,457)


If you don't want to scale or crop the image, you can leave off the last six parameters. In this case, it will appear full-size.

g.DrawPicture(myImage,0,0)

See Also

Canvas control.