minigui.h

一个linux下的根文件系统的源码

                               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);

    /** @} end of etc_fns */

    /**
     * \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);

/**
 * \fn void GUIAPI Draw3DUpFrame (HDC hDC, int l, int t, int r, int b, gal_pixel fillc)
 * \brief Draws a thick 3D up frame.
 *
 * This function draws a thick 3D up frame (the border is 2-pixel wide), 
 * and fills the frame if a valid filling pixel is specified.
 *
 * \param hDC The device context.
 * \param l The x-coordinate of upper-left corner of the frame.
 * \param t The y-coordinate of upper-left corner of the frame.
 * \param r The x-coordinate of lower-right corner of the frame.
 * \param b The y-coordinate of lower-right corner of the frame.
 * \param fillc The filling color.
 *
 * \note If \a fillc is zero, this function will not fill the frame.
 *
 * \sa Draw3DDownFrame, Draw3DUpThinFrame
 */
void GUIAPI Draw3DUpFrame (HDC hDC, int l, int t, int r, int b, gal_pixel fillc);

/**
 * \fn void GUIAPI Draw3DDownFrame (HDC hDC, int l, int t, int r, int b, gal_pixel fillc)
 * \brief Draws a thick 3D down frame.
 *
 * This function draws a thick 3D down frame (the border is 2-pixel wide), 
 * and fills the frame if a valid filling pixel is specified.
 *
 * \param hDC The device context.
 * \param l The x-coordinate of upper-left corner of the frame.
 * \param t The y-coordinate of upper-left corner of the frame.
 * \param r The x-coordinate of lower-right corner of the frame.
 * \param b The y-coordinate of lower-right corner of the frame.
 * \param fillc The filling color.
 *
 * \note If \a fillc is zero, this function will not fill the frame.
 *
 * \sa Draw3DUpFrame, Draw3DDownThinFrame
 */
void GUIAPI Draw3DDownFrame (HDC hDC, int l, int t, int r, int b, gal_pixel fillc);

/**
 * \def Draw3DUpThickFrame
 * \brief Alias of Draw3DUpFrame
 */
#define Draw3DUpThickFrame      Draw3DUpFrame

/**
 * \def Draw3DDownThickFrame
 * \brief Alias of Draw3DDownFrame
 */
#define Draw3DDownThickFrame    Draw3DDownFrame

/**
 * \fn void GUIAPI Draw3DUpThinFrame (HDC hDC, int l, int t, int r, int b, gal_pixel fillc)
 * \brief Draws a thin 3D up frame.
 *
 * This function draws a thin 3D up frame (the border is 1-pixel wide), 
 * and fills the frame if a valid filling pixel is specified.
 *
 * \param hDC The device context.
 * \param l The x-coordinate of upper-left corner of the frame.
 * \param t The y-coordinate of upper-left corner of the frame.
 * \param r The x-coordinate of lower-right corner of the frame.
 * \param b The y-coordinate of lower-right corner of the frame.
 * \param fillc The filling color.
 *
 * \note If \a fillc is zero, this function will not fill the frame.
 *
 * \sa Draw3DDownThinFrame, Draw3DUpFrame
 */
void GUIAPI Draw3DUpThinFrame (HDC hDC, 
                int l, int t, int r, int b, gal_pixel fillc);

/**
 * \fn void GUIAPI Draw3DDownThinFrame (HDC hDC, int l, int t, int r, int b, gal_pixel fillc)
 * \brief Draws a thin 3D down frame.
 *
 * This function draws a thin 3D down frame (the border is 1-pixel wide), 
 * and fills the frame if a valid filling pixel is specified.
 *
 * \param hDC The device context.
 * \param l The x-coordinate of upper-left corner of the frame.
 * \param t The y-coordinate of upper-left corner of the frame.
 * \param r The x-coordinate of lower-right corner of the frame.
 * \param b The y-coordinate of lower-right corner of the frame.
 * \param fillc The filling color.
 *
 * \note If \a fillc is zero, this function will not fill the frame.
 *
 * \sa Draw3DUpThinFrame, Draw3DDownFrame
 */
void GUIAPI Draw3DDownThinFrame (HDC hDC, 
                int l, int t, int r, int b, gal_pixel fillc);

/**
 * \fn void GUIAPI Draw3DBorder (HDC hdc, int l, int t, int r, int b)
 * \brief Draws a 3D rectangle border.
 *
 * This function draws a 3D retangle border which is 2-pixel wide.
 *
 * \param hdc The device context.
 * \param l The x-coordinate of upper-left corner of the rectangle.
 * \param t The y-coordinate of upper-left corner of the rectangle.
 * \param r The x-coordinate of lower-right corner of the rectangle.
 * \param b The y-coordinate of lower-right corner of the rectangle.
 *
 * \sa Draw3DUpThinFrame, Draw3DDownFrame
 */
void GUIAPI Draw3DBorder (HDC hdc, int l, int t, int r, int b);

/**
 * \fn void GUIAPI DisabledTextOut (HDC hDC, int x, int y, const char* szText)
 * \brief Outputs disabled (grayed) text.
 *
 * This function outputs a grayed text at the specified position.
 *
 * \param hDC The device context.
 * \param x The x-coordinate of start point.
 * \param y The y-coordinate of start point.
 * \param szText The null-terminated text to be outputted.
 *
 * \sa TextOut, DrawText
 */
void GUIAPI DisabledTextOut (HDC hDC, int x, int y, const char* szText);

    /** @} 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) { };
#endif

#ifdef _CURSOR_SUPPORT

/**
 * \fn HCURSOR GUIAPI LoadCursorFromFile (const char* filename)
 * \brief Loads a cursor from a M$ Windows cursor file.
 *
 * This function loads a cursor from M$ Windows *.cur file 
 * named \a filename and returns the handle to loaded cursor. 
 * The returned handle can be used by \a SetCursor to set new mouse cursor.
 *
 * \param filename The path name of the cursor file.
 * \return Handle to the cursor, zero on error.
 *
 * \note MiniGUI does not support 256-color or animation cursor.
 *
 * \sa SetCursor
 */
  HCURSOR GUIAPI LoadCursorFromFile (const char* filename);

/**
 * \fn HCURSOR GUIAPI LoadCursorFromMem (const void* area)
 * \brief Loads a cursor from a memory area.
 *
 * This function loads a cursor from a memory area pointed to by \a area. 
 * The memory has the same layout as a M$ Windows CURSOR file.
 * The returned handle can be used by \a SetCursor to set new mouse cursor.
 *
 * \param area The pointer to the cursor data.
 * \return Handle to the cursor, zero on error.
 *
 * \note MiniGUI does not support 256-color or animation cursor.
 *
 * \sa SetCursor
 */
  HCURSOR GUIAPI LoadCursorFromMem (const void* area);

/**
 * \fn HCURSOR GUIAPI CreateCursor (int xhotspot, int yhotspot, int w, int h, const BYTE* pANDBits, const BYTE* pXORBits, int colornum)
 * \brief Creates a cursor from memory data.
 *
 * This function creates a cursor from memory data rather than cursor file. 
 * \a xhotspot and \a yhotspot specify the hotpot of the cursor, \a w and \a h are 
 * the width and the height of the cursor respectively. \a pANDBits and \a pXORBits
 * are AND bitmask and XOR bitmask of the cursor. 
 * MiniGUI currently support mono-color cursor and 16-color cursor, \a colornum 
 * specifies the cursor's color depth. For mono-color, it should be 1, and for
 * 16-color cursor, it should be 4.
 *
 * \param xhotspot The x-coordinate of the hotspot.
 * \param yhotspot The y-coordinate of the hotspot.
 * \param w The width of the cursor.
 * \param h The height of the cursor.
 * \param pANDBits The pointer to AND bits of the cursor.
 * \param pXORBits The pointer to XOR bits of the cursor.
 * \param colornum The bit-per-pixel of XOR bits.
 * \return Handle to the cursor, zero on error.
 *
 * \note MiniGUI only support 2-color or 16-color cursor.
 */
  HCURSOR GUIAPI CreateCursor (int xhotspot, int yhotspot, int w, int h, 
               const BYTE* pANDBits, const BYTE* pXORBits, int colornum);

/**
 * \fn BOOL GUIAPI DestroyCursor (HCURSOR hcsr)
 * \brief Destroies a cursor object.
 *
 * This function destroys a cursor object specified by \a hcsr.
 *
 * \param hcsr Handle to the cursor.
 * \return TRUE on success, otherwise FALSE.
 */
  BOOL GUIAPI DestroyCursor (HCURSOR hcsr);

/**
 * \fn HCURSOR GUIAPI GetSystemCursor (int csrid)
 * \brief Gets the handle to a system cursor by its identifier.
 *
 * MiniGUI creates (MAX_SYSCURSORINDEX + 1) system cursors for application.
 * You can use \a GetSystemCursor to get the handle to these system cursors.
 * The identifier can be one of the following:
 * 
 *  - IDC_ARROW\n
 *    Normal arrow cursor.
 *  - IDC_IBEAM\n
 *    'I' shaped beam cursor, indicate an input field.
 *  - IDC_PENCIL\n
 *    Pencil-shape cursor.
 *  - IDC_CROSS\n
 *    Cross cursor.
 *  - IDC_MOVE\n
 *    Moving cursor.
 *  - IDC_SIZENWSE\n
 *    Sizing cursor, along north-west and south-east.
 *  - IDC_SIZENESW\n
 *    Sizing cursor, along north-east and south-west.
 *  - IDC_SIZEWE\n
 *    Sizing cursor, along west and east.
 *  - IDC_SIZENS\n
 *    Sizing cursor, along north and south.
 *  - IDC_UPARROW\n
 *    Up arrow cursor.
 *  - IDC_NONE\n
 *    None cursor.
 *  - IDC_HELP\n
 *    Arrow with question.
 *  - IDC_BUSY\n
 *    Busy cursor.
 *  - IDC_WAIT\n
 *    Wait cursor.
 *  - IDC_RARROW\n
 *    Right arrow cursor.
 *  - IDC_COLOMN\n
 *    Cursor indicates column.
 *  - IDC_ROW\n
 *    Cursor indicates row.
 *  - IDC_DRAG\n
 *    Draging cursor.