The DADrawingSurface class uses a style of drawing that depends on a graphics context. This is in contrast to the other DirectAnimation classes that use a constructive approach. The constructive approach combines primitive data types into a more complex model, in a hierarchical fashion.
The graphics context approach is analagous to the way a pen plotter works, where the pen acts as the mechanical extension of a hand and the plotter acts as a piece of paper. To draw something, the pen is directed to a location on the plotter and then draws the shape. Many people find this approach to be more familiar than hierarchical modeling. For example, to draw the sun in the sky, it may seem more obvious to simply draw a yellow circle exactly where you want it, instead of first drawing a circle, then creating a yellow circle, and then, with a transform, creating yet another yellow circle that is now correctly placed. The difference is in the approach rather than in capabilities.
A DADrawingSurface object maintains a graphics state object for two-dimensional graphics. This state includes attributes such as line style, fill style, border style, font style, and two-dimensional transformations. The drawing commands (such as Oval and RoundRect are always interpreted in terms of the current state.
Draws a portion of an oval. (This is, in effect, an arc).
The following example, in VBScript, draws a series of differently-sized arcs:
<HTML> <HEAD> <TITLE>Demonstration of ArcDegrees subroutine</TITLE> </HEAD> <BODY> <DIV ID=controlDiv> <OBJECT ID="DAViewer" STYLE="position:absolute; left:10; top:10;width:450;height:450" CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D"> </OBJECT> </DIV> </DIV> <SCRIPT LANGUAGE="VBScript"> sub window_onLoad Set s = DAViewer.MeterLibrary Set ds = s.NewDrawingSurface() ds.Text "Degrees 0", -.04, .06 ds.ArcDegrees 0, .05, 0, 0, .01, .01 ds.Text "Degrees 45", -.04, .04 ds.ArcDegrees 0, .03, 0, 45, .01, .01 ds.Text "Degrees 90", -.04, .02 ds.ArcDegrees 0, .01, 0, 90, .01, .01 ds.Text "Degrees 180", -.04, 0 ds.ArcDegrees 0, -.01, 0, 180, .01, .01 ds.Text "Degrees 270", -.04, -.02 ds.ArcDegrees 0, -.03, 0, 270, .01, .01 ds.Text "Degrees 360", -.04, -.04 ds.ArcDegrees 0, -.05, 0, 360, .01, .01 DAViewer.Image = ds.Image DAViewer.Start end sub </SCRIPT> </BODY> </HTML>
drawingObj.ArcDegrees(
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)
Same as ArcDegrees except that startAngle and endAngle are expessed in radians.
drawingObj.ArcRadians((
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)
Scales the fill pattern horizontally and vertically to fit the drawn object's bounding box.
drawingObj.AutoSizeFillScale( )
There is no guarantee that the entire fill style will appear in drawn object because many fill regions are not rectangular.
Specifies the color of a filled region's outline (border).
drawingObj.BorderColor(
color
)
Sets the dash style of the border.
drawingObj.BorderDashStyle(
id
)
Specifies the border's join style.
drawingObj.BorderJoinStyle(
id
)
Sets the width of the border, in points. Border widths are affected by Transform. For example, scaling by 2 will double the border width.
The following example demonstrates different border widths, using JScript:
<HTML> <HEAD> <TITLE>Demonstration of BorderWidth Subroutine</TITLE> </HEAD> <BODY> <DIV ID=controlDiv> <OBJECT ID="DAViewer" STYLE="position:absolute; left:10; top:10;width:450;height:450" CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D"> </OBJECT> </DIV> </DIV> <SCRIPT LANGUAGE="JScript" for="window" event="onload"> s = DAViewer.MeterLibrary; ds = s.NewDrawingSurface(); ds.BorderWidth(1); ds.Rect(0, .05, .06, .01); ds.BorderWidth(2); ds.Rect(0, .03, .06, .01); ds.BorderWidth(3); ds.Rect(0, .01, .06, .01); ds.BorderWidth(4); ds.Rect(0, -.01, .06, .01); ds.BorderWidth(5); ds.Rect(0, -.03, .06, .01); DAViewer.Image = ds.Image; DAViewer.Start(); </SCRIPT> </BODY> </HTML>
drawingObj.BorderWidth(
width
)
Resets both the global images (Image) and the local context images (LocalContextImage). All attributes for the local context images are set to their defaults.
drawingObj.Clear( )
Sets a rectangular cropping region outside of which drawing commands have no effect. Note that, unlike the DAImage Crop() function, this subroutine affects what will be drawn, not what has been drawn.
drawingObj.Crop(
minX,
minY,
maxX,
maxY
)
Same as Crop except that the arguments are specified as DAPoint2 objects.
drawingObj.CropPoints(
min,
max
)
Same as Polyline, except that it takes a DAPath2 object instead of points.
drawingObj.DrawPath(
path
)
If used with a gradient fill, specifies the starting color. If used with a hatched fill, specifies its color. It is ignored for solid fills. The default foreground color is black.
drawingObj.FillColor(
foreground
)
Creates a fill pattern that is an image. This subroutine allows you to create your own fill pattern from any type of two-dimensional animation. The default is to scale the image to fit the window. If the mode is set to FixedFillScale and the image is transformed before being passed in, it will retain its position relative to the shape.
drawingObj.FillImage(
image
)
Same as Polygon except that it takes a DAPath2 object rather than points.
drawingObj.FillPath(
path
)
Sets the fill style. The parameter specifying the fill style, id, can be any of the following possible styles:
Id | Style |
0 | Empty (does not support mouse events) |
1 | Solid |
2 | Empty Pickable (supports mouse events) |
3 | HatchHorizonal |
4 | HatchVertical |
5 | HatchForwardVertical |
6 | HatchBackwardDiagonal |
7 | HatchCross |
8 | HatchDiagonalCross |
9 | HorizontalGradient |
10 | VerticalGradient |
11 | RadialGradient |
12 | LinearGradient |
13 | RectangularGradient |
14 | ShapeGradient |
Fill styles are used to paint closed regions. The default fill type is the solid fill. Some uses of particular fill styles are:
Fill colors are used in three ways. For gradient fills, the fill color is the first color used for blending. For hatched fills, it is the color used to draw the hatch marks. For solid fills, it is the color used for the entire filled area. It does not apply to empty and texture fill styles. The default color is black.
A secondary (or background) fill color is possible and is also used in several ways. For gradient fills, it specifies the second color used for blending. For hatch fills, it is the color used to fill around the hatch marks. For empty fills, it is always transparent. Solid fills have no secondary color. The default secondary color depends on the fill type. For solid and gradient fills, the default background color is white. For hatched fills, the default background color is transparent.
Gradient and texture fills can either be scaled to fit the shape being filled or can use their own scaling information. This is called a size-to-fit option. It does not apply to empty, solid, or hatched fill styles.
Scale-to-fit uses rectangular bounding regions to scale the fill style into the region to be filled. Thus, scale-to-fit does not guarantee that the entire fill style will appear in the shape, because many fill regions are not rectangular. Gradient fills in which no interpolation coordinates are specified use scale-to-fit by default. Gradient fills with explicit coordinates as well as all texture fills use, by default, their local coordinates and are not scaled to fit the drawing region. For particular scale-to-fit subroutines, see AutoSizeFillScale, FixedFillScale, HorizontalFillScale, and VerticalFillScale.
For gradient fills, it can be useful to explicitly set the starting and ending positions for the transition between the colors. For example, with a radial gradient, (which is a color transition in a circular shape) it may be useful to set the center point. To set these points, use the GradientExtent subroutine.
The GradientRolloffPower subroutine uses an exponent (the power argument) to control how rapidly one color transitions into another. A value of 1 is a linear transition. For 0 < power < 1 the transition occurs rapidly, while power > 1 means that the transition occurs more slowly. For example, if you are transitioning from red to blue, and power = 2, you will see a great deal of red in the gradient fill. On the other hand, if power = 0.5 (the inverse of 2), you will see very little red. If power = 0, you will see only blue.
More precisely, if x is considered the normalized distance (from 0 to 1), then the gradient is xp, where p is in the range [0, infinity].
The following table summarizes the default values of the different fill attributes (such as color) for each fill style:
Default | Empty | Empty/Pickable | Solid | Hatched | Gradient | Texture | Image |
Fill Color | N/A | N/A | Black | Black | Black | N/A | N/A |
Secondary | N/A | N/A | N/A | Transparent | White | N/A | N/A |
Mouse Events? | Always No | Always Yes | No | No | No | No | No |
Size-to-fit | N/A | N/A | N/A | N/A | Yes, if no start point, No, if start point specified | Always No | No |
Gradient End Points | N/A | N/A | N/A | N/A | No Default | N/A | N/A |
Rolloff Power | N/A | N/A | N/A | N/A | 1 | N/A | N/A |
drawingObj.FillStyle(
id
)
Specifies a fill image that will be tiled (according to its bounding box) and/or clipped to fit within the extents of the path. It is not scaled. If the image is transformed before being passed in, it will retain its position relative to the shape.
drawingObj.FillTexture(
image
)
Specifies that the fill pattern will not be be scaled. The fill style attributes are applied directly to the drawn object, regardless of size.
drawingObj.FixedFillScale( )
Sets the font attributes.
drawingObj.Font(
face,
size,
bold,
italic,
underline,
strikethrough
)
Specifies a length and a direction for a gradient to transition between colors. The starting color is unblended, as is the ending color. Between the points, the colors are blended according to the gradient type.
drawingObj.GradientExtent(
startX,
startY,
endX,
endY
)
Same as GradientExtent except that the arguments are DAPoint2 objects.
drawingObj.GradientExtentPoints(
startPoint,
endPoint
)
Controls the sharpness of the transition between the colors.
drawingObj.GradientRolloffPowerAnim(
power
)
Same as GradientRolloffPowerAnim except that power is a non-animated number (a double).
drawingObj.GradientRolloffPower(
power
)
Specifies a polygon that is progressively scaled to control the shape of the color transition. This applies only if the FillStyle subroutine was invoked with an id of 14 (ShapeGradient).
drawingObj.GradientShape(
pts
)
Stretches or compresses the fill pattern horizontally to match the width of the drawn object's bounding box.
drawingObj.HorizontalFillScale( )
There is no guarantee that the entire fill style will appear in drawn object because many fill regions are not rectangular.
Draws a line segment from the starting point to the ending point, using the current LineDashStyle.
drawingObj.Line(
startX,
startY,
endX,
endY
)
Sets the color of the line.
drawingObj.LineColor(
col
)
Sets the dash style of the line. The parameter specifying the dash style, id, can be any of the following possible styles:
ID | Dash Style |
0 | Null |
1 | Solid |
2 | Dash |
drawingObj.LineDashStyle(
id
)
Sets the end style of the line. The parameter specifying the end style, id, can be any of the following possible styles:
ID | End Style |
0 | Flat |
1 | Square |
2 | Round |
drawingObj.LineEndStyle(
id
)
Sets the join style of the line. The parameter specifying the join style, id, can be any of the following possible styles:
ID | Join Style |
0 | Bevel |
1 | Round |
2 | Miter |
drawingObj.LineJoinStyle(
id
)
Same as Line except that the arguments are DAPoint2 objects (they can be animated).
drawingObj.LinePoints(
pt1,
pt2
)
Sets the width of the current line, in points. Line widths are affected by Transform. For example, scaling by 2 will double the line width.
drawingObj.LineWidth(
width
)
Sets the opacity used by drawing commands. In contrast to the DAImage Opacity function, this subroutine affects what will be drawn rather than what has been drawn.
drawingObj.OpacityAnim(
opac
)
Same as OpacityAnim except that opac is a non-animated number (a double).
drawingObj.Opacity(
opac
)
Draws an outline of an oval and fills it, using the current fill and border styles.
The following example uses VBScript to draw an oval with a hatch cross fill style:
<HTML> <HEAD> <TITLE>Oval with Hatch Cross Fill Style</TITLE> </HEAD> <BODY> <DIV ID=controlDiv> <OBJECT ID="DAViewer" STYLE="position:absolute; left:10; top:10;width:450;height:450" CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D"> </OBJECT> </DIV> </DIV> <SCRIPT LANGUAGE="VBScript"> sub window_onLoad Set s = DAViewer.MeterLibrary Set ds = s.NewDrawingSurface() ds.FillColor s.ColorRgb255(0,0,200) ds.SecondaryFillColor s.ColorRgb255(255,0,0) ds.Text "Hatch Cross", -.04, .06 ds.FillStyle 7 ds.Oval -.04, -.04, .1, .1 DAViewer.Image = ds.Image DAViewer.Start end sub </SCRIPT> </BODY> </HTML>
drawingObj.Oval(
xPos,
yPos,
width,
height
)
Overlays a DAImage object onto the current drawing surface. This means the image can be animated.
drawingObj.OverlayImage(
img
)
Renders a closed path that traces a segment of an oval and connects it to the origin. (In effect, it is a pie-shaped wedge).
The following example uses VBScript to draw a series of wedges, each with a solid-red fill:
<HTML> <HEAD> <TITLE>Demonstration of PieDegrees Subroutine</TITLE> </HEAD> <BODY> <DIV ID=controlDiv> <OBJECT ID="DAViewer" STYLE="position:absolute; left:10; top:10;width:450;height:450" CLASSID="CLSID:B6FFC24C-7E13-11D0-9B47-00C04FC2F51D"> </OBJECT> </DIV> </DIV> <SCRIPT LANGUAGE="VBScript"> sub window_onLoad Set s = DAViewer.MeterLibrary Set ds = s.NewDrawingSurface() ds.FillStyle 1 ds.FillColor s.ColorRgb255(255,0,0) ds.Text "Degrees 0", -.04, .06 ds.PieDegrees 0, .05, 0, 0, .01, .01 ds.Text "Degrees 45", -.04, .04 ds.PieDegrees 0, .03, 0, 45, .01, .01 ds.Text "Degrees 90", -.04, .02 ds.PieDegrees 0, .01, 0, 90, .01, .01 ds.Text "Degrees 180", -.04, 0 ds.PieDegrees 0, -.01, 0, 180, .01, .01 ds.Text "Degrees 270", -.04, -.02 ds.PieDegrees 0, -.03, 0, 270, .01, .01 ds.Text "Degrees 360", -.04, -.04 ds.PieDegrees 0, -.05, 0, 360, .01, .01 DAViewer.Image = ds.Image DAViewer.Start end sub </SCRIPT> </BODY> </HTML>
drawingObj.PieDegrees(
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)
Same as PieDegrees except that startAngle and endAngle are expressed in radians.
drawingObj.PieRadians(
xPos,
yPos,
startAngle,
endAngle,
arcWidth,
arcHeight
)
Draws and fills a polygon, using the current fill and border styles. The points can be specified as a variant array of either DAPoint2[] objects or doubles. The array of doubles array must contain (2 * numPts) because it represents (x, y) coordinate pairs.
drawingObj.Polygon(
points
)
Draws a set of line segments according to the current line style. The points can be specified as a variant array of either DAPoint2[] objects or doubles. The array of doubles array must contain (2 * numPts) because it represents (x, y) coordinate pairs.
drawingObj.Polyline(
points
)
Draws and fills a rectangle, using the current fill and border styles.
drawingObj.Rect(
xPos,
yPos,
width,
height
)
Resets the local context and sets all attributes to their defaults (nested transformations from the context still apply although local transformations are reset). This subroutine affects only the state used for upcoming drawing methods, not the current drawing.
drawingObj.Reset( )
Restores the drawing surface's graphics state (the font, color, fillstyles, and so on) to what it was before the last SaveGraphicsState.
drawingObj.RestoreGraphicsState( )
Draws a rectangle with rounded, rather than square, corners. The corners are considered to be segments of an oval (in effect, an arc).
drawingObj.RoundRect(
xPos,
yPos,
width,
height,
arcWidth,
arcHeight
)
Saves the drawing surface's current graphics state by pushing it onto an internal stack.
drawingObj.SaveGraphicsState( )
Specifies a secondary fill color. For gradient fills, this is the second color used for blending. For hatch fills, it is the color used to fill around the hatch marks. For empty fills, it is always transparent. It does not apply to solid fills.
drawingObj.SecondaryFillColor(
val
)
Creates a filled region from the text outlines, using the current fontstyle to determine the size of the font and the face. Color and other attributes come from the current fill and border styles. Note that the color attribute of the current font style is ignored. The text's starting location is given by xPos, yPos.
drawingObj.Text(
string,
xPos,
yPos
)
Same as Text except that the starting location is given by a DAPoint2 object.
drawingObj.TextPoint(
string,
pt
)
Transform operations include translation, scaling, and/or shearing. The subroutine affects only the state used for upcoming drawing methods, not the current drawing. This operation is cumulative.
drawingObj.Transform(
xf
)
Stretches or compresses the fill pattern vertically to match the width of the drawn object's bounding box.
drawingObj.VerticalFillScale( )
There is no guarantee that the entire fill style will appear in drawn object because many fill regions are not rectangular.
A DALineStyle object that specifies how the outline of a filled region will be drawn. The color specified in the line style determines the color of the border. (Interior fills are specified with FillStyle.) For an alternative way of setting border attributes, see BorderColor, BorderDashStyle, BorderJoinStyle, and BorderWidth.
drawingObj.BorderStyle
Specifies an image matte (or masking stencil) to the drawing context. Note that, unlike the DAImage Clip function, this property affects what will be drawn rather than what has already been drawn.
drawingObj.ClipMatte
A DAFontStyle (animated) object that sets font attributes such as face, size, and color.
drawingObj.FontStyle
A boolean specifying whether the hatch fill is transparent or not.
drawingObj.HatchFillTransparent
Returns the DAImage object (animated image) associated with the DrawingSurface.
drawingObj.Image
Adds a DALineStyle to the graphics state. A DALineStyle object determines the line color, dash style, width, endpoint, and join style. Setting this property affects how the line drawing commands (such as ArcRadians and Polyline) are drawn.
drawingObj.LineStyle
LineColor, LineDashStyle, LineEndStyle, LineJoinStyle, LineWidth
Returns an image that corresponds to what was drawn since the latest SaveGraphicsState call. This property is useful for instancing and procedural tiling.
drawingObj.LocalContextImage
Specifies whether mouseover and selection events will be detected for the objects subsequently drawn. TRUE means that events are detected and FALSE means they are not.
drawingObj.MouseEventsEnabled
lib.ImportDirectDrawSurface(dds, updateEvent)
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.