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
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.
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
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.
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.
|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.
The following are the events provided by Extender object
Properties of UserControl object
The following are the properties that are specific to user control object.
|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.
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.
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:
- First make Property Page Wizard available to Visual Basic project by selecting Add-Ins menu and then select Add-In Manager
- In Add-In Manager dialog box double click on VB 6 Property Page Wizard. You should see Loaded message in Load Behavior
- Click on Ok.
- 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.
- When Property Page Wizard is displayed, it first displays Introduction screen.
- Click on Next button to move to select the Property Pages page.
- Click on Add
- Enter ppValue as the name of the page. (see figure 28.1).
Figure 28.1: Entering name of the property page.
5. Click on Add button again and enter ppLength as the name of second property page.
Figure 28.2: Property Page Wizard after two property pages are created.
- Click on Next button to move to Add Properties page.
- Available Properties list contains the list of available properties.
- Make sure ppValue tab is selected in Available Property Pages.
- Select Value property and click on > to move the property to ppValue
- In the same way select ppLength tab and click on >> to place MinLength and MaxLength properties on ppLength property page.
- Click on Finish button to start building property pages.
- Invoke ppValue property page and change Caption property to “Value”
- Invoke ppLength property page and change Caption property to “Length”.
Property Page Wizard has created two property pages ( ppValue and ppLength, shown in figure 28.3, and 28.4).
The code that Property Page Wizard has written for ppValue property page is as follows.
Private Sub txtValue_Change()
Changed = True
Private Sub PropertyPage_ApplyChanges()
SelectedControls(0).Value = txtValue.Text
Private Sub PropertyPage_SelectionChanged()
txtValue.Text = SelectedControls(0).Value
Listing 28.1: Code written by property page wizard.
Figure 28.3: Property page containing Value property.
Figure 28.4: 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.
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.
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.
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.
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
- SelectionChanged event is used to get the value of Value property of the currently selected control (SelectedControls(0)) and put that value in txtValue
- 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
Private Sub txtMinLength_Change()
Changed = True
Private Sub PropertyPage_ApplyChanges()
SelectedControls(0).MaxLength = txtMaxLength.Text
SelectedControls(0).MinLength = txtMinLength.Text
Private Sub PropertyPage_SelectionChanged()
txtMaxLength.Text = SelectedControls(0).MaxLength
txtMinLength.Text = SelectedControls(0).MinLength
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:
- Open testing project (tstNumctrl) project
- Invoke Form designer
- Select Number1 control and click right button
- You should see a new option in popup menu – Properties.
- Select Properties option to invoke Property pages.
- Property pages window is displayed with two tabs at the top, one for Value property page and another for Length property page.
- In Value property page, you will see the value you assigned to Value property of the selected control. As shown in figure 28.5 , the value assigned to Value property is 1000. So initially you will see 1000.
- Change the value to 2000 in property page. It will enable Apply button of the property At this stage, your property Page should be identical to figure 28.5.
- 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.
Figure 28.5: Property Page when invoked during design time.