Interface Functions

<<< The Draw List

Chapters

Known Issues >>>

Contents

[back to top]

A.1 Introduction

This chapter provides a complete reference to all the functions and properties available in the COM interfaces provided by PS/Workshop.

• For a more general introduction to the interfaces available, see Chapter 6, "The PS/Workshop Interfaces".
• For an explanation of the support your module should provide for the interfaces, and the support provided by default when you use the PS/Workshop AppWizard, see Chapter 5, "Module Structure".

As for all COM interfaces, the interfaces described in this chapter inherit the IUnknown interface. That is, they all have QueryInterface, AddRef, and Release methods to control the lifetimes of objects that expose the interface. See Section 3.4, "Managing the lifetime of COM objects", for more information.

[back to top]

A.2 IPSWApp

The IPSWApp interface represents the overall PS/Workshop application. There is exactly one IPSWApp interface for each instance of PS/Workshop. The IPSWApp interface is supplied to a module when the module is first loaded.

The IPSWApp interface contains functions for modifying the PS/Workshop user interface, opening documents and registering callback functions.

[back to top]

A.2.1 Summary

The following is a summary of the IPSWApp interface.

Properties

ActiveDocument

IPSWDoc

Documents

IPSWDocs

StatusBarText

BSTR

Version

double

Functions

AddMenuItem

AddMenuItem2

OpenDocument

OpenNewDocument

CloseDocument

QueryPSWModuleInterface

RegisterFileOpenFunction

RegisterFileSaveAsFunction

[back to top]

A.2.2 IPSWApp Properties

ActiveDocument

HRESULT   get_ActiveDocument
(
--- returned arguments ---
   IPSWDoc **ppDoc
)

Returns the IPSWDoc interface pointer associated with the currently active document. If there is no active document this returns S_FALSE.

ppDoc

When get_ActiveDocument returns S_FALSE or E_FAIL, the value of ppDoc is undefined.

HRESULT   put_ActiveDocument
(
--- received arguments ---
   IPSWDoc *pDoc 
)

Attempts to activate the document associated with the pDoc interface.

pDoc

Documents

HRESULT   get_Documents
(
--- returned arguments ---
   IPSWDocs **pDocs 
)

Returns the IPSWDocs interface (a collection of IPSWDoc interfaces) which can be used to interate over the documents in PS/Workshop.

pDocs

StatusBarText

HRESULT   get_StatusBarText
(
--- returned arguments ---
   BSTR *pText 
)

Returns the current text in the PS/Workshop status bar.

pText

Example

// allocated previously
CComPtr<IPSWApp> pApp;

CComBSTR bsStatusText;
HRESULT hr      = pApp->get_StatusBarText(&bsStatusText);
if (SUCCEEDED( hr ) )
{
   // convert the BSTR into a more usable CString
   CString csStatusText = bsStatusText;
}

HRESULT   put_StatusBarText
(
--- received arguments ---
   BSTR Text
)

Sets the text in the PS/Workshop status bar.

Text

Example

// allocated previously
CComPtr<IPSWApp> pApp;

CComBSTR bstrStatusText( OLESTR("Set Status Text") );
// or alternatively
// Cstring csStatusText = _T("Set Status Text");
// bstrStatusText.AllocSysString( bstrStatusText );

if (SUCCEEDED( pApp->put_StatusBarText ) )
{
   // convert the BSTR into a more usable CString
   CString csStatusText = bsStatusText;
}

Version

HRESULT   get_Version
(
--- returned arguments ---
   double *pVersion
)

Returns the current version of PS/Workshop.

[back to top]

A.2.3 IPSWApp Functions

AddMenuItem

HRESULT   AddMenuItem
(
--- received arguments ---
   IPSWAddIn *pAddIn, 
   BSTR CommandName, 
   long CommandID, 
   PSW_Menu_Mode  mode 
)

Adds an item to a PS/Workshop menu. If the menu does not already exist then it is created first.

pAddIn

CommandName

CommandID

mode

CommandName must be a NULL separated string.

• The last part of the string contains the text of the menu item to add.
• The first part of the string contains the text of the menu to add.

You can add a cascading menu to PS/Workshop by specifying a string that contains more than two parts, as follows:

Menu\nCommand\nSub-Command

You can use the & character in CommandName to specify keyboard mnemonics for your menu and menu item that the user can use to access the new command. The character immediately after any & character in CommandName is used as the keyboard mnemonic for that part of the string. For example, the string

&Menu\nC&ommand

would create a Menu menu containing a Command item. A PS/Workshop user could access the new Command by typing Alt+M+O.

CommandID contains the ID to be associated with the menu item. This is subsequently passed back to the module during the IPSWEvents::OnCommand event when the user chooses the menu item.

The mode argument may have the following values:

See Chapter 7, "Adding a New Menu Item to PS/Workshop" for more information about adding menu items to PS/Workshop.

Example

The following example adds a Debug menu to PS/Workshop that contains an Analyse command. When the user chooses this command the OnCommand message on the module is called with the CommandID ID_ON_ANALYSE. The & characters specify that the user can press Alt+D+A on the keyboard to access the Analyse command.

HRESULT hr = E_FAIL;
CComBSTR bstrMenuItem( OLESTR("&Debug\n&Analyse") );
hr = m_pAppInterface->AddMenuItem( pApp, bstrMenuItem, ID_ON_ANALYSE, PSW_Menu_Doc);
if ( SUCCEED(hr) )
{   
   // ... do something
}

AddMenuItem2

HRESULT   AddMenuItem
(
--- received arguments ---
   IPSWAddIn *pAddIn, 
   BSTR  CommandName,
   long CommandID, 
   PSW_Menu_Mode mode 
   long menuPos, 
   long itemPos
)

Adds an item to a PS/Workshop menu, specifying the precise position of the menu and menu item. If the menu does not already exist then it is created first.

pAddIn

CommandName

CommandID

mode

menuPos

itemPos

CommandName must be a NULL separated string.

• The last part of the string contains the text of the menu item to add.
• The first part of the string contains the text of the menu to add.

You can add a cascading menu to PS/Workshop by specifying a string that contains more than two parts, as described in the documentation for See AddMenuItem..

You can use & to specify keyboard mnemonics for menus and menu items, as described in the documentation for AddMenuItem.

CommandID contains the ID to be associated with the menu item. This is subsequently passed back to the module during the IPSWEvents::OnCommand event when the user chooses the menu item.

The mode argument may have the following values:

See Chapter 7, "Adding a New Menu Item to PS/Workshop" for more information about adding menu items to PS/Workshop.

The menuPos argument lets you specify the position of the new menu in the PS/Workshop menu bar. Setting this to 0 makes the new menu the first one on the menu bar (at the left), setting it to 1 makes it the second menu, and so on. A value of -1 appends the new menu to the right hand end of the menu bar.

The itemPos argument lets you specify the position of the new menu item in the PS/Workshop menu. Setting this to 0 makes the new item the first one on the menu, setting it to 1 makes it the second item, and so on. A value of -1 appends the new item to the end of the specified menu.

Example

The following example adds a Blend menu to PS/Workshop that contains a Notch command. When the user chooses this command the OnCommand message on the module is called with the CommandID ID_ON_NOTCH. The Blend menu is placed at position 5, which ensures that it appears between the Window and Help menus in PS/Workshop, and the Notch command is placed at position 0, which ensures it is the first command in the Blend menu, regardless of other commands that may have been added.

HRESULT hr = E_FAIL;
CComBSTR bstrMenuItem( OLESTR("Bl&end\nNotch") );
hr = m_pAppInterface->AddMenuItem2( pApp, bstrMenuItem, ID_ON_NOTCH, PSW_Menu_Doc, 5, 0);
if ( SUCCEEDED(hr) )
{   
   // ... do something
}

OpenDocument

HRESULT   OpenDocument
(
--- received arguments ---
   BSTR fileName, 
--- returned arguments ---
   IPSWDoc **ppDoc 
)

Loads a new part from file and opens a corresponding module document.

fileName

ppDoc

Example

// Previously initialised pointer
CComPtr<IPSWApp>         pApp;

// our variable to store the returned interface
CcomPtr<IPSWDoc>  pDoc = NULL;
HRESULT hr = pApp->OpenDocument("c:\\TestDoc.x_b", &pDoc );
if ( SUCCEEDED(hr))
{
   //... do something with the pDoc
}

OpenNewDocument

HRESULT   OpenNewDocument
(
--- returned arguments ---
   IPSWDoc **ppDoc
)

Opens a new document in PS/Workshop.

ppDoc

Usage:

// Previously initialised pointer
CComPtr<IPSWApp>         pApp;

// our variable to store the returned interface
CcomPtr<IPSWDoc>  pDoc = NULL;
HRESULT hr = pApp->OpenNewDocument(&pDoc);
If ( SUCCEEDED(hr))
{
   //... do something with the pDoc
}

CloseDocument

HRESULT   CloseDocument
(
--- received arguments ---
   IPSWDoc  *pDoc 
)

Closes the specified document.

pDoc

QueryPSWModuleInterface

HRESULT   QueryPSWModuleInterface
(
--- received arguments ---
   GUID *riid, 
--- returned arguments ---
   IUnknown **ppUnknown 
)

Queries if a module currently loaded in PS/Workshop supports a particular interface.

riid

ppUnknown

This function behaves in a similar way to IUnknown::QueryInterface. It allows one module to communicate with another module, so that modules can provide functionality to one another.

RegisterFileOpenFunction

HRESULT   RegisterFileOpenFunction
(   
--- received arguments ---
   IPSWAddIn *pAddIn, 
   BSTR description, 
   long CommandID 
)

Registers a function to act as a FileOpen handler, and adds an entry to the PS/Workshop File Open dialog to handle a particular file extension.

pAddIn

description

CommandID

If a registered filetype is subsequently opened from the PS/Workshop File Open dialog, the IPSWEvents::OnCommand function is called on the module with the CommandID of the registered function and a LPCSTR giving the full path name of the file to open.

The supplied description is a specially formatted string that contains information about the file types to associate with the registered function and the accompanying text that appears in the PS/Workshop File Open dialog.

The string must be formatted in the following way:

File Description to appear in the dialog |
File extensions to be associated with the function |

For example, Parasolid text XT files might have the following description:

"Parasolid Files (*.x_t;*.xmt_txt)|*.x_t;*.xmt_txt|"

For more information about registering handlers for filetypes, see Chapter 8, "Registering Handlers for Different Filetypes".

RegisterFileSaveAsFunction

HRESULT   RegisterFileSaveAsFunction
(   
--- received arguments ---
   IPSWAddIn *pAddIn, 
   BSTR description, 
   long CommandID
)

Registers a function to act as a FileSaveAs handler, and adds an entry to the PS/Workshop File Save As dialog to handle a particular file extension.

pAddIn

description

CommandID

If the PS/Workshop File Save As dialog is subsequently used to save a registered filetype, the IPSWEvents::OnCommand function is called on the module with the CommandID of the registered function and a LPCSTR giving the full path name of the file to save.

The supplied description is a specially formatted string that contains information about the file types to associate with the registered function and the accompanying text that appears in the PS/Workshop File Save As dialog.

The string must be formatted in the following way:

File Description to appear in the dialog |
File extensions to be associated with the function |

For example, JPEG files might have the following description:

"JPG Files (*.jpg;*.jpeg)|*.jpg;*.jpeg|"

For more information about registering handlers for filetypes, see Chapter 8, "Registering Handlers for Different Filetypes".

[back to top]

A.3 IPSWDoc

The IPSWDoc interface represents each of the PS/Workshop parts (documents) currently open. For each open document there exists a corresponding IPSWDoc interface pointer. Those functions called from IPSWDoc only affect the associated PS/Workshop document.

[back to top]

A.3.1 Summary

The following is a summary of the IPSWDoc interface.

Properties

Colour

COLORREF

DocumentTitle

BSTR

DrawList

IPSWDrawList*

PartList

IPSWParts*

Rollback

IPSWRollback*

SelectionList

IPSWSelectionList*

Functions

SaveAsBMP

SaveAsXGL

SaveAsWMF

Update

[back to top]

A.3.2 IPSWDoc Properties

Colour

HRESULT   get_Colour
(
--- received arguments ---            
   PK_ENTITY_t pkEnt, 
--- returned arguments ---
   COLORREF *pColour 
)

Returns the colour of the given pkEnt .

pkEnt

pColour

This works on the following classes of Parasolid entity:

• PK_CLASS_face, PK_CLASS_edge, PK_CLASS_vertex, PK_CLASS_body
• PK_CLASS_geom and all subclasses, if the entities are in a draw list

Attempting to return the colour of a geometric entity not in the draw list returns E_FAIL.

HRESULT   put_Colour
(
--- received arguments --- 
   PK_ENTITY_t pkEnt, 
   COLORREF pColour
)

Sets the colour of the given pkEnt .

pkEnt

pColour

This works on the following classes of Parasolid entity:

• PK_CLASS_face, PK_CLASS_edge, PK_CLASS_vertex, PK_CLASS_body
• PK_CLASS_geom and all subclasses, if the entities are in a draw list

Attempting to set the colour of a geometric entity not in the draw list returns E_FAIL.

DocumentTitle

HRESULT   get_DocumentTitle
(      
--- returned arguments ---
   BSTR *pDocTitle 
)

Returns the title of the current document.

pDocTitle

The title of the document appears in the title bar of the PS/Workshop document window, and is also used in the list of currently open documents in the Window menu, and the list of recently used files in the File menu.

HRESULT   put_DocumentTitle
(      
--- received arguments ---
   BSTR DocTitle
)

Sets the title of the current document.

DocTitle

The title of the document appears in the title bar of the PS/Workshop document window, and is also used in the list of currently open documents in the Window menu, and the list of recently used files in the File menu.

DrawList

HRESULT   get_DrawList
(
--- returned arguments ---
   IPSWDrawList **ppDrawList
)

Returns the IPSWDrawList associated with the document.

ppDrawList

PartList

HRESULT   get_PartList
(
--- returned arguments ---
   IPSWParts **ppPartList
)

Returns the IPSWParts associated with the document.

ppPartList

Rollback

HRESULT   get_Rollback
(
--- returned arguments ---
   IPSWRollback **ppRollback
)

Returns the IPSWRollback interface associated with the document.

ppRollback

SelectionList

HRESULT   get_SelectionList
(
--- returned arguments ---
   IPSWSelectionList **ppSelectionList
)

Returns the IPSWSelectionList associated with the document

ppSelectionList

[back to top]

A.3.3 IPSWDoc Functions

SaveAsBMP

HRESULT   SaveAsBMP
(
--- received arguments ---
   LPCTSTR lpszPathName 
)

Saves the current document in Windows bitmap format ( *.bmp ).

lpszPathName

SaveAsXGL

HRESULT   SaveAsXGL
(
--- received arguments ---
   LPCTSTR lpszPathName 
)

Saves the parts in the document in RealityWave format ( *.xgl ).

SaveAsWMF

HRESULT   SaveAsWMF
(
--- received arguments ---
   LPCTSTR lpszPathName 
)

Saves the parts in the document in Enhanced Metafile format ( *.emf ).

lpszPathName

Update

HRESULT   Update
(
--- received arguments ---
   BOOL render
)

Tells PS/Workshop that the parts in the document have changed and forces an update.

render

The render option controls whether the parts in the document should be completely redrawn, and is included for performance reasons. Setting render to FALSE allows you to improve the performance of an operation by ensuring that the document is not redrawn unnecessarily.

The final call in any sequence of calls to Update should pass render as TRUE to ensure that the display is correctly updated.

[back to top]

A.4 IPSWParts

This interface allows control over the number of Parasolid parts in a PS/Workshop document. You can use the functionality in this interface to add, remove, or interrogate parts in a document. It can be obtained from the IPSWDoc interface, and so only affects the associated document.

As an alternative to this interface, you can use direct calls to Parasolid. You might find it easier to use Parasolid functionality directly rather than use this interface. So long as parts have been created in a partition associated with a document, calling IPSWDoc::Update correctly handles the part list whenever necessary. For example, a part can be removed from the part list by calling PK_ENTITY_delete, and then calling Update.

[back to top]

A.4.1 Summary

The following is a summary of the IPSWParts interface.

Properties

_NewEnum

IUnknown*

Count

int

Item

PK_PART_t

Functions

AddItems

IsEmpty

IsMember

RemoveAll

RemoveItems

ReplaceItems

[back to top]

A.4.2 IPSWParts properties

_NewEnum

HRESULT   get__NewEnum
(
--- returned arguments ---
   IUnknown **ppunkEnum 
)

Returns the IPSWEnumParts interface associated with the IPSWParts interface.

This differs from get_Item in that get__NewEnum can be used to return more than one item at a time, so using this property in preference to get_Item could improve performance in some situations.

You can use the IPSWEnumParts interface to enumerate the parts in the IPSWParts interface. For more information see the definition of IPSWEnumParts.

The returned interface only represents a snapshot of the part list. It is not updated if the part list changes.

Count

HRESULT   get_Count
(
--- returned arguments ---
   int *pCount 
)

Returns the number of entities in the part list.

pCount

Item

HRESULT   get_Item
(
---received arguments ---
   int index,
--- returned arguments ---
   PK_PART_t *pEnt 
)

Returns the pEnt at position index in the part list.

index

pEnt

The part list is a zero based index system: index >= 0 and index < n - 1 where n is the number of entities in the list.

This can only be used to return a single item in the part list at a time. To return more than one item, use get__NewEnum.

[back to top]

A.4.3 IPSWParts functions

AddItems

HRESULT   AddItems
(
--- received arguments ---
   int nParts 
   PK_PART_t *pkParts 
)

Adds a list of parts to the part list.

nParts

pkParts

IsEmpty

HRESULT   IsEmpty
(
--- returned arguments ---
   BOOL *Empty 
)

Indicates whether the part list contains any elements.

Empty

Empty is TRUE if the list is empty, FALSE otherwise.

IsMember

HRESULT   IsMember
(
--- received arguments ---
   PK_PART_t pkPart, 
--- returned arguments ---
   BOOL *member 
)

Indicates whether pkPart is a member of the part list.

pkPart

member

Member is TRUE if pkPart is a member of the list, FALSE otherwise.

RemoveAll

HRESULT   RemoveAll
(
)

Removes all the parts in the part list.

RemoveItems

HRESULT   RemoveItems
(
--- received arguments ---
   int nParts 
   PK_PART_t *pkParts 
)

Removes the specified parts from the part list.

nParts

pkParts

ReplaceItems

HRESULT   ReplaceItems
(
--- received arguments ---
   int nNewPartCount
   PK_PART_t *nNewPartCount
)

Replaces all the parts in the list with the specified pNewParts .

nNewPartCount

nNewPartCount

[back to top]

A.5 IPSWSelectionList

This interface allows control over the selection of entities in a PS/Workshop document. It can be obtained from the IPSWDoc interface, and so only affects the associated document.

[back to top]

A.5.1 Summary

The following is a summary of the IPSWSelectionList interface.

Properties

_NewEnum

IUnknown*

Colour

COLORREF

Count

int

Item

PK_ENTITY_t

Functions

AddItems

IsEmpty

IsMember

RemoveAll

RemoveItems

ResetColour

ResetColour2

SetColour

SetColour2

[back to top]

A.5.2 IPSWSelectionList Properties

_NewEnum

HRESULT   get__NewEnum
(
--- received arguments ---
   PK_CLASS_t pkClass 
--- returned arguments ---
   IUnknown **ppunkEnum
)

Returns the IPSWEnumSelectionList interface associated with the IPSWSelectionList.

pkClass

ppunkEnum

This differs from get_Item in that get__NewEnum can be used to return more than one item at a time, so using this property in preference to get_Item could improve performance in some situations.

The IPSWEnumSelectionList interface can be used to enumerate the entities in the IPSWSelectionList interface. For more information see the definition of IPSWEnumSelectionList.

The returned interface only represents a snapshot of the selection list. It is not updated if the selection list changes.

The pkClass argument determines the type of entities in the selection list to enumerate through. This can have the following values:

Colour

HRESULT   get_Colour
(
--- received arguments ---
   PK_ENTITY_t pkEnt, 
--- returned arguments ---
   COLORREF *pColour 
)

Returns the selection colour of the given pkEnt .

pkEnt

pColour

HRESULT   put_Colour
(
--- received arguments ---
   PK_ENTITY_t      pkEnt,       --- The entity
   COLORREF      Colour  --- The new selection colour for pkEnt
)

Sets the selection colour of pkEnt .

Count

HRESULT   get_Count
(
--- received arguments ---
   PK_CLASS_t pkClass 
--- returned arguments ---
   int *pCount 
)

Returns the number of entities in the selection list.

pkClass

pCount

The pkClass argument determines the type of entities in the selection list to enumerate. This can have the following values:

Item

HRESULT   get_Item
(
---received arguments ---
   PK_CLASS_t pkClass 
   int index, 
--- returned arguments ---
   PK_PART_t *pEnt
)

Returns the pEnt at position index in the selection list.

pkClass

index

pEnt

The selection list is a zero based index system: index >= 0 and index < n - 1 where n is the number of entities in the list.

This can only be used to return a single item in the selection list at a time. To return more than one item, use get__NewEnum.

[back to top]

A.5.3 IPSWSelectionList Functions

AddItems

HRESULT   AddItems
(
--- received arguments ---
   int nEnts 
   PK_ENTITY_t *pEnts 
)

Adds a list of parts to the selection list.

nEnts

pEnts

The class of pEnts can be one of the following:

• PK_CLASS_body
• PK_CLASS_edge
• PK_CLASS_vertex
• PK_CLASS_face

IsEmpty

HRESULT   IsEmpty
(
--- returned arguments ---
   BOOL *Empty 
)

Indicates whether the selection list contains any elements.

Empty

Empty is TRUE if the list is empty, FALSE otherwise.

IsMember

HRESULT   IsMember
(
--- received arguments ---
   PK_ENTITY_t pkEnt, 
--- returned arguments ---
   BOOL *member 
)

Indicates whether pkPart is a member of the selection list.

pkEnt

Member is TRUE if pkPart is a member of the list, FALSE otherwise.

RemoveAll

HRESULT   RemoveAll
(
)

Removes all the entities in the selection list.

RemoveItems

HRESULT   RemoveItems
(
--- received arguments ---
   int nEnts 
   PK_ENTITY_t *pkEnts 
)

Removes the specified entities from the selection list.

nEnts

pkEnts

ResetColour

HRESULT   ResetColour
(
)

Resets the selection colour of all the entities in the document.

The default selection color is specified in the Default Colors tab of the Options dialog in PS/Workshop.

ResetColour2

HRESULT   ResetColour2
(
--- received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts 
)

Resets the selection colour for the specified entities.

nEnts

pkEnts

The default selection color is specified in the Default Colors tab of the Options dialog in PS/Workshop.

SetColour

HRESULT   SetColour
(
--- received arguments ---
   COLORREF colour 
)

Sets the selection colour for all entities in the selection list

colour

SetColour2

HRESULT   SetColour2
(
--- received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts, 
   COLORREF colour 
)

Sets the selection colour for the given pkEnts .

nEnts

pkEnts

colour

[back to top]

A.6 IPSWDrawList

This interface allows control over custom drawing of entities in a PS/Workshop document. It can be obtained from the IPSWDoc interface, and so only affects the associated document.

[back to top]

A.6.1 Summary

The following is a summary of the IPSWDrawList interface.

Properties

_NewEnum

IUnknown*

Count

int

DrawOptions

IPSWDrawOpts*

Item

PK_ENTITY_t

Functions

AddItems

AddItems2

IsEmpty

IsMember

ModifyItems

RemoveAll

RemoveItems

Update

[back to top]

A.6.2 IPSWDrawList properties

_NewEnum

HRESULT   get__NewEnum
(
--- returned arguments ---
   IUnknown **ppunkEnum 
)

Returns the IPSWEnumDrawList interface associated with the IPSWDrawList interface.

This differs from get_Item in that get__NewEnum can be used to return more than one item at a time, so using this property in preference to get_Item could improve performance in some situations.

Count

HRESULT   get_Count
(
--- returned arguments ---
   int *pCount 
)

Returns the number of entities in the draw list.

pCount

DrawOptions

HRESULT   get__DrawOptions
(
--- received arguments ---
   PK_ENTITY_t pkEnt, 
--- returned arguments ---
   IPSWDrawOpts **ppDrawOpts 
)

Returns the IPSWDrawOpts interface associated with the IPSWDrawList interface

pkEnt

ppDrawOpts

Item

HRESULT   get_Item
(
--- received arguments ---
   int index,  
--- returned arguments ---
   PK_ENTITY_t *pEnt
)

Returns the pEnt at position index in the draw list.

index

pEnt

The draw list is a zero based index system: index >= 0 and index < n - 1 where n is the number of entities in the list.

This can only be used to return a single item in the draw list at a time. To return more than one item, use get__NewEnum.

[back to top]

A.6.3 IPSWDrawList functions

AddItems

HRESULT   AddItems
(
--- received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts 
)

Add entities to the draw list using the default draw options

nEnts

pkEnts

The following entity classes are allowed:

• PK_CLASS_body
• PK_CLASS_face
• PK_CLASS_edge
• PK_CLASS_vertex
• PK_CLASS_curve, and all subclasses
• PK_CLASS_surf, and all subclasses
• PK_CLASS_point

Any given entity must appear once and only once in the draw list. Attempting to add an item for the second time produces the error PSWERR_ITEMALREADYEXISTS

AddItems2

HRESULT   AddItems2
(
--- received arguments ---
   int nEnts,
   PK_ENTITY_t *pkEnts, 
   IPSWDrawOpts *pDrawOpts 
)

Add Items to the draw list using the draw options specified by pDrawOpts .

nEnts

pkEnts

pDrawOpts

The following entity classes are allowed:

• PK_CLASS_body
• PK_CLASS_face
• PK_CLASS_edge
• PK_CLASS_vertex
• PK_CLASS_curve, and all subclasses
• PK_CLASS_surf, and all subclasses
• PK_CLASS_point

Any given entity must appear once and only once in the draw list. Attempting to add an item for the second time produces the error PSWERR_ITEMALREADYEXISTS

IsEmpty

HRESULT   IsEmpty
(
--- returned arguments ---
   BOOL *Empty 
)

Indicates whether the draw list contains any elements.

Empty

Empty is TRUE if the list is empty, FALSE otherwise.

IsMember

HRESULT   IsMember
(
--- received arguments ---
   PK_ENTITY_t pkEnt, 
--- returned arguments ---
   BOOL *member 
)

Indicates whether pkEnt is a member of the list.

pkEnt

member

Member is TRUE if pkPart is a member of the list, FALSE otherwise.

ModifyItems

HRESULT   ModifyItems
(
--- received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts, 
   IPSWDrawOpts *pDrawOpts 
)

Modifies the draw options for the specified pkEnts .

nEnts

pkEnts

pDrawOpts

RemoveAll

HRESULT   RemoveAll
(
)

Removes all the entities in the draw list.

RemoveItems

HRESULT   RemoveItems
(
--- received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts 
)

Removes the given entities from the draw list.

nEnts

pkEnts

Update

HRESULT   Update
(
--- received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts 
)

Forces an update (re-render) of the given entities in the draw list.

nEnts

pkEnts

[back to top]

A.7 IPSWDrawOpts

This interface can be obtained from IPSWDrawList (in which case it contains the current draw options). It provides control over how particular entities are displayed in the draw list.

IPSWDrawOpts is somewhat different from other interfaces, in that it can also be instantiated and passed to the IPSWDrawList interface (in which case it contains the new draw options). To instantiate this interface, you need to use the CoCreateInstance function, as described in Section 3.2, "Creating a COM object".

[back to top]

A.7.1 Summary

The following is a summary of the IPSWDrawOpts interface.

Properties

Clip

BOOL

Colour

COLORREF

DrawSense

BOOL

N_U

int

N_V

int

Tolerance

BOOL

ToleranceColour

COLORREF

Functions

Init

Reset

[back to top]

A.7.2 IPSWDrawOpts Properties

Clip

HRESULT   get_Clip
(
--- returned arguments ---
   BOOL *pVal 
)

Returns the clip option for the entity.

This option is currently ignored.

HRESULT   put_Clip
(
--- received arguments ---
   BOOL newVal 
)

Sets the clip option for the entity.

newVal

This option is currently ignored.

Colour

HRESULT   get_Colour
(
--- returned arguments ---
   COLORREF *pColour 
)

Returns the draw colour for the entity.

pColour

HRESULT   put_Colour
(
--- received arguments ---
   COLORREF Colour 
)

Sets the draw colour for the entity.

Colour

Specifying Colour as -1 draws the entity in the default colour.

DrawSense

The DrawSense flag is only valid for entities of the following classes:

• PK_CLASS_face
• PK_CLASS_edge
• PK_CLASS_curve
• PK_CLASS_surf

If this flag is set for other class types it is ignored.

In the case of faces and surfaces, setting DrawSense to TRUE displays a face/surface normal in the same colour as the face/surface. For edges/curves an arrow is drawn depicting the direction going from the low to the high parameter.

HRESULT   get_DrawSense
(
--- returned arguments ---
   BOOL *pValue 
)

Gets the draw sense option for the entity

pValue

HRESULT   put_DrawSense
(
--- received arguments ---
   BOOL newVal 
)

Sets the draw sense for the entity

N_U

The N_U flag is only valid for entities of class PK_CLASS_surf. It is ignored for all other entity classes.

HRESULT   get_N_U
(
--- returned arguments ---
   int *pVal 
)

Returns the number of u parameter lines for the entity.

pVal

HRESULT   put_N_U
(
--- received arguments ---
   int newVal 
)

Sets the number of U parameter lines for the entity.

newVal

N_V

The N_V flag is only valid for entities of class PK_CLASS_surf. It is ignored for all other entity classes.

HRESULT   get_N_V
(
--- returned arguments ---
   int *pVal 
)

Returns the number of v parameter lines for the entity.

pVal

HRESULT   put_N_V
(
--- received arguments ---
   int newVal 
)

Sets the number of V parameter lines for the entity.

newVal

Tolerance

This option is only valid for entities of class PK_CLASS_edge and class PK_CLASS_vertex. It is ignored for all other entity classes. In addition, this option only has a visible effect if the edge or vertex is tolerant.

• For tolerant edges, a tube is displayed around the edge with the same radius as the edge tolerance.
• For tolerant vertices, a sphere based on the point of the vertex is displayed with the same radius as the vertex tolerance.

HRESULT   get_Tolerance
(
--- returned arguments ---
   BOOL *pVal
--- 
)

Returns whether the tolerance of an entity should be displayed.

pVal

HRESULT   put_Tolerance
(
--- received arguments ---
   BOOL newVal 
)

Sets whether the tolerance of an entity should be displayed

newVal

ToleranceColour

This option is only used if the Tolerance option is set. As with Tolerance , this option is only valid for entities of class PK_CLASS_edge and PK_CLASS_vertex. It is ignored for all other entity classes.

If the ToleranceColour is not set then the tolerance is displayed in the same colour as the entity.

HRESULT   get_ToleranceColour
(
--- returned arguments ---
   COLORREF *pVal 
)

Returns the colour in which to draw the tolerance of an entity.

pVal

This function is currently not implemented and returns E_NOTIMPL.

HRESULT   put_ToleranceColour
(
--- received arguments ---
   COLORREF newVal 
)

Sets the colour in which to draw the tolerance of an entity.

newVal

This function is currently not implemented and returns E_NOTIMPL.

[back to top]

A.7.3 IPSWDrawOpts Functions

Init

HRESULT   Init
( 
--- received arguments ---
   int n_u, 
   int n_v, 
   COLORREF col, 
   BOOL clipToPartBox, 
   BOOL drawSense, 
   BOOL tolerance 
)

Allows a number of draw options to be set in one function call.

n_u

n_v

col

clipToPartBox

drawSense

tolerance

Reset

HRESULT   Reset
(
)

Resets the draw options to their default values.

[back to top]

A.8 IPSWRollback

This interface provides access to Parasolid partitioned rollback functionality. It can be obtained from the IPSWDoc interface, and so only affects the associated document.

[back to top]

A.8.1 Summary

The following is a summary of the IPSWRollback interface.

Functions

DeletePMark

MakePMark

RollbackTo

[back to top]

A.8.2 IPSWRollback functions

DeletePMark

HRESULT   DeletePMark
(
--- received arguments ---
   PK_PMARK_t pMark 
)

Deletes an existing pMark .

pMark

MakePMark

HRESULT   MakePMark
(
--- returned arguments ---
   PK_PMARK_t *pMark 
)

Creates a new pMark .

pMark

RollbackTo

HRESULT   RollbackTo
(
--- received arguments ---
   PK_PMARK_t *pMark,
   BOOL del 
)

Rollback the document to the specified pMark .

pMark

del

The del argument controls whether to delete pMark after rolling back to it. If del is TRUE then pMark is deleted, and also returned by the function as PK_ENTITY_null.

[back to top]

A.9 IPSWEnumDrawList

Provides enumeration over the entities in the draw list

This interface can be obtained from the IPSWDrawList interface using the IPSWDrawList::_NewEnum property. Once obtained the interface can be used to enumerate over all the entities in the IPSWDrawList. Note that the _NewEnum property returns a snapshot of the IPSWDrawList and is not updated if the draw list is changed externally.

[back to top]

A.9.1 Summary

The following is a summary of the IPSWEnumDrawList interface.

Functions

Clone

Next

Reset

Skip

[back to top]

A.9.2 IPSWEnumDrawList functions

Clone

HRESULT   Clone
(
--- returned arguments ---
   IPSWEnumDrawList **ppenum 
)

Creates another enumerator that contains the same enumeration state as the current one.

ppenum

If the function succeeds then ppenum is a pointer to a new IPSWEnumDrawList. If the function fails then the value of ppenum is undefined.

Next

HRESULT   Next
(
--- received arguments ---
   ULONG celt, 
--- returned arguments ---
   PK_ENTITY_t *rgelt, 
   ULONG *pceltFetched 
)

Retrieves the next celt items in the enumeration sequence.

celt

rgelt

pceltFetched

If there are fewer than the requested items left in the sequence, this function retrieves the remaining elements. The number of elements actually retrieved is returned in the pceltFetched argument.

Reset

HRESULT   Reset
(
)

Resets the enumeration sequence to the beginning.

Skip

HRESULT   Skip
(
--- received arguments ---
   ULONG celt 
)

Skips over the next specified number of elements in the enumeration sequence.

celt

[back to top]

A.10 IPSWEnumParts

Provides enumeration over the entities in the part list

This interface can be obtained from the IPSWParts interface using the IPSWParts::_NewEnum property. Once obtained the interface can be used to enumerate over all the entities in the IPSWParts. Note that the _NewEnum property returns a snapshot of the IPSWParts and is not updated if the number of parts in the document are changed externally.

[back to top]

A.10.1 Summary

The following is a summary of the IPSWEnumParts interface.

Functions

Clone

Next

Reset

Skip

[back to top]

A.10.2 IPSWEnumParts functions

Clone

HRESULT   Clone
(
--- returned arguments ---
   IPSWEnumParts **ppenum 
)

Creates another enumerator that contains the same enumeration state as the current one

ppenum

If the function succeeds then ppenum is a pointer to a new IPSWEnumParts. If it fails then the value of ppenum is undefined.

Next

HRESULT   Next
(
--- received arguments ---
   ULONG celt, 
--- returned arguments ---
   PK_PART_t *rgelt, 
   ULONG *pceltFetched 
)

Retrieves the next celt items in the enumeration sequence.

rgelt

pceltFetched

If there are fewer than the requested items left in the sequence, this function retrieves the remaining elements. The number of elements actually retrieved is returned in the pceltFetched argument.

Reset

HRESULT   Reset
(
)

Resets the enumeration sequence to the beginning.

Skip

HRESULT   Skip
(
--- received arguments ---
   ULONG celt 
)

Skips over the next specified number of elements in the enumeration sequence.

celt

[back to top]

A.11 IPSWEnumSelectionList

Provides enumeration over the entities in the selection list.

This interface can be obtained from the IPSWSelectionList interface using the IPSWSelectionList::_NewEnum property. Once obtained the interface can be used to enumerate over all the entities in the IPSWSelectionList. It should be noted that the _NewEnum property returns a snapshot of the IPSWSelectionList and is not updated if the selection list is changed externally.

[back to top]

A.11.1 Summary

The following is a summary of the IPSWEnumSelectionList interface.

Functions

Clone

Next

Reset

Skip

[back to top]

A.11.2 IPSWEnumSelectionList functions

Clone

HRESULT   Clone
(
--- returned arguments ---
   IPSWEnumSelectionList **ppenum
)

Creates another enumerator that contains the same enumeration state as the current one.

ppenum

If the function succeeds then ppenum is a pointer to a new IPSWEnumSelectionList. If it fails then the value of ppenum is undefined.

Next

HRESULT   Next
(
--- received arguments ---
   ULONG celt, 
--- returned arguments ---
   PK_ENTITY_t *rgelt, 
   ULONG *pceltFetched 
)

Retrieves the next celt items in the enumeration sequence.

celt

rgelt

pceltFetched

If there are fewer than the requested items left in the sequence, this function retrieves the remaining elements. The number of elements actually retrieved is returned in the pceltFetched argument.

Reset

HRESULT   Reset
(
)

Resets the enumeration sequence to the beginning.

Skip

HRESULT   Skip
(
--- received arguments ---
   ULONG celt 
)

Skips over the next specified number of elements in the enumeration sequence.

celt

[back to top]

A.12 IPSWView

This interface is superseded by IPSWView2.

[back to top]

A.13 IPSWView2

Each document open in PS/Workshop has one or more views attached. Each IPSWView is associated with an IPSWDoc.

[back to top]

A.13.1 Summary

The following is a summary of the IPSWView interface.

Properties

ViewMatrix

PK_TRANSF_t

CurrentOperation

pswCurrentOperation

ViewStyle

pswViewStyle

SelectionFilter

pswSelectionFilter

RenderFacetOpts

void*

RenderLineOpts

void*

ViewCentre

double*

Functions

FitToScreen

ResetRenderOptions

ScaleView

ZoomToEntities

RotateView

Update

[back to top]

A.13.2 IPSWView2 properties

ViewMatrix

HRESULT   get_ViewMatrix
(
--- returned arguments ---
   PK_TRANSF_t *pVal 
)

Returns the current view matrix.

pVal

HRESULT   put_ViewMatrix
(
--- received arguments ---
   PK_TRANSF_t newVal 
)

Sets the current view matrix.

newVal

CurrentOperation

HRESULT   get_CurrentOperation
(
--- returned arguments ---
   pswCurrentOperation *pVal 
)

Returns the current PS/Workshop operation.

pVal

pVal may be one of the following values:

• pswCurrentOperationIdle
• pswCurrentOperationRotate
• pswCurrentOperationZoom
• pswCurrentOperationZoomWindow
• pswCurrentOperationPan

HRESULT   put_CurrentOperation
(
--- received arguments ---
   pswCurrentOperation newVal 
)

Sets the current PS/Workshop operation.

newVal

newVal may be one of the following values:

• pswCurrentOperationIdle
• pswCurrentOperationRotate
• pswCurrentOperationZoom
• pswCurrentOperationZoomWindow
• pswCurrentOperationPan

ViewStyle

HRESULT   get_ViewStyle
(
--- returned arguments ---
   pswViewStyle *pVal 
)

Returns the current view style.

pVal

pVal may be one of:

• pswViewStyleShaded
• pswViewStyleWireframe
• pswViewStyleWireAndSils
• pswViewStyleShadedWireAndSils
• pswViewStyleHidden
• pswViewStyleShadedWireframe

HRESULT   put_ViewStyle
(
--- received arguments ---
   pswViewStyle newVal 
)

Sets the current view style.

newVal may be one of:

• pswViewStyleShaded
• pswViewStyleWireframe
• pswViewStyleWireAndSils
• pswViewStyleShadedWireAndSils
• pswViewStyleHidden
• pswViewStyleShadedWireframe

SelectionFilter

HRESULT   get_SelectionFilter
(
--- returned arguments ---
   pswSelectionFilter *pVal 
)

Returns the current selection filter.

pVal

pVal may be any combination of the following flags:

• pswSelectionFilter_None
• pswSelectionFilter_Edge
• pswSelectionFilter_Face
• pswSelectionFilter_Vertex
• pswSelectionFilter_Body
• pswSelectionFilter_All

HRESULT   put_SelectionFilter
(
--- received arguments ---
   pswSelectionFilter newVal
)

Sets the current selection filter.

newVal

newVal may be any combination of the following flags:

• pswSelectionFilter_None
• pswSelectionFilter_Edge
• pswSelectionFilter_Face
• pswSelectionFilter_Vertex
• pswSelectionFilter_Body
• pswSelectionFilter_All

RenderFacetOpts

HRESULT   get_RenderFacetOpts
(
--- returned arguments ---
   void *pVal 
)

Returns the current facetting options.

pVal

HRESULT   put_RenderFacetOpts
(
--- returned arguments ---
   void *newVal
)

Sets the current facetting options.

newVal

RenderLineOpts

HRESULT   get_RenderLineOpts
(
--- returned arguments ---
   void *pVal 
)

Returns the current line rendering options.

pVal

HRESULT   put_RenderLineOpts
(
--- returned arguments ---
   void *newVal 
)

Sets the current line rendering options.

newVal

ViewCentre

HRESULT   get_ViewCentre
(
--- returned arguments ---
   double pVal[3] 
)

Returns the current view centre

pVal

pVal is the current view centre where:

• pVal[0] represents the x component
• pVal[1] represents the y component
• pVal[2] represents the z component

HRESULT   put_ViewCentre
(
--- received arguments ---
   double newVal[3] 
)

Sets the current view centre

newVal

newVal is the current view centre where:

• newVal[0] represents the x component
• newVal[1] represents the y component
• newVal[2] represents the z component

[back to top]

A.13.3 IPSWView2 functions

FitToScreen

HRESULT   FitToScreen
(
)

Recalculates the view to fit all the parts in the document on the screen.

ResetRenderOptions

HRESULT   ResetRenderOptions
(
)

Resets the render options to their default values.

This function returns full control of the rendering to PS/Workshop.

ScaleView

HRESULT   ScaleView
(
--- received arguments ---
   double factor 
)

Scales the view by the given factor .

factor

If factor < 1 then the view zooms out. If factor is > 1 then the view zooms in.

ZoomToEntities

HRESULT   ZoomToEntities
(
---received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts 
)

Zooms to the given entities.

nEnts

pkEnts

The following classes of entities are supported:

• PK_CLASS_assembly
• PK_CLASS_body
• PK_CLASS_face
• PK_CLASS_edge
• PK_CLASS_vertex
• PK_CLASS_point
• PK_CLASS_curve, and all subclasses
• PK_CLASS_surf, and all subclasses

RotateView

HRESULT   RotateView
(
--- received arguments ---
   double angle, 
   double *axis 
)

Rotates the view about the given axis .

angle

axis

• axis[0] represents the x component of axis
• axis[1] represents the y component of axis
• axis[2] represents the z component of axis

Update

HRESULT   Update
(
--- received arguments ---
   int nEnts, 
   PK_ENTITY_t *pkEnts 
)

Forces an update (re-render) of the given entities.

nEnts

pkEnts

This function updates the folllowing Parasolid entity classes:

• PK_CLASS_body
• PK_CLASS_assembly
• PK_CLASS_face
• PK_CLASS_edge
• PK_CLASS_vertex
• PK_CLASS_curve, and all subclasses (if in the draw list)
• PK_CLASS_surf, and all subclasses (if in the draw list)
• PK_CLASS_point (if in the draw list)

[back to top]

A.14 IPSWAddIn

Provides the connection/disconnection mechanism for a module. Every PS/Workshop module must support this interface.

[back to top]

A.14.1 Summary

The following is a summary of the IPSWAddIn interface.

Functions

OnConnection

OnDisconnection

[back to top]

A.14.2 IPSWAddIn functions

OnConnection

HRESULT   OnConnection
(
--- received arguments ---
   IDispatch *pIPSWApp, 
   IDispatch *pIPSWAddIn,
   PswConnectMode eConnectMode
)

This function is called whenever a module is loaded.

pIPSWApp

pIPSWAddIn

eConnectMode

The eConnectMode argument determines how the module was loaded. It can have one of the following values:

pswConnectAtStartUp

pswConnectByUser

pswConnectExternally

PS/Workshop calls this function on a module when it attempts to load it. If this returns an error code then PS/Workshop unloads the module. In the default implementation this calls CAddonMain:StartModule.

OnDisconnection

HRESULT   OnDisconnection
(
--- received arguments ---
   pswDisconnectMode DisconnectMode
)

This function is called when the module is disconnected.

DisconnectMode

The pswDisconnectMode argument determines how the module came to be unloaded. It may have the following values:

pswDisconnectAtShutdown

pswDisconnectByUser

pswDisconnectExternally

This function on a module is called immediately before the module is unloaded. It is suggested that during this function the module ensures that all references to PS/Workshop interfaces are released.

[back to top]

A.15 IPSWEvents

Provides notification of PS/Workshop events to a module

[back to top]

A.15.1 Summary

The following is a summary of the IPSWEvents interface.

Functions

OnCommand

OnCommandHelp

OnCommandUpdateUI

OnDocClose

OnDocOpen

OnPartChange

OnSelectTopols

OnViewClose

OnViewOpen

[back to top]

A.15.2 IPSWEvents functions

OnCommand

HRESULT   OnCommand
(
--- received arguments ---
   long CommandID, 
   void *lparam 
)

Called whenever a menu item added by a module is selected, or a file of a registered filetype is chosen.

CommandID

lparam

This event may occur in the following cases:

OnCommandHelp

HRESULT   OnCommandHelp
(
--- received arguments ---
   long hFrameWnd,
   long HelpCommandID,
   long CommandID
)

Called whenever help is requested about a menu item added by a module.

This function is currently not implemented and returns E_NOTIMPL.

OnCommandUpdateUI

HRESULT   OnCommandUpdateUI
(
--- received arguments ---
   long CommandID,
--- returned arguments --- 
   long *CommandFlags, 
   BSTR *MenuItemText,
   long *BitmapID
)

Called to update the user interface for a menu item added by a module.

CommandID

CommandFlags

MenuItemText

BitmapID

This function is called by the framework to update the status of user added menu items. CommandID is the ID previously passed to IPSWApp::AddMenuItem or AddMenuItem2 for a particular menu item.

You can use CommandFlags to change the status of a menu item. It can take any of the following values:

The MenuItemText argument controls the text that is associated with the menu item, so that the text seen by the user can be changed on the fly, in conjunction with the value of CommandFlags .

OnDocClose

HRESULT   OnDocClose
(
--- received arguments ---
   IPSWDoc* pDoc 
)

Called whenever a PS/Workshop document is closed.

pDoc

This event only occurs after the associated OnViewClose event.

OnDocOpen

HRESULT   OnDocOpen
(
--- received arguments ---
   IPSWDoc* pDoc 
)

Called whenever a PS/Workshop document is opened.

pDoc

This event occurs before the associated OnViewOpen event.

OnPartChange

HRESULT   OnPartChange
(
)

Called whenever the parts in a document change.

This function is called whenever the number of parts in any document change, or the parts themselves change. It is not called if any sub-entities of the part are modified.

OnSelectTopols

HRESULT   OnSelectTopols
(
)

Called whenever a selection event occurs inside PS/Workshop.

This function is called whenever an entity is selected or deselected in any document. The selected entities can then be found using the IPSWSelectionList interface.

OnViewClose

HRESULT   OnViewClose
(
--- received arguments ---
   IPSWDoc *pDoc, 
   IPSWView *pView 
)

Called whenever the PS/Workshop view is closed.

pDoc

pView

This function is called before any subsequent call to OnDocClose.

As of PS/Workshop 2.1, pView can be query-interfaced to IPSWView.

OnViewOpen

HRESULT   OnViewOpen
(
--- received arguments ---
   IPSWDoc *pDoc, 
   IPSWView *pView 
)

Called whenever the PS/Workshop view is opened.

pDoc

pView

This function is called after any call to OnDocOpen.

[back to top]