window.h

MiniGUI for uCOS 移植实验全部源码

 * \brief Is an alias of \a Send2Client
 *
 * \sa Send2Client
 */
#define send2client Send2Client

/**
 * \fn BOOL Send2TopMostClients (int iMsg, WPARAM wParam, LPARAM lParam)
 * \brief Sends a message to all clients in the topmost layer.
 *
 * This function sends the message specified by (\a iMsg, \a wParam, \a lParam) 
 * to all clients in the topmost layer.
 *
 * \param iMsg The message identifier.
 * \param wParam The first parameter of the message.
 * \param lParam The second parameter of the message.
 * \return TRUE on success, FALSE on error.
 *
 * \note This function is only defined for MiniGUI-Lite, and
 *       can be called only by the server, i.e. \a mginit.
 *
 * \sa Send2Client
 */
    BOOL GUIAPI Send2TopMostClients (int iMsg, WPARAM wParam, LPARAM lParam);

/**
 * \fn BOOL Send2ActiveClient (int iMsg, WPARAM wParam, LPARAM lParam)
 * \brief Sends a message to the active client in the topmost layer.
 *
 * This function sends the message specified by (\a iMsg, \a wParam, \a lParam) 
 * to the current active client in the topmost layer.
 *
 * \param iMsg The message identifier.
 * \param wParam The first parameter of the message.
 * \param lParam The second parameter of the message.
 * \return TRUE on success, FALSE on error.
 *
 * \note This function is only defined for MiniGUI-Lite, and
 *       can be called only by the server, i.e. \a mginit.
 *
 * \sa Send2Client
 */
    BOOL GUIAPI Send2ActiveClient (int iMsg, WPARAM wParam, LPARAM lParam);
#else

/**
 * \fn int PostSyncMessage (HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam)
 * \brief Posts a synchronical message to a window which is in different thread.
 *
 * This function posts the synchronical message specified by 
 * (\a iMsg, \a wParam, \a lParam) to the window \a hWnd which 
 * is in different thread. This function will return until 
 * the message is handled by the window procedure.
 *
 * \note The destination window must belong to other thread.
 *
 * \param iMsg The message identifier.
 * \param wParam The first parameter of the message.
 * \param lParam The second parameter of the message.
 * \return The return value of the message handler.
 *
 * \sa SendMessage
 */
    int GUIAPI PostSyncMessage (HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam);

/**
 * \fn int SendAsyncMessage (HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam)
 * \brief Sends an asynchronical message to a window.
 *
 * This function sends the asynchronical message specified by 
 * (\a iMsg, \a wParam, \a lParam) to the window \a hWnd 
 * which is in different thread. This function calls 
 * the window procedure immediately. So it is very dangerous.
 *
 * \param iMsg The message identifier.
 * \param wParam The first parameter of the message.
 * \param lParam The second parameter of the message.
 * \return The return value of the message handler.
 *
 * \note This function may corrupt your data.
 *
 * \sa PostSyncMessage
 */
    int GUIAPI SendAsyncMessage (HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam);
#endif

/**
 * \fn int SendNotifyMessage (HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam)
 * \brief Sends a notification message to a window.
 *
 * This function sends the notification message specified by (\a iMsg, \a wParam, \a lParam)
 * to the window \a hWnd. This function puts the notication message in the message queue
 * and then returns immediately.
 *
 * \param hWnd The handle to the window.
 * \param iMsg The message identifier.
 * \param wParam The first parameter of the message.
 * \param lParam The second parameter of the message.
 * \return 0 if all OK, < 0 on error.
 *
 * \sa SendMessage, PostMessage
 */
int GUIAPI SendNotifyMessage (HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam);

/**
 * \fn int BroadcastMessage (int iMsg, WPARAM wParam, LPARAM lParam)
 * \brief Broadcasts a message to all main window on the desktop.
 *
 * This function posts the message specified by (\a iMsg, \a wParam, \a lParam)
 * to all the main windows on the desktop.
 *
 * \param iMsg The message identifier.
 * \param wParam The first parameter of the message.
 * \param lParam The second parameter of the message.
 * \return 0 if all OK, < 0 on error.
 *
 * \sa PostMessage
 */
int GUIAPI BroadcastMessage (int iMsg, WPARAM wParam, LPARAM lParam);

/**
 * \fn int PostQuitMessage (HWND hWnd)
 * \brief Puts a MSG_QUIT message into the message queue of a main window.
 *
 * This function puts a MSG_QUIT message into the message queue of the
 * main window \a hWnd. The next call to \a GetMessage will return 0.
 *
 * \param hWnd The handle to the main window.
 * \return 0 if all OK, < 0 on error.
 *
 * \sa GetMessage
 */
int GUIAPI PostQuitMessage (HWND hWnd);

#define KBD_LAYOUT_DEFAULT  "default"
#define KBD_LAYOUT_FRPC     "frpc"
#define KBD_LAYOUT_FR       "fr"
#define KBD_LAYOUT_DE       "de"
#define KBD_LAYOUT_DELATIN1 "delatin1"
#define KBD_LAYOUT_IT       "it"
#define KBD_LAYOUT_ES       "es"
#define KBD_LAYOUT_ESCP850  "escp850"

/**
 * \fn BOOL SetKeyboardLayout (const char* kbd_layout)
 * \brief Sets a new keyboard layout.
 *
 * This function sets the keymaps to translate key scancodes to MSG_CHAR
 * or MSG_KEYSYM messages. The default keymaps is for US PC keyboard 
 * layout, you can call this function to set a different keyboard layout.
 * The argument of \a kbd_layout specifies the name of the keyboard layout.
 *
 * \param kbd_layout The keyboard layout name. It can be one of the following values:
 *
 *      - KBD_LAYOUT_DEFAULT\n
 *        The default keyboard layout, i.e., US PC.
 *      - KBD_LAYOUT_FRPC\n
 *        The France PC keyboard layout.
 *      - KBD_LAYOUT_FR\n
 *        The France keyboard layout.
 *      - KBD_LAYOUT_DE\n
 *        The German keyboard layout.
 *      - KBD_LAYOUT_DELATIN1\n
 *        The German Latin1 keyboard layout.
 *      - KBD_LAYOUT_IT\n
 *        The Italian keyboard layout.
 *      - KBD_LAYOUT_ES\n
 *        The Spanish keyboard layout.
 *      - KBD_LAYOUT_ESCP850\n
 *        The Spanish CP850 keyboard layout.
 *
 * \return TRUE for success, otherwise FALSE.
 *
 * \sa TranslateMessage, MSG_CHAR, MSG_KEYSYM
 */
BOOL GUIAPI SetKeyboardLayout (const char* kbd_layout);

/**
 * \fn BOOL TranslateMessage (PMSG pMsg)
 * \brief Translates key down and key up messages to MSG_CHAR 
 *        message and post it into the message queue.
 *
 * This function translates key down and key up message to an MSG_CHAR 
 * message or some MSG_KEYSYM messages, and send the message(s) to 
 * the window procedure as a notification message. If the message is 
 * not a key message, this function does nothing.
 *
 * The behavior of this function is inflected by the current
 * keyboard layout. The default keyboard layout is US keyboard, but
 * you can call \a SetKeyboardLayout function to set a different keyboard
 * layout.
 *
 * \param pMsg The pointer of message.
 * \return A boolean indicates whether the message is a key message.
 *
 * \sa SetKeyboardLayout, MSG_CHAR, MSG_KEYSYM
 */
BOOL GUIAPI TranslateMessage (PMSG pMsg);

/**
 * \fn int DispatchMessage (PMSG pMsg)
 * \brief Dispatches a message to the window's callback procedure.
 *
 * This function dispatches the message pointed to by \a pMsg to the
 * target window's callback procedure.
 *
 * \param pMsg The pointer to the message.
 * \return The return value of the message handler.
 *
 * \sa GetMessage
 *
 * Example:
 *
 * \include getmessage.c
 */
int GUIAPI DispatchMessage (PMSG pMsg);

/**
 * \fn int ThrowAwayMessages (HWND pMainWnd)
 * \brief Removes all messages in the message queue associated with a window.
 *
 * This function removes all messages which are associated with 
 * the specified window \a pMainWnd.
 *
 * \param pMainWnd The handle to the window.
 * \return The number of thrown messages.
 *
 * \sa EmptyMessageQueue
 */
int GUIAPI ThrowAwayMessages (HWND pMainWnd);

#ifdef _LITE_VERSION

/**
 * \fn BOOL EmptyMessageQueue (HWND hWnd)
 * \brief Empties a message queue.
 *
 * This function empties the message queue of the main window \a hWnd.
 *
 * \param hWnd The handle to the main window.
 * \return TRUE on all success, FALSE on error.
 *
 * \note Only defined for MiniGUI-Lite.
 *
 * \sa ThrowAwayMessages
 */
BOOL GUIAPI EmptyMessageQueue (HWND hWnd);
#endif

#ifdef _MSG_STRING

/**
 * \fn const char* GUIAPI Message2Str (int message)
 * \brief Translates a message identifier to the message string.
 *
 * This function returns the message string of the message identifier \a message.
 * E.g. this function will return the string of "MSG_CHAR" for MSG_CHAR message.
 * 
 * \param message The message identifier.
 * \return The message string.
 *
 * \note Only defined for _MSG_STRING.
 *
 * \sa PrintMessage
 */
const char* GUIAPI Message2Str (int message);

/**
 * \fn void GUIAPI PrintMessage (FILE* fp, HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam)
 * \brief Prints a message in readable string form to a stdio stream.
 *
 * This function prints the message specified by (\a iMsg, \a wParam, \a lParam)
 * in readable string form to the stdio stream \a fp.
 *
 * \param fp The pointer to the FILE object.
 * \param hWnd The target window of the message.
 * \param iMsg The message identifier.
 * \param wParam The first parameter of the message.
 * \param lParam The second parameter of the message.
 *
 * \sa Message2Str
 */
void GUIAPI PrintMessage (FILE* fp, HWND hWnd, int iMsg, WPARAM wParam, LPARAM lParam);

#endif

    /** @} end of msg_pass_fns */

    /**
     * \defgroup msg_hook_fns Message or event hook functions
     * @{
     */

#define HOOK_GOON       0
#define HOOK_STOP       1

/**
 * Type of message hook function.
 */
typedef int (* MSGHOOK)(void* context, HWND dst_wnd, int msg, WPARAM wparam, LPARAM lparam);

/**
 * Structure defines a message hook.
 */
typedef struct _HOOKINFO
{
    /** the context which will be passed to the hook function. */
    void* context;
    /** the pointer to the hook function. */
    MSGHOOK hook;
} HOOKINFO;

/**
 * \fn MSGHOOK GUIAPI RegisterKeyMsgHook (void* context, MSGHOOK hook)
 * \brief Registers a key message hook.
 *
 * This function registers a key message hook pointed to by \a hook.
 *
 * When the desktop receives a key message, it will send it to the hook first,
 * and passes the \a context value to the hook as the first argument.
 *
 * \param context The context value will be passed to the hook.
 * \param hook The hook. This function will unregister the old hook if hook is NULL.
 * \return The old hook.
 *
 * \sa UnregisterHook, KEYMSGHOOK
 */
MSGHOOK GUIAPI RegisterKeyMsgHook (void* context, MSGHOOK hook);

/**
 * \fn MSGHOOK GUIAPI RegisterMouseMsgHook (void* context, MSGHOOK hook)
 * \brief Registers a mouse message hook.
 *
 * This function registers a mouse message hook pointed to by \a hook.
 *
 * When the desktop receives a mouse message, it will send it to the hook first,
 * and passes the \a context value to the hook as the first argument.
 *
 * \param context The context value will be passed to the hook.
 * \param hook The hook. This function will unregister the old hook if hook is NULL.
 * \return The old hook.
 *
 * \sa UnregisterHook, KEYMSGHOOK
 */
MSGHOOK GUIAPI RegisterMouseMsgHook (void* context, MSGHOOK hook);

#ifdef _LITE_VERSION

/**
 * \var typedef int (* SRVEVTHOOK) (PMSG pMsg)
 * \brief The type of the event hook.
 *
 * You can call \a SetServerEventHook to set an event hook
 * in the server of the MiniGUI-Lite.
 *
 * If the event hook returns HOOK_GOON, \a mginit will continue to
 * handle the event, and send it to the active client.
 * If the hook returns HOOK_STOP, \a mginit will cancel normal handling.
 *
 * \sa SetServerEventHook
 */
typedef int (* SRVEVTHOOK) (PMSG pMsg);

/**
 * \fn void GUIAPI SetServerEventHook (SRVEVTHOOK SrvEvtHook)
 * \brief Sets an event hook in the server of MiniGUI-Lite.
 *
 * This function sets the event hook as \a SrvEvtHook in the server, 
 * i.e. mginit, of MiniGUI-Lite.
 *
 * \param SrvEvtHook The pointer to the hook, NULL to cancel the hook.
 *
 * \note Only defined for MiniGUI-Lite, and only can be used by the server.
 *
 * \sa SRVEVTHOOK
 */
SRVEVTHOOK GUIAPI SetServerEventHook (SRVEVTHOOK SrvEvtHook);
#endif

    /** @} end of msg_hook_fns */

    /** @} end of msg_fns */

    /** @} end of fns */

    /**
     * \defgroup styles Window styles
     * @{
     */

/**
 * \def WS_NONE
 * \brief None style.
 */
#define WS_NONE             0x00000000L

#define WS_OVERLAPPED       0x00000000L

/**
 * \def WS_ABSSCRPOS
 * \brief Create a main window whose position is based on absolute screen coordinates.
 */
#define WS_ABSSCRPOS        0x80000000L

/**
 * \def WS_CHILD
 * \brief Indicates the window is a child.
 */
#define WS_CHILD            0x40000000L

/* Clipping styles -- not supported so far */

/**
 * \def WS_VISIBLE
 * \brief Creates a window initially visible.
 */
#define WS_VISIBLE          0x08000000L

/**
 * \def WS_DISABLED
 * \brief Creates a window initially disabled.
 */
#define WS_DISABLED         0x04000000L

/* Main window states -- not supported so far */
#define WS_MINIMIZE         0x02000000L
#define WS_MAXIMIZE         0x01000000L

/**
 * \def WS_CAPTION
 * \brief Creates a main window with caption.
 */
#define WS_CAPTION          0x20000000L

/**
 * \def WS_SYSMENU
 * \brief Creates a main window with system menu.
 */
#define WS_SYSMENU          0x10000000L

#define WS_DLGFRAME         0x00800000L

/**