[[Category:OOBasicCode]]
*'''Site''': http://www.oooforum.org/forum/viewtopic.phtml?t=5057&highlight=frame+controller+model
*'''Autor''': DannyB

There are three objects that you typically associate with a document. There is:
#the document model
#the document controller
#the document frame.

When you need to do something to a document, you need one of these three objects. Which one of the three you need depends on what you intend to do.

Calling loadComponentFromURL() always gives you the document model object. OOo Basic also has a "variable" called ThisComponent which returns the document model of the document that contains the currently running macro code. So using either technique: loadComponentFromURL() or ThisComponent, always results in the document model.

Sometimes, for instnace, to use the Dispatcher, you need the document frame. Other times, you need the document controller (for instance, to manipulate which shapes of a drawing are selected).

The following three functions from my library are how I easily move between the three different objects.
<pre>
'############################################################
'   API navigation convenience
'############################################################


'----------
' This will always return the document's controller.
' Pass in any one of...
'   * the document's model (subclass of com.sun.star.document.OfficeDocument)
'   * the document's controller
'   * the document's frame
Function GetDocumentController( oDoc As Object ) As Object
   Dim oCtrl As Object
   
   ' If the caller gave us the document model...
   If oDoc.supportsService( "com.sun.star.document.OfficeDocument" ) Then
      ' ...then get the controller from that.
      oCtrl = oDoc.getCurrentController()

   ' If the caller gave us a document controller...
   ElseIf HasUnoInterfaces( oDoc, "com.sun.star.frame.XController" ) Then
      ' ...thanks!  That's just what we wanted!
      oCtrl = oDoc
   
   ' If the caller gave us the document frame...
   ElseIf HasUnoInterfaces( oDoc, "com.sun.star.frame.XFrame" ) Then
      oFrame = oDoc
      ' ...then get the controller from the frame.
      oCtrl = oFrame.getController()
   
   Else
      ' The caller did not give us what we expected!
      MsgBox( "GetDocController called with incorrect parameter." )
   EndIf
   
   GetDocumentController() = oCtrl
End Function


'----------
' This will always return the document's frame.
' Pass in any one of...
'   * the document's model (subclass of com.sun.star.document.OfficeDocument)
'   * the document's controller
'   * the document's frame
Function GetDocumentFrame( oDoc As Object ) As Object
   Dim oFrame As Object
   
   ' If the caller gave us the document model...
   If oDoc.supportsService( "com.sun.star.document.OfficeDocument" ) Then
      ' ...then get the controller from that.
      oCtrl = oDoc.getCurrentController()
      ' ...then get the frame from the controller.
      oFrame = oCtrl.getFrame()

   ' If the caller gave us a document controller...
   ElseIf HasUnoInterfaces( oDoc, "com.sun.star.frame.XController" ) Then
      oCtrl = oDoc
      ' ...then get the frame from the controller.
      oFrame = oCtrl.getFrame()
   
   ' If the caller gave us the document frame...
   ElseIf HasUnoInterfaces( oDoc, "com.sun.star.frame.XFrame" ) Then
      ' ...thanks!  That's just what we wanted!
      oFrame = oDoc
   
   Else
      ' The caller did not give us what we expected!
      MsgBox( "GetDocumentFrame called with incorrect parameter." )
   EndIf
   
   GetDocumentFrame() = oFrame
End Function


'----------
' This will always return the document's model.
' Pass in any one of...
'   * the document's model (subclass of com.sun.star.document.OfficeDocument)
'   * the document's controller
'   * the document's frame
Function GetDocumentModel( oDoc As Object ) As Object
   Dim oDocModel As Object
   
   ' If the caller gave us the document model...
   If oDoc.supportsService( "com.sun.star.document.OfficeDocument" ) Then
      ' ...thanks!  That's just what we wanted!
      oDocModel = oDoc

   ' If the caller gave us a document controller...
   ElseIf HasUnoInterfaces( oDoc, "com.sun.star.frame.XController" ) Then
      oCtrl = oDoc
      ' ...then get the model from the controller.
      oDocModel = oCtrl.getModel()
   
   ' If the caller gave us the document frame...
   ElseIf HasUnoInterfaces( oDoc, "com.sun.star.frame.XFrame" ) Then
      oFrame = oDoc
      ' ...then get the controller from the frame.
      oCtrl = oFrame.getController()
      ' ...then get the model from the controller.
      oDocModel = oCtrl.getModel()
      
   Else
      ' The caller did not give us what we expected!
      MsgBox( "GetDocumentModel called with incorrect parameter." )
   EndIf
   
   GetDocumentModel() = oDocModel
End Function
</pre>
Now I can do something like...
<pre>
oDoc = loadComponentFromURL( ..... )	
</pre>
Then later, I need the frame, I can just call...
<pre>
oDocFrame = GetDocumentFrame( oDoc )	
</pre>
The above code provides three functions...
<pre>	
Function GetDocumentModel     ( oDoc As Object ) As Object
Function GetDocumentController( oDoc As Object ) As Object
Function GetDocumentFrame     ( oDoc As Object ) As Object	
</pre>
All three functions accept any of the model, frame or controller. Each function will "convert" to the desired object. For instance, if I need the model, I'll call GetDocumentModel(), but I can pass it the model, the frame or the controller. (Obviously, if I pass the document model to GetDocumentModel(), it doesn't have to do anything but just return what I gave it.)

Where these routines are really useful is in writing more general subroutines. I could write a routine to, say, copy to the clipboard. The routine takes a single parameter oDoc. But you could pass in any of the three objects (model, controller, frame). This makes my clipboardCopy() function easier to call. You just pass it whichever of the three document objects that you conveniently have on hand. If internally, the clipboardCopy() function needs a Frame, then it will use my GetDocumentFrame() function to get the frame from whichever one of the three you passed it.

Hope this is helpful to someone.