wxRuby Documentation Home

# Wx::Pen

A pen is a drawing tool for drawing outlines. It is used for drawing
lines and painting the outline of rectangles, ellipses, etc. It has a
colour, a width and a style. The style defines what dash pattern, if
any, should be applied. The default is a solid line, but a set of
predefined dashes or a custom pattern can be used.

## Derived from

GDIObject

Object

## Predefined objects

The following standard pens are available to all applications:

Wx::NULL_PEN Wx::RED_PEN Wx::CYAN_PEN Wx::GREEN_PEN Wx::BLACK_PEN Wx::WHITE_PEN Wx::TRANSPARENT_PEN Wx::BLACK_DASHED_PEN Wx::GREY_PEN Wx::MEDIUM_GREY_PEN Wx::LIGHT_GREY_PEN

## Remarks

On a monochrome display, wxRUby shows all non-white pens as black.

Do not initialize Pens before the application commences, since other
required structures may not have been set up yet. Instead, define
methods which return Pens, and initialize them on first call.

## See also

PenList, DC, DC#set_pen, Brush

## Methods

- Pen.new
- Pen#get_cap
- Pen#get_colour
- Pen#get_dashes
- Pen#get_join
- Pen#get_stipple
- Pen#get_style
- Pen#get_width
- Pen#ok
- Pen#set_cap
- Pen#set_colour
- Pen#set_dashes
- Pen#set_join
- Pen#set_stipple
- Pen#set_style
- Pen#set_width

### Pen.new

Pen.new(%(arg-type)Colour% colour, Integer width = 1, Integer style = `Wx::SOLID`)

Constructs a pen from a colour object, pen width and style.

Pen.new(%(arg-type)String% colourName, Integer width, Integer style)

Constructs a pen from a colour name, pen width and style.

Pen.new(%(arg-type)Bitmap% stipple, Integer width)

Constructs a stippled pen from a stipple bitmap and a width.

#### Parameters

- colour A colour object.
- colourName A colour name.
- width Pen width. Under Windows, the pen width cannot be greater than 1 if
  the style is DOT, LONG_DASH, SHORT_DASH, DOT_DASH, or USER_DASH.
- stipple A stipple bitmap.
- style The style may be one of the following:

SOLID | Solid style.
TRANSPARENT | No pen is used.
DOT | Dotted style.
LONG_DASH | Long dashed style.
SHORT_DASH | Short dashed style.
DOT_DASH | Dot and dash style.
STIPPLE | Use the stipple bitmap.
USER_DASH | Use a custom dash pattern: see set_dashes.
BDIAGONAL_HATCH | Backward diagonal hatch.
CROSSDIAG_HATCH | Cross-diagonal hatch.
FDIAGONAL_HATCH | Forward diagonal hatch.
CROSS_HATCH | Cross hatch.
HORIZONTAL_HATCH | Horizontal hatch.
VERTICAL_HATCH | Vertical hatch.

#### Remarks

Different versions of Windows and different versions of other platforms
support very different subsets of the styles above – there is no
similarity even between Windows95 and Windows98 – so handle with care,
and test across platforms.

If the named colour form is used, an appropriate
Wx::Colour structure is found in the colour database.

#### See also

Pen#set_style, Pen#set_colour, Pen#set_width, Pen#set_stipple

### Pen#get_cap

Integer get_cap()

Returns the pen cap style, which may be one of `Wx::CAP_ROUND`,
`Wx::CAP_PROJECTING` and `Wx::CAP_BUTT`. The default is `Wx::CAP_ROUND`.

### Pen#get_colour

Colour get_colour()

Returns the pen’s colour

### Pen#get_dashes

Array get_dashes()

Returns an Array of Integers representing the current dashing pattern
being used by this pen. See set_dashes for a
description of the Array format used to represent dashes.

### Pen#get_join

Integer get_join()

Returns the pen join style, which may be one of `Wx::JOIN_BEVEL`,
`Wx::JOIN_ROUND` and `Wx::JOIN_MITER`. The default is `Wx::JOIN_ROUND`.

### Pen#get_stipple

Bitmap get_stipple()

Gets the stipple bitmap.

### Pen#get_style

Integer get_style()

Returns the pen style, for example `Wx::SOLID`.

### Pen#get_width

Integer get_width()

Returns the pen width.

### Pen#is_ok

Boolean is_ok()

Returns true if the pen is initialised.

### Pen#set_cap

set_cap(%(arg-type)Integer% capStyle)

Sets the pen cap style, which may be one of `Wx::CAP_ROUND`,
`Wx::CAP_PROJECTING` and `Wx::CAP_BUTT`. The default is
`Wx::CAP_ROUND`.

### Pen#set_colour

set_colour(%(arg-type)Colour% colour) set_colour(%(arg-type)String% colour_name) set_colour(%(arg-type)Integer% red, Integer blue, Integer green)

Specifies the colour of the pen by using a Colour, a
colour name (see Colour for more details), or a set of
red, green and blue values.

### Pen#set_dashes

set_dashes(%(arg-type)Array% dashes)

Sets the lengths of a custom dash pattern. dashes should be an Array
of Integers each of which specifies the length of an on (drawn) or off
(blank) section of the line. For example, passing [4, 1, 4, 2] as an
argument would draw a line with 4 pixels dash, 1 pixel blank, 4 pixels
dash, 2 pixels blank.

Note that the pen should have been created with the style
`Wx::USER_DASH` in order to define custom dashing styles.

### Pen#set_join

set_join(%(arg-type)Integer% join_style)

Returns the pen join style, which may be one of `Wx::JOIN_BEVEL`,
`Wx::JOIN_ROUND` and `Wx::JOIN_MITER`. The default is `Wx::JOIN_ROUND`.

### Pen#set_stipple

set_stipple(%(arg-type)Bitmap% stipple)

Sets the bitmap for stippling.

### Pen#set_style

set_style(%(arg-type)Integer% style)

Sets the pen style; see Pen.new for valid styles.

### Pen#set_width

set_width(%(arg-type)Integer% width)

Sets the pen width, in pixels.

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