How to create an enhanced label custom control?

Steps

• 1 - Introduction
• 2 - Setting the caption's control property
• 3 - Changing the BackColor Enhanced Label property...
• 4 - Adding the TextColor property
• 5 - Adding the FontLabel property
• 6 - List of our new properties added enhancing the label control
• 7 - List of color constants
• 8 - List of font constants
• 9 - The complete source code for custom control
• 10 - Conclusion

1 - Introduction

This tutorial will teach you how to create your own user control. This user control will enhance the basic label control's capabilities.Actually, we will create from scratch a label control which will offer interesting new capabilities than the basic label control provided such like allows the developer to set properties BackColor, ForeColor, Font text and Text alignment. All these new enhancements will let you create a more attractive fully coloured interface for your programs.

2 - Setting the control's caption property

First of all, we start by creating a minimal project and add in a user control.

Click on the File menu, then choose the New command, the following dialog box appears:

Choose Minimal Project, just as shown.

The following dialog box appears:

You can leave all default values. Click the Next button. Do the same for step 2, just click the Next button. Finally to step 3 click the Finish button without changing anything. Now, we have a minimal project with a form. We have to add a UserControl. To do it, find the window called Project right click on UserControls and choose Add User Control into the contextual menu as shown below:

UserControl1 is now added to your project. You can rename the user control by changing the property name UserControl1 for the following name: Enhanced_Label as shown below:

You can also change the frmMain caption property to Enhanced Label Demo.

At this point, the only thing we can expect from our enhanced custom control label is to display itself as a blank rectangle on a form.

To continue, double-click on the Enhanced_Label project item you have just added. This item is available in the project window:

Just add the following code for our control enhanced label:

Our new enhanced label control is now created! To test it, draw an occurrence of the enhanced label control onto your main form:

Open the main form and click on the tool box to choose the enhanced label control:

Once the Enhanced Label is selected, draw it on the form and launch the emulator. You can keep the default name which is Enhanced_Label1. You'll not see anything, except a blank rectangle:

Our control is a little bit basic, isn't it? So what we are going to do now is to add the ability to set and display a text string into the control

Go back to the Enhanced Label project item (simply double click on it inside the Project Window, User Controls, Enhanced_Label).

At the top of the user control code, we declare a private variable called m_strCaption:

m is for Member, str is for String. This convention is useful to know the type and scope of a variable simply from its name. This variable will contain our string shown into the label control.

We also add two properties procedures into the code:

The Let Caption procedure property sets the content of our label's caption. The Get Caption procedure property allows us to get the current caption of the label. Now we are going to implement these properties. Add this code into each procedure property:

Also, we add this code into the two events control Load and Paint:

This is very important here to understand the role of the Load and the Paint events. Load is an event raised when the control is loaded in memory while the Paint event occurs when the control is painted on screen. We define the default value of the caption in the Load event. The default caption will be set to the word Enhanced Label, and will be showed on screen from the Paint event, using the TextOut function. One parameter of the TextOut function is the m_strCaption variable which contains our string.

Note that we raise automatically the Paint event by the reserved keyword Repaint called right after a change of the property in the Let Caption procedure.

Now we are going to show you how to modify the control's properties programmatically into our project. Add a button to your application in the main form and set its name property to Change_Caption and its Text property to Change Caption. Edit the code for the click event in the editor, and write in this code:

Now when you tap on the Change Caption button, the caption of the label changes to "Hello".

In the emulator, you will get this result:

If you tap on the button, you should have this result:

How does it works exactly ?

Actually, when you write this instruction:

You change the Enhanced_Label Caption property. In the control code you actually make a call to Property Let Caption:

The private variable m_strCaption is set to the Property Let parameter called Value. Value is passed to set the new caption for our control and is equal to "Hello!" in this case. Note that the member is updated directly, you should always first affect the new value to a private variable declared and visible only from the control code (m_strCaption, for instance). This allows you to perform checks on the new value before changingthe actual property value. Once m_strCaption is set, we raise immediately the Repaint event from our control.

This event refreshes the control by repainting it on the screen. Since the user control is repainted, the event UserControl_Paint() is raised, so the control caption will be redrawn with the new value of m_strCaption

Additionnaly, suppose that you want to accept only 4 characters and no more for your caption, we could add into our Let Property a check before changing the value:

And, finally, you can get the actual caption property of the control simply by adding this statement into your Change_Caption Button event:

Actually, you call the Get Caption property of our Enhanced_Label:

>Get Caption simply returns the current caption property of the control which is stored in the m_strCaption private variable.

That's all! Once you have assimilated the principle, it's pretty simple to continue our project. Now let's learn how to change the BackColor property of the Enhanced Label

3 - Changing the BackColor property

We will follow exactly the same approach.

Add a member variable called m_lngBackColor in our code control:

This variable will contain the Background Color of our enhanced label. Since a color is stored into a long integer, we had to declare our variable as a long variable, of course.

Also, add this code into the Load event:

This line initializes the label background color to a default color, which is the "white" color in this example.

Now, add this code to the Paint event:

This statement will paint the control with the color stored into the m_lngBackcolor variable (The white color, for instance) when your control appears on your form. Since the UserControl_Paint event is raised when you draw your control, the m_lngBackcolor member is initialized with the default background color.

But we also want to change programmatically the background color. So let's add two properties, just like we did before to set and get the caption control. However, we now want to set and get the background color of the control, so add those two properties:

The Drawing color is defined when you call the BackColorLabel property. For example, draw a new button to your form and set its name to "Change_BackColor". Now open the code of its Click event and enter exactly the following statement to set the background color of the label to blue:

(Note that you can use any color constant to set the background color of the label easily)

Now, when you start the program and click on the button, the following code is executed:

Actually, you call the Let BackColorLabel property, inside the control code and pass the hbColorBlue value to this property. The blue color is, at first, assigned to our member variable m_lngBackcolor:

Now, m_lngBackcolor has the value hbColorBlue, the blue color.

Then, since the Repaint statement is called, the Paint event is raised, allowing us to immediately apply this change to our control by this statement:

the control is repainted on the form with its new blue background color.

Note that the BackColor reserved word is a property inherited from the display class.

Here is the result:

Click on the Change BackColor button, the background color of the label will become blue:

To get the new background color of the control, you can use this statement whenever you want:

4 - Adding the TextColor property

Now you know how to add properties to our Enhanced Label control and how to change them programmatically. What we are going to do now is to add a TextColor property allowing us to get/set the text color of our control.

Open the Enhanced_Label project item and add the following code:

Also, add this line into the Private Sub UserControl_Paint() event handler:

Note that the TextColor reserved word is a property inherited from the Display class.

Now add this other line to the Private Sub UserControl_Load() event handler:

Now you can change the color of the label using a color constant .

Here is an example, you can copy it and paste it in the Click event handler of a button named Change Text Color to make the text color appear in red:

When you launch the program you get this result:

Tap on the Change Text Color button, you will get this result:

Now let's see how to add a new feature allowing us to modify the font used in our Enhanced_Label control

5 - Adding the FontLabel property

We will add the "FontLabel" property allowing us to get/set the font used for the text inside our enhanced label control.

Select the Enhanced_Label item in the project explorer, and add the following code:

Then, add this statement into the Private Sub UserControl_Paint() event handler:

Note that the DrawFont reserved word is a property inherited from the Display class.

Now, add this line to the Private Sub UserControl_Load() event handler:

Now you can change the font used in our Enhanced Label custom control by setting the FontLabel property using a font constant. Here is an example, you can copy it and paste it into the Click event handler of a button called Change_Font, to set the font of the label to a large font:

When you launch the program, you get this result:

Tap on the Change_Font button, the font is modified and is now larger.

6 - List of the new properties added to the enhanced label control

7 - List of color constants

8 - List of font constants

hbFontStandard = 0

hbFontBold = 1

hbFontLarge = 2

hbFontLargeBold = 7

hbFontSymbol = 3

hbFontSymbol7 = 5

hbFontSymbol11 = 4

hbFontLED = 6

9 - The complete source code for the Enhanced Label custom control

You can downoad the whole project here

10 - Conclusion

The goal of this tutorial was to show you how easy it is to develop a custom user control.We have tried to explain in details how to add properties to a control. We hope that you have found this tutorial useful, as well as fun to read and to understand. Now you have all the knowledgeto create your own custom controls and extend your HB++ projects as far as you want with reusable and powerful controls.

We really hope that you will enjoy programming with HB++.