.TH TICKIT_PEN_NEW 3
.SH NAME
tickit_pen_new \- create a new pen instance
.SH SYNOPSIS
.EX
.B #include <tickit.h>
.sp
.BI "TickitPen *tickit_pen_new(void);"
.BI "TickitPen *tickit_pen_new_attrs(...);"
.BI "TickitPen *tickit_pen_clone(const TickitPen *" orig );
.EE
.sp
Link with \fI\-ltickit\fP.
.SH DESCRIPTION
\fBtickit_pen_new\fP() creates a new \fBTickitPen\fP instance. It initially has no attributes set.
.PP
\fBtickit_pen_new_attrs\fP() creates a new \fBTickitPen\fP instance and populates it with a given list of attribute values. The attributes are given as pairs; first a \fBTickitPenAttr\fP then an integer giving its value, terminated by a final 0 or -1.
.PP
Two additional attribute types are recognised here, \fBTICKIT_PEN_FG_DESC\fP and \fBTICKIT_PEN_BG_DESC\fP. These will expect to receive a string argument value, which will be parsed as for \fBtickit_pen_set_colour_attr_desc\fP(3).
.PP
\fBtickit_pen_clone\fP() creates a new \fBTickitPen\fP instance. It initially has the same attributes values set as the one given by \fIorig\fP.
.PP
The reference count of a newly-constructed pen instance will be one. This can be incremented or decremented using \fBtickit_pen_ref\fP(3) and \fBtickit_pen_unref\fP(3). When its reference count reaches zero it is destroyed.
.SH "RETURN VALUE"
If successful, \fBtickit_pen_new\fP(), \fBtickit_pen_new_attrs\fP() and \fBtickit_pen_clone\fP() return a pointer to the new instance. On failure, \fBNULL\fP is returned with \fIerrno\fP set to indicate the failure.
.SH "SEE ALSO"
.BR tickit_pen_ref (3),
.BR tickit_pen_unref (3),
.BR tickit_pen_bind_event (3),
.BR tickit_pen (7),
.BR tickit (7)