home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / yacl-012.zip / ui / composit.h < prev    next >
C/C++ Source or Header  |  1995-04-08  |  11KB  |  314 lines
  1.  
  2. #ifndef _composit_h_
  3. #define _composit_h_
  4.  
  5.  
  6.  
  7.  
  8.  
  9. /*
  10.  *
  11.  *          Copyright (C) 1994, M. A. Sridhar
  12.  *  
  13.  *
  14.  *     This software is Copyright M. A. Sridhar, 1994. You are free
  15.  *     to copy, modify or distribute this software  as you see fit,
  16.  *     and to use  it  for  any  purpose, provided   this copyright
  17.  *     notice and the following   disclaimer are included  with all
  18.  *     copies.
  19.  *
  20.  *                        DISCLAIMER
  21.  *
  22.  *     The author makes no warranties, either expressed or implied,
  23.  *     with respect  to  this  software, its  quality, performance,
  24.  *     merchantability, or fitness for any particular purpose. This
  25.  *     software is distributed  AS IS.  The  user of this  software
  26.  *     assumes all risks  as to its quality  and performance. In no
  27.  *     event shall the author be liable for any direct, indirect or
  28.  *     consequential damages, even if the  author has been  advised
  29.  *     as to the possibility of such damages.
  30.  *
  31.  */
  32.  
  33.  
  34.  
  35. // Authors:   M. A. Sridhar
  36. //            N. Bhowmik
  37.  
  38.  
  39. #if defined(__GNUC__)
  40. #pragma interface
  41. #endif
  42.  
  43.  
  44.  
  45. #include "base/intseq.h"
  46.  
  47.  
  48. #include "ui/vobjcoll.h"
  49. #include "ui/event.h"
  50.  
  51.  
  52. class CL_EXPORT UI_Menu;
  53. class CL_EXPORT UI_MenuBar;
  54.  
  55. // The Composite is an object whose visual representation is a window, on
  56. // which other visual objects can be placed. The other objects so placed
  57. // are thought of as children of the Composite. Thus the Composite
  58. // provides the heterogeneous composition mechanism in YACL. Typical
  59. // applications for the Composite are modeless and modal dialogs. The
  60. // operator[] provided by the Composite allows access to its children via
  61. // their view ID. The Composite manages the setting of focus on its
  62. // children when the user types the TAB (or SHIFT-TAB) key.
  63. //
  64. // From another viewpoint, a Composite can be thought of as essentially a
  65. // mechanism for accessing its child VisualObjects via their ViewID's.
  66. //
  67. // The children of a composite may be drawn anywhere; however, only those
  68. // that are within its client area (and have not been made invisible by
  69. // the programmer) will be visible.
  70. //
  71. // A Composite can be created with an array of descriptors of its
  72. // children. When so created, the Composite creates all of the children
  73. // described by those descriptors. When the Composite is destroyed, these
  74. // children are all destroyed; in fact, so is the entire subtree of the view
  75. // tree rooted at the Composite being destroyed.
  76. //
  77. // A Composite may have other Composites as its children (although this
  78. // doesn't always seem to work under MS-Windows, possibly because of a
  79. // Windows bug.) 
  80. //
  81. // It is possible to associate a MenuBar with a Composite, using the
  82. // {\small\tt UseMenuBar} method.
  83. //
  84. // In response to each event in the windowing
  85. // system, the controller first sends the event to its destination (e.g.,
  86. // when the mouse is clicked on a button, a click event is sent to the
  87. // button) by invoking the destination's {\small\tt HandleEvent} method.
  88. // Then, the event is sent to the each of the ancestors of the destination
  89. // in the view tree, in order from leaf to root, via their {\small\tt
  90. // HandleChildEvent} methods. This allows a Composite to inspect events
  91. // that occur in its children (in fact, all its descendants) by overriding
  92. // the {\small\tt HandleChildEvent}, and taking the necessary action.
  93. //
  94.  
  95. class CL_EXPORT UI_CompositeVObject: public UI_VObjCollection {
  96.  
  97. public:
  98.  
  99.     // ---------------------- Construction ----------------------------
  100.  
  101.     UI_CompositeVObject (UI_CompositeVObject* parent,
  102.                          const UI_Rectangle& shape, UI_ViewID id = -1);
  103.     
  104.     UI_CompositeVObject (UI_CompositeVObject* parent,
  105.                          UI_ViewDescriptor* vd, bool sticky = FALSE,
  106.                          const UI_Rectangle& shape = UI_Rectangle (),
  107.                          UI_ViewID id = -1);
  108.     // Descriptor-based construction: the second parameter points to an
  109.     // array of ViewDescriptor structures, the last of which has type set to
  110.     // View_None. The data structure pointer to by vd is "borrowed" for
  111.     // reading by this composite object, and therefore may not be destroyed
  112.     // until the composite becomes visible. (But the composite does not
  113.     // write into the vd data structure.) The parameter "sticky" indicates
  114.     // whether this composite "sticks" to its parent's surface, and moves
  115.     // along with the parent; if it is FALSE, the composite appears as a
  116.     // separate window with its own caption bar. (Composites that stick to
  117.     // parent composites seem to behave erroneously under MS-Windows,
  118.     // perhaps because of a Windows bug?)
  119.  
  120.  
  121. #if defined(__MS_WINDOWS__)
  122.     UI_CompositeVObject (UI_CompositeVObject* parent,
  123.                          const char* resource_name, UI_ViewID id = -1);
  124.     // Resource-based construction: currently supported only under
  125.     // MS-Windows. This creates a non-sticky composite.
  126.  
  127. #endif
  128.  
  129.     // ------------------- View-related methods ---------------
  130.  
  131.     UI_Rectangle Area () const;
  132.     
  133.     virtual void ShowTitleBar ();
  134.  
  135.     virtual void HideTitleBar ();
  136.  
  137.     virtual bool IsTitleBarShown ();
  138.  
  139.     virtual bool IsIconified () {return _iconified;};
  140.  
  141.     bool SticksToParent () const {return _stickToParent;};
  142.     
  143. #if defined(__MS_WINDOWS__)
  144.     virtual void Set3DLook ();
  145.     // [MS-Windows-specific] Use the Borland 3-dimensional look on this
  146.     // Composite  and all its descendants. This method must be called
  147.     // before the Composite is displayed. [NOT YET IMPLEMENTED]
  148.  
  149.     bool Has3DLook () const;
  150.     // [MS-Windows-specific] Does this Composite have a 3-d look?
  151.  
  152. #endif
  153.     // -------------------- Subview manipulation ---------------------
  154.     
  155.     virtual UI_VisualObject*  CreateChild (const UI_ViewDescriptor& vd);
  156.     //  Create a child with given descriptor, and return a pointer to it.
  157.     //  This array cannot include any ExOrToggleButton descriptors.
  158.     
  159.     virtual UI_VisualObject* RemoveChild (UI_VisualObject* view);
  160.     // Remove the given VisualObject from the composite and
  161.     // return it. The caller must destroy the returned object via the
  162.     // Application's Destroy method.
  163.  
  164.     // ------------------ Convenience methods ----------------------
  165.  
  166.     CL_Object& Model ();
  167.     // The returned model is an IntPtrMap whose keys are the view id's of
  168.     // the children, and whose values are pointers to the corresponding
  169.     // model objects.
  170.     
  171. #if defined(__MS_WINDOWS__)
  172.     bool CreatedViaResource () {return _rname.Size() > 0;};
  173.     // [MS-Windows-specific] Return TRUE if this object was created using a
  174.     // resource name.
  175.  
  176. #endif
  177.     // --------------------- Menu methods ---------------------------
  178.     
  179.     UI_MenuBar* MenuBar () const;
  180.     // Return the menu used by this composite. Return NULL if there is no
  181.     // associated menu.
  182.  
  183.     
  184.     // ---------------------- Basic methods -----------------------
  185.  
  186.     virtual UI_WindowClass WindowClass () const;
  187.     
  188.     const char* ClassName() const { return "UI_CompositeVObject";};
  189.  
  190.  
  191.  
  192. protected:
  193.     
  194.  
  195.     ~UI_CompositeVObject();
  196.  
  197.     virtual bool MakeVisualElement ();
  198.     
  199.     // 
  200.     // Composite method for child event inspection:
  201.     // 
  202.  
  203.     virtual bool HandleChildEvent (const UI_Event& e);
  204.     // This is a hook for inspecting and processing any event originating
  205.     // in any of the contained objects that are passed up to this
  206.     // composite -- the parent. The default implementation does nothing and
  207.     // simply returns FALSE.
  208.  
  209.     
  210.     bool DestroyVisualElement ();
  211.  
  212.     void initSimple (UI_VisualObject*);
  213.  
  214.     void _PrivateInitialize();
  215.  
  216.  
  217.  
  218. #if defined(__X_MOTIF__)
  219.     static void DeleteWindowCallback (struct _WidgetRec* w,
  220.                                       void *client, void *call);
  221.     
  222. #endif
  223.     
  224. public:
  225.  
  226.     // -------------- For YACL internal use only -----------------
  227.     
  228. #if defined(__MS_WINDOWS__)
  229.     bool CreateResourceChild (UI_ViewHandle, const CL_String& name);
  230.     //  [YACL internal use only] MS-Windows-specific: Create a child if
  231.     //  instantiated from a resource file.
  232.  
  233. #endif
  234.     void AddChild (UI_VisualObject* child);
  235.     // [YACL internal use only]
  236.     
  237.     bool UseMenuBar  (UI_MenuBar* menu);
  238.     // [YACL internal use only]
  239.  
  240. #if defined(__MS_WINDOWS__) || defined(__OS2__)
  241.     void TakeFocus ();
  242.     // [Specific to OS/2 and Windows. YACL internal use only.]
  243.  
  244.     virtual void MoveFocusTo (UI_VisualObject* child);
  245.     // [Specific to OS/2 and Windows. YACL internal use only.] This method
  246.     // moves the focus to the specified child. Called by the child on mouse
  247.     // click.
  248.  
  249.     virtual bool AdvanceFocus (short n);
  250.     // [Specific to OS/2 and Windows. YACL internal use only.] This method
  251.     // advances focus to the next child if n is +1, and to the previous
  252.     // child if n is -1. Returns TRUE on success, FALSE if it hits the ends
  253.     // of the tab sequence.
  254.  
  255. protected:
  256.     void _SetFocusTo (short i);
  257.     // [Specific to OS/2 and Windows. YACL internal use only.] Set the focus
  258.     // to child $i$ in the tab sequence.
  259.     
  260. #endif
  261.     
  262.     
  263. protected:
  264.     // 
  265.     // Instance Variables:
  266.     // 
  267.  
  268.     UI_MenuBar*        _menuBar;
  269.     bool               _stickToParent; // Do we stick to our parent's
  270.                                        // surface?
  271.     short              _currentChild;  // Index of current child in map
  272.     CL_ObjectSequence  _tabSequence;   // The sequence of children in
  273.                                        // tabbing order
  274.  
  275.     bool               _titleBarShown; // Is the title bar currently shown?
  276.  
  277.     bool               _iconified;     // Are we currently iconified?
  278.  
  279. #if defined(__OS2__)
  280.     UI_ViewHandle      _frameHandle;
  281. #endif
  282.     
  283. private:
  284.  
  285.     bool  _ShapeRectChanged (CL_Object&, long);
  286.     // Override VisualObject's method
  287.  
  288.     bool _TitleChanged (CL_Object&, long);
  289.     // Override VisualObject's method
  290.     
  291. #if defined(__X_MOTIF__)
  292.     _WidgetRec* _popup;
  293. #endif
  294.  
  295. #if defined(__MS_WINDOWS__)
  296.     bool               _3dLook;
  297.     CL_String          _rname;         // Resource  name
  298.                                        // (used only under MS-Windows)
  299. #endif
  300.  
  301. private:
  302.     void _Init ();
  303.  
  304.     
  305.     bool _EventOccurred (CL_Object& o, long);
  306.     // [Internal use only. Meant for handling tab sequences.]
  307.  
  308. };
  309.  
  310.  
  311.  
  312.  
  313. #endif
  314.