home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / ICNRCOL.HPP < prev    next >
Text File  |  1993-10-22  |  28KB  |  496 lines
  1. #ifndef _ICNRCOL_
  2. #define _ICNRCOL_
  3. /*******************************************************************************
  4. * FILE NAME: icnrcol.hpp                                                       *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     IContainerColumn - Details View column information.                      *
  9. *                                                                              *
  10. * COPYRIGHT:                                                                   *
  11. *   (C) Copyright IBM Corporation 1992                                         *
  12. *   All Rights Reserved                                                        *
  13. *   Licensed Materials * Property of IBM                                       *
  14. *                                                                              *
  15. * HISTORY:                                                                     *
  16. *******************************************************************************/
  17.  
  18. #ifndef _IVBASE_
  19.   #include <ivbase.hpp>
  20. #endif
  21.  
  22. #ifndef _BITFLAGS_
  23.    #include <ibitflag.hpp>
  24. #endif
  25.  
  26. #ifndef _HANDLE_
  27.    #include <ihandle.hpp>
  28. #endif
  29.  
  30. /*----------------------------------------------------------------------------*/
  31. /* Align classes on four byte boundary.                                       */
  32. /*----------------------------------------------------------------------------*/
  33. #pragma pack(4)
  34.  
  35.  
  36. //  Forward Declarations
  37. class IContainerWindow;
  38. class IContainerControl;
  39. class IContainerObject;
  40. class IResourceId;
  41. class IString;
  42. class IDate;
  43. class ITime;
  44. struct _FIELDINFO;
  45.  
  46.  
  47. class IContainerColumn : public IVBase
  48. {
  49. typedef IVBase
  50.   Inherited;
  51. /*******************************************************************************
  52. *  The IContainerColumn class provides the container with the ability          *
  53. *  to display a details view. Functions exist to add, delete, and hide         *
  54. *  columns in a container control. It also defines the characteristics         *
  55. *  of the column header (text or icon) and the position of the data in         *
  56. *  the column record.                                                          *
  57. *                                                                              *
  58. *  The data in the object and the data displayed in the column are connected.  *
  59. *  For a user to have a details view, IContainerObject must be subclassed      *
  60. *  and extended with the additional "fields" to be displayed in the columns    *
  61. *  of the container.  The column object must know the exact offset and type    *
  62. *  of the data in the object because it handles the drawing of this data.      *
  63. *  It is the class user's responsibility to ensure that the column object is   *
  64. *  correctly informed.  If it is not, the behavior of the column is undefined. *
  65. *                                                                              *
  66. *  The default implementation of a container column has:                       *
  67. *                                                                              *
  68. *    - A heading that contains centered, read-only text                        *
  69. *    - A horizontal separator under the heading                                *
  70. *    - A vertical separator between columns                                    *
  71. *    - String data that is non-editable, left-justified, and centered          *
  72. *      vertically.                                                             *
  73. *                                                                              *
  74. *  Note:  An IContainerColumn object can be added to one container only.       *
  75. *                                                                              *
  76. * EXAMPLE:                                                                     *
  77. *                                                                              *
  78. * IContainerColumn pIcon = new IContainerColumn(                               *
  79. *                         IContainerObject :: iconOffset(),                    *
  80. *                         IContainerColumn::defaultHeadingStyle(),             *
  81. *                         IContainerColumn::icon   |                           *
  82. *                         IContainerColumn::alignVerticallyCentered);          *
  83. * IContainerColumn pName = new IContainerColumn(                               *
  84. *                         IContainerObject::iconTextOffset(),                  *
  85. *                         IContainerColumn::defaultHeadingStyle(),             *
  86. *                         IContainerColumn::string |                           *
  87. *                         IContainerColumn::alignVerticallyCentered |          *
  88. *                         IContainerColumn::alignLeft |                        *
  89. *                         IContainerColumn::horizontalSeparator);              *
  90. *                                                                              *
  91. *                                                                              *
  92. * container().addColumn(pIcon);                                                *
  93. * container().addColumn(pName);                                                *
  94. *                                                                              *
  95. *                                                                             *
  96. *******************************************************************************/
  97. friend class IContainerControl;
  98.  
  99.                          /*----------------------*/
  100.                          /*    PUBLIC SECTION    */
  101.                          /*----------------------*/
  102. public:
  103.  
  104. /*---------------------------- Style -------------------------------------------
  105. | Style - A flag used to represent construction values for both the column     |
  106. |         heading and the column data.                                         |
  107. |                                                                              |
  108. | The following styles are currently supported as both heading styles and      |
  109. | data styles. Only one of alignTop, alignBottom, and alignVerticallyCentered, |
  110. | and one of alignLeft, alignRight, and alignCentered can be specified.        |
  111. |   string                    - The data is a string.                          |
  112. |   icon                      - The data is an icon.                           |
  113. |   alignTop                  - The data is aligned to the top of the cell.    |
  114. |   alignBottom               - The data is aligned to the bottom of the cell. |
  115. |   alignVerticallyCentered   - The data is vertically centered in the cell.   |
  116. |   alignLeft                 - The data is aligned to the left of the cell.   |
  117. |   alignRight                - The data is aligned to the right of the cell.  |
  118. |   alignCentered             - The data is horizontally centered in the cell. |
  119. ------------------------------------------------------------------------------*/
  120. typedef unsigned long
  121.   Style;
  122.  
  123. static const Style
  124.   string,                        /* default */
  125.   icon,
  126.   alignTop,
  127.   alignBottom,
  128.   alignVerticallyCentered,     /* default */
  129.   alignLeft,                   /* default */
  130.   alignRight,
  131.   alignCentered;
  132.  
  133. /*---------------------------- Heading Style -----------------------------------
  134. | HeadingStyle - A flag used to represent construction values for the column   |
  135. |                heading.                                                      |
  136. |                                                                              |
  137. | The heading can contain the following styles:                                |
  138. |                                                                              |
  139. |   readOnlyHeading           - The data in the heading cannot be edited.      |
  140. |   classDefaultHeadingStyle  - The class default styles for a heading are     |
  141. |                               string, alignVerticallyCentered, alignLeft,    |
  142. |                               and readOnlyHeading.                           |
  143. |                                                                              |
  144. | Default heading styles can be queried and set with the following functions:  |
  145. |                                                                              |
  146. |   defaultHeadingStyle        - Retrieves the default heading style.          |
  147. |   setDefaultHeadingStyle     - Sets a new default heading style.             |
  148. ------------------------------------------------------------------------------*/
  149. typedef unsigned long
  150.   HeadingStyle;
  151.  
  152. static const HeadingStyle
  153.   readOnlyHeading,        /* default */
  154.   classDefaultHeadingStyle;
  155.  
  156. static Style
  157.   defaultHeadingStyle     ( );
  158.  
  159. static void
  160.   setDefaultHeadingStyle  ( HeadingStyle headingStyle);
  161.  
  162. /*---------------------------- Data Style --------------------------------------
  163. | DataStyle    - A flag used to represent construction values for the data in a|
  164. |                column.                                                       |
  165. |                                                                              |
  166. | A column can contain the following data styles:                              |
  167. |                                                                              |
  168. |   date                      - The data is displayed in date format with      |
  169. |                               National Language Support enabled.  The date   |
  170. |                               format is a four byte field with a single      |
  171. |                               byte each for day and month and two bytes      |
  172. |                               for year (in order).                           |
  173. |   time                      - The data is displayed in time format with      |
  174. |                               National Language Support enabled. The time    |
  175. |                               format is a four byte field with a single      |
  176. |                               byte each for hours, minutes, and seconds      |
  177. |                               (in order). The last byte is reserved.         |
  178. |   number                    - The data is an unsigned long number.           |
  179. |   horizontalSeparator       - A horizontal separator is provided beneath     |
  180. |                               column headings.                               |
  181. |   verticalSeparator         - A vertical separator is drawn after this       |
  182. |                               column.                                        |
  183. |   handleDrawItem            - Causes an ICnrDrawItemEvent to be dispatched   |
  184. |                               to the ICnrDrawHandler::drawDetailsItem        |
  185. |                               function when drawing a details item is        |
  186. |                               required.                                      |
  187. |   readOnly                  - The data in the column cannot be edited.       |
  188. |   invisible                 - The data in the column is invisible.           |
  189. |   classDefaultDataStyle     - The default style for data in a column is      |
  190. |                               string, alignVerticallyCentered, alignLeft,    |
  191. |                               and readOnly.                                  |
  192. |                                                                              |
  193. | Default data styles can be queried and set with the following functions:     |
  194. |                                                                              |
  195. |   defaultDataStyle           - Retrieves the default data style.             |
  196. |   setDefaultDataStyle        - Sets a new default data style.                |
  197. ------------------------------------------------------------------------------*/
  198. typedef unsigned long
  199.   DataStyle;
  200.  
  201. static const DataStyle   /* plus Style styles */
  202.   date,
  203.   time,
  204.   number,
  205.   horizontalSeparator,
  206.   verticalSeparator,
  207.   handleDrawItem,
  208.   readOnly,
  209.   invisible,
  210.   classDefaultDataStyle;
  211.  
  212. static Style
  213.   defaultDataStyle        ( );
  214. static void
  215.   setDefaultDataStyle     ( DataStyle    dataStyle);
  216.  
  217. /*------------------------------ Related Types ---------------------------------
  218. | The following enumeration types are defined to pass "modes" to various       |
  219. | implementation functions:                                                    |
  220. |   DataSource          - A construction value that indicates whether the      |
  221. |                         column data is either the icon or the icon text      |
  222. |                         stored in the object.  The allowable values are:     |
  223. |                                                                              |
  224. |                         isIcon         - The data used in the column is the  |
  225. |                                          icon from the icon view.            |
  226. |                         isIconViewText - The data used in the column is the  |
  227. |                                          text from the icon view.            |
  228. |                                                                              |
  229. |   VerticalAlignment   - The values used to vertically align text in the      |
  230. |                         column (top, bottom, centeredVertically).            |
  231. |   HorizontalAlignment - The values used to horizontally align text in the    |
  232. |                         column (left, right, centered).                      |
  233. ------------------------------------------------------------------------------*/
  234. enum DataSource          { isIcon, isIconViewText };
  235. enum VerticalAlignment   { top, bottom, centeredVertically};
  236. enum HorizontalAlignment { left, right, centered};
  237.  
  238. /*------------------------ Constructors ----------------------------------------
  239. | You can construct an instance of this class in the following ways:           |
  240. |    - By providing the offset of the object data to be displayed in the       |
  241. |      column and, optionally, the styles to be used for the heading and data. |
  242. |    - By providing a type of data that is part of the IContainerObject        |
  243. |      (as opposed to the user portion of the object) and, optionally, the     |
  244. |      styles to be used for the heading and data.                             |
  245. |    - By copying from an existing container column.                           |
  246. ------------------------------------------------------------------------------*/
  247.   IContainerColumn     ( unsigned long       dataOffset,
  248.                          const HeadingStyle& title = defaultHeadingStyle(),
  249.                          const DataStyle&    data = defaultDataStyle());
  250.  
  251.   IContainerColumn     (DataSource          objectDataType,
  252.                         const HeadingStyle& title = defaultHeadingStyle(),
  253.                         const DataStyle&    data = defaultDataStyle());
  254.  
  255.   IContainerColumn     ( const IContainerColumn& column);
  256.  
  257. virtual
  258.   ~IContainerColumn    ( );
  259.  
  260. /*-------------------------------- Accessors -----------------------------------
  261. | The following functions provide means of getting and setting the accessible  |
  262. | attributes of instances of this class:                                       |
  263. |   setHeadingText         - Sets the text to be used for the heading and      |
  264. |                            changes the style to string.                      |
  265. |   setHeadingIcon         - Sets the icon to be used for the heading and      |
  266. |                            changes the style to icon.                        |
  267. |   headingText            - Returns the text in the heading if the style is   |
  268. |                            string.                                           |
  269. |   headingIcon            - Returns the icon in the heading if the style is   |
  270. |                            icon.                                             |
  271. |   enableHeadingUpdate    - Allows an edit field to be opened on the heading. |
  272. |                            This is valid only if the style is string.        |
  273. |   disableHeadingUpdate   - Prevents editing of the heading.                  |
  274. |   enableDataUpdate       - Allows an edit field to be opened in the column   |
  275. |                            data.  This is valid only if the style is string. |
  276. |   disableDataUpdate      - Prevents editing of the column data.              |
  277. |   show                   - Makes the column visible.                         |
  278. |   hide                   - Makes the column invisible.                       |
  279. |   isVisible              - Returns true if the column is visible in the      |
  280. |                            container.                                        |
  281. |   showSeparators         - Adds a vertical separator after a column, a       |
  282. |                            horizontal separator under the column heading, or |
  283. |                            both.  By default, both separators are added.     |
  284. |   hideSeparators         - Removes the vertical separator after a column, a  |
  285. |                            horizontal separator under the column heading, or |
  286. |                            both.  By default, both separators are removed.   |
  287. |   justifyHeading         - Sets the justification of the heading to a        |
  288. |                            horizontal and vertical alignment.  Settings for  |
  289. |                            these are:                                        |
  290. |                              - For HorizontalAlignment, set it to either     |
  291. |                                left, right, or centered.                     |
  292. |                              - For VerticalAlignment, set it to either top,  |
  293. |                                bottom, or centeredVertically.                |
  294. |   justifyData            - Sets the justification of the data to a           |
  295. |                            horizontal and vertical alignment.  Settings for  |
  296. |                            these are:                                        |
  297. |                              - For HorizontalAlignment, set it to either     |
  298. |                                left, right, or centered.                     |
  299. |                              - For VerticalAlignment, set it to either top,  |
  300. |                                bottom, or centeredVertically.                |
  301. |   setDisplayWidth        - Sets the displayable width of the column, in      |
  302. |                            pixels.                                           |
  303. |   displayWidth           - Returns the displayable width of the column, in   |
  304. |                            pixels, after showing the details view.           |
  305. |   setDataOffset          - Identifies where the data is located in a         |
  306. |                            container object for this column.                 |
  307. |   setHelpId              - Stores a help panel identifier.                   |
  308. |   helpId                 - Retrieves a help panel identifier.                |
  309. |   isDate                 - Returns true if the data in the column is a date. |
  310. |   isTime                 - Returns true if the data in the column is a time. |
  311. |   isNumber               - Returns true if the data in the column is a       |
  312. |                            number.                                           |
  313. |   isString               - Returns true if the data in the column is a       |
  314. |                            pointer to a character string or an IString.      |
  315. |   isIconHandle           - Returns true if the data in the column is an icon.|
  316. |   isReadOnly             - Returns true if the data in the column cannot be  |
  317. |                            edited.                                           |
  318. |   isHeadingReadOnly      - Returns true if the data in the column heading    |
  319. |                            cannot be edited.                                 |
  320. |   isHeadingString        - Returns true if the data in the column heading    |
  321. |                            is a character string.                            |
  322. |   isHeadingIconHandle    - Returns true if the data in the column heading    |
  323. |                            is an icon.                                       |
  324. |   hasHorizontalSeparator - Returns true if the column heading has a          |
  325. |                            separator drawn under it.                         |
  326. |   hasVeritcalSeparator   - Returns true if the column heading has a          |
  327. |                            vertical separator drawn after the column.        |
  328. ------------------------------------------------------------------------------*/
  329. virtual IContainerColumn
  330.  &setHeadingText         ( const char*           text),
  331.  &setHeadingText         ( const IResourceId&    textId),
  332.  &setHeadingIcon         ( const IPointerHandle& iconHandle),
  333.  &setHeadingIcon         ( const IResourceId&    iconId),
  334.  &setHeadingIcon         ( unsigned long         iconId);
  335.  
  336. virtual IString
  337.   headingText            ( ) const;
  338. virtual IPointerHandle
  339.   headingIcon            ( ) const;
  340.  
  341. virtual IContainerColumn
  342.  &enableHeadingUpdate    ( Boolean enable = true),
  343.  &disableHeadingUpdate   ( ),
  344.  &enableDataUpdate       ( Boolean enable = true),
  345.  &disableDataUpdate();
  346.  
  347. virtual IContainerColumn
  348.  &show                   ( Boolean visible = true),
  349.  &hide(),
  350.  &showSeparators         ( const DataStyle& separatorStyles =
  351.                            horizontalSeparator | verticalSeparator),
  352.  &hideSeparators         ( const DataStyle& separatorStyles =
  353.                            horizontalSeparator | verticalSeparator);
  354.  
  355.  
  356. virtual IContainerColumn
  357.  &justifyData         ( VerticalAlignment   = centeredVertically,
  358.                         HorizontalAlignment = centered),
  359.  &justifyHeading      ( VerticalAlignment   = centeredVertically,
  360.                         HorizontalAlignment = centered);
  361.  
  362. virtual IContainerColumn
  363.  &setDisplayWidth     ( unsigned long widthInPixels);
  364. virtual unsigned long
  365.   displayWidth        ( );
  366.  
  367. IContainerColumn
  368.  &setDataOffset       ( unsigned long dataOffset),
  369.  &setHelpId           ( unsigned long helpId);
  370.  
  371. unsigned long
  372.   helpId              ( ) const;
  373.  
  374. Boolean
  375.  isVisible              ( ) const,
  376.  isDate                 ( ) const,
  377.  isTime                 ( ) const,
  378.  isNumber               ( ) const,
  379.  isString               ( ) const,
  380.  isIconHandle           ( ) const,
  381.  isReadOnly             ( ) const,
  382.  isHeadingReadOnly      ( ) const,
  383.  isHeadingString        ( ) const,
  384.  isHeadingIconHandle    ( ) const,
  385.  hasHorizontalSeparator ( ) const,
  386.  hasVerticalSeparator   ( ) const;
  387.  
  388.  
  389. VerticalAlignment
  390.   verticalDataAlignment      ( ) const,
  391.   verticalHeadingAlignment   ( ) const;
  392. HorizontalAlignment
  393.   horizontalDataAlignment    ( ) const,
  394.   horizontalHeadingAlignment ( ) const;
  395.  
  396.  
  397. /*---------------------------Data Retrieval ------------------------------------
  398. | The following functions are used to retrieve data that is stored in an       |
  399. | object referenced by this column.                                            |
  400. |   dataAsNumber - Returns the data in the passed object referenced by this    |
  401. |                  column as an unsigned long integer.  All data types can be  |
  402. |                  returned as an unsigned long integer.                       |
  403. |   dataAsString - Returns the data in the passed object referenced by this    |
  404. |                  column as an IString.  An IInvalidRequest exception occurs  |
  405. |                  if the type of the data is not IContainerColumn::string.    |
  406. |   dataAsDate   - Returns the data in the passed object referenced by this    |
  407. |                  column as an IDate.  An IInvalidRequest exception occurs if |
  408. |                  the type of the data is not IContainerColumn::date.         |
  409. |   dataAsTime   - Returns the data in the passed object referenced by this    |
  410. |                  column as an ITime.  An IInvalidRequest exception occurs if |
  411. |                  the type of the data is not IContainerColumn::time.         |
  412. |   dataAsIcon   - Returns the data in the passed object referenced by this    |
  413. |                  column as an IPointerHandle.  An IInvalidRequest exception  |
  414. |                  occurs if the type of the data is not                       |
  415. |                  IContainerColumn::icon.                                     |
  416. ------------------------------------------------------------------------------*/
  417. unsigned long
  418.   dataAsNumber        ( const IContainerObject* object) const;
  419. IString
  420.   dataAsString        ( const IContainerObject* object) const;
  421. IDate
  422.   dataAsDate          ( const IContainerObject* object) const;
  423. ITime
  424.   dataAsTime          ( const IContainerObject* object) const;
  425. IPointerHandle
  426.   dataAsIcon          ( const IContainerObject* object) const;
  427.  
  428. protected:
  429. /*----------------------------- Implementation ---------------------------------
  430. | The following functions are used in the implementation of the class:         |
  431. |   setTitleAttributes - Sets the passed attribute into the title.             |
  432. |   setDataAttributes  - Sets the passed attribute into the data.              |
  433. |   titleAttributes    - Returns the current title attributes in the           |
  434. |                        container.                                            |
  435. |   dataAttributes     - Returns the current data attributes in the container. |
  436. |   columnInfo         - Returns the address of the container's column record. |
  437. |   setColumnInfo      - Stores the address of the container's column record.  |
  438. |   container          - Returns the container in which this column is         |
  439. |                        located.                                              |
  440. |   setContainer       - Stores the container in which this column is located. |
  441. |   invalidate         - Causes a refresh of the column if it is in a          |
  442. |                        container.                                            |
  443. ------------------------------------------------------------------------------*/
  444. virtual IContainerColumn
  445.  &setTitleAttributes    ( unsigned long  titleAttributes),
  446.  &setDataAttributes     ( unsigned long  dataAttributes);
  447.  
  448. virtual unsigned long
  449.   titleAttributes       ( ) const,
  450.   dataAttributes        ( ) const;
  451.  
  452. _FIELDINFO
  453.  *columnInfo            ( ) const;
  454.  
  455. IContainerControl
  456.  *container             ( ) const;
  457.  
  458. IContainerColumn
  459.  &setContainer          ( IContainerControl* container),
  460.  &setColumnInfo         ( _FIELDINFO*        fieldinfo),
  461.  &invalidate            ( );
  462.  
  463.  
  464.  
  465. private:
  466. /*--------------------------------- PRIVATE ----------------------------------*/
  467.  
  468. const char*
  469.   headingTextRef        ( ) const;
  470. _FIELDINFO
  471.  *pfieldinfoCl;
  472.  
  473. IContainerControl
  474.  *pcnrctlCl;
  475. IPointerHandle
  476.   ptrhCl;
  477. static Style
  478.   currentDefaultHeadingStyle,
  479.   currentDefaultDataStyle;
  480. unsigned long
  481.   ulHelpId;
  482. };
  483.  
  484. /*----------------------------------------------------------------------------*/
  485. /* Resume compiler default packing.                                           */
  486. /*----------------------------------------------------------------------------*/
  487. #pragma pack()
  488.  
  489. /*--------------------------------- INLINES ----------------------------------*/
  490. #ifndef I_NO_INLINES
  491.   #include <icnrcol.inl>
  492. #endif
  493.  
  494.  
  495. #endif
  496.