Activation(OD Cookbook)

Inside Macintosh: OpenDoc Cookbook /: Chapter 2 - SamplePart Tutorial

Activation
When the user clicks within the used shape of any frame belonging to the part, the frame should activate itself. The frame should also activate itself when its window opens or becomes active if the part has stored information specifying that the frame should become active in those situations. In addition, a frame should activate itself when the user drags and drops data on it. The frame activates itself by acquiring the selection focus.
Methods illustrating the standard OpenDoc activation protocol are included in this section. These method implementations are short, so their descriptions are not shown as numbered steps.

The BeginRelinquishFocus Method
OpenDoc calls the BeginRelinquishFocus method when another frame requests ownership of a focus of which the specified frame is the current owner. Generally, a part's response to the BeginRelinquishFocus method call is to determine if it can safely relinquish the focus, in which case it returns kODTrue. A part does not actually relinquish the focus in response to the BeginRelinquishFocus call.
The SamplePart object's implementation of BeginRelinquishFocus first determines if the focus in question is its modal focus. If so, unless the frame requesting the focus belongs to SamplePart itself, the method returns kODFalse. That is, if another part wants to display a modal dialog box while SamplePart is displaying its own, SamplePart denies the request. Otherwise, the method returns kODTrue.
Listing 2-32 shows the implementation of the BeginRelinquishFocus method.
Listing 2-32 BeginRelinquishFocus method
ODBoolean SamplePart::BeginRelinquishFocus( Environment*   ev,
                                            ODTypeToken    focus,
                                            ODFrame*       /* ownerFrame */,
                                            ODFrame*       proposedFrame )
{
    SOM_Trace("SamplePart","BeginRelinquishFocus");

   ODBoolean willRelinquish = kODTrue;
   if ( focus == gGlobals->fModalFocus )
   {
      TempODPart proposedPart = ODAcquirePart(ev,proposedFrame);
      if ( ODObjectsAreEqual(ev, proposedPart, fSelf) == kODFalse )
         willRelinquish = kODFalse;
   }
   return willRelinquish;
}
The CommitRelinquishFocus Method
OpenDoc calls the CommitRelinquishFocus method when it is time for a frame to actually relinquish ownership of the specified focus, completing the process begun in response to a previous BeginRelinquishFocus method call. Generally, a part's response to the CommitRelinquishFocus method call is to remove any indications of the specified frame owning the focus; for example, the method could remove highlighting. If the focus is being transferred to a frame belonging to a different part, the part could do further actions, such as disabling menu items or removing a palette.
The SamplePart object's implementation of CommitRelinquishFocus calls the FocusLost method to do the actual work. The FocusLost method is shown in Listing 2-34.
Listing 2-33 shows the implementation of the CommitRelinquishFocus method.
Listing 2-33 CommitRelinquishFocus method
void SamplePart::CommitRelinquishFocus( Environment*   ev,
                                        ODTypeToken    focus,
                                        ODFrame*       ownerFrame,
                                        ODFrame*       /* proposedFrame */ )
{
   SOM_Trace("SamplePart","CommitRelinquishFocus");

   this->FocusLost(ev, focus, ownerFrame);
}
The FocusLost Method
The SamplePart object calls its own FocusLost method to do the actual work of relinquishing a focus specified by the CommitRelinquishFocus method call. In addition, OpenDoc may call the FocusLost method directly when the arbitrator has transferred ownership of a specified focus from the specified frame to another due to events, without benefit of the BeginRelinquishFocus and CommitRelinquishFocus method calls.
The SamplePart object's implementation of FocusLost acts only if the lost focus is the selection focus. In that case, the specified frame is being deactivated, so the method removes the indication that the frame is active, which is stored in the frame's CFrameInfo object.
Listing 2-34 shows the implementation of the FocusLost method.
Listing 2-34 FocusLost method
void SamplePart::FocusLost( Environment*   ev,
                            ODTypeToken    focus,
                            ODFrame*       ownerFrame )
{
    SOM_Trace("SamplePart","FocusLost");

   if ( focus == gGlobals->fSelectionFocus )
   {
      CFrameInfo* frameInfo = (CFrameInfo*) ownerFrame->GetPartInfo(ev);
      frameInfo->SetFrameActive(kODFalse);
   }
}
The AbortRelinquishFocus Method
OpenDoc calls the AbortRelinquishFocus method when it rescinds a previous request (made with a BeginRelinquishFocus call) to relinquish ownership of a focus. Generally, a part's response to the AbortRelinquishFocus method call is to back out of any changes it initiated in response to the previous BeginRelinquishFocus call.
The SamplePart objects's implementation of AbortRelinquishFocus does nothing.
Listing 2-35 shows the implementation of the AbortRelinquishFocus method.
Listing 2-35 AbortRelinquishFocus method
void SamplePart::AbortRelinquishFocus( Environment*   ev,
                                       ODTypeToken    /*focus*/,
                                       ODFrame*       /*ownerFrame*/,
                                       ODFrame*       /*proposedFrame*/ )
{
    SOM_Trace("SamplePart","AbortRelinquishFocus");

   // Some parts may have suspended some events in the BeginRelinquishFocus
   // method. If so, they would resume those events here.
}
The FocusAcquired Method
OpenDoc calls the FocusAcquired method when the arbitrator has transferred ownership of the specified focus to the specified frame without benefit of the BeginRelinquishFocus and CommitRelinquishFocus method calls. Generally, a part's response to the FocusAcquired method call is to perform any actions needed to indicate that the specified frame now owns the focus. For example, if a frame acquired the selection focus, a part would highlight any selection within the frame.
The SamplePart object's implementation of FocusAcquired calls the arbitrator's RequestFocusSet method to request the complete focus set it needs to be active. If that action succeeds, the method calls the SamplePart object's internal method PartActivated, which puts the part into an active state, as shown in Listing 2-37.
Listing 2-36 shows the SamplePart object's implementation of the FocusAcquired method.
Listing 2-36 FocusAcquired method
void SamplePart::FocusAcquired( Environment*   ev,
                                ODTypeToken    focus,
                                ODFrame*       ownerFrame )
{
    SOM_Trace("SamplePart","FocusAcquired");

   ODArbitrator* arbitrator =  ODGetSession(ev,fSelf)->GetArbitrator(ev);

   if ( arbitrator->RequestFocusSet(ev, gGlobals->fUIFocusSet, ownerFrame) )
   {
      this->PartActivated(ev, ownerFrame);
   }
}
The PartActivated Method
The SamplePart object calls its own internal method PartActivated to display the part's menu bar and set the active flag in the specified frame's CFrameInfo object to true. Before displaying the menu bar, however, the method revalidates it, as described in "The AdjustMenus Method".
Listing 2-37 shows the implementation of the PartActivated method.
Listing 2-37 PartActivated method
void SamplePart::PartActivated( Environment*   ev,
                                ODFrame*       frame )
{
    SOM_Trace("SamplePart","PartActivated");
    
   if ( gGlobals->fMenuBar->IsValid(ev) == kODFalse )
   {
      ODReleaseObject(ev, gGlobals->fMenuBar);
      gGlobals->fMenuBar = 
               ODGetSession(ev,fSelf)->GetWindowState(ev)->CopyBaseMenuBar(ev);
   }
   gGlobals->fMenuBar->Display(ev);
   CFrameInfo* frameInfo = (CFrameInfo*) frame->GetPartInfo(ev);
   frameInfo->SetFrameActive(kODTrue);
}
The ActivateFrame Method
The SamplePart object calls its own internal ActivateFrame method when a mouse-up event occurs in an inactive frame in an active window or when the window in which the frame is displayed is activated by the Mac OS.
The method requests the user-interface focus set (defined in the Initialize method) and, if that request is granted, calls the PartActivated method to display the menu bar and set the specified frame's active flag. If the method executes successfully, it returns kODTrue as a signal to the caller that the specified frame is now active; otherwise, it returns kODFalse.
Listing 2-38 shows the implementation of the ActivateFrame method.
Listing 2-38 ActivateFrame method
ODBoolean SamplePart::ActivateFrame( Environment*   ev,
                                     ODFrame*       frame )
{
    SOM_Trace("SamplePart","ActivateFrame");

   ODBoolean activated = kODFalse;

   if ( ODGetSession(ev,fSelf)->GetArbitrator(ev)
         ->RequestFocusSet(ev, gGlobals->fUIFocusSet, frame) )
   {
      this->PartActivated(ev, frame);
      activated = kODTrue;
   }
   return activated;
}
The WindowActivating Method
The SamplePart object calls its own internal WindowActivating method from its HandleEvent method when it receives an activate event from the Mac OS. The activate event (kODEvtActivate) indicates that a window displaying the specified frame is being either activated or deactivated, as indicated by the Boolean parameter activating.
If the window is being activated, and if the specified frame had the selection focus when it was deactivated, the method calls the SamplePart object's internal ActivateFrame method. If the window is being deactivated and the specified frame is active, the method marks the frame's reactivation flag true. By setting the flag in this way, the frame can reactivate itself if the window becomes active again later, using the previous block of this same method.
Listing 2-39 shows the implementation of the WindowActivating method.
Listing 2-39 WindowActivating method
void SamplePart::WindowActivating( Environment*   ev,
                                   ODFrame*       frame,
                                   ODBoolean      activating )
{
    SOM_Trace("SamplePart","WindowActivating");

   CFrameInfo* frameInfo = (CFrameInfo*) frame->GetPartInfo(ev);
   if ( activating && frameInfo->FrameNeedsReactivating() )
   {
      this->ActivateFrame(ev, frame);
      frameInfo->SetFrameReactivate(kODFalse);
   }
   else if ( !activating && frameInfo->IsFrameActive() )
   {
      frameInfo->SetFrameReactivate(kODTrue);
   }
}