home *** CD-ROM | disk | FTP | other *** search
/ Chip 1997 October / Chip_1997-10_cd.bin / tema / sybase / powerj / hpp.z / WDATATRG.HPP < prev    next >
C/C++ Source or Header  |  1996-12-20  |  18KB  |  657 lines
  1. //
  2. // wdatatrg.hpp
  3. //
  4.  
  5. #ifndef _WDATATRG_HPP_INCLUDED
  6. #define _WDATATRG_HPP_INCLUDED
  7.  
  8. //-----------------------------------------------------------------------
  9. //
  10. // Interfaces used to implement the binding of objects to data sources.
  11. //
  12. // These interfaces are meant to be embedded in other objects.  All
  13. // methods are virtual so that specializations can be created.
  14. //
  15. //-----------------------------------------------------------------------
  16.  
  17. #ifndef _WDATAOBJ_HPP_INCLUDED
  18. #include "wdataobj.hpp"
  19. #endif
  20.  
  21. // Define the basic type of a data target (single or multi/table valued).
  22.  
  23. enum WDataTargetType {
  24.     WDTTCell,
  25.     WDTTColumn,         // Multi-value
  26.     WDTTTable,          // Multi-value
  27.     WDTTLookup,
  28.     WDTTNavigator
  29. };
  30.  
  31. #define WDTTIsMultiValued(T)    ( (T)==WDTTTable || (T)==WDTTColumn )
  32. #define WDTTIsTable(T)          ( (T)==WDTTTable )
  33.  
  34. //
  35. // WDataTarget -- An interface exposed by a bound object.  This interface
  36. //                is what the data source uses to communicate with the
  37. //                object.  The default implementation is to call events
  38. //                on a given event object.
  39. //
  40.  
  41. class WCMCLASS WDataTarget : public WObject {
  42.  
  43.     private:
  44.         WDataTarget( const WDataTarget & );
  45.         WDataTarget& operator=( const WDataTarget & );
  46.  
  47.     public:
  48.  
  49.         WDataTarget( WEventGenerator *eventTarget, WDataTargetType type );
  50.  
  51.         ~WDataTarget();
  52.  
  53.         /*********************************************************
  54.          * Properties
  55.          *********************************************************/
  56.  
  57.         // DataChanged
  58.         //
  59.         //    The target sets this value when the data has changed.
  60.         //    The source uses this to determine if it should invoke
  61.         //    the DataRequest method.
  62.  
  63.         virtual WBool GetDataChanged() const;
  64.         virtual WBool SetDataChanged( WBool changed );
  65.  
  66.         // DataColumns
  67.         //
  68.         //    A string that defines the column or columns that
  69.         //    the target is interested in.
  70.  
  71.         virtual WString GetDataColumns() const;
  72.         virtual WBool   SetDataColumns( const WString & cols );
  73.  
  74.         // DataSource
  75.         //
  76.         //    Setting this registers the target with a WDataSource.
  77.  
  78.         virtual WDataSource *GetDataSource() const;
  79.         virtual WBool        SetDataSource( WDataSource *source );
  80.  
  81.         // DataTouched
  82.         //
  83.         //    The target sets this value when the data has been touched.
  84.         //    Data changed back to old value is considered touched but
  85.         //    not changed.
  86.         //
  87.  
  88.         virtual WBool GetDataTouched() const;
  89.         virtual WBool SetDataTouched( WBool touched );
  90.  
  91.         // Type
  92.         //
  93.         //    What type of target this is.
  94.  
  95.         WDataTargetType GetType() const;
  96.  
  97.         /*********************************************************
  98.          * Methods (called by the data source)
  99.          *********************************************************/
  100.  
  101.         // DataAvailable
  102.         //
  103.         //    The data source calls this method when it has data
  104.         //    available for the target (such as when the current
  105.         //    row changes).  The default implementation is to simply
  106.         //    call the DataAvailable event on the event object.
  107.  
  108.         virtual WBool DataAvailable( WDataAvailableEventData *event );
  109.  
  110.         // DataClose
  111.         //
  112.         //    The data source calls this method when its data set
  113.         //    is no longer available.
  114.  
  115.         virtual WBool DataClose( WDataCloseEventData *event );
  116.  
  117.         // DataOpen
  118.         //
  119.         //    The data source calls this method when a new set of
  120.         //    data is available.  The target can prepare itself
  121.         //    and can also make calls back on the source to bind
  122.         //    columns, etc.
  123.  
  124.         virtual WBool DataOpen( WDataOpenEventData *event );
  125.  
  126.         // DataRequest
  127.         //
  128.         //    The data source calls this method when it wishes
  129.         //    the target to send changed data back to the source.
  130.         //    The default implementation is to simply call the
  131.         //    DataRequest event on the event object.
  132.  
  133.         virtual WBool DataRequest( WDataRequestEventData *event );
  134.  
  135.         /*********************************************************
  136.          * Static functions
  137.          *********************************************************/
  138.  
  139.         // ColumnsToIndexes
  140.         //
  141.         //    Parse the given columns string and save the indexes in the given
  142.         //    array, which is assumed to be at least numberToParse elements
  143.         //    large.
  144.  
  145.         static WBool ColumnsToIndexes( WDataSource * dataSource,
  146.                                        const WString & columns,
  147.                                        WShort * indexes,
  148.                                        WShort numberToParse );
  149.  
  150.         // ColumnsToIndexesEx
  151.         //
  152.         //    Parse given columns and save the indexes in an allocated array.
  153.         //    Return a pointer to the array and the number of columns parsed.
  154.  
  155.         static WBool ColumnsToIndexesEx( WDataSource * dataSource,
  156.                                          const WString & columns,
  157.                                          WShort ** indexes,
  158.                                          WShort & numberParsed );
  159.  
  160.     protected:
  161.     
  162.         WBool            _dataChanged;
  163.         WBool            _dataTouched;
  164.         WDataSource     *_source;
  165.         WEventGenerator *_eventTarget;
  166.         WString          _columns;
  167.         WDataTargetType  _type;
  168. };
  169.  
  170. //
  171. // WDataTargetCell
  172. //
  173. //     A specialization of WDataTarget for single-valued objects.
  174.  
  175. class WCMCLASS WDataTargetCell : public WDataTarget {
  176.  
  177.     public:
  178.  
  179.         WDataTargetCell( WEventGenerator *eventTarget );
  180.  
  181.         ~WDataTargetCell();
  182.  
  183.         /*********************************************************
  184.          * Properties
  185.          *********************************************************/
  186.  
  187.         // Index
  188.  
  189.         WShort GetIndex() const;
  190.  
  191.         // Nullable
  192.  
  193.         WBool GetNullable() const;
  194.  
  195.         // ReadOnly
  196.  
  197.         WBool GetReadOnly() const;
  198.  
  199.         // SourceValue
  200.  
  201.         WDataValue GetSourceValue() const;
  202.         WBool      SetSourceValue( const WDataValue & value );
  203.  
  204.         /*********************************************************
  205.          * Overrides
  206.          *********************************************************/
  207.  
  208.         virtual WBool SetDataColumns( const WString & cols );
  209.  
  210.     protected:
  211.  
  212.         // ParseColumns
  213.  
  214.         WBool ParseColumns( WDataSource *src ) const;
  215.  
  216.         WShort  _index;
  217.         WBool   _tried;
  218. };
  219.  
  220. //
  221. // WDataTargetBoolCell
  222. //
  223.  
  224. class WCMCLASS WDataTargetBoolCell : public WDataTargetCell {
  225.  
  226.     public:
  227.  
  228.         WDataTargetBoolCell( WEventGenerator *eventTarget );
  229.  
  230.         ~WDataTargetBoolCell();
  231.  
  232.         /*********************************************************
  233.          * Properties
  234.          *********************************************************/
  235.  
  236.         // DataChecked
  237.  
  238.         WBool   GetDataChecked() const;
  239.         WBool   SetDataChecked( WBool checked );
  240.  
  241.         // DataIndeterminate
  242.         //
  243.         //  TRUE if the current data value matches neither the checked nor
  244.         //  the unchecked value.
  245.  
  246.         WBool   GetDataIndeterminate() const;
  247.  
  248.         // DataValueChecked
  249.  
  250.         WString GetDataValueChecked() const;
  251.         WBool   SetDataValueChecked( const WString & str );
  252.  
  253.         // DataValueUnchecked
  254.  
  255.         WString GetDataValueUnchecked() const;
  256.         WBool   SetDataValueUnchecked( const WString & str );
  257.  
  258.     protected:
  259.  
  260.         WString _checked;
  261.         WString _unchecked;
  262. };
  263.  
  264. //
  265. // WDataTargetColumn
  266. //
  267. //     A specialization of WDataTarget for multiple-valued objects which display
  268. //     one column - ListBox.
  269. //     This does not support updates to the database.
  270. //
  271.  
  272. class WCMCLASS WDataTargetColumn : public WDataTarget {
  273.  
  274.     public:
  275.  
  276.         WDataTargetColumn( WEventGenerator *eventTarget );
  277.  
  278.         ~WDataTargetColumn();
  279.  
  280.         /*********************************************************
  281.          * Properties
  282.          *********************************************************/
  283.  
  284.         // DataTrackRow
  285.  
  286.         WBool GetDataTrackRow() const;
  287.         WBool SetDataTrackRow( WBool trackRow );
  288.  
  289.         // SourceValues
  290.  
  291.         WBool GetSourceValues( WDataValue *value, WDataValue *data ) const;
  292.  
  293.         /*********************************************************
  294.          * Methods
  295.          *********************************************************/
  296.  
  297.         // BindToSource
  298.  
  299.         WBool BindToSource() const;
  300.  
  301.         /*********************************************************
  302.          * Overrides
  303.          *********************************************************/
  304.  
  305.         WBool SetDataColumns( const WString & cols );
  306.  
  307.     protected:
  308.  
  309.         // ParseColumns
  310.  
  311.         WBool ParseColumns() const;
  312.  
  313.         WBool           _trackRow;
  314.         WShort          _valueIndex;
  315.         WShort          _dataIndex;
  316. };
  317.  
  318. //
  319. // WDataTargetTable
  320. //
  321.  
  322. class WCMCLASS WDataTargetTable : public WDataTarget {
  323.  
  324.     public:
  325.  
  326.         WDataTargetTable( WEventGenerator *eventTarget );
  327.  
  328.         ~WDataTargetTable();
  329.  
  330.         /*********************************************************
  331.          * Properties
  332.          *********************************************************/
  333.  
  334.         // BottomRow
  335.  
  336.         WLong GetBottomRow() const;
  337.         WBool SetBottomRow( WLong bottomRow );
  338.  
  339.         // Column
  340.  
  341.         const WDataColumn & GetColumn( WShort index ) const;
  342.  
  343.         // ColumnChanged
  344.  
  345.         WBool GetColumnChanged( WShort index ) const;
  346.         WBool SetColumnChanged( WShort index, WBool changed );
  347.  
  348.         // ColumnCount
  349.  
  350.         WShort GetColumnCount() const;
  351.  
  352.         // ColumnName
  353.  
  354.         WString GetColumnName( WShort index ) const;
  355.  
  356.         // DataTrackRow
  357.  
  358.         WBool GetDataTrackRow() const;
  359.         WBool SetDataTrackRow( WBool trackRow );
  360.  
  361.         // DataGuardRows
  362.  
  363.         WLong GetDataGuardRows() const;
  364.         WBool SetDataGuardRows( WLong guardRows );
  365.  
  366.         // DataKeptRows
  367.  
  368.         WLong GetDataKeptRows() const;
  369.         WBool SetDataKeptRows( WLong keptRows );
  370.  
  371.         // SourceValue
  372.  
  373.         WDataValue GetSourceValue( WShort index ) const;
  374.         WBool SetSourceValue( WShort index, const WDataValue & value );
  375.  
  376.         // TopRow
  377.  
  378.         WLong GetTopRow() const;
  379.         WBool SetTopRow( WLong topRow );
  380.  
  381.         /*********************************************************
  382.          * Methods
  383.          *********************************************************/
  384.  
  385.         // BindToSource
  386.  
  387.         WBool BindToSource();
  388.  
  389.         // FetchGuardRows
  390.         //
  391.         //  Returns the number of guard rows fetched.
  392.  
  393.         WLong FetchGuardRows( WLong checkRow, WBool restoreCurrentRow );
  394.  
  395.         /*********************************************************
  396.          * Overrides
  397.          *********************************************************/
  398.  
  399.         virtual WBool SetDataColumns( const WString & cols );
  400.  
  401.         virtual WBool DataAvailable( WDataAvailableEventData *ev );
  402.  
  403.     protected:
  404.  
  405.         /*********************************************************
  406.          * Internal
  407.          *********************************************************/
  408.  
  409.         // ParseColumns
  410.  
  411.         WBool ParseColumns() const;
  412.  
  413.         // SendGuardRowEvent
  414.  
  415.         WBool SendGuardRowEvent( WDataSource *src, WLong row, WLong count,
  416.                                  WULong action, WBool top ) const;
  417.  
  418.         /*********************************************************
  419.          * Data Members
  420.          *********************************************************/
  421.  
  422.         WBool           _trackRow;
  423.         WLong           _guardRows;
  424.         WLong           _keptRows;
  425.         WShort *        _indexes;
  426.         WShort          _columnCount;
  427.         WLong           _topRow;
  428.         WLong           _bottomRow;
  429.         WLong           _addedRows;
  430.         WLong           _deletedRows;
  431.         WBool           _atTop;
  432.         WBool           _atBottom;
  433.         WBool *         _changed;
  434. };
  435.  
  436. //
  437. // WDataLookup -- A specialization of WDataTarget to support lookup-type
  438. //                bound objects.
  439. //                Calls the DataLookupItem event on the bound object.
  440. //                Does not call the DataOpen/Available/Request/Close events.
  441. //
  442.  
  443. class WCMCLASS WDataLookup : public WDataTarget {
  444.  
  445.     public:
  446.  
  447.         WDataLookup( WEventGenerator *eventTarget );
  448.  
  449.         ~WDataLookup();
  450.  
  451.         /*********************************************************
  452.          * Properties
  453.          *********************************************************/
  454.  
  455.         // HasDisplayColumn
  456.         //
  457.         //  TRUE if a display column was specified, FALSE if only a value
  458.         //  column was specified
  459.  
  460.         virtual WBool GetHasDisplayColumn() const;
  461.  
  462.         /*********************************************************
  463.          * Methods
  464.          *********************************************************/
  465.  
  466.         // FetchLookupItems
  467.         //
  468.         //  Calls the WDataLookupItem event for each data item.
  469.         //  This can be called directly by the target (the data source will be
  470.         //  opened and closed automatically) and will otherwise be called
  471.         //  internally when the specified data source is opened.
  472.  
  473.         virtual WBool FetchLookupItems();
  474.  
  475.         /*********************************************************
  476.          * Overrides
  477.          *********************************************************/
  478.  
  479.         virtual WBool GetDataChanged() const;
  480.         virtual WBool SetDataChanged( WBool );
  481.  
  482.         virtual WBool SetDataColumns( const WString & cols );
  483.  
  484.         virtual WBool DataAvailable( WDataAvailableEventData * );
  485.  
  486.         virtual WBool DataClose( WDataCloseEventData * );
  487.  
  488.         virtual WBool DataOpen( WDataOpenEventData *event );
  489.  
  490.         virtual WBool DataRequest( WDataRequestEventData * );
  491.  
  492.         /*********************************************************
  493.          * Internal
  494.          *********************************************************/
  495.  
  496.     protected:
  497.  
  498.         // ParseColumns
  499.  
  500.         WBool ParseColumns() const;
  501.  
  502.         // SendLookupItemEvent
  503.  
  504.         WBool SendLookupItemEvent( WDataSource *src, WDataValue *value,
  505.                                    WDataValue *displayValue,
  506.                                    WULong action ) const;
  507.  
  508.         // DoFetch
  509.         
  510.         WBool DoFetch( WDataSource * src, WBool weOpened ) const;
  511.  
  512.         /*********************************************************
  513.          * Data Members
  514.          *********************************************************/
  515.  
  516.         WShort          _valueIndex;
  517.         WShort          _displayIndex;
  518.         WBool           _ignoreDataOpen;
  519. };
  520.  
  521. //
  522. // Events triggered by the data source
  523. //
  524. //  These events originate in the data source.
  525. //
  526.  
  527. //
  528. // Reasons for data available/request
  529. //
  530.  
  531. enum {
  532.     WDataReasonNone,
  533.     WDataReasonMove,
  534.     WDataReasonUpdate,
  535.     WDataReasonDelete,
  536.     WDataReasonPrepareForAdd,
  537.     WDataReasonAdd,
  538.     WDataReasonFill,
  539.     WDataReasonCancelUpdate,
  540.     WDataReasonClear,
  541.     WDataReasonEnable,
  542.     WDataReasonDisable,
  543.     WDataReasonEnableAlwaysRW,
  544.     WDataReasonDisableAlwaysRW
  545. };
  546.  
  547. //
  548. // Suggested actions for data available/request
  549. //
  550.  
  551. enum {
  552.     WDataActionNone,
  553.     WDataActionRefreshRow,      // moved to a new row
  554.     WDataActionFillBegin,       // a fill is beginning
  555.     WDataActionFillEnd,         // a fill is ending
  556.     WDataActionClear,           // clear the control
  557.     WDataActionRenumber,        // multi-value, recount internal row numbers
  558.     WDataActionNewState,        // sent to navigators
  559.     WDataActionEnable,
  560.     WDataActionDisable,
  561.     WDataActionEnableAlwaysRW,  // targets always read/write
  562.     WDataActionDisableAlwaysRW
  563. };
  564.  
  565. //
  566. // WDataOpenEventData
  567. //
  568.  
  569. struct WDataOpenEventData : public WEventData {
  570.     WDataSource      *dataSource;
  571.     WBool             isRequery;
  572. };
  573.  
  574. //
  575. // WDataAvailableEventData
  576. //
  577.  
  578. struct WDataAvailableEventData : public WEventData {
  579.     WDataSource      *dataSource;
  580.     WLong             currentRow;
  581.     WULong            reason;
  582.     WULong            suggestedAction;
  583. };
  584.  
  585. //
  586. // WDataRequestEventData
  587. //
  588.  
  589. struct WDataRequestEventData : public WEventData {
  590.     WDataSource      *dataSource;
  591.     WLong             currentRow;
  592.     WULong            reason;
  593.     WULong            suggestedAction;
  594. };
  595.  
  596. //
  597. // WDataCloseEventData
  598. //
  599.  
  600. struct WDataCloseEventData : public WEventData {
  601.     WDataSource *dataSource;
  602.     WBool        isRequery;
  603. };
  604.  
  605. //
  606. // Events triggered by the data target
  607. //
  608. //  These events originate in the data target.
  609. //
  610.  
  611. //
  612. // GuardRowEvent actions
  613. //
  614.  
  615. enum {
  616.     WDTGRActionNone,
  617.     WDTGRActionGroupBegin,      // start of guard row group
  618.     WDTGRActionGroupEnd,        // end of guard row group
  619.     WDTGRActionAddRow,          // add a row (top or bottom)
  620. };
  621.  
  622. //
  623. // WDataGuardRowEventData
  624. //
  625.  
  626. struct WDataGuardRowEventData : public WEventData {
  627.     WDataSource *       dataSource;
  628.     WLong               currentRow;
  629.     WLong               count;      // Starts at 0, for current fill
  630.     WULong              action;
  631.     WBool               top;        // TRUE if action refers to top row
  632. };
  633.  
  634. //
  635. // LookupItemEvent actions
  636. //
  637.  
  638. enum {
  639.     WDTLIActionNone,
  640.     WDTLIActionFillBegin,
  641.     WDTLIActionFillEnd,
  642.     WDTLIActionAddRow,
  643. };
  644.  
  645. //
  646. // WDataLookupItemEventData
  647. //
  648.  
  649. struct WDataLookupItemEventData : public WEventData {
  650.     WDataSource *       dataSource;
  651.     WDataValue *        value;
  652.     WDataValue *        displayValue;
  653.     WULong              action;
  654. };
  655.  
  656. #endif
  657.