wxRuby Documentation Home

# Wx::DC

A DC is a device context onto which graphics and text can be drawn.
It is intended to represent a number of output devices in a generic way,
so a window can have a device context associated with it, and a printer
also has a device context. In this way, the same piece of code may
write to a number of different devices, if the device context is used as
a parameter.

This DC class itself is not used directly; instead, a particular type of
DC is used depending on the surface to be drawn upon. However, the
common drawing methods are all documented here. Derived types of DC
have documentation for specific features only, such as when to use them,
and how to instantiate them.

Please note that in addition to the versions of the methods documented here,
there are also versions which accept single `Point` parameter instead of
two `Integer` ones or `Point` and `Size` instead of four of
them.

## Support for Transparency / Alpha Channel / Anti-aliasing

The standard Device Contexts such as WindowDC do not, on
Windows and GTK, support anti-aliasing of lines and drawing and painting
with semi-transparent colours. Colours with an alpha channel
(transparency level) will be drawn solid. To get anti-aliased drawing
and support for alpha channels, use GCDC. The same drawing
methods can be used with that class. See also
GraphicsContext and associated classes for
advanced drawing.

In wxRuby on Mac OS X, drawing and painting with semi-transparent
colours is supported by normal Device Contexts; however, GCDC can be
used without harm so the same code can be used cross-platform if
anti-aliased drawing is desired.

## Derived from

Object

## See also

Overview

## Methods

- DC.new
- DC#blit
- DC#cache_enabled
- DC#calc_bounding_box
- DC#clear
- DC#clear_cache
- DC#compute_scale_and_origin
- DC#cross_hair
- DC#destroy_clipping_region
- DC#device_to_logical_x
- DC#device_to_logical_xrel
- DC#device_to_logical_y
- DC#device_to_logical_yrel
- DC#draw_arc
- DC#draw_bitmap
- DC#draw_check_mark
- DC#draw_circle
- DC#draw_ellipse
- DC#draw_elliptic_arc
- DC#draw_icon
- DC#draw_label
- DC#draw_line
- DC#draw_lines
- DC#draw_polygon
- DC#draw_poly_polygon
- DC#draw_point
- DC#draw_rectangle
- DC#draw_rotated_text
- DC#draw_rounded_rectangle
- DC#draw_spline
- DC#draw_text
- DC#enable_cache
- DC#end_doc
- DC#end_page
- DC#flood_fill
- DC#get_background
- DC#get_background_mode
- DC#get_brush
- DC#get_char_height
- DC#get_char_width
- DC#get_clipping_box
- DC#get_font
- DC#get_layout_direction
- DC#get_logical_function
- DC#get_map_mode
- DC#get_multi_line_text_extent
- DC#get_partial_text_extents
- DC#get_pen
- DC#get_pixel
- DC#get_ppi
- DC#get_size
- DC#get_size_mm
- DC#get_text_background
- DC#get_text_extent
- DC#get_text_foreground
- DC#get_user_scale
- DC#gradient_fill_concentric
- DC#gradient_fill_linear
- DC#logical_to_device_x
- DC#logical_to_device_xrel
- DC#logical_to_device_y
- DC#logical_to_device_yrel
- DC#max_x
- DC#max_y
- DC#min_x
- DC#min_y
- DC#is_ok
- DC#reset_bounding_box
- DC#set_axis_orientation
- DC#set_background
- DC#set_background_mode
- DC#set_brush
- DC#set_clipping_region
- DC#set_device_origin
- DC#set_font
- DC#set_layout_direction
- DC#set_logical_function
- DC#set_map_mode
- DC#set_palette
- DC#set_pen
- DC#set_text_background
- DC#set_text_foreground
- DC#set_user_scale
- DC#start_doc
- DC#start_page

### DC.new

### DC#blit

Boolean blit(%(arg-type)Integer% xdest, Integer ydest, Integer width, Integer height, DC source, Integer xsrc, Integer ysrc, Integer logicalFunc = COPY, Boolean useMask = false, Integer xsrcMask = -1, Integer ysrcMask = -1)

Copy from a source DC to this DC, specifying the destination
coordinates, size of area to copy, source DC, source coordinates,
logical function, whether to use a bitmap mask, and mask source position.

#### Parameters

- xdest Destination device context x position.
- ydest Destination device context y position.
- width Width of source area to be copied.
- height Height of source area to be copied.
- source Source device context.
- xsrc Source device context x position.
- ysrc Source device context y position.
- logicalFunc Logical function to use: see DC#set_logical_function.
- useMask If true, Blit does a transparent blit using the mask that is associated with the bitmap
  selected into the source device context. The Windows implementation does the following if MaskBlt cannot be used:

#Creates a temporary bitmap and copies the destination area into it.

1. Copies the source area into the temporary bitmap using the specified logical function.
2. Sets the masked area in the temporary bitmap to BLACK by ANDing the
   mask bitmap with the temp bitmap with the foreground colour set to WHITE
   and the bg colour set to BLACK.
3. Sets the unmasked area in the destination area to BLACK by ANDing the
   mask bitmap with the destination area with the foreground colour set to BLACK
   and the background colour set to WHITE.
4. ORs the temporary bitmap with the destination area.
5. Deletes the temporary bitmap.

This sequence of operations ensures that the source’s transparent area need not be black,
and logical functions are supported.

Note: on Windows, blitting with masks can be speeded up considerably by compiling
Widgets with the USE_DC_CACHE option enabled. You can also influence whether MaskBlt
or the explicit mask blitting code above is used, by using SystemOptions and
setting the no-maskblt option to 1.

- xsrcMask Source x position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and ysrc
  will be assumed for the mask source position. Currently only implemented on Windows.
- ysrcMask Source y position on the mask. If both xsrcMask and ysrcMask are -1, xsrc and ysrc
  will be assumed for the mask source position. Currently only implemented on Windows.

#### Remarks

There is partial support for Blit in PostScriptDC, under X.

See MemoryDC for typical usage.

#### See also

MemoryDC, Bitmap, Mask

### DC#cache_enabled

Boolean cache_enabled()

On supported platforms (currently only Windows), returns true
if the DC cache is enabled. The DC cache
can speed up the Blit operation when
drawing a large number of masked bitmaps.

If using the cache functions in your code, please test for the
USE_DC_CACHEING preprocessor symbol for portability.

#### See also

DC#enable_cache, DC#clear_cache

### DC#calc_bounding_box

calc_bounding_box(%(arg-type)Integer% x, Integer y)

Adds the specified point to the bounding box which can be retrieved with
MinX, MaxX and
MinY, MaxY functions.

#### See also

reset_bounding_box

### DC#clear

clear()

Clears the device context using the current background brush.

### DC#clear_cache

clear_cache()

On supported platforms (currently only Windows), clears
the contents of the DC cache (one bitmap and two Windows device contexts). The DC cache
can speed up the Blit operation when
drawing a large number of masked bitmaps. You should
call ClearCache at the end of length DC operations if you wish to only use
the cache transiently; you should also call it as your application exits.

If using the cache functions in your code, please test for the
USE_DC_CACHEING preprocessor symbol for portability.

#### See also

DC#enable_cache, DC#cache_enabled

### DC#compute_scale_and_origin

compute_scale_and_origin()

Performs all necessary computations for given platform and context type
after each change of scale and origin parameters. Usually called automatically
internally after such changes.

### DC#cross_hair

cross_hair(%(arg-type)Integer% x, Integer y)

Displays a cross hair using the current pen. This is a vertical
and horizontal line the height and width of the window, centred
on the given point.

### DC#destroy_clipping_region

destroy_clipping_region()

Destroys the current clipping region so that none of the DC is clipped.
See also DC#set_clipping_region.

### DC#device_to_logical_x

Integer device_to_logical_x(%(arg-type)Integer% x)

Convert device X coordinate to logical coordinate, using the current
mapping mode.

### DC#device_to_logical_xrel

Integer device_to_logical_xrel(%(arg-type)Integer% x)

Convert device X coordinate to relative logical coordinate, using the current
mapping mode but ignoring the x axis orientation.
Use this function for converting a width, for example.

### DC#device_to_logical_y

Integer device_to_logical_y(%(arg-type)Integer% y)

Converts device Y coordinate to logical coordinate, using the current
mapping mode.

### DC#device_to_logical_yrel

Integer device_to_logical_yrel(%(arg-type)Integer% y)

Convert device Y coordinate to relative logical coordinate, using the current
mapping mode but ignoring the y axis orientation.
Use this function for converting a height, for example.

### DC#draw_arc

draw_arc(%(arg-type)Integer% x1, Integer y1, Integer x2, Integer y2, Integer xc, Integer yc)

Draws an arc of a circle, centred on (xc, yc_), with starting point (x1, y1_)
and ending at (x2, y2). The current pen is used for the outline
and the current brush for filling the shape.

The arc is drawn in an anticlockwise direction from the start point to the end point.

### DC#draw_bitmap

draw_bitmap(%(arg-type)Bitmap% bitmap, Integer x, Integer y, Boolean transparent)

Draw a bitmap on the device context at the specified point. If transparent is true and the bitmap has
a transparency mask, the bitmap will be drawn transparently.

When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground
of the bitmap (all bits set to 1), and the current text background colour to draw the background
(all bits set to 0). See also set_text_foreground,
set_text_background and MemoryDC.

### DC#draw_check_mark

draw_check_mark(%(arg-type)Integer% x, Integer y, Integer width, Integer height) draw_check_mark(%(arg-type)Rect% rect)

Draws a check mark inside the given rectangle.

### DC#draw_circle

draw_circle(%(arg-type)Integer% x, Integer y, Integer radius) draw_circle(%(arg-type)Point% pt, Integer radius)

Draws a circle with the given centre and radius.

#### See also

draw_ellipse

### DC#draw_ellipse

draw_ellipse(%(arg-type)Integer% x, Integer y, Integer width, Integer height) draw_ellipse(%(arg-type)Point% pt, Size size) draw_ellipse(%(arg-type)Rect% rect)

Draws an ellipse contained in the rectangle specified either with the given top
left corner and the given size or directly. The current pen is used for the
outline and the current brush for filling the shape.

#### See also

draw_circle

### DC#draw_elliptic_arc

draw_elliptic_arc(%(arg-type)Integer% x, Integer y, Integer width, Integer height, Float start, Float end)

Draws an arc of an ellipse. The current pen is used for drawing the arc and
the current brush is used for drawing the pie.

x and y specify the x and y coordinates of the upper-left corner of the rectangle that contains
the ellipse.

width and height specify the width and height of the rectangle that contains
the ellipse.

start and end specify the start and end of the arc relative to the three-o’clock
position from the center of the rectangle. Angles are specified
in degrees (360 is a complete circle). Positive values mean
counter-clockwise motion. If start is equal to end, a
complete ellipse will be drawn.

### DC#draw_icon

draw_icon(%(arg-type)Icon% icon, Integer x, Integer y)

Draw an icon on the display (does nothing if the device context is PostScript).
This can be the simplest way of drawing bitmaps on a window.

### DC#draw_label

draw_label(%(arg-type)String% text, Bitmap image, Rect rect, Integer alignment = ALIGN_LEFT | ALIGN_TOP, Integer indexAccel = -1, Rect rectBounding = nil) draw_label(%(arg-type)String% text, Rect rect, Integer alignment = ALIGN_LEFT | ALIGN_TOP, Integer indexAccel = -1)

Draw optional bitmap and the text into the given rectangle and aligns it as specified
by alignment parameter; it also will emphasize the character with the given index if
it is != -1 and return the bounding rectangle if required.

### DC#draw_line

draw_line(%(arg-type)Integer% x1, Integer y1, Integer x2, Integer y2)

Draws a line from the first point to the second. The current pen is used
for drawing the line. Note that the point (x2, y2) is not part of the
line and is not drawn by this function (this is consistent with the
behaviour of many other toolkits).

### DC#draw_lines

draw_lines(%(arg-type)Array% points, Integer xoffset = 0, Integer yoffset = 0)

Draws lines between each element in points, which should be an Array of
co-ordinates. These may be passed as Point objects, or
using the shorter notation of two-element arrays representing x and
y. This example draws from (20, 25) to (50, 75) to (0, 100)

points = [ [20, 25], [50, 75], [0, 100] ] dc.draw_lines(points)

An optional offset may be supplied which will be added to each
point. The current pen is used for drawing the lines.

### DC#draw_polygon

draw_polygon(%(arg-type)Array% points, Integer xoffset = 0, Integer yoffset = 0, Integer fill_style = Wx::ODDEVEN_RULE)

Draws a filled polygon using points, which should be an Array of
co-ordinates. These may be passed as Point objects, or
using the shorter notation of two-element arrays representing x and
y_. See draw_linesdrawlines for an example. wxRuby automatically
closes the first and last points.

An optional offset may be supplied which will be added to each point.

The current pen is used for drawing the outline, and the current brush
for filling the shape. Using a transparent brush suppresses filling.
The last argument specifies the fill rule: Wx::ODDEVEN_RULE (the
default) or Wx::WINDING_RULE.

### DC#draw_poly_polygon

draw_poly_polygon(%(arg-type)Array% points, Integer xoffset = 0, Integer yoffset = 0, Integer fill_style = Wx::ODDEVEN_RULE)

Draws two or more filled polygons using an set of polygons described in
points_, adding the optional offset coordinates. The main reason to use
this method is for efficiency if drawing many polygons at one
time. draw_polygon is simpler, but on some platforms,
including Windows draw_poly_polygon more
efficient than using draw_polygondrawpolygon in a loop.

The argument points should be an array of arrays of co-ordinates. Each
array should describe the points of a polygon, with each point specified
using either a Point object, or a two-element array
containing x and y coordinates using integers.

The polygons maybe disjoint or overlapping. Each polygon specified in a
call to draw_poly_polygon must be closed. Unlike
polygons created by draw_polygon, the polygons created
by this method are not closed automatically.

The last argument specifies the fill rule: Wx::ODDEVEN_RULE (the
default) or Wx::WINDING_RULE. The current pen is used for drawing the
outline, and the current brush for filling the shape. Using a
transparent brush suppresses filling.

This example draws two triangles, offsetting to the right by 20 pixels
and to the top by 10 pixels.

polygon1 = [ [5, 5], [50, 50], [100, 50], [5, 5] ] polygon2 = [ [100, 200], [250, 250], [100, 75], [100, 200]] dc.draw_poly_polygon( [ polygon1, polygon2 ], 20, -10)

### DC#draw_point

draw_point(%(arg-type)Integer% x, Integer y)

Draws a point using the color of the current pen. Note that the other properties of the pen are not used, such as width etc..

### DC#draw_rectangle

draw_rectangle(%(arg-type)Integer% x, Integer y, Integer width, Integer height)

Draws a rectangle with the given top left corner, and with the given
size. The current pen is used for the outline and the current brush
for filling the shape.

### DC#draw_rotated_text

draw_rotated_text(%(arg-type)String% text, Integer x, Integer y, Float angle)

Draws the text rotated by angle degrees.

NB: Under Win9x only TrueType fonts can be drawn by this function. In
particular, a font different from `NORMAL_FONT` should be used as the
latter is not a TrueType font. `SWISS_FONT` is an example of a font
which is.

#### See also

draw_text

### DC#draw_rounded_rectangle

draw_rounded_rectangle(%(arg-type)Integer% x, Integer y, Integer width, Integer height, Float radius)

Draws a rectangle with the given top left corner, and with the given
size. The corners are quarter-circles using the given radius. The
current pen is used for the outline and the current brush for filling
the shape.

If radius is positive, the value is assumed to be the
radius of the rounded corner. If radius is negative,
the absolute value is assumed to be the proportion of the smallest
dimension of the rectangle. This means that the corner can be
a sensible size relative to the size of the rectangle, and also avoids
the strange effects X produces when the corners are too big for
the rectangle.

### DC#draw_spline

draw_spline(%(arg-type)Array% points)

Draws a spline between all given control points, using the current
pen. points should be an Array of co-ordinates. These may be passed as
Point objects, or using the shorter notation of two-element
arrays representing x and y_. See draw_linesdrawlines for an
example.

draw_spline(%(arg-type)Integer% x1, Integer y1, Integer x2, Integer y2, Integer x3, Integer y3)

Draws a three-point spline using the current pen.

### DC#draw_text

draw_text(%(arg-type)String% text, Integer x, Integer y)

Draws a text string at the specified point, using the current text font,
and the current text foreground and background colours.

The coordinates refer to the top-left corner of the rectangle bounding
the string. See DC#get_text_extent for how
to get the dimensions of a text string, which can be used to position the
text more precisely.

NB: under GTK the current
logical function is used by this function
but it is ignored by MSW. Thus, you should avoid using logical functions
with this function in portable programs.

### DC#enable_cache

enable_cache(%(arg-type)Boolean% enableCache)

On supported platforms (currently only Windows), enables the DC cache
which can speed up the Blit operation when
drawing a large number of masked bitmaps.

If using the cache functions in your code, please test for the
USE_DC_CACHEING preprocessor symbol for portability.

#### See also

DC#cache_enabled, DC#clear_cache

### DC#end_doc

end_doc()

Ends a document (only relevant when outputting to a printer).

### DC#end_page

end_page()

Ends a document page (only relevant when outputting to a printer).

### DC#flood_fill

Boolean flood_fill(%(arg-type)Integer% x, Integer y, Colour colour, Integer style=FLOOD_SURFACE)

Flood fills the device context starting from the given point, using
the current brush colour, and using a style:

- FLOOD_SURFACE: the flooding occurs until a colour other than the given colour is encountered.
- FLOOD_BORDER: the area to be flooded is bounded by the given colour.

Returns false if the operation failed.

Note: The present implementation for non-Windows platforms may fail to find
colour borders if the pixels do not match the colour exactly. However the
function will still return true.

### DC#get_background

Brush get_background()

Gets the brush used for painting the background (see DC#set_background).

### DC#get_background_mode

Integer get_background_mode()

Returns the current background mode: `SOLID` or `TRANSPARENT`.

#### See also

set_background_mode

### DC#get_brush

Brush get_brush()

Gets the current brush (see DC#set_brush).

### DC#get_char_height

Integer get_char_height()

Gets the character height of the currently set font.

### DC#get_char_width

Integer get_char_width()

Gets the average character width of the currently set font.

### DC#get_clipping_box

get_clipping_box(%(arg-type)Integer% x, Integer y, Integer width, Integer height)

Gets the rectangle surrounding the current clipping region.

### DC#get_font

Font get_font()

Gets the current font (see DC#set_font).

### DC#get_layout_direction

Integer get_layout_direction()

Gets the current layout direction of the device context. On platforms
where RTL layout is supported, the return value will either be
`Layout_LeftToRight` or `Layout_RightToLeft`. If RTL layout is not
supported, the return value will be `Layout_Default`.

#### See also

set_layout_direction

### DC#get_logical_function

Integer get_logical_function()

Gets the current logical function (see DC#set_logical_function).

### DC#get_map_mode

Integer get_map_mode()

Gets the mapping mode for the device context (see DC#set_map_mode).

### DC#get_partial_text_extents

Boolean get_partial_text_extents(%(arg-type)String% text, ArrayInt widths)

Fills the widths array with the widths from the beginning of
text to the corresponding character of text_. The generic
version simply builds a running total of the widths of each character
using get_text_extentgettextextent, however if the
various platforms have a native API function that is faster or more
accurate than the generic implementation then it should be used
instead.

### DC#get_pen

Pen get_pen()

Gets the current pen (see DC#set_pen).

### DC#get_pixel

Boolean get_pixel(%(arg-type)Integer% x, Integer y, Colour colour)

Gets in colour the colour at the specified location.
Not available for PostScriptDC or MetafileDC.

Note that setting a pixel can be done using draw_point.
h3(#DC_getppi). DC#get_ppi

Size get_ppi()

Returns the resolution of the device in pixels per inch.

### DC#get_size

Size get_size()

This gets the horizontal and vertical resolution in device units. It can
be used to scale graphics to fit the page.

For example, if max_x and max_y represent the maximum horizontal and
vertical `pixel’ values used in your application, the following code
will scale the graphic to fit on the printer page:

scale_x = max_x / dc.size.width scale_y = max_y / dc.size.height dc.set_user_scale( [scale_x, scale_y].min, [scale_x, scale_y].min)

### DC#get_size_mm

Size get_size_mm()

Returns the horizontal and vertical resolution in millimetres.

### DC#get_text_background

Colour get_text_background()

Gets the current text background colour (see
DC#set_text_background).

### DC#get_text_extent

Integer w, Integer h, Integer descent, Integer external_leading = get_text_extent(%(arg-type)String% string, Font font = nil)

Gets the dimensions of the string using the currently selected font.
string is the text string to measure, and the optional parameter
font specifies an alternative to the currently selected font: but note
that this does not yet work under Windows, so you need to set a font for
the device context first.

The method returns an array of values. w and h are the total width
and height respectively, descent is the dimension from the baseline of
the font to the bottom of the descender, and external_leading is any
extra vertical space added to the font by the font designer. This is
usually zero.

See also Font, DC#set_font.

### DC#get_text_foreground

Colour get_text_foreground()

Gets the current text foreground colour (see DC#set_text_foreground).

### DC#get_user_scale

get_user_scale(%(arg-type)Float% x, Float y)

Gets the current user scale factor (set by set_user_scale).

### DC#gradient_fill_concentric

gradient_fill_concentric(%(arg-type)Rect% rect, Colour initial_colour, Colour dest_colour, Point centre = nil )

Fill the area specified by rect with a radial gradient, starting from
initial_colour at the centre of the circle and fading to dest_colour on
the circle outside.

centre is the relative coordinates of centre of the circle in the
specified rect. If not specified, the circle is placed at the centre of
rect.

Note: Currently this function is very slow, don’t use it for real-time drawing.

### DC#gradient_fill_linear

gradient_fill_concentric(%(arg-type)Rect% rect, Colour initial_colour, Colour dest_colour, Direction dir = `Wx::EAST` )

Fill the area specified by rect with a linear gradient, starting from initialColour and eventually fading to destColour. The nDirection specifies the direction of the colour change, default is to use initialColour on the left part of the rectangle and destColour on the right one.

### DC#logical_to_device_x

Integer logical_to_device_x(%(arg-type)Integer% x)

Converts logical X coordinate to device coordinate, using the current
mapping mode.

### DC#logical_to_device_xrel

Integer logical_to_device_xrel(%(arg-type)Integer% x)

Converts logical X coordinate to relative device coordinate, using the current
mapping mode but ignoring the x axis orientation.
Use this for converting a width, for example.

### DC#logical_to_device_y

Integer logical_to_device_y(%(arg-type)Integer% y)

Converts logical Y coordinate to device coordinate, using the current
mapping mode.

### DC#logical_to_device_yrel

Integer logical_to_device_yrel(%(arg-type)Integer% y)

Converts logical Y coordinate to relative device coordinate, using the current
mapping mode but ignoring the y axis orientation.
Use this for converting a height, for example.

### DC#max_x

Integer max_x()

Gets the maximum horizontal extent used in drawing commands so far.

### DC#max_y

Integer max_y()

Gets the maximum vertical extent used in drawing commands so far.

### DC#min_x

Integer min_x()

Gets the minimum horizontal extent used in drawing commands so far.

### DC#min_y

Integer min_y()

Gets the minimum vertical extent used in drawing commands so far.

### DC#is_ok

Boolean is_ok()

Returns true if the DC is ok to use.

### DC#reset_bounding_box

reset_bounding_box()

Resets the bounding box: after a call to this function, the bounding box
doesn’t contain anything.

#### See also

calc_bounding_box

### DC#set_axis_orientation

set_axis_orientation(%(arg-type)Boolean% xLeftRight, Boolean yBottomUp)

Sets the x and y axis orientation (i.e., the direction from lowest to
highest values on the axis). The default orientation is
x axis from left to right and y axis from top down.

#### Parameters

- xLeftRight True to set the x axis orientation to the natural
  left to right orientation, false to invert it.
- yBottomUp True to set the y axis orientation to the natural
  bottom up orientation, false to invert it.

### DC#set_background

set_background(%(arg-type)Brush% brush)

Sets the current background brush for the DC.

### DC#set_background_mode

set_background_mode(%(arg-type)Integer% mode)

mode may be one of SOLID and TRANSPARENT. This setting determines
whether text will be drawn with a background colour or not.

### DC#set_brush

set_brush(%(arg-type)Brush% brush)

Sets the current brush for the DC.

If the argument is `Wx::NULL_BRUSH`, the current brush is selected out
of the device context, and the original brush restored, allowing the
current brush to be destroyed safely.

See also Brush.

See also MemoryDC for the interpretation of colours
when drawing into a monochrome bitmap.

### DC#set_clipping_region

set_clipping_region(%(arg-type)Integer% x, Integer y, Integer width, Integer height) set_clipping_region(%(arg-type)Point% pt, Size sz) set_clipping_region(%(arg-type)Rect% rect) set_clipping_region(%(arg-type)Region% region)

Sets the clipping region for this device context to the intersection of the
given region described by the parameters of this method and the previously set
clipping region. You should call
destroy_clipping_region if you want to set
the clipping region exactly to the region specified.

The clipping region is an area to which drawing is restricted. Possible uses
for the clipping region are for clipping text or for speeding up window redraws
when only a known area of the screen is damaged.

#### See also

DC#destroy_clipping_region, Region

### DC#set_device_origin

set_device_origin(%(arg-type)Integer% x, Integer y)

Sets the device origin (i.e., the origin in pixels after scaling has been
applied).

This function may be useful in Windows printing
operations for placing a graphic on a page.

### DC#set_font

set_font(%(arg-type)Font% font)

Sets the current font for the DC. It must be a valid font, in particular you
should not pass `NullFont` to this method.

See also Font.

### DC#set_layout_direction

set_layout_direction(%(arg-type)LayoutDirection% dir)

Sets the current layout direction for the device context. dir may be
either `Wx::LAYOUT_DEFAULT`, `Wx::LAYOUT_LEFT_TO_RIGHT` or
`Wx::LAYOUT_RIGHT_TO_LEFT`.

See also get_layout_direction

### DC#set_logical_function

set_logical_function(%(arg-type)Integer% function)

Sets the current logical function for the device context. This determines how
a source pixel (from a pen or brush colour, or source device context if
using DC#blit) combines with a destination pixel in the
current device context.

The possible values
and their meaning in terms of source and destination pixel values are
as follows:

AND src AND dst AND_INVERT (NOT src) AND dst AND_REVERSE src AND (NOT dst) CLEAR 0 COPY src EQUIV (NOT src) XOR dst INVERT NOT dst NAND (NOT src) OR (NOT dst) NOR (NOT src) AND (NOT dst) NO_OP dst OR src OR dst OR_INVERT (NOT src) OR dst OR_REVERSE src OR (NOT dst) SET 1 SRC_INVERT NOT src XOR src XOR dst

The default is COPY, which simply draws with the current colour.
The others combine the current colour and the background using a
logical operation. INVERT is commonly used for drawing rubber bands or
moving outlines, since drawing twice reverts to the original colour.

### DC#set_map_mode

set_map_mode(%(arg-type)Integer% int)

The mapping mode of the device context defines the unit of
measurement used to convert logical units to device units. Note that
in X, text drawing isn’t handled consistently with the mapping mode; a
font is always specified in point size. However, setting the
user scale (see DC#set_user_scale) scales the text appropriately. In
Windows, scalable TrueType fonts are always used; in X, results depend
on availability of fonts, but usually a reasonable match is found.

The coordinate origin is always at the top left of the screen/printer.

Drawing to a Windows printer device context uses the current mapping mode,
but mapping mode is currently ignored for PostScript output.

The mapping mode can be one of the following:

MM_TWIPS | Each logical unit is 1/20 of a point, or 1/1440 of an inch.
MM_POINTS | Each logical unit is a point, or 1/72 of an inch.
MM_METRIC | Each logical unit is 1 mm.
MM_LOMETRIC | Each logical unit is 1/10 of a mm.
MM_TEXT | Each logical unit is 1 pixel.

### DC#set_palette

set_palette(%(arg-type)Palette% palette)

If this is a window DC or memory DC, assigns the given palette to the window
or bitmap associated with the DC. If the argument is NullPalette, the current
palette is selected out of the device context, and the original palette
restored.

See Palette for further details.

### DC#set_pen

set_pen(%(arg-type)Pen% pen)

Sets the current pen for the DC.

If the argument is NullPen, the current pen is selected out of the device
context, and the original pen restored.

See also MemoryDC for the interpretation of colours
when drawing into a monochrome bitmap.

### DC#set_text_background

set_text_background(%(arg-type)Colour% colour)

Sets the current text background colour for the DC.

### DC#set_text_foreground

set_text_foreground(%(arg-type)Colour% colour)

Sets the current text foreground colour for the DC.

See also MemoryDC for the interpretation of colours
when drawing into a monochrome bitmap.

### DC#set_user_scale

set_user_scale(%(arg-type)Float% xScale, Float yScale)

Sets the user scaling factor, useful for applications which require
`zooming’.

### DC#start_doc

Boolean start_doc(%(arg-type)String% message)

Starts a document (only relevant when outputting to a printer).
Message is a message to show while printing.

### DC#start_page

Boolean start_page()

Starts a document page (only relevant when outputting to a printer).

[This page automatically generated from the Textile source at 2023-06-09 00:45:28 +0000]