Difference between revisions of "Graphics"

From Xojo Documentation

(Removing DrawPolygon and FillPolygon since both are deprecated as of 2020r1.)
(Available on all platforms)
 
(17 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{SupportedPlatforms | type = a}}
 
 
{{WebApp | link = [[WebGraphics]]}}
 
{{WebApp | link = [[WebGraphics]]}}
 
 
{{ClassBox
 
{{ClassBox
 
| super=[[Object]]
 
| super=[[Object]]
Line 8: Line 6:
 
}}
 
}}
 
{{Description
 
{{Description
|text = '''Graphics''' class objects are used for drawing text, lines, rectangles, ovals, and pictures. Normally you use a graphics object in response to a [[Canvas.Paint]] event, but you can also perform direct drawing by using the '''Graphics''' property of a [[Picture]]. Alternatively, you can create vector graphics using the subclasses of the [[Object2D]] class. You cannot create a meaningful '''Graphics''' object via the [[New]] command.
+
|text = '''Graphics''' class objects are used for drawing text, lines, rectangles, ovals, and pictures.}}
}}
+
 
 +
<dynamicTable id="Enumerations" class="methodTable" title="Enumerations" columns="3">
 +
{{Enum | name=HandleTypes | description=Specifies the type of OS handle you wish to receive for use with the Handle property.}}
 +
{{Enum | name=LineCapTypes | description=Specifies the various ways the end of a line is drawn.}}
 +
{{Enum | name=LineJoinTypes | description=Specifies the various ways lines can be joined.}}
 +
{{Enum | name=TextDirections | description=Specifies in which direction text will be rendered.}}
 +
</dynamicTable>
  
 
<dynamicTable id="Properties" class="propertyTable" title="Properties" columns="3">
 
<dynamicTable id="Properties" class="propertyTable" title="Properties" columns="3">
Line 15: Line 19:
 
{{Property | name=AntiAliasMode | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp; Controls the level of interpolation/quality when drawing scaled Pictures. Valid modes are LowQuality, DefaultQuality, and HighQuality. }}
 
{{Property | name=AntiAliasMode | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp; Controls the level of interpolation/quality when drawing scaled Pictures. Valid modes are LowQuality, DefaultQuality, and HighQuality. }}
 
{{Property | name=Bold | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, text will appear in bold when using the DrawText method. }}
 
{{Property | name=Bold | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, text will appear in bold when using the DrawText method. }}
 +
{{Property | name=Brush | type=GraphicsBrush | description=(GraphicsBrush)&nbsp;&nbsp;The brush to be used when drawing.}}
 
{{Property | name=CharacterSpacing | type=Integer | platform=all | description=( Integer)&nbsp;&nbsp;This property is expressed as a percentage of spacing between characters. Positive and negative values are accepted. }}
 
{{Property | name=CharacterSpacing | type=Integer | platform=all | description=( Integer)&nbsp;&nbsp;This property is expressed as a percentage of spacing between characters. Positive and negative values are accepted. }}
 
{{Property | name=Copies | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The value in the Copies field of the Print dialog box. }}
 
{{Property | name=Copies | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The value in the Copies field of the Print dialog box. }}
 
{{Property | name=FirstPage | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The value in the From field of the Print dialog box.  }}
 
{{Property | name=FirstPage | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The value in the From field of the Print dialog box.  }}
 
{{Property | name=DrawingColor | type=Color | platform=all | description=( Color)&nbsp;&nbsp;The currently selected color for the Graphics object. }}
 
{{Property | name=DrawingColor | type=Color | platform=all | description=( Color)&nbsp;&nbsp;The currently selected color for the Graphics object. }}
{{Property | name=Handle | type=Integer | platform=all| parameters=Type as [[Integer]] | readonly=yes | description=( Integer)&nbsp;&nbsp;Gets the OS Handle for the passed Type }}
 
 
{{Property | name=Height | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The height in pixels of the parent object, typically a Canvas control or a Window }}
 
{{Property | name=Height | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The height in pixels of the parent object, typically a Canvas control or a Window }}
 
{{Property | name=Italic | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, text will appear in italic when using the DrawText method. }}
 
{{Property | name=Italic | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, text will appear in italic when using the DrawText method. }}
 
{{Property | name=LastPage | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The value in the "To" field of the Print dialog box.  }}
 
{{Property | name=LastPage | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The value in the "To" field of the Print dialog box.  }}
{{Property | name=ScaleX | type=Double | platform=all | description=( Double)&nbsp;&nbsp;The scale factor used when converting user space coordinates to backing store coordinates. }}
+
{{Property | name=Outline | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, text will appear in outline when using the DrawText method. }}
{{Property | name=ScaleY | type=Double | platform=all | description=( Double)&nbsp;&nbsp;The scale factor used when converting user space coordinates to backing store coordinates. }}
 
 
{{Property | name=PenSize | type= Double | platform=all | description=( Double)&nbsp;&nbsp;The size used when drawing lines, ovals, and rectangles. }}
 
{{Property | name=PenSize | type= Double | platform=all | description=( Double)&nbsp;&nbsp;The size used when drawing lines, ovals, and rectangles. }}
 
{{Property | name=FontAscent | type= Double | platform=all | readonly=yes | description=( Double)&nbsp;&nbsp;Returns the ascent of a line of text drawn with the current font. }}
 
{{Property | name=FontAscent | type= Double | platform=all | readonly=yes | description=( Double)&nbsp;&nbsp;Returns the ascent of a line of text drawn with the current font. }}
 +
{{Property | name=Font | description=( Font)&nbsp;&nbsp;Used to get and set the current font on mobile.  }}
 
{{Property | name=FontName | type=String | platform=all | description=( String)&nbsp;&nbsp;Used to get and set the current font.  }}
 
{{Property | name=FontName | type=String | platform=all | description=( String)&nbsp;&nbsp;Used to get and set the current font.  }}
 
{{Property | name=FontSize | type=Single | platform=all | description=( Single)&nbsp;&nbsp;Used to get and set the current font size in points.  }}
 
{{Property | name=FontSize | type=Single | platform=all | description=( Single)&nbsp;&nbsp;Used to get and set the current font size in points.  }}
 
{{Property | name=FontUnit | type=FontUnits | platform=all | description=( FontUnits)&nbsp;&nbsp;The units in which FontSize is measured. }}
 
{{Property | name=FontUnit | type=FontUnits | platform=all | description=( FontUnits)&nbsp;&nbsp;The units in which FontSize is measured. }}
 +
{{Property | name=LineCap | type=Graphics.LineCapTypes | description=(Graphics.LineCaps)&nbsp;&nbsp;The type of cap at the end of the line.}}
 +
{{Property | name=LineDashOffset | type=Double | description=(Double)&nbsp;&nbsp;Specifies the starting point of the dash.}}
 +
{{Property | name=LineJoin | type=Graphics.LineJoinTypes | description=(Graphics.LineJoins)&nbsp;&nbsp;The way the line joins another line.}}
 +
{{Property | name=PrintingCancelled | type=Boolean | platform=mac | readonly=yes | modifiedinversion=2013r1 | description=( Boolean)&nbsp;&nbsp;If True, the current print job has been cancelled (macOS only). }}
 +
{{Property | name=ScaleX | type=Double | platform=all | description=( Double)&nbsp;&nbsp;The scale factor used when converting user space coordinates to backing store coordinates. }}
 +
{{Property | name=ScaleY | type=Double | platform=all | description=( Double)&nbsp;&nbsp;The scale factor used when converting user space coordinates to backing store coordinates. }}
 +
{{Property | name=ShadowBrush | type=ShadowBrush | description=(ShadowBrush)&nbsp;&nbsp;The ShadowBrush used to draw a shadow on the object being drawn.}}
 
{{Property | name=Transparency | type=Double | platform=all |  newinversion=2011r4 | description=( Double)&nbsp;&nbsp; The amount of transparency of all drawing. The range is from 0.0 (opaque) to 100.0 (transparent). }}
 
{{Property | name=Transparency | type=Double | platform=all |  newinversion=2011r4 | description=( Double)&nbsp;&nbsp; The amount of transparency of all drawing. The range is from 0.0 (opaque) to 100.0 (transparent). }}
 
{{Property | name=Underline | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, text will appear in underline when using the DrawText method. }}
 
{{Property | name=Underline | type=Boolean | platform=all | description=( Boolean)&nbsp;&nbsp;If True, text will appear in underline when using the DrawText method. }}
 
{{Property | name=Width | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The width in pixels of the parent object, typically a Canvas control or a Window }}
 
{{Property | name=Width | type=Integer | platform=all | readonly=yes | description=( Integer)&nbsp;&nbsp;The width in pixels of the parent object, typically a Canvas control or a Window }}
{{Property | name=PrintingCancelled | type=Boolean | platform=mac | readonly=yes | modifiedinversion=2013r1 | description=( Boolean)&nbsp;&nbsp;If True, the current print job has been cancelled (macOS only). }}
 
 
</dynamicTable>
 
</dynamicTable>
 
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.<br> For example, 50,50 is 50 pixels to the right and 50 pixels down from the top-left of the window or control.
 
  
 
<dynamicTable id="Methods" class="methodTable" title="Methods" columns="3">
 
<dynamicTable id="Methods" class="methodTable" title="Methods" columns="3">
 
{{Method | name=ClearRectangle | params=X as [[Integer]],  Y as [[Integer]],  Width as [[Integer]],  Height as [[Integer]] | description=ClearRectangle(X as Integer,  Y as Integer,  Width as Integer,  Height as Integer)&#x0A;Clears the rectangle described by the parameters passed by filling it with the background color of the parent window. }}
 
{{Method | name=ClearRectangle | params=X as [[Integer]],  Y as [[Integer]],  Width as [[Integer]],  Height as [[Integer]] | description=ClearRectangle(X as Integer,  Y as Integer,  Width as Integer,  Height as Integer)&#x0A;Clears the rectangle described by the parameters passed by filling it with the background color of the parent window. }}
 
{{Method | name=Clip | params=X as [[Integer]], Y as [[Integer]], Width as [[Integer]], Height as [[Integer]] | returntype='''Graphics''' | newinversion=2007r4 | description=Clip(X as Integer, Y as Integer, Width as Integer, Height as Integer) as '''Graphics'''&#x0A;Creates a new Graphics object in the parent Graphics object }}
 
{{Method | name=Clip | params=X as [[Integer]], Y as [[Integer]], Width as [[Integer]], Height as [[Integer]] | returntype='''Graphics''' | newinversion=2007r4 | description=Clip(X as Integer, Y as Integer, Width as Integer, Height as Integer) as '''Graphics'''&#x0A;Creates a new Graphics object in the parent Graphics object }}
 +
{{Method | name=ClipToPath | description=ClipToPath(path As iOSPath)&#10;Clips the drawing to the specified GraphicsPath.}}
 +
{{Method | name=ClipToRectangle | description=ClipToRectangle(x As Double, y As Double, width As Double, height As Double)&#10;Clips the drawing to the specified rectangle.}}
 
{{Method | name=DrawCautionIcon | params=X as [[Integer]],  Y as [[Integer]] | description=DrawCautionIcon(X as Integer,  Y as Integer)&#x0A;Draws the operating system's Caution icon at the coordinates specified. }}
 
{{Method | name=DrawCautionIcon | params=X as [[Integer]],  Y as [[Integer]] | description=DrawCautionIcon(X as Integer,  Y as Integer)&#x0A;Draws the operating system's Caution icon at the coordinates specified. }}
 
{{Method | name=DrawLine | params=X1 as [[Integer]],  Y1 as [[Integer]],  X2 as [[Integer]],  Y2 as [[Integer]] | description=DrawLine(X1 as Integer,  Y1 as Integer,  X2 as Integer,  Y2 as Integer)&#x0A;Draws a line from X1, Y1 to X2, Y2 in the current color. }}
 
{{Method | name=DrawLine | params=X1 as [[Integer]],  Y1 as [[Integer]],  X2 as [[Integer]],  Y2 as [[Integer]] | description=DrawLine(X1 as Integer,  Y1 as Integer,  X2 as Integer,  Y2 as Integer)&#x0A;Draws a line from X1, Y1 to X2, Y2 in the current color. }}
Line 56: Line 66:
 
{{Method | name=FillRectangle | params=X as [[Integer]],  Y as [[Integer]],  Width as [[Integer]],  Height as [[Integer]] | description=FillRectangle(X as Integer,  Y as Integer,  Width as Integer,  Height as Integer)&#x0A;Draws a rectangle filled with the current color. }}
 
{{Method | name=FillRectangle | params=X as [[Integer]],  Y as [[Integer]],  Width as [[Integer]],  Height as [[Integer]] | description=FillRectangle(X as Integer,  Y as Integer,  Width as Integer,  Height as Integer)&#x0A;Draws a rectangle filled with the current color. }}
 
{{Method | name=FillRoundRectangle | params=X as [[Integer]],  Y as [[Integer]],  Width as [[Integer]],  Height as [[Integer]],  ArcWidth as [[Integer]],  ArcHeight as [[Integer]] | description=FillRoundRectangle(X as Integer,  Y as Integer,  Width as Integer,  Height as Integer,  ArcWidth as Integer,  ArcHeight as Integer)&#x0A;Draws a rounded rectangle filled with the current color. }}
 
{{Method | name=FillRoundRectangle | params=X as [[Integer]],  Y as [[Integer]],  Width as [[Integer]],  Height as [[Integer]],  ArcWidth as [[Integer]],  ArcHeight as [[Integer]] | description=FillRoundRectangle(X as Integer,  Y as Integer,  Width as Integer,  Height as Integer,  ArcWidth as Integer,  ArcHeight as Integer)&#x0A;Draws a rounded rectangle filled with the current color. }}
 +
{{Method | name = Handle | platform=all | description = Handle(Graphics.HandleTypes)&#x0D;Gets the OS Handle for the passed Type}}
 +
{{Method | name=LineDash | description=LineDash(values() As Double)&#x0A;Sets and gets the on/off dash pattern.&#x0A;LineDash As Double()&#x0A;Sets and gets the on/off dash pattern.}}
 
{{Method | name=NextPage | description=NextPage()&#x0A;When printing a graphics object, this method will cause the current page to be printed and a new page to be created }}
 
{{Method | name=NextPage | description=NextPage()&#x0A;When printing a graphics object, this method will cause the current page to be printed and a new page to be created }}
 +
{{Method | name=RestoreState | description=RestoreState&#10;Restores graphics context previously saved with SaveState.}}
 +
{{Method | name=Rotate | description=Rotate(angle As Double)&#10;Rotates the drawing context by the specified angle (in radians) around the origin point (0,0). This only affects subsequent drawing. Any drawing done before the Rotate method call is not rotated.&#10;Rotate(angle As Double, x As Double, y As Double)&#10;Rotates the drawing context by the specified angle (in radians) around the origin point specified. This only affects subsequent drawing. Any drawing done before the Rotate method call is not rotated.}}
 +
{{Method | name=SaveState | description=SaveState&#10;Saves graphics state of the graphics context so that it can be restored later.}}
 +
{{Method | name=Scale | description=Scale(x As Double, y As Double)&#10;Sets the scale for the graphics context as specified scaleX and scaleY.}}
 
{{Method | name=TextDirection | params=Text as [[String]] | returntype=[[Integer]] | description=TextDirection(Text as String) as Integer&#x0A;Returns an Integer that indicates the direction in which the text is written.  }}
 
{{Method | name=TextDirection | params=Text as [[String]] | returntype=[[Integer]] | description=TextDirection(Text as String) as Integer&#x0A;Returns an Integer that indicates the direction in which the text is written.  }}
{{Method | name=TextHeight | returntype=[[Double]] | description=( Double)&nbsp;&nbsp;Returns the height of a line of text drawn with the current font. }}
 
 
{{Method | name=TextHeight | params=Text as [[String]],  WrapWidth as [[Integer]] | returntype=[[Integer]] | description=TextHeight(Text as String,  WrapWidth as Integer) as Integer&#x0A;Returns as an Integer the height of the text based on the current font and font size and the passed WrapWidth.}}
 
{{Method | name=TextHeight | params=Text as [[String]],  WrapWidth as [[Integer]] | returntype=[[Integer]] | description=TextHeight(Text as String,  WrapWidth as Integer) as Integer&#x0A;Returns as an Integer the height of the text based on the current font and font size and the passed WrapWidth.}}
 
{{Method | name=TextWidth | params=Text as [[String]] | returntype=[[Double]] | description=TextWidth(Text as String) as Double&#x0A;Returns as a Double the width of the text (based on the current font and font size).  }}
 
{{Method | name=TextWidth | params=Text as [[String]] | returntype=[[Double]] | description=TextWidth(Text as String) as Double&#x0A;Returns as a Double the width of the text (based on the current font and font size).  }}
 +
{{Method | name=Translate | description=Translate(translateX As Double, translateY As Double)&#10;Translates the origin point by the specified translateX and translateY values. Useful with Rotate.}}
 
</dynamicTable>
 
</dynamicTable>
  
<dynamicTable id="Enumerations" class="methodTable" title="Enumerations" columns="3">
+
==Notes==
{{Enum | name=HandleTypes | description=Specifies the type of OS handle you wish to receive for use with the Handle property.}}
+
Normally you use a graphics object in response to a [[Canvas.Paint]] event, but you can also perform direct drawing by using the '''Graphics''' property of a [[Picture]]. Alternatively, you can create vector graphics using the subclasses of the [[Object2D]] class.
</dynamicTable>
+
 
 +
{{Information | You cannot create a meaningful '''Graphics''' object via the [[New]] command.}}
 +
 
 +
===Coordinates===
 +
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 points to the right and 50 points down from the top-left of the window or control.
  
 
=== Alpha Channel Support ===
 
=== Alpha Channel Support ===
Line 115: Line 137:
  
 
== See Also ==
 
== See Also ==
[[Canvas]] control; [[Window]], [[ContainerControl]] class.
+
[[Canvas]] control; [[Window]], [[ContainerControl]], [[Group2D]] classes.
 
 
  
 
[[Category:Graphics/Multimedia_Graphics]]
 
[[Category:Graphics/Multimedia_Graphics]]
 
[[Category:Language_Classes]]
 
[[Category:Language_Classes]]

Latest revision as of 12:25, 5 April 2021

For web apps, see WebGraphics.

Class (inherits from Object)

Graphics class objects are used for drawing text, lines, rectangles, ovals, and pictures.

Enumerations
HandleTypes LineJoinTypes
LineCapTypes TextDirections
Properties
AntiAliasMode FontName PenSize
AntiAliased FontSize PrintingCancelled fa-lock-32.png
Bold FontUnit ScaleX
Brush Height fa-lock-32.png ScaleY
CharacterSpacing Italic ShadowBrush
Copies fa-lock-32.png LastPage fa-lock-32.png Transparency
DrawingColor LineCap Underline
FirstPage fa-lock-32.png LineDashOffset Width fa-lock-32.png
Font LineJoin
FontAscent fa-lock-32.png Outline
Methods
ClearRectangle DrawPicture LineDash
Clip DrawRectangle NextPage
ClipToPath DrawRoundRectangle RestoreState
ClipToRectangle DrawStopIcon Rotate
DrawCautionIcon DrawText SaveState
DrawLine FillOval Scale
DrawNoteIcon FillPath TextDirection
DrawObject FillRectangle TextHeight
DrawOval FillRoundRectangle TextWidth
DrawPath Handle Translate

Notes

Normally you use a graphics object in response to a Canvas.Paint event, but you can also perform direct drawing by using the Graphics property of a Picture. Alternatively, you can create vector graphics using the subclasses of the Object2D class.

fa-info-circle-32.png
You cannot create a meaningful Graphics object via the New command.

Coordinates

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 points to the right and 50 points down from the top-left of the window or control.

Alpha Channel Support

The Transparency property takes a value between 0.0 (opaque) and 100.0 (transparent) that can be used to obtain "fading" effects (amongst other uses) by setting the transparency to a value greater than 0.0.

When rendering colors or pictures with alpha channel information, the Transparency property is composited with the alpha channel information. This allows you to perform uniform fading operations easily and efficiently.

On Windows, using the Transparency property only works on Picture.Graphics if the Picture was created with a depth of 32, or is a Picture with an alpha channel. Attempting to use it on other forms of Pictures will result in an UnsupportedOperationException.

Sample Code

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.FontName = "Helvetica"
g.FontSize = 18
g.DrawText("The quick brown fox", 10, 50)

This 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.

Var points() As Integer
points = Array(10, 10, 100, 50, 10, 200, 10, 10)
g.DrawingColor = RGB(100, 200, 255)
g.FillPolygon(points)

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.

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..
g.DrawingColor = &c000000
g.DrawRectangle(0, 0, g.Width, g.Height)

// draw into the first area...
myClip.DrawingColor = &cff0000
myClip.DrawRectangle(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.DrawingColor = &c0000ff
myClip2.DrawRectangle(0, 0, myClip2.Width, myClip2.Height) // draw the border of the area
myClip2.DrawOval(0, 0, 150, 15)

See Also

Canvas control; Window, ContainerControl, Group2D classes.