egg.h

某国际贸易中心共有40层

/*****************************************************************************
  版权所有 (C) 2005-2005  Sun Zhigang  (http://egg.sunner.cn)

  该系统是自由软件；您可以按照自由软件基金会所公布的GNU通用公共许可证(GPL)进行
  修改或重新发布；许可证可以是第2版或更新的版本。

  发布该软件是希望它有用有益，但不提供任何形式的担保，不论是明确的还是隐含的，
  包括但不限于可销售和适合特定用途的隐含保证。详见GNU通用公共许可证: 

  http://www.gnu.org/copyleft/gpl.html

  $Id: egg.h,v 1.20 2005/11/02 03:47:49 sun Exp $ 
*****************************************************************************/

/**
 * \mainpage Easy Graphical egG 图形开发平台
 *
 * \section intro 简介
 * Easy Graphical egG (Egg) 是一个开放源代码的C语言函数库，采用GPL协议。它的设
 * 计目标是开发一个极其简单、直观的Win32平台下的图形动画库，C语言的初学者可以使
 * 用它开发动画、游戏等图形程序，让C语言的学习过程变得更有趣，更有成就感。
 * <p>关于Egg的详情，请浏览： http://egg.sunner.cn </p>
 * <p>更多文档，请访问： http://wiki.hit.edu.cn/index.php/Egg </p>
 * <p>Hosted by http://gf.cs.hit.edu.cn </p>
 */

#ifndef _EGG_SUNNER_HIT     //防止多次包含egg.h，造成冲突
#define _EGG_SUNNER_HIT

#include <windows.h>		//使用Win32 API
#include <limits.h>         //使用INT_MAX和INT_MIN

struct egg;

//////////////////////////////////////////////////////////////////////////
//
// 定义数据类型
//
//////////////////////////////////////////////////////////////////////////

/**
 * \ingroup EggAnimation
 * egg的句柄
 *
 * @see EggStart(), LayEgg()
 */
typedef struct egg* HEGG;

/**
 * \ingroup EggInput
 * 事件类型
 *
 * WaitForEvent的返回值类型，通过它判断都发生了什么事情（用户输入、定时器）
 */
typedef enum 
{
    EXIT,           /**< 窗口关闭事件。用户点窗口右上角的“x”按钮或按Alt+F4都会触发这个事件 */
    TIMER,          /**< 定时周期事件。参见 StartTimer() */
    MOUSEMOVE,      /**< 鼠标移动事件。鼠标在窗口内移动，就会触发这个事件。用 GetMouseX() 和 GetMouseY() 得到鼠标的坐标*/
    KEYDOWN,        /**< 按下按键事件。键盘或鼠标按键被按下时触发此事件。可用 GetStruckKey() 得知哪个键被按下 */
    KEYUP           /**< 抬起按键事件。键盘或鼠标按键被抬起时触发此事件。可用 GetStruckKey() 得知哪个键被抬起 */
} EVENT_TYPE;

//////////////////////////////////////////////////////////////////////////
//
// 定义宏
//
//////////////////////////////////////////////////////////////////////////

/**
 * \addtogroup EggAdvGraph
 * @{
 */
//!黑色
#define BLACK        RGB(0x00, 0x00, 0x00)
//!深蓝色
#define DARK_BLUE    RGB(0x00, 0x00, 0x80)
//!深绿色
#define DARK_GREEN   RGB(0x00, 0x80, 0x00)
//!深青色
#define DARK_CYAN    RGB(0x00, 0x80, 0x80)
//!深红色
#define DARK_RED     RGB(0x80, 0x00, 0x00)
//!深紫色
#define DARK_MAGENTA RGB(0x80, 0x00, 0x80)
//!深黄色
#define DARK_YELLOW  RGB(0x80, 0x80, 0x00)
//!浅灰色
#define LIGHT_GRAY   RGB(0xC0, 0xC0, 0xC0)
//!深灰色
#define DARK_GRAY    RGB(0x80, 0x80, 0x80)
//!蓝色
#define BLUE         RGB(0x00, 0x00, 0xFF)
//!绿色
#define GREEN        RGB(0x00, 0xFF, 0x00)
//!青色
#define CYAN         RGB(0x00, 0xFF, 0xFF)
//!红色
#define RED          RGB(0xFF, 0x00, 0x00)
//!紫色
#define MAGENTA      RGB(0xFF, 0x00, 0xFF)
//!黄色
#define YELLOW       RGB(0xFF, 0xFF, 0x00)
//!白色
#define WHITE        RGB(0xFF, 0xFF, 0xFF)
//!透明色，产生透明效果
#define TRANSPARENT_COLOR  RGB(0x00, 0x00, 0xC8)
//! @}

/**
 * \addtogroup EggAnimation 
 *  @{
 */

//!顶层
#define TOP         (INT_MAX)
//!底层
#define BOTTOM      (INT_MIN+1)

//! @}

//////////////////////////////////////////////////////////////////////////
//
// 函数原型声明
//
//////////////////////////////////////////////////////////////////////////

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \defgroup EggBasic 基本功能
 * 下列数据类型和函数实现了Egg最基本的功能。通过它们可以建立图形窗口（Egg平台称
 * 它为盘子），并能在其上绘制简单的图形和文字。
 * @{
 */

/** 
 * 开始使用Egg
 *
 * 建立并显示一个Egg图形窗口，称为“盘子”。盘子是方形的（-_-!），表面采用平面
 * 直角坐标系，左下角作为坐标原点(0,0)，单位厘米。可以使用Egg提供的其它函数在盘
 * 子内摆放egg，并在egg上绘画。
 * <P> <b>必须先调用此函数一次，且只能一次，才可以使用Egg的其它功能。</b>
 * <P>程序退出时，Egg占用的资源会被自动释放。
 *
 * @param fWidth 指定盘子宽度（厘米）
 * @param fHeight 指定盘子高度（厘米）
 */
void EggStart(double fWidth, double fHeight);

/**
 * 显示或隐藏终端窗口
 *
 * 终端窗口很难看，可以用此函数隐藏它。但可以从终端窗口读取用户输入，也可以在开
 * 发阶段向里面方便地输出调试信息，所以还有需要显示的时候。
 *
 * @param bShow 非0值，显示；0，隐藏
 */
void ShowConsoleWindow(int bShow);

/**
 * 移动画笔位置
 *
 * 改变画笔位置到参数指定的绝对坐标。
 *
 * @param x 新画笔位置的X轴坐标
 * @param y 新画笔位置的Y轴坐标
 */
void MovePen(double x, double y);

/**
 * 位移画笔位置
 *
 * 按参数指定的位移移动画笔位置。
 *
 * @param dx 在X轴的位移
 * @param dy 在Y轴的位移
 */
void OffsetPen(double dx, double dy);

/**
 * 得到画笔的X坐标
 *
 * 返回画笔当前的X坐标
 *
 * @return 画笔当前的X坐标
 */
double GetPenXPos(void);

/**
 * 得到画笔的Y坐标
 *
 * 返回画笔当前的Y坐标
 *
 * @return 画笔当前的Y坐标
 */
double GetPenYPos(void);

/**
 * 画直线
 *
 * 从当前画笔位置开始，向X轴方向位移dx厘米，向Y轴方向位移dy厘米，画一条直线。画
 * 线结束后，直线的终点被设为新的画笔位置。
 *
 * @param dx X轴方向的位移
 * @param dy Y轴方向的位移
 * @see MovePen()
 */
void DrawLine(double dx, double dy);

/**
 * 绘制字符串 
 *
 * 此函数使用当前颜色和字体，以画笔位置为左上角，沿水平方向绘制字符串。
 * 绘图完毕后画笔位置自动移动到字符串的右上角。
 *
 * @param pString 被绘制的字符串，以'\\0'为结束符
 */
void DrawString(char* pString);

/**
 * 得到字符串宽度
 *
 * 本函数返回pString用当前字体、字号显示到窗口内的宽度。
 *
 * @param pString 要计算的字符串
 * @return 宽度（厘米）
 * @see DrawString()
 */
double GetStringWidth(char* pString);

/**
 * 画曲线
 *
 * 从画笔当前位置开始，画一条以r为半径的正圆曲线。这段曲线在从所在圆的dStart角
 * 度开始，沿逆时针方向扫过dSweep度。
 *
 * @param r 半径
 * @param dStart 曲线开始角度
 * @param dSweep 曲线扫过的角度。正数表示沿逆时针方向，负数表示沿顺时针方向。
 * @see DrawEllipticalArc
 */
void DrawArc(double r, double dStart, double dSweep);

/**
 * 画椭圆曲线
 *
 * 和 DrawArc() 一样。唯一不同是所绘曲线为椭圆曲线。
 * 
 * @param rx 曲线所在椭圆在X轴方向的半径
 * @param ry 曲线所在椭圆在Y轴方向的半径
 * @param dStart 曲线开始角度
 * @param dSweep 曲线扫过的角度。正数表示沿逆时针方向，负数表示沿顺时针方向。
 * @see DrawArc()
 */
void DrawEllipticalArc(double rx, double ry, double dStart, double dSweep);

/**
 * 帖图 
 *
 * 以当前位置为左上角帖一个位图，然后将画笔位置移动到位图的右上角。
 *
 * @param lpszFilename 位图文件名
 */
void DrawBitmap(char* lpszFilename);

//!@}

/**
 * \defgroup EggAdvGraph 高级图形功能
 * 下列宏和函数实现了Egg的高级图形功能。通过它们不仅可以绘制曲线和圆形，而且可
 * 以改变颜色、线粗、字体和填充色，还可以张贴位图。
 * @{
 */

/**
 * 设置画笔颜色和宽度
 *
 * 画笔的缺省颜色为黑色，宽度为一个像素。用此函数改变颜色和宽度后，所有的后续绘
 * 图操作都将使用此设置。
 * @param color 新的画笔颜色，可以使用：
 *      - BLACK —— 黑色
 *      - DARK_BLUE —— 深蓝色
 *      - DARK_GREEN —— 深绿色
 *      - DARK_CYAN —— 深青色
 *      - DARK_RED —— 深红色
 *      - DARK_MAGENTA —— 深紫色
 *      - DARK_YELLOW —— 深黄色
 *      - LIGHT_GRAY —— 浅灰色
 *      - DARK_GRAY —— 深灰色
 *      - BLUE —— 蓝色
 *      - GREEN —— 绿色
 *      - CYAN —— 青色
 *      - RED —— 红色
 *      - MAGENTA —— 紫色  
 *      - YELLOW —— 黄色
 *      - WHITE —— 白色
 * @param fWidth 画笔宽度，单位厘米
 * @see SetPenColor
 * @see SetPenWidth
 */
void SetPen(unsigned long color, double fWidth);

/**
 * 设置画笔颜色
 *
 * 画笔的缺省颜色为黑色。用此函数改变颜色后，所有的绘图操作都将是用此颜色。
 * @param color 新的画笔颜色，可以使用：
 *      - BLACK —— 黑色
 *      - DARK_BLUE —— 深蓝色
 *      - DARK_GREEN —— 深绿色
 *      - DARK_CYAN —— 深青色
 *      - DARK_RED —— 深红色
 *      - DARK_MAGENTA —— 深紫色