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, 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
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.
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. As shown in figure 28.5 , 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 to figure 28.5.
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.

Post a Comment

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, 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
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.
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. As shown in figure 28.5 , 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 to figure 28.5.
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.

Post a Comment