NumericUpDown Class

Definition

Represents a Windows spin box (also known as an up-down control) that displays numeric values.

[System.ComponentModel.DefaultBindingProperty("Value")]
[System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.AutoDispatch)]
[System.Runtime.InteropServices.ComVisible(true)]
public class NumericUpDown : System.Windows.Forms.UpDownBase, System.ComponentModel.ISupportInitialize
Inheritance
Attributes
Implements

Inherited Members

System.ComponentModel.Component

System.MarshalByRefObject

System.Object

System.Windows.Forms.ContainerControl

System.Windows.Forms.Control

System.Windows.Forms.ScrollableControl

System.Windows.Forms.UpDownBase

Examples

The following code example creates and initializes a NumericUpDown control, sets some of its common properties, and allows the user to change some of these properties at run time. This code assumes three CheckBox controls have been placed on a form and handlers for their Click events have been instantiated. The DecimalPlaces, ThousandsSeparator, and Hexadecimal properties are set on the Click event of each check box.

public:
   void InstantiateMyNumericUpDown()
   {
      // Create and initialize a NumericUpDown control.
      numericUpDown1 = gcnew NumericUpDown;
      
      // Dock the control to the top of the form.
      numericUpDown1->Dock = System::Windows::Forms::DockStyle::Top;
      
      // Set the Minimum, Maximum, and initial Value.
      numericUpDown1->Value = 5;
      numericUpDown1->Maximum = 2500;
      numericUpDown1->Minimum = -100;
      
      // Add the NumericUpDown to the Form.
      Controls->Add( numericUpDown1 );
   }

private:
   // Check box to toggle decimal places to be displayed.
   void checkBox1_Click( Object^ sender, EventArgs^ e )
   {
      /* If DecimalPlaces is greater than 0, set them to 0 and round the 
         current Value; otherwise, set DecimalPlaces to 2 and change the 
         Increment to 0.25. */
      if ( numericUpDown1->DecimalPlaces > 0 )
      {
         numericUpDown1->DecimalPlaces = 0;
         numericUpDown1->Value = Decimal::Round( numericUpDown1->Value, 0 );
      }
      else
      {
         numericUpDown1->DecimalPlaces = 2;
         numericUpDown1->Increment = Decimal(0.25);
      }
   }

   // Check box to toggle thousands separators to be displayed.
   void checkBox2_Click( Object^ sender, EventArgs^ e )
   {
      /* If ThousandsSeparator is true, set it to false; 
         otherwise, set it to true. */
      if ( numericUpDown1->ThousandsSeparator )
      {
         numericUpDown1->ThousandsSeparator = false;
      }
      else
      {
         numericUpDown1->ThousandsSeparator = true;
      }
   }

   // Check box to toggle hexadecimal to be displayed.
   void checkBox3_Click( Object^ sender, EventArgs^ e )
   {
      /* If Hexadecimal is true, set it to false; 
         otherwise, set it to true. */
      if ( numericUpDown1->Hexadecimal )
      {
         numericUpDown1->Hexadecimal = false;
      }
      else
      {
         numericUpDown1->Hexadecimal = true;
      }
   }
public void InstantiateMyNumericUpDown()
{
   // Create and initialize a NumericUpDown control.
   numericUpDown1 = new NumericUpDown();

   // Dock the control to the top of the form.
   numericUpDown1.Dock = System.Windows.Forms.DockStyle.Top;

   // Set the Minimum, Maximum, and initial Value.
   numericUpDown1.Value = 5;
   numericUpDown1.Maximum = 2500;
   numericUpDown1.Minimum = -100;
   
   // Add the NumericUpDown to the Form.
   Controls.Add(numericUpDown1);
}

// Check box to toggle decimal places to be displayed.
private void checkBox1_Click(Object sender,
                             EventArgs e)
{
   /* If DecimalPlaces is greater than 0, set them to 0 and round the 
      current Value; otherwise, set DecimalPlaces to 2 and change the 
      Increment to 0.25. */
   if (numericUpDown1.DecimalPlaces > 0)
   {
      numericUpDown1.DecimalPlaces = 0;
      numericUpDown1.Value = Decimal.Round(numericUpDown1.Value, 0);
   }
   else
   {
      numericUpDown1.DecimalPlaces = 2;
      numericUpDown1.Increment = 0.25M;
   }
}

// Check box to toggle thousands separators to be displayed.
private void checkBox2_Click(Object sender,
                             EventArgs e)
{   
   /* If ThousandsSeparator is true, set it to false; 
      otherwise, set it to true. */
   if (numericUpDown1.ThousandsSeparator)
   {
      numericUpDown1.ThousandsSeparator = false;
   }
   else
   {
      numericUpDown1.ThousandsSeparator = true;
   }
}

// Check box to toggle hexadecimal to be displayed.
private void checkBox3_Click(Object sender, 
                             EventArgs e)
{
   /* If Hexadecimal is true, set it to false; 
      otherwise, set it to true. */    
   if (numericUpDown1.Hexadecimal)
   {
      numericUpDown1.Hexadecimal = false;
   }
   else
   {
      numericUpDown1.Hexadecimal = true;
   }
}

Public Sub InstantiateMyNumericUpDown()
    ' Create and initialize a NumericUpDown control.
    numericUpDown1 = New NumericUpDown()
    
    ' Dock the control to the top of the form.
    numericUpDown1.Dock = System.Windows.Forms.DockStyle.Top
    
    ' Set the Minimum, Maximum, and initial Value.
    numericUpDown1.Value = 5
    numericUpDown1.Maximum = 2500
    numericUpDown1.Minimum = - 100
    
    ' Add the NumericUpDown to the Form.
    Controls.Add(numericUpDown1)
End Sub    

' Check box to toggle decimal places to be displayed.
Private Sub checkBox1_Click(sender As Object, e As EventArgs)
    ' If DecimalPlaces is greater than 0, set them to 0 and round the
    ' current Value; otherwise, set DecimalPlaces to 2 and change the
    ' Increment to 0.25. 
    If numericUpDown1.DecimalPlaces > 0 Then
        numericUpDown1.DecimalPlaces = 0
        numericUpDown1.Value = Decimal.Round(numericUpDown1.Value, 0)
    Else
        numericUpDown1.DecimalPlaces = 2
        numericUpDown1.Increment = 0.25D
    End If
End Sub    

' Check box to toggle thousands separators to be displayed.
Private Sub checkBox2_Click(sender As Object, e As EventArgs)
    ' If ThousandsSeparator is true, set it to false;
    ' otherwise, set it to true. 
    If numericUpDown1.ThousandsSeparator Then
        numericUpDown1.ThousandsSeparator = False
    Else
        numericUpDown1.ThousandsSeparator = True
    End If
End Sub    

' Check box to toggle hexadecimal to be displayed.
Private Sub checkBox3_Click(sender As Object, e As EventArgs)
    ' If Hexadecimal is true, set it to false;
    ' otherwise, set it to true. 
    If numericUpDown1.Hexadecimal Then
        numericUpDown1.Hexadecimal = False
    Else
        numericUpDown1.Hexadecimal = True
    End If
End Sub

Remarks

A NumericUpDown control contains a single numeric value that can be incremented or decremented by clicking the up or down buttons of the control. The user can also enter in a value, unless the ReadOnly property is set to true.

The numeric display can be formatted by setting the DecimalPlaces, Hexadecimal, or ThousandsSeparator properties. To display hexadecimal values in the control, set the Hexadecimal property to true. To display a thousands separator in decimal numbers when appropriate, set the ThousandsSeparator property to true. To specify the number of digits displayed after the decimal symbol, set the DecimalPlaces property to the number of decimal places to display.

To specify the allowable range of values for the control, set the Minimum and Maximum properties. Set the Increment value to specify the value to be incremented or decremented to the Value property when the user clicks the up or down arrow buttons. You can increase the speed that the control moves through numbers when the user continuously presses the up or down arrow by setting the Accelerations property.

When the UpButton or DownButton methods are called, either in code or by the click of the up or down buttons, the new value is validated and the control is updated with the new value in the appropriate format. Specifically, if the UserEdit property is set to true, the ParseEditText method is called prior to validating or updating the value. The value is then verified to be between the Minimum and Maximum values, and the UpdateEditText method is called.

Starting with the .NET Framework 4.6, the NumericUpDown control will be resized based on the system DPI setting when the app.config file contains the following entry:

<appSettings>  
  <add key="EnableWindowsFormsHighDpiAutoResizing" value="true" />  
</appSettings>  

Constructors

NumericUpDown()

Initializes a new instance of the NumericUpDown class.

Properties

Accelerations

Gets a collection of sorted acceleration objects for the NumericUpDown control.

DecimalPlaces

Gets or sets the number of decimal places to display in the spin box (also known as an up-down control).

Hexadecimal

Gets or sets a value indicating whether the spin box (also known as an up-down control) should display the value it contains in hexadecimal format.

Increment

Gets or sets the value to increment or decrement the spin box (also known as an up-down control) when the up or down buttons are clicked.

Maximum

Gets or sets the maximum value for the spin box (also known as an up-down control).

Minimum

Gets or sets the minimum allowed value for the spin box (also known as an up-down control).

Padding

Gets or sets the space between the edges of a NumericUpDown control and its contents.

Text

Gets or sets the text to be displayed in the NumericUpDown control.

ThousandsSeparator

Gets or sets a value indicating whether a thousands separator is displayed in the spin box (also known as an up-down control) when appropriate.

Value

Gets or sets the value assigned to the spin box (also known as an up-down control).

Methods

BeginInit()

Begins the initialization of a NumericUpDown control that is used on a form or used by another component. The initialization occurs at run time.

CreateAccessibilityInstance()

Creates a new accessibility object for the control.

DownButton()

Decrements the value of the spin box (also known as an up-down control).

EndInit()

Ends the initialization of a NumericUpDown control that is used on a form or used by another component. The initialization occurs at run time.

OnKeyDown(KeyEventArgs)

Raises the KeyDown event.

OnKeyUp(KeyEventArgs)

Raises the KeyUp event.

OnLostFocus(EventArgs)

Raises the LostFocus event.

OnTextBoxKeyPress(Object, KeyPressEventArgs)

Raises the KeyPress event.

OnValueChanged(EventArgs)

Raises the ValueChanged event.

ParseEditText()

Converts the text displayed in the spin box (also known as an up-down control) to a numeric value and evaluates it.

ToString()

Returns a string that represents the NumericUpDown control.

UpButton()

Increments the value of the spin box (also known as an up-down control).

UpdateEditText()

Displays the current value of the spin box (also known as an up-down control) in the appropriate format.

ValidateEditText()

Validates and updates the text displayed in the spin box (also known as an up-down control).

Events

PaddingChanged

Occurs when the value of the Padding property changes.

TextChanged

Occurs when the value of the Text property changes.

ValueChanged

Occurs when the Value property has been changed in some way.