home *** CD-ROM | disk | FTP | other *** search
/ On Hand / On_Hand_From_Softbank_1994_Release_2_Disc_2_1994.iso / 00202 / s / disk3 / tn001.tx_ / tn001.bin
Text File  |  1993-04-28  |  4KB  |  96 lines
  1. Microsoft Visual Basic 3.00                            Microsoft Corporation
  2. Technical Notes
  3.  
  4. TN001.TXT:  Support for DT_OBJECT Properties
  5.  
  6. This note describes how to use OLE Automation by creating a custom control
  7. property whose data type is DT_OBJECT.
  8.  
  9. ========================================================================
  10.  
  11. ------------
  12. Introduction
  13. ------------
  14. The Visual Basic 3.0 Control Development Kit allows you to create custom
  15. controls that support OLE Automation.  A custom control can define
  16. a DT_OBJECT type property, whose value is a 4-byte pointer to an IDispatch
  17. interface.  If your control can contain or refer to an OLE object, you
  18. may want to expose this ability via a property of type DT_OBJECT.
  19.  
  20. This allows you to use Visual Basic statements such as:
  21.  
  22.     Dim MyObject As OBJECT
  23.     Set MyObject = Control.Object
  24.     MyObject.Method...
  25.  
  26. or, more directly:
  27.  
  28.     Control.Object.Method
  29.  
  30. ----------------
  31. Reference Counts
  32. ----------------
  33. OLE has strict guidelines for maintaining reference counts on interface
  34. pointers.  Functions that return interface pointers increment the reference
  35. count on the pointer on behalf of the caller.  For example, calling
  36. VBGetControlProperty for a DT_OBJECT property causes the returned
  37. interface pointer to be incremented.  However, the caller is responsible
  38. for eventually releasing the reference to the interface pointer
  39. via IUnknown::Release().
  40.  
  41. If the property is PF_fGetMsg, you are responsible for incrementing the
  42. reference count on the interface pointer you return in your VBM_GETPROPERTY
  43. message code.
  44.  
  45. -------
  46. Example
  47. -------
  48. You may want to create a control that is an OLE container, meaning that you
  49. expose a pointer to an IDispatch interface via a DT_OBJECT property.
  50. When the OLE object is initially created within the control, the control
  51. could establish a connection to the OLE object by setting a pointer to an
  52. IDispatch interface via IUnknown::QueryInterface().  The reference count for
  53. the interface pointer would then be incremented from zero to one.
  54.  
  55. When the control is destroyed, or the control causes the OLE object
  56. it contains to be released, the control would also need to release the
  57. interface pointer using IUnknown::Release().  If the DT_OBJECT property is
  58. PF_fGetData, then all reference count maintenance associated with fetching
  59. the property is automatically handled by Visual Basic.  If, on the other hand,
  60. the DT_OBJECT property is PF_fGetMsg, you would need to call
  61. IUnknown::AddRef() on the interface pointer in your VBM_GETPROPERTY message
  62. code.
  63.  
  64. If there is no valid IDispatch interface, VBGetControlProperty returns
  65. NULL (DWORD 0).
  66.  
  67. --------------
  68. Property Flags
  69. --------------
  70. Since the IDispatch interface pointer can be used only at run time,
  71. you cannot save or load an interface pointer while saving or loading a form.
  72. For this reason, you cannot use the PF_fSaveData flag on your DT_OBJECT
  73. property.
  74.  
  75. You might want use to PF_fSaveMsg to enable you to do more sophisticated
  76. processing at save or load time.  For example, you could handle
  77. VBM_SAVEPROPERTY by serializing the OLE object corresponding to the
  78. interface pointer into the form file, and handle VBM_LOADPROPERTY by
  79. deserializing the object and getting a pointer to an IDispatch interface to
  80. it to set your property.
  81.  
  82. A property defined as DT_OBJECT cannot be set.  This means that you cannot
  83. use the property flags PF_fSetData or PF_fSetMsg.  In addition, you should
  84. specify the PF_fNoRuntimeW flag for a DT_OBJECT property.
  85.  
  86. Since you cannot view or modify the value of a DT_OBJECT property at
  87. design time, you should specify the PF_fNoShow flag for your DT_OBJECT 
  88. property.
  89.  
  90. Note
  91. ----
  92. You should not designate a DT_OBJECT property as the default property 
  93. for your control.
  94.  
  95.  
  96.