home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 October: Mac OS SDK / Dev.CD Oct 96 SDK / Dev.CD Oct 96 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / Documentation / Engineering Notes / Embedding / RequestEmbeddedFrame < prev   
Encoding:
Text File  |  1996-08-16  |  8.3 KB  |  214 lines  |  [TEXT/ttxt]
  1. OpenDoc
  2. Development
  3. Framework
  4.                                                                                                                                                                                      
  5. RequestEmbeddedFrame 
  6. ODF Release 1                                                                                                                                                             
  7.  
  8.  
  9.  
  10. This version ODF supports the RequestEmbeddedFrame API for both container and embedded parts. ODFDraw and ODFBitmap implement this API for embedding and embedded parts, respectively.
  11.  
  12.  
  13. Embedding Parts
  14.  
  15. • Required API
  16.  
  17. As an embedding part, you need to override two methods in order to support RequestEmbeddedFrame:
  18.  
  19.      - FW_CEmbeddingFrame::EmbeddedFrameRequested
  20.      - FW_CEmbeddingPart::EmbeddedFrameRemoved
  21.     
  22. 1) FW_CEmbeddingFrame::EmbeddedFrameRequested
  23.  
  24. The parameters are the following.
  25.  
  26. FW_MProxy* FW_CEmbeddingFrame::EmbeddedFrameRequested(Environment *ev,
  27.                                                       FW_MProxy* baseProxy,
  28.                                                       ODFrame* baseFrame,
  29.                                                       ODShape* frameShape,
  30.                                                       ODPart* embeddedPart,
  31.                                                       ODTypeToken viewType,
  32.                                                       ODTypeToken presentation,
  33.                                                       ODID frameGroupID,
  34.                                                       FW_Boolean isOverlaid,
  35.                                                       FW_Boolean isSubFrame)
  36.  
  37. baseProxy:   the proxy making the request
  38. baseFrame:  the base frame making the request
  39. frameShape: the suggested frame shape for the new frame (in frame coordinates of baseFrame)
  40. embeddedPart: the embedded part requesting a new frame
  41. viewType: the view type for the new frame
  42. presentation: the presentation for the new frame
  43. frameGroupID: the group ID for the new frame
  44. isOverlaid: tells you if the new frame should be an overlaid frame
  45. isSubFrame: tells you if the new frame should be a subframe
  46.  
  47. By default FW_CEmbeddingFrame::EmbeddedFrameRequested returns NULL meaning that RequestEmbeddedFrame is not supported. This is the case for example with the ODFEmbed part (only one frame can be embedded).
  48.  
  49. If your part wants to allow embedded parts to request additional frames you need to override CEmbeddingFrame::EmbeddedFrameRequested. In your override first create a new proxy object and then call FW_CPresentation::Embed to create the new frame.
  50.  
  51. Here is an example taken from ODFDraw. Notice that in this example ODFDraw doesn't care about the suggested frame shape but force the requested frame to be the same size as the base frame.
  52.  
  53. //----------------------------------------------------------------------------------------
  54. // CDrawFrame::EmbeddedFrameRequested
  55. //----------------------------------------------------------------------------------------
  56.  
  57. FW_MProxy* CDrawFrame::EmbeddedFrameRequested(Environment *ev,
  58.            FW_MProxy* baseProxy,
  59.            ODFrame* baseFrame,
  60.            ODShape* frameShape,
  61.            ODPart* embeddedPart,
  62.            ODTypeToken viewType,
  63.            ODTypeToken presentation,
  64.            ODID frameGroupID,
  65.            FW_Boolean isOverlaid,
  66.            FW_Boolean isSubFrame)
  67. {
  68.  
  69.  FW_CPresentation* myPresentation = GetPresentation(ev);
  70.  
  71.  CProxyShape* baseProxyShape = (CProxyShape*)baseProxy;
  72.  FW_CRect embeddedFrameBounds = baseProxyShape->GetFrameRect(ev);
  73.  
  74.  embeddedFrameBounds.Offset(embeddedFrameBounds.Width(), FW_kFixed0);
  75.  
  76.  CProxyShape* proxy = FW_NEW(CProxyShape, (ev, embeddedFrameBounds, fDrawPart));
  77.   
  78.  FW_CRect tempRect(embeddedFrameBounds);
  79.  tempRect.Place(FW_kFixed0, FW_kFixed0);
  80.  FW_CAcquiredODShape aqFrameShape = ::FW_NewODShape(ev, tempRect);
  81.  
  82.  FW_TRY
  83.  {
  84.    myPresentation->Embed(ev, 
  85.         embeddedPart,
  86.         NULL,
  87.         kODFrameObject,
  88.         proxy,
  89.         aqFrameShape,
  90.         viewType,
  91.         presentation,
  92.         frameGroupID,
  93.         isOverlaid,
  94.         isSubFrame);
  95.  }
  96.  FW_CATCH_BEGIN
  97.  FW_CATCH_EVERYTHING () 
  98.  {
  99.   delete proxy;
  100.   FW_THROW_SAME ();
  101.  }
  102.  FW_CATCH_END
  103.  
  104.  // ----- Now I can add it to my data    
  105.  fDrawPart->AddShapeToPart(ev, proxy);
  106.  
  107.  // ----- Clip the facets -----
  108.  CDrawFacetClipper facetClipper(ev, fDrawPart);
  109.  FW_CAcquiredODShape limitShape = ::FW_NewODShape(ev, embeddedFrameBounds);
  110.  facetClipper.Clip(ev, myPresentation, limitShape);
  111.  
  112.  return proxy;
  113. }
  114.  
  115. 2) FW_CEmbeddingPart::EmbeddedFrameRemoved
  116.  
  117. in the same way that an embedded part can request an additional frame, it can ask you (the embedding part) to remove a previously requested frame. The API is:
  118.  
  119. void FW_CEmbeddingPart::EmbeddedFrameRemoved(Environment *ev, FW_MProxy* proxy);
  120.  
  121. FW_MProxy is one of the proxy objects you have created in EmbeddedFrameRequested. Here is an example taken from ODFDraw:
  122.  
  123. //----------------------------------------------------------------------------------------
  124. // CDrawPart::EmbeddedFrameRemoved
  125. //----------------------------------------------------------------------------------------
  126.  
  127. void CDrawPart::EmbeddedFrameRemoved(Environment *ev, FW_MProxy* proxy)
  128. {
  129.  CProxyShape* proxyShape = (CProxyShape*)proxy;  // I have only one type of proxy
  130.  
  131.  FW_CRect updateBox;
  132.  proxyShape->GetUpdateBox(updateBox);
  133.  
  134.  proxyShape->GetPresentation(ev)->Invalidate(ev, updateBox);
  135.  
  136.  RemoveShapeFromPart(ev, proxyShape);
  137.  
  138.  delete proxyShape;
  139. }
  140.  
  141. Optional API
  142.  
  143. ODF usually takes care of the Group ID and Sequence number. You cannot change the group ID but you can change the sequence number if necessary. The following API is available in FW_MProxy:
  144.  
  145. ODID    FW_MProxy::GetFrameGroup(Environment *ev) const;
  146. ODID    FW_MProxy::GetSequenceNumber(Environment *ev) const;
  147. void    FW_MProxy::ChangeSequenceNumber(Environment *ev, ODID sequenceNumber);
  148.  
  149.  
  150. Embedded Parts
  151.  
  152. As an embedded part you can request additional frames from your containing part. The API in ODF to do that is the following:
  153.  
  154.    - FW_CPresentation::RequestSiblingFrame
  155.    - FW_CPresentation::RemoveSiblingFrame
  156.  
  157. 1) FW_CPresentation::RequestSiblingFrame
  158.  
  159. Call RequestSiblingFrame to get a new frame from your containing part. The API is as follow:
  160.  
  161. ODID FW_CPresentation::RequestSiblingFrame(Environment* ev,
  162.                                            FW_CFrame* baseFrame, 
  163.                                            ODShape* suggestedFrameShape,
  164.                                            ODTypeToken viewType,
  165.                                            FW_Boolean isOverlaid)
  166.  
  167. If your containing part does not support RequestEmbeddedFrame, RequestSiblingFrame will return kODNULLID. You need to test for that, since not all embedding parts will support RequestEmbeddedFrame.
  168.  
  169. The following  example is taken from ODFBitmap:
  170.  
  171. //----------------------------------------------------------------------------------------
  172. // CBitmapFrame::DoMenu
  173. //----------------------------------------------------------------------------------------
  174.  
  175. FW_Boolean CBitmapFrame::DoMenu(Environment* ev, const FW_CMenuEvent& theMenuEvent)
  176. {
  177.     FW_Boolean result = TRUE;
  178.     ODCommandID commandID = theMenuEvent.GetCommandID(ev);
  179.  
  180.     FW_CPresentation* myPresentation = GetPresentation(ev);
  181.  
  182.     switch (commandID)
  183.     {
  184.         .......
  185.  
  186.         case cRequestFrame:
  187.         {
  188.             FW_CAcquiredODShape aqShape = FW_CopyAndRelease(ev, AcquireFrameShape(ev));
  189.             ODID sequence = myPresentation->RequestSiblingFrame(ev, this, aqShape, GetViewType(ev), FALSE);
  190.             if (sequence != kODNULLID)
  191.                 myPresentation->Invalidate(ev, NULL, sequence); // invalidate all frames of this sequence
  192.             break;
  193.         }
  194.  
  195.     .....
  196.    
  197.         default:  
  198.             result = FALSE;
  199.     }
  200.  
  201.     return result;
  202. }
  203.  
  204. 2) FW_CPresentation::RemoveSiblingFrame
  205.  
  206. When you no longer need a frame you have requested, call FW_CPresentation::RemoveSiblingFrame. Note that in the OpenDoc documentation it is mentioned that only requested frames can be removed. ODF will post an assert if you try to remove a frame you haven't requested.
  207.  
  208. The API for RemoveSiblingFrame is as follow:
  209.  
  210. void FW_CPresentation::RemoveSiblingFrame(Environment* ev, FW_CFrame* frameToRemove)
  211.  
  212.  
  213. © 1993 - 1996 Apple Computer, Inc. All rights reserved.
  214. Apple, the Apple Logo, Macintosh, and OpenDoc are trademarks of Apple Computer, Inc., registered in the United States and other countries.