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 |
事件數據的指針對象 |