a guest Dec 11th, 2016 118 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
- Keywords to be addressed:
- UserControl_InitProperties Event / Sub within a UserControl
- UserControl_ReadProperties Event / Sub within a UserControl
- UserControl_WriteProperties Event / Sub within a UserControl
- PropertyBag Object with UserControl parent
- ReadProperty Method of PropertyBag
- WriteProperty Method of PropertyBag
- PropertyChanged Method of UserControl directed at form (container).
- Get [PropertyName] Procedure associated with a property
- Let/Set [PropertyName] Procedure associated with a property
- Ambient Object with UserControl parent
- Extender Object with UserControl parent
- EditAtDesignTime Property of UserControl
- Fields: This is not listed above because it is more of a concept rather than an actual keyword. In the context here, a field is a property of a sub-control that is placed on our UserControl. For instance, we may have a UserControl with a single VB label on it. This label will have its own properties (like .Caption, .BackColor, etc.) These will be referred to as fields of the UserControl. You could also have other fields that are just module level variables of the UserControl.
- PropertyBag: This is an internal object associated with a UserControl. It is quite similar to the Properties Window, but not the same thing. It can best be thought of as a memory object that is quite similar to the properties for a control in the .FRM file. It is used to set up the Properties Window, but other things can also create fields in the Properties Window (which should ultimately be included in the PropertyBag). Data is moved into and out of this PropertyBag memory object with the .ReadProperty and .WriteProperty methods.
- The PropertyBag object is available to us only when the UserControl_ReadProperties or UserControl_WriteProperties fires (as a passed argument), unless we chose to save a copy of it (from within UserControl_ReadProperties) as a module level object.
- We must guarantee that things stay in-sync between the PropertyBag object, the Properties Window, and the actual UserControl fields.
- The one thing we need not concern ourselves with is the PropertyBag getting written to and read from the actual .FRM. This is done independent of anything here.
- This PropertyBag is entirely read-only during runtime, although the UserControl fields are not.
- UserControl_InitProperties: This is fired in only one instance, while in design mode when a control instance is first created by selecting the control from the toolbox and placing it on a form. It is not fired during runtime, nor when the form is opened in either the IDE or runtime. It’s not even fired when copying a control while in design mode. Strictly speaking, this event is not needed (and shouldn’t be used, if possible). It is a way to set initial fields for a new instance of a UserControl, but this is possibly better done by editing the actual UserControl and setting these defaults in the sub-controls of the UserControl.
- UserControl_ReadProperties: This is fired anytime VB feels that the PropertyBag object should be read, with its properties placed in the fields of the UserControl. It fires when the form is opened from the project window in design mode, and also when the form is opened during runtime. Disappointingly, it does NOT fire when a new UserControl is created from the Toolbox (which causes a problem with snagging a copy of the PropertyBag). I suppose VB sees no reason to fire it since the UserControl and the PropertyBag were just created, so there is (in theory) no reason to fire it. It DOES fire when a control is copied. The PropertyBag is passed as an argument.
- UserControl_WriteProperties: This is fired anytime VB feels that the fields of the UserControl should be written back into the PropertyBag. It is fired when a form is closed in design mode (if properties need to be saved from UserControl fields). It may also be fired when saving the project to disk (if the form with the UserControl is open and properties need to be saved from UserControl fields). The PropertyBag is passed as an argument.
- ReadProperty: This is a method of the PropertyBag. This method is primarily (if not exclusively) used within the ReadProperties event. It allows the reading of data from the PropertyBag object in memory (not the Properties Window). These properties are typically written to the fields of the UserControl (but they might be written to module level variables).
- WriteProperty: This is a method of the PropertyBag. This method is primarily (if not exclusively) used within the WriteProperties event. It allows the writing of data to the PropertyBag object in memory (not the Properties Window). This data is typically read from the UserControl fields (but it might be contained in module level variables).
- PropertyChanged: This is a method of the UserControl , but it is more aimed at saving and loading the UserControl when the actual form is saved and loaded (from the project window). A PropertyBag property name must be specified when it is called. It can be called anywhere in the UserControl, but it is typically called anytime one of the user defined UserControl fields is changed. It notifies VB that the UserControl_WriteProperties event must be fired when the form is closed (or saved). Calling PropertyChanged does NOT cause UserControl_WriteProperties to immediately fire. This method is completely ignored during runtime.
- Properties Window: This is not listed in the initial list of keywords, but it is mentioned several times. This is sometimes called a Property Page in other literature. This refers to the actual window that comes up in VB and lists the properties for a control (or possibly also the custom window). This Properties Window is partially constructed from the PropertyBag and partially constructed from the Get/Let/Set properties listed in the UserControl code. In fact, there can be some overlap in certain cases. The default properties (from the PropertyBag) that are always in the Properties Window are: (Name), CausesValidation, DragIcon, DragMode, Height, HelpContextID, Index, Left, TabIndex, Tag, ToolTipText, Top, Visible, WhatsThisHelp, & Width. All of these will automatically transfer between the Properties Window and the PropertyBag with no need for any coding. It is possible to create Get/Let/Set property procedures for these default properties that would do extra stuff (which would require that PropertyChanged be used), but this is not recommended. It is best if these properties were left alone.
- In addition to these default properties, the coder can create as many additional properties on the Properties Window as he desires, by simply creating Get/Let/Set property procedures in the UserControl code. When the coder does this, he is responsible for deciding what to do with this data. Typically, it goes directly into (or out of) one of the UserControl fields, but it could go into a module level variable for other use. As a notice, to keep things in-sync, anytime a Let or Set it called, the coder should make sure that PropertyChanged is called with the name of the new property specified. That way, when it comes time to save the field to the PropertyBag, it will be saved.
- The entire concept of a Properties Window disappears during runtime.
- Get [PropertyName]: There are basically two circumstances when this fires. One, when the VB design mode Properties Window opens and needs to know the value for the property. Two, when the user programmatically reads the property during runtime. In the first instance (design mode), it fires anytime the Properties Window is opened and the UserControl is selected. It will also fire when moving from one property to the next on the Properties Window, even if we’re moving off of the property of interest.
- Let/Set [PropertyName]: This fires in two instances. One, when the property is changed on the VB design mode Properties Window (upon the specific property losing focus). Two, when the property is changed during runtime in code. It is within this event that the coder is responsible for placing a PropertyChanged call with the PropertyName specified. It is assumed that this is ignored during runtime, but it notifies VB that the PropertyBag needs updating during design time.
- Extender: This is an implicit object that is always available in the module level code of a UserControl. Some properties of a UserControl are supplied by the container rather than the actual UserControl. These are the properties supplied by the Extender object. They always appear in the PropertyBag and the Properties Window, and typically need not be of concern to the coder. For instance, Top, Left, Width, & Height are examples of Extender properties. There are a plethora of properties available in the Extender object. See “Extender Object” in the MSDN help for all of them.
- Ambient: As with the Extender object, this is an implicit object that is always available in the module level code of a UserControl. This one actually has an associated class (AmbientProperties). (For MSDN help, look for AmbientProperties). This Ambient object provides properties that are specific to the UserControl, but not related to the sub-controls on the UserControl. For instance, the UserControl has its own BackColor. This BackColor is a property of the Ambient object.
- One property of the Ambient object that is of particular use is the UserMode property. If it’s true, the project is actually running (in IDE or compiled). If it’s false, the IDE is in design mode. One must remember that a UserControl will possibly execute its code even when the IDE is in design mode.
- EditAtDesignTime: This is just a native property of any UserControl. It states whether or not the control can fire it’s events while in design mode of the IDE. Even if it is set, the UserControl does not automatically fire its events. It only becomes active when the user right-clicks and clicks “Edit” from the design mode context menu of the UserControl. And then it goes out of this “active” mode when the user clicks off of that particular instance of the UserControl. There are several ways to detect when “Edit” was clicked, but the easiest is by monitoring the UserControl_EnterFocus event. This will always fire. The coder may also want to place “If Ambient.UserMode Then Exit Sub” at the top of this event so that it is ignored during runtime.
- Figuring out when the coder is ready to get out of “Edit” mode is a bit tricky. If a separate “Edit” interface (with a separate form) is being used, that form can be loaded modally, and the code in the UserControl_EnterFocus event will freeze until that external form is either hidden or closed. The external form isn’t fully modal, but the UserControl code does freeze.
- If the coder goes into “Edit” mode with hidden sub-controls actually on the UserControl, it’s best to have a module level flag to this effect. If this is done, be sure to check this flag when the UserControl_WriteProperties event fires. The coder may close the form with the UserControl without clicking off of the UserControl first. In other words, the exposed hidden “Edit” mode sub controls will not get a chance to re-hide (and also save their values) if you don’t check this flag in the UserControl_WriteProperties event. But even this isn’t always true. A Property “” will guarantee that the UserControl_WriteProperties event fires.
- Example #1: For our first example, we will create a simple UserControl that only contains one VB label. The following code (within the UserControl) would completely get this label up and going. The coder can work out their own resizing issues. The label also has a plethora of properties that might be “exposed” via the UserControl properties. This is entirely up to the coder. The default UserControl properties have nothing to do with this label’s properties.
- Option Explicit
- Public Property Get LabelCaption() As String
- LabelCaption = Label1.Caption
- End Property
- Public Property Let LabelCaption(ByVal sCaption As String)
- Label1.Caption = sCaption
- PropertyChanged "LabelCaption"
- End Property
- Private Sub UserControl_ReadProperties(PropBag As PropertyBag)
- Label1.Caption = PropBag.ReadProperty("LabelCaption")
- End Sub
- Private Sub UserControl_WriteProperties(PropBag As PropertyBag)
- PropBag.WriteProperty "LabelCaption", Label1.Caption
- End Sub
RAW Paste Data