Home

Windows Controls: The Domain Up Down Control
 

Introduction to the Domain Up Down Control
 

Description

A spin button, also called an up-down control, is usually made to display a numeric value that can then be increased or decreased when the user clicks one of the buttons of the controls. In a Microsoft Windows typical application, if you wanted to deal with values other than numbers, there was some gymnastic code to write. Fortunately, the .NET Framework provides a special spin button that can hold and display values other numbers.

The .NET Framework's domain up-down control is a text-based object created from a class named DomainUpDown. Like NumericUpDown, the DomainUpDown class is derived from the UpDownBase class where it gets its primary functionality from.

Creating a Domain Up-Down Control

At design time, to get a domain up-down control, from the Toolbox, you can click the DomainUpDown button and click the form. To programmatically create a domain up-down control, declare a variable of type DomainUpDown, initialize it and add it to the Controls property of the container that will hold it. Here is an example:

#include <windows.h>

#using <System.dll>
#using <System.Drawing.dll>
#using <System.Windows.Forms.dll>

using namespace System;
using namespace System::Drawing;
using namespace System::Windows::Forms;

public ref class CExercise : Form
{
private:
    DomainUpDown ^ spnNames;

public:
    CExercise()
    {
        InitializeComponent();
    }
	
private:
    void InitializeComponent()
    {
        spnNames  = gcnew DomainUpDown;
        
        Controls->Add(spnNames);
    }
};

[STAThread]
int APIENTRY WinMain(HINSTANCE hInstance,
		     HINSTANCE hPrevInstance,
		     LPSTR lpCmdLine,
		     int nCmdShow)
{
    Application::Run(gcnew CExercise);

    return 0;
}

This would produce:

ApplicationPractical Learning: Introducing the Domain Up-Down Control
  1. Start a new Windows Application and name it MovieReview1
  2. Right-click each of the following pictures and paste them in the MovieReview1\MovieReview1 folder of the current project
     
  3. Design the form as follows:
     
    Movie Review
    Control Text Name Other Properties
    Label Label Title:    
    DomainUpDown DomainUpDown   dudTitles  
    Label Label Director:    
    TextBox TextBox   txtDirector  
    Label Label Cast of Characters    
    Label Label © Year    
    TextBox TextBox   txtYearReleased TextAlign: Right
    Label Label Rating:    
    TextBox TextBox   txtRating  
    ListBox ListBox   lbxCastMembers  
    Label Label Length:    
    TextBox TextBox   txtLength  
    PictureBox PictureBox   pbxImage  
    Button Button Close btnClose  
  4. In the Solution Explorer, right-click Form1.h and click Rename
  5. Type MovieReview.h and press Enter
  6. Open the Form1.h header file and change the include line: 
    // MovieReview1.cpp : main project file.

#include "stdafx.h"
#include "MovieReview.h"

using namespace MovieReview1;

[STAThreadAttribute]
int main(array<System::String ^> ^args)
{
	// Enabling Windows XP visual effects before any controls are created
	Application::EnableVisualStyles();
	Application::SetCompatibleTextRenderingDefault(false); 

	// Create the main window and run it
	Application::Run(gcnew Form1());
	return 0;
}

Characteristics of the Domain Up-Down Control
 

Introduction

The spin button shares the normal characteristics of other graphical Windows controls that they inherit from their ancestor the Control class. These characteristics including the location, the size, the background color, the ability to be enabled or disabled, the ability to be hidden or shown, etc. As a text-based object, the domain up-down control uses characteristics such as the ability to display text, alignment of text, and the ability to resize itself according to the length of its text, which is based on the AutoSize property.

Because the DomainUpDown class is derived from the UpDownBase class, it inherits the ability to specify on what side of the text box the spin button will align, to the left or to the right. This is controlled by the UpDownAlign property. The DomainUpDown class also inherits the ability to let the user manually change the value of the control. This is supported by the UserEdit Boolean property.

ApplicationPractical Learning: Configuring the Control
  1. On the form, click the domain up-down control
  2. In the Properties window, set the TextAlign property to Center
  3. Set the UpDownAlign property to Left
     
  4. Save the form
 
 
 

The Text of the Control

When using the spin button, the user can click one of the arrow buttons. This would bring the next or the previous string of the list and display that item in the text box part of the control. The user can also first give focus to the control, and then use the arrow keys to navigate in the list of strings.

At any time, the string that is currently displaying on the spin button is represented by its Text property. To specify the string that the control should display, at design time, you can enter the string in the Text field of the Properties window. To programmatically specify what item the control should display, assign it to its Text property. Here is an example:

void InitializeComponent()
{
    spnNames  = gcnew DomainUpDown;
    spnNames->Location = Point(12, 12);

    spnNames->Text = "Paul Yamaguchi";
        
    Controls->Add(spnNames);
}

This would produce:

You can even use a string that is not in the collection. If you do, the control would display it but if the user changes the current item of the control that string would disappear and the user cannot get it back.

The Items of the Control

As mentioned already, instead of displaying (only) numbers, the domain up-down control can be used to display strings (and/or numbers). To make this possible, the control must hold a list the strings to display. This list is held by the Items property. At design time, to create a list of values, in the Properties window of the control, click Items and click its ellipsis button. This would open the String Collection Editor

String Collection Editor

You can then type each string on its own line (of course, you can type only numbers or a mix of numbers and strings). After creating the list, you can click OK.

The DomainUpDown.Items property is based on the nested DomainUpDownItemCollection class. The DomainUpDownItemCollection class is derived from the ArrayList class which gives it the ability to create and manage its list. To programmatically add a string to the list, call its Add() member function. You can do this continually until you have added all the necessary strings. Here is an example:

void InitializeComponent()
{
    spnNames  = gcnew DomainUpDown;
    spnNames->Location = Point(12, 12);

    spnNames->Items->Add("Patricia Katts");
    spnNames->Items->Add("Paul Bertrand Yamaguchi");
    spnNames->Items->Add("Marguerite Soya");
        
    Controls->Add(spnNames);
}

Instead of adding one item at a time, the DomainUpDownItemCollection class is equipped with a member function named AddRange. This allows you to add an array of items. Here is an example:

void InitializeComponent()
{
    spnNames  = gcnew DomainUpDown;
    spnNames->Location = Point(12, 12);

    spnNames->Items->Add("Patricia Katts");
    spnNames->Items->Add("Paul Bertrand Yamaguchi");
    spnNames->Items->Add("Marguerite Soya");

    array<String ^> ^  Names = 
    {
        "Huguette Lingon", "Peter Kabba",
        "Harry Almada", "Allen Dean"
    };
    spnNames->Items->AddRange(Names);
        
    Controls->Add(spnNames);
}

When calling Add() (or AddRange()), the new item(s) is(are) added at the end of the existing list, unless the list is empty, in which case the item(s) would be the first. The DomainUpDownItemCollection class is also equipped with a member function named Insert() that allows you to add a new item somewhere inside the list at a position of your choice.

Sorting the List

As you create the list of strings, they are added either at the end (with Add() or AddRange()) or inserted (with Insert()) at the position of your choice. If you want the items to be arranged in alphabetical or chronological order, use the Sorted Boolean property.

To find out whether the list is sorted or not, get the value of the control's Sorted property.

The Index of the Current String

When the user clicks one of the buttons of the spin control or use an arrow key to change the item, the control fires a SelectedItemChanged event. You can use this event to find out what the index of the item that was selected. You have to alternatives.

You can identify an item by its index. The index of the current item is represented by the SelectedIndex property, which is an integer. If you prefer to locate an item by its name (or string), you can use the SelectedItem property, which is of type object. You can also use the SelectedItem property to specify the string that the spin button should display. To do this, simply assign a string to this property. Here is an example:

void InitializeComponent()
{
    spnNames  = gcnew DomainUpDown;
    spnNames->Location = Point(12, 12);

    spnNames->Items->Add("Patricia Katts");
    spnNames->Items->Add("Paul Bertrand Yamaguchi");
    spnNames->Items->Add("Marguerite Soya");

    array<String ^> ^  Names = 
    {
        "Huguette Lingon", "Peter Kabba",
        "Harry Almada", "Allen Dean"
    };
    spnNames->Items->AddRange(Names);

    spnNames->SelectedItem = "Peter Kabba";
        
    Controls->Add(spnNames);
}

Unlike the Text property, if you assign a string that is not in the list, it would not show in the text box part of the control. This means that, if you assign a string (that is not in the list of control's strings) to the Text property, the compiler would simply display that string in the control. On the other hand, when you assign a string to the SelectedItem property, the compiler would check in the list if that string exists. If it finds it, then it displays it in the text box. If it does not find, it does nothing: it does not throw an exception.

ApplicationPractical Learning: Identifying the Selected Item
  1. Double-click an unoccupied area of the form
  2. Return to the form
  3. On the form, double-click the domain up-down control
  4. Change the file as follows:
    #pragma once

namespace MovieReview1
{
    using namespace System;
    using namespace System::ComponentModel;
    using namespace System::Collections;
    using namespace System::Windows::Forms;
    using namespace System::Data;
    using namespace System::Drawing;

    /// <summary>
    /// Summary for Form1
    /// </summary>
    public ref class Form1 : public System::Windows::Forms::Form
    {
    private:
	array<String ^> ^  Titles;
        array<String ^> ^  Directors;
        array<int ^> ^     YearsReleased;
        array<String ^> ^  Ratings;
        array<String ^> ^  Lengths;
        array<String ^> ^  Pictures;

        array<ListBox ^> ^ Actors;

        . . . No Change
		
	System::Void Form1_Load(System::Object^  sender, System::EventArgs^  e)
	{
	    Titles        = gcnew array<String ^>(8);
	    Directors     = gcnew array<String ^>(8);
	    YearsReleased = gcnew array<int ^>(8);
	    Ratings       = gcnew array<String ^>(8);
	    Lengths       = gcnew array<String ^>(8);
	    Pictures      = gcnew array<String ^>(8);
			 
	    Actors        = gcnew array<ListBox ^>(8);
			 
	    Titles[0]       = "Distinguished Gentleman (The)";
	    Directors[0]    = "Jonathan Lynn";
            YearsReleased[0] = 1992;
            Ratings[0]       = "R";
            Lengths[0]       = "112 Minutes";
            Pictures[0]      = "distgent.jpg";
            Actors[0]        = gcnew ListBox();
            Actors[0]->Items->Add("Eddie Murphy");
            Actors[0]->Items->Add("Lane Smith");
            Actors[0]->Items->Add("Sheryl Lee Ralph");
            Actors[0]->Items->Add("Joe Don Baker");
            Actors[0]->Items->Add("Victoria Rowell");
            Actors[0]->Items->Add("Grant Shaud");
            Actors[0]->Items->Add("Kevin McCarthy");
            Actors[0]->Items->Add("Charles S. Dutton");
            Actors[0]->Items->Add("Victor Rivers");
            Actors[0]->Items->Add("Chi McBride");
            Actors[0]->Items->Add("Sonny Jim Gaines");
            Actors[0]->Items->Add("Noble Willingham");
            Actors[0]->Items->Add("Gary Frank");
            Actors[0]->Items->Add("Daniel Benzali");
            Actors[0]->Items->Add("Cynthia Harris");

            Titles[1]        = "Fatal Attraction";
            Directors[1]     = "Adrian Lyne";
            YearsReleased[1] = 1987;
            Ratings[1]       = "R";
            Lengths[1]       = "119 Minutes";
            Pictures[1]      = "fatal.jpg";
            Actors[1]        = gcnew ListBox();
            Actors[1]->Items->Add("Michael Douglas");
            Actors[1]->Items->Add("Glenn Close");
            Actors[1]->Items->Add("Anne Archer");
            Actors[1]->Items->Add("Ellen Hamilton Latzen");
            Actors[1]->Items->Add("Stuart Pankin");

            Titles[2]        = "New Jack City";
            Directors[2]     = "Mario Van Peebles";
            YearsReleased[2] = 1991;
            Ratings[2]       = "R";
            Lengths[2]       = "97 Minutes";
            Pictures[2]      = "newjack.jpg";
            Actors[2]        = gcnew ListBox();
            Actors[2]->Items->Add("Wesley Snipes");
            Actors[2]->Items->Add("Ice-T");
            Actors[2]->Items->Add("Allen Payne");
            Actors[2]->Items->Add("Chris Rock");
            Actors[2]->Items->Add("Mario Van Peebles");
            Actors[2]->Items->Add("Michael Michele");
            Actors[2]->Items->Add("Bill Nunn");

            Titles[3]        = "Showgirls";
            Directors[3]     = "Paul Verhoeven";
            YearsReleased[3] = 1995;
            Ratings[3]       = "NC-17";
            Lengths[3]       = "128 Minutes";
            Pictures[3]      = "showgirls.jpg";
            Actors[3]        = gcnew ListBox();
            Actors[3]->Items->Add("Elizabeth Berkley");
            Actors[3]->Items->Add("Kyle MacLachlan");
            Actors[3]->Items->Add("Gina Gershon");
            Actors[3]->Items->Add("Glenn Plummer");

            Titles[4] = "Annie";
            Directors[4] = "John Huston";
            YearsReleased[4] = 1982;
            Ratings[4] = "PG";
            Lengths[4] = "126 Minutes";
            Pictures[4] = "annie.jpg";
            Actors[4] = gcnew ListBox();
            Actors[4]->Items->Add("Albert Finney");
            Actors[4]->Items->Add("Carol Burnett");
            Actors[4]->Items->Add("Ann Reinking");
            Actors[4]->Items->Add("Tim Curry");
            Actors[4]->Items->Add("Bernadette Peters");

            Titles[5] = "Dave";
            Directors[5] = "Ivan Reitman";
            YearsReleased[5] = 1993;
            Ratings[5] = "R";
            Lengths[5] = "110 Minutes";
            Pictures[5] = "Dave.jpg";
            Actors[5] = gcnew ListBox();
            Actors[5]->Items->Add("Kevin Kline");
            Actors[5]->Items->Add("Sigourney Weaver");
            Actors[5]->Items->Add("Frank Langella");
            Actors[5]->Items->Add("Kevin Dunn");
            Actors[5]->Items->Add("Ving Rhames");
            Actors[5]->Items->Add("Ben Kingsley");
            Actors[5]->Items->Add("Charles Grodin");

            Titles[6] = "Housesitter";
            Directors[6] = "Frank Oz";
            YearsReleased[6] = 1992;
            Ratings[6] = "PG";
            Lengths[6] = "110 Minutes";
            Pictures[6] = "housesitter.jpg";
            Actors[6] = gcnew ListBox();
            Actors[6]->Items->Add("Steve Martin");
            Actors[6]->Items->Add("Goldie Hawn");
            Actors[6]->Items->Add("Dana Delany");
            Actors[6]->Items->Add("Julie Harris");
            Actors[6]->Items->Add("Donald Moffat");
            Actors[6]->Items->Add("Peter MacNicol");

            Titles[7] = "Beverly Hills Cop";
            Directors[7] = "Martin Brest";
            YearsReleased[7] = 1984;
            Ratings[7] = "R";
            Lengths[7] = "105 Minutes";
            Pictures[7] = "bhc.jpg";
            Actors[7] = gcnew ListBox();
            Actors[7]->Items->Add("Eddie Murphy");
            Actors[7]->Items->Add("Judge Reinhold");
            Actors[7]->Items->Add("John Ashton");
            Actors[7]->Items->Add("Lisa Eilbacher");
            Actors[7]->Items->Add("Ronny Cox");
            Actors[7]->Items->Add("Steven Berkoff");
            Actors[7]->Items->Add("James Russo");
            Actors[7]->Items->Add("Jonathan Banks");
            Actors[7]->Items->Add("Bronson Pinchot");
            Actors[7]->Items->Add("Paul Reiser");
            
            dudTitles->Items->AddRange(Titles);

            dudTitles->SelectedIndex = 0;
            dudTitles_SelectedItemChanged(sender, e);
	}
private: System::Void dudTitles_SelectedItemChanged(System::Object^  sender,
			System::EventArgs^  e)
	{
	    lbxCastMembers->Items->Clear();
			 
	    txtDirector->Text = Directors[dudTitles->SelectedIndex];
	    txtYearReleased->Text =
	    	YearsReleased[dudTitles->SelectedIndex]->ToString();
	    txtRating->Text = Ratings[dudTitles->SelectedIndex];
	    txtLength->Text = Lengths[dudTitles->SelectedIndex];
	    pbxImage->Image =
	    	Image::FromFile(Pictures[dudTitles->SelectedIndex]);
	    lbxCastMembers->Items->AddRange(Actors[dudTitles->SelectedIndex]->Items);
	 }
    };
}
  5. Return to the form
  6. Double-click the Close button and implement its event as follows:
    System::Void btnClose_Click(Object ^ sender, EventArgs ^ e)
{
    Close();
}
  7. Execute the application and test the domain control
  8. Close the form and return to your programming environment
  9. Return to the form

Wrapping the List Navigation

As mentioned previously, when the user navigates through the list, the items are changed one after another. When the user gets to the end of the list, the navigation stops and the user cannot go further. As an alternative, when the user gets to the end of the list and click the up button, if you want, you can make the list restart from the beginning. This characteristics is controlled by the Wrap Boolean property whose default value is false.

To find out whether the control is currently set to wrap, get the value of its Wrap property.

ApplicationPractical Learning: Wrapping the Navigation
  1. On the form, click the domain up-down control
  2. In the Properties window, double-click Wrap to set its value to True 
  3. Execute the application and test the domain control
     
  4. Close the form and return to your programming environment
 
 
   
 
Home Copyright © 2011 FunctionX, Inc. Home