3.2 CommandButton
The following example shows a CommandButtonControl structure. The CommandButton is embedded in a UserForm and has the following properties set:
The Caption property is set to "CommandButton1".
The Height and Width properties are set to 36 points and 126 points, respectively.
The MousePointer property is set to fmMousePointerCustomer.
Although this example uses the CommandButtonControl, the persistence of the data structures for this control can also be applied to other control types.
The following table shows the top-level representation of the CommandButtonControl structure.
|
Offset |
Size |
Structure |
Value |
|---|---|---|---|
|
00000000 |
036A |
CommandButtonControl |
|
|
00000000 |
0001 |
BYTE - MinorVersion |
0x00 |
|
00000001 |
0001 |
BYTE - MajorVersion |
0x02 |
|
00000002 |
0002 |
USHORT - cbCommandButton |
0x0024 |
|
00000004 |
0004 |
A: CommandButtonPropMask - PropMask |
|
|
00000008 |
0008 |
B: CommandButtonDataBlock - DataBlock |
|
|
00000010 |
0018 |
C: CommandButtonExtraDataBlock - ExtraDataBlock |
|
|
00000028 |
0316 |
D: CommandButtonStreamData - StreamData |
|
|
0000033E |
002C |
TextProps - TextProps |
|
Figure 24: CommandButtonControl structure
The following are detailed examples of PropMask, DataBlock, ExtraDataBlock, and StreamData. An example of the TextProps structure has been omitted because it closely resembles this example.
MinorVersion: 0x00 specifies the minor version of the control.
MajorVersion: 0x02 specifies the major version of the control.
cbCommandButton: 0x0024 specifies the sum of the sizes, in bytes, of PropMask, DataBlock, and ExtraDataBlock.
The following table shows which properties of the CommandButtonControl are not set to the file format default. If a bit has is set to 1, the corresponding property value in the CommandButtonDataBlock is not the file format default and is stored in the file. If a bit is set to zero, the corresponding property value is the file format default and is not stored in the file. As previously described, the Caption, Size (Height and Width), MousePointer, and MouseIcon properties are set to a value different from the file format default, and only these bits are set to 1.
|
Offset |
Size |
Structure |
Value |
|---|---|---|---|
|
00000004 |
0004 |
A: CommandButtonPropMask - PropMask |
|
|
00000004 |
1 bit |
BOOL - fForeColor |
0 |
|
00000004 |
1 bit |
BOOL - fBackColor |
0 |
|
00000004 |
1 bit |
BOOL - fVariousPropertyBits |
0 |
|
00000004 |
1 bit |
BOOL - fCaption |
1 |
|
00000004 |
1 bit |
BOOL - fPicturePosition |
0 |
|
00000004 |
1 bit |
BOOL - fSize |
1 |
|
00000004 |
1 bit |
BOOL - fMousePointer |
1 |
|
00000004 |
1 bit |
BOOL - fPicture |
0 |
|
00000004 |
1 bit |
BOOL - fAccelerator |
0 |
|
00000004 |
1 bit |
BOOL - fTakeFocusOnClick |
0 |
|
00000004 |
1 bit |
BOOL - fMouseIcon |
1 |
|
00000004 |
21 bits |
BOOL - UnusedBits |
0 |
Figure 25: CommandButtonPropMask structure
fForeColor: Zero specifies that the value of the ForeColor property is the file format default and is not stored in the file.
fBackColor: Zero specifies that the value of the BackColor property is the file format default and is not stored in the file.
fVariousPropertyBits: Zero specifies that the value of the VariousPropertyBits property is the file format default and is not stored in the file.
fCaption: 1 specifies that the Caption property is set to a value that is not the file format default and is stored in the CommandButtonDataBlock and CommandButtonExtraDataBlock.
fPicturePosition: Zero specifies that the value of the PicturePosition property is the file format default and is not stored in the file.
fSize: 1 specifies that the Size property is set to a value that is not the file format default and is stored in the CommandButtonExtraDataBlock.
fMousePointer: 1 specifies that the MousePointer property is set to a value that is not the file format default and is stored in the CommandButtonDataBlock.
fAccelerator: Zero specifies that the value of the Accelerator property is the file format default and is not stored in the file.
fTakeFocusOnClick: Zero specifies that the value of the TakeFocusOnClick property is the file format default and is not stored in the file.
fMouseIcon: 1 specifies that the MouseIcon property is set to a value that is not the file format default and is stored in the CommandButtonStreamData.
The following table shows the CommandButtonDataBlock. The DataBlock stores property values that are 4 bytes or smaller and are not the file format default. In this example, MousePointer is the only property whose value is stored in the DataBlock. For the Caption property, the length and compression flag of the Caption string are stored in the DataBlock, but the Caption string itself is stored in the CommandButtonExtraDataBlock.
|
Offset |
Size |
Structure |
Value |
|---|---|---|---|
|
00000008 |
0008 |
B: CommandButtonDataBlock - DataBlock |
|
|
00000008 |
0004 |
CountOfBytesWithCompressionFlag - Caption |
|
|
00000008 |
31 bits |
ULONG - cb |
0x0000000E |
|
00000008 |
1 bit |
BOOL - fCompressed |
1 |
|
0000000C |
0001 |
fmMousePointer - MousePointer |
0x63 |
|
0000000D |
0001 |
Align - Padding1 |
0x00 |
|
0000000E |
0002 |
SHORT - MouseIcon |
0xFFFF |
|
00000010 |
0000 |
Align - Padding2 |
|
Figure 26: CommandButtonDataBlock structure
Caption.cb: 0x0000000E specifies that the size, after compression, of the Caption string in the CommandButtonExtraDataBlock is 14 bytes.
Caption.fCompressed: 1 specifies that the Caption string in the CommandButtonExtraDataBlock is compressed.
MousePointer: 0x63 specifies that the MousePointer has the value fmMousePointerCustom and the icon is specified in the MouseIcon property.
Padding1: 1 byte of unused data needed for the value of the MousePointer property to align to an offset divisible by 2 from the beginning of the CommandButtonControl.
MouseIcon: 0xFFFF specifies that the MouseIcon property is set.
Padding2: Because the size of the CommandButtonDataBlock is divisible by 4, there is no need to add any padding at the end of the CommandButtonDataBlock.
The following table shows the CommandButtonExtraDataBlock. For this example, the Caption and Size properties are the only properties stored in the CommandButtonExtraDataBlock.
|
Offset |
Size |
Structure |
Value |
|---|---|---|---|
|
00000010 |
0018 |
C: CommandButtonExtraDataBlock - ExtraDataBlock |
|
|
00000010 |
000E |
Caption - Caption |
CommandButton1 |
|
0000001E |
0002 |
Array of bytes - Padding |
0x0000 |
|
00000020 |
0008 |
Size - Size |
|
|
00000020 |
0004 |
LONG - Width |
0x0000115D |
|
00000024 |
0004 |
LONG - Height |
0x000004F6 |
Figure 27: CommandButtonExtraDataBlock structure
Caption: “CommandButton1” specifies the compressed string for the Caption property.
Padding: 2 bytes of unused data needed for the size of the compressed string to be divisible by 4.
Size.Width: 0x0000115D specifies that the width of the CommandButtonControl is 4445 HIMETRIC units, or 126 points.
Size.Height: 0x000004F6 specifies that the height of the CommandButtonControl is 1270 HIMETRIC units, or 36 points.
The following table shows the CommandButtonStreamData. The StreamData stores picture properties of the CommandButtonControl. For this example, MouseIcon is the only picture property persisted.
|
Offset |
Size |
Structure |
Value |
|---|---|---|---|
|
00000028 |
0316 |
D: CommandButtonStreamData - StreamData |
|
|
00000028 |
0316 |
MouseIcon - MouseIcon |
|
|
00000028 |
0010 |
GUID - CLSID_StdPicture |
04 52 E3 0B 91 8F CE 11 ... |
|
00000038 |
0004 |
ULONG - Preamble |
0x0000746C |
|
0000003C |
0004 |
ULONG - Size |
0x000002FE |
|
00000040 |
02FE |
Array of bytes - Picture |
00 00 02 00 01 00 20 20 ... |
Figure 28: CommandButtonStreamData structure
MouseIcon.CLSID_StdPicture: 04 52 E3 0B 91 8F CE 11 9D E3 00 AA 00 4B B8 51 specifies the CLSID of the StdPicture object in little-endian format. The CLSID in standard GUID [MS-DTYP] format is {0BE35204-8F91-11CE-9DE3-00AA004BB851}.
MouseIcon.Preamble: 0x0000746C specifies a constant value for the StdPicture object.
MouseIcon.Size: 0x000002FE specifies the size, in bytes, of Picture.
MouseIcon.Picture: 00 00 02 00 01 00 20 20 ... specifies the embedded icon to be used for the MouseIcon property. The complete value of this property has been omitted for brevity. For this example, the contents of this property are the same as the contents of the up_l.cur file.