More articles to the new site

[Merri]

Since I'm too lazy to look for the old topic, I just post into a new one. So, here we have a guide to usercontrols for beginners.

---

Usercontrols

Sooner or later you find out VB's default controls aren't enough: you need more. You can take a look in the OCXs, but there is a major disadvantage in them: you have to include the file with your program setup. There is also a lot of different versions of the OCXs and it just might happen there are times when your application just doesn't start working and the user is confused and might even remove the program because it doesn't work.

A solution this is to create your own controls. Once you get used to the basics, it is relatively easy in most cases. And once you've created a user control, you can always use it in your other programs. At worst, user controls can be very complex on how they work, but most times controls are like small applications.

User controls have three main things you need to notice:
- you can declare events, and you must manually raise them too
- controls always have properties: Property Get, Let and Set
- property bags - these are used to store the control default settings set by the programmer who uses the control

And here the same told more practically.

If you want your control to have Private Sub ControlName_Click(), you must declare event Public Event Click() and then have RaiseEvent Click in your UserControl_Click()

If you want the control to have some customizable property, such as BackColor, you must have Property Get and Property Let, an inner variable m_BackColor holding the information (a good programming habit in the case) and also code for propertybags at UserControl_ReadProperties and UserControl_WriteProperties. Also, you need to initialize the properties. Sample code for this:

'just a reminder :)
Option Explicit
 
'for an almost complete list of these, please see Object Browser > SystemColorConstants
'there are a few more, the ones you see are supported by Windows 95 and NT4
Private Const m_def_BackColor As Long = vbButtonFace
 
Dim m_BackColor As Long
 
'we use OLE_COLOR so we don't see just a decimal value
'in the control property window when we are using the control
Public Property Get BackColor() As OLE_COLOR
    BackColor = m_BackColor
End Property
 
'you can title NewColor as you want
Public Property Let BackColor(ByVal NewColor As OLE_COLOR)
    m_BackColor = NewColor
    UserControl.BackColor = NewColor
    'in most cases you also need to redraw your control
    'this happens simply by calling your redrawing sub
End Property
 
Private Sub UserControl_InitProperties()
    'the first initialization, because ReadProperties doesn't get called in design time
    'when you place the object on the form the first time
    m_BackColor = m_def_BackColor
End Sub
 
Private Sub UserControl_ReadProperties(PropBag As PropertyBag)
    'you could use something else than "BackColor", but I recommend to use the standard names
    m_BackColor = PropBag.ReadProperty("BackColor", m_def_BackColor)
End Sub
 
Private Sub UserControl_WriteProperties(PropBag As PropertyBag)
    'the "BackColor" must match with the code found at ReadProperties
    PropBag.WriteProperty "BackColor", m_BackColor, m_def_BackColor
End Sub

Actually, with just the above, you can make up your first usercontrol! Try it out! Make a new fresh usercontrol, add the code, close the usercontrol and add it into the form. Then see what you can do with it.

To make a little more use with it, lets add four common events: Click, MouseDown, MouseMove and MouseUp

'in the user control declarations
Public Event Click()
Public Event MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
Public Event MouseMove(Button As Integer, Shift As Integer, X As Single, Y As Single)
Public Event MouseUp(Button As Integer, Shift As Integer, X As Single, Y As Single)
 
Private Sub UserControl_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
    RaiseEvent MouseDown(Button, Shift, X, Y)
End Sub
 
Private Sub UserControl_MouseMove(Button As Integer, Shift As Integer, X As Single, Y As Single)
    RaiseEvent MouseMove(Button, Shift, X, Y)
End Sub
 
Private Sub UserControl_MouseUp(Button As Integer, Shift As Integer, X As Single, Y As Single)
    RaiseEvent MouseUp(Button, Shift, X, Y)
End Sub

After adding this code and testing it out, you should see these four events being available for use. Please note while making your own events that you must call RaiseEvent somewhere or the event will not ever occur. Also, if you don't declare the events (Public Event Click...), the events are not available at all and you also get an error when you are trying to call RaiseEvent.

Now, based on the property code above, add a new property: ForeColor. At simplest you can just double the code and then change all Back to Fore; and you're done. To make up some challenge, figure out something that show you visually the new ForeColor property is alive and working.

Once done, brace yourself: you have just learned the basics!

---

Too long article, have to split into two posts...