Export (0) Print
Expand All

Walkthrough: Authoring a User Control with Visual J#

Visual Studio 2005

User controls provide a means by which custom graphical interfaces can be created and reused. A user control is essentially a component with a visual representation. As such, it might consist of one or more Windows Forms controls, components, or blocks of code. These elements can extend functionality by validating user input, modifying display properties, or performing other tasks required by the author. User controls can be placed on Windows Forms in the same manner as other controls. In the first part of this walkthrough, you create a simple user control called ctlClock. In the second part of the walkthrough, you extend the functionality of ctlClock through inheritance.

When you create a new project, you specify its name to set the root package, assembly name, and project name, and ensure that the default component will be in the correct package.

To create the ctlClockLib control library and the ctlClock control

  1. On the File menu, point to New, and then click Project to open the New Project dialog box.

  2. Click the Windows Control Library project template in the list of Visual J# Projects, and in the Name box, type ctlClockLib.

    The project name, ctlClockLib, is also assigned to the root package by default. The root package is used to qualify the names of components in the assembly. For example, if two assemblies provide components named ctlClock, you can specify your ctlClock component using ctlClockLib.ctlClock.

  3. In Solution Explorer, right-click UserControl1.jsl, and on the shortcut menu, select View Code.

  4. In Solution Explorer, right-click UserControl1.jsl and click Rename. Change the name from UserControl1.jsl to ctlClock.jsl.

  5. Examine the class definition and the class constructor and notice that their names have changed from public class UserControl1 to public class ctlClock and from public UserControl1() to public ctlClock() respectively.

  6. On the File menu, click Save All to save the project.

A visual interface is an essential part of your user control. This visual interface is implemented by the addition of one or more controls to the User Control Designer. In the following demonstration, you will incorporate controls into your user control and write code to implement functionality.

To add a label and a timer to your user control

  1. In Solution Explorer, right-click ctlClock.jsl, and then select View Designer.

  2. In the Toolbox, click the All Windows Forms tab, and then double-click label.

    A label control named label1 is added to your control on the User Control Designer.

  3. In the designer, click label1. In the Properties window, set the following properties.

    Property Change to

    Name

    lblDisplay

    Text

    (blank space)

    TextAlign

    MiddleCenter

    Font.Size

    14

  4. In the Toolbox, click All Windows Forms, and then double-click Timer.

    Because a timer is a component, it has no visual representation at run time. It therefore does not appear with the controls on the User Control Designer, but rather in the component tray.

  5. In the component tray, click timer1 and set the Interval property to 1000, and the Enabled property to True.

    The Interval property controls the frequency with which the timer component ticks. Each time timer1 ticks, it runs the code in the timer1_Tick event. The interval represents the number of milliseconds between ticks.

  6. In the component tray, double-click timer1 to go to the timer1_Tick event for ctlClock.

  7. Modify the code so that it resembles the following:

    // Visual J#
    protected void timer1_Tick (Object sender, System.EventArgs e)
    {
        lblDisplay.set_Text(System.DateTime.get_Now().ToLongTimeString()); 
    }
    

    This code will cause the current time to be shown in lblDisplay. Because the interval of timer1 was set to 1000, this event will fire every thousand milliseconds, thus updating the current time every second.

    By default, the timer1_Tick method added by double-clicking timer1 will have private scope. Notice in the previous code segment that you modified the scope to protected.

  8. From the File menu, choose Save All to save the project.

Your clock control now encapsulates a Label control and a Timer component, each with its own set of inherent properties. While the individual properties of these controls will not be accessible to subsequent users of your control, you can create and expose custom properties by writing the appropriate blocks of code. In the following section, you will add custom properties to your control that enable the user to change the color of the background and text.

To add custom member to your user control

  1. In Solution Explorer, right-click ctlClock.jsl, and then click View Code from the shortcut menu.

    The Code Editor opens.

  2. Locate the public class ctlClock statement. Beneath the opening {, type:

    // Visual J#
    private Color colFColor;
    private Color colBColor;
    

    These statements create the private variables that you will use to store the values for the custom properties you are about to create.

  3. Add the following code beneath the variable declarations from the previous step:

    // Visual J#
    /** @property */
    public Color get_ClockBackColor()
    {
        return colBColor;
    }
    /** @property */
    public void set_ClockBackColor(Color value)
    {
        colBColor = value;
        lblDisplay.set_BackColor(colBColor);
    }
    /** @property */
    public Color get_ClockForeColor()
    {
        return colFColor;
    }
    /** @property */
    public void set_ClockForeColor(Color value)
    {
        colFColor = value;
        lblDisplay.set_ForeColor(colFColor);
    }
    

    The preceding code makes two custom properties, ClockForeColor and ClockBackColor, available to subsequent users of this control. The get_ and set_ statements provide for storage and retrieval of the custom properties' values, as well as code to implement appropriate functionality.

  4. From the File menu, choose Save All to save the project.

Controls are not stand-alone applications; they must be hosted in a container. To test your control, you must provide a test project within which it runs. In this section, you will build your control and test it in a Windows Form.

To build your control

  • On the Build menu, click Build Solution.

To create a test project

  1. On the File menu, point to Add and then click New Project to open the Add New Project window.

  2. Click Windows Application, and in the Name box, type Test.

  3. In Solution Explorer, right-click the References node for the Test project. Click Add Reference to display the Add Reference dialog box.

  4. Click the tab labeled Projects. Your user control project will be listed under Project Name.

    Double-click your project. This will add a new tab to the Toolbox called ctlClockLib Components.

After you have added your reference, you can place your control in your form.

To test your control

  1. With Form1 displayed in the Design view, click ctlClockLib Components, in the Toolbox, and then scroll down until the control icon representing ctlClock is displayed.

  2. Double-click the ctlClock icon.

    A copy of your control is now added to your form. Note that it displays the current time and is updated each second.

  3. Select the icon and move your mouse over your form.

  4. Hold down the left mouse button while moving the mouse across the form.

    Another copy of your control is drawn onto the form. You can add as many copies of your timer to your form as you want.

  5. In the designer, click one of the instances of ctlClock.

    The properties for this instance are displayed in the Properties window.

  6. In the Properties window, locate the ClockBackColor property, and then select the property to display the color palette.

  7. Select a color by clicking it.

    The background color of your control changes to the color you selected.

  8. Use a similar sequence of events to verify that the ClockForeColor property is functioning as expected.

  9. Press F5 to run your control in the UserControl TestContainer window. For more information on UserControl TestContainer, see How to: Test the Run-Time Behavior of a UserControl.

  10. To close the UserControl TestContainer, click Close.

In this section, you have seen how components and Windows controls can be combined with code and packaging to provide custom functionality in the form of a user control. You have learned to expose properties in your user control, and how to test your control after it is complete. In the next section, you will learn how to construct an inherited user control using ctlClock as a base.

In the previous section, you learned how to combine Windows controls, components, and code into reusable user controls. Your user control can now be used as a base upon which other controls can be built. The process of deriving a class from a base class is called inheritance. In this section, you will create a user control called ctlAlarmClock. This control will be derived from its parent control, ctlClock. You will learn to extend the functionality of ctlClock by overriding parent methods and adding new methods and properties.

Creating the Inherited Control

The first step in creating an inherited control is to derive it from its parent. This action creates a new control that has all of the properties, methods, and graphical characteristics of the parent control, but can also act as a base for the addition of new or modified functionality.

To create the inherited control

  1. In Solution Explorer, click ctlClockLib.

  2. From the Project menu, select Add User Control.

    The Add New Item window opens with User Control selected.

  3. In the Name box, type ctlAlarmClock.jsl, and click Add.

    The Inheritance Picker window appears.

  4. Under Component Name, double-click ctlClock.

  5. In Solution Explorer, browse the current projects. Notice the file ctlAlarmClock.jsl that has been added to the project.

Adding the Alarm Properties

Properties are added to an inherited control in the same way they are added to a user control. You will now use the property declaration syntax to add two properties to your control:

  • AlarmTime, which will store the value of the date and time the alarm, is to go off.

  • AlarmSet, which will indicate whether or not the alarm is set.

To add properties to your user control

  1. In Solution Explorer, right-click ctlAlarmClock and select View Code.

  2. Locate the public class statement. Note that your control inherits from ctlClockLib.ctlClock. Beneath the public class ctlAlarmClock extends ctlClockLib.ctlClock { statement, add the following code:

    // Visual J#
    private System.DateTime dteAlarmTime;
    private boolean blnAlarmSet;
    // These properties will be declared as public to allow future 
    // developers to access them.
    /** @property*/
    public System.DateTime get_AlarmTime()
    {
        return dteAlarmTime;
    }
    /** @property*/
    public void set_AlarmTime(System.DateTime value)
    {
        dteAlarmTime = value;
    }
    /** @property*/
    public boolean get_AlarmSet()
    {
        return blnAlarmSet;
    }
    /** @property*/
    public void set_AlarmSet(boolean value)
    {
        blnAlarmSet = value;
    }
    

Adding to the Graphical Interface of Your Control

Your inherited control has a visual interface that is identical to the control it inherits from. It possesses the same constituent controls as its parent control, but the properties of the constituent controls will not be available unless they were specifically exposed. You may add to the graphical interface of an inherited user control in the same manner as you would add to any user control. To continue adding to your alarm clock's visual interface, you will add a label control that will flash when the alarm is sounding.

To add the label control

  1. In Solution Explorer, right-click ctlAlarmClock and select View Designer from the shortcut menu.

    The designer for ctlAlarmClock opens in the main window.

  2. Click the display portion of the control, and observe the Properties window.

    Notice that while all the properties are displayed, they are dimmed. This indicates that these properties are native to lblDisplay, and cannot be modified or accessed in the Properties window. By default, controls contained in a user control are private, and their properties are not accessible by any means.

    NoteTip

    If you want subsequent users of your control to have access to its internal controls, declare them as public or protected. This will allow you to set and modify properties of controls contained within your user control by using the appropriate code.

  3. Add a Label control to your user control.

  4. Using the mouse, move the label control immediately beneath the display box. In the Properties window, set the following properties:

    Property Setting

    Name

    lblAlarm

    Text

    Alarm!

    TextAlign

    Middle Center

    Visible

    False

Adding the Alarm Functionality

In the previous sections, you added custom members and a control that will enable alarm functionality in your user control. In this section, you will add code to compare the current time to the alarm time and, if they are the same, to flash an alarm. By overriding the timer1_Tick method of ctlClock, you will extend the capability of ctlAlarmClock while retaining all of the inherent functionality of ctlClock.

To override the timer1_Tick method of ctlClock

  1. In the Code Editor, locate the private boolean blnAlarmSet; statement. Immediately beneath it, add the following statement:

    // Visual J#
    private boolean blnColorTicker;
    
  2. Add following code just before the end of class declaration:

    // Visual J#
    protected void timer1_Tick(Object sender, System.EventArgs e)
    {
       // Calls the timer1_Tick method of ctlClock.
       super.timer1_Tick(sender, e);
       // Checks to see if the alarm is set.
       if (blnAlarmSet == false)
           return;
       else
       // If the date, hour, and minute of the alarm time are the same as
       // now, cause the display to flash. 
       {
            if (dteAlarmTime.get_Date() == System.DateTime.get_Now().get_Date() && 
                dteAlarmTime.get_Hour() == System.DateTime.get_Now().get_Hour() && 
                dteAlarmTime.get_Minute() == System.DateTime.get_Now().get_Minute())
            {
                // Makes lblAlarm visible, and changes the backcolor based 
                // on the value of blnColorTicker. The backcolor of the 
                // label will flash once per tick of the clock.
                lblAlarm.set_Visible(true);
                if (blnColorTicker == false) 
                {
                    lblAlarm.set_BackColor( Color.get_Red());
                    blnColorTicker = true;
                }
                else
                {
                    lblAlarm.set_BackColor(Color.get_Blue());
                    blnColorTicker = false;
                }
            }
            else
            {
                // Once the alarm has sounded for a minute, the label is 
                // made invisible again.
                lblAlarm.set_Visible(false);
            }
        }
    }
    

The addition of this code accomplishes several tasks. It directs the control to use this method in place of the method that was inherited from the base control. When this method is called, it invokes the super.timer1_Tick statement, ensuring that all of the functionality incorporated in the original control is reproduced in this control. It then runs additional code to incorporate the alarm functionality. A flashing label control will appear when the alarm is triggered.

Your alarm clock control is almost complete. The only thing that remains is to implement a way to turn it off. To do this, we will add a button and add code to the btnAlarmOff_Click method.

To implement the shutoff method

  1. In Solution Explorer, right-click ctlAlarmClock.jsl and click View Designer.

    The designer opens.

  2. Add a button to the control. Set the properties of the button as follows:

    Property Value

    Name

    btnAlarmOff

    Text

    Disable Alarm

  3. In the designer, double-click Disable Alarm.

    The Code Editor opens to the private void btnAlarmOff_Click line.

  4. Modify this method so that it resembles the following:

    // Visual J#
    private void btnAlarmOff_Click (Object sender, System.EventArgs e)
    {
        // Turns off the alarm.
        blnAlarmSet = false;
        // Hides the flashing label
        lblAlarm.set_Visible(false);
    }
    
  5. From the File menu, choose Save All to save the project.

Testing Your Inherited Control

As with a standard user control, an inherited user control cannot stand alone and must be hosted in a form or other container. Because ctlAlarmClock has a greater depth of functionality, additional code is required to test it. In this section, you will write a simple program to test the functionality of ctlAlarmClock. You will write code to set and display the AlarmTime property of ctlAlarmClock, and will test its inherent functions.

To build and add your control to a test form

  1. In Solution Explorer, click ctlClockLib. On the Build menu, select Build ctlClockLib.

  2. Add a new Windows Application project to the solution, and name it Test2.

  3. In Solution Explorer, right-click the References node for your test project. Click Add Reference to display the Add Reference window. Click the tab labeled Projects. The ctlClockLib name will be listed under Project Name. Double-click it, and note that it now appears in the ctlClockLib Components window. This will add a reference to ctlClockLib.

  4. In the Toolbox, click ctlClockLib Components.

  5. Scroll down until the icon for ctlAlarmClock comes into view.

  6. Double-click ctlAlarmClock to add a copy of ctlAlarmClock to your form.

  7. In the Toolbox, locate and double-click DateTimePicker to add a DateTimePicker control to your form, and add a Label control by double-clicking Label.

  8. Use the mouse to position the controls in a convenient place on the form.

  9. Set the properties of these controls as follows:

    Control Property Value

    label1

    Text

    (leave blank)

     

    Name

    lblTest

    dateTimePicker1

    Name

    dtpTest

     

    Format

    Time

  10. In the designer, double-click DateTimePicker.

    The Code Editor opens to private void dtpTest_ValueChanged.

  11. Modify the code so that it resembles the following:

    // Visual J#
    private void dtpTest_ValueChanged (Object sender, System.EventArgs e)
    {
        ctlAlarmClock1.set_AlarmTime(dtpTest.get_Value());
        ctlAlarmClock1.set_AlarmSet(true);
        lblTest.set_Text("Alarm Time is " + ctlAlarmClock1.get_AlarmTime().ToShortTimeString());
    }
    
  12. In Solution Explorer, right-click Test2 and choose Set as Startup Project from the shortcut menu.

  13. From the Debug menu, choose Start.

    The test program starts. Note that the current time is updated in the ctlAlarmClock control, and that the starting time is shown in the DateTimePicker control.

  14. Click the DateTimePicker where the minutes of the hour are displayed.

  15. Using the keyboard, set a value for minutes that is one minute greater than the current time shown by ctlAlarmClock.

    The time for the alarm setting is shown in lblTest.

  16. Wait for the displayed time to reach the alarm setting time.

    When the displayed time reaches the time to which the alarm is set, the lblAlarm will flash. Turn off the alarm by clicking the Disable Alarm button. You can now reset the alarm.

This walkthrough has covered a number of key concepts. You have learned to create a user control by combining controls and components into a user control container. You have learned to add properties to your control, and to write code to implement custom functionality. In the second section, you learned to extend the functionality of a given user control through inheritance, and to alter the functionality of host methods by overriding those methods.

Community Additions

ADD
Show:
© 2014 Microsoft