.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tickit::Debug 3pm"
.TH Tickit::Debug 3pm "2023-02-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Tickit::Debug" \- debug logging support for "Tickit"
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the debug logging logic for Tickit. It is controlled
by a number of environment variables. It exports a constant called \f(CW\*(C`DEBUG\*(C'\fR
which will be true if the debug logging is enabled; allowing code to
efficiently skip over it if it isn't.
.PP
Debug messages themselves each have a flag name, which is a short string
identifying the Tickit subsystem or kind of event that caused it. A given
subset of these flags can be enabled for printing. Flags not enabled will not
be printed.
.SH "FLAGS"
.IX Header "FLAGS"
Each flag name starts with a upper-case letters indicating the subsystem it
relates to, then lower-case letters to indicate the particular kind of event
or message.
.SS "B (RenderBuffer)"
.IX Subsection "B (RenderBuffer)"
\fIBd\fR
.IX Subsection "Bd"
.PP
Drawing operations
.PP
\fIBf\fR
.IX Subsection "Bf"
.PP
Flushing
.PP
\fIBs\fR
.IX Subsection "Bs"
.PP
State stack save/restore
.PP
\fIBt\fR
.IX Subsection "Bt"
.PP
Transformations (translate, clip, mask)
.SS "I (Input)"
.IX Subsection "I (Input)"
\fIIk\fR
.IX Subsection "Ik"
.PP
Keyboard events
.PP
\fIIm\fR
.IX Subsection "Im"
.PP
Mouse events
.PP
\fIIr\fR
.IX Subsection "Ir"
.PP
Resize events
.SS "W (Window)"
.IX Subsection "W (Window)"
\fIWd\fR
.IX Subsection "Wd"
.PP
Rectangles of damage queued on the root window for re-expose
.PP
\fIWh\fR
.IX Subsection "Wh"
.PP
Hierarchy changes on Windows (creates, deletes, re-orderings)
.PP
\fIWs\fR
.IX Subsection "Ws"
.PP
Calls to \f(CW\*(C`$win\->scrollrect\*(C'\fR
.PP
\fIWsr\fR
.IX Subsection "Wsr"
.PP
Calls to \f(CW\*(C`$term\->scrollrect\*(C'\fR on the root window as part of scrollrect
.PP
\fIWx\fR
.IX Subsection "Wx"
.PP
Expose events on Windows; which may result in calls to its \f(CW\*(C`on_expose\*(C'\fR
handler. As this event is recursive, it prints an indent.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.SS "\s-1TICKIT_DEBUG_FLAGS\s0"
.IX Subsection "TICKIT_DEBUG_FLAGS"
A comma-separated list of the flags or flag categories to enable for printing.
Each potential flag exists in a category, given by the leading upper-case
letters of its name. Entire categories can be enabled by name, as can
individual flags.
.PP
See the \*(L"\s-1FLAGS\*(R"\s0 list above for the available flags.
.SS "\s-1TICKIT_DEBUG_FD\s0"
.IX Subsection "TICKIT_DEBUG_FD"
If set, debug logging is sent directly to the opened filehandle given by this
file descriptor number, rather than opening a log file.
.PP
Typically this is most useful to start a \f(CW\*(C`Tickit\*(C'\fR\-based application in a new
terminal but have its debug logging printed to \s-1STDERR\s0 of the original terminal
the new one was launched from. For example
.PP
.Vb 1
\& $ TICKIT_DEBUG_FD=3 TICKIT_DEBUG_FLAGS=... $TERM perl my\-tickit\-app.pl 3>&2
.Ve
.PP
This requests that \f(CW\*(C`Tickit::Debug\*(C'\fR log to file descriptor 3, which has been
created by copying the original shell's standard error output, and so logging
is printed to the shell this was run from.
.SS "\s-1TICKIT_DEBUG_FILE\s0"
.IX Subsection "TICKIT_DEBUG_FILE"
Gives the name of a file to open and write logging to, if \f(CW\*(C`TICKIT_DEBUG_FD\*(C'\fR
is not set. If this is not set either, a filename will be generated using the
\&\s-1PID\s0 of the process, named as
.PP
.Vb 1
\& tickit\-PID.log
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "log"
.IX Subsection "log"
.Vb 1
\&   Tickit::Debug\->log( $flag => $format, @args )
.Ve
.PP
Prints a line to the debug log if the specified \f(CW$flag\fR is present in the set
of enabled flags.
.PP
Any arguments that are \f(CW\*(C`CODE\*(C'\fR references are called and replaced by the
list of values they return, then the line itself is generated by calling
\&\f(CW\*(C`sprintf\*(C'\fR using the format string and the given arguments. It is then
printed to the log, prefixed by the flag name and with a linefeed appended.
.PP
It is not necessary to include the \f(CW\*(C`\en\*(C'\fR linefeed in the \f(CW$format\fR itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>