* \fn int GUIAPI GetValueFromEtcFile (const char* pEtcFile, const char* pSection, const char* pKey, char* pValue, int iLen)
 * \brief Gets value from a configuration file.
 *
 * This function gets the value of the key \a pKey in the section \a pSection 
 * of the configuration file \a pEtcFile, and saves the value to the buffer
 * pointed to by \a pValue. 
 *
 * \param pEtcFile The path name of the configuration file.
 * \param pSection The section name in which the value located.
 * \param pKey The key name of the value.
 * \param pValue The value will be saved in this buffer.
 * \param iLen The length in bytes of the buffer.
 * \return ETC_OK on success, < 0 on error.
 *
 * \retval ETC_OK               Gets value successfullly.
 * \retval ETC_FILENOTFOUND     Can not find the specified configuration file.
 * \retval ETC_SECTIONNOTFOUND  Can not find the specified section in the configuration file.
 * \retval ETC_KEYNOTFOUND      Can not find the specified key in the section.
 * \retval ETC_FILEIOFAILED     File I/O operation error occurred.
 *
 * \note MiniGUI use \a strncpy to copy actual value to \a pValue. Thus, if the length of 
 * the actual value is larger than \a iLen, the result copied to \a pValue 
 * will \em NOT be null-terminated.
 *
 * \sa GetIntValueFromEtcFile, SetValueToEtcFile, strncpy(3)
 */
int GUIAPI GetValueFromEtcFile (const char* pEtcFile, const char* pSection,
                               const char* pKey, char* pValue, int iLen);

/**
 * \fn int GUIAPI GetIntValueFromEtcFile (const char* pEtcFile, const char* pSection, const char* pKey, int* value)
 * \brief Gets integer value from a configuration file.
 *
 * This function gets the integer value of the key \a pKey in the section \a pSection 
 * of the configuration file \a pEtcFile, and returns the integer value through the buffer
 * pointed to by \a value. 
 *
 * \param pEtcFile The path name of the configuration file.
 * \param pSection The section name in which the value located.
 * \param pKey The key name of the value.
 * \param value The integer value will be saved in this buffer.
 * \return ETC_OK on success, < 0 on error.
 *
 * \retval ETC_OK               Gets value successfullly.
 * \retval ETC_FILENOTFOUND     Can not find the specified configuration file.
 * \retval ETC_SECTIONNOTFOUND  Can not find the specified section in the configuration file.
 * \retval ETC_KEYNOTFOUND      Can not find the specified key in the section.
 * \retval ETC_FILEIOFAILED     File I/O operation error occurred.
 * \retval ETC_INTCONV          Can not convert the value string to an integer.
 *
 * \note MiniGUI uses \a strtol to convert the string value to an integer, and pass the base as 0.
 * Thus, the valid string value can be converted to integer should be in the following forms:
 *
 *  - [+|-]0x[0-9|A-F]*\n
 *    Will be read in base 16.
 *  - [+|-]0[0-7]*\n
 *    Will be read in base 8.
 *  - [+|-][1-9][0-9]*\n
 *    Will be read in base 10.
 *
 * \sa GetValueFromEtcFile, SetValueToEtcFile, strtol(3)
 */
int GUIAPI GetIntValueFromEtcFile (const char* pEtcFile, const char* pSection,
                               const char* pKey, int* value);

/**
 * \fn int GUIAPI SetValueToEtcFile (const char* pEtcFile, const char* pSection, const char* pKey, char* pValue)
 * \brief Sets a value in a configuration file.
 *
 * This function sets the value of the key \a pKey in the section \a pSection
 * of the configuration file \a pEtcFile to be the string pointed to by \a pValue.
 *
 * \param pEtcFile The path name of the configuration file.
 * \param pSection The section name in which the value located.
 * \param pKey The key name of the value.
 * \param pValue The null-terminated value string.
 * \return ETC_OK on success, < 0 on error.
 *
 * \retval ETC_OK               Sets value successfullly.
 * \retval ETC_FILEIOFAILED     File I/O operation error occurred.
 * \retval ETC_TMPFILEFAILED    Can not create temporary file.
 *
 * \note If the specified configuration file does not exist, MiniGUI will try to
 * create this file.
 *
 * \sa GetValueFromEtcFile, GetIntValueFromEtcFile
 */
int GUIAPI SetValueToEtcFile (const char* pEtcFile, const char* pSection,
                               const char* pKey, char* pValue);

/**
 * \fn GHANDLE GUIAPI LoadEtcFile (const char * pEtcFile)
 * \brief Loads an etc file into memory.
 *
 * This function loads the content of an etc file into the memory, later, you
 * can visit the content using \a GetValueFromEtc function.
 *
 * \param pEtcFile The path name of the configuration file.
 * \return Handle of the etc object on success, NULL on error.
 *
 * \sa UnloadEtcFile, GetValueFromEtc
 */
GHANDLE GUIAPI LoadEtcFile (const char * pEtcFile);

/**
 * \fn GUIAPI UnloadEtcFile (GHANDLE hEtc)
 * \brief Unloads an etc file.
 *
 * This function unloads the etc object generated by using \sa LoadEtcFile function.
 *
 * \param hEtc Handle of the etc object.
 * \return 0 on success, -1 on error.
 *
 * \sa LoadEtcFile, GetValueFromEtc
 */
int GUIAPI UnloadEtcFile (GHANDLE hEtc);

/**
 * \fn GUIAPI GetValueFromEtc (GHANDLE hEtc, const char* pSection, const char* pKey, char* pValue, int iLen)
 * \brief Gets value from a configuration etc object.
 *
 * This function gets value from an etc object, similar to GetValueFromEtcFile.
 * This function gets the value of the key \a pKey in the section \a pSection 
 * of the etc object \a hEtc, and saves the value to the buffer
 * pointed to by \a pValue. 
 *
 * \param hEtc Handle of the etc object.
 * \param pSection The section name in which the value located.
 * \param pKey The key name of the value.
 * \param pValue The value will be saved in this buffer.
 * \param iLen The length in bytes of the buffer.
 * \return ETC_OK on success, < 0 on error.
 *
 * \retval ETC_OK               Gets value successfullly.
 * \retval ETC_FILENOTFOUND     Can not find the specified configuration file.
 * \retval ETC_SECTIONNOTFOUND  Can not find the specified section in the configuration file.
 * \retval ETC_KEYNOTFOUND      Can not find the specified key in the section.
 * \retval ETC_FILEIOFAILED     File I/O operation error occurred.
 *
 * \sa LoadEtcFile, UnloadEtcFile
 */
int GUIAPI GetValueFromEtc (GHANDLE hEtc, const char* pSection,
                                            const char* pKey, char* pValue, int iLen);

/**
 * \fn int GUIAPI GetIntValueFromEtc (GHANDLE hEtc, const char* pSection, const char* pKey, int* pValue)
 * \brief Gets the integer value from a configuration etc object.
 *
 * \sa GetValueFromEtc, GetIntValueFromEtcFile
 */
int GUIAPI GetIntValueFromEtc (GHANDLE hEtc, const char* pSection,
                                            const char* pKey, int* pValue);
/**
 * \def SetValueToEtc (GHANDLE hEtc, const char* pSection, const char* pKey, char* pValue)
 * \brief Sets the value in the etc object.
 *
 * This fuctions sets the value in the etc object, somewhat similiar to \sa SetValueToEtcFile.
 */
#define SetValueToEtc(hEtc, pSection, pKey, pValue) \
        GetValueFromEtc(hEtc, pSection, pKey, pValue, -1)


/* global MiniGUI etc file object */
extern GHANDLE hMgEtc;

/* Gets value from MiniGUI configuration etc object */
static inline int GetMgEtcValue(const char* pSection, const char *pKey, char *pValue, int iLen) 
{
#ifndef _INCORE_RES
    if (!hMgEtc)
        return GetValueFromEtcFile (ETCFILEPATH, pSection, pKey, pValue, iLen);
#endif

    return GetValueFromEtc (hMgEtc, pSection, pKey, pValue, iLen);
}

/* Gets integer value from MiniGUI configuration etc object */
static inline int GetMgEtcIntValue (const char *pSection, const char* pKey, int *value)
{
#ifndef _INCORE_RES
    if (!hMgEtc)
        return GetIntValueFromEtcFile (ETCFILEPATH, pSection, pKey, value);
#endif

    return GetIntValueFromEtc (hMgEtc, pSection, pKey, value);
}

    /** @} end of etc_fns */

#ifdef _CLIPBOARD_SUPPORT

    /**
     * \addtogroup clipboard_fns ClipBoard Operations
     * @{
     */

#define LEN_CLIPBOARD_NAME      15
#define NR_CLIPBOARDS           4

#define CBNAME_TEXT             ("text")

#define CBERR_OK        0
#define CBERR_BADNAME   1
#define CBERR_NOMEM     2

#define CBOP_NORMAL     0
#define CBOP_APPEND     1

/**
 * \fn int GUIAPI CreateClipBoard (const char* cb_name, size_t size)
 * \brief Create a new clip board.
 *
 * This function creates a new clip board with the name \a cb_name.
 * MiniGUI itself creates a clip board for text copying/pasting
 * called CBNAME_TEXT.
 *
 * \param cb_name The name of the new clip board.
 * \param size The size of the clip board.
 *
 * \retval CBERR_OK         The clip board created.
 * \retval CBERR_BADNAME    Duplicated clip board name.
 * \retval CBERR_NOMEM      No enogh memory.
 *
 */
int GUIAPI CreateClipBoard (const char* cb_name, size_t size);

/**
 * \fn int GUIAPI DestroyClipBoard (const char* cb_name)
 * \brief Destroy a new clip board.
 *
 * This function destroies a clip board with the name \a cb_name.
 *
 * \param cb_name The name of the clip board.
 *
 * \retval CBERR_OK         The clip board created.
 * \retval CBERR_BADNAME    Can not find the clip board with the name.
 */
int GUIAPI DestroyClipBoard (const char* cb_name);

/**
 * \fn int GUIAPI SetClipBoardData (const char* cb_name, void* data, size_t n, int cbop)
 * \brief Set the data of a clip board.
 *
 * This function set the data into the clipboard named \a cb_name.
 *
 * \param cb_name The name of the clip board.
 * \param data The pointer to the data.
 * \param n The length of the data.
 * \param cbop Type of clipboard operations, default is CBOP_NORMAL
 *
 * \retval CBERR_OK         Success.
 * \retval CBERR_BADNAME    Bad clip board name.
 * \retval CBERR_NOMEM      No enogh memory.
 */
int GUIAPI SetClipBoardData (const char* cb_name, void* data, size_t n, int cbop);

/**
 * \fn size_t GUIAPI GetClipBoardDataLen (const char* cb_name);
 * \brief Get the length of the data of a clip board.
 *
 * This function the data length of the clipboard named \a cb_name.
 *
 * \param cb_name The name of the clip board.
 * \return The size of the data if success, otherwise zero.
 */
size_t GUIAPI GetClipBoardDataLen (const char* cb_name);

/**
 * \fn size_t GUIAPI GetClipBoardData (const char* cb_name, void* data, size_t n);
 * \brief Get the data of a clip board.
 *
 * This function get the all data from the clipboard named \a cb_name.
 *
 * \param cb_name The name of the clip board.
 * \param data The pointer to a buffer will save the data.
 * \param n The length of the buffer.
 *
 * \return The size of the data got if success, otherwise zero.
 */
size_t GUIAPI GetClipBoardData (const char* cb_name, void* data, size_t n);

/**
 * \fn int GUIAPI GetClipBoardByte (const char* cb_name, int index, unsigned char* byte);
 * \brief Get a byte of from a clip board.
 *
 * This function gets a byte from the clipboard named \a cb_name.
 *
 * \param cb_name The name of the clip board.
 * \param index The index of the byte.
 * \param byte The buffer saving the returned byte.
 *
 * \retval CBERR_OK         The clip board created.
 * \retval CBERR_BADNAME    Duplicated clip board name.
 * \retval CBERR_NOMEM      The index is beyond the data in the clipboard.
 */
int GUIAPI GetClipBoardByte (const char* cb_name, int index, unsigned char* byte);

    /** @} end of clipboard_fns */

#endif /* _CLIPBOARD_SUPPORT */

    /**
     * \addtogroup misc_fns Miscellaneous functions
     * @{
     */

/**
 * \fn void GUIAPI Ping (void)
 * \brief Makes a beep sound.
 * \sa Beep
 */
void GUIAPI Ping (void);

/**
 * \def Beep
 * \brief Alias of Ping.
 * \sa Ping
 */
#define Beep Ping

/**
 * \fn void GUIAPI Tone (int frequency_hz, int duration_ms)
 * \brief Makes a tone.
 *
 * This function will return after the tone. Thus, your program
 * will be blocked when the tone is being played.
 *
 * \param frequency_hz The frequency of the tone in hertz.
 * \param duration_ms The duration of the tone in millisecond.
 *
 * \bug When MiniGUI runs on X Window, the tone can not be played correctly.
 *
 * \sa Ping
 */
void GUIAPI Tone (int frequency_hz, int duration_ms);

/**
 * \fn void* GUIAPI GetOriginalTermIO (void)
 * \brief Gets \a termios structure of the original terminal before initializing MiniGUI.
 *
 * \return The pointer to the original \a termios structure.
 */
void* GUIAPI GetOriginalTermIO (void);

    /** @} end of misc_fns */

    /**
     * \defgroup fixed_str Length-Fixed string operations
     *
     * MiniGUI maintains a private heap for length-fixed strings, and allocates
     * length-fixed strings from this heap for window caption, menu item text, 
     * and so on. You can also use this private heap to allocate length-fixed strings.
     *
     * \include fixstr.c
     *
     * @{
     */

/**
 * \fn char* GUIAPI FixStrAlloc (int len)
 * \brief Allocates a buffer for a length-fixed string.
 *
 * This function allocates a buffer from the length-fixed string heap
 * for a string which is \a len bytes long (does not include 
 * the null character of the string). 
 *
 * \note You can change the content of the string, but do not change the
 * length of this string (shorter is valid) via \a strcat function or 
 * other equivalent functions or operations.
 *
 * \param len The length of the string.
 * \return The pointer to the buffer on success, otherwise NULL.
 *
 * \sa FreeFixStr
 */
char* GUIAPI FixStrAlloc (int len);

/**
 * \fn void GUIAPI FreeFixStr (char* str)
 * \brief Frees a length-fixed string.
 *
 * This function frees the buffer used by the length-fixed string \a str.
 *
 * \param str The length-fixed string.
 *
 * \note Do not use \a free to free the length-fixed string.
 *
 * \sa FixStrAlloc
 */
void GUIAPI FreeFixStr (char* str);

    /** @} end of fixed_str */

    /**
     * \defgroup cursor_fns Cursor operations
     * @{
     */

#ifndef _CURSOR_SUPPORT
static inline void do_nothing (void) { return; }