▼Draw:   Drawing Toolkit
On this page:
DC.pen
DC.brush
DC.font
DC.text_  color
DC.clipping_  region
DC.alpha
DC.start_  alpha
DC.end_  alpha
DC.using_  alpha
DC.transformation
DC.layered_  transformation
DC.scale
DC.translate
DC.rotate
DC.transform
DC.save
DC.restore
DC.save_  and_  restore
DC.smoothing
DC.alignment_  scale
DC.Smoothing
DC.Smoothing.smoothed
DC.Smoothing.unsmoothed
DC.Smoothing.aligned
0.45+9.1.0.1
Rhombus
  top  contents    up   

2 Drawing State🔗ℹ

Drawing operations on a DC depend on its current pen, brush, and other state.

property

property

| (dc :: draw.DC).pen :: Pen

| (dc :: draw.DC).pen := (p :: Pen)

 

property

property

| (dc :: draw.DC).brush :: Brush

| (dc :: draw.DC).brush := (b :: Brush)

The current pen used for lines or shape outlines, and the current brush used for shape fills.

property

property

| (dc :: draw.DC).font :: Font

| (dc :: draw.DC).font := (f :: Font)

 

property

property

| (dc :: draw.DC).text_color :: Color

| (dc :: draw.DC).text_color := (c :: String || Color)

The current font and color used for drawing text.

property

property

| (dc :: draw.DC).clipping_region :: maybe(Region)

| (dc :: draw.DC).clipping_region := (rgn :: maybe(Region))

The current clipping region, or #false if no clipping is in effect. Drawing effects that would fall outside the current clipping region are discarded.

property

property

| (dc :: draw.DC).alpha :: Real.in(0, 1)

| (dc :: draw.DC).alpha := (a :: Real.in(0, 1))

The current opacity used for drawing, where 0.0 is fully transparent, so it causes no effect on the target, and 1.0 is fully opaque. A pen or brush’s color can have its own opacity, which is multiplied by the drawing context’s opacity. Similarly, a drawn bitmap can have its own alpha channel, which is multiplied by the drawing context’s opacity.

method

method (dc :: draw.DC).start_alpha(alpha :: Real.in(0, 1)) :: Void

 

method

method (dc :: draw.DC).end_alpha() :: Void

 

expression

dot (dc :: draw.DC).using_alpha (alpha :: Real.in(0, 1)):

  body

  ...

The DC.start_alpha method starts a compositing drawing sequence that is not rendered until DC.end_alpha is called. At that point, the accumulated sequence is conceptually rendered to a separate context, and then transferred at once with opacity times the current opacity as produced by DC.alpha. The DC.start_alpha call meanwhile sets the current opacity to 1.0, and DC.end_alpha restores the drawing context’s opacity to the setting before DC.start_alpha.

This effect is different than setting DC.alpha (times the current DC.alpha result) in the case that drawing between DC.start_alpha and DC.end_alpha produces overlapping output. In that case, adjusting DC.alpha would affect the drawing operations separately, while DC.start_alpha creates an opacity adjustment on the overlapped result, instead.

The DC.using_alpha form returns the result of the body sequence, but adds a DC.start_alpha(alpha) call before and DC.end_alpha() call afterward.

property

property

| (dc :: draw.DC).transformation :: Transformation

| (dc :: draw.DC).transformation := (t :: Transformation)

 

property

property

| (dc :: draw.DC).layered_transformation :: LayeredTransformation

| (dc :: draw.DC).layered_transformation := (lt :: LayeredTransformation)

The current transformation that is applied to any drawing coordinate to arrive at coordinated in the target (such as a bitmaps).

Beware that getting and setting DC.transformation does not save and restore precisely the same internal transformation state of dc. For cases where that is needed, DC.layered_transformation produces and consumes an opaque value representing the internal state The DC.save and DC.restore methods use DC.layered_transformation, for example.

method

method (dc :: draw.DC).scale(s :: Real) :: Void

 

method

method (dc :: draw.DC).scale(sx :: Real, sy :: Real) :: Void

 

method

method (dc :: draw.DC).translate(dpt :: PointLike) :: Void

 

method

method (dc :: draw.DC).translate(dx :: Real, dy :: Real) :: Void

 

method

method (dc :: draw.DC).rotate(radians :: Real) :: Void

 

method

method (dc :: draw.DC).transform(t :: Transformation) :: Void

Applies a (further) transformation to the drawing context’s conversion from drawing coordinates to device coordinates. In other words, these methods change the result that is returned by the DC.transformation property, and they affect drawing accordingly.

method

method (dc :: draw.DC).save() :: Void

 

method

method (dc :: draw.DC).restore() :: Void

 

expression

dot (dc :: draw.DC).save_and_restore:

  body

  ...

Saves and restores the draw context’s configuration.

The DC.save method pushes the current drawing state (pen, brush, clipping region, and transformation) onto an internal stack, and DC.restore pops the stack and restores the popped drawing state. The DC.save_and_restore form wraps a body sequence to save the drawing state on entry to the sequence and restore it on exit, returning the value(s) produced by the body sequence; entry and exit cover continuation jumps, like try.

property

property

| (dc :: draw.DC).smoothing :: DC.Smoothing

| (dc :: draw.DC).smoothing := (s :: DC.Smoothing)

 

property

property

| (dc :: draw.DC).alignment_scale :: PosReal

| (dc :: draw.DC).alignment_scale := (s :: PosReal)

 

enumeration

enum draw.DC.Smoothing

| smoothed

| unsmoothed

| aligned

A drawing context’s smoothing mode (the DC.smoothing property) determines whether drawing coordinates are aligned to its alignment scale (the DC.alignment_scale property) and whether anti-aliasing is used to make shapes appear smoother:

  • #'smoothed: The default smoothing mode, which uses anti-aliasing and does not adjust drawing coordinates to align them.

  • #'unsmoothed: Draws without anti-aliasing. Drawing coordinates are rounded to the nearest pixel after the alignment scale, after taking into account scaling after the drawing context’s current transformation.

  • #'aligned: Draws with anti-aliasing, but drawing coordinates are rounded to the nearest pixel after the alignment scale, after taking into account scaling after the drawing context’s current transformation.

An alignment scale of 2.0 aligns drawing coordinates to half-integer values. A value of 2.0 could be suitable for drawing to a bitmap with a backing scale of 2.0, since half-integer values correspond to pixel boundaries. Even when a destination bitmap has a backing scale of 2.0, however, an alignment scale of 1.0 may be desirable to maintain consistency with drawing contexts that have a backing scale and alignment scale of 1.0.

  top  contents    up