1Tickit::Debug(3)      User Contributed Perl Documentation     Tickit::Debug(3)
2
3
4

NAME

6       "Tickit::Debug" - debug logging support for "Tickit"
7

DESCRIPTION

9       This module implements the debug logging logic for Tickit. It is
10       controlled by a number of environment variables. It exports a constant
11       called "DEBUG" which will be true if the debug logging is enabled;
12       allowing code to efficiently skip over it if it isn't.
13
14       Debug messages themselves each have a flag name, which is a short
15       string identifying the Tickit subsystem or kind of event that caused
16       it. A given subset of these flags can be enabled for printing. Flags
17       not enabled will not be printed.
18

FLAGS

20       Each flag name starts with a upper-case letters indicating the
21       subsystem it relates to, then lower-case letters to indicate the
22       particular kind of event or message.
23
24   B (RenderBuffer)
25       Bd
26
27       Drawing operations
28
29       Bf
30
31       Flushing
32
33       Bs
34
35       State stack save/restore
36
37       Bt
38
39       Transformations (translate, clip, mask)
40
41   I (Input)
42       Ik
43
44       Keyboard events
45
46       Im
47
48       Mouse events
49
50       Ir
51
52       Resize events
53
54   W (Window)
55       Wd
56
57       Rectangles of damage queued on the root window for re-expose
58
59       Wh
60
61       Hierarchy changes on Windows (creates, deletes, re-orderings)
62
63       Ws
64
65       Calls to "$win->scrollrect"
66
67       Wsr
68
69       Calls to "$term->scrollrect" on the root window as part of scrollrect
70
71       Wx
72
73       Expose events on Windows; which may result in calls to its "on_expose"
74       handler. As this event is recursive, it prints an indent.
75

ENVIRONMENT

77   TICKIT_DEBUG_FLAGS
78       A comma-separated list of the flags or flag categories to enable for
79       printing.  Each potential flag exists in a category, given by the
80       leading upper-case letters of its name. Entire categories can be
81       enabled by name, as can individual flags.
82
83       See the "FLAGS" list above for the available flags.
84
85   TICKIT_DEBUG_FD
86       If set, debug logging is sent directly to the opened filehandle given
87       by this file descriptor number, rather than opening a log file.
88
89       Typically this is most useful to start a "Tickit"-based application in
90       a new terminal but have its debug logging printed to STDERR of the
91       original terminal the new one was launched from. For example
92
93        $ TICKIT_DEBUG_FD=3 TICKIT_DEBUG_FLAGS=... $TERM perl my-tickit-app.pl 3>&2
94
95       This requests that "Tickit::Debug" log to file descriptor 3, which has
96       been created by copying the original shell's standard error output, and
97       so logging is printed to the shell this was run from.
98
99   TICKIT_DEBUG_FILE
100       Gives the name of a file to open and write logging to, if
101       "TICKIT_DEBUG_FD" is not set. If this is not set either, a filename
102       will be generated using the PID of the process, named as
103
104        tickit-PID.log
105

METHODS

107   log
108          Tickit::Debug->log( $flag => $format, @args )
109
110       Prints a line to the debug log if the specified $flag is present in the
111       set of enabled flags.
112
113       Any arguments that are "CODE" references are called and replaced by the
114       list of values they return, then the line itself is generated by
115       calling "sprintf" using the format string and the given arguments. It
116       is then printed to the log, prefixed by the flag name and with a
117       linefeed appended.
118
119       It is not necessary to include the "\n" linefeed in the $format itself.
120

AUTHOR

122       Paul Evans <leonerd@leonerd.org.uk>
123
124
125
126perl v5.36.0                      2023-01-20                  Tickit::Debug(3)