mywindows.h

libminigui-1.3.0.tar.gz。 miniGUI的库函数源代码！

/**
 * \file mywindows.h
 * \author Wei Yongming <[e-mail]>
 * \date 2002/01/06
 * 
 *  This file includes interfaces for MyWins module of MiniGUIExt library, 
 *  which provides some useful and convenient user interface functions.
 *
 \verbatim
    Copyright (C) 1998-2002 Wei Yongming.
    Copyright (C) 2002-2003 Feynman Software.

    This file is part of MiniGUI, a lightweight Graphics User Interface
    support library for real-time embedded Linux.

    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 2 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, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 \endverbatim
 */

/*
 * $Id: mywindows.h,v 1.3 2003/09/04 06:12:04 weiym Exp $
 *
 *             MiniGUI for Linux Version 1.3.x
 *             Copyright (C) 2002 ~ 2003 Feynman Software.
 *             Copyright (C) 1998 ~ 2002 Wei Yongming.
 */

#ifndef _MGUI_MYWINDOWS_H
    #define _MGUI_MYWINDOWS_H

#ifdef __cplusplus
extern "C" {
#endif  /* __cplusplus */

    /**
     * \addtogroup mgext_fns Interfaces of the MiniGUI extension library (libmgext)
     * @{
     */

    /**
     * \addtogroup mywins_fns Interfaces of MyWins module of MiniGUIExt library
     * @{
     */

    /**
     * \defgroup mywins_helpers Useful helpers
     *
     * This module defines some useful helpers, such as tool-tip window,
     * progress window, and so on.
     *
     * @{
     */

/**
 * \fn int myMessageBox (HWND hwnd, DWORD dwStyle, char* title, char* text, ...)
 * \brief Creates a message box.
 *
 * This function creates a message box calling \a MessageBox and passing
 * \a hwnd, \a dwStyle and \a title to it. This function also receives \a printf-like
 * arguments to format a string.
 *
 * \param hwnd The hosting main window.
 * \param dwStyle The style of the message box.
 * \param title The title of the message box.
 * \param text The format string.
 * \return Identifier of the button which close the message box.
 *
 * \sa MessageBox, printf(3)
 */
int myMessageBox (HWND hwnd, DWORD dwStyle, char* title, char* text, ...);

/**
 * \fn int myWinMessage (HWND hwnd, char* title, char* button1, char* text, ...)
 * \brief Creates a message box within only one button.
 *
 * This function creates a message box hosted to the main window \a hwnd,
 * displays a message and an application icon in the message box, and creates
 * a button which can be used to close the box. This function also 
 * receives \a printf-like arguments to format a string.
 *
 * This function can be used to display a information for the user.
 *
 * \param hwnd The hosting main window.
 * \param title The title of the message box.
 * \param button1 The text in the button.
 * \param text The format string.
 * \return 0: indicates the message box was closed by click the only button.
 *
 * \sa myWinChoice, printf(3)
 */
int myWinMessage (HWND hwnd, char* title, char* button1, char* text, ...);

/**
 * \fn int myWinChoice (HWND hwnd, char* title, char* button1, char* button2, char* text, ...)
 * \brief Creates a message box within two buttons.
 *
 * This function creates a message box hosted to the main window \a hwnd, 
 * displays a message and an application icon in the message box, and creates
 * two buttons in it. This function also receives \a printf-like arguments 
 * to format a string.
 *
 * This function can be used to prompt the user to choose one item between two items.
 *
 * \param hwnd The hosting main window.
 * \param title The title of the message box.
 * \param button1 The title of the first button.
 * \param button2 The title of the second button.
 * \param text The format string.
 * \return Either 0 or 1, indicates the message box was closed by 
 *         the first or second button.
 *
 * \sa myWinTernary, printf(3)
 */
int myWinChoice (HWND hwnd, char* title, char* button1, char* button2,
                       char* text, ...);

/**
 * \fn int myWinTernary (HWND hwnd, char* title, char* button1, char* button2, char* button3, char* text, ...)
 * \brief Creates a message box within three buttons.
 *
 * This function creates a message box hosted to the main window \a hwnd, 
 * displays a message and an application icon in the message box, and creates
 * three buttons in it. This function also receives \a printf-like arguments 
 * to format a string.
 *
 * This function can be used to prompt the user to choose one item among three choices.
 *
 * \param hwnd The hosting main window.
 * \param title The title of the message box.
 * \param button1 The title of the first button.
 * \param button2 The title of the second button.
 * \param button3 The title of the third button.
 * \param text The format string.
 * \return 0, 1, or 2, indicates the message box was closed by 
 *         the first, the second or the third button.
 *
 * \sa myWinChoice, printf(3)
 */
int myWinTernary (HWND hwnd, char* title, char* button1, char* button2,
                       char* button3, char* text, ...);

/**
 * \fn void errorWindow (HWND hwnd, char * str, char* title)
 * \brief A MiniGUI edition of \a perror.
 *
 * This function creates a message box by using \a myMessageBox, and display the
 * current system error message. You can consider it as an alternative of \a perror.
 *
 * \param hwnd The hosting main window.
 * \param str The string will be appeared before the system error message.
 * \param title The title of the message box.
 *
 * \sa myMessageBox, perror(3)
 */
void errorWindow (HWND hwnd, char * str, char* title);

/**
 * \fn HWND createStatusWin (HWND hParentWnd, int width, int height, char * title, char * text, ...)
 * \brief Creates a status main window.
 *
 * This function creates a status main window and returns the handle to it.
 * You can call \a destroyStatusWin to destroy it. This function also 
 * receives \a printf-like arguments to format a string.
 *
 * \param hParentWnd The hosting main window.
 * \param width The width of the status window. 
 * \param height The height of the status window. 
 * \param title The title of the status window.
 * \param text The format string.
 * \return The handle to the status window on success, HWND_INVALID on error.
 *
 * \sa destroyStatusWin
 */
HWND createStatusWin (HWND hParentWnd, int width, int height, 
                char * title, char * text, ...);

/**
 * \fn void destroyStatusWin (HWND hwnd)
 * \brief Destroies a status window.
 *
 * This function destroies the specified status window \a hwnd, which 
 * is returned by \a createStatusWin.
 *
 * \param hwnd The handle to the status window.
 * 
 * \sa createStatusWin
 */
void destroyStatusWin (HWND hwnd);

/**
 * \fn HWND createToolTipWin (HWND hParentWnd, int x, int y, int timeout_ms, const char * text, ...)
 * \brief Creates a tool tip window.
 *
 * This function creates a tool tip window and returns the handle to it.
 * You can call \a destroyToolTipWin to destroy it. This function also 
 * receives \a printf-like arguments to format a string. 
 *
 * Note that the tool tip window will disappear automatically after the specified 
 * milliseconds by \a timeout_ms if \a timeout_ms is larger than 9 ms.
 *
 * \param hParentWnd The hosting main window.
 * \param x x,y: The position of the tool tip window.
 * \param y x,y: The position of the tool tip window.
 * \param timeout_ms The timeout value of the tool tip window. 
 * \param text The format string.