NTDLS.WinFormsHelpers 1.5.0

NTDLS.WinFormsHelpers

NTDLS.WinFormsHelpers is a small NuGet package of helper utilities for Windows Forms applications. It provides thread-safe extension methods for Control, Form and ListView that remove the boilerplate around cross-thread Invoke calls, validated value accessors for TextBox controls, tooltip helpers, a spinning ActivityIndicator user control, and a ready-made ProgressForm for running work on a background thread while reporting progress to the user.

📦 Be sure to check out the NuGet package: https://www.nuget.org/packages/NTDLS.WinFormsHelpers

When to use this package

Use NTDLS.WinFormsHelpers when you are writing a WinForms app and keep running into one or more of these problems:

• Cross-thread exceptions. Updating a label, list view, or dialog from a worker thread throws InvalidOperationException. The Invoke* extension methods handle InvokeRequired for you, so the same call works whether it runs on the UI thread or not.
• Tedious input validation. You want a typed value out of a TextBox with range or length checks, and a clear error message when the user enters something invalid.
• Long-running operations. You need to run work off the UI thread while showing a progress form — including optional cancellation — without hand-rolling threads, Invokes, and synchronization.
• Polish. You want tooltips applied in bulk (with automatic text wrapping) or a lightweight spinning activity indicator.

If your app is pure console/server code, WPF, or Blazor, this package will not help you — it is strictly WinForms.

Usage examples

Thread-safe control updates

using NTDLS.WinFormsHelpers; // required for the extension methods

// Safe to call from any thread — no InvokeRequired check needed.
labelStatus.InvokeSetText("Working...");
buttonSave.InvokeDisable();          // disable while work is in flight
buttonSave.InvokeEnable();           // re-enable when done

// Close a dialog from a worker thread.
this.InvokeClose(DialogResult.OK);

// Show a message box from any thread; returns the button the user pressed.
DialogResult result = this.InvokeMessageBox("Done!", "Info", MessageBoxButtons.OK, MessageBoxIcon.Information);

ListView updates from another thread

using NTDLS.WinFormsHelpers;

// All of these are safe to call from a background thread.
listView.InvokeClearRows();                       // clear all items
listView.Items.Add(new ListViewItem("Item"));     // then populate...
listView.InvokeDeleteItem(listView.Items[0]);     // remove one item
listView.InvokeDeleteSelectedItems();             // remove everything selected
listView.InvokeClearSelection();                  // deselect all

Sorting a ListView by column

using NetTunnel.UI.Helpers; // note: the comparer lives in this namespace

var comparer = new ListViewItemComparer { SortColumn = 1, SortOrder = SortOrder.Ascending };
listView.ListViewItemSorter = comparer;
listView.Sort(); // rows now sorted by column 1, ascending

Reading and validating TextBox values

using NTDLS.WinFormsHelpers;

// Parse and range-check an integer ([min]/[max] are substituted into the message).
int port = txtPort.GetAndValidateNumeric(1, 65535, "Port must be between [min] and [max].");

// Require non-empty text; throws with your message if the box is blank.
string name = txtName.GetAndValidateText("A name is required.");

// Convert the text to any type supported by the underlying converter.
decimal price = txtPrice.ValueAs<decimal>();

All validators throw an Exception carrying your message when the value is missing or out of range.

Tooltips

using NTDLS.WinFormsHelpers;

// Create a tooltip owned by the form — it disposes itself when the form closes.
ToolTip tips = this.CreateToolTipControl();

// Apply the same (soft-wrapped) text to several controls at once.
tips.AddControls(new Control[] { btnOpen, btnSave, btnCancel },
                 "Performs the action after validating all inputs.", wrapLength: 40);

ProgressForm for background work

using NTDLS.WinFormsHelpers;

// Runs the worker on a background thread, shows the progress form,
// and closes it automatically when the worker finishes.
var progress = new ProgressForm("Exporting", "Please wait", "Building the report...");
progress.Execute(sender =>
{
    for (int i = 0; i < 100; i++)
    {
        DoWork(i);
        sender.SetProgressValue(i + 1);   // thread-safe progress update
        if (sender.IsCancelPending) break; // honor the Cancel button
    }
});
progress.Dispose();

There are async variants too (ExecuteAsync) and overloads that return a result:

// Fire-and-forget async work.
await progress.ExecuteAsync(async sender =>
{
    await Task.Delay(2000);
});

// Async work that returns a value.
string result = await progress.ExecuteAsync<string>(async sender =>
{
    return await GenerateReportAsync(sender);
});

You can also drive the form manually via ShowDialog(...), SetHeaderText, SetBodyText, IncrementProgressValue, SetCanCancel, and the OnCancel event.

ActivityIndicator control

using NTDLS.WinFormsHelpers.Controls;

var spinner = new ActivityIndicator
{
    AutoIncrement = true,            // rotate automatically
    AutoIncrementFrequency = 80      // milliseconds per step
};
spinner.ActiveSegmentColor = Color.SteelBlue;
form.Controls.Add(spinner);

License

MIT