minigui.h

这是ARM嵌入式系统的实验教程中的MINIGUI的实验源代码！

 */
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-Lite 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-Lite application can call this function to create a 
 * listening socket. The server, i.e. \a mginit, of MiniGUI-Lite 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.
 */
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
 */
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.
 * 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
 */
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-Lite, i.e. \a mginit. 
 *
 * \sa sock_read_t
 */
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-Lite, i.e. \a mginit. 
 *
 * \sa sock_write_t
 */
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 /* !_STAND_ALONE */
#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 hello_world.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)

/*
 * We remove the SuspendGUI and ResumeGUI functions. 
 * Don't use these two functios any more.
 * void GUIAPI SuspendGUI (void);
 * BOOL GUIAPI ResumeGUI (void); 
 */

/**
 * \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 does not return.
 *
 * \sa exit(3)
 */
MG_EXPORT void GUIAPI ExitGUISafely (int exitcode);

/**
 * \def int MiniGUIMain (int args, const char* arg[])
 * \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 arg The arguments passed to \a main() by operating system.
 * \return The exit status will be retured to the parent process.
 *
 */

#ifdef _USE_MINIGUIENTRY
  #define main_entry minigui_entry
  int minigui_entry (int args, const char* arg[]);
#else
  #define main_entry main
#endif

#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

#define IDM_DTI_FIRST   (300)

#ifndef _LITE_VERSION
/*
 * NOTE: The following two functions is only valid for MiniGUI-Threads
 * since version 1.0.01.
 */
MG_EXPORT typedef void GUIAPI (*CustomizeDesktopMenuFunc) (HMENU hDesktopMenu, int iPos);
MG_EXPORT typedef int GUIAPI (*CustomDesktopCommandFunc) (int id);

extern CustomizeDesktopMenuFunc CustomizeDesktopMenu;
extern CustomDesktopCommandFunc CustomDesktopCommand;
#endif

    /** @} end of init_fns */

    /**
     * \defgroup mouse_calibrate Mouse calibration.
     * @{
     */

#ifdef _MISC_MOUSECALIBRATE

/**
 * \fn BOOL 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 disired 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 _MISC_MOUSECALIBRATE (option: --enable-mousecalibrate) defined.
 */
MG_EXPORT BOOL GUIAPI SetMouseCalibrationParameters (const POINT* src_pts, const POINT* dst_pts);

#endif /* _MISC_MOUSECALIBRATE */

    /** @} end of mouse_calibrate */

    /**
     * \defgroup about_dlg About MiniGUI dialog
     * @{
     */
#ifdef _MISC_ABOUTDLG
#ifndef _LITE_VERSION
  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-Lite and when _MISC_ABOUTDLG defined.
 * For MiniGUI-Threads, you should call 'void GUIAPI OpenAboutDialog (void)' function
 * instead.
 */
  HWND GUIAPI OpenAboutDialog (HWND hHosting);
#endif /* _LITE_VERSION */
#endif /* _MISC_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
     *
     * @{
     */