/** * \file minigui.h * \author Wei Yongming * \date 2002/01/06 * * \brief This file includes global and miscellaneous interfaces of MiniGUI. * \verbatim This file is part of MiniGUI, a mature cross-platform windowing and Graphics User Interface (GUI) support system for embedded systems and smart IoT devices. Copyright (C) 2002~2018, Beijing FMSoft Technologies Co., Ltd. Copyright (C) 1998~2002, WEI Yongming This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Or, As this program is a library, any link to this program must follow GNU General Public License version 3 (GPLv3). If you cannot accept GPLv3, you need to be licensed from FMSoft. If you have got a commercial license of this program, please use it under the terms and conditions of the commercial license. For more information about the commercial license, please refer to . \endverbatim */ /* * $Id: minigui.h 13674 2010-12-06 06:45:01Z wanzheng $ * * MiniGUI for Linux/uClinux, eCos, uC/OS-II, VxWorks, * pSOS, ThreadX, NuCleus, OSE, and Win32. */ #ifndef _MGUI_MINIGUI_H #define _MGUI_MINIGUI_H #include #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** * \addtogroup global_vars Global variables * @{ */ /** * \defgroup rect_vars Global Rectangles * @{ */ /** * \var RECT g_rcScr * \brief Contains the rectangle of the whole screen. */ extern MG_EXPORT RECT g_rcScr; /** * \def g_rcDesktop * \brief Contains the rectangle of desktop of the application. * * \a g_rcDesktop is defined as an alias (macro) of \a g_rcScr. * * \sa g_rcScr */ #define g_rcDesktop g_rcScr /** @} end of rect_vars */ /** * \defgroup lite_vars MiniGUI-Processes specific variables * @{ */ #ifdef _MGRM_PROCESSES #include /** * \var BOOL mgIsServer * \brief Indicates whether the process is the server or a client on * MiniGUI-Processes. * * \note Only defined for MiniGUI-Processes. */ extern MG_EXPORT BOOL mgIsServer; /** * \var void* mgSharedRes * \brief Contains the pointer to the shared resource of MiniGUI-Processes. * * \note Not defined for MiniGUI-Threads, and the shared resource is * read-only for all clients. * * \sa mgSizeRes */ extern MG_EXPORT void* mgSharedRes; /** * \var void* mgSizeRes * \brief Contains the length of shared resource of MiniGUI-Processes. * * \note Only defined for MiniGUI-Processes. * * \sa mgSharedRes */ extern MG_EXPORT size_t mgSizeRes; /** * \def LEN_LAYER_NAME * \brief The maximum length of name of layer in MiniGUI-Processes. **/ #define LEN_LAYER_NAME 14 /** * \def LEN_CLIENT_NAME * \brief The maximum length of name of client in MiniGUI-Processes. **/ #define LEN_CLIENT_NAME 14 /** * \def INV_LAYER_HANDLE * \brief Invalid handle value of the layer. **/ #define INV_LAYER_HANDLE 0 struct _MG_Layer; /** Client information. */ typedef struct _MG_Client { /** The name of the client. */ char name [LEN_CLIENT_NAME + 1]; /** PID of the client process. */ pid_t pid; /** UID of the client process. */ uid_t uid; /** The file descriptor of the socket connected to the client. */ int fd; /** Flag indicate whether this client has dirty windows. */ BOOL has_dirty; /** The last active tick count of the client. */ DWORD last_live_time; /** The additional data of the client. */ DWORD dwAddData; /** The pointer to the next client in the same layer. */ struct _MG_Client* next; /** The pointer to the previous client in the same layer. */ struct _MG_Client* prev; /** The pointer to the layer on which the client lays. */ struct _MG_Layer* layer; /** The pointer to the global resoures of the client. */ struct GlobalRes* global_res; } MG_Client; /** Layer information. */ typedef struct _MG_Layer { /** The name of the layer. */ char name [LEN_LAYER_NAME + 1]; /** The pointer to the active client on the layer. */ DWORD dwAddData; /** The pointer to the list of clients in the layer. */ MG_Client* cli_head; /** The pointer to the active client on the layer. */ MG_Client* cli_active; /** The pointer to the next layer. */ struct _MG_Layer* next; /** The pointer to the previous layer. */ struct _MG_Layer* prev; /** Internal field. */ void* zorder_info; /** Internal field. */ int zorder_shmid; } MG_Layer; /*screen attr type*/ #define SCREEN_ATTR_ALPHA_CHANNEL 0x01 //alpha channel #define SCREEN_ATTR_COLORKEY 0x02 //colorkey #define SCREEN_ATTR_COLORSPACE 0x03 //colorspace #define SCREEN_ATTR_ALPHA 0x04 #define SCREEN_NO_EXIST -99 //screen don't exist /** * \var int mgClientSize * \brief The current size of the array \a mgClients. * * \sa mgClients */ extern MG_EXPORT int mgClientSize; /** * \var MG_Client* mgClients * \brief The pointer to the array contains all clients' information. * * You can access the elements in \a mgClients as a normal array. If the * field \a fd of one element is not less than zero, then the element * will be a vaild client. * * \sa MG_Client */ extern MG_EXPORT MG_Client* mgClients; /** * \var MG_Layer* mgTopmostLayer * \brief The pointer to the topmost layer. * * \sa MG_Layer */ extern MG_EXPORT MG_Layer* mgTopmostLayer; /** * \var MG_Layer* mgLayers * \brief The pointer to the array of layers. * * \sa MG_Layer */ extern MG_EXPORT MG_Layer* mgLayers; #endif /* _MGRM_PROCESSES */ /** @} end of lite_vars */ /** @} end of global_vars */ /** * \fn int GUIAPI InitGUI (int, const char **) * \brief Initialize MiniGUI. * * The meaning of two parameters is same with parameters of main function. * **/ MG_EXPORT int GUIAPI InitGUI (int, const char **); /** * \fn void GUIAPI TerminateGUI (int not_used) * \brief Terminate MiniGUI. * * \param not_used not used * **/ MG_EXPORT void GUIAPI TerminateGUI (int not_used); /** * \fn void GUIAPI MiniGUIPanic (int exitcode) * \brief The panic of MiniGUI application. * * The function forces to close GAL and IAL engine. * * \param exitcode The value of exitcode, now it can be any values. * **/ MG_EXPORT void GUIAPI MiniGUIPanic (int exitcode); /** * \addtogroup fns Functions * @{ */ /** * \addtogroup global_fns Global/general functions * @{ */ /** * \defgroup lite_fns MiniGUI-Processes specific functions * @{ */ #ifndef _MGRM_THREADS /** * \defgroup lite_listenfd_fns Listening a file descriptor * * Register/Unregister a listen fd to MiniGUI. * * When you need to listen a file descriptor, you can use \a select(2) * system call. In MiniGUI, you can also register it to MiniGUI to * be a listened fd, and when there is a read/write/except event on * the registered fd , MiniGUI will sent a notification message to * the registered window. * * Example: * * \include listenfd.c * * @{ */ /** * \def MAX_NR_LISTEN_FD * \brief The max number of listen fd which user can use. **/ #define MAX_NR_LISTEN_FD 5 #ifdef WIN32 #ifndef POLLIN #define POLLIN 0x001 #endif #ifndef POLLOUT #define POLLOUT 0x004 #endif #ifndef POLLERR #define POLLERR 0x008 #endif #endif /** * \fn BOOL GUIAPI RegisterListenFD (int fd, int type,\ HWND hwnd, void* context) * \brief Registers a listening file descriptor to MiniGUI-Lite. * * This function registers the file desciptor \a fd to MiniGUI-Lite for * listening. * * When there is a read/write/except event on this \a fd, MiniGUI * will post a MSG_FDEVENT message with wParam being equal to * MAKELONG (fd, type), and the lParam being set to \a context * to the target window \a hwnd. * * \param fd The file descriptor to be listened. * \param type The type of the event to be listened, can be POLLIN, POLLOUT, * or POLLERR. * \param hwnd The handle to the window will receive MSG_FDEVENT message. * \param context The value will be passed to the window as lParam of * MSG_FDEVENT message. * * \return TRUE if all OK, and FALSE on error. * * \note Only available on MiniGUI-Processes. * * \sa UnregisterListenFD, system_msgs */ MG_EXPORT BOOL GUIAPI RegisterListenFD (int fd, int type, HWND hwnd, void* context); /** * \fn BOOL GUIAPI UnregisterListenFD (int fd) * \brief Unregisters a being listened file descriptor. * * This function unregisters the being listened file descriptor \a fd. * * \param fd The file descriptor to be unregistered, should be a being * listened file descriptor. * \return TRUE if all OK, and FALSE on error. * * \note Only available on MiniGUI-Processes. * * \sa RegisterListenFD */ MG_EXPORT BOOL GUIAPI UnregisterListenFD (int fd); /** @} end of lite_listenfd_fns */ #ifdef _MGRM_PROCESSES /** * \defgroup lite_layer_fns Layer operations * * A client in MiniGUI-Processes can create a new layer or join * an existed layer. * * Example: * * \include client_startup.c * * @{ */ /** * \def NAME_SELF_LAYER * \brief The name of the self layer. **/ #define NAME_SELF_LAYER "" /** * \def NAME_TOPMOST_LAYER * \brief The name of the topmost layer. **/ #define NAME_TOPMOST_LAYER "" /** * \def NAME_DEF_LAYER * \brief The default name of the layer. **/ #define NAME_DEF_LAYER "mginit" /** * \fn GHANDLE GUIAPI JoinLayer (const char* layer_name,\ const char* client_name,\ int max_nr_topmosts, int max_nr_normals) * \brief Joins to a layer. * * This function should be called by clients before calling any other MiniGUI * functions. You can call \a GetLayerInfo to get the layer information. * If the layer to be joined does not exist, the server, i.e. \a mginit, will * try to create a new one. If you passed a NULL pointer or a null string for * \a layer_name, the client will join to the default layer. * * If the client want to create a new layer, you should specify the maximal * number of topmost frame objects (max_nr_topmosts) and the maximal number of * normal frame objects (max_nr_normals) in the new layer. Passing zero to * \a max_nr_topmosts and max_nr_normals will use the default values, and the default * values are specified by ServerStartup. * * Note that the server will create a default layer named "mginit". * * \param layer_name The name of the layer.You can use NAME_TOPMOST_LAYER to * specify the current topmost layer. * \param client_name The name of the client. * \param max_nr_topmosts The maximal number of topmost z-order nodes in * the new layer. * \param max_nr_normals The maximal number of normal z-order nodes in * the new layer. * * \return The handle to the layer on success, INV_LAYER_HANDLE on error. * * \note Only call this function in clients of MiniGUI-Processes. * * \sa GetLayerInfo, ServerStartup, ServerCreateLayer */ MG_EXPORT GHANDLE GUIAPI JoinLayer (const char* layer_name, const char* client_name, int max_nr_topmosts, int max_nr_normals); /** * \fn GHANDLE GUIAPI GetLayerInfo (const char* layer_name,\ int* nr_clients, BOOL* is_topmost, int* cli_active) * \brief Gets information of a layer by a client. * * You can get the information of a layer through this function. * The information will be returned through the pointer arguments * if the specific pointer is not NULL. * * \param layer_name The name of the layer. You can use NAME_SELF_LAYER to * specify the layer the calling client belongs to. * \param nr_clients The number of clients in the layer will be returned * through this pointer. * \param is_topmost A boolean which indicates whether the layer is the * topmost layer will be returned. * \param cli_active The identifier of the active client in the layer. * * \return Returns the handle to the layer on success, * INV_LAYER_HANDLE on error. * * \note Only call this function in clients of MiniGUI-Processes. * * \sa JoinLayer */ MG_EXPORT GHANDLE GUIAPI GetLayerInfo (const char* layer_name, int* nr_clients, BOOL* is_topmost, int* cli_active); /** * \fn BOOL GUIAPI SetTopmostLayer (BOOL handle_name,\ * GHANDLE handle, const char* name) * \brief Brings a layer to be the topmost one. * * This function brings the specified layer \a handle to be the topmost layer. * * \param handle_name The way specifing the layer; TRUE for handle of * the layer, FALSE for name. * \param handle The handle to the layer. * \param name The name of the layer. You can use NAME_SELF_LAYER to * specify the layer to which the calling client belongs. * * \return TRUE on success, otherwise FALSE. * * \note Only call this function in clients of MiniGUI-Processes. */ MG_EXPORT BOOL GUIAPI SetTopmostLayer (BOOL handle_name, GHANDLE handle, const char* name); /** * \fn BOOL GUIAPI DeleteLayer (BOOL handle_name,\ GHANDLE handle, const char* layer_name) * \brief Deletes a specific layer. * * \param handle_name The way specifing the layer; TRUE for handle of * the layer, FALSE for name. * \param handle The handle to the layer. * \param layer_name The name of the layer. You can use NAME_SELF_LAYER to * specify the layer to which the calling client belongs. * * \return TRUE for success, FALSE on error. * * \note Only call this function in clients of MiniGUI-Processes. * * \sa JoinLayer */ MG_EXPORT BOOL GUIAPI DeleteLayer (BOOL handle_name, GHANDLE handle, const char* layer_name); /** @} end of lite_layer_fns */ /** * \defgroup lite_server_fns Server-only operations * * MiniGUI provides some server-only functions for you to create a * customized server for MiniGUI-Processes, i.e. \a mginit. * * Example: * * \include server_startup.c * * @{ */ /** * \var typedef void (* ON_LOCK_CLIENT_REQ) (void) * \brief Type of client request lock callback. * * \sa OnTrylockClientReq, OnLockClientReq, OnUnlockClientReq */ typedef int (* ON_LOCK_CLIENT_REQ) (void); /** * \var typedef void (* ON_TRYLOCK_CLIENT_REQ) (void) * \brief Type of client request lock callback. * * \sa OnTrylockClientReq, OnLockClientReq, OnUnlockClientReq */ typedef int (* ON_TRYLOCK_CLIENT_REQ) (void); /** * \var typedef void (* ON_UNLOCK_CLIENT_REQ) (void) * \brief Type of client request unlock callback. * * \sa OnTrylockClientReq, OnLockClientReq, OnUnlockClientReq */ typedef void (* ON_UNLOCK_CLIENT_REQ) (void); /** * \var ON_LOCK_CLIENT_REQ OnLockClientReq * \brief Sets to a function to lock a client request. * * \note Only available for the client of MiniGUI-Processes. * * \sa ON_LOCK_CLIENT_REQ */ extern MG_EXPORT ON_LOCK_CLIENT_REQ OnLockClientReq; /** * \var ON_TRYLOCK_CLIENT_REQ OnTrylockClientReq * \brief Sets to a function to lock a client request. * * \note Only available for the client of MiniGUI-Processes. * * \sa ON_TRYLOCK_CLIENT_REQ */ extern MG_EXPORT ON_TRYLOCK_CLIENT_REQ OnTrylockClientReq; /** * \var ON_UNLOCK_CLIENT_REQ OnUnlockClientReq * \brief Sets to a function to unlock a client request. * * \note Only available for the client of MiniGUI-Processes. * * \sa ON_UNLOCK_CLIENT_REQ */ extern MG_EXPORT ON_UNLOCK_CLIENT_REQ OnUnlockClientReq; #define LCO_NEW_CLIENT 1 #define LCO_DEL_CLIENT 2 /** * \var typedef void (* ON_NEW_DEL_CLIENT) (int op, int cli) * \brief Type of client event callback. * * \sa OnNewDelClient, OnChangeLayer */ typedef void (* ON_NEW_DEL_CLIENT) (int op, int cli); #define LCO_NEW_LAYER 1 #define LCO_DEL_LAYER 2 #define LCO_JOIN_CLIENT 3 #define LCO_REMOVE_CLIENT 4 #define LCO_TOPMOST_CHANGED 5 #define LCO_ACTIVE_CHANGED 6 /** * \var typedef void (* ON_CHANGE_LAYER) (int op, MG_Layer* layer, MG_Client* client) * \brief Type of layer change event callback. * * \sa OnNewDelClient, OnChangeLayer */ typedef void (* ON_CHANGE_LAYER) (int op, MG_Layer* layer, MG_Client* client); #define ZNOP_ALLOCATE 1 #define ZNOP_FREE 2 #define ZNOP_MOVE2TOP 3 #define ZNOP_SHOW 4 #define ZNOP_HIDE 5 #define ZNOP_MOVEWIN 6 #define ZNOP_SETACTIVE 7 #define ZNOP_ENABLEWINDOW 11 #define ZNOP_DISABLEWINDOW 12 #define ZNOP_STARTDRAG 13 #define ZNOP_CANCELDRAG 14 #define ZNOP_CHANGECAPTION 15 /** * \var typedef void (* ON_ZNODE_OPERATION) (int op, int cli, int idx_znode) * \brief Type of z-node operation callback. * * \sa OnNewDelClient, OnChangeLayer, OnZNodeOperation */ typedef void (* ON_ZNODE_OPERATION) (int op, int cli, int idx_znode); /** * \var ON_NEW_DEL_CLIENT OnNewDelClient * \brief Sets to a function to handle a comming in (going away) * connection of client. * * When a client is connecting to or disconnecting from the server, MiniGUI * will call this function to tell you the event and the client identifier. * The event could be one of the following: * * - LCO_NEW_CLIENT\n * A new client is connecting to the server. * - LCO_DEL_CLIENT\n * A new client is disconnecting from the server. * * The event will be passed through the argument of \a op, and the client * identifier will be passed through the argument of \a cli. * You can get the information of the client by accessing \a mgClients * with \a cli. * * \note Only available for the server of MiniGUI-Processes. * * \sa ON_NEW_DEL_CLIENT, mgClients */ extern MG_EXPORT ON_NEW_DEL_CLIENT OnNewDelClient; /** * \var ON_CHANGE_LAYER OnChangeLayer * \brief Sets to a function to handle events of layers. * * When a layer is changing, MiniGUI will call this function to tell * you the event and the layer or the client which leads to the event. * The event could be one of the following: * * - LCO_NEW_LAYER\n * A new layer is creating. * - LCO_DEL_LAYER\n * A new layer is deleting. * - LCO_JOIN_CLIENT\n * A client is joining to the layer. * - LCO_REMOVE_CLIENT\n * A client is removing from the layer. * - LCO_TOPMOST_CHANGED\n * The topmost layer changed, the layer will be the topmost one. * - LCO_ACTIVE_CHANGED\n * The active client changed, the client will be the active one. * * The event will be passed through the argument of \a op, and the * pointers to the relevant layer and client will be passed through * the argument of \a layer and \a client respectively. * * \note Only available for the server of MiniGUI-Processes. * * \sa ON_NEW_DEL_CLIENT, mgClients */ extern MG_EXPORT ON_CHANGE_LAYER OnChangeLayer; /** * \var ON_ZNODE_OPERATION OnZNodeOperation * \brief Sets to a function to handle events of z-node. * * After the server does an operation on a znode, MiniGUI will call * this function to tell you the event and the layer, the client, and * the z-node which leads to the event. * * The event could be one of the following: * * - ZNOP_ALLOCATE\n * The z-node has been created. * - ZNOP_FREE\n * The z-node has been destroyed. * - ZNOP_MOVE2TOP\n * The z-node has been moved to be the topmost one. * - ZNOP_SHOW\n * The z-node has been shown. * - ZNOP_HIDE\n * The z-node has been hidden. * - ZNOP_MOVEWIN\n * The z-node has been moved or its size has changed. * - ZNOP_SETACTIVE\n * The z-node has been set to be the active one. * - ZNOP_ENABLEWINDOW\n * The z-node is disabled or enabled. * - ZNOP_STARTDRAG\n * Start to drag the z-node. * - ZNOP_CANCELDRAG\n * Cancel to drag the z-node. * - ZNOP_CHANGECAPTION\n * The caption of the z-node has changed. * * The event will be passed through the argument of \a op; the * pointers to the layer, the identifier of the client, and the index of * the z-node will be passed through the argument of \a layer, \a cli, * and \a idx_znode respectively. * * \note Only available for the server of MiniGUI-Processes. * * \sa ON_ZNODE_OPERATION, ServerGetZNodeInfo, mgClients */ extern MG_EXPORT ON_ZNODE_OPERATION OnZNodeOperation; /** * \fn BOOL GUIAPI ServerStartup (int nr_globals,\ int def_nr_topmosts, int def_nr_normals) * \brief Initializes the server of MiniGUI-Processes. * * This function initializes the server, i.e. \a mginit. It creates the * shared resource, the listening socket, the default layer, and other * internal objects. Your costomized \a mginit program should call * this function before calling any other function. * * Note that the default layer created by the server called * "mginit" (NAME_DEF_LAYER). * * \param nr_globals The number of the global z-order nodes. All z-order nodes * created by mginit are global ones. * \param def_nr_topmosts The maximal number of the topmost z-order nodes in * the default layer. It is also the default number of topmost * z-order nodes of a new layer. * \param def_nr_normals The maximal number of normal global z-order nodes in * the new layer. It is also the default number of normal * z-order nodes of a new layer. * * \return TRUE on success, otherwise FALSE. * * \note Server-only function, i.e. \em only can be called by \a mginit. */ MG_EXPORT BOOL GUIAPI ServerStartup (int nr_globals, int def_nr_topmosts, int def_nr_normals); /** * \fn MG_Layer* GUIAPI ServerCreateLayer (const char* layer_name,\ int max_nr_topmosts, int max_nr_normals) * \brief Create a new layer from the server. * * This function creates a new layer named by \a layer_name. * You should specify the maximal number of topmost frame * objects (max_nr_topmosts) and the maximal number of normal frame * objects (max_nr_normals) in the new layer. Passing zero to * max_nr_topmosts and max_nr_normals will use the default values, * and the default values are specified by ServerStartup. * * Note that the server will create a default layer named "mginit". * * \param layer_name The name of the layer. If there is already a layer * named \a layer_name, the function will return the pointer to the layer. * \param max_nr_topmosts The maximal number of topmost z-order nodes in * the new layer. * \param max_nr_normals The maximal number of normal z-order nodes in * the new layer. * * \return The handle to the layer on success, NULL on error. * * \note Only call this function in the server of MiniGUI-Processes. * * \sa ServerDeleteLayer, ServerStartup */ MG_EXPORT MG_Layer* GUIAPI ServerCreateLayer (const char* layer_name, int max_nr_topmosts, int max_nr_normals); /** * \fn BOOL GUIAPI ServerSetTopmostLayer (MG_Layer* layer) * \brief Sets topmost layer from the server. * * This functions sets the specified layer \a layer to be the topmost layer. * * \param layer The pointer to the layer. * * \return TRUE on success, otherwise FALSE. * * \note Server-only function. * * \sa SetTopmostClient, SetTopmostLayer */ MG_EXPORT BOOL GUIAPI ServerSetTopmostLayer (MG_Layer* layer); /** * \fn BOOL GUIAPI ServerDeleteLayer (MG_Layer* layer) * \brief Delete a layer from the server. * * This functions deletes the specified layer \a layer. * * \param layer The pointer to the layer. * * \return TRUE on success, otherwise FALSE. * * \note Server-only function. * * \sa ServerCreateLayer, JoinLayer, DeleteLayer */ MG_EXPORT BOOL GUIAPI ServerDeleteLayer (MG_Layer* layer); /** * \fn int GUIAPI ServerGetNextZNode (MG_Layer* layer, int idx_znode, \ * int* cli) * \brief Get the next z-node in the specified layer from the server. * * This functions gets the next z-node in the specified layer \a layer from * the server. * * \param layer The pointer to the layer, NULL for the current topmost layer. * \param idx_znode The initial z-node. If the initial z-node index is * less than or equal to zero, the function will return * the index of the first z-node in the layer. * \param cli The client identifier of the next znode will be returned * through this pointer. NULL is okay. * * \return The index of the next z-node. Zero when the next z-node is * the last one; < 0 when error; * * \note Server-only function. Note that this function will not return * the z-node of the desktop, and the desktop always has the index * of z-node zero. * * \sa ServerGetZNodeInfo */ MG_EXPORT int GUIAPI ServerGetNextZNode (MG_Layer* layer, int idx_znode, int* cli); #define ZNIT_DESKTOP 0x50000000 #define ZNIT_GLOBAL_MAINWIN 0x31000000 #define ZNIT_GLOBAL_TOOLWIN 0x32000000 #define ZNIT_GLOBAL_CONTROL 0x30000000 #define ZNIT_TOPMOST_MAINWIN 0x21000000 #define ZNIT_TOPMOST_TOOLWIN 0x22000000 #define ZNIT_TOPMOST_CONTROL 0x20000000 #define ZNIT_NORMAL_MAINWIN 0x11000000 #define ZNIT_NORMAL_TOOLWIN 0x12000000 #define ZNIT_NORMAL_CONTROL 0x10000000 #define ZNIT_NULL 0x00000000 #define ZNIF_VISIBLE 0x00000002 #define ZNIF_DISABLED 0x00000004 /** Z-node information structure */ typedef struct _ZNODEINFO { /** * The type of the znode, can be one of the following values: * - ZNIT_GLOBAL_MAINWIN\n * a global main window. * - ZNIT_GLOBAL_TOOLWIN\n * a global tool window. * - ZNIT_GLOBAL_CONTROL\n * a global control with WS_EX_CTRLASMAINWIN style. * - ZNIT_TOPMOST_MAINWIN\n * a topmost main window. * - ZNIT_TOPMOST_TOOLWIN\n * a topmost tool window. * - ZNIT_TOPMOST_CONTROL\n * a topmost control with WS_EX_CTRLASMAINWIN style. * - ZNIT_NORMAL_MAINWIN\n * a normal main window. * - ZNIT_NORMAL_TOOLWIN\n * a normal tool window. * - ZNIT_NORMAL_CONTROL\n * a normal control with WS_EX_CTRLASMAINWIN style. * - ZNIT_DESKTOP\n * the desktop. * - ZNIT_NULL\n * a null and not-used z-node which does not refer to any window. */ DWORD type; /** * The flags of the znode, can be OR'd with the following values: * - ZNIF_VISIBLE\n * a visible window. * - ZNIF_DISABLED\n * a disabled window. * Note that the flags are only applied to window. */ DWORD flags; /** The pointer to the caption string of the znode if it is a window. */ const char* caption; /** The rectangle of the znode in the screen. */ RECT rc; /** Client id of the znode. */ int cli; /** The window handle of the znode if it is a window. */ HWND hwnd; /** * The window handle of the znode's main window if it is a control * with WS_EX_CTRLASMAINWIN style. */ HWND main_win; } ZNODEINFO; /** * \fn BOOL GUIAPI ServerGetZNodeInfo (MG_Layer* layer, int idx_znode, \ * ZNODEINFO* znode_info) * \brief Get the z-node information in the specified layer from the server. * * This functions gets the z-node information in the specified layer \a layer * from the server. * * \param layer The pointer to the layer, NULL for the current topmost layer. * \param idx_znode The index of the znode. * \param znode_info The information of the requested znode will be returned * through this structure. * * \return TRUE on success, otherwise FALSE. * * \note Server-only function. * * \sa ServerGetNextZNode, ZNODEINFO */ MG_EXPORT BOOL GUIAPI ServerGetZNodeInfo (MG_Layer* layer, int idx_znode, ZNODEINFO* znode_info); /** * \fn BOOL GUIAPI ServerDoZNodeOperation (MG_Layer* layer, int idx_znode, \ * int op_code, void* op_data, BOOL notify) * \brief Does an operation on the z-node in the specified layer * from the server. * * This functions does an operation upon the z-node in the specified * layer \a layer from the server. * * \param layer The pointer to the layer, NULL for the current topmost layer. * \param idx_znode The index of the znode. * \param op_code The code of the operation, can be one of the following * values: * - ZNOP_MOVE2TOP\n * Move the znode to be the topmost one. * - ZNOP_SETACTIVE\n * Set the znode to be the active one. * Note that the operation can be applied only for a main window. * \param op_data The data of the operation, used to pass the data need by * the operation. For example, if the operation is moving the z-node, * \a op_data will be a pointer to a RECT structure, which contains * the new position and size of the znode. Not used currently, reserved * for future use. * \param notify Whether to notify the client about the change of the znode. * * \return TRUE on success, otherwise FALSE. * * \note Server-only function, and the operation can be applied only for * a main window. * * \sa ServerGetZNodeInfo */ MG_EXPORT BOOL GUIAPI ServerDoZNodeOperation (MG_Layer* layer, int idx_znode, int op_code, void* op_data, BOOL notify); /** * \fn int GUIAPI GetClientByPID (int pid) * \brief Returns the client identifier from PID of a client. * * This function gets the identifier of the sepcified client from the PID of it. * * \param pid The process ID of the client. * \return The client identifier on success, less than 0 on error. * * \note Server-only function. */ MG_EXPORT int GUIAPI GetClientByPID (int pid); /** * \fn BOOL GUIAPI SetTopmostClient (int cli) * \brief Sets topmost layer by a client identifier. * * This function sets the topmost layer by the specified client * identifier \a cli. It will bring the layer contains the client * to be the topmost one. * * \param cli The identifier of the client. * * \return TRUE on success, otherwise FALSE. * * \note Server-only function. * * \sa ServerSetTopmostLayer, SetTopmostLayer */ MG_EXPORT BOOL GUIAPI SetTopmostClient (int cli); /** * \fn void GUIAPI DisableClientsOutput (void) * \brief Disable all clients output. */ MG_EXPORT void GUIAPI DisableClientsOutput (void); /** * \fn void GUIAPI UpdateTopmostLayer (const RECT* dirty_rc) * \brief Update topmost layer. * * \param dirty_rc The refresh region. */ MG_EXPORT void GUIAPI UpdateTopmostLayer (const RECT* dirty_rc); /** @} end of lite_server_fns */ /** * \defgroup lite_request_fns Simple request/reply interfaces * * You can register a customized request handler to extend your server, * i.e. mginit, of MiniGUI-Processes. * * A request consists of an identifier and the data associated with * the request. The identifier is used by MiniGUI to determine which * handler should be called when a request arrives. When MiniGUI * finds one handler, it will call the handler and pass the socket * fd connected to the client, the data associated with the request, * and the length of the data. Eventually, the handler will sent the * reply to the client. * * After register a customized request handler in your server, you can call * \a ClientRequest function in the client to send a request to the server * and wait for the reply. On the other hand, the request handler in the * server will receive the request and call \a ServerSendReply to send the * reply to the client. In this way, you can create a simple IPC * (inter-process conmmunication) mechanism between clients and the server. * * Example: * * \include request.c * * @{ */ /** * \def MAX_SYS_REQID * \brief Maximal system reserved request identifier. * * \sa RegisterRequestHandler */ #define MAX_SYS_REQID 0x0020 /** * \def MAX_REQID * \brief Maximal request identifier. * * \sa RegisterRequestHandler */ #define MAX_REQID 0x0030 /** A request will be sent to the server of MiniGUI-Processes. */ typedef struct _REQUEST { /** The identifier of the type of the request. */ int id; /** The data will be sent to the server. */ const void* data; /** The length of the data. */ size_t len_data; } REQUEST; /** Data type of pointer to a REQUEST */ typedef REQUEST* PREQUEST; /** * \fn int ClientRequestEx (const REQUEST* request, const void* ex_data, int ex_data_len, void* result, int len_rslt) * \brief Sends a request to the server and wait reply. * * If \a result is NULL or \a len_rslt is zero, the function will return * immediately after sent the data to the server. * * \param request The pointer to REQUEST, which contains the data of * the request. * \param ex_data The pointer to extra data to be sent to the server. * \param ex_data_len The length of the extra data in bytes. * \param result The buffer receives the reply. * \param len_rslt The lenght of the buffer. * * \return Zero on success, no-zero on error. * * \note Only used by clients to send a request to the server of * MiniGUI-Processes. * * \sa ServerSendReply */ MG_EXPORT int GUIAPI ClientRequestEx (const REQUEST* request, const void* ex_data, int ex_data_len, void* result, int len_rslt); /** * \fn int ClientRequest (const REQUEST* request, void* result, int len_rslt) * \brief Sends a request to the server and wait reply. * * If \a result is NULL or \a len_rslt is zero, the function will return * immediately after sent the data to the server. * * This function is a simplified version of ClientRequestEx, i.e. * there is no extra data to be sent. * * \param request The pointer to REQUEST, which contains the data of * the request. * \param result The buffer receives the reply. * \param len_rslt The lenght of the buffer. * * \return Zero on success, no-zero on error. * * \note Only used by clients to send a request to the server of * MiniGUI-Processes. * * \sa ClientRequestEx, ServerSendReply */ static inline int ClientRequest (const REQUEST* request, void* result, int len_rslt) { return ClientRequestEx (request, NULL, 0, result, len_rslt); } /** * \fn int GUIAPI GetSockFD2Server (void) * \brief Gets the file descriptor of the socket connected to the server. * * This function returns the file descriptor of the socket connected * to the server, i.e. mginit. * * \return The file descriptor of the socket connected to the server. * * \note Only used by clients, no meaning for the server. */ MG_EXPORT int GUIAPI GetSockFD2Server (void); /** * \fn int GUIAPI ServerSendReply (int clifd, const void* reply, int len) * \brief Sends the reply to the client. * * This function sends a replay pointed to by \a reply which is * \a len bytes long to the client. * * \note Only used by the server to send the reply to the client. * This function typically called in your customized request handler. * * \param clifd The fd connected to the client. * \param reply The buffer contains the reply data. * \param len The length of the reply data in bytes. * \return Zero on success, no-zero on error. * * \sa ClientRequest, RegisterRequestHandler */ MG_EXPORT int GUIAPI ServerSendReply (int clifd, const void* reply, int len); /** * \var typedef int (* REQ_HANDLER)(int cli, int clifd, void* buff, size_t len) * \brief Request handler. * * \sa RegisterRequestHandler */ typedef int (* REQ_HANDLER) (int cli, int clifd, void* buff, size_t len); /** * \fn BOOL GUIAPI RegisterRequestHandler (int req_id, REQ_HANDLER your_handler) * \brief Registers a customize request handler. * * This function registers a request handler to the server, i.e. \a mginit. * * \param req_id The identifier of the customized request. * \param your_handler The handler of the request. * Being NULL to unregister the request handler. * * \return TRUE on success, FALSE on error. * * \note Only used by the server to register a request handler. * And the identifier should be larger than \a MAX_SYS_REQID and * less than or equal to \a MAX_REQID. * * \sa ClientRequest, ServerSendReply, MAX_SYS_REQID, MAX_REQID */ MG_EXPORT BOOL GUIAPI RegisterRequestHandler (int req_id, REQ_HANDLER your_handler); /** * \fn EQ_HANDLER GUIAPI GetRequestHandler (int req_id) * \brief Gets the request handler by request identifier. * * This function returns the request handler of the specified request * identifier \a req_id. * * \param req_id The request identifier. * * \return The handler on success, NULL on error. * * \note Only can be used by the server. * * \sa RegisterRequestHandler */ MG_EXPORT REQ_HANDLER GUIAPI GetRequestHandler (int req_id); /** @} end of lite_request_fns */ /** * \defgroup lite_socket_fns General socket operations * * MiniGUI-Processes uses UNIX domain socket to build the communication * between the server and the clients. * * You can also use the underlay interfaces which MiniGUI uses to create * your own UNIX domain socket. * * Example: * * \include socket.c * * @{ */ /** * \fn int serv_listen (const char* name) * \brief Creates a listen socket. * * This function is used by the server to create a listening socket. * Any MiniGUI-Processes application can call this function to create a * listening socket. The server, i.e. \a mginit, of MiniGUI-Processes uses * this function to create its listening socket, and named the socket * to '/var/tmp/minigui'. * * \param name The path name of the listening socket. * \return The file discriptor of the listening socket created, -1 on error. * * \note As a convention, you should located the socket in '/var/tmp/' * directory. */ MG_EXPORT int serv_listen (const char* name); /** * \fn int serv_accept (int listenfd, pid_t *pidptr, uid_t *uidptr) * \brief Waits for a client connection to arrive, and accept it. * * This function is used by the server to wait a connection and accept it. * * After creating a listening socket by calling \a serv_listen, you can * call this function to create a connection with a client. We also obtain * the client's PID and UID from the pathname that it must bind before * calling us. * * \param listenfd The fd of listen socket. * \param pidptr The client PID will be saved to this buffer when this * function returns. * \param uidptr The client UID will be saved to this buffer when this * function returns. * * \return The new connected fd if all OK, < 0 on error. * * \sa serv_listen, cli_conn */ MG_EXPORT int serv_accept (int listenfd, pid_t *pidptr, uid_t *uidptr); /** * \fn int cli_conn (const char* name, char project) * \brief Used by clients to connect to a server. * * This function is used by clients to connect to a server. * * The created socket will be located at the directory '/var/tmp', * and with name of '/var/tmp/xxxxx-c', where 'xxxxx' is the pid of client. * and 'c' is a character to distinguish different projects. * * Note that MiniGUI itself uses 'a' as the project character to * create socket between 'mginit' and clients. * * \param name The name of the well-known listen socket (created by server). * \param project A character to distinguish different projects * (Do \em NOT use 'a'). * \return The new connected fd if all OK, < 0 on error. * * \sa serv_listen, serv_accept */ MG_EXPORT int cli_conn (const char* name, char project); #define SOCKERR_IO -1 #define SOCKERR_CLOSED -2 #define SOCKERR_INVARG -3 #define SOCKERR_TIMEOUT -4 #define SOCKERR_OK 0 /** * \fn int sock_write_t (int fd, const void* buff,\ int count, unsigned int timeout) * \brief Writes data to socket. * * This function writes the data block pointed to by \a buff * which is \a count bytes long to the socket \a fd. * * \param fd The file descriptor of the socket. * \param buff The buffer contains the data. * \param count The length in bytes of the buffer. * \param timeout An upper bound on the amount of time elapsed before * \a sock_write_t returns. When it is zero, \a sock_write_t can * block indefinitely. The timeout value is in tick count, and * tick count of MiniGUI is in unit of 10 milliseconds. * \return SOCKERR_OK if all OK, < 0 on error. * * \retval SOCKERR_OK Read data successfully. * \retval SOCKERR_IO There are some I/O errors occurred. * \retval SOCKERR_CLOSED The socket has been closed by the peer. * \retval SOCKERR_INVARG You passed invalid arguments. * \retval SOCKERR_TIMEOUT Timeout. * * \note The \a timeout only goes into effect when this function called * by the server of MiniGUI-Processes, i.e. \a mginit. * * \sa sock_read_t */ MG_EXPORT int sock_write_t (int fd, const void* buff, int count, unsigned int timeout); /** * \fn int sock_read_t (int fd, void* buff, int count, unsigned int timeout) * \brief Reads data from socket. * * This function reads data which is \a count bytes long to the buffer \a buff * from the socket \a fd. * * \param fd The file descriptor of the socket. * \param buff The buffer used to save the data. * \param count The length in bytes of the buffer. * \param timeout An upper bound on the amount of time elapsed before * \a sock_read_t returns. When it is zero, \a sock_read_t can * block indefinitely. The timeout value is in the tick count of MiniGUI, * and tick count of MiniGUI is in unit of 10 milliseconds. * \return SOCKERR_OK if all OK, < 0 on error. * * \retval SOCKERR_OK Read data successfully. * \retval SOCKERR_IO There are some I/O errors occurred. * \retval SOCKERR_CLOSED The socket has been closed by the peer. * \retval SOCKERR_INVARG You passed invalid arguments. * \retval SOCKERR_TIMEOUT Timeout. * * \note The \a timeout only goes into effect when this function called * by the server of MiniGUI-Processes, i.e. \a mginit. * * \sa sock_write_t */ MG_EXPORT int sock_read_t (int fd, void* buff, int count, unsigned int timeout); /** * \def sock_write(fd, buff, count) * \brief The blocking version of \a sock_write_t function. * * \sa sock_write_t */ #define sock_write(fd, buff, count) sock_write_t(fd, buff, count, 0) /** * \def sock_read(fd, buff, count) * \brief The blocking version of \a sock_read_t function. * * \sa sock_read_t */ #define sock_read(fd, buff, count) sock_read_t(fd, buff, count, 0) /** @} end of lite_socket_fns */ /** @} end of lite_fns */ #endif /* _MGRM_PROCESSES */ #endif /* LITE_VERSION */ /** * \defgroup init_fns Initialization and termination functions * * Normally, the only entry of any MiniGUI application is \a MiniGUIMain. * The application will terminate when you call \a exit(3) or just * return from \a MiniGUIMain. * * Example 1: * * \include miniguimain.c * * Example 2: * * \include helloworld.c * * @{ */ /** * \fn BOOL GUIAPI ReinitDesktopEx (BOOL init_sys_text) * \brief Re-initializes the desktop. * * When you changed the charset or the background picture of the desktop, * you should call this function to re-initialize the local system text * (when \a init_sys_text is TRUE), the background picture, and the desktop * menu. * * \param init_sys_text Indicates whether to initialize the local system text. * * \return TRUE on success, otherwise FALSE. * * \sa ReinitDesktop */ MG_EXPORT BOOL GUIAPI ReinitDesktopEx (BOOL init_sys_text); /** * \def ReinitDesktop() * \brief Re-initializes the desktop including the local system text. * * \return TRUE on success, otherwise FALSE. * * \note This function defined as a macro calling \a ReinitDesktopEx with * \a init_sys_text set to TRUE. * * \sa ReinitDesktopEx */ #define ReinitDesktop() ReinitDesktopEx (TRUE) /** * \fn void GUIAPI ExitGUISafely (int exitcode) * \brief Exits your MiniGUI application safely. * * Calling this function will terminate your MiniGUI application. This * function will restore console attributes and call \a exit() function and * pass \a exitcode to it. * * \param exitcode The exit status will be passed to exit(3) function. * * \return This function will not return. * * \sa exit(3) */ MG_EXPORT void GUIAPI ExitGUISafely (int exitcode); #ifdef _USE_MINIGUIENTRY #define main_entry minigui_entry int minigui_entry (int args, const char* arg[]); #else #define main_entry main #endif /** * \def MiniGUIMain * \brief The main entry of a MiniGUI application. * * This function should be defined by your application. Before Version 1.6.1, * MiniGUI defines \a main() function in libminigui library for your * application, and call \a MiniGUIMain() in this \a main() function. * The \a main() defined by MiniGUI is responsible of initializing and * terminating MiniGUI. * * After version 1.6.1, MiniGUI defines MiniGUIMain as a macro. * * \param args The number of arguments passed to \a main() by operating system. * \param argv The arguments passed to \a main() by operating system. * * \return The exit status will be retured to the parent process. */ #define MiniGUIMain \ MiniGUIAppMain (int args, const char* argv[]); \ int main_entry (int args, const char* argv[]) \ { \ int iRet = 0; \ if (InitGUI (args, argv) != 0) { \ return 1; \ } \ iRet = MiniGUIAppMain (args, argv); \ TerminateGUI (iRet); \ return iRet; \ } \ int MiniGUIAppMain /** * \def IDM_DTI_FIRST * \brief The minimum interger value of command ID when user customize * desktop menu. **/ #define IDM_DTI_FIRST (300) /** Desktop operation set */ typedef struct _DESKTOPOPS { /** called when starting a new session, and return a context */ void* (*init) (void); /** called when terminating a seesion */ void (*deinit) (void* context); /** called when the desktop should be repainted */ void (*paint_desktop) (void* context, HDC dc_desktop, const RECT* inv_rc); /** the keyboard event handler for the desktop */ void (*keyboard_handler) (void* context, int message, WPARAM wParam, LPARAM lParam); /** the mouse event handler for the desktop */ void (*mouse_handler) (void* context, int message, WPARAM wParam, LPARAM lParam); /** the desktop menu customizer */ void (*customize_desktop_menu) (void* context, HMENU hmenu, int start_pos); /** the desktop menu command handler */ void (*desktop_menucmd_handler) (void* context, int id); } DESKTOPOPS; /** * \fn DESKTOPOPS* GUIAPI SetCustomDesktopOperationSet (DESKTOPOPS* usr_dsk_ops) * * \brief Set customer desktop operation set. * * \param usr_dsk_ops The pointer to user customer desktop operation set. * * \return Old desktop operation set. * * \code * static void* this_init(void) * { * ...... * } * * static void this_deinit(void* context) * { * ...... * } * * static void this_paint_desktop(void* context,\ * HDC dc_desktop, const RECT* inv_rc) * { * ...... * } * * static void this_keyboard_handler(void* context, int message,\ * WPARAM wParam, LPARAM lParam) * { * ...... * } * * static void this_mouse_handler(void* context, int message,\ * WPARAM wParam, LPARAM lParam) * { * ...... * } * * static void this_customize_desktop_menu (void* context,\ * HMENU hmnu, int start_pos) * { * ...... * } * * static void this_desktop_menucmd_handler (void* context, int id) * { * ...... * } * * static DESKTOPOPS this_dsk_ops = * { * this_init, * this_deinit, * this_paint_desktop, * this_keyboard_handler, * this_mouse_handler, * this_customize_desktop_menu, * this_desktop_menucmd_handler, * }; * * SetCustomDesktopOperationSet(&this_dsk_ops); * * \endcode * * \sa DESKTOPOPS * */ MG_EXPORT DESKTOPOPS* GUIAPI SetCustomDesktopOperationSet (DESKTOPOPS* usr_dsk_ops); /** * \fn void GUIAPI DesktopUpdateAllWindow (void) * * \brief Update all visible windows on the desktop. * * On MiniGUI-Processes update all the main windows of the client and desktop window, * and it only can be used by mginit on MiniGUI-Processes. * On MiniGUI-Threads and MiniGUI-Standalone update all visible windows and desktop window. * */ MG_EXPORT void GUIAPI DesktopUpdateAllWindow (void); /** @} end of init_fns */ /** * \defgroup mouse_calibrate Mouse calibration. * @{ */ #ifdef _MGHAVE_MOUSECALIBRATE /** * \fn BOOL GUIAPI SetMouseCalibrationParameters (const POINT* src_pts,\ const POINT* dst_pts) * \brief Sets the parameters for doing mouse calibration. * * This function set the parameters for doing mouse calibration. * You should pass five source points and five destination points. * * Normally, the points should be the upper-left, upper-right, lower-right, * lower-left, and center points on the touch panel. The source point is * the coordinates before calibrating, and the destination point is the * desired coordinates after calibrating. * * This function will try to evaluate a matrix to calibrate. If the points * are okay, MiniGUI will do the calibration after getting a point from the * underlay IAL engine. * * \param src_pts The pointer to an array of five source points. * \param dst_pts The pointer to an array of five destination points. * * \return TRUE for success, FALSE for bad arguments. * * \note This function is available when _MGHAVE_MOUSECALIBRATE * (option: --enable-mousecalibrate) defined. * \note Only call this function in MiniGUI-Standalone, MiniGUI-Threads, * and the server (mginit) of MiniGUI-Processes. The behavior of this * function will be undefined if you call it in a client of * MiniGUI-Processes. */ MG_EXPORT BOOL GUIAPI SetMouseCalibrationParameters (const POINT* src_pts, const POINT* dst_pts); /** * \fn void GUIAPI GetOriginalMousePosition (int* x, int* y) * \brief Gets the original mouse position. * * \param x The pointer used to return the x coordinate of original mouse * position. * \param y The pointer used to return the y coordinate of original mouse * position. * * \return none. * * \note This function is available when _MGHAVE_MOUSECALIBRATE * (option: --enable-mousecalibrate) defined. * * \note Only call this function in MiniGUI-Standalone, MiniGUI-Threads, * and the server (mginit) of MiniGUI-Processes. The behavior of this * function will be undefined if you call it in a client of * MiniGUI-Processes. */ MG_EXPORT void GUIAPI GetOriginalMousePosition (int* x, int* y); #endif /* _MGHAVE_MOUSECALIBRATE */ /** @} end of mouse_calibrate */ /** * \defgroup about_dlg About MiniGUI dialog * @{ */ #ifdef _MGMISC_ABOUTDLG #ifdef _MGRM_THREADS /** * \fn HWND GUIAPI OpenAboutDialog (void) * \brief Opens or actives the 'About MiniGUI' dialog. * * Calling this function will create a main window displaying * copyright and license information of MiniGUI. When the about dialog * is displaying, calling this function again will bring the dialog to be * the topmost main window, not create a new one. * * \return The handle to the about dialog box. * * \note This function is available for MiniGUI-Threads and when * _MGMISC_ABOUTDLG defined. For MiniGUI-Processes, you should * call 'void GUIAPI OpenAboutDialog (HWND hHosting)' function instead. */ MG_EXPORT void GUIAPI OpenAboutDialog (void); #else /** * \fn HWND GUIAPI OpenAboutDialog (HWND hHosting) * \brief Opens or actives the 'About MiniGUI' dialog. * * Calling this function will create a main window displaying * copyright and license information of MiniGUI. When the about dialog * is displaying, calling this function again will bring the dialog to be * the topmost main window, not create a new one. * * \param hHosting The hosting main window of the about dialog. * * \return The handle to the about dialog box. * * \note This function is available for MiniGUI-Processes and when * _MGMISC_ABOUTDLG defined. For MiniGUI-Threads, you should * call 'void GUIAPI OpenAboutDialog (void)' function instead. */ MG_EXPORT HWND GUIAPI OpenAboutDialog (HWND hHosting); #endif /* _MGRM_THREADS */ #endif /* _MGMISC_ABOUTDLG */ /** @} end of about_dlg */ /** * \defgroup etc_fns Configuration file operations * * The configuration file used by MiniGUI have a similiar format as * M$ Windows INI file, i.e. the file consists of sections, and * the section consists of key-value pairs, like this: * * \code * [system] * # GAL engine * gal_engine=fbcon * * # IAL engine * ial_engine=console * * mdev=/dev/mouse * mtype=PS2 * * [fbcon] * defaultmode=1024x768-16bpp * * [qvfb] * defaultmode=640x480-16bpp * display=0 * \endcode * * Assume that the configuration file named \a my.cfg, if you want get * the value of \a mdev in \a system section, you can call * \a GetValueFromEtcFile in the following way: * * \code * char buffer [51]; * * GetValueFromEtcFile ("my.cfg", "system", "mdev", buffer, 51); * \endcode * * Example: * * \include cfgfile.c * * @{ */ /** * \def ETC_MAXLINE * \brief The max line number of etc file. **/ #define ETC_MAXLINE 1024 /** * \def ETC_FILENOTFOUND * \brief No found etc file. **/ #define ETC_FILENOTFOUND -1 /** * \def ETC_SECTIONNOTFOUND * \brief No found section in etc file. **/ #define ETC_SECTIONNOTFOUND -2 /** * \def ETC_KEYNOTFOUND * \brief No found key in etc file. **/ #define ETC_KEYNOTFOUND -3 /** * \def ETC_TMPFILEFAILED * \brief Create tmpfile failed. **/ #define ETC_TMPFILEFAILED -4 /** * \def ETC_FILEIOFAILED * \brief IO operation failed to etc file. **/ #define ETC_FILEIOFAILED -5 /** * \def ETC_INTCONV * \brief Convert the value string to an integer failed. **/ #define ETC_INTCONV -6 /** * \def ETC_INVALIDOBJ * \brief Invalid object to etc file. **/ #define ETC_INVALIDOBJ -7 /** * \def ETC_READONLYOBJ * \brief Read only to etc file. **/ #define ETC_READONLYOBJ -8 /** * \def ETC_OK * \brief Operate success to etc file. **/ #define ETC_OK 0 /** Etc The current config section information */ typedef struct _ETCSECTION { /** Allocated number of keys */ int key_nr_alloc; /** Key number in the section */ int key_nr; /** Name of the section */ char *name; /** Array of keys */ char** keys; /** Array of values */ char** values; } ETCSECTION; /** Data type of pointer to a ETCSECTION */ typedef ETCSECTION* PETCSECTION; /** ETC_S The current config file information*/ typedef struct _ETC_S { /** Allocated number of sections */ int sect_nr_alloc; /** Number of sections */ int section_nr; /** Pointer to section arrays */ PETCSECTION sections; } ETC_S; #ifndef _MGINCORE_RES /** * \var char* ETCFILEPATH * \brief The path name of MiniGUI configuration file. * * By default, the configuration file of MiniGUI must be installed in /etc, * /usr/local/etc or your home directory. When you install it in your * home directory, the name should be ".MiniGUI.cfg". * * MiniGUI will try to use MiniGUI.cfg in the current directory, * \a ~/.MiniGUI.cfg, then \a /usr/local/etc/MiniGUI.cfg, and * \a /etc/MiniGUI.cfg last. * * If MiniGUI can not find any \a MiniGUI.cfg file, or find a bad * formated configure file, the initialzation of MiniGUI will be canceled. */ extern MG_EXPORT char ETCFILEPATH []; #endif /* _MGINCORE_RES */ /** * \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) */ MG_EXPORT 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) */ MG_EXPORT 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 */ MG_EXPORT int GUIAPI SetValueToEtcFile (const char* pEtcFile, const char* pSection, const char* pKey, char* pValue); /** * \fn int GUIAPI RemoveSectionInEtcFile (const char* pEtcFile,\ const char* pSection) * \brief Removes a section in an etc file. * * This function removes a section named \a pSection from the etc file * named \a pEtcFile. * * \param pEtcFile The name of the etc file. * \param pSection The name of the pSection; * * \return ETC_OK on success, < 0 on error. * * \retval ETC_OK Gets value successfullly. * \retval ETC_FILEIOFAILED File I/O operation error occurred. * \retval ETC_SECTIONNOTFOUND Can not find the specified section in the * etc object. * * \sa RemoveSectionInEtc */ MG_EXPORT int GUIAPI RemoveSectionInEtcFile (const char* pEtcFile, const char* pSection); /** * \fn int GUIAPI SaveSectionToEtcFile (const char* pEtcFile, \ PETCSECTION psect); * \brief Saves a section to an etc file. * * This function saves a section named \a psect to the etc file * named \a pEtcFile. * * \param pEtcFile The name of the etc file. * \param psect The name of the psect; * * \return ETC_OK on success, < 0 on error. * * \retval ETC_OK Gets value successfullly. * \retval ETC_FILEIOFAILED File I/O operation error occurred. * \retval ETC_SECTIONNOTFOUND Can not find the specified section in the * etc object. */ MG_EXPORT int GUIAPI SaveSectionToEtcFile (const char* pEtcFile, PETCSECTION psect); /** * \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. * If pEtcFile is NULL, the function will create an empty ETC object. * * \return Handle of the etc object on success, NULL on error. * * \sa UnloadEtcFile, GetValueFromEtc */ MG_EXPORT GHANDLE GUIAPI LoadEtcFile (const char * pEtcFile); /** * \fn int GUIAPI SaveEtcToFile (GHANDLE hEtc, const char* file_name); * \brief Saves an ETC object into a file. * * This function saves the etc object into the file named \a file_name; * * \param hEtc Handle to the etc object. * \param file_name The name of the target file. * * \return ETC_OK on success, 0 < on error. * * \retval ETC_OK Sets the etc object successfullly. * \retval ETC_INVALIDOBJ Invalid etc object. * \retval ETC_FILEIOFAILED File I/O operation error occurred. * * \sa LoadEtcFile */ MG_EXPORT int GUIAPI SaveEtcToFile (GHANDLE hEtc, const char* file_name); /** * \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 Returns 0 on success, -1 on error. * * \sa LoadEtcFile, GetValueFromEtc */ MG_EXPORT int GUIAPI UnloadEtcFile (GHANDLE hEtc); /** * \fn int 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 to 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. This function will set value * if the iLen is less than 1. * * \return ETC_OK on success, < 0 on error. * * \retval ETC_OK Gets value successfullly. * \retval ETC_INVALIDOBJ Invalid etc object. * \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_READONLYOBJ The etc object is read-only. * * \sa GetValueFromEtcFile, LoadEtcFile, UnloadEtcFile */ MG_EXPORT 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 */ MG_EXPORT 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. * * \sa SetValueToEtcFile, GetValueFromEtc */ #define SetValueToEtc(hEtc, pSection, pKey, pValue) \ GetValueFromEtc(hEtc, pSection, pKey, pValue, -1) /** * \fn GHANDLE GUIAPI FindSectionInEtc (GHANDLE hEtc,\ const char* pSection, BOOL bCreateNew) * \brief Finds/Creates a section from an etc object. * * This function look for a section named \a pSection from the etc object * \a hEtc. If there is no such section in the etc object and \a bCreateNew * is TRUE, the function will create an empty section. * * \param hEtc Handle to the etc object. * \param pSection The name of the section. * \param bCreateNew Indicate whether to create a new section. * * \return The handle to the section, 0 if not found or creatation failed. * * \sa GetValueFromEtcSec, GetIntValueFromEtcSec, SetValueInEtcSec */ MG_EXPORT GHANDLE GUIAPI FindSectionInEtc (GHANDLE hEtc, const char* pSection, BOOL bCreateNew); /** * \fn int GUIAPI GetValueFromEtcSec (GHANDLE hSect,\ const char* pKey, char* pValue, int iLen) * \brief Gets value from an etc section object. * * This function gets value from an etc section object, similar * to GetValueFromEtc. It gets the value of the key \a pKey in the * section \a hSect, and saves the value to the buffer pointed to * by \a pValue. * * \param hSect The handle to the section. * \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. This function will set value * if the iLen is less than 1. * * \return ETC_OK on success, < 0 on error. * * \retval ETC_OK Gets value successfullly. * \retval ETC_INVALIDOBJ Invalid etc object. * \retval ETC_KEYNOTFOUND Can not find the specified key in the section. * \retval ETC_READONLYOBJ The section object is read-only. * * \sa GetValueFromEtcFile, GetValueFromEtc, FindSectionInEtc */ MG_EXPORT int GUIAPI GetValueFromEtcSec (GHANDLE hSect, const char* pKey, char* pValue, int iLen); /** * \fn int GUIAPI GetIntValueFromEtcSec (GHANDLE hSect,\ const char* pKey, int* pValue) * \brief Gets an integer value from an etc section object. * * This function gets an integer value from an etc section object, * similar to GetIntValueFromEtc. It gets the value of the key \a pKey * in the section \a hSect, and saves the value to the buffer pointed to * by \a pValue. * * \param hSect The handle to the section. * \param pKey The key name of the value. * \param pValue The value will be saved in this buffer. * * \return ETC_OK on success, < 0 on error. * * \retval ETC_OK Gets value successfullly. * \retval ETC_INVALIDOBJ Invalid etc object. * \retval ETC_KEYNOTFOUND Can not find the specified key in the section. * \retval ETC_INTCONV Can not convert the value string to an integer. * * \sa GetValueFromEtcFile, GetValueFromEtc, FindSectionInEtc */ MG_EXPORT int GUIAPI GetIntValueFromEtcSec (GHANDLE hSect, const char* pKey, int* pValue); /** * \fn int GUIAPI SetValueToEtcSec (GHANDLE hSect,\ const char* pKey, char* pValue) * \brief Sets the value in the etc section object. * * This fuctions sets the value in the etc section object \a hSect, * somewhat similiar to SetValueToEtc \sa SetValueToEtc. * * \sa GetValueFromEtc, FindSectionInEtc */ MG_EXPORT int GUIAPI SetValueToEtcSec (GHANDLE hSect, const char* pKey, char* pValue); /** * \fn int GUIAPI RemoveSectionInEtc (GHANDLE hEtc, const char* pSection) * \brief Removes a section in etc object. * * This function removes a section named \a pSection from the etc object * \a hEtc. * * \param hEtc The handle to the etc object. * \param pSection The name of the pSection; * * \return ETC_OK on success, < 0 on error. * * \retval ETC_OK Gets value successfullly. * \retval ETC_INVALIDOBJ Invalid etc object. * \retval ETC_READONLYOBJ The etc object is read-only. * \retval ETC_SECTIONNOTFOUND Can not find the specified section in the * etc object. * * \sa RemoveSectionInEtcFile */ MG_EXPORT int GUIAPI RemoveSectionInEtc (GHANDLE hEtc, const char* pSection); /* global MiniGUI etc file object */ extern MG_EXPORT GHANDLE hMgEtc; /** * \fn static inline int GetMgEtcValue(const char* pSection,\ const char *pKey, char *pValue, int iLen) * \brief Gets value from MiniGUI configuration etc object * * This fuctions gets the value from MiniGUi configuration etc object, * somewhat similiar to GetValueFromEtcFile and GetValueFromEtc * \sa GetValueFromEtcFile \sa GetValueFromEtc. */ static inline int GetMgEtcValue(const char* pSection, const char *pKey, char *pValue, int iLen) { #ifndef _MGINCORE_RES if (!hMgEtc) return GetValueFromEtcFile (ETCFILEPATH, pSection, pKey, pValue, iLen); #endif return GetValueFromEtc (hMgEtc, pSection, pKey, pValue, iLen); } /** * \fn static inline int GetMgEtcIntValue (const char *pSection,\ const char* pKey, int *value) * \brief Gets integer value from MiniGUI configuration etc object * * This fuctions get integer value from MiniGUI configuration etc object * some what similiar to GetIntValueFromEtcFile and GetIntValueFromEtc * \sa GetIntValueFromEtcFile \sa GetIntValueFromEtc */ static inline int GetMgEtcIntValue (const char *pSection, const char* pKey, int *value) { #ifndef _MGINCORE_RES if (!hMgEtc) return GetIntValueFromEtcFile (ETCFILEPATH, pSection, pKey, value); #endif return GetIntValueFromEtc (hMgEtc, pSection, pKey, value); } /** @} end of etc_fns */ #ifdef _MGHAVE_CLIPBOARD /** * \addtogroup clipboard_fns ClipBoard Operations * @{ */ /** * \def LEN_CLIPBOARD_NAME * \brief The maximum length of the name of clipboard. **/ #define LEN_CLIPBOARD_NAME 15 /** * \def NR_CLIPBOARDS * \brief The maximum number of clipboard. **/ #define NR_CLIPBOARDS 4 /** * \def CBNAME_TEXT * \brief The default clipboard name of text control. **/ #define CBNAME_TEXT ("text") /** * \def CBERR_OK * \brief Operate clipboard success. * \sa CreateClipBoard **/ #define CBERR_OK 0 /** * \def CBERR_BADNAME * \brief Bad name to clipboard. * \sa CreateClipBoard **/ #define CBERR_BADNAME 1 /** * \def CBERR_NOMEM * \brief No enough memory to clipboard. * \sa CreateClipBoard **/ #define CBERR_NOMEM 2 /** * \def CBOP_NORMAL * \brief Overwrite operation to clipboard. **/ #define CBOP_NORMAL 0 /** * \def CBOP_APPEND * \brief Append the new data to clipboarda after the old data. **/ #define CBOP_APPEND 1 /** * \fn int GUIAPI CreateClipBoard (const char* cb_name, size_t size) * \brief Creates a new clipboard. * * This function creates a new clipboard with the name \a cb_name. * MiniGUI itself creates a clipboard for text copying/pasting * called CBNAME_TEXT. * * \param cb_name The name of the new clipboard. * \param size The size of the clipboard. * * \retval CBERR_OK The clipboard created. * \retval CBERR_BADNAME Duplicated clipboard name. * \retval CBERR_NOMEM No enough memory. * * \sa DestroyClipBoard */ MG_EXPORT int GUIAPI CreateClipBoard (const char* cb_name, size_t size); /** * \fn int GUIAPI DestroyClipBoard (const char* cb_name) * \brief Destroys a new clipboard. * * This function destroys a clipboard with the name \a cb_name. * * \param cb_name The name of the clipboard. * * \retval CBERR_OK The clipboard has been destroyed. * \retval CBERR_BADNAME Can not find the clipboard with the name. * * \sa CreateClipBoard */ MG_EXPORT int GUIAPI DestroyClipBoard (const char* cb_name); /** * \fn int GUIAPI SetClipBoardData (const char* cb_name,\ void* data, size_t n, int cbop) * \brief Sets the data of a clipboard. * * This function sets the data into the clipboard named \a cb_name. * * \param cb_name The name of the clipboard. * \param data The pointer to the data. * \param n The length of the data. * \param cbop Type of clipboard operations, can be one of * the following values: * - CBOP_NORMAL\n * Overwrite the old data. * - CBOP_APPEND\n * Append the new data after the old data. * * \retval CBERR_OK Success. * \retval CBERR_BADNAME Bad clipboard name. * \retval CBERR_NOMEM No enough memory. * * \sa GetClipBoardDataLen, GetClipBoardData */ MG_EXPORT int GUIAPI SetClipBoardData (const char* cb_name, void* data, size_t n, int cbop); /** * \fn size_t GUIAPI GetClipBoardDataLen (const char* cb_name) * \brief Gets the length of the data of a clipboard. * * This function gets the data length of the clipboard named \a cb_name. * * \param cb_name The name of the clipboard. * * \return The size of the data if success, otherwise zero. * * \sa GetClipBoardData */ MG_EXPORT size_t GUIAPI GetClipBoardDataLen (const char* cb_name); /** * \fn size_t GUIAPI GetClipBoardData (const char* cb_name,\ void* data, size_t n) * \brief Gets the data of a clipboard. * * This function gets the all data from the clipboard named \a cb_name. * * \param cb_name The name of the clipboard. * \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. * * \sa GetClipBoardByte */ MG_EXPORT 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 Gets a byte from a clipboard. * * This function gets a byte from the clipboard named \a cb_name. * * \param cb_name The name of the clipboard. * \param index The index of the byte. * \param byte The buffer saving the returned byte. * * \retval CBERR_OK Success. * \retval CBERR_BADNAME Bad clipboard name. * \retval CBERR_NOMEM The index is beyond the data in the clipboard. * * \sa GetClipBoardData */ MG_EXPORT int GUIAPI GetClipBoardByte (const char* cb_name, int index, unsigned char* byte); /** @} end of clipboard_fns */ #endif /* _MGHAVE_CLIPBOARD */ /** * \addtogroup misc_fns Miscellaneous functions * @{ */ /** * \fn void GUIAPI Ping (void) * \brief Makes a beep sound. * \sa Beep */ MG_EXPORT 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 or RTOS, the tone can not be played * correctly. * * \sa Ping */ MG_EXPORT 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. */ MG_EXPORT 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 */ MG_EXPORT char* GUIAPI FixStrAlloc (int len); /** * \fn char* GUIAPI FixStrDup (const char* str) * \brief Duplicates a length-fixed string. * * This function allocates a buffer from the length-fixed string heap * and copy the string \a str to the buffer. * * \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 str The pointer to the string will be duplicated. * * \return The pointer to the buffer on success, otherwise NULL. * * \sa FreeFixStr */ MG_EXPORT char* GUIAPI FixStrDup (const char* str); /** * \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 */ MG_EXPORT void GUIAPI FreeFixStr (char* str); /** @} end of fixed_str */ /** * \defgroup cursor_fns Cursor operations * @{ */ #ifndef _MGHAVE_CURSOR static inline void do_nothing (void) { return; } #endif #ifdef _MGHAVE_CURSOR /** * \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 */ MG_EXPORT 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 */ MG_EXPORT 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. */ MG_EXPORT HCURSOR GUIAPI CreateCursor (int xhotspot, int yhotspot, int w, int h, const BYTE* pANDBits, const BYTE* pXORBits, int colornum); /** * \fn HCURSOR GUIAPI CopyCursor (HCURSOR hcsr) * \brief Copies a cursor object. * * This function copies the specified cursor. * * \param hcsr Handle to the cursor to be copied. * * \return If the function succeeds, the return value is the * handle to the duplicate cursor. If the function fails, * the return value is 0. */ MG_EXPORT HCURSOR GUIAPI CopyCursor (HCURSOR hcsr); /** * \fn BOOL GUIAPI DestroyCursor (HCURSOR hcsr) * \brief Destroys 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. */ MG_EXPORT 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. */ MG_EXPORT 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. */ MG_EXPORT 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 /* _MGHAVE_CURSOR */ #define MAX_SYSCURSORINDEX 22 /* System cursor index. */ /** System arrow cursor index. */ #define IDC_ARROW 0 /** System beam cursor index. */ #define IDC_IBEAM 1 /** System pencil cursor index. */ #define IDC_PENCIL 2 /** System cross cursor index. */ #define IDC_CROSS 3 /** System move cursor index. */ #define IDC_MOVE 4 /** System size northwest to southeast cursor index. */ #define IDC_SIZENWSE 5 /** System size northeast to southwest cursor index. */ #define IDC_SIZENESW 6 /** System west to east cursor index. */ #define IDC_SIZEWE 7 /** System north to south cursor index. */ #define IDC_SIZENS 8 /** System up arrow cursor index. */ #define IDC_UPARROW 9 /** System none cursor index. */ #define IDC_NONE 10 /** System help cursor index. */ #define IDC_HELP 11 /** System busy cursor index. */ #define IDC_BUSY 12 /** System wait cursor index. */ #define IDC_WAIT 13 /** System right arrow cursor index. */ #define IDC_RARROW 14 /** System colomn cursor index. */ #define IDC_COLOMN 15 /** System row cursor index. */ #define IDC_ROW 16 /** System drag cursor index. */ #define IDC_DRAG 17 /** System nodrop cursor index. */ #define IDC_NODROP 18 /** System hand point cursor index. */ #define IDC_HAND_POINT 19 /** System hand select cursor index. */ #define IDC_HAND_SELECT 20 /** System horizontal split cursor index. */ #define IDC_SPLIT_HORZ 21 /** System vertical cursor index. */ #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. */ MG_EXPORT 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. */ MG_EXPORT 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 */ MG_EXPORT 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 (\a x,\a y). * * \param x The x-corrdinate of the expected poistion. * \param y The y-corrdinate of the expected poistion. * \return None. * * \sa GetCursorPos */ MG_EXPORT void GUIAPI SetCursorPos (int x, int y); #ifdef _MGHAVE_CURSOR /** * \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 the 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 */ MG_EXPORT 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 */ MG_EXPORT 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 /* _MGHAVE_CURSOR */ #ifdef _MGHAVE_CURSOR /** * \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. */ MG_EXPORT int GUIAPI ShowCursor (BOOL fShow); #else #define ShowCursor(fShow) (do_nothing(), 0) #endif /* _MGHAVE_CURSOR */ /** @} end of cursor_fns */ /** * \defgroup key_status Asynchronous key status functions * @{ */ /** * \fn BOOL GUIAPI GetKeyStatus (UINT uKey) * \brief Gets a key or a mouse button status. * * This function gets a key or a mouse button status, returns TRUE * when pressed, or FALSE when released. \a uKey indicates * the key or mouse button. For keys on keyboard, \a uKey should be * the scancode of the key, for mouse button, \a uKey should be one * value of the following: * * - SCANCODE_LEFTBUTTON\n * Left mouse button. * - SCANCODE_MIDDLBUTTON\n * Middle mouse button. * - SCANCODE_RIGHTBUTTON\n * Right mouse button. * * These constants and the scancodes of keys are defined in . * * \param uKey Indicates the key or mouse button. * * \return Returns TRUE when pressed, or FALSE when released. * * \sa GetShiftKeyStatus */ MG_EXPORT BOOL GUIAPI GetKeyStatus (UINT uKey); /** * \fn DWORD GUIAPI GetShiftKeyStatus (void) * \brief Gets status of the shift keys. * * This function gets ths status of the shift keys, the returned value * indicates the status of shift keys -- CapsLock, ScrollLock, NumLock, * Left Shift, Right Shift, Left Ctrl, Right Ctrl, Left Alt, and Right Alt. * You can use KS_* ORed with the status value to determine one shift key's * status: * * - KS_CAPSLOCK\n * Indicates that CapsLock is locked. * - KS_NUMLOCK\n * Indicates that NumLock is locked. * - KS_SCROLLLOCK\n * Indicates that ScrollLock is locked. * - KS_LEFTCTRL\n * Indicates that left Ctrl key is pressed. * - KS_RIGHTCTRL\n * Indicates that right Ctrl key is pressed. * - KS_CTRL\n * Indicates that either left or right Ctrl key is pressed. * - KS_LEFTALT\n * Indicates that left Alt key is pressed. * - KS_RIGHTALT\n * Indicates that right Alt key is pressed. * - KS_ALT\n * Indicates that either left or right Alt key is pressed. * - KS_LEFTSHIFT\n * Indicates that left Shift key is pressed. * - KS_RIGHTSHIFT\n * Indicates that right Shift key is pressed. * - KS_SHIFT\n * Indicates that either left or right Shift key is pressed. * * These constants are defined in . * * \return The status of the shift keys. * \sa key_defs */ MG_EXPORT DWORD GUIAPI GetShiftKeyStatus (void); /** * \fn void GUIAPI GetKeyboardState (BYTE* kbd_state) * \brief Gets status of all keys on keyboard. * * This function gets the status of all keys on keyboard. * * The scancodes of all keys are defined in . * * \param kbd_state The buffer returns the current status of all keys. * Note that the length of the buffer should be larger than * (MGUI_NR_KEYS + 1). * * \sa GetKeyStatus, MGUI_NR_KEYS */ MG_EXPORT void GUIAPI GetKeyboardState (BYTE* kbd_state); /** @} end of key_status */ /** * \defgroup sys_text Internationlization of system text * @{ */ /** * \def IDS_MGST_WINDOW * \brief The identifier of the window system text. */ #define IDS_MGST_WINDOW 0 /** * \def IDS_MGST_START * \brief The identifier of the start system text. */ #define IDS_MGST_START 1 /** * \def IDS_MGST_REFRESH * \brief The identifier of the refresh background system text. */ #define IDS_MGST_REFRESH 2 /** * \def IDS_MGST_CLOSEALLWIN * \brief The identifier of the close all windows system text. */ #define IDS_MGST_CLOSEALLWIN 3 /** * \def IDS_MGST_ENDSESSION * \brief The identifier of the end session system text. */ #define IDS_MGST_ENDSESSION 4 /** * \def IDS_MGST_OPERATIONS * \brief The identifier of the operations system text. */ #define IDS_MGST_OPERATIONS 5 /** * \def IDS_MGST_MINIMIZE * \brief The identifier of the minimize system text. */ #define IDS_MGST_MINIMIZE 6 /** * \def IDS_MGST_MAXIMIZE * \brief The identifier of the maximize system text. */ #define IDS_MGST_MAXIMIZE 7 /** * \def IDS_MGST_RESTORE * \brief The identifier of the restore system text. */ #define IDS_MGST_RESTORE 8 /** * \def IDS_MGST_CLOSE * \brief The identifier of the close system text. */ #define IDS_MGST_CLOSE 9 /** * \def IDS_MGST_OK * \brief The identifier of the ok system text. */ #define IDS_MGST_OK 10 /** * \def IDS_MGST_NEXT * \brief The identifier of the next system text. */ #define IDS_MGST_NEXT 11 /** * \def IDS_MGST_CANCEL * \brief The identifier of the cancel system text. */ #define IDS_MGST_CANCEL 12 /** * \def IDS_MGST_PREV * \brief The identifier of the previous system text. */ #define IDS_MGST_PREV 13 /** * \def IDS_MGST_YES * \brief The identifier of the yes system text. */ #define IDS_MGST_YES 14 /** * \def IDS_MGST_NO * \brief The identifier of the no system text. */ #define IDS_MGST_NO 15 /** * \def IDS_MGST_ABORT * \brief The identifier of the abort system text. */ #define IDS_MGST_ABORT 16 /** * \def IDS_MGST_RETRY * \brief The identifier of the retry system text. */ #define IDS_MGST_RETRY 17 /** * \def IDS_MGST_IGNORE * \brief The identifier of the ignore system text. */ #define IDS_MGST_IGNORE 18 /** * \def IDS_MGST_ABOUTMG * \brief The identifier of the about minigui system text. */ #define IDS_MGST_ABOUTMG 19 /** * \def IDS_MGST_OPENFILE * \brief The identifier of the open file system text. */ #define IDS_MGST_OPENFILE 20 /** * \def IDS_MGST_SAVEFILE * \brief The identifier of the save file system text. */ #define IDS_MGST_SAVEFILE 21 /** * \def IDS_MGST_COLORSEL * \brief The identifier of the color selection system text. */ #define IDS_MGST_COLORSEL 22 /** * \def IDS_MGST_SWITCHLAYER * \brief The identifier of the switch layer system text. */ #define IDS_MGST_SWITCHLAYER 23 /** * \def IDS_MGST_DELLAYER * \brief The identifier of the delete layer system text. */ #define IDS_MGST_DELLAYER 24 /** * \def IDS_MGST_ERROR * \brief The identifier of the error system text. */ #define IDS_MGST_ERROR 25 /** * \def IDS_MGST_LOGO * \brief The identifier of the logo system text. */ #define IDS_MGST_LOGO 26 /** * \def IDS_MGST_CURRPATH * \brief The identifier of the current path system text. */ #define IDS_MGST_CURRPATH 27 /** * \def IDS_MGST_FILE * \brief The identifier of the file system text. */ #define IDS_MGST_FILE 28 /** * \def IDS_MGST_LOCATION * \brief The identifier of the location system text. */ #define IDS_MGST_LOCATION 29 /** * \def IDS_MGST_UP * \brief The identifier of the up system text. */ #define IDS_MGST_UP 30 /** * \def IDS_MGST_NAME * \brief The identifier of the name system text. */ #define IDS_MGST_NAME 31 /** * \def IDS_MGST_SIZE * \brief The identifier of the size system text. */ #define IDS_MGST_SIZE 32 /** * \def IDS_MGST_ACCESSMODE * \brief The identifier of the access mode system text. */ #define IDS_MGST_ACCESSMODE 33 /** * \def IDS_MGST_LASTMODTIME * \brief The identifier of the last modify time system text. */ #define IDS_MGST_LASTMODTIME 34 /** * \def IDS_MGST_OPEN * \brief The identifier of the open system text. */ #define IDS_MGST_OPEN 35 /** * \def IDS_MGST_FILENAME * \brief The identifier of the file name system text. */ #define IDS_MGST_FILENAME 36 /** * \def IDS_MGST_FILETYPE * \brief The identifier of the file type system text. */ #define IDS_MGST_FILETYPE 37 /** * \def IDS_MGST_SHOWHIDEFILE * \brief The identifier of the show hide file system text. */ #define IDS_MGST_SHOWHIDEFILE 38 /** * \def IDS_MGST_NOTFOUND * \brief The identifier of the not found file system text. */ #define IDS_MGST_NOTFOUND 39 /** * \def IDS_MGST_NR * \brief The identifier of the can't read system text. */ #define IDS_MGST_NR 40 /** * \def IDS_MGST_NW * \brief The identifier of the can't write system text. */ #define IDS_MGST_NW 41 /** * \def IDS_MGST_INFO * \brief The identifier of the information system text. */ #define IDS_MGST_INFO 42 /** * \def IDS_MGST_R * \brief The identifier of the read system text. */ #define IDS_MGST_R 43 /** * \def IDS_MGST_W * \brief The identifier of the write system text. */ #define IDS_MGST_W 44 /** * \def IDS_MGST_WR * \brief The identifier of the read and write system text. */ #define IDS_MGST_WR 45 /** * \def IDS_MGST_SAVE * \brief The identifier of the save system text. */ #define IDS_MGST_SAVE 46 /** * \def IDS_MGST_FILEEXIST * \brief The identifier of the file exist system text. */ #define IDS_MGST_FILEEXIST 47 #define IDS_MGST_MAXNUM 47 /** * \fn const char* GUIAPI GetSysText (unsigned int id); * \brief Translates system text to localized text. * * When MiniGUI display some system messages, it will call \a GetSysText * function to translate system text from English to other language. * Global variable \a SysText contains all text used by MiniGUI in English. * * \a GetSysText function returns localized text from \a local_SysText. * MiniGUI have already defined localized sytem text for en_US, zh_CN.GB2312 * and zh_TW.Big5 locales. MiniGUI initializes \a local_SysText to * point one of above localized system text when startup. You can also * let \a local_SysText point to your customized string array. * * \param id The system text id. * \return The localized text. * * \sa SysText, local_SysText */ MG_EXPORT const char* GUIAPI GetSysText (unsigned int id); /** * \var const char* SysText [] * \brief Contains all text used by MiniGUI in English. * * System text defined as follows in MiniGUI: * * \code * const char* SysText [] = * { * "Windows...", * "Start...", * "Refresh Background", * "Close All Windows", * "End Session", * "Operations...", * "Minimize", * "Maximize", * "Restore", * "Close", * "OK", * "Next", * "Cancel", * "Previous", * "Yes", * "No", * "Abort", * "Retry", * "Ignore", * "About MiniGUI...", * "Open File", * "Save File", * "Color Selection", * "Switch Layer", * "Delete Layer", * "Error", * "LOGO", * "Current Path", * "File", * #if (!defined (__NOUNIX__) || defined (WIN32)) && defined (_MGCTRL_LISTVIEW) * "Location", * "Up", * "Name", * "Size", * "Access Mode", * "Last Modify Time", * "Open", * "File Name", * "File Type", * "Show Hide File", * "Sorry! not find %s ", * "Can't Read %s !", * "Can't Write %s !", * "Information", * "R", * "W", * "WR", * "Save", * "File %s exists, Replace or not?", * #endif * NULL * }; * \endcode * * \sa GetSysText, local_SysText */ extern MG_EXPORT const char* SysText []; /** * \var const char** local_SysText * \brief The pointer to the current localized system text array. * * Changing \a local_SysText will lead to \a GetSysText returns a different * localized system text. Please set it when MiniGUI starts * and send desktop a MSG_REINITSESSION message (call \a ReinitDesktop * function) after assigned a different value to this variable. * * \sa GetSysText, SysText, ReinitDesktopEx */ extern MG_EXPORT const char** local_SysText; #ifdef _MGCHARSET_UNICODE /** * \fn const char** GUIAPI GetSysTextInUTF8 (const char* language) * \brief Gets the localized system text array in UTF-8 for * a specified language. * * This function returns the localized system text array in UTF-8 encode * for the specified language. You can use the returned localized system * text array to set \a local_SysText if your system logical fonts are using * UNICODE/UTF-8 charset. * * \param language The language name. So far, you can specify the language * as 'zh_CN' (for simlified Chinese) * or 'zh_TW' (for tranditional Chinese). * * \return The pointer to the localized system text array. * * \sa SysText, local_SysText */ extern MG_EXPORT const char** GUIAPI GetSysTextInUTF8 (const char* language); #endif /* _MGCHARSET_UNICODE */ /** @} end of sys_text */ /** * \defgroup str_helpers String operation helpers * @{ */ /** * \fn char* strnchr (const char* s, size_t n, int c); * \brief Locates character in the first \a n characters of string \a s. * * \param s The pointer to the string. * \param n The number of first characters will be searched. * \param c The expected character. * * \return Returns a pointer to the first occurrence of the character \a c * in the string \a s. * * \sa strchr(3) */ MG_EXPORT char* strnchr (const char* s, size_t n, int c); /** * \fn int substrlen (const char* text, int len, int delimiter,\ int* nr_delim) * \brief Locates a substring delimited by one or more delimiters in the * first \a len characters of string \a text. * * \param text The pointer to the string. * \param len The number of first characters will be searched. * \param delimiter The delimiter which delimites the substring from other. * \param nr_delim The number of continuous delimiters will be returned * through this pointer. * * \return The length of the substring. * * \sa strstr(3) */ MG_EXPORT int substrlen (const char* text, int len, int delimiter, int* nr_delim); /** * \fn char* strtrimall (char* src); * \brief Deletes all space characters. * * This function deletes the blank space, form-feed('\\f'), newline('\\n'), * carriage return('\\r'), horizontal tab('\\t'),and vertical tab('\\v') * in the head and the tail of the string. * * \param src The pointer to the string. * * \return Returns a pointer to the string. */ MG_EXPORT char * strtrimall (char* src); /** @} end of str_helpers */ /** @} end of global_fns */ /** @} end of fns */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* _MGUI_MINIGUI_H */