HypernovaDesktop Components · docs
Binarymission
WinForms › Extended Text › BinaryNumericExtendedText

BinaryNumericExtendedText

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.TextControls

A BinaryExtendedText for numbers – quantities, prices, percentages – that accepts only numeric input, can hold the value within a range, steps it with the arrow keys and the mouse wheel, and reads it back as a decimal.

public class BinaryNumericExtendedText : BinaryExtendedText, ISupportInitialize

Inherits from / implements: BinaryExtendedText, ISupportInitialize

Remarks

What it is for

Use it where a NumericUpDown is too heavy or its spin buttons are not wanted: an order quantity, a discount percentage, a unit price. It has the flat, coloured border of BinaryExtendedText.

Key concepts

  • The text is the value. Read and write it as a number through Value, which is null while the box is empty; ValueChanged is raised for every change.
  • Input. Only digits, the minus sign, editing keys and – when DecimalPlaces is above zero – one decimal separator of the current culture can be typed. Pasted text that is not a number is replaced with Minimum.
  • Range. While ShouldIUseInputRange is true, the value is held between Minimum and Maximum.
  • Stepping. Up and Down move the value by Step, Page Up and Page Down by ten steps, and the wheel by one step a notch while the box has the focus (EnableStepping).
  • Display. When the box loses the focus the value is written with DecimalPlaces places, and with grouping separators if ShowThousandsSeparator is set; the separators come out again while it is being edited.

Examples

using System;
using System.Drawing;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.TextControls;

public class OrderLineForm : Form
{
    private const decimal UnitPrice = 12.50m;
    private readonly BinaryNumericExtendedText discountBox;
    private readonly Label totalLabel;

    public OrderLineForm()
    {
        Text = "Order line";
        ClientSize = new Size(300, 100);

        discountBox = new BinaryNumericExtendedText
        {
            Location = new Point(12, 12),
            Width = 80,
            DecimalPlaces = 1,
            Step = 2.5m,
            Minimum = 0,
            Maximum = 50,
            ShouldIUseInputRange = true,
            SelectAllOnFocus = true,
            TextAlign = HorizontalAlignment.Right
        };
        discountBox.ValueChanged += DiscountBox_ValueChanged;

        totalLabel = new Label { Location = new Point(110, 15), AutoSize = true };

        Controls.Add(discountBox);
        Controls.Add(totalLabel);

        discountBox.Value = 10m;   // 10.0 per cent
    }

    private void DiscountBox_ValueChanged(object sender, EventArgs e)
    {
        decimal discount = discountBox.Value ?? 0m;   // null while the box is empty
        totalLabel.Text = "Unit price after discount: " + (UnitPrice * (100m - discount) / 100m).ToString("C");
    }
}

See also

Members at a glance

Constructors
BinaryNumericExtendedTextInitialises an empty numeric box for whole numbers, with no range in force and stepping on.
Properties
DecimalPlacesGets or sets how many decimal places the box accepts and shows.
EnableSteppingGets or sets whether the arrow keys, the page keys and the mouse wheel step the value.
MaximumGets or sets the highest value the box accepts while ShouldIUseInputRange is true.
MinimumGets or sets the lowest value the box accepts while ShouldIUseInputRange is true.
SelectAllOnFocusGets or sets whether the text is selected when the box takes the focus, so that typing replaces the value rather than adding to it.
ShouldIUseInputRangeGets or sets whether the value is held between Minimum and Maximum.
ShowThousandsSeparatorGets or sets whether the value is shown with the current culture's grouping separators – "1,250,000" – while the box does not have the focus.
StepGets or sets how far one press of Up or Down, or one wheel notch, moves the value.
TextGets or sets the text in the box – the number as the user sees it.
ValueGets or sets the number in the box, or null when the box is empty.
Methods
BeginInitSignals the start of initialisation by the designer-generated code. It does nothing; the checks are made in EndInit.
EndInitSignals the end of initialisation by the designer-generated code, and checks the range.
OnEnterTakes the grouping separators out of the text for editing, raises the Control.Enter event, and selects the text when SelectAllOnFocus is set.
OnKeyDownSteps the value for Up, Down, Page Up and Page Down, and raises the Control.KeyDown event.
OnKeyPressLets through digits, the minus sign, editing keys such as Backspace and – when DecimalPlaces is above zero – one decimal separator, rejects every other character, and raises the Control.KeyPress event.
OnLostFocusRewrites the value the way it is read – with DecimalPlaces places and, if ShowThousandsSeparator is set, grouping separators – and then passes the event on.
OnMouseWheelSteps the value by one Step for each wheel notch while the box has the focus, and raises the Control.MouseWheel event.
OnValueChangedRaises the ValueChanged event.
StepByMoves the value up or down by the given amount, and puts the caret at the end of the text.
Events
ValueChangedOccurs when the number in the box changes – typed, pasted, stepped or assigned in code.

Constructors

BinaryNumericExtendedText

public BinaryNumericExtendedText()

Initialises an empty numeric box for whole numbers, with no range in force and stepping on.

Properties

DecimalPlaces

public int DecimalPlaces

Gets or sets how many decimal places the box accepts and shows.

Value
From 0 to 15; values outside that range are clamped. The default is 0: whole numbers only, and the decimal separator cannot be typed.
Default
0
Remarks

The separator is the current culture's – a comma in much of Europe. The number is written with exactly this many places when the box loses the focus.

EnableStepping

public bool EnableStepping

Gets or sets whether the arrow keys, the page keys and the mouse wheel step the value.

Value
true to step; the default is true.
Default
true
Remarks

StepBy works whatever this is set to.

Maximum

public int Maximum

Gets or sets the highest value the box accepts while ShouldIUseInputRange is true.

Value
The upper bound. The default is 100.
Default
100
Remarks

A value typed above the maximum is replaced with the maximum when the box loses the focus.

See also

Minimum

public int Minimum

Gets or sets the lowest value the box accepts while ShouldIUseInputRange is true.

Value
The lower bound. The default is 0.
Default
0
Remarks

The bound is not checked against Maximum when it is set; a range whose minimum is above its maximum is reported by EndInit.

A typed value is held in the range when the box loses the focus, so a value such as 15 can be typed digit by digit with a minimum of 10.

Minimum is also what the box shows after text that is not a number is assigned or pasted, whether or not the range is in force.

See also

SelectAllOnFocus

public bool SelectAllOnFocus

Gets or sets whether the text is selected when the box takes the focus, so that typing replaces the value rather than adding to it.

Value
true to select the text on entry; the default is false.
Default
false

ShouldIUseInputRange

public bool ShouldIUseInputRange

Gets or sets whether the value is held between Minimum and Maximum.

Value
true to enforce the range; the default is false.
Default
false
Remarks

Stepped and assigned values are held in the range at once, typed values when the box loses the focus. Turning the range on does not change a value already in the box.

Example
var percentBox = new BinaryNumericExtendedText
{
    Minimum = 0,
    Maximum = 100,
    ShouldIUseInputRange = true,
    Step = 5
};

ShowThousandsSeparator

public bool ShowThousandsSeparator

Gets or sets whether the value is shown with the current culture's grouping separators – "1,250,000" – while the box does not have the focus.

Value
true to group the digits; the default is false.
Default
false
Remarks

The separators are taken out while the box is being edited, so the user never types round them.

Step

public decimal Step

Gets or sets how far one press of Up or Down, or one wheel notch, moves the value.

Value
The step, greater than zero. Zero or a negative value is taken as 1. The default is 1.
Default
1
Remarks

Page Up and Page Down move ten steps.

Text

public override string Text

Gets or sets the text in the box – the number as the user sees it.

Value
The text, possibly with grouping separators while the box does not have the focus. The default is an empty string.
Remarks

Prefer Value in code. Assigning text that is not a number – an empty string included – sets the text to Minimum; assigning a number outside the range while ShouldIUseInputRange is true leaves the text unchanged.

Value

public decimal? Value

Gets or sets the number in the box, or null when the box is empty.

Value
The number, read in the current culture; null while the box is empty or holds something that is not yet a number, such as a lone minus sign. The default is null.
Remarks

Setting a value rounds it to DecimalPlaces (halves away from zero), holds it in the range when ShouldIUseInputRange is true, and writes it the way the box shows numbers. Setting null empties the box.

Example
quantityBox.Value = 12;                     // shows "12"
decimal quantity = quantityBox.Value ?? 1;  // 1 when the box was left empty

Methods

BeginInit

public void BeginInit()

Signals the start of initialisation by the designer-generated code. It does nothing; the checks are made in EndInit.

EndInit

public void EndInit()

Signals the end of initialisation by the designer-generated code, and checks the range.

Exceptions
ArgumentException
ShouldIUseInputRange is true and Minimum is greater than Maximum.

OnEnter

protected override void OnEnter(EventArgs e)

Takes the grouping separators out of the text for editing, raises the Control.Enter event, and selects the text when SelectAllOnFocus is set.

Parameters
e
The data for the event.

OnKeyDown

protected override void OnKeyDown(KeyEventArgs e)

Steps the value for Up, Down, Page Up and Page Down, and raises the Control.KeyDown event.

Parameters
e
The key pressed.
Remarks

Up and Down move by Step, the page keys by ten steps. Nothing is stepped while EnableStepping is false or the box is read-only.

OnKeyPress

protected override void OnKeyPress(KeyPressEventArgs e)

Lets through digits, the minus sign, editing keys such as Backspace and – when DecimalPlaces is above zero – one decimal separator, rejects every other character, and raises the Control.KeyPress event.

Parameters
e
The character typed. Handled is already set when a handler sees it.
Remarks

The minus sign is accepted anywhere in the text; text that does not then read as a number is replaced with Minimum.

OnLostFocus

protected override void OnLostFocus(EventArgs e)

Rewrites the value the way it is read – with DecimalPlaces places and, if ShowThousandsSeparator is set, grouping separators – and then passes the event on.

Parameters
e
The data for the event.
Remarks

While a range is in force, a typed value outside it is replaced with the nearer bound, and an empty box is refilled with the last one-character value it held, or with Minimum.

OnMouseWheel

protected override void OnMouseWheel(MouseEventArgs e)

Steps the value by one Step for each wheel notch while the box has the focus, and raises the Control.MouseWheel event.

Parameters
e
The wheel movement.
Remarks

A notch that steps the value is marked handled, so the form or panel behind the box does not scroll as well.

OnValueChanged

protected virtual void OnValueChanged(EventArgs e)

Raises the ValueChanged event.

Parameters
e
The data for the event.
Remarks

A derived class that overrides this should call the base implementation, or handlers of ValueChanged are not called.

StepBy

public void StepBy(decimal by)

Moves the value up or down by the given amount, and puts the caret at the end of the text.

Parameters
by
How far to move the value; negative to move it down.
Remarks

An empty box counts as Minimum while the range is in force, and as 0 otherwise. The result is rounded to DecimalPlaces and held in the range. This method works even when EnableStepping is false or the box is read-only.

Events

ValueChanged

public event EventHandler ValueChanged

Occurs when the number in the box changes – typed, pasted, stepped or assigned in code.

Remarks

Raised for every change of the text, including partial entries such as a lone minus sign, the box being emptied, and the reformatting when the box loses the focus. Read Value in the handler; it is null while the text is not yet a number.