Castle Game Engine

Unit CastleLog

Description
Uses
Classes, Interfaces, Objects and Records
Functions and Procedures
Types
Constants
Variables

Description

Logging. Log has to be activated in your program (nothing in the Castle Game Engine activates it automatically) by InitializeLog.

Uses

Overview

Functions and Procedures

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;
function LogOutput: String;
function LastLogCount: Integer;
function LastLog(const Index: Integer): String;

Types

TLogTimePrefix = (...);

Constants

MaxLastLogCount = 10;

Variables

BacktraceOnLog: boolean = false;
LogTimePrefix: TLogTimePrefix;
LogFileName: String = '';
LogEnableStandardOutput: Boolean = true;

Description

Functions and Procedures

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

Initialize logging. See https://castle-engine.io/manual_log.php for more documentation about logging.

Where do we write the log:

  • To the ALogStream, if you provide this parameter and it has non-nil value.

  • Otherwise, to the LogFileName, if you set this global variable to non-empty value.

  • Otherwise, we detect the best place to store the log automatically. This detection depends on various factors – the operating system, whether the application is GUI/console (matters for Windows), whether we are inside a shared library etc. The exact algorithm is described on https://castle-engine.io/manual_log.php .

    You can always check LogOutput value to see where the output is going now. You can e.g. display LogOutput somewhere in UI.

In case of some platforms (Android and Nintendo Switch, now) the log also always goes to the device-specific log facility. In case of Android, this is just "adb logcat", visible also if you run "castle-engine run –target=android". This is done regardless of the ALogStream or LogFileName values.

Parameters
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.

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. 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. 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 TCastleWindow.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;
 
function LogOutput: String;

Where is the log output going. This is either a filename, or something special in brackets, like <stdout>, <logging-not-initialized>, <custom-stream>.

function LastLogCount: Integer;
 
function LastLog(const Index: Integer): String;

Last log messages. Use Index from 0 (newest) to LastLogCount - 1 (oldest).

Types

TLogTimePrefix = (...);

Prefix each log line with optional date/time.

Values
  • ltNone: No prefix.
  • ltTime: Record a time for each log record.
  • ltDateTime: Record date and time for each log record.

Constants

MaxLastLogCount = 10;

How many last logs to preserve. Last logs are useful to read using LastLog, observe in inspector (press F8 in debug build), and they serve as a buffer in case you call InitializeLog after something already did WritelnLog.

Variables

BacktraceOnLog: boolean = false;

Dump backtrace (call stack) with each log. Displaying line info requires compiling your program with -gl. Note that displaying a backtrace may slow down logging considerably, so use this only when you really need it, and disable for the final build.

LogTimePrefix: TLogTimePrefix;

Current log date/time prefix style. Can be changed at 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. Note that this variable doesn't support URLs. It is only a simple filename.

It's your responsibility to choose a path that is writeable on current OS (you can e.g. use GetAppConfigDir function from FPC RTL).

LogEnableStandardOutput: Boolean = true;

Enable logging to StdOut, which is used on some platforms (like on Unix) and situations (like when run under CGE editor or CGE build tool). If False, we will always log to some file.

Generated by PasDoc 0.16.0.