Module Structure

<<< Event Handling Within A Module

Chapters

The PS/Workshop Interfaces >>>

Contents

• 5.1 CAddinImpl
• 5.2 CXXXApp
  • 5.2.1 CXXXApp Functions
• 5.3 CAddonMain
  • 5.3.1 Summary
  • 5.3.2 CAddonMain functions
• 5.4 CAddonDoc
  • 5.4.1 Summary
  • 5.4.2 CAddonDoc functions
• 5.5 CAddonView
  • 5.5.1 Summary
  • 5.5.2 CAddonView functions

This chapter describes the module structure that is created for you automatically when you use the PS/Workshop AppWizard as a basis for a new module. The relationships between the classes produced are detailed in Figure 5-1. A more in-depth description of each class is given in the rest of this chapter. See Appendix A, "Interface Functions" for a description of the interfaces that each class supports.

Figure 5-1 Overview of the structure of a module created using the AppWizard

[back to top]

5.1 CAddinImpl

The CAddinImpl class receives all events and messages from PS/Workshop and passes them to the encapsulated CAddonMain class.

It is also responsible for instantiating the class itself (IPSWAddIn::OnConnection) and deleting the class (IPSWAddIn::OnDisconnection).

This class supports both the IPSWAddIn and IPSWEvents interfaces. During the initial IPSWAddIn::OnConnection event, CAddinImpl creates an instance of the CAddonMain class. Subsequent messages from PS/Workshop are passed to this encapsulated CAddonMain object.

CAddinImpl has a single data member:

CAddonMain *m_pMain

[back to top]

5.2 CXXXApp

The CXXXApp class is an MFC-generated module application object, and is provided as part of the MFC framework of the module. You should place any initialisation code for a module in either the CAddinImpl or CAddonMain classes, rather than this class.

[back to top]

5.2.1 CXXXApp Functions

CXXXApp contains the following functions.

InitInstance

BOOL InitInstance()

Performs initialisation of the module.

ExitInstance

int ExitInstance()

Performs clean-up of the application.

[back to top]

5.3 CAddonMain

The CAddonMain class receives all events and messages from the CAddinImpl class. These can either be handled by the appropriate message handler in CAddonMain, or passed on to CAddonDoc for handling.

[back to top]

5.3.1 Summary

The following is a summary of the CAddonMain class.

CComQIPtr<IPSWApp> m_pAppInterface

CMap<IPSWDoc*, IPSWDoc*, CAddonDoc*, CAddonDoc* > m_InterfaceVsDocMap

OnDocClose

OnDocOpen

OnPartChange

OnSelectTopols

OnViewClose

OnViewOpen

OnCmdMsg

GetActiveDocument

CAddonDoc*

StartModule

OnAppDestroy

[back to top]

5.3.2 CAddonMain functions

CAddonMain contains the following functions.

CAddonMain

Constructor

CAddonMain
(
--- received arguments ---
   IDispatch *pIPSWApp 
)

Constructs a CAddonMain object.

pIPSWApp

OnDocClose

Message handler

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

Handles the IPSWEvents::OnDocClose event.

pDoc

This function traverses the interface/document map (m_pInterfaceVsDocMap) and passes the event to the correct document to handle.

OnDocOpen

Message handler

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

Handles the IPSWEvents::OnDocOpen event.

pDoc

This function creates a new CAddonDoc object and adds this to the interface/document map (m_pInterfaceVsDocMap).

OnPartChange

Message handler

HRESULT OnPartChange()

Handles the IPSWEvents::OnPartChange event.

This function passes the event to each of the documents.

OnSelectTopols

Message handler

HRESULT OnSelectTopols()

Handles the IPSWEvents::OnSelectTopols event.

This function passes the event to each of the documents.

OnViewClose

Message handler

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

Handles the IPSWEvents::OnViewClose event.

pDoc

pView

This function traverses the interface/document map (m_pInterfaceVsDocMap) for the associated document and passes the event to it.

OnViewOpen

Message handler

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

Handles the IPSWEvents::OnViewOpen event.

pDoc

pView

This function traverses the interface/document map (m_pInterfaceVsDocMap) and passes the event to the correct CAddonDoc.

OnCmdMsg

Message handler

HRESULT  OnCmdMsg
(
--- received arguments ---
   UINT  nID,            
   void *lpparam = NULL   
)

Handles the IPSWEvents::OnCommand event.

nID

lpparam

The OnCmdMsg function looks for the function associated with the ID in the CAddonMain class. If it fails to find one, the event is passed to the CAddonDoc class to handle.

GetActiveDocument

Module method

CAddonDoc* GetActiveDocument()

This function returns the currently active CAddonDoc class. If there is no currently active document it returns NULL.

StartModule

Initializer

HRESULT  StartModule
(
--- received arguments ---
   IPSWAddIn *pApp  
)

This function handles initialisation of the PS/Workshop module. It is called as a result of IPSWAddIn::OnConnection.

pApp

You should add any one-time initialisation code for your module here. This includes code for adding menu items, as well as registering any callback functions.

If this function returns a failure code then the CAddinImpl::OnConnection deletes the CAddonMain class and itself returns a failure which forces PS/Workshop to unload the module.

OnAppDestroy

Destructor

HRESULT  OnAppDestroy()

This function handles destruction of the module. It is called as a result of IPSWAddIn::OnDisconnection.

OnAppDestroy traverses the interface/document map (m_pInterfaceVsDocMap) deleting each document.

[back to top]

5.4 CAddonDoc

The CAddonDoc class represents a module document that shadows the current PS/Workshop document.

[back to top]

5.4.1 Summary

The following is a summary of the CAddonDoc class.

CAddonMain *m_addonMain	

int m_nParts

PK_PART_t *m_pkParts

CComPtr<IPSWDoc> m_pDocInterface

CComPtr<IPSWParts> m_pPartList

CComPtr<IPSWSelectionList> m_pSelectionList

CComPtr<IPSWDrawList> m_pDrawList

CcomPtr<IPSWRollback> m_pRollback

CMap< IPSWView*, IPSWView*, CAddonView*, CAddonView* > m_InterfaceVsViewMap

CAddonDoc

OnDocClose

OnPartChange

OnSelectTopols

OnViewClose

OnViewOpen

OnCmdMsg

CComPtr<IPSWDoc>& GetDocumentInterface

CComPtr<IPSWSelectionList>& GetSelectionInterface

CComPtr<IPSWDrawList>& GetDrawInterface

CComPtr<IPSWParts>& GetPartInterface

CComPtr<IPSWRollback>& GetRollbackInterface

GetActiveView

CAddonView*

GetParts

HRESULT

OnMyFunction

[back to top]

5.4.2 CAddonDoc functions

CAddonDoc contains the following functions.

CAddonDoc

Constructor

CAddonDoc
(
--- received arguments ---
   IPSWDoc *pDoc, 
   CAddonMain *pMain
)

This function constructs a CAddonDoc object and sets the values of the following interfaces:

• IPSWSelectionList
• IPSWDrawList
• IPSWRollback
• IPSWParts

pDoc

pMain

The CAddonDoc constructor also queries and sets the correct values for m_nParts and m_pkParts.

OnDocClose

Message handler

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

This function handles any CAddonMain::OnDocClose events passed to it from CAddonMain.

pDoc

It traverses the view/interface map (m_InterfaceVsViewMap) and deletes the associated view.

OnPartChange

Message handler

HRESULT OnPartChange()

This function handles the CAddonMain::OnPartChange events passed to it from CAddonMain.

It does the following:

• Deletes the m_pkParts array, which stores a copy of the parts in the document.
• Sets m_nparts (the length of m_pkParts ) to zero.
• Gets the parts in the document from PS/Workshop again, and places them in m_pkParts .
• Sets m_nparts accordingly.

OnSelectTopols

Message handler

HRESULT OnSelectTopols()

This function handles the CAddonMain::OnSelectTopols events passed to it from CAddonMain.

Events can either be handled here or passed to the active view using the CAddonView class.

OnViewClose

Message handler

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

This function handles the CAddonMain::OnViewClose events passed to it from CAddonMain.

pDoc

pView

It traverses the view/interface map (m_InterfaceVsViewMap) and deletes the associated view.

OnViewOpen

Message handler

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

This function handles the CAddonMain::OnViewOpen events passed to it from CAddonMain.

pDoc

pView

It traverses the view/interface map (m_InterfaceVsViewMap) and opens the associated view.

OnCmdMsg

Message handler

HRESULT  OnCmdMsg
(
--- received arguments ---
   UINT nID, 
   void *lpparam = NULL 
)

This function handles CAddonMain::OnCmdMsg events passed to it from CAddonMain.

nID

lpparam

It looks for a handler for the nID message in the CAddonDoc class. If it is unable to find a handler then the event is passed to the CAddonView class.

GetDocumentInterface

Interface access function

CComPtr<IPSWDoc>& GetDocumentInterface()

This function returns the IPSWDoc interface.

GetSelectionInterface

Interface access function

CComPtr<IPSWSelectionList>& GetSelectionInterface()

This function returns the IPSWSelectionList interface.

GetDrawInterface

Interface access function

CComPtr<IPSWDrawList>& GetDrawInterface()

This function returns the IPSWDrawList interface.

GetPartInterface

Interface access function

CComPtr<IPSWParts>& GetPartInterface()

This function returns the IPSWParts interface.

GetRollbackInterface

Interface access function

CComPtr<IPSWRollback>& GetRollbackInterface()

This function returns the IPSWRollback interface.

GetActiveView

Module method

CAddonView* GetActiveView()

This function returns the currently active view. If there is no active view then this will return NULL.

GetParts

Module method

HRESULT  GetParts
(
--- returned arguments ---
   int &nParts, 
   PK_PART_t *&pkParts 
)

This function returns the number of parts in the document. It interrogates and returns a copy of the parts in the PS/Workshop document.

&nParts

&pkParts

This function allocates an array of the parts in PS/Workshop. It is up to the module to correctly free the returned array, using delete[] .

OnMyFunction

Custom function

HRESULT OnMyFunction()

This function is supplied to demonstrate the message handling functionality.

When the module as created by the AppWizard is compiled and built, a new menu item is added to PS/Workshop. OnMyFunction is called when the user clicks on this new menu item. OnMyFunction simply displays a message indicating that this function has been reached.

[back to top]

5.5 CAddonView

The CAddonView class represents a module view that shadows the current PS/Workshop view.

[back to top]

5.5.1 Summary

The following is a summary of the CAddonView class.

CAddonDoc* m_doc

CComQIPtr<IPSWView2> m_pViewInterface

CAddonView

OnCmdMsg 

CComQIPtr<IPSWView2>& GetViewInterface

[back to top]

5.5.2 CAddonView functions

CAddonView contains the following functions.

CAddonView

Constructor

CAddonView
( 
--- received arguments ---
   IPSWView *pView, 
   CAddonDoc *pDoc 
)

This function constructs the CAddonView object.

pView

pDoc

OnCmdMsg

Message handler

HRESULT OnCmdMsg
(
--- received arguments ---
   UINT nID,   
   void *lpparam  
)

This function handles the CAddonDoc::OnCmdMsg message.

nID

lpparam

GetViewInterface

Interface access function

CComQIPtr<IPSWView2>& GetViewInterface()

This function returns the encapsulated IPSWView2 interface.

[back to top]