src/Message/Message_MsgFile.hxx

   1 // Created on: 2001-04-26
   2 // Created by: OCC Team
   3 // Copyright (c) 2001-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Message_MsgFile_HeaderFile
  17 #define _Message_MsgFile_HeaderFile
  18
  19 #include <Standard.hxx>
  20 #include <Standard_DefineAlloc.hxx>
  21 #include <Standard_Handle.hxx>
  22
  23 #include <Standard_Boolean.hxx>
  24 class TCollection_AsciiString;
  25 class TCollection_ExtendedString;
  26
  27 //! A tool providing facility to load definitions of message strings from
  28 //! resource file(s).
  29 //!
  30 //! The message file is an ASCII file which defines a set of messages.
  31 //! Each message is identified by its keyword (string).
  32 //!
  33 //! All lines in the file starting with the exclamation sign
  34 //! (perhaps preceding by spaces and/or tabs) are ignored as comments.
  35 //!
  36 //! Each line in the file starting with the dot character "."
  37 //! (perhaps preceding by spaces and/or tabs) defines the keyword.
  38 //! The keyword is a string starting from the next symbol after dot
  39 //! and ending at the symbol preceding ending newline character "\n".
  40 //!
  41 //! All the lines in the file after the keyword and before next
  42 //! keyword (and which are not comments) define the message for that
  43 //! keyword. If the message consists of several lines, the message
  44 //! string will contain newline symbols "\n" between parts (but not
  45 //! at the end).
  46 //!
  47 //! The experimental support of Unicode message files is provided.
  48 //! These are distinguished by two bytes FF.FE or FE.FF at the beginning.
  49 //!
  50 //! The loaded messages are stored in static data map; all methods of that
  51 //! class are also static.
  52 class Message_MsgFile
  53 {
  54 public:
  55
  56   DEFINE_STANDARD_ALLOC
  57
  58   //! Load message file <theFileName> from directory <theDirName>
  59   //! or its sub-directory
  60   Standard_EXPORT static Standard_Boolean Load (const Standard_CString theDirName, const Standard_CString theFileName);
  61
  62   //! Load the messages from the given file, additive to any previously
  63   //! loaded messages. Messages with same keywords, if already present,
  64   //! are replaced with the new ones.
  65   Standard_EXPORT static Standard_Boolean LoadFile (const Standard_CString theFName);
  66
  67   //! Loads the messages from the file with name (without extension) given by environment variable.
  68   //! Extension of the file name is given separately. If its not defined, it is taken:
  69   //! - by default from environment CSF_LANGUAGE,
  70   //! - if not defined either, as "us".
  71   //! @name theEnvName  environment variable name
  72   //! @name theFileName file name without language suffix
  73   //! @name theLangExt  language file name extension
  74   //! @return TRUE on success
  75   Standard_EXPORT static Standard_Boolean LoadFromEnv (const Standard_CString theEnvName,
  76                                                        const Standard_CString theFileName,
  77                                                        const Standard_CString theLangExt = "");
  78
  79   //! Loads the messages from the given text buffer.
  80   //! @param theContent string containing the messages
  81   //! @param theLength  length of the buffer;
  82   //!                   when -1 specified - theContent will be considered as NULL-terminated string
  83   Standard_EXPORT static Standard_Boolean LoadFromString (const Standard_CString theContent,
  84                                                           const Standard_Integer theLength = -1);
  85
  86   //! Adds new message to the map. Parameter <key> gives
  87   //! the key of the message, <text> defines the message itself.
  88   //! If there already was defined the message identified by the
  89   //! same keyword, it is replaced with the new one.
  90   Standard_EXPORT static Standard_Boolean AddMsg (const TCollection_AsciiString& key, const TCollection_ExtendedString& text);
  91
  92   //! Returns True if message with specified keyword is registered
  93   Standard_EXPORT static Standard_Boolean HasMsg (const TCollection_AsciiString& key);
  94
  95   Standard_EXPORT static const TCollection_ExtendedString& Msg (const Standard_CString key);
  96
  97   //! Gives the text for the message identified by the keyword <key>.
  98   //! If there are no messages with such keyword defined, the error message is returned.
  99   //! In that case reference to static string is returned, it can be changed with next call(s) to Msg().
 100   //! Note: The error message is constructed like 'Unknown message: <key>', and can
 101   //! itself be customized by defining message with key Message_Msg_BadKeyword.
 102   Standard_EXPORT static const TCollection_ExtendedString& Msg (const TCollection_AsciiString& key);
 103
 104 };
 105
 106 #endif // _Message_MsgFile_HeaderFile