Difference between revisions of "Graphics"

From Xojo Documentation

(See Also)
(Move Handle from Properties to Methods)
 
(7 intermediate revisions by 2 users not shown)
Line 8: Line 8:
 
}}
 
}}
 
{{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.}}
 +
</dynamicTable>
  
 
<dynamicTable id="Properties" class="propertyTable" title="Properties" columns="3">
 
<dynamicTable id="Properties" class="propertyTable" title="Properties" columns="3">
Line 15: Line 20:
 
{{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=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">
Line 56: Line 64:
 
{{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;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=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).  }}
 
</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.<br> For example, 50,50 is 50 pixels to the right and 50 pixels down from the top-left of the window or control.
  
 
=== Alpha Channel Support ===
 
=== Alpha Channel Support ===

Latest revision as of 17:18, 19 November 2020


For web apps, see WebGraphics.

Class (inherits from Object)

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

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

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 pixels to the right and 50 pixels 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.