NAME

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

DESCRIPTION

       This module implements the debug logging logic for Tickit. It is controlled by a number of
       environment variables. It exports a constant called "DEBUG" which will be true if the
       debug logging is enabled; allowing code to efficiently skip over it if it isn't.

       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.

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.

   B (RenderBuffer)
       Bd

       Drawing operations

       Bf

       Flushing

       Bs

       State stack save/restore

       Bt

       Transformations (translate, clip, mask)

   I (Input)
       Ik

       Keyboard events

       Im

       Mouse events

       Ir

       Resize events

   W (Window)
       Wd

       Rectangles of damage queued on the root window for re-expose

       Wh

       Hierarchy changes on Windows (creates, deletes, re-orderings)

       Ws

       Calls to "$win->scrollrect"

       Wsr

       Calls to "$term->scrollrect" on the root window as part of scrollrect

       Wx

       Expose events on Windows; which may result in calls to its "on_expose" handler. As this
       event is recursive, it prints an indent.

ENVIRONMENT

   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.

       See the "FLAGS" list above for the available flags.

   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.

       Typically this is most useful to start a "Tickit"-based application in a new terminal but
       have its debug logging printed to STDERR of the original terminal the new one was launched
       from. For example

        $ TICKIT_DEBUG_FD=3 TICKIT_DEBUG_FLAGS=... $TERM perl my-tickit-app.pl 3>&2

       This requests that "Tickit::Debug" 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.

   TICKIT_DEBUG_FILE
       Gives the name of a file to open and write logging to, if "TICKIT_DEBUG_FD" is not set. If
       this is not set either, a filename will be generated using the PID of the process, named
       as

        tickit-PID.log

METHODS

   log
          Tickit::Debug->log( $flag => $format, @args )

       Prints a line to the debug log if the specified $flag is present in the set of enabled
       flags.

       Any arguments that are "CODE" references are called and replaced by the list of values
       they return, then the line itself is generated by calling "sprintf" 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.

       It is not necessary to include the "\n" linefeed in the $format itself.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>