zhangzhaopeng
/
sdk-hwV1.3
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
sdk-hwV1.3/external/eyesee-mpp/dragonboard/include/V5CDRTP/minigui/minigui.h

3521 lines
104 KiB
C
Executable File
Raw Blame History

/**
* \file minigui.h
* \author Wei Yongming <vincent@minigui.org>
* \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 <http://www.gnu.org/licenses/>.
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
<http://www.minigui.com/en/about/licensing-policy/>.
\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 <stdio.h>
#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 <sys/types.h>
/**
* \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 <minigui/common.h>.
*
* \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 <minigui/common.h>.
*
* \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 <minigui/common.h>.
*
* \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 */
Reference in New Issue View Git Blame Copy Permalink