Unit CastleLog

Classes, Interfaces, Objects and Records
Constants

Description

Logging. Log has to be activated in your program (nothing in the Castle Game Engine activates it automatically) by InitializeLog. Various units of the engine print some logging info when Log is true.

Uses

  • Classes

Overview

Functions and Procedures

function Log: boolean;
procedure InitializeLog( const ALogStream: TStream = nil; const ALogTimePrefix: TLogTimePrefix = ltNone); overload;
procedure InitializeLog(const ProgramVersion: string; const ALogStream: TStream = nil; const ALogTimePrefix: TLogTimePrefix = ltNone); overload; deprecated 'to provide a Version to InitializeLog, set ApplicationProperties.Version earlier, instead of calling InitializeLog with an explicit ProgramVersion parameter';
procedure WritelnLog(const Category: string; const Message: string); overload;
procedure WritelnLog(const Message: string); overload;
procedure WritelnLog(const Category: string; const MessageBase: string; const Args: array of const); overload;
procedure WritelnLog(const MessageBase: string; const Args: array of const); overload;
procedure WriteLog(const Category: string; const Message: string); overload; deprecated 'use WritelnLog, and do not add the final newline yourself to Message';
procedure WritelnLogMultiline(const Category: string; const Message: string);
procedure WriteLogMultiline(const Category: string; const Message: string); deprecated 'use WritelnLogMultiline';
procedure WritelnWarning(const Category: string; const Message: string); overload;
procedure WritelnWarning(const Message: string); overload;
procedure WritelnWarning(const Category: string; const MessageBase: string; const Args: array of const); overload;
procedure WritelnWarning(const MessageBase: string; const Args: array of const); overload;

Types

TLogTimePrefix = (...);

Variables

BacktraceOnLog: boolean = false;
LogTimePrefix: TLogTimePrefix;
LogFileName: String = '';

Description

Functions and Procedures

function Log: boolean;

Is logging active. Initially no. Activate by InitializeLog.

procedure InitializeLog( const ALogStream: TStream = nil; const ALogTimePrefix: TLogTimePrefix = ltNone); overload;

Initialize logging. The default log output is documented on https://castle-engine.io/manual_log.php .

Parameters
ALogStream
Where to generate the log.

If you leave ALogStream as Nil (default), the default log output is determined as follows:

  • To a file called LogFileName, if you set this.

  • On Unix and on console Windows applications, the output goes to the standard output, StdOut. This is most useful and common behavior on Unix, where most programs log to StdOut, and StdOut is always available.

    This approach avoids any questions from users asking "where can I find the log file?". And it avoids technical questions like "should we create a new log file with new number when old log file exists, or just overwrite old file, or append to it?" or "which directory is user-writeable". Since the user must explicitly redirect the output to the file, (s)he knows where the log file is.

  • On Windows GUI applications, we create a file xxx.log in the current directory. Where xxx is from ApplicatioName.

    GUI programs (with apptype GUI) do not have StdOut available under Windows (at least not always).

Note that on Android, we also automatically log to Android-specific log facility (that you can browse using "adb logcat"). This happens regardless of the ALogStream or LogFileName variables, all log entries *always* go to Android log.

ALogTimePrefix
optionally adds date&time prefix to each log record.
procedure InitializeLog(const ProgramVersion: string; const ALogStream: TStream = nil; const ALogTimePrefix: TLogTimePrefix = ltNone); overload; deprecated 'to provide a Version to InitializeLog, set ApplicationProperties.Version earlier, instead of calling InitializeLog with an explicit ProgramVersion parameter';

Warning: this symbol is deprecated: to provide a Version to InitializeLog, set ApplicationProperties.Version earlier, instead of calling InitializeLog with an explicit ProgramVersion parameter

 
procedure WritelnLog(const Category: string; const Message: string); overload;

Log message. Ignored when log is not initialized (Log is False).

Although we check Log here, you can also check it yourself before even calling this procedure. This way you can avoid spending time on constructing Message.

When no Category, we use ApplicationName as a category.

procedure WritelnLog(const Message: string); overload;
 
procedure WritelnLog(const Category: string; const MessageBase: string; const Args: array of const); overload;

Format and log a message. Ignored when log is not initialized (Log is False). This is a shortcut for WritelnLog(Category, Format(MessageBase, Args)).

procedure WritelnLog(const MessageBase: string; const Args: array of const); overload;
 
procedure WriteLog(const Category: string; const Message: string); overload; deprecated 'use WritelnLog, and do not add the final newline yourself to Message';

Warning: this symbol is deprecated: use WritelnLog, and do not add the final newline yourself to Message

Log message, without appending newline at the end (given Message should already contain a final newline).

procedure WritelnLogMultiline(const Category: string; const Message: string);

Log multiline message. The Message may, but doesn't have to, terminate with a newline – we will format it OK either way.

procedure WriteLogMultiline(const Category: string; const Message: string); deprecated 'use WritelnLogMultiline';

Warning: this symbol is deprecated: use WritelnLogMultiline

 
procedure WritelnWarning(const Category: string; const Message: string); overload;

Log a warning, and call ApplicationProperties.OnWarning event.

This outputs a log message, if the log is initialized by InitializeLog. We simply append the word "warning" to the Category, and pass arguments to WritelnLog.

Then, regardless if the log is initialized or not, we also call ApplicationProperties.OnWarning. This allows to react to warnings e.g. by displaying a message dialog (like ShowMessage in Lazarus, or MessageOK in CastleMessages, or TCastleWindowCustom.MessageOK). Or by raising an exception, if you want to be strict about warnings.

procedure WritelnWarning(const Message: string); overload;
 
procedure WritelnWarning(const Category: string; const MessageBase: string; const Args: array of const); overload;

A shortcut for WritelnWarning(Category, Format(MessageBase, Args)).

procedure WritelnWarning(const MessageBase: string; const Args: array of const); overload;
 

Types

TLogTimePrefix = (...);

Log date&time prefix style.

Values
  • ltNone: Default: no DateTime prefix is added.
  • ltTime: Add time prefix to each log record.
  • ltDateTime: Add date&time prefix to each log record.

Variables

BacktraceOnLog: boolean = false;

Dump backtrace (call stack) with each log. Displaying line info requires compiling your program with -gl.

LogTimePrefix: TLogTimePrefix;

Current log date&time prefix style. Can be changed runtime.

LogFileName: String = '';

Set this to a filename that should contain log, before calling InitializeLog. This may be an absolute or relative (to the current directory at the time of InitializeLog call) path. It's your responsibility to choose a path that is writeable on current OS (you can e.g. use GetAppConfigDir function from FPC RTL).


Generated by PasDoc 0.15.0.