home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / ICNROBJ.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  23KB  |  421 lines

  1. #ifndef _ICNROBJ_
  2.   #define _ICNROBJ_
  3. /*******************************************************************************
  4. * FILE NAME: icnrobj.hpp                                                       *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     IContainerObject - Base container object class                           *
  9. *                                                                              *
  10. * COPYRIGHT:                                                                   *
  11. *   (C) Copyright IBM Corporation 1992                                         *
  12. *   All Rights Reserved                                                        *
  13. *   Licensed Materials * Property of IBM                                       *
  14. *                                                                              *
  15. * HISTORY:                                                                     *
  16. *******************************************************************************/
  17. #if !defined(_IVBASE_)
  18.   #include <ivbase.hpp>
  19. #endif
  20.  
  21. #if !defined(_ISTRING_)
  22.   #include <istring.hpp>
  23. #endif
  24.  
  25. #if !defined(_IBITFLAG_)
  26.   #include <ibitflag.hpp>
  27. #endif
  28.  
  29. #if !defined(_IHANDLE_)
  30.   #include <ihandle.hpp>
  31. #endif
  32.  
  33. /*----------------------------------------------------------------------------*/
  34. /* Align classes on four byte boundary.                                       */
  35. /*----------------------------------------------------------------------------*/
  36. #pragma pack(4)
  37.  
  38.  
  39. // Class Forward Declarations
  40. class IContainerObject;
  41. class IMiniCnrRecord;
  42. class IContainerControl;
  43. class IResourceId;
  44.  
  45.  
  46.  
  47. class IContainerObject : public IVBase
  48. {
  49. typedef IVBase
  50.   Inherited;
  51. /*******************************************************************************
  52. * IContainerObject is the base class of all objects stored in a container.     *
  53. * This object is required to be subclassed to support additional data in the   *
  54. * details view but can be used as is in other views. All instances of          *
  55. * this class must be created using operator new, which is overloaded here      *
  56. * to provide the storage allocation required by the underlying OS/2 container  *
  57. * control.                                                                     *
  58. *                                                                              *
  59. * If this object is subclassed and data is added for the details view, the     *
  60. * data must be contiguous with the data of this class and be one of the        *
  61. * supported types defined in IContainerColumn.  It is important to note that   *
  62. * only the string type can be edited.  The IString class is the recommended    *
  63. * way to store text data in an object subclass.                                *
  64. *                                                                              *
  65. * Container initialization normally occurs when the first IContainerControl    *
  66. * is instantiated.  If container objects need to be instantiated earlier, the  *
  67. * IContainerControl::initialize function should be called prior to the first   *
  68. * instantiation, but after the presentation environment has been initialized.  *
  69. *                                                                              *
  70. * It is recommended that you use a Resource Library to load icons as it         *
  71. * is capable of satisfying multiple requests for the same icon with a          *
  72. * single load and will manage multiple references to the same object. Actual   *
  73. * icon deletion occurs when the use count reaches zero.                        *
  74. *                                                                              *
  75. * IContainerObjects can be added to multiple containers at the same time. When *
  76. * functions in this class modify an object's characteristics, they do so in    *
  77. * all containers that hold the object.  Functions exist in IContainerControl   *
  78. * that can be used to modify certain attributes of an object in a single       *
  79. * container.                                                                   *
  80. *                                                                              *
  81. * EXAMPLE:                                                                     *
  82. *                                                                              *
  83. *                                                                              *
  84. * class Customer : public IContainerObject                                     *
  85. * {                                                                            *
  86. * public:                                                                      *
  87. *    Customer(const IString& Name,                                             *
  88. *             const IPointerHandle& Icon = 0,                                  *
  89. *             const IString& Address = IString(),                              *
  90. *             const IString& Phone = IString(),                                *
  91. *             unsigned long Age = 0)                                           *
  92. *       : IContainerObject(Name, hptrIcon),                                    *
  93. *         strCustomerAddress(Address),                                         *
  94. *         strCustomerPhone(Phone),                                             *
  95. *         ulCustomerAge(Age) {  }                                              *
  96. *                                                                              *
  97. * private:                                                                     *
  98. *   IString strCustomerAddress;                                                *
  99. *   IString strCustomerPhone;                                                  *
  100. *  unsigned long ulCustomerAge;                                                *
  101. * };                                                                           *
  102. *                                                                              *
  103. *                                                                              *
  104. * Customer ski("Blacky Diamond", 10, "Park City, Utah", "1-800-SKI-JUMP", 39); *
  105. *                                                                              *
  106. *                                                                              *
  107. *                                                                              *
  108. *******************************************************************************/
  109. friend class IContainerControl;
  110. friend class IMiniCnrRecord;
  111. friend IMiniCnrRecord* IRecFromObj( const IContainerObject* pcnrobj);
  112.  
  113. public:
  114.  
  115. /*----------------------- Related Types ----------------------------------------
  116. | The following IContainerObject types are defined:                            |
  117. |     Emphasis - A visible indication of the condition of an object that can   |
  118. |                affect the ability of a user to interact with that object.    |
  119. |                The types of emphasis are:                                    |
  120. |                                                                              |
  121. |                none     - Used when no visible indication is required.       |
  122. |                cursored - A visible indication of where user interaction     |
  123. |                           with the keyboard will appear.                     |
  124. |                inuse    - A visible indication that the object has been      |
  125. |                           opened.                                            |
  126. |                selected - A visible indication that the object has been      |
  127. |                           selected by the user.                              |
  128. ------------------------------------------------------------------------------*/
  129. enum Emphasis { none=0, cursored=1, inuse=2, selected=4};
  130.  
  131. /*------------------------ Constructors ----------------------------------------
  132. | You can construct an instance of this class in the following ways:           |
  133. |    - The default with no arguments.                                          |
  134. |                                                                              |
  135. |    - By providing an IString for text and an IPointerHandle for the icon.    |
  136. |                                                                              |
  137. |    - By providing an IString for text and an IResourceId for the icon.       |
  138. |                                                                              |
  139. |    - By providing resource IDs for both the text and icon.                   |
  140. |                                                                              |
  141. |    - From a copy of an existing object.  If the object is subclassed, this   |
  142. |      copy constructor must be overloaded to ensure that the object is copied |
  143. |      correctly.                                                              |
  144. |                                                                              |
  145. |    - By providing an IString for text and an unsigned long that is used      |
  146. |      as a resource ID. This constructor is provided to resolve a potential   |
  147. |      ambiguity since both IResourceIds and IPointerHandles can be built      |
  148. |      implicitly from an unsigned long integer.                               |
  149. ------------------------------------------------------------------------------*/
  150.   IContainerObject  ( );
  151.   IContainerObject  ( const IString&          string,
  152.                       const IPointerHandle&   iconHandle = 0);
  153.  
  154.   IContainerObject  ( const IString&          string,
  155.                       const IResourceId&      iconId);
  156.  
  157.   IContainerObject  ( const IResourceId&      nameID,
  158.                       const IResourceId&      iconId);
  159.  
  160.   IContainerObject  ( const IContainerObject& object);
  161.  
  162.   IContainerObject  ( const IString&           string,
  163.                       unsigned long            iconId);
  164.  
  165.  
  166. virtual
  167.   ~IContainerObject ( );
  168.  
  169. /*-------------------------------- Accessors -----------------------------------
  170. | These functions provide means of getting and setting the accessible          |
  171. | attributes of instances of this class. Note: Since an object may exist in    |
  172. | more than one container, many of these functions accept a container as an    |
  173. | optional parameter.  If the container is not specified, the function is      |
  174. | applied to all containers that this object is in.                            |
  175. |   setIcon               - Sets a new icon for an object.                     |
  176. |   setIconText           - Sets the new text for an object.                   |
  177. |   icon                  - Returns the icon handle of an object.              |
  178. |   iconText              - Returns the text of an object.                     |
  179. |   setInUse              - Sets the in-use emphasis for this object.          |
  180. |   removeInUse           - Removes the in-use emphasis for this object.       |
  181. |   enableDataUpdate      - Enables this object to be updated.                 |
  182. |   disableDataUpdate     - Disables update of this object.                    |
  183. |   refresh               - Refreshes this object.                             |
  184. |   show                  - Makes this object visible.                         |
  185. |   hide                  - Makes this object invisible by filtering it out.   |
  186. |   enableDrop            - Allows other objects to be dropped on this object. |
  187. |   disableDrop           - Prevents any object from being dropped on this     |
  188. |                           object.                                            |
  189. |   setRefreshOn          - Sets this object's state to be refreshable.        |
  190. |   setRefreshOff         - Inhibits refresh of this object.                   |
  191. |   isInUse               - Returns true if this object has in-use emphasis.   |
  192. |   isReadOnly            - Returns true if this object is read-only.          |
  193. |   isDropOnAble          - Returns true if this object can accept a drop.     |
  194. |   isVisible             - Returns true if this object is visible.            |
  195. |   isRefreshOn           - Returns true if this object is in refreshable      |
  196. |                           state.                                             |
  197. |   iconOffset            - Returns the offset of the object's IPointerHandle  |
  198. |                           for the icon. This allows the icon to be used in a |
  199. |                           column of the details view.                        |
  200. |   iconTextOffset        - Returns the offset of the object's IString. This   |
  201. |                           allows the IString to be used in a                 |
  202. |                           column of the details view.                        |
  203. |   setOpen               - Sets the open emphasis.                            |
  204. |   setClosed             - Removes the open emphasis in all containers.       |
  205. |   isOpen                - Returns true if this object is open.               |
  206. ------------------------------------------------------------------------------*/
  207. virtual IContainerObject
  208.  &setIcon           ( const IPointerHandle& iconHandle),
  209.  &setIcon           ( const IResourceId&    iconId),
  210.  &setIcon           ( unsigned long         iconId),
  211.  
  212.  &setIconText       ( const char*           iconText),
  213.  &setIconText       ( const IString&        iconText),
  214.  &setIconText       ( const IResourceId&    iconTextId);
  215.  
  216. virtual IPointerHandle
  217.   icon              ( ) const;
  218. virtual IString
  219.   iconText          ( ) const;
  220.  
  221. virtual IContainerObject
  222.  &setInUse          ( Boolean            inUse = true,
  223.                       IContainerControl* container = 0),
  224.  &removeInUse       ( IContainerControl* container = 0),
  225.  
  226.  &enableDataUpdate  ( Boolean            enable = true,
  227.                       IContainerControl* container = 0),
  228.  &disableDataUpdate ( IContainerControl* container = 0),
  229.  
  230.  &enableDrop        ( Boolean            enable = true,
  231.                       IContainerControl* container = 0),
  232.  &disableDrop       ( IContainerControl* container = 0),
  233.  
  234.  &show              ( Boolean            show = true,
  235.                       IContainerControl* container = 0),
  236.  &hide              ( IContainerControl* container = 0),
  237.  &refresh           ( IContainerControl* container = 0),
  238.  &setRefreshOn      ( Boolean            refreshOn = true),
  239.  &setRefreshOff     ( );
  240.  
  241. virtual Boolean
  242.   isInUse           ( IContainerControl* container = 0) const,
  243.   isReadOnly        ( IContainerControl* container = 0) const,
  244.   isDropOnAble      ( IContainerControl* container = 0) const,
  245.   isVisible         ( IContainerControl* container = 0) const,
  246.   isRefreshOn       ( ) const;
  247.  
  248. static unsigned long
  249.   iconOffset        ( ),
  250.   iconTextOffset    ( );
  251.  
  252.  
  253. virtual IContainerObject
  254.   &setOpen          ( Boolean open = true),
  255.   &setClosed        ( );
  256. virtual Boolean
  257.   isOpen            ( ) const;
  258.  
  259.  
  260. /*------------------------ Object Allocation -----------------------------------
  261. | These functions provide all object allocation and deallocation for instances |
  262. | of the class.  Stack and static instances of this class are not allowed.     |
  263. |   operator new    - Allocates storage for a class instance.                  |
  264. |   operator delete - Deallocates the storage of a class instance.             |
  265. ------------------------------------------------------------------------------*/
  266. #ifdef __DEBUG_ALLOC__
  267. void
  268.   *operator new    ( size_t        size,
  269.                      const char*   fileName,
  270.                      size_t        lineNumber),
  271.    operator delete ( void*,
  272.                      const char* fileName,
  273.                      size_t      lineNumber );
  274. #else
  275. void
  276.   *operator new    ( size_t size),
  277.    operator delete ( void* );
  278.  
  279. #endif
  280.  
  281. /*------------------------ Subclass Provided Functions -------------------------
  282. | These functions must be provided by the subclass if the behavior is          |
  283. | required:                                                                    |
  284. |  handleOpen           - Called when Enter is pressed on an object or a mouse |
  285. |                         double click occurs on an object and the             |
  286. |                         IContainerControl that contains the object has been  |
  287. |                         provided with an ICnrHandler.                        |
  288. |  handleInuseChange    - Called when in-use emphasis changes on an object and |
  289. |                         the IContainerControl that contains the object has   |
  290. |                         been provided with an ICnrHandler.  If the object    |
  291. |                         has just acquired in-use emphasis, acquired is set   |
  292. |                         to true.                                             |
  293. |  handleCursoredChange - Called when cursored emphasis changes on an object   |
  294. |                         and the IContainerControl that contains the object   |
  295. |                         has been provided with an ICnrHandler. If the        |
  296. |                         object has just acquired cursored emphasis, acquired |
  297. |                         is set to true.                                      |
  298. |  handleSelectedChange - Called when selection emphasis changes on an object  |
  299. |                         and the IContainerControl that contains the object   |
  300. |                         has been provided with an ICnrHandler. If the        |
  301. |                         object has just acquired selection emphasis,         |
  302. |                         acquired is set to true.                             |
  303. |  handleTreeCollapse   - Called when this object is a parent in the tree view |
  304. |                         and the descendent objects have been collapsed. This |
  305. |                         is only called when the IContainerControl that       |
  306. |                         contains the object has been provided with an        |
  307. |                         ICnrHandler.                                         |
  308. |  handleTreeExpand     - Called when this object is a parent in the tree view |
  309. |                         and the descendent objects have been expanded.  This |
  310. |                         is only called when the IContainerControl that       |
  311. |                         contains the object has been provided with an        |
  312. |                         ICnrHandler.                                         |
  313. |  helpId               - Called when an ICnrHelpEvent is dispatched to        |
  314. |                         ICnrHandler.  The default behavior is to return 0.   |
  315. |                         If the identifier returned is greater than 0, the    |
  316. |                         default behavior of the container's help handler is  |
  317. |                         to display the help panel.                           |
  318. |  objectCopy           - Called when it is necessary to make a copy of an     |
  319. |                         object.  This occurs when                            |
  320. |                         IContainerControl::copyObjectTo is called.           |
  321. |  operator ==          - Returns true if the objects are at the same storage  |
  322. |                         location.                                            |
  323. ------------------------------------------------------------------------------*/
  324. virtual void
  325.   handleOpen           ( IContainerControl* container),
  326.   handleInuseChange    ( IContainerControl* container,
  327.                          Boolean            acquired),
  328.   handleCursoredChange ( IContainerControl* container,
  329.                          Boolean            acquired),
  330.   handleSelectedChange ( IContainerControl* container,
  331.                          Boolean            acquired),
  332.   handleTreeCollapse   ( IContainerControl* container),
  333.   handleTreeExpand     ( IContainerControl* container);
  334.  
  335. virtual unsigned long
  336.   helpId               ( ) const;
  337.  
  338. virtual IContainerObject
  339.  *objectCopy           ( );
  340.  
  341. Boolean
  342.   operator==           ( const IContainerObject& object);
  343.  
  344.  
  345. protected:
  346. /*----------------------------- Implementation ---------------------------------
  347. | The following functions are used in the implementation of the class:         |
  348. |   setEmphasis       - Sets the passed emphasis attribute On or Off. If a     |
  349. |                       container is not specified, the changes are made to    |
  350. |                       all containers that hold this object.                  |
  351. |   setAttributes     - Sets some attributes Off while setting others On.  It  |
  352. |                       is used to toggle the state of mutually exclusive      |
  353. |                       attributes. If a container is not specified, the       |
  354. |                       changes are made to all containers that hold this      |
  355. |                       object.                                                |
  356. |   incrementUseCount - Increases the count of containers with this object.    |
  357. |   decrementUseCount - Decreases the count of containers with this object.    |
  358. |   setBase           - Stores the address of the real base of this object.    |
  359. |   initialize        - Initializes an object after construction.              |
  360. |   baseRecord        - Returns the address of the real base of this object.   |
  361. |   useCount          - Returns the number of containers with this object.     |
  362. |   isAttribute       - Returns true if the passed attribute is On.            |
  363. ------------------------------------------------------------------------------*/
  364. virtual IContainerObject
  365.  &setEmphasis        ( unsigned long      emphasisAttribute,
  366.                        Boolean            turnOn = true,
  367.                        IContainerControl* container = 0),
  368.  &setAttributes      ( unsigned long      attributeTurnedOff,
  369.                        unsigned long      attributeTurnedOn,
  370.                        IContainerControl* container = 0),
  371.  &incrementUseCount  ( ),
  372.  &decrementUseCount  ( ),
  373.  &setBase            ( const IMiniCnrRecord* baseRecord),
  374.  &initialize         ( );
  375.  
  376. IMiniCnrRecord
  377.  *baseRecord         ( );
  378.  
  379. unsigned long
  380.   useCount           ( ) const;
  381.  
  382. virtual Boolean
  383.   isAttribute        ( unsigned long      attribute,
  384.                        IContainerControl* container  ) const;
  385.  
  386. private:
  387. /*--------------------------------- PRIVATE ----------------------------------*/
  388.  
  389. enum State    { ok=1, opened=2, noInvalidate=4, hasDescendents=8,
  390.                  noRefresh=16, invalid=32, subclassed=64, deleteInProcess=128,
  391.                  nestedDelete=256};
  392.  
  393.  
  394. unsigned long
  395.   iconTextLength() const;
  396. static void
  397.  *newRecord(size_t size),
  398.   deleteRecord(void* precord);
  399.  
  400. int
  401.   flClState;
  402. unsigned long
  403.   ulClUseCount;
  404. IContainerObject
  405.  *pcnrobjClParent;
  406. IMiniCnrRecord
  407.  *pbase;
  408. } ;
  409.  
  410. /*----------------------------------------------------------------------------*/
  411. /* Resume compiler default packing.                                           */
  412. /*----------------------------------------------------------------------------*/
  413. #pragma pack()
  414.  
  415. /*--------------------------------- INLINES ----------------------------------*/
  416. #ifndef I_NO_INLINES
  417.   #include <icnrobj.inl>
  418. #endif
  419.  
  420. #endif  /* _ICNROBJ_ */
  421.