home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / source / bento / headers / arbitrat.h next >
Encoding:
C/C++ Source or Header  |  1994-03-02  |  6.3 KB  |  190 lines
  1. /*
  2.     File:        Arbitrat.h
  3.  
  4.     Contains:    XMPArbitrator interface
  5.  
  6.     Written by:    Richard Rodseth
  7.  
  8.     Copyright:    ⌐ 1993-94 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.         <28>     2/14/94    RR        #1143609.
  13.                                     relinguishingFrame->transferringFrame in
  14.                                     TransferFocus
  15.         <27>      2/9/94    NP        Tiger Team cleanup.
  16.         <26>      2/7/94    NP        Tiger Team doings.
  17.         <25>      2/7/94    NP        Tiger Team doings.
  18.         <24>     1/26/94    RR        Moved Foci to Foci.h
  19.         <23>     1/21/94    RR        Renamed foci
  20.         <22>     1/18/94    RR        Added kXMPScrollingFocus
  21.         <21>     1/11/94    Té        Init... changes
  22.         <20>     1/10/94    RR        Added TransferFocus and TransferFocusSet
  23.         <19>    12/23/93    RR        Added "Macintosh:" to focus names
  24.         <18>    12/20/93    RR        New init strategy
  25.         <17>     12/8/93    RR        Added RequestFocus/RelinquishFocus. Moved
  26.                                     extra classes to separate files
  27.         <16>     12/6/93    RR        Added modal focus
  28.         <15>     12/2/93    CC        Removed clipboard focus constant.
  29.         <14>    11/19/93    RR        Added IsFocusRegistered
  30.         <13>    10/27/93    CC        Added constant for the clipboard focus.
  31.         <12>    10/18/93    CG        Added #define id for ASLM
  32.         <11>     8/17/93    RR        Use DictionaryList instead of LinkedList
  33.         <10>      8/9/93    NP        Added class id string.
  34.          <9>     7/21/93    NP        Added a virtual keyword (temporary for
  35.                                     ASLM).
  36.          <7>      6/15/93    RCR        Added session to constructor
  37.          <6>      6/15/93    RCR        Changed FocusType back to XMPTypeToken
  38.          <5>      6/15/93    RCR        Changed FocusType to ISOStr
  39.          <4>      6/8/93    RCR        Added IsFocusExclusive() 
  40.          <3>      6/8/93    RCR        Added some support for non-exclusive foci 
  41.          <2>      4/29/93    RCR        Rename Includes 
  42.          <1>     4/23/93    RCR        first checked in
  43.  
  44.     To Do:
  45. */
  46.  
  47. #ifndef _ARBITRAT_
  48. #define _ARBITRAT_
  49.  
  50. #ifndef _XMPOBJ_
  51. #include "XMPObj.h"
  52. #endif
  53.  
  54. #ifndef _XMPTYPES_
  55. #include "XMPTypes.h"
  56. #endif
  57.  
  58. //==============================================================================
  59. // Theory of Operation
  60. //==============================================================================
  61.  
  62. /*
  63.     The arbitrator is used to manage competition for facilities which can only
  64.     be controlled by a single part at a time. These facilities are referred to
  65.     as "focus types". An example is the keystroke focus. Keyboard events are
  66.     sent to the part which has the keystroke focus. Another example is the menu
  67.     focus. One part owns the menu bar at any time. Many focus types are related
  68.     to event distribution, but focus types could also be associated with ports,
  69.     for example.
  70.     
  71.     Rather than having an all-encompassing notion of "active" part, parts simply
  72.     request ownership of a set of focus types. It is possible, in principle, to
  73.     have one part receive keystroke events while another receives sound input,
  74.     though the human interface guidelines may encourage parts to request and 
  75.     relinquish most focus types along with the menu focus.
  76.         
  77.     New focus types can be added. This might be done by a part handler which is
  78.     associated with some exotic input device.
  79.     
  80.     Parts request ownership of a set of focus types. This is necessary to 
  81.     avoid deadlock.
  82.         
  83. */
  84.  
  85. //==============================================================================
  86. // Constants
  87. //==============================================================================
  88.  
  89.  
  90. //==============================================================================
  91. // Scalar Types
  92. //==============================================================================
  93.  
  94. //=====================================================================================
  95. // Class defined in this interface
  96. //=====================================================================================
  97.  
  98. class XMPArbitrator;
  99.  
  100. //=====================================================================================
  101. // Classes used by this interface
  102. //=====================================================================================
  103.  
  104. class XMPFocusModule;
  105. class XMPFocusSet;
  106. class XMPFocusOwnerIterator;
  107. class XMPSession;
  108. class XMPFrame;
  109. class DictionaryList;
  110.  
  111. //=====================================================================================
  112. // Global Variables
  113. //=====================================================================================
  114.  
  115. //=====================================================================================
  116. // Class XMPArbitrator
  117. //=====================================================================================
  118.  
  119. #define kXMPArbitratorID "appl:xmparbitrator$class,1.0.0"
  120.  
  121.  class XMPArbitrator : public XMPObject
  122. {
  123. public:
  124.  
  125.     XMPArbitrator();
  126.             
  127.     virtual ~XMPArbitrator();
  128.     
  129.     XMPNVMethod void InitArbitrator(XMPSession* session);
  130.  
  131.     XMPMethod    XMPSize    Purge(XMPSize size); 
  132.         
  133.     XMPMethod XMPBoolean RequestFocusSet(XMPFocusSet* focusSet, XMPFrame* requestingFrame);
  134.         
  135.     XMPMethod XMPBoolean RequestFocus(XMPTypeToken focus, XMPFrame* requestingFrame);
  136.                 
  137.     XMPMethod void RelinquishFocusSet(XMPFocusSet* focusSet, XMPFrame* relinquishingFrame);
  138.                 
  139.     XMPMethod void RelinquishFocus(XMPTypeToken focus, XMPFrame* relinquishingFrame);
  140.     
  141.     XMPMethod void TransferFocus(XMPTypeToken focus, 
  142.                                  XMPFrame* transferringFrame,
  143.                                  XMPFrame* newOwner);
  144.                                  
  145.     XMPMethod void TransferFocusSet(XMPFocusSet* focusSet, 
  146.                                  XMPFrame* transferringFrame,
  147.                                  XMPFrame* newOwner);
  148.                                  
  149.     XMPMethod XMPFrame* GetFocusOwner(XMPTypeToken focus);
  150.         
  151.     XMPMethod XMPFocusOwnerIterator* CreateOwnerIterator(XMPTypeToken focus);
  152.                     
  153.     XMPMethod void RegisterFocus(XMPTypeToken focus, XMPFocusModule* focusModule);
  154.             
  155.     XMPMethod void UnregisterFocus(XMPTypeToken focus);
  156.  
  157.     XMPMethod XMPBoolean IsFocusRegistered(XMPTypeToken focus);
  158.     
  159.     XMPMethod XMPBoolean IsFocusExclusive(XMPTypeToken focus);
  160.     
  161. protected:
  162.  
  163.     XMPMethod void SetFocusOwnership(XMPTypeToken focus, XMPFrame* frame);
  164.     
  165.     XMPMethod XMPFocusModule* GetFocusModule(XMPTypeToken focus);
  166.             
  167.     XMPMethod XMPBoolean BeginRelinquishFocus(
  168.                                 XMPTypeToken focus, 
  169.                                  XMPFrame* requestingFrame);
  170.                                                                   
  171.     XMPMethod void CommitRelinquishFocus(XMPTypeToken focus, 
  172.                              XMPFrame* requestingFrame);
  173.                                                           
  174.     XMPMethod void AbortRelinquishFocus(XMPTypeToken focus, 
  175.                              XMPFrame* requestingFrame);
  176.                              
  177. protected:
  178.  
  179.     XMPSession* fSession;    // Access to globals
  180.             
  181. private:
  182.  
  183.     DictionaryList* fFocusModules;    
  184.  
  185. };
  186.  
  187.  
  188.  
  189. #endif // _ARBITRAT_
  190.