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.
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.
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.
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.
There is partial support for Blit in PostScriptDC, under X.
See MemoryDC for typical usage.
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.
DC#enable_cache, DC#clear_cache
Adds the specified point to the bounding box which can be retrieved with
MinX, MaxX and
MinY, MaxY functions.
Clears the device context using the current background brush.
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.
DC#enable_cache, DC#cache_enabled
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.
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.
Destroys the current clipping region so that none of the DC is clipped.
See also DC#set_clipping_region.
Convert device X coordinate to logical coordinate, using the current
mapping mode.
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.
Converts device Y coordinate to logical coordinate, using the current
mapping mode.
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.
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.
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.
Draws a check mark inside the given rectangle.
Draws a circle with the given centre and radius.
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.
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.
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.
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.
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).
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)
An optional offset may be supplied which will be added to each
point. The current pen is used for drawing the lines.
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.
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.
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..
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.
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.
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.
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.
Draws a three-point spline using the current pen.
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.
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.
DC#cache_enabled, DC#clear_cache
Ends a document (only relevant when outputting to a printer).
Ends a document page (only relevant when outputting to a printer).
Flood fills the device context starting from the given point, using
the current brush colour, and using a style:
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.
Gets the brush used for painting the background (see DC#set_background).
Returns the current background mode: SOLID
or TRANSPARENT
.
Gets the current brush (see DC#set_brush).
Gets the character height of the currently set font.
Gets the average character width of the currently set font.
Gets the rectangle surrounding the current clipping region.
Gets the current font (see DC#set_font).
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
.
Gets the current logical function (see DC#set_logical_function).
Gets the mapping mode for the device context (see DC#set_map_mode).
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.
Gets the current pen (see DC#set_pen).
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
Returns the resolution of the device in pixels per inch.
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:
Returns the horizontal and vertical resolution in millimetres.
Gets the current text background colour (see
DC#set_text_background).
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.
Gets the current text foreground colour (see DC#set_text_foreground).
Gets the current user scale factor (set by set_user_scale).
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.
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.
Converts logical X coordinate to device coordinate, using the current
mapping mode.
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.
Converts logical Y coordinate to device coordinate, using the current
mapping mode.
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.
Gets the maximum horizontal extent used in drawing commands so far.
Gets the maximum vertical extent used in drawing commands so far.
Gets the minimum horizontal extent used in drawing commands so far.
Gets the minimum vertical extent used in drawing commands so far.
Returns true if the DC is ok to use.
Resets the bounding box: after a call to this function, the bounding box
doesn’t contain anything.
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.
Sets the current background brush for the DC.
mode may be one of SOLID and TRANSPARENT. This setting determines
whether text will be drawn with a background colour or not.
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.
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.
DC#destroy_clipping_region, Region
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.
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.
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
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:
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.
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. |
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.
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.
Sets the current text background colour for the DC.
Sets the current text foreground colour for the DC.
See also MemoryDC for the interpretation of colours
when drawing into a monochrome bitmap.
Sets the user scaling factor, useful for applications which require
`zooming’.
Starts a document (only relevant when outputting to a printer).
Message is a message to show while printing.
Starts a document page (only relevant when outputting to a printer).
[This page automatically generated from the Textile source at 2023-06-03 08:07:32 +0000]