0. VSM编程开发接口
0.1 概述
0.1.1 简介
Proteus VSM的一个主要特点在于，通过使用基于DLL的元件模型，使它具有良好的可扩展性。这些模型可以是纯电气的，也可以组合元件的电气与图形模型，以便用户在仿真过程中可以进行交互。本文档致力于描述如何创建这些模型，作为本书的读者，希望您是一个C++编程高手，并精通Proteus VSM。
0.1.2 架构
下图显示了VSM模型与Proteus系统中的其它部分进行通信的概貌，其中的箭头表明通信的方向。
值得指出的是，模型中的电气部分将与PROSPICE仿真内核进行通信，而其图形部分将与ISIS进行通信。图形显示时以一个相对较慢的刷新频率(20次/秒)进行更新，而电气仿真分析则可能以每秒上百万次的速率进行。因此，在进行仿真分析时不应调用图形模型，而在ISIS中也不要调用电气模型。
(这些接口在VSM.HPP中定义。陈斌文注)
0.1.3 元件对象模型
VSM API在很大程度上使用Micorsoft的COM技术，但并不是全部。尤其是，所有主要VSM接口都实现为C++抽象类。指向这些类的实例的指针实际上将指向一个函数表，只不过其语法形式更容易，也更清楚。系统内核为各个模型提供多个接口指针以便能访问数据或其他相关服务。
这些接口中，各有各的用处。如：IINSTANCE接口，使得模型可访问其拥有者的属性；ICOMPONENT接口，使得图形模型能在原理图中画出；类似地，各模型也可通过返回一个或多个接口来将其自身数据提供给系统，这样，所有模型均可以标准化方式进行处理。电气模型可返回ISPICEMODEL或IDSIMMODEL接口，而图形模型将返回IACTIVEMODEL。
为保证VSM API在各操作系统间的可移植性(没有考虑移植到Linux)，我们没有完全实现COM，并使得安装与不同计算机上的模型共享变得更加简单。
0.2 模型的创建与删除
0.2.1 简介
创建了模型之后才能访问其中各项功能。显然，不能使用一个接口类来创建模型，否则这又将是一个“先有鸡还是先有蛋”的逻辑。我们通过使用一些传统C函数来创建模型，您需要在您的模型DLL中发布这些函数。您必须在这些函数中完成您的模型实例的创建与销毁工作。
此处的概念与微软的COM中的CoCreateInstance机制相似。
函数列表：
IACTIVEMODEL *createactivemodel (CHAR*device, ILICENCESERVER*ils)
VOID deleteactivemodel (IACTIVEMODEL *model)
ISPICEMODEL *createspicemodel (CHAR*device, ILICENCESERVER*ils)
VOID deletespicemodel (ISPICEMODEL *model)
IDSIMMODEL *createdsimmodel (CHAR*device, ILICENCESERVER*ils)
VOID deletedsimmodel (IDSIMMODEL *model)
IMIXEDMODEL *createmixedmodel (CHAR *device, ILICENCESERVER *ils)
VOID deletemixedmodel (IDSIMMODEL *model)
(这些函数在VSM.HPP中的Com Instance Creation/Destruction模块处。陈斌文注)
0.2.2 createactivemodel
IACTIVEMODEL *createactivemodel (CHAR *device, ILICENCESERVER *ils)
说明：
对于任意的期望具有图形功能的模型均需要实现该函数。如果一个模型实现了图形与电气模型，则在仿真时会缺省仅调用该函数，除非设置仿真选项为批处理模式。请参阅IACTIVEMODEL中的getspicemodel与getdsimmodel函数。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ IACTIVEMODEL * _export createactivemodel (CHAR *dvc, ILICENCESERVER *ils)
{
IACTIVEMODEL *newmodel = new MYMODEL (dvc);
ils->authorize(MY_PRODUCT_ID);
return newmodel;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *device |
ISIS库名，该库中包括当前所设计的活动模型。您可以通过该参数而在同一DLL中实现多个不同的活动模型类，或者根据ISIS库名支持小版本更新。 |
|
ILICENCESERVER *ils |
许可服务接口。各个模型必须通过该接口进行授权，以获得仿真器的其它服务。 |
返回值：
|
IACTIVEMODEL * |
返回一个指向您的模型类的指针，该类必须派生于IACTIVEMODEL接口。 |
0.2.3 deleteactivemodel
VOID deleteactivemodel (IACTIVEMODEL *model)
说明：
对于任意的期望具有图形功能的模型均需要实现该函数。当用户的仿真过程结束时，ISIS会调用该函数。在该函数中，应释放模型所使用的各种资源，传统术语也称该函数为析构函数。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ VOID _export deleteactivemodel (IACTIVEMODEL *model)
{
delete (MYMODEL *)model;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
IACTIVEMODEL * model |
一个指向IACTIVEMODEL接口的指针，它由相应的createactivemodel函数返回。在删除之前，您需要将它转换为您的实际模型。 |
0.2.4 createspicemodel
ISPICEMODEL *createspicemodel (CHAR *device, ILICENCESERVER *ils)
说明：
如果您的模型需要在批处理模式(batch mode)下支持模拟分析功能，则应该实现该函数。但如果您的模型需要访问一个ICOMPONENT接口时，不要实现该函数。
(能理解后一句话不？我的理解是：ICOMPONENT接口与IACTIVEMODEL属于图形模型，而SPICEMODEL属于仿真分析模型，按Proteus的做法，在进行仿真分析时不应调用图形模型，而在ISIS中也不要调用电气模型。所以在这里要求你需要访问一个ICOMPONENT接口时不要实现该函数。但这也仅仅是建议你这样做，如果你非要图形模型与分析模型一块实现，我猜Proteus也得乖乖地照单全收。陈斌文注)
如果您的模型中已通过createactivemodel函数返回了一个ICOMPONENT接口实例，则该函数永远也不会被调用。在这种情形下，PROSPICE将通过调用IACTIVEMODEL::getspicemode函数来获得ISPICEMODEL接口对象。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ ISPICEMODEL * _export createspicemodel (CHAR *dvc, ILICENCESERVER *ils)
{
ISPICEMODEL *newmodel = new MYMODEL (dvc);
ils->authorize(MY_PRODUCT_ID);
return newmodel;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *device |
该活动模型类所从属的存在于仿真器实例中的基本类型。您可以通过该参数在同一DLL中实现多个不同的活动模型类，或者与PRIMTIVE属性所指代的基本类型相匹配。 |
|
ILICENCESERVER *ils |
许可服务接口。各个模型必须通过该接口进行授权，以获得仿真器的其它服务。 |
返回值：
|
ISPICEMODEL* |
返回一个指向您的模型类的指针，该类必须派生于ISPICEMODEL接口。 |
0.2.5 deletespicemodel
VOID deletespicemodel (ISPICEMODEL *model)
说明：
如果您的模型需要在批处理模式(batch mode)下支持模拟分析功能，则应该实现该函数。但如果您的模型需要访问一个ICOMPONENT接口时，不要实现该函数。当用户的仿真过程结束时，PROSPICE会自动调用该函数。在该函数中，应释放模型所使用的各种资源，传统术语也称该函数为析构函数。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ VOID _export deletespicemodel (ISPICEMODEL *model)
{
delete (MYMODEL *)model;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
ISPICEMODEL* model |
一个指向ISPICEMODEL接口的指针，它由相应的createspicemodel函数返回。在删除之前，您需要将它转换为您的实际模型。 |
0.2.6 createsimmodel
IDSIMMODEL *createdsimmodel (CHAR *device, ILICENCESERVER
*ils)
说明：
如果您的模型需要在批处理模式(batch mode)下支持数字功能，则应该实现该函数。但如果您的模型需要访问一个ICOMPONENT接口时，不要实现该函数。
如果您的模型中已通过createactivemodel函数返回了一个ICOMPONENT接口实例，则该函数永远也不会被调用。在这种情形下，PROSPICE将通过调用IACTIVEMODEL:: getdsimmodel函数来获得IDSIMMODEL接口对象。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ IDSIMMODEL * _export createdsimmodel (CHAR *dvc, ILICENCESERVER *ils)
{
IDSIMMODEL *newmodel = new MYMODEL (dvc);
ils->authorize(MY_PRODUCT_ID);
return newmodel;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *device |
该活动模型类所从属的存在于仿真器实例中的基本类型。您可以通过该参数在同一DLL中实现多个不同的DSIM模型类，或者与PRIMTIVE属性所指代的基本类型相匹配。 |
|
ILICENCESERVER *ils |
许可服务接口。各个模型必须通过该接口进行授权，以获得仿真器的其它服务。 |
返回值：
|
IDSIMMODEL* |
返回一个指向您的模型类的指针，该类必须派生于IDSIMMODEL接口。 |
0.2.7 deletesimmodel
VOID deletedsimmodel (IDSIMMODEL *model)
说明：
如果您的模型需要在批处理模式(batch mode)下支持数字功能，则应该实现该函数。但如果您的模型需要访问一个ICOMPONENT接口时，不要实现该函数。当用户的仿真过程结束时，PROSPICE会自动调用该函数。在该函数中，应释放模型所使用的各种资源，传统术语也称该函数为析构函数。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ VOID _export deletedsimmodel (IDSIMMODEL *model)
{
delete (MYMODEL *)model;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
IDSIMMODEL * model |
一个指向IDSIMMODEL接口的指针，它由相应的createdsimmodel函数返回。在删除之前，您需要将它转换为您的实际模型。 |
0.2.8 createsimmodel
IDSIMMODEL *createdmixedmodel (CHAR *device, ILICENCESERVER
*ils)
说明：
如果您的模型需要在批处理模式(batch mode)下支持混合模式(模拟与数字)功能，则应该实现该函数。但如果您的模型需要访问一个ICOMPONENT接口时，不要实现该函数。
如果您的模型中已通过createactivemodel函数返回了一个ICOMPONENT接口实例，则该函数永远也不会被调用。在这种情形下，PROSPICE将通过调用IACTIVEMODEL::getspicemodel与IACTIVEMODEL::getdsimmodel函数来分别获得ISPICEMODEL与IDSIMMODEL接口对象。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ IMIXEDMODEL * _export createmixedmodel (CHAR *dvc, ILICENCESERVER *ils)
{
IMIXEDMODEL *newmodel = new MYMODEL (dvc);
ils->authorize(MY_PRODUCT_ID);
return newmodel;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *device |
该活动模型类所从属的存在于仿真器实例中的基本类型。您可以通过该参数在同一DLL中实现多个不同的SPICE模型类，或者与PRIMTIVE属性所指代的基本类型相匹配。 |
|
ILICENCESERVER *ils |
许可服务接口。各个模型必须通过该接口进行授权，以获得仿真器的其它服务。 |
返回值：
|
IMIXEDMODEL* |
返回一个指向您的模型类的指针，该类必须派生于IMIXEDMODEL接口。 |
0.2.9 deletemixedmodel
VOID deletemixedmodel (IMIXEDMODEL *model)
说明：
如果您的模型需要在批处理模式(batch mode)下支持模拟(呃，原文如此哈，可能是写该手册的技术人员是复制粘贴过来的，按我的理解，应该为混合模式。陈斌文注)功能，则应该实现该函数。但如果您的模型需要访问一个ICOMPONENT接口时，不要实现该函数。当用户的仿真过程结束时，PROSPICE会自动调用该函数。在该函数中，应释放模型所使用的各种资源，传统术语也称该函数为析构函数。
该函数必须按C语言命名方式与链接方式进行声明与输出，如下所示：
extern "C"
{ VOID _export deletespicemodel (ISPICEMODEL *model)
(呵呵，果然是复制粘贴过来的，至少这里应该是deletemixedmodel函数。我不改了，要是你不知道这里该如何声明或实现，回去看看C语言。陈斌文注)
{
delete (MYMODEL *)model;
}
}
参数含义：
|
参数声明 |
参数含义 |
|
IMIXEDMODEL* model |
一个指向IMIXEDMODEL接口的指针，它由相应的createmixedmodel函数返回。在删除之前，您需要将它转换为您的实际模型。 |
0.3 许可服务接口
0.3.1 概述
Proteus VSM的商业化是否成功将极大地取决于大量可用的模型。考虑到这一点，我们将大力推行在本软件的用户中发展模型市场这种模式。从另一角度来说，如果您需要设计一个自己的模型，以便在您自己的应用中更好地使用本软件，这中间所需要花费的成本代价可能会成为一个较大的障碍。然而，如果您发现有可能您能将您的模型卖给其他的用户，或许您就能克服刚才所说的障碍。互联网为我们提供了创建这样一个市场的理想场所。
为使得这种商业模式可行，就很有必要确保这些模型只能在付费的条件下才能使用，这也是Proteus VSM中许可服务API的作用。在本软件中，有一个术语叫用户码(Custom Key)，它是根据用户信息即用户名称与公司详细信息而生成的，有时，我们还可能会在用户码中绑定用户的硬件或OS安装信息。对于本软件的每个用户都将分配得到一个唯一用户ID，它与用户所得到的软件拷贝及用户码相对应。
对于所创建的每一个模型而言，其产品ID也是唯一的。这样，要在一个给定的用户端使用该模型，最终用户将被提示输入一个产品码Product Key。该产品码由用户ID与产品ID组成，在软件特定安装过程中将进行这些模型的验证工作。
0.3.2 为您的模型获得产品ID
在你着手进行设计新的模型之前，你应当向我们申请获得一个唯一产品ID。您可向我们邮箱[email protected]发送电子邮件。我们将向您提供一个基本值与一个产品码(Product key)文件，前者可以生成多个产品ID，后者可以使得这些ID值在Proteus VSM中可用。
0.3.3 如何进行模型许可
为了得到仿真器的服务，一个模型必须在其创建过程中通过系统的验证。该过程可通过调用ILICENCESERVER::authorize函数来完成，该函数有一个唯一的参数，即产品ID值。许可服务器将检查所安装的产品码集合，并只允许那些正确的码值能够验证通过。如果模型未能成功通过系统验证，ILICENCESERVER::authorize函数将返回FALSE，仿真器在后续工作中将忽略该模型对象。
一般而言，模型构造函数代码如下：
extern "C"
{ ISPICEMODEL * _export createspicemodel (CHAR *dvc, ILICENCESERVER *ils)
{
ISPICEMODEL *newmodel = new MYMODEL (dvc);
ils->authorize(MY_PRODUCT_ID);
return newmodel;
}
}
在某些情况下，将ILICENCESERVER实例对象传递给模型类构造函数更为方便，尤其对于那些支持批处理模型batch mode与交互(interactive)仿真的模型而言更是这样。
0.4 图形模型接口
0.4.1 概述
图形模型接口包括两个接口类：
l ICOMPONENT接口表示ISIS中的一个活动器件对象，它允许VSM模型在原理图中进行画图操作以及提供用户交互功能。
l IACTIVEMODEL接口作为您的VSM图形模型基类。您需要实现相应的功能，如在原理图中画出父器件对象，在适当的时候响应鼠标与键盘事件。
这两个接口类存在于ISIS中，而不是PROSPICE中，调用它们的函数以帧的概念进行处理，典型值为20Hz，即每秒20帧。
0.4.2 图形功能
VSM API为您提供了三个层次的图形化功能：
l 活动对象变化图。这种方式最简单，但其灵活性也最差。它使用可在ISIS中画出的基本图元，允许VSM模型在某些特定时刻画出指定的图元对象。可以指定这些图元对象相对于模型对象实例的初始位置与方向等属性，还允许进行旋转操作，如仪表指针与马达转子等。具体请参阅创建你的活动器件一节。
l 矢量图形。该方式折中考虑编程复杂性与灵活性。它允许一个VSM模型直接在原理图中画出矢量图形对象(如线、圆、圆弧等)与文本，它可以选择ISIS中可提供的2D图元对象，也可通过API使用原理图中命名方式所提供的图形样式。
l Windows GDI。对于高级用户，VSM API提供采用Windows GDI的方式完成图形模型处理。该方式允许您在Windows范畴内随心所欲地画图操作，尤其允许您使用位图。我们的LCD Display模型就是采用这种方式实现的。
请注意：使用这种方式进行图形功能设计后，不能方便的移植到其它操作系统，如果您有这种需求，我们应当选择在其它平台上发布VSM。
0.4.3 座标
一些API函数采用了座标参数。如，ICOMPONENT::drawline函数有四个整型参数，表示线的起止点。这些座标点是相对于原理图中的器件而言的，在屏幕上画出之前它们将进行换算工作。
在缺省情况下，其单位为1000 ppi。换句话说，在模型座标中的1000将换算成为原理图座标系中的1英寸。这种换算比例可以通过ICOMPONENT::setdrawscale函数进行修改。
0.4.4 ICOMPONENT接口类
图形模型可使用本接口完成原理图中画出图形功能及与用户交互功能。一个图形模型通过IACTIVEMODEL::initialize函数得到其ICOMPONENT接口实例。
属性管理
CHAR*ICOMPONENT::getprop (CHAR *name)
CHAR* ICOMPONENT::getproptext(VOID)
VOID ICOMPONENT::addprop (CHAR *propname, CHAR*item, WORD hflags)
VOID ICOMPONENT::delprop (CHAR*propname)
VOID ICOMPONENT::setproptext (CHAR*text)
活动状态处理
ACTIVESTATE ICOMPONENT::getstate (INT element, ACTIVEDATA *data)
BOOL ICOMPONENT::setstate (ACTIVESTATE state)
图形管理
VOID ICOMPONENT::setdrawscale (INT ppi)
HDC ICOMPONENT::begincache (BOX &area)
HDC ICOMPONENT::begincache (INT symbol)
VOID ICOMPONENT::endcache (VOID)
矢量画图服务
HGFXSTYLE ICOMPONENT::creategfxstyle (CHAR *name)
VOID ICOMPONENT::selectgfxstyle (HGFXSTYLE style)
VOID ICOMPONENT::setpenwidth (INT w)
VOID ICOMPONENT::setpencolour (COLOURc)
VOID ICOMPONENT::setbrushcolour (COLOUR c)
VOID ICOMPONENT::drawline (INT x1, INT y1, INT x2, INT y2)
VOID ICOMPONENT::drawbox (INT x1, INT y1, INT x2, INT y2)
VOID ICOMPONENT::drawbox (BOX &bx)
VOID ICOMPONENT::drawcircle (INT x, INT y, INTradius)
VOID ICOMPONENT::drawbezier (POINT *p, INTnumpoints)
VOID ICOMPONENT::drawpolyline (POINT *p, INT numpoints)
VOID ICOMPONENT::drawpolygon (POINT *p, INTnumpoints)
VOID ICOMPONENT::drawsymbol (INT symbol)
VOID ICOMPONENT::drawsymbol (INT x, INTy, INT rot, INTmir, INT symbol)
VOID ICOMPONENT::drawstate (ACTIVESTATE state)
VOID ICOMPONENT::getsymbolarea (INT symbol, BOX *area)
BOOL ICOMPONENT::getmarker (CHAR*name, POINT *pos, INT *rot, INT *mir);
文本输出服务
HTEXTSTYLE ICOMPONENT::createtextstyle (CHAR*name)
VOID ICOMPONENT::selecttextstyle (HTEXTSTYLE style)
VOID ICOMPONENT::settextfont (CHAR *name)
VOID ICOMPONENT::settextsize (INT h)
VOID ICOMPONENT::setbold (BOOL f)
VOID ICOMPONENT::setitalic (BOOL f)
VOID ICOMPONENT::setunderline (BOOL f)
VOID ICOMPONENT::settextcolour (COLOUR c)
VOID ICOMPONENT::drawtext (INTx, INT y, INT rot, INT jflags, CHAR *text, ...)
Window弹出菜单支持
IPOPUP *ICOMPONENT::createpopup (CREATEPOPUPSTRUCT *cps)
VOID ICOMPONENT::deletepopup (POPUPID id)
0.4.4.1 getprop
CHAR *ICOMPONENT::getprop (CHAR *name)
说明：
返回原理图中器件的单个属性值。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *name |
期望返回属性值的属性名称 |
返回值：
|
CHAR * |
指向属性值的指针。该值保存在一个静态缓冲区内，因此每次调用ICOMPONENT::getprop后都将覆盖掉上次调用结果。 |
0.4.4.2 getproptext
CHAR *ICOMPONENT::getproptext (VOID)
说明：
返回原理图中器件的整个属性模块。
必要时，可调用函数ICOMPONENT::setproptext对该值重新赋值。
返回值：
|
CHAR * |
指向属性模块的指针，该模块保存在ISIS中的器件中的situ中。调用结果为该器件中实际保存内容，可能还会包含ISIS中所用的花括号等表示隐藏文本内容。 |
0.4.4.3 addprop
VOID ICOMPONENT::addprop (CHAR *propname, CHAR *item,
WORD hflags)
说明：
为原理图中的器件对象添加或修改单个属性。
在仿真分析运行过程中，虚拟仪器模型可使用本函数来保存控制参数。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *propname |
期望添加或修改的属性名称 |
|
CHAR *item |
目标属性值 |
|
WORD hflags |
属性的可见标志。这些值将决定属性名称及其值的可见性。Hflags可能取值内容为： SHOW_ALL HIDE_ALL HIDE_KEYWORD HIDE_VALUE |
0.4.4.4 delprop
VOID ICOMPONENT::delprop (CHAR *propname)
说明：
删除原理图中的器件对象的一个属性。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *propname |
待删除的属性名称 |
0.4.4.5 setproptext
VOID ICOMPONENT::setproptext (CHAR *text)
说明：
对原理图中的器件对象的属性模块进行重新赋值。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *text |
待设置的新属性值。该文本内容必须按您手动录入到器件属性模块中的格式进行编排，采用换行符分隔各个属性名称，花括号表示隐藏名称与值。 |
0.4.4.6 setstate
BOOL ICOMPONENT::setstate (ACTIVESTATE state)
说明：
设置原理图中的器件对象的活动状态，必要时将导致该器件重画。
该函数为VSM中动画效果的器件模型改变其图形状态提供了一个非常简单快捷的方式。如果ISIS库对象通过一系列的图元符号创建而成，该函数可在一个模型中选择将显示的符号。
参数含义：
|
参数声明 |
参数含义 |
|
ACTIVESTATE |
器件的新状态值。对于一个常规指示器indicator，它对于应将被显示的图元符号的数目；而对于一个位指示器bitwise indicator，状态值的每一位代表一个元素的某个条件 |
返回值：
|
BOOL |
如果选择了新的状态，返回TRUE 如果没有任何改变，返回FALSE |
0.4.4.7 getstate
ACTIVESTATE ICOMPONENT::getstate (INT element, ACTIVEDATA
*data)
说明：
设计该函数的目的在于使VSM模型能够处理标准指示器indicators的各项功能，它可将RTVPROBE, RTIPROBE 或 RTDPROBE中的数据转换为ACTIVESTATE值，该值可用作为调用ICOMPONENT::setstate函数的实参。
主动器件的标准动画效果可经由如下IACTIVEMODEL::animate函数中的两行代码实现
VOID MYMODEL::animate (INT element, ACTIVEDATA *data)
{ ACTIVESTATE newstate = component->getstate(element, data);
component->setstate(newstate);
}
参数含义：
|
参数声明 |
参数含义 |
|
INT element |
数据所关联器件的元素对象。用于位指示器bitwise indicators，其返回值的每位值均表示一个元素状态。 |
|
ACTIVEDATA *data |
一个包括由PROSPICE中的探针对象所测量的联合结构对象。详情有参阅IACTIVEMODEL::animate |
返回值：
|
ACTIVESTATE |
器件的新状态值。对于一个普通指示器，它对应于所显示的图元数目；而对于一个位指示器，该状态值的每位均表示一个元素状态。 |
0.4.4.8 setdrawscale
VOID ICOMPONENT::setdrawscale (INT ppi)
说明：
设置所有矢量图形函数中的缩放因子。其缺省值为1000ppi，因此若调用
component->drawline(0, 0, 1000, 0)
将在ISIS座标系系统中画出一条长为1英寸的线段。
参数含义：
|
参数声明 |
参数含义 |
|
INT ppi |
新的缩放因子值，表示每英寸所对应的像素点数。 |
0.4.4.9 begincache
HDC ICOMPONENT::begincache (BOX &area)
HDC ICOMPONENT::begincache (INT sprite)
说明：
开始缓冲即将调用的矢量图形函数，并返回所缓冲的位图的Window DC对象(HDC类型)。一般地会基于如下两种目的来调用这些函数：
l 若需要调用多个矢量图形函数才能画出一个器件，此情况下，可能会出现闪屏现象。如果将这些函数画出结果缓冲到一个位图中，则可以避免闪屏。
l 若一个模型需要调用VSM的API所不支持的Windows GDI函数，则begincache函数可以为您提供对于Windows DC的访问途径，即HDC对象，它可作为参数传递到Windows GDI函数中。
您可以通过调用ICOMPONENT::endcache函数来结束缓冲过程，并将所缓冲的位图显示出来。
参数含义：
|
参数声明 |
参数含义 |
|
BOX &area |
您所缓冲的区域范围。缓冲过程中的矢量图形函数将仅在此区域中画出。 |
|
INT sprite |
另一种指定区域范围的方法，即所限制的范围由所给定的图元符号大小所决定。如果该值为-1，则表示该区域范围为库中器件的大小范围。 |
返回值：
|
HDC |
选择了所缓冲位图的Windows DC句柄。请注意，当ISIS的画出目标设备不支持位图时将返回NULL值。显然，如果一个模型需要位图支持时，它就不能显示在不支持位图的设备上。 |
0.4.4.10 endcache
VOID ICOMPONENT::endcache (VOID)
说明：
结束矢量图形函数的位图缓冲过程，并将所缓冲的位图对象显示到屏幕上。显然，本函数应当且只能与ICOMPONENT::begincache函数配对使用。
0.4.4.11 creategfxstyle
HGFXSTYLE ICOMPONENT::creategfxstyle (CHAR *name)
说明：
创建并选择一种新的图形样式，以用于后续矢量图形操作。一个图形样式定义了各种图形属性，如画笔宽度、填充样式与颜色及其他可用于ISIS中的图形功能函数的属性。
一般而言，一个模型可在其构造函数中创建多个图形模式，并将它们作为成员变量保存起来，在实现IACTIVEMODEL::plot函数与IACTIVEMODEL:animate函数时就可将这些成员变量传回到ICOMPONENT::selectgfxstyle函数中。
系统中没有专用于删除图形样式的函数，在仿真分析结束时系统将自动完成删除工作。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *name |
新创建图形样式的蓝本样式名称。如果该值为NULL，则新创建的图形样式将基于器件COMPONENT样式。 |
返回值：
|
HGFXSTYLE |
新的图形样式对象句柄 |
0.4.4.12 selectgfxstyle
VOID ICOMPONENT::selectgfxstyle (HGFXSTYLE style)
说明：
选择一个由ICOMPONENT::creategfxstyle函数所创建的图形样式，以用于后续矢量图形操作。
参数含义：
|
参数声明 |
参数含义 |
|
HGFXSTYLE style |
所选择的图形样式对象句柄 |
0.4.4.13 setpenwidth
VOID ICOMPONENT::setpenwidth (INT width)
说明：
设置当前图形样式中的新的画笔宽度。
参数含义：
|
参数声明 |
参数含义 |
|
INT width |
模型座标系中的画笔宽度 |
0.4.4.14 setpencolour
VOID ICOMPONENT::setpencolour (COLOUR c)
说明：
设置当前图形样式中的新的画笔颜色。
参数含义：
|
参数声明 |
参数含义 |
|
COLOUR c |
画笔的RGB颜色值。在VSM.HPP头文件中有多个预定义的颜色值。 |
0.4.4.15 setbrushcolour
VOID ICOMPONENT::setbrushcolour (COLOUR c)
说明：
设置当前图形样式中的新的填充颜色。
参数含义：
|
参数声明 |
参数含义 |
|
COLOUR c |
画刷的RGB颜色值。在VSM.HPP头文件中有多个预定义的颜色值。 |
0.4.4.16 drawline
VOID ICOMPONENT::drawline (INT x1, INT y1, INT x2, INT y2)
说明：
画出一条线段，其起止点为(x1, y1)与(x2, y2)。
参数含义：
|
参数声明 |
参数含义 |
|
INT x1, y1, x2, y2 |
线段的起止点座标值 |
0.4.4.17 drawbox
VOID ICOMPONENT::drawbox (INT x1, INT y1, INT x2, INT y2)
VOID ICOMPONENT::drawbox (BOX &area)
说明：
画出一个矩形，其对角点为(x1, y1)与(x2, y2)。
参数含义：
|
参数声明 |
参数含义 |
|
INT x1, y1, x2, y2 |
矩形的左下角与右上角(啊？一般都是左上角与右下角，看来这个ISIS的座标系还有点与众不同，需要理解与注意一下。陈斌文注) |
|
BOX &area |
另一种指定矩形的方法。 |
0.4.4.18 drawcircle
VOID ICOMPONENT::drawcircle (INT x, INT y, INT radius)
说明：
画出一个圆，其圆心座标为(x, y)，半径为radius。
参数含义：
|
参数声明 |
参数含义 |
|
INT x, y |
圆心座标 |
|
INT radius |
圆的半径 |
0.4.4.19 drawbezier
VOID ICOMPONENT::drawbezier (POINT *p, INT numpoints)
说明：
画出一条由一系列点所决定的贝塞尔曲线。
更多关于贝塞尔曲线的知识请参阅Windows SDK。
参数含义：
|
参数声明 |
参数含义 |
|
POINT *p |
贝塞尔曲线的模型点 |
|
INT numpoints |
点数 |
0.4.4.20 drawpolyline
VOID ICOMPONENT::drawpolyline (POINT *p, INT numpoints)
说明：
画出一条由一系列点所决定的Polyline(这些点依次连接而成的图形对象)。请注意，Polyline与多边形的区别在于前者不是一个封闭形状。
参数含义：
|
参数声明 |
参数含义 |
|
POINT *p |
Polyline的模型点 |
|
INT numpoints |
点数。尽管VSM本身并不限定模型点的数目，但一些Windows图形驱动引擎在处理较大点数的Polyline时会出现问题。 |
0.4.4.21 drawpolygon
VOID ICOMPONENT::drawpolygon (POINT *p, INT numpoints)
说明：
画出一条由一系列点所决定的多边形。请注意，多边形是一个封闭形状，它用当前画刷颜色进行填充。
参数含义：
|
参数声明 |
参数含义 |
|
POINT *p |
多边形的模型点，每个点表示一个顶点。 |
|
INT numpoints |
点数。 |
0.4.4.22 drawsymbol
VOID ICOMPONENT::drawsymbol (INT sprite)
VOID ICOMPONENT::drawsymbol (INT x, INT y, INT rot, INT mir, INT
sprite)
说明：
画出指定的图元符号，上面两个函数中，前者相对于器件，后者可为任意位置与方位。该函数提供了一个介于基于图元与基于矢量图形两种方式之间的实现途径，并使得通过很少代码实现高效动画效果成为可能，特别是，它可以非常简单地以任意角度画出图元符号来实现旋转动画效果。
参数含义：
|
参数声明 |
参数含义 |
|
INT sprite |
主动器件中的图元符号序号。若该值为-1，则将画出基元，如果基元不存在，则将画出缺省图形。 |
|
INT x, y |
画出图元符号时的基准偏移量。 |
|
INT rot |
画出图元符号时的逆时针旋转角度值。 |
|
INT mir |
画出图元符号时的镜像标志，其可能的取值值为： 0 无翻转 MIR_X 水平镜像 MIR_Y 垂直镜像 |
座标变换处理顺序为: 镜像、旋转、偏移
0.4.4.23 drawstate
VOID ICOMPONENT::drawstate (ACTIVESTATE state)
说明：
画出指定状态的图元符号。如果该器件有一个公共符号，它将在画出其余图元符号后被画出。
该函数用于实现IACTIVEMODEL::plot函数，与ICOMPONENT::setstate函数不同之处在于，在画出相关目标符号时并不考虑器件当前状态。
参数含义：
|
参数声明 |
参数含义 |
|
ACTIVESTATE state |
器件的新状态值。对于一个常规指示器indicator，它对于应将被显示的图元符号的数目；而对于一个位指示器bitwise indicator，状态值的每一位代表一个元素的某个条件 若该值为-1，将画出器件缺省图形 |
0.4.4.24 getsymbolarea
BOOL ICOMPONENT::getsymbolarea (INT symbol, BOX *area)
说明：
取得指定图元符号的区域。它可用于定义在ICOMPONENT:begincache函数中进行缓冲的位图对象，也可作为取得器件图形模型中特定区域的位置手段。例如，一个特定的图元符号可能会用来定义一个矩形框，以可在其中输出文本。
参数含义：
|
参数声明 |
参数含义 |
|
INT symbol |
待取得区域的图元符号的序号。若该值为-1，则会返回整个ISIS库器件对象，即模型中全体有效画出区域的全体。 |
|
ACTIVESTATE state |
器件的新状态值。对于一个常规指示器indicator，它对于应将被显示的图元符号的数目；而对于一个位指示器bitwise indicator，状态值的每一位代表一个元素的某个条件 若该值为-1，将画出器件缺省图形 |
返回值：
|
BOOL |
如果指定图元符号存在，则返回TRUE；反之亦然。 |
0.4.4.25 getmarker
BOOL ICOMPONENT::getmarker (CHAR *name, POINT *pos, INT
*rot, INT *mir)
说明：
取得一个命名标记的位置与方位，该命名标记在ISIS库器件构造函数中创建。该函数可用于在实现IACTIVEMODEL::actuate函数时判断用户是否单击了特定的命名标记对象。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *name |
待取得位置方位的命名标记对象名称。 |
|
POINT *pos |
命名标记对象相对于器件原点的偏移量指针 |
|
INT *rot |
待取得的命名标记对象的旋转角度指针，逆时针方向为正。 |
|
INT *mir |
待取得的命名标记对象的镜像标志指针，其可能的取值值为： 0 无翻转 MIR_X 水平镜像 MIR_Y 垂直镜像 |
返回值：
|
BOOL |
如果指定命名标记对象存在，则返回TRUE；反之亦然。 |
0.4.4.26 createtextstyle
HTEXTSTYLE ICOMPONENT::createtextstyle (CHAR *name)
说明：
创建并选择一个新的文本样式，以用于后续文本输出操作。一个文本样式将定义诸如字体、大小、下划线、粗体等文本属性，在ISIS的各文本样式模板函数中使用。
一般情况下，一个模型的构造函数中将创建多个文本样式，并以其数据成员变量形式保存下来，在后续的IACTIVEMODEL::plot函数与IACTIVEMODEL::animate函数中作为参数传递给ICOMPONENT::selecttextstyle函数。
系统没有设计删除文本样式的API函数，在仿真分析结束后，系统将自动删除它们。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *name |
新创建文本样式的蓝本样式名称。如果该值为NULL，则新创建的文本样式将基于READOUT样式。 |
返回值：
|
HTEXTSTYLE |
新的文本样式句柄 |
0.4.4.27 selecttextstyle
VOID ICOMPONENT::selecttextstyle (HTEXTSTYLE style)
说明：
选择一个由ICOMPONENT::createtextstyle函数所创建的文本样式，以用于后续文本输出操作。
参数含义：
|
参数声明 |
参数含义 |
|
HTEXTSTYLE style |
将选择的文本样式对象句柄 |
0.4.4.28 settextfont
VOID ICOMPONENT::settextfont (CHAR *name)
说明：
设置当前所选择的文本样式对象的字体。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *name |
将选择的字体名称。它为某个普通的Windows字体名称，如"Arial"。另外，Labcenter矢量字体也可使用矢量字体名称，而字体名称"Default Font"可用于选择当前原理图中的缺省字体。 |
0.4.4.29 settextsize
VOID ICOMPONENT::settextsize (INT height)
说明：
设置当前所选择的文本样式对象的字体大小。
参数含义：
|
参数声明 |
参数含义 |
|
INT height |
期望的字体大小值。对于Windows GDI函数而言，它们可能将该值自动设置为最接近的可用字体。 |
0.4.4.30 setbold
VOID ICOMPONENT::setbold (BOOL flag)
说明：
设置当前所选择的文本样式对象的粗体标志。
参数含义：
|
参数声明 |
参数含义 |
|
BOOL flag |
TRUE表示为粗体，而FALSE表示为正常体。 |
0.4.4.31 setitalic
VOID ICOMPONENT::setitalic (BOOL flag)
说明：
设置当前所选择的文本样式对象的斜体标志。
参数含义：
|
参数声明 |
参数含义 |
|
BOOL flag |
TRUE表示为斜体，而FALSE表示为正常体。 |
0.4.4.32 setunderline
VOID ICOMPONENT::setunderline (BOOL flag)
说明：
设置当前所选择的文本样式对象的下划线标志。
参数含义：
|
参数声明 |
参数含义 |
|
BOOL flag |
TRUE表示为含下划线，而FALSE表示为正常体。 |
0.4.4.33 settextcolour
VOID ICOMPONENT::settextcolour (COLOUR c)
说明：
设置当前所选择的文本样式对象的颜色属性。
参数含义：
|
参数声明 |
参数含义 |
|
COLOUR c |
文本的RGB颜色值。可参阅VSM.HPP查看预定义的颜色值。 |
0.4.4.34 drawtext
VOID ICOMPONENT::drawtext (INT x, INT y, INT rot, INT jflags, CHAR
*text, ...)
说明：
在原理图中用当前所选择的文本样式画出文本内容，其文本位置、角度与偏移量等属性均由各相应参数指定，该函数类似于C语言中的printf函数。
参数含义：
|
参数声明 |
参数含义 |
|
INT x, y |
待输出文本的偏移座标量 |
|
INT rot |
待输出文本的旋转角度值，逆时针为正。 |
|
INT jflags |
一个位操作结果值，它控制文本对齐方式及垂直方位。其的取值值为： TXJ_LEFT 文本左对齐 TXJ_RIGHT文本右对齐 TXJ_CENTRE 文本水平居中 TXJ_BOTTOM 文本位于原点之上 TXJ_TOP 文本位于原点之下 TXJ_MIDDLE 文本与原点垂直居中对齐 |
|
CHAR *text |
文本输出格式字符串，与printf函数中的格式字符串含义一致。 … 与printf函数中的输出参数相同 |
0.4.4.35 createpopup
IPOPUP *ICOMPONENT::createpopup (CREATEPOPUPSTRUCT
*cps)
说明：
创建模型的弹出式菜单。更多信息请参阅POPUPWINDOW INTERFACE
参数含义：
|
参数声明 |
参数含义 |
|
CREATEPOPUPSTRUCT *cps |
弹出式菜单窗口的初始化参数指针 |
返回值：
|
IPOPUP * |
弹出式菜单窗口的接口指针。一般情况下，您需要将其转换成为相应的接口类型。 |
0.4.4.36 deletepopup
VOID ICOMPONENT::deletepopup (POPUPID id)
说明：
删除一个弹出式窗口，恢复屏幕显示。
如果在仿真分析过程中，这是您能删除一个弹出式菜单的唯一方法。在正常的事件处理流程中，ISIS将在仿真分析结束时删除所有弹出式菜单对象。
参数含义：
|
参数声明 |
参数含义 |
|
POPUPID id |
将被删除的弹出式菜单的ID值。各弹出式菜单对象的ID值在其CREATEPOPUPSTRUCT结构中指定，而该结构是ICOMPONENT::createpopup函数的参数类型。 |
0.4.5 IACTIVEMODEL接口类
图形模型可使用本接口完成原理图中画出图形功能及与用户交互功能。一个图形模型通过
该接口是那些要实现图形功能的模型的必备基类。它提供ISIS将调用的各种功能服务，以完成器件的画出与动画功能效果，并能接收来自ISIS的键盘与鼠标事件
一个图形模型所需实现的各个函数：
VOID IACTIVEMODEL::initialize (ICOMPONENT *cpt)
ISPICEMODEL *IACTIVEMODEL::getspicemodel (CHAR *primitive)
IDSIMMODEL *IACTIVEMODEL::getdsimmodel (CHAR*primitive)
VOID IACTIVEMODEL::plot (ACTIVESTATE state)
VOID IACTIVEMODEL::animate (INTelement, ACTIVEDATA *newstate)
BOOL IACTIVEMODEL::actuate (WORD key, INT x, INT y, DWORD flags)
0.4.5.1 initialize
VOID IACTIVEMODEL::initialize (ICOMPONENT *cpt)
说明：
当模型被许可验证通过后，ISIS将马上调用该函数。其主要功能是从ISIS器件中接管ICOMPONENT接口，交由模型所从属宿主接口处理。您也可使用该函数完成传统意义上的初始化功能任务，它也是一个创建弹出式菜单窗口的好场所。
参数含义：
|
参数声明 |
参数含义 |
|
ICOMPONENT *cpt |
原理图中关联器件的ICOMPONENT接口指针 |
0.4.5.2 getspicemodel
ISPICEMODEL *IACTIVEMODEL::getspicemodel (CHAR *primitive)
说明：
对于那些实现了图形模型与电气功能的模型而言，它是一个很有用的函数。PROSPICE调用它来取得一个与ISPICEMODEL接口相关联的图形模型(如果存在的话)。
对于一个派生于IACTIVEMODEL与ISPICEMODEL的模型类，该函数一般按以下形式实现：
ISPICEMODEL *MYMODEL::getspicemodel (CHAR *primitive)
{ return this;
}
因为ISIS库器件需要一个PRIMITIVE属性，所以在PROSPICE中，仿真器件实例将为其创建一个。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *primitive |
与模型相关联的仿真实例基本类型。该值来自于PRIMITIVE属性的第二个参数，因此，若一个模型，其库中有以下赋值语句： PRIMITIVE=ANALOG,AMMETER 则将取得AMMETER作为其值。 |
返回值：
|
ISPICEMODEL * |
模型的ISPICEMODEL接口指针。如果该模型未实现ISPICEMODEL接口，则您应该返回NULL |
0.4.5.3 getsimmodel
IDSIMMODEL *IACTIVEMODEL::getdsimmodel (CHAR *primitive)
说明：
对于那些实现了图形模型与电气功能的VSM模型而言，它是一个很有用的函数。PROSPICE调用它来取得一个与IDSIMMODEL接口相关联的图形模型(如果存在的话)。
对于一个派生于IACTIVEMODEL与IDSIMMODEL的模型类，该函数一般按以下形式实现：
IDSIMMODEL *MYMODEL::getdsimmodel (CHAR *primitive)
{ return this;
}
因为ISIS库器件还需要一个PRIMITIVE属性，所以在PROSPICE中，仿真器件实例将为其创建一个。
参数含义：
|
参数声明 |
参数含义 |
|
CHAR *primitive |
与模型相关联的仿真实例基本类型。该值来自于PRIMITIVE属性的第二个参数，因此，若一个模型，其库中有以下赋值语句： PRIMITIVE=DIGITAL,DISPLAY 则将取得DISPLAY作为其值。 |
返回值：
|
IDSIMMODEL * |
模型的IDSIMMODEL接口指针。如果该模型未实现IDSIMMODEL接口，则您应该返回NULL |
0.4.5.4 plot
VOID IACTIVEMODEL::plot (ACTIVESTATE state)
说明：
ISIS在需要重画原理图时就会调用该函数。它与IACTIVEMODEL::animate函数不同之处在于模型器件期望重画所有部件，此处，无需传递Active事件信息。
您必须实现该函数，这样您的器件才能在仿真重画过程中被画出。该函数的一个最小化实现代码如下所示：
VOID MYMODEL::plot (ACTIVESTATE state)
{ component->drawstate(state);
}
参数含义：
|
参数声明 |
参数含义 |
|
ACTIVESTATE state |
所关联器件的当前状态 |
0.4.5.5 animate
VOID IACTIVEMODEL::animate (INT element, ACTIVEDATA *event)
说明：
对于图形模型而言，其相关联的电气模型(ISPICEMODEL或IDSIMMODEL)可能会产生active事件，此时ISIS将调用animate函数。
Active事件由PROSPICE在每次仿真结束时调用ISPICEMODEL::indicate或IDSIMMODEL::indicate函数的返回结果所产生。它提供了一个电气模型与图形模型通信的通用机制。
参数含义：
|
参数声明 |
参数含义 |
|
INT element |
事件相关的图形模型元素。该特性允许子图中多个RTprobe基元将测量结果传递给父图形器件，请参阅BITWISE INDICATORS中的例子以理解其工作原理。 |
|
ACTIVEDATA *event |
事件数据的指针对象 |