xtd - Reference Guide 0.2.0
xtd::drawing::pen Class Referencefinal

#include <pen.h>

## Definition

Defines an object used to draw lines and curves. This class cannot be inherited.

class drawing_export_ pen : public xtd::object
Inheritance
xtd::objectxtd::drawing::pen
Namespace
xtd::drawing
Library
xtd.drawing
Examples:
fill_rectangle.cpp, and user_control.cpp.

## Constructors

template<typename brush_t >
pen (const brush_t &brush)
Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::brush. More...

template<typename brush_t >
pen (const brush_t &brush, float width)
Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::brush. More...

pen (const xtd::drawing::color &color)
Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::color. More...

pen (const xtd::drawing::color &color, float width)
Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::color. More...

## Properties

xtd::drawing::drawing2d::pen_alignment alignment () const
Gets the alignment for this xtd::drawing::pen. More...

xtd::drawing::penalignment (xtd::drawing::drawing2d::pen_alignment value)
Sets the alignment for this xtd::drawing::pen. More...

const std::unique_ptr< xtd::drawing::brush > & brush () const
Gets the xtd::drawing::brush that determines attributes of this xtd::drawing::pen. More...

template<typename brush_t >
xtd::drawing::penbrush (const brush_t &value)
Sets the xtd::drawing::brush that determines attributes of this xtd::drawing::pen. More...

const xtd::drawing::colorcolor () const
Gets the color of this xtd::drawing::pen. More...

xtd::drawing::pencolor (const xtd::drawing::color &value)
Sets the color of this xtd::drawing::pen. More...

std::vector< float > dash_pattern () const
Gets an array of custom dashes and spaces. More...

xtd::drawing::pendash_pattern (const std::vector< float > &value)
Sets an array of custom dashes and spaces. More...

xtd::drawing::dash_style dash_style () const
Gets the style used for dashed lines drawn with this xtd::drawing::pen. More...

xtd::drawing::pendash_style (drawing::dash_style value)
Sets the style used for dashed lines drawn with this xtd::drawing::pen. More...

xtd::drawing::drawing2d::line_cap end_cap () const noexcept
Gets the cap style used at the end of lines drawn with this xtd::drawing::pen. More...

xtd::drawing::penend_cap (xtd::drawing::drawing2d::line_cap value)
Sets the cap style used at the end of lines drawn with this xtd::drawing::pen. More...

intptr_t handle () const
Gets the handle of the pen. More...

xtd::drawing::drawing2d::line_join line_join () const noexcept
Gets the join style for the ends of two consecutive lines drawn with this xtd::drawing::pen. More...

xtd::drawing::penline_join (xtd::drawing::drawing2d::line_join value)
Sets the join style for the ends of two consecutive lines drawn with this xtd::drawing::pen. More...

float miter_limit () const noexcept
Gets the limit of the thickness of the join on a mitered corner. More...

xtd::drawing::penmiter_limit (float value)
Sets the limit of the thickness of the join on a mitered corner. More...

xtd::drawing::drawing2d::line_cap start_cap () const noexcept
Gets the cap style used at the beginning of lines drawn with this xtd::drawing::pen. More...

xtd::drawing::penstart_cap (xtd::drawing::drawing2d::line_cap value)
Sets the cap style used at the beginning of lines drawn with this xtd::drawing::pen. More...

xtd::drawing::drawing2d::pen_type type () const
Gets the style of lines drawn with this xtd::drawing::pen. More...

float width () const
Gets the width of this xtd::drawing::pen, in units of the xtd::drawing::graphics object used for drawing. More...

xtd::drawing::penwidth (float value)
Sets the width of this xtd::drawing::pen, in units of the xtd::drawing::graphics object used for drawing. More...

## Methods

xtd::ustring to_string () const noexcept override
Returns a sxd::ustring that represents the current object. More...

Public Member Functions inherited from xtd::object
object ()=default
Create a new instance of the ultimate base class object. More...

virtual bool equals (const object &obj) const noexcept
Determines whether the specified object is equal to the current object. More...

virtual size_t get_hash_code () const noexcept
Serves as a hash function for a particular type. More...

template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
Gets the type of the current instance. More...

Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
Determines whether the specified object instances are considered equal. More...

static bool reference_equals (const object &object_a, const object &object_b) noexcept
Determines whether the specified object instances are the same instance. More...

## ◆ pen() [1/4]

template<typename brush_t >
 xtd::drawing::pen::pen ( const brush_t & brush )
inlineexplicit

Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::brush.

Parameters
 brush A xtd::drawing::brush that determines the fill properties of this xtd::drawing::pen.
Remarks
The brush property determines how the xtd::drawing::pen draws lines. Lines are drawn as if they are filled rectangles, with the characteristics of the specified brush.
The width property of the new xtd::drawing::pen is set to 1 (the default).

## ◆ pen() [2/4]

template<typename brush_t >
 xtd::drawing::pen::pen ( const brush_t & brush, float width )
inline

Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::brush.

Parameters
 brush A xtd::drawing::brush that determines the fill properties of this xtd::drawing::pen. width A single number that represent the pen width.
Remarks
The brush property determines how the xtd::drawing::pen draws lines. Lines are drawn as if they are filled rectangles, with the characteristics of the specified brush.
The width property of the new xtd::drawing::pen is set to 1 (the default).

## ◆ pen() [3/4]

 xtd::drawing::pen::pen ( const xtd::drawing::color & color )
explicit

Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::color.

Parameters
 color A xtd::drawing::color structure that indicates the color of this xtd::drawing::pen.
Remarks
The color property is set to the color specified by the color parameter. The width property is set to 1 (the default).

## ◆ pen() [4/4]

 xtd::drawing::pen::pen ( const xtd::drawing::color & color, float width )

Initializes a new instance of the xtd::drawing::pen class with the specified xtd::drawing::color.

Parameters
 color A xtd::drawing::color structure that indicates the color of this xtd::drawing::pen. width A single number that represent the pen width.
Remarks
The color property is set to the color specified by the color parameter. The width property is set to 1 (the default).

## ◆ alignment() [1/2]

 xtd::drawing::drawing2d::pen_alignment xtd::drawing::pen::alignment ( ) const

Gets the alignment for this xtd::drawing::pen.

Returns
A xtd::drawing::drawing2d::pen_alignment that represents the alignment for this xtd::drawing::pen.
Remarks
This property determines how the xtd::drawing::pen draws closed curves and polygons. The td::drawing2d::pen_alignment enumeration specifies five values; however, only two values - td::drawing2d::pen_alignment::center and td::drawing2d::pen_alignment::inset - will change the appearance of a drawn line. td::drawing2d::pen_alignment::center is the default value for this property and specifies that the width of the pen is centered on the outline of the curve or polygon. A value of td::drawing2d::pen_alignment::inset for this property specifies that the width of the pen is inside the outline of the curve or polygon. The other three values, td::drawing2d::pen_alignment::right, td::drawing2d::pen_alignment::left, and td::drawing2d::pen_alignment::outset, will result in a pen that is centered.

## ◆ alignment() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::alignment ( xtd::drawing::drawing2d::pen_alignment value )

Sets the alignment for this xtd::drawing::pen.

Parameters
 value A xtd::drawing::drawing2d::pen_alignment that represents the alignment for this xtd::drawing::pen.
Remarks
This property determines how the xtd::drawing::pen draws closed curves and polygons. The xtd::drawing::drawing2d::pen_alignment enumeration specifies five values; however, only two values - xtd::drawing::drawing2d::pen_alignment::center and xtd::drawing::drawing2d::pen_alignment::inset - will change the appearance of a drawn line. xtd::drawing::drawing2d::pen_alignment::center is the default value for this property and specifies that the width of the pen is centered on the outline of the curve or polygon. A value of xtd::drawing::drawing2d::pen_alignment::inset for this property specifies that the width of the pen is inside the outline of the curve or polygon. The other three values, xtd::drawing::drawing2d::pen_alignment::right, xtd::drawing::drawing2d::pen_alignment::left, and xtd::drawing::drawing2d::pen_alignment::outset, will result in a pen that is centered.

## ◆ brush() [1/2]

 const std::unique_ptr& xtd::drawing::pen::brush ( ) const

Gets the xtd::drawing::brush that determines attributes of this xtd::drawing::pen.

Returns
A Brush that determines attributes of this xtd::drawing::pen.
Remarks
Assigning this property causes the pen to draw filled lines and curves. It overrides thextd::drawing::pen::color property of the xtd::drawing::pen.

## ◆ brush() [2/2]

template<typename brush_t >
 xtd::drawing::pen& xtd::drawing::pen::brush ( const brush_t & value )
inline

Sets the xtd::drawing::brush that determines attributes of this xtd::drawing::pen.

Parameters
 value A xtd::drawing::brush that determines attributes of this xtd::drawing::pen.
Remarks
Assigning this property causes the pen to draw filled lines and curves. It overrides thextd::drawing::pen::color property of the xtd::drawing::pen.

## ◆ color() [1/2]

 const xtd::drawing::color& xtd::drawing::pen::color ( ) const

Gets the color of this xtd::drawing::pen.

Returns
A xtd::drawing::color structure that represents the color of this xtd::drawing::pen.

## ◆ color() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::color ( const xtd::drawing::color & value )

Sets the color of this xtd::drawing::pen.

Parameters
 value A xtd::drawing::color structure that represents the color of this xtd::drawing::pen.
Returns
This current instance.

## ◆ dash_pattern() [1/2]

 std::vector xtd::drawing::pen::dash_pattern ( ) const

Gets an array of custom dashes and spaces.

Returns
An array of real numbers that specifies the lengths of alternating dashes and spaces in dashed lines.
Remarks
Assigning a value other than empty to this property will set the xtd::drawing::pen::dash_style property for this xtd::drawing::pen to xtd::drawing:dash_style::custom.
The elements in the dash_pattern array set the length of each dash and space in the dash pattern. The first element sets the length of a dash, the second element sets the length of a space, the third element sets the length of a dash, and so on. Consequently, each element should be a non-zero positive number.
The length of each dash and space in the dash pattern is the product of the element value in the array and the width of the xtd::drawing::pen.

## ◆ dash_pattern() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::dash_pattern ( const std::vector< float > & value )

Sets an array of custom dashes and spaces.

Parameters
 value An array of real numbers that specifies the lengths of alternating dashes and spaces in dashed lines.
Remarks
Assigning a value other than empty to this property will set the xtd::drawing::pen::dash_style property for this xtd::drawing::pen to xtd::drawing:dash_style::custom.
The elements in the dash_pattern array set the length of each dash and space in the dash pattern. The first element sets the length of a dash, the second element sets the length of a space, the third element sets the length of a dash, and so on. Consequently, each element should be a non-zero positive number.
The length of each dash and space in the dash pattern is the product of the element value in the array and the width of the xtd::drawing::pen.

## ◆ dash_style() [1/2]

 xtd::drawing::dash_style xtd::drawing::pen::dash_style ( ) const

Gets the style used for dashed lines drawn with this xtd::drawing::pen.

Returns
A xtd::drawing::dash_style that represents the style used for dashed lines drawn with this xtd::drawing::pen.
Remarks
A value of xtd::drawing::dash_style::custom for this property specifies that a custom pattern of dashes and spaces, defined by the xtd::drawing::pendash_pattern property, makes up lines drawn with this xtd::drawing::pen. If the value of this property is xtd::drawing::dash_style::custom and the value of the xtd::drawing::pen::dash_pattern property is empty, the pen draws solid lines.

## ◆ dash_style() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::dash_style ( drawing::dash_style value )

Sets the style used for dashed lines drawn with this xtd::drawing::pen.

Parameters
 value A xtd::drawing::dash_style that represents the style used for dashed lines drawn with this xtd::drawing::pen.
Returns
This current instance.
Remarks
A value of xtd::drawing::dash_style::custom for this property specifies that a custom pattern of dashes and spaces, defined by the xtd::drawing::pendash_pattern property, makes up lines drawn with this xtd::drawing::pen. If the value of this property is xtd::drawing::dash_style::custom and the value of the xtd::drawing::pen::dash_pattern property is empty, the pen draws solid lines.

## ◆ end_cap() [1/2]

 xtd::drawing::drawing2d::line_cap xtd::drawing::pen::end_cap ( ) const
noexcept

Gets the cap style used at the end of lines drawn with this xtd::drawing::pen.

Returns
One of the xtd::drawing::drawing2d::line_cap values that represents the cap style used at the end of lines drawn with this xtd::drawing::pen.

## ◆ end_cap() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::end_cap ( xtd::drawing::drawing2d::line_cap value )

Sets the cap style used at the end of lines drawn with this xtd::drawing::pen.

Parameters
 value One of the xtd::drawing::drawing2d::line_cap values that represents the cap style used at the end of lines drawn with this xtd::drawing::pen.
Returns
This current instance.

## ◆ handle()

 intptr_t xtd::drawing::pen::handle ( ) const

Gets the handle of the pen.

Returns
An intptr_t that contains the handle of the pen.

## ◆ line_join() [1/2]

 xtd::drawing::drawing2d::line_join xtd::drawing::pen::line_join ( ) const
noexcept

Gets the join style for the ends of two consecutive lines drawn with this xtd::drawing::pen.

Returns
A xtd::drawing::drawing2d::line_join that represents the join style for the ends of two consecutive lines drawn with this xtd::drawing::pen.
Remarks
A line join is the common area that is formed by two lines whose ends meet or overlap. There are three line join styles: miter, bevel, and round. When you specify a line join style for a xtd::drawing::pen object, that join style will be applied to all the connected lines in any xtd::drawing::drawing2d::graphics_path object drawn using that pen. The following illustration shows the results of the beveled line join example.

## ◆ line_join() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::line_join ( xtd::drawing::drawing2d::line_join value )

Sets the join style for the ends of two consecutive lines drawn with this xtd::drawing::pen.

Parameters
 value A xtd::drawing::drawing2d::line_join that represents the join style for the ends of two consecutive lines drawn with this xtd::drawing::pen.
Returns
This current instance.
Remarks
A line join is the common area that is formed by two lines whose ends meet or overlap. There are three line join styles: miter, bevel, and round. When you specify a line join style for a xtd::drawing::pen object, that join style will be applied to all the connected lines in any xtd::drawing::drawing2d::graphics_path object drawn using that pen. The following illustration shows the results of the beveled line join example.

## ◆ miter_limit() [1/2]

 float xtd::drawing::pen::miter_limit ( ) const
noexcept

Gets the limit of the thickness of the join on a mitered corner.

Returns
The limit of the thickness of the join on a mitered corner.
Remarks
The miter length is the distance from the intersection of the line walls on the inside of the join to the intersection of the line walls outside of the join. The miter length can be large when the angle between two lines is small. The miter limit is the maximum allowed ratio of miter length to stroke width. The default value is 10.0f.
If the miter length of the join of the intersection exceeds the limit of the join, then the join will be beveled to keep it within the limit of the join of the intersection.

## ◆ miter_limit() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::miter_limit ( float value )

Sets the limit of the thickness of the join on a mitered corner.

Parameters
 value The limit of the thickness of the join on a mitered corner.
Returns
This current instance.
Remarks
The miter length is the distance from the intersection of the line walls on the inside of the join to the intersection of the line walls outside of the join. The miter length can be large when the angle between two lines is small. The miter limit is the maximum allowed ratio of miter length to stroke width. The default value is 10.0f.
If the miter length of the join of the intersection exceeds the limit of the join, then the join will be beveled to keep it within the limit of the join of the intersection.

## ◆ start_cap() [1/2]

 xtd::drawing::drawing2d::line_cap xtd::drawing::pen::start_cap ( ) const
noexcept

Gets the cap style used at the beginning of lines drawn with this xtd::drawing::pen.

Returns
One of the xtd::drawing::drawing2d::line_cap values that represents the cap style used at the beginning of lines drawn with this xtd::drawing::pen.

## ◆ start_cap() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::start_cap ( xtd::drawing::drawing2d::line_cap value )

Sets the cap style used at the beginning of lines drawn with this xtd::drawing::pen.

Parameters
 value One of the xtd::drawing::drawing2d::line_cap values that represents the cap style used at the beginning of lines drawn with this xtd::drawing::pen.
Returns
This current instance.

## ◆ to_string()

 xtd::ustring xtd::drawing::pen::to_string ( ) const
overridevirtualnoexcept

Returns a sxd::ustring that represents the current object.

Returns
A string that represents the current object.
Examples
The following code example demonstrates what to_string returns.

Reimplemented from xtd::object.

## ◆ type()

 xtd::drawing::drawing2d::pen_type xtd::drawing::pen::type ( ) const

Gets the style of lines drawn with this xtd::drawing::pen.

Returns
A xtd::drawing::drawing2d::pen_type enumeration that specifies the style of lines drawn with this xtd::drawing::pen.
Remarks
A xtd::drawing::pen can draw solid lines, filled lines, or textured lines, depending on the style specified by a member of the PenType enumeration.

## ◆ width() [1/2]

 float xtd::drawing::pen::width ( ) const
inline

Gets the width of this xtd::drawing::pen, in units of the xtd::drawing::graphics object used for drawing.

Returns
The width of this xtd::drawing::pen.
Remarks
You can access the unit of measure of the xtd::drawing::graphics object using its xtd::drawing::graphics::page_unit property. The unit of measure is typically pixels. A Width of 0 will result in the xtd::drawing::pen drawing as if the xtd::drawing::pen::width were 1.

## ◆ width() [2/2]

 xtd::drawing::pen& xtd::drawing::pen::width ( float value )

Sets the width of this xtd::drawing::pen, in units of the xtd::drawing::graphics object used for drawing.

Parameters
 value The width of this xtd::drawing::pen.
Returns
This current instance.
Remarks
You can access the unit of measure of the xtd::drawing::graphics object using its xtd::drawing::graphics::page_unit property. The unit of measure is typically pixels. A Width of 0 will result in the xtd::drawing::pen drawing as if the xtd::drawing::pen::width were 1.

The documentation for this class was generated from the following file:
• xtd.drawing/include/xtd/drawing/pen.h