ActiveX Control Related Objects and Property pages

Objects related to ActiveX control
The following are the objects that are involved in the process of creating an ActiveX control.

• UserControl object
• AmbientProperties object
• Extender object
• Constituent control objects

UserControl Object
This is the object used to create a single ActiveX control. Every ActiveX control is consisting of one UserControl object and a set of constituent controls. Just like a From, a UserControl object also has a designer, which allows you to place intrinsic control on the UserControl object.

You have properties, methods, and events for UserControl object. They are discussed later in this chapter.

AmbientProperties Object
This is used to get information from container of ActiveX control. The properties of AmbientProperties object are the ambient properties of the control. These properties are read-only. These properties allow you to determine how you adapt your control according to the capabilities of the container.

Not all ambient properties are standard. Some of them are specific to only a particular container.

AmbientChanged event occurs whenever any of the ambient properties (properties in container) changes. This enables programmer to change control according to the container.

AmbientProperties object is not available in Initialize event.

The following is the list of standard ambient properties.


Property Meaning Default value if property is not supported by Container.
BackColor Color that contains the suggested interior color of the contained control. &H80000005
DisplayAsDefault Returns True if the control is the default control otherwise false. false
DisplayName The name that the control assigned by developer. "".
Font Contains the suggested font information of the contained control. MS Sans Serif 8.
ForeColor Suggested foreground color of the contained control. 0x80000008: the system color for window text.
LocaleID Specifies the language and country of the user System locale ID.
Palette Picture object whose palette specifies the suggested palette for the contained control.
RightToLeft Indicates the text display direction and control visual appearance on a bi-directional system. False.
ScaleUnits The name of the coordinate units being used by the container. ""
TextAlign Specifies how text is to be aligned. 0 - General Align.
UserMode Specifies if the environment is in design mode or end user mode True.
Table 28.1: Ambient properties of a UserControl.

The following code changes the background color of the text box to the background color of the container whenever background color of the container is changed.

Private Sub UserControl_AmbientChanged(PropertyName As String)
If PropertyName = "BackColor" Then
txtNumber.BackColor = Ambient.BackColor
End If
End Sub
Listing 28.1: Changing BackColor property of text box to BackColor property of user Control.

AmbientChanged event of the UserControl object occurs whenever any of the ambient properties is changed. Ambient object provides access to values of ambient properties.

PropertyName parameter of the AmbientChanged event contains the name of the properties that has been changed in the container.

Extender Object
This object holds properties of the control that are actually controlled by the container of the control rather than by the control itself

The properties, methods, and events of Extender object are provided by the container. So there is no guarantee that all these are supported in all platforms.

You can access extender properties using Extender property of UserControl.

The following is the list of extender properties.

Property Meaning
Name Contains the user-defined name of the control.
Visible Specifies if the control is visible or not.
Parent Represents the container of the control, such as a form in Visual Basic.
Cancel Indicates that the control is the Cancel button for the container.
Default Indicates that the control is the default button for the container.
Container Represents the visual container of the control.
DragIcon Picture that specifies the icon to use when the control is dragged.
DragMode Specifies if the control will automatically drag, or if the user of the control must call the Drag method.
Enabled Specifies if the control is enabled. This is not present unless the control also has an Enabled property.
Height Specifies the height of the control in the container’s scale units.
HelpContextID Specifies the context ID to use when F1 key is pressed being in the control.
Index Specifies the position in a control array that this instance of the control occupies.
Left Specifies the position of the left edge of the control to the left edge of the container, specified in the container’s scale units.
TabIndex Specifies the position of the control in the tab order of the controls in the container.
TabStop Specifies if Tab will stop on the control.
Tag Contains a user-defined value.
ToolTipText Contains the text to be displayed when the cursor stays on the control for more than a second.
Top Specifies the position of the top edge of the control to the top edge of the container, specified in the container’s scale units.
WhatThisHelpID Specifies the context ID to use when the What’s This pop-up is used on the control.
Width Specifies the width of the control in the container’s scale units.

Table 28.2: Extender properties.

The following are the methods provided by Extender object.

• Drag
• Move
• SetFocus
• ShowWhatsThis
• Zorder

The following are the events provided by Extender object

• DragOver
• DragDrop
• GotFocus
• LostFocus

Properties of UserControl object
The following are the properties that are specific to user control object.

Property Meaning
AccessKey Returns or sets a string that contains the keys that will act as the access keys (or hot keys) for the control.
Ambient Returns an AmbientProperties object holding the ambient properties of the container.
ContainedControls Returns a collection of the controls that were added to the control.
EditAtDesignTime Returns or sets a value determining if a control can become active during the developer design time
EventsFrozen If it is set to true, then events of usercontrol are ignored by container
Extender Returns the Extender object for this control that holds the properties of the control that are kept track of by the container.
ParentControls Returns a collection containing other controls in parent container.
PropertyPages Is a string array containing the names of the property pages in the project that are associated with this control.
ContainerHwnd Returns the window handle (hWnd) of a UserControl’s container.
Parent Returns a reference to the container object on which the control is sited.
CanGetFocus Determines whether focus should move to this control or not.
Table 28.3: Properties of User Control.

UserControl Events
The following are the various events of usercontrol object and their description.

Event When does it occur?
AccessKeyPress Occurs when user presses one of the accesskeys for the control. It passes the key that is pressed by user.
AmbientChanged Occurs when an ambient property’s value changes. This passes the name of the property as the only parameter
EnterFocus This event occurs whenever a constituent control receives focus.
ExitFocus Occurs whenever focus leaves the control.
GotFocus Occurs in the constituent control when focus enters it. The EnterFocus event is raised before the GotFocus event.
Hide Occurs when the object’s Visible property changes to False.
InitProperties Occurs when a new instance of an object is created.
This allows programmer to initialize new control when it is placed on the form.
ReadProperties Occurs when loading an old instance of an object that has a saved state. This is used to read the values of the properties. Used for property persistence.
Show Occurs when the object’s Visible property changes
WriteProperties Occurs when an instance of an object is to be saved. This is used to save the values of properties.
AsyncReadProgress Occurs when more data is available as a result of an AsyncRead method.
AsyncReadComplete Occurs when the container has completed an asynchronous read request.
HitTest Occurs when the user moves the mouse over a UserControl object. Only occurs when the Windowless property of the UserControl is set to True and the BackStyle property is set to Transparent.
Initialize Occurs when an application creates an instance of a user control.
Terminate Occurs when the instance of the control is about to be destroyed.
Table 28.4: Events of user control object.

Property Pages
Before we started creating ActiveX Control, we had already used a few ActiveX controls. All of them have Property pages that allow you to change properties of the control. Now let us create two property pages for our Number control. First one contains a text box to take number from user and changes Value property, Second one contains two text boxes Maximum Length and Minimum Length properties. A developer using Number ActiveX Control can invoke property pages and change properties.

The best way of creating a property page is using Property Page Wizard. Now having decided how many property pages to have and what to have in each of these property pages, we are ready to use Property Page Wizard.

To invoke property page wizard:

1. First make Property Page Wizard available to Visual Basic project by selecting Add-Ins menu and then select Add-In Manager option.
2. In Add-In Manager dialog box double click on VB 6 Property Page Wizard. You should see Loaded message in Load Behavior column.
3. Click on Ok.
4. Then select Add-Ins menu and Property Page Wizard. You will see a series of windows prompting for required information.

The following are the steps to create two property pages and to place Value property in first property page and MinLength and MaxLength properties on the second property page.

1. When Property Page Wizard is displayed, it first displays Introduction screen.
2. Click on Next button to move to select the Property Pages page.
3. Click on Add button.
4. Enter ppValue as the name of the page.
5. Click on Add button again and enter ppLength as the name of second property page.
6. Click on Next button to move to Add Properties page.
7. Available Properties list contains the list of available properties.
8. Make sure ppValue tab is selected in Available Property Pages.
9. Select Value property and click on > to move the property to ppValue property.
10. In the same way select ppLength tab and click on >> to place MinLength and MaxLength properties on ppLength property page.
11. Click on Finish button to start building property pages.
12. Invoke ppValue property page and change Caption property to “Value”
13. Invoke ppLength property page and change Caption property to “Length”.

Property Page Wizard has created two property pages ( ppValue and ppLength)

The code that Property Page Wizard has written for ppValue property page is as follows.

Private Sub txtValue_Change()
Changed = True
End Sub

Private Sub PropertyPage_ApplyChanges()
SelectedControls(0).Value = txtValue.Text
End Sub

Private Sub PropertyPage_SelectionChanged()
txtValue.Text = SelectedControls(0).Value
End Sub
Listing 28.1: Code written by property page wizard.
Property page containing text boxes for MaxLength and MinLength properties.

Let us understand the code written by Property Page Wizard. But before we try to do that, we have to understand properties, events of property page.

Changed Property
When this property is set to true, Apply button in the property page will be enabled. In addition to that, setting it to true calls ApplyChanges event whenever you click on Ok button or move to a different property page.

SelectedControls property
This is a collection that contains the controls that are currently selected on the form. SelectedControls (0) references the control that is currently selected. This is used to get the values for properties of the currently selected instance of the ActiveX control for which property page belongs.

The code written by Property Page Wizard, uses SelectedControls (0) (first selected control) only. If you want to handle all selected controls, you have to modify the code written by wizard.

SelectionChanged Event
This is fired whenever an instance of the ActiveX control is selected for editing properties through property pages. This event is used to get the values of the properties from selected control (SelectedControls (0)) and assign those values to controls in property pages to enable user to change them.

ApplyChanges Event
This event is fired whenever user is selecting Apply button, selecting Ok button, closing page or shifting to a different page.

The event occurs only when Changed property is set to true,

Now, if you look at the code written by Property Page Wizard, you should be able to understand the code. The code uses all the properties and events that we have discussed. The following is the summary of the code.

• Sets Changed property to True, whenever user changes values in txtValue text box, which is meant for Value property.
• SelectionChanged event is used to get the value of Value property of the currently selected control (SelectedControls(0)) and put that value in txtValue textbox.
• ApplyChanges event is used to write value entered in txtValue textbox into Value property of the currently selected control (SelectedControls (0)).

Code for ppLength property page
The code written by Property Page Wizard for ppLength property page is as follows.

Private Sub txtMaxLength_Change()
Changed = True
End Sub

Private Sub txtMinLength_Change()
Changed = True
End Sub

Private Sub PropertyPage_ApplyChanges()
SelectedControls(0).MaxLength = txtMaxLength.Text
SelectedControls(0).MinLength = txtMinLength.Text
End Sub

Private Sub PropertyPage_SelectionChanged()
txtMaxLength.Text = SelectedControls(0).MaxLength
txtMinLength.Text = SelectedControls(0).MinLength
End Sub
Listing 28.2: Code for ppLength property page.

This code needs no explanation, as it doesn’t differ from the previous code.

Using property pages at the time of designing
Let us see how a developer who is using Number ActiveX control can use Property Pages of Number control. Here are the steps to test it:

1. Open testing project (tstNumctrl) project
2. Invoke Form designer
3. Select Number1 control and click right button
4. You should see a new option in popup menu – Properties.
5. Select Properties option to invoke Property pages.
6. Property pages window is displayed with two tabs at the top, one for Value property page and another for Length property page.
7. In Value property page, you will see the value you assigned to Value property of the selected control. the value assigned to Value property is 1000. So initially you will see 1000.
8. Change the value to 2000 in property page. It will enable Apply button of the property page. At this stage, your property Page should be identical
9. Click on Apply to make Value property of Number1 control. Click on Length tab to move to Length property page.

Note: Pressing F4 on the control will invoke Properties Pallette. And selecting Popup Menu -> Properties option will invoke Property pages. This is same for all ActiveX controls.