home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 10 / 10.iso / l / l405 / 3.ddi / TN002.TX_ / TN002.bin
Encoding:
Text File  |  1993-04-28  |  4.7 KB  |  99 lines
  1. Microsoft Visual Basic 3.00                              Microsoft Corporation
  2. Technical Notes
  3.  
  4. TN002.TXT:  Custom Control Version Management
  5.  
  6. This note describes how to use the version management functionality for
  7. custom controls.
  8.  
  9. ========================================================================
  10.  
  11. ------------
  12. Introduction
  13. ------------
  14. Visual Basic provides upward compatibility for custom controls.  This means
  15. that a custom control created for Visual Basic version 1.0 will run in 
  16. Visual Basic versions 2.0 and 3.0.  If a custom control uses version-specific
  17. features, a custom control can always explicitly test for a specific version
  18. during initialization and thereby determine whether or not to load.
  19.  
  20. There are cases, however, when a Visual Basic application created with
  21. a new version of a custom control runs on a system with an older version
  22. of the custom control.  Depending on the features and implementation
  23. of the custom control, the application may not work correctly -- or worse,
  24. may cause VB.EXE or VBRUNx00.DLL to crash.
  25.  
  26. The following sections describe Visual Basic 3.0's custom control
  27. version management system, which can help avoid potential application 
  28. failure.
  29.  
  30. ---------------
  31. MODEL Structure
  32. ---------------
  33. This is the definition of the MODEL structure used in Visual Basic 3.0.
  34. Note the addition of the last field (USHORT usCtlVersion).
  35.  
  36. typedef struct tagMODEL
  37.     {
  38.     USHORT      usVersion;           // VB version used by control
  39.     FLONG       fl;                  // Bitfield structure
  40.     PCTLPROC    pctlproc;            // The control procedure
  41.     FSHORT      fsClassStyle;        // Window class style
  42.     FLONG       flWndStyle;          // Default window style
  43.     USHORT      cbCtlExtra;          // Number of bytes allocated
  44.                      // for control structure
  45.     USHORT      idBmpPalette;        // BITMAP ID for tool palette
  46.     PSTR        npszDefCtlName;      // Default control name prefix
  47.     PSTR        npszClassName;       // Visual Basic class name
  48.     PSTR        npszParentClassName; // Parent window class, if subclassed
  49.     NPPROPLIST  npproplist;          // Property list
  50.     NPEVENTLIST npeventlist;         // Event list
  51.     BYTE        nDefProp;            // Index of default property
  52.     BYTE        nDefEvent;           // Index of default event
  53.     BYTE        nValueProp;          // Index of control value property
  54.     USHORT      usCtlVersion;        // Identifies the current version of the                                           
  55.                      // custom control.  The values 1 and
  56.                      // 2 are reserved for custom controls
  57.                      // created with VB1.0 and VB2.0
  58. } MODEL;
  59.  
  60. ---------------
  61. Control Version
  62. ---------------
  63. A custom control developer who wants to take advantage of the version
  64. management feature in Visual Basic 3.0 needs to provide a valid version number
  65. in the usCtlVersion field.  This value must be an unsigned integer (USHORT),
  66. and it should be changed any time the custom control changes its
  67. backward compatibility with previous versions.
  68.  
  69. Although any nonzero value is valid, the values 1 and 2 should not be
  70. used.  Since Visual Basic versions 1.0 and 2.0 do not support version 
  71. management, Visual Basic automatically assigns values 1 and 2 to any custom 
  72. control that has the usVersion field in the control's MODEL structure set 
  73. to VB100_VERSION and VB200_VERSION, respectively.
  74.  
  75. In order to take advantage of version management, the usVersion field
  76. of the control's MODEL structure must be set to VB300_VERSION or greater
  77. (or simply use VB_VERSION defined in a Visual Basic 3.0 VBAPI.H).  This allows
  78. Visual Basic to determine whether the usCtlVersion field is defined
  79. in the MODEL structure of a given custom control.
  80.  
  81. If the custom control contains a value of 0 in the usCtlVersion field,
  82. then no version control checks are made on this custom control.  
  83.  
  84. --------------------
  85. How the System Works
  86. --------------------
  87. When you create a Visual Basic executable (.EXE) file that uses a custom
  88. control, Visual Basic retrieves the control version number (usCtlVersion) 
  89. for that control and stores it in a special section of the .EXE file.
  90.  
  91. When you execute the application, the Visual Basic run-time support file
  92. (VBRUN300.DLL or greater) checks the control version number recorded
  93. in the .EXE file against the version number found in the custom control
  94. when it is loaded into the system.  If the version found in the .EXE file
  95. is greater than the version of the control loaded into the system,
  96. Visual Basic displays a notification that the particular custom control
  97. (.VBX file) is out of date and will not load, consequently forcing
  98. the application to terminate.
  99.