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

Boolean blit(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

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.

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(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(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(Integer x)

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

DC#device_to_logical_xrel

Integer device_to_logical_xrel(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(Integer y)

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

DC#device_to_logical_yrel

Integer device_to_logical_yrel(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(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(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(Integer x,  Integer y,  Integer width, 
                Integer height)
draw_check_mark(Rect rect)

Draws a check mark inside the given rectangle.

DC#draw_circle

draw_circle(Integer x,  Integer y,  Integer radius)
draw_circle(Point pt,  Integer radius)

Draws a circle with the given centre and radius.

See also

draw_ellipse

DC#draw_ellipse

draw_ellipse(Integer x,  Integer y,  Integer width, 
             Integer height)
draw_ellipse(Point pt,  Size size)
draw_ellipse(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(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(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(String text,                                Bitmap image, 
                                         Rect rect, 
                                         Integer alignment = ALIGN_LEFT | ALIGN_TOP, 
                                         Integer indexAccel = -1, 
                                         Rect rectBounding = nil)
draw_label(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(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(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(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_lines 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(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_polygon 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(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(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(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(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(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_lines for an example.

draw_spline(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(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(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(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:

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(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(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_extent, 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(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.

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(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(Float x,  Float y)

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

DC#gradient_fill_concentric

gradient_fill_concentric(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(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(Integer x)

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

DC#logical_to_device_xrel

Integer logical_to_device_xrel(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(Integer y)

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

DC#logical_to_device_yrel

Integer logical_to_device_yrel(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(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

DC#set_background

set_background(Brush brush)

Sets the current background brush for the DC.

DC#set_background_mode

set_background_mode(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(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(Integer x,  Integer y,  Integer width, 
                    Integer height)
set_clipping_region(Point pt,  Size sz)
set_clipping_region(Rect rect)
set_clipping_region(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(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(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(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(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(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(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(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(Colour colour)

Sets the current text background colour for the DC.

DC#set_text_foreground

set_text_foreground(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(Float xScale,  Float yScale)

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

DC#start_doc

Boolean start_doc(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 Wed Sep 09 02:21:04 +0100 2009]