wxLog クラスの概要

クラス: wxLog,
wxLogStderr,
wxLogStream,
wxLogTextCtrl,
wxLogWindow,
wxLogGui,
wxLogNull,
wxLogChain,
wxLogPassThrough,
wxStreamToTextRedirector

これは wxWidgets の提供するロギングクラス全般の概要です。ここでのロギングという言葉は広い意味を持っており、非対話形式のメッセージに限らず、プログラムの出力すべてを含んでいます。wxWidgets のロギング機能では ログターゲット に対する標準的なインタフェースを定義する基底 wxLog クラスや、いくつかのログクラスの標準的な実装とそれを使用する関数群を提供しています。

まず最初に、wxLog クラス郡を使用するのにその知識は必要とされません。そのため、wxLogXXX() 関数についてのみ、知っておく必要があります。これらの関数はすべて printf() や vprintf() と同じ構文を持ちます。つまり、第一引数にフォーマット文字列を取り、続けて可変引数か可変引数リストのポインタを取ります。以下にすべての関数を示します:

• wxLogFatalError は wxLogError と似ていますが、(abort() 標準関数を使用して) リターンコード 3 でプログラムを終了させます。他のすべてのロギング関数と異なり、この関数はログターゲットによってオーバーライドすることができません。
• wxLogError はエラーメッセージ (ユーザに通知しなければならないメッセージ) 用の関数です。デフォルトの処理ではメッセージボックスをポップアップして通知します。
• wxLogWarning は警告メッセージ (通常はユーザに通知されますが、プログラムの動作を妨げないメッセージ） 用の関数です。
• wxLogMessage はすべての通常 (通知) メッセージ用の関数です。この関数もデフォルトでメッセージボックスを表示します。 (ただし、この振る舞いは変更可能です。以下を参照してください)
• wxLogVerbose は詳細な出力用の関数です。通常は出力されませんが、ユーザがプログラムの進捗状況についてより詳しく知りたい場合に有効化されるかもしれません。 (名前の紛らわしい同じ機能の関数として wxLogInfo があります)
• wxLogStatus はステータスメッセージ用の関数で、このメッセージはアクティブまたは第一引数で指定された wxFrame がステータスバーを持つ場合に、ステータスバーへ出力されます。
• wxLogSysError は主に wxWidgets 自身で使用されますが、システムコール (API 関数) の失敗後のエラーログを記録するのに便利かもしれません。この関数は指定したメッセージとあわせて、最後のシステムエラーコード (プラットフォームに応じて errno または ::GetLastError() ) とそれに対応するエラーメッセージを出力します。この関数の 2 番目の形式では第一引数として明示的にエラーコードを指定できます。
• wxLogDebug は まさに デバッグ出力に適切な関数です。デバッグモードの場合 (プリプロセッサシンボル __WXDEBUG__ が定義されている場合) のみ処理を行い、リリースモードの場合 (それ以外の場合) では空文字列に展開されます。ヒント: Windows でデバッグ出力を確認するためにはデバッガーを使用するか、DbgView のようなサードパーティーのプログラムを使用する必要があります。
• wxLogTrace も wxLogDebug と同じようにデバッグビルド時のみ動作します。これを別の関数とした理由は、通常、トレースメッセージを大量に出力するため、同じように大量に出力する他のデバッグ出力と区別することに意味があるはずだからです。くわえて、2 番目の形式では第一引数としてトレースマスクを指定できるため、生成されるメッセージの量をさらに制限することができます。

これらの関数の用途はかなり明確ですが、なぜ C の標準入出力関数や C++ のストリームといった他のロギング機能を使用しないのか疑問に思うかもしれません。簡単に答えれば、それらの関数やストリームは確かに優れた汎用的な仕組みを持っていますが、本当に wxWidgets に適しているとは言えないためです。wxWidgets のログ関数を使用するいくつかの利点は以下の通りです:

• 移植性 デバッグ情報や他の情報の出力に printf() や cout/cerr などの C++ ストリームを使用するのはごく普通のことです。ただし、これは Unix では正常に動作しますが、GUI プログラムの標準出力がどこにも割り当てられない Windows では厳密にどこにも出力されません. したがって、wxLogMessage() を printf() の単純な代替として考えてください。

  以下のように書くことで wxLogXXX 呼び出しを cout へリダイレクトすることもできます:

    wxLog *logger=new wxLogStream(&cout);
    wxLog::SetActiveTarget(logger);
  

  最後に、wxStreamToTextRedirector クラスを使用することで cout へ出力した内容を wxTextCtrl にリダイレクトすることもできます。

• 柔軟性 wxLog 関数の出力はその重要度に応じてリダイレクトしたり抑制したりできます。これは従来の関数では不可能、もしくは困難なことです。例えば、すべての通知メッセージをフィルタリングして、エラーメッセージのみ、もしくはエラーメッセージと警告メッセージのみを記録しても構いません。
• 完全性 通常、処理が失敗した場合にはエラーメッセージが表示されるべきです。非常に単純で、よくあるファイルエラーの場合を考えてみましょう: データをディスク上のファイルに書き込もうとして充分な空き容量がなかったときを想像してください。実際のエラーは wxWidgets コード (wxFile::Write) 内で検知されるため、呼び出し元の関数では失敗の正確な原因を実際に知ることはできず、ディスクへの書き込みに失敗したことしか分かりません。しかし、このような状況で wxLogError() を使用すれば、書き込みに失敗したファイルに関する "高レベル" なメッセージとともに正確なエラーコード (と対応するエラーメッセージ) が表示されます。

メッセージのロギングに通常使用するすべての関数と、それらを使用する理由について列挙したので、これらの動作方法について説明します。

wxWidgets では ログターゲット という考え方があります: これは単純に wxLog を継承したクラスです。そのため、メッセージのロギング時に呼ばれる基底クラスの仮想関数を実装ています。いつでも 有効な ログターゲットはひとつだけで、これが wxLogXXX() 関数によって使用されます。ログオブジェクト (つまり、wxLog を継承したクラスのオブジェクト) の通常の使用方法は SetActiveTarget() を使用して有効なターゲットとして設定することで、それ以降に呼び出された wxLogXXX() 関数で自動的に使用されるようになります。

新しいログターゲットクラスを作成する場合、wxLog を継承し、DoLog() と DoLogString() のどちらか (または両方) を実装するだけです。標準的な wxLog メッセージの形式 (先頭に "Error:" か "Warning:" とタイムスタンプが付きます) で充分だが、メッセージを他の場所へ送りたい場合は 2 番目の関数を実装するだけで充分です。最初の関数をオーバーライドすると何でもできますが、異なるメッセージ型を自分で区別する必要があります。

wxLog を継承したクラスがいくつか事前に定義されており、新しいログターゲットクラスを作成する際の参考になると思います。もちろん、そのまま使用することも可能です。以下にその一覧を示します:

• wxLogStderr このクラスはメッセージを FILE * へ出力します。その名の通り、デフォルトでは stderr へ出力します。
• wxLogStream このクラスは wxLogStderr と同じ機能を持ちますが、FILE * と stderr の代わりに ostream と cerr を使用します。
• wxLogGui これは wxWidgets アプリケーションの標準ログターゲット (何もしない場合にデフォルトで使用されます) で、指定されたプラットフォームについて、メッセージのすべての型に対してもっとも合理的な処理を行います。
• wxLogWindow このログターゲットはアプリケーションの生成するすべてのメッセージを収集する "ログコンソール" を提供するとともに、前に有効だったログターゲットに収集したメッセージを引き渡します。ログウィンドウフレームはメニューを持ち、ログの消去、終了、メッセージの保存を選択することができます。
• wxLogNull 最後のログクラスは極めて特殊です: これは何も行いません。このクラスのオブジェクトは wxLogXXX() 関数の出力を (一時的に) 抑制する場合にインスタンス化されます。例として、存在しないファイルを開こうとすると通常はエラーメッセージが表示されますが、何らかの理由でそれを望まない場合、次のようにするだけです:

    wxFile file;
  
    // 通常はファイルを開けなかった場合に wxFile.Open() がエラーメッセージを出力するが、そうさせたくない
    {
      wxLogNull logNo;
      if ( !file.Open("bar") )
        ... 自分自身でエラー処理を行なう ...
    } // ~wxLogNull が呼ばれ、古いログ出力先が元に戻される
    
    wxLogMessage("..."); // ok
  

ログターゲットは組み合わせて使用することもできます: 例えば、メッセージを他の場所 (例えばログファイルなど) にリダイレクトしつつ、通常通りの方法でも処理したいとします。このために wxLogChain と wxLogPassThrough を使用できます。