// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2005 Koen Deforche, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WMESSAGE_RESOURCE_BUNDLE_
#define WMESSAGE_RESOURCE_BUNDLE_

#include <string>
#include <vector>
#include "WDllDefs.h"

namespace Wt {

class WString;
class WMessageResources;
class WApplication;
class WebSession;

/*! \class WMessageResourceBundle WMessageResourceBundle WMessageResourceBundle
 *  \brief The message-resource-bundle of a WApplication manages its
 *         localazible messages.
 *
 * The resource bundle manages a number of resource files, which allow
 * the developer to conceptually manage its messages in a number of
 * libraries.
 *
 * For example, a WApplication may have a generic message library, that is
 * shared with many other libraries, with re-occurring messages (such as
 * 'welcome', 'add to shopping cart', and 'pay'), and a specific message
 * library for specific messages.
 */
class WT_API WMessageResourceBundle
{
public:
  /*! \brief Add a (series) of message resource files to be used.
   *
   * When you give as path: /path/to/name, then the following message
   * resource files will be used:
   *  - /path/to/name.xml (default, English)
   *  - /path/to/name_nl.xml (for Dutch)
   *  - /path/to/name_fr.xml (for French)
   *  - etc...
   *
   * The message file that will be currently used depends on the application's
   * locale.
   *
   * A Message resource file must be formatted as follows:
   * \code
     <messages>
       <message id='welcome-text'>
         Welcome dear visiter, {1} of the WFooBar magic website !
       </message>
       <message id='company-policy'>
         The company policy is to <b>please our share-holders</b>.
       </message>
     </messages>
     \endcode
   *
   * To refer the two messages defined in this resource file, use
   * WString::tr("welcome-text").\link WString::arg()
   * arg\endlink(userName) or WWidget::tr("company-policy").
   *
   * \sa WApplication::locale(), WString::tr(), WWidget::tr()
   */
  void use(const std::string path, bool loadInMemory = true);

  /*! \brief Get the value for a particular string in the current locale.
   */
  std::wstring getValue(const WString& message);

  /*! \brief Reread the message resources.
   */
  void refresh();

private:
  std::vector<WMessageResources *> messageResources_;

  WMessageResourceBundle();
  ~WMessageResourceBundle();

  void hibernate();

  friend class WApplication;
  friend class WebSession;
};

}

#endif // WMESSAGE_RESOURCE_BUNDLE_
