/**
 * @file xklavier_config.h
 */

#ifndef __XKLABIER_CONFIG_H__
#define __XKLABIER_CONFIG_H__

/**
 * Maximum name length, including '\0' character
 */
#define XKL_MAX_CI_NAME_LENGTH 64
/**
 * Maximum description length, including '\0' character.
 * Important: this length is in bytes, so for unicode (UTF-8 encoding in 
 * XML file) the actual maximum length can be smaller.
 */
#define XKL_MAX_CI_DESC_LENGTH 192

#ifdef __cplusplus
extern "C"
{
#endif                          /* __cplusplus */

/**
 * The configuration item. Corresponds to XML element "configItem".
 */
  typedef struct _XklConfigItem
  {
/**
 * The configuration item name. Corresponds to XML element "name".
 */
    char name[XKL_MAX_CI_NAME_LENGTH];

/**
 * The configuration item name. Corresponds to XML element "description".
 */
    char description[XKL_MAX_CI_DESC_LENGTH];
  }
  XklConfigItem, *XklConfigItemPtr;

/**
 * @defgroup initterm XKB configuration handling initialization and termination
 * @{
 */

/**
 * Initializes XML configuration-related structures
 */
  extern void XklConfigInit( void );

/**
 * Cleans XML configuration-related structures
 */
  extern void XklConfigTerm( void );

/**
 * Loads XML configuration registry
 * @return true on success
 */
  extern Bool XklConfigLoadRegistry( void );

/**
 * Frees XML configuration registry
 */
  extern void XklConfigFreeRegistry( void );
/** @} */

/**
 * @defgroup enum XKB configuration elements enumeration functions
 * @{
 */

/**
 * Callback type used for enumerating keyboard models, layouts, variants, options
 * @param configItem is the item from registry
 * @param userData is anything which can be stored into the pointer
 */
  typedef void ( *ConfigItemProcessFunc ) ( const XklConfigItemPtr configItem,
                                            void *userData );

/**
 * Callback type used for enumerating keyboard option groups
 * @param configItem is the item from registry
 * @param allowMultipleSelection is a flag whether this group allows multiple selection
 * @param userData is anything which can be stored into the pointer
 */
  typedef void ( *GroupProcessFunc ) ( const XklConfigItemPtr configItem,
                                       Bool allowMultipleSelection,
                                       void *userData );

/**
 * Enumerates keyboard models from the XML configuration registry
 * @param func is a callback to call for every model
 * @param userData is anything which can be stored into the pointer
 */
  extern void XklConfigEnumModels( ConfigItemProcessFunc func,
                                   void *userData );

/**
 * Enumerates keyboard layouts from the XML configuration registry
 * @param func is a callback to call for every layout
 * @param userData is anything which can be stored into the pointer
 */
  extern void XklConfigEnumLayouts( ConfigItemProcessFunc func,
                                    void *userData );

/**
 * Enumerates keyboard layout variants from the XML configuration registry
 * @param layoutName is the layout name for which variants will be listed
 * @param func is a callback to call for every layout variant
 * @param userData is anything which can be stored into the pointer
 */
  extern void XklConfigEnumLayoutVariants( const char *layoutName,
                                           ConfigItemProcessFunc func,
                                           void *userData );

/**
 * Enumerates keyboard option groups from the XML configuration registry
 * @param func is a callback to call for every option group
 * @param userData is anything which can be stored into the pointer
 */
  extern void XklConfigEnumOptionGroups( GroupProcessFunc func,
                                         void *userData );

/**
 * Enumerates keyboard options from the XML configuration registry
 * @param optionGroupName is the option group name for which variants 
 * will be listed
 * @param func is a callback to call for every option
 * @param userData is anything which can be stored into the pointer
 */
  extern void XklConfigEnumOptions( const char *optionGroupName,
                                    ConfigItemProcessFunc func,
                                    void *userData );
/** @} */

/**
 * @defgroup lookup XKB configuration element lookup functions
 * @{
 */

/**
 * Loads a keyboard model information from the XML configuration registry.
 * @param ptr is a pointer to a XklConfigItem containing the name of the
 * keyboard model. On successfull return, the description is filled.
 * @return True if appropriate element was found and loaded
 */
  extern Bool XklConfigFindModel( XklConfigItemPtr ptr );

/**
 * Loads a keyboard layout information from the XML configuration registry.
 * @param ptr is a pointer to a XklConfigItem containing the name of the
 * keyboard layout. On successfull return, the description is filled.
 * @return True if appropriate element was found and loaded
 */
  extern Bool XklConfigFindLayout( XklConfigItemPtr ptr );

/**
 * Loads a keyboard layout variant information from the XML configuration 
 * registry.
 * @param layoutName is a name of the parent layout
 * @param ptr is a pointer to a XklConfigItem containing the name of the
 * keyboard layout variant. On successfull return, the description is filled.
 * @return True if appropriate element was found and loaded
 */
  extern Bool XklConfigFindVariant( const char *layoutName,
                                    XklConfigItemPtr ptr );

/**
 * Loads a keyboard option group information from the XML configuration 
 * registry.
 * @param ptr is a pointer to a XklConfigItem containing the name of the
 * keyboard option group. On successfull return, the description is filled.
 * @param allowMultipleSelection is a pointer to some Bool variable to fill 
 * the corresponding attribute of XML element "group".
 * @return True if appropriate element was found and loaded
 */
  extern Bool XklConfigFindOptionGroup( XklConfigItemPtr ptr,
                                        Bool * allowMultipleSelection );

/**
 * Loads a keyboard option information from the XML configuration 
 * registry.
 * @param optionGroupName is a name of the option group
 * @param ptr is a pointer to a XklConfigItem containing the name of the
 * keyboard option. On successfull return, the description is filled.
 * @return True if appropriate element was found and loaded
 */
  extern Bool XklConfigFindOption( const char *optionGroupName,
                                   XklConfigItemPtr ptr );
/** @} */

/**
 * @defgroup activation XKB configuration activation
 * @{
 */

/**
 * Activates some XKB configuration
 * @param model is a valid XKB model
 * @param layout is a valid XKB layout
 * @param variant is a valid XKB variant
 * @param numOptions is the size of the options array
 * @param options is an array of valid XKB options
 * @return True on success
 * At the moment, accepts only _ONE_ layout. Later probably I'll improve this..
 */
  extern Bool XklConfigActivate( const char *model, const char *layout,
                                 const char *variant, const int numOptions,
                                 const char *options[] );

/**
 * Writes some XKB configuration into XKM file
 * @param fileName is a name of the file to create
 * @param model is a valid XKB model
 * @param layout is a valid XKB layout
 * @param variant is a valid XKB variant
 * @param numOptions is the size of the options array
 * @param options is an array of valid XKB options
 * @return True on success
 * At the moment, accepts only _ONE_ layout. Later probably I'll improve this..
 */
  extern Bool XklConfigWriteXKMFile( const char *fileName, const char *model,
                                     const char *layout, const char *variant,
                                     const int numOptions,
                                     const char *options[] );
/** @} */

#ifdef __cplusplus
}
#endif                          /* __cplusplus */

#endif
