minigui.h

2410开发板上的ucos开发实例

 * \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) { return; }
#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.
 *  - IDC_NODROP\n
 *    No droping cursor.
 *  - IDC_HAND_POINT\n
 *    Hand point cursor.
 *  - IDC_HAND_SELECT\n
 *    Hand selection cursor.
 *  - IDC_SPLIT_HORZ\n
 *    Horizontal splitting cursor.
 *  - IDC_SPLIT_VERT\n
 *    Vertical splitting cursor.
 *
 * \param csrid The identifier of the system cursor.
 * \return Handle to the system cursor, otherwise zero.
 */
  HCURSOR GUIAPI GetSystemCursor (int csrid);

/**
 * \fn HCURSOR GUIAPI GetCurrentCursor (void)
 * \brief Gets the handle to the current cursor.
 *
 * This function retrives the current cursor and returns its handle.
 *
 * \return Handle to the current system cursor, zero means no current cursor.
 */
  HCURSOR GUIAPI GetCurrentCursor (void);
#else
  #define LoadCursorFromFile(filename)    (do_nothing(), 0)
  #define CreateCursor(x, y, w, h, ANDbs, XORbs, cr) (do_nothing(), 0)
  #define DestroyCursor(hcsr)             (do_nothing(), 0)
  #define GetSystemCursor(csrid)          (do_nothing(), 0)
  #define GetCurrentCursor()              (do_nothing(), 0)
#endif /* _CURSOR_SUPPORT */

#define MAX_SYSCURSORINDEX    22

/* System cursor index. */
#define IDC_ARROW       0
#define IDC_IBEAM       1
#define IDC_PENCIL      2
#define IDC_CROSS       3
#define IDC_MOVE        4
#define IDC_SIZENWSE    5
#define IDC_SIZENESW    6
#define IDC_SIZEWE      7
#define IDC_SIZENS      8
#define IDC_UPARROW     9
#define IDC_NONE        10
#define IDC_HELP        11
#define IDC_BUSY        12
#define IDC_WAIT        13
#define IDC_RARROW      14
#define IDC_COLOMN      15
#define IDC_ROW         16
#define IDC_DRAG        17
#define IDC_NODROP      18
#define IDC_HAND_POINT  19
#define IDC_HAND_SELECT 20
#define IDC_SPLIT_HORZ  21
#define IDC_SPLIT_VERT  22

/**
 * \fn void GUIAPI ClipCursor (const RECT* prc)
 * \brief Clips the cursor range.
 *
 * This function sets cursor's clipping rectangle. \a prc 
 * is the new clipping rectangle in screen coordinates. If \a prc is NULL, 
 * \a ClipCursor will disable cursor clipping.
 *
 * \param prc The clipping rectangle.
 * \return None.
 */
void GUIAPI ClipCursor (const RECT* prc);

/**
 * \fn void GUIAPI GetClipCursor (RECT* prc)
 * \brief Gets the current cursor clipping rectangle.
 *
 * This function copies the current clipping rectangle to 
 * a RECT pointed to by \a prc.
 *
 * \param prc The clipping rectangle will be saved to this rectangle.
 * \return None.
 */
void GUIAPI GetClipCursor (RECT* prc);

/**
 * \fn void GUIAPI GetCursorPos (POINT* ppt)
 * \brief Gets position of the current cursor.
 *
 * This function copies the current mouse cursor position to 
 * a POINT structure pointed to by \a ppt.
 *
 * \param ppt The position will be saved in this buffer.
 * \return None.
 *
 * \sa SetCursorPos, POINT
 */
void GUIAPI GetCursorPos (POINT* ppt);

/**
 * \fn void GUIAPI SetCursorPos (int x, int y)
 * \brief Sets position of the current cursor.
 *
 * This function sets mouse cursor position with the given 
 * arguments: \a (x,y).
 *
 * \param x The x-corrdinate of the expected poistion.
 * \param y The y-corrdinate of the expected poistion.
 * \return None.
 *
 * \sa GetCursorPos
 */
void GUIAPI SetCursorPos (int x, int y);

#ifdef _CURSOR_SUPPORT
/**
 * \fn HCURSOR GUIAPI SetCursorEx (HCURSOR hcsr, BOOL set_def)
 * \brief Changes the current cursor.
 *
 * This function changes the current cursor to be \a hcsr,
 * and/or sets it to be the default cursor.
 *
 * If you pass \a set_def as TRUE, the expected cursor will be the default cursor. 
 * The default cursor will be used when you move cursor to the desktop.
 *
 * \param hcsr The expected cursor handle.
 * \param set_def Indicates whether setting the cursor as the default cursor.
 * \return The old cursor handle.
 *
 * \sa SetCursor, SetDefaultCursor, GetDefaultCursor
 */
  HCURSOR GUIAPI SetCursorEx (HCURSOR hcsr, BOOL set_def);

/**
 * \def SetCursor(hcsr)
 * \brief Changes the current cursor.
 *
 * This function changes the current cursor to be \a hcsr.
 *
 * \param hcsr The expected cursor handle.
 * \return The old cursor handle.
 *
 * \note This function defined as a macro calling \a SetCursorEx with
 * passing \a set_def as FALSE.
 *
 * \sa SetCursorEx, SetDefaultCursor
 */
  #define SetCursor(hcsr) SetCursorEx (hcsr, FALSE)

/**
 * \def SetDefaultCursor(hcsr)
 * \brief Changes the current cursor, and set it as the default cursor.
 *
 * This function changes the current cursor to be \a hcsr, and set it as the default cursor.
 *
 * \param hcsr The expected cursor handle.
 * \return The old cursor handle.
 *
 * \note This function defined as a macro calling \a SetCursorEx with
 * passing \a set_def as TRUE.
 *
 * \sa SetCursorEx, SetCursor
 */
  #define SetDefaultCursor(hcsr) SetCursorEx (hcsr, TRUE)

/**
 * \fn HCURSOR GUIAPI GetDefaultCursor (void)
 * \brief Gets the default cursor.
 *
 * This function gets the current default cursor.
 *
 * \return The current default cursor handle.
 *
 * \sa SetCursorEx, SetDefaultCursor
 */
  HCURSOR GUIAPI GetDefaultCursor (void);

#else
  #define SetCursorEx(hcsr, set_def)    (do_nothing(), 0)
  #define SetCursor(hcsr)               (do_nothing(), 0)
  #define SetDefaultCursor(hcsr)        (do_nothing(), 0)
  #define GetDefaultCursor()            (do_nothing(), 0)
#endif /* _CURSOR_SUPPORT */

#ifdef _CURSOR_SUPPORT

/**
 * \fn int GUIAPI ShowCursor (BOOL fShow)
 * \brief Shows or hides cursor.
 *
 * This function shows or hides cursor according to the argument \a fShow. 
 * Show cursor when \a fShow is TRUE, and hide cursor when \a fShow is FALSE.
 * MiniGUI maintains a showing count value. Calling \a ShowCursor once, the count 
 * will increase when \a fShow is TRUE, or decrease one when FALSE.
 * When the count is less than 0, the cursor will disapear actually.
 *
 * \param fShow Indicates show or hide the cursor.
 * \return Cursor showing count value. 
 */
  int GUIAPI ShowCursor (BOOL fShow);
#else
  #define ShowCursor(fS