/*
 * Copyright (c) 2005 Massachusetts Institute of Technology
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/* $Id$ */

/*!
\page pi_localization Localization

If a module requires localized resources, it can register the
localized resource libraries with the module manager when it receives
the init_module() callback.  Note that you can only register localized
resource libraries during init_module().

The localized resource library is global to a module.  Each plugin is
not allowed to define its own localization library, although it is
free to load and use any library as it sees fit.  The module manager
does not manage these libraries for the plugin.

\section pi_loc_spec Specification of localized resources

In order to register localized resource libraries, a module calls
kmm_set_locale_info().  The \a locales parameter to the function holds
a pointer to an array of ::kmm_module_locale records.  Each record
specifies one language code and a filename of a library that holds the
language resources for that language.

It is recommended that you use the LOCALE_DEF convenience macro when
defining locale records for use with kmm_set_locale_info().  This will
ensure that future changes in the API will only minimally affect your
code.  For example:

\code
kmm_module_locale my_locales[] = {
LOCALE_DEF(MAKELANGID(LANG_ENGLISH,SUBLANG_ENGLISH_US), L"english.dll", KMM_MLOC_FLAG_DEFAULT),
LOCALE_DEF(MAKELANGID(LANG_DUTCH,SUBLANG_DUTCH), L"dutch.dll", 0),
LOCALE_DEF(MAKELANGID(LANG_SPANISH,SUBLANG_SPANISH_MODERN), L"spanish.dll", 0)
};

int n_locales = sizeof(my_locales)/sizeof(my_locales[0]);

...

kmm_set_locale_info(h_module, my_locales, n_locales);

...
\endcode

See kmm_set_locale_info() and ::kmm_module_locale for more info.

\section pi_loc_how Selection of localized resource library

The module manager searches the array of ::kmm_module_locale objects
passed into the kmm_set_locale_info() function for one that matches
the current user locale (as opposed to the current system locale).  A
record matches the locale if it has the same language ID.  

If a match is found, that library is selected.  Otherwise, the list is
searched for one that is compatible with the current user locale.  A
locale record is compatible with the user locale if the primary
language matches.

If a match is still not found, the first record in the locale array
that has the ::KMM_MLOC_FLAG_DEFAULT flag set will be selected.

If a match is still not found, then the kmm_set_locale_info() will
return ::KHM_ERROR_NOT_FOUND.

\section pi_loc_usage Using localization

The following convenience macros are available for using a module
handle to load resources from the corresponding resource library.
However, for performance reasons, it is advisable to obtain a handle
to the resource library loaded by the module manager using
kmm_get_resource_module() and then use it to access resources using
the regular WIN32 API.

- ::kmm_LoadAccelerators
- ::kmm_LoadBitmap
- ::kmm_LoadCursor
- ::kmm_LoadIcon
- ::kmm_LoadImage
- ::kmm_LoadMenu
- ::kmm_LoadString

*/

