WiseProgress.Framework 2026.5.16.1

WiseProgress.FrameworkCore (.NET 8)

A Windows Forms framework library targeting .NET 8.
Namespace root: WiseProgress

This project is the .NET 8 equivalent of WiseProgress.Framework.
All classes, properties, and methods are identical unless noted below.

---

Table of Contents

1. EnvironmentSettings
2. Controls
   • TextBoxW
   • ComboBoxW
   • NumericBox
   • NumericLabel
3. Grid & Columns
   • WiseDataGridView
   • WiseDataGridViewRow
   • WiseCellValue
   • AdvancedHelpCellValue
   • WiseAdvancedHelpColumn
   • WiseDataGridViewDoubleColumn
   • WiseDataGridViewCalendarColumn
   • WiseDataGridViewTextColumn
   • DataGridViewRolloverCellColumn
4. UI Dialogs
   • MessageBox
   • CustomizedMessageBox
   • InputBox
   • Notification
5. Security
   • Cryptography
6. Net
   • Email

---

EnvironmentSettings

Namespace: (root)
Inherits: Component

A singleton component that holds global application settings consumed by controls and dialogs.

Shared Members

Member	Type	Description
DefaultInstance	EnvironmentSettings (ReadOnly)	Returns the active singleton. Auto-created if not set
UseInstance(instance)	Method	Replaces the global singleton with a custom instance

Properties

Property	Type	Default	Category	Description
ConnectionString	String	""	Database Settings	ADO.NET connection string
ConnectionInfo	ConnectionInfo	Nothing	—	Typed connection info object
SqlConnnection	SqlConnection	Nothing	—	Reusable SQL connection object
DateFormat	String	Nothing	Regional Settings	Date format for grid date columns. E.g. "dd-MM-yyyy", "d". Empty = system default
NumberFormat	String	Nothing	Regional Settings	Number format for grid numeric columns. E.g. "N2", "#,##0.00". Empty = "N2"
RightToLeft	Boolean	False	UI Settings	When True, all dialogs render right-to-left. Set automatically by CurrentLanguage
CurrentLanguage	DialogLanguage	Nothing	—	Active dialog language. Setting it also updates RightToLeft
Languages	List(Of DialogLanguage)	EN, AR, FR	—	Available languages. Add custom DialogLanguage instances here

Methods

Method	Signature	Description
SetLanguage	(languageName As String)	Activates a language from Languages by name (case-insensitive)
CreateConnection	() As SqlConnection	Opens and returns a new SqlConnection. Throws if ConnectionString is empty

Example

Dim env As New EnvironmentSettings()
env.ConnectionString = "Server=.;Database=MyDB;Integrated Security=True"
env.NumberFormat = "N2"
env.DateFormat = "dd/MM/yyyy"
env.SetLanguage("Arabic")

---

Controls

TextBoxW

Namespace: WiseProgress.Controls
Inherits: System.Windows.Forms.TextBox

A text box with built-in validation, watermark (cue banner), colored border feedback, and an error provider.

Properties

Property	Type	Default	Description
CueBanner	String	"Watermark"	Placeholder text shown when empty
IsRequired	Boolean	False	When True, IsValid() fails on empty
ValidationString	String	"*"	Regex pattern. "*" = accept any text
BorderColor	Color	Gray	Current border color. Turns red on failure
ErrorMessageEmptyField	String	"Empty TextBox"	Error shown when the field is empty and required
ErrorMessageRegexFail	String	"Incorrect format"	Error shown when regex fails
ErrorIcon	Icon	system default	Error provider icon
ErrorIconPosition	ErrorIconAlignment	MiddleRight	Error icon alignment
ErrorIconPadding	Integer	2	Pixels between control edge and error icon

Methods

Method	Signature	Description
IsValid	() As Boolean	Validates the field. Sets border and error provider
ClearError	()	Removes error icon and resets border color

---

ComboBoxW

Namespace: WiseProgress.Controls
Inherits: System.Windows.Forms.ComboBox

A combo box with validation, colored border feedback, and an error provider.

Properties

Property	Type	Default	Description
IsRequired	Boolean	False	Fails validation when no item is selected
BorderColor	Color	Gray	Current border color
ErrorMessageEmptyField	String	"Empty TextBox"	Error shown when required and empty
ErrorIcon	Icon	system default	Error provider icon
ErrorIconPosition	ErrorIconAlignment	MiddleRight	Error icon alignment
ErrorIconPadding	Integer	2	Icon padding in pixels

Methods

Method	Signature	Description
IsValid	() As Boolean	Returns True if not required, or if required and has a value
ClearError	()	Removes error icon and resets border

---

NumericBox

Namespace: WiseProgress.Controls
Inherits: TextBoxW

A text box restricted to numeric input with min/max, decimal control, and a ValueChanged event.

Properties

Property	Type	Default	Description
AllowDecimal	Boolean	True	Allows decimal input
AllowNegative	Boolean	False	Allows negative values
DecimalPlaces	Integer	2	Decimal places enforced on LostFocus
MinValue	Decimal	Decimal.MinValue	Minimum allowed value
MaxValue	Decimal	Decimal.MaxValue	Maximum allowed value
IsEmpty	Boolean (ReadOnly)	—	True when text is empty

Events

Event	Description
ValueChanged	Raised on LostFocus when value changes

Methods

Method	Signature	Description
GetNumericValue	() As Decimal?	Returns parsed value or Nothing if empty/invalid

---

NumericLabel

Namespace: WiseProgress.Controls
Inherits: Label

A read-only label for displaying a Double with formatting, sign-based coloring, prefix/suffix support.

Properties

Property	Type	Default	Category	Description
Value	Double	0	Numeric	The number to display
Format	String	"N2"	Numeric	Format string. Falls back to EnvironmentSettings.NumberFormat then "N2"
Prefix	String	""	Numeric	Text prepended to the formatted value
Suffix	String	""	Numeric	Text appended to the formatted value
PositiveColor	Color	Color.Empty	Numeric	ForeColor for positive values. Empty = default ForeColor
NegativeColor	Color	Red	Numeric	ForeColor for negative values
ZeroColor	Color	Color.Empty	Numeric	ForeColor for zero. Empty = default ForeColor
ShowPositiveSign	Boolean	False	Numeric	Prepends "+" for positive values
Text	String	—	—	Read-only at runtime. Set Value instead
AutoSize	Boolean	False	—	Default overridden to False

---

Grid & Columns

WiseDataGridView

Namespace: WiseProgress.UI.Grid
Inherits: System.Windows.Forms.DataGridView

Properties

Property	Type	Default	Description
ShowRowNumber	Boolean	False	Draws sequential row numbers in the row header
ProcessEnterAsTab	Boolean	True	Treats Enter key as Tab
ConnectionInfo	ConnectionInfo	Nothing	Connection info passed to advanced help columns
PropertyColumnMap	Dictionary(Of String, String)	empty	Maps class property names to column names
LinkedClassType	Type	Nothing	Auto-creates text columns for each property of the type when set
VirtualProperties	HashSet(Of String)	empty	Property names stored per-row without a visible column
DeletedVirtualValues	List(Of Dictionary(Of String, Object))	empty	Virtual value snapshots of user-deleted rows. Cleared on SetList

Methods

Method	Signature	Description
AddRow	() As Integer	Adds one empty row. Returns last row index
AddRow	(count As Integer) As Integer	Adds count rows. Returns last row index
SetPropertyColumnMap	(propertyName, columnName)	Maps a class property name to a grid column name
LinkClass(Of T)	()	Registers type T (no-op; use SetPropertyColumnMap directly)
AddVirtualProperty	(ParamArray names() As String)	Registers property names as virtual (hidden, no column)
SetList(Of T)	(items As List(Of T))	Fills the grid from a list. Clears DeletedVirtualValues
GetList(Of T)	() As List(Of T)	Reads all remaining rows into a typed list
GetDeletedList(Of T)	() As List(Of T)	Returns deleted rows with their virtual values restored
FilterRows	(searchText As String)	Hides non-matching rows, highlights matches in yellow
SetAdvancedHelp	(rowIndex, columnIndex, guid, ParamArray strings())	Sets an advanced help cell by index
SetAdvancedHelp	(rowIndex, columnName, guid, ParamArray strings())	Sets an advanced help cell by column name
SetAdvancedHelp	(row, columnName, guid, ParamArray strings())	Sets an advanced help cell using a row reference
AdvancedHelpCellValue	(rowIndex, columnIndex) As WiseCellValue	Gets the cell wrapper by index
AdvancedHelpCellValue	(rowIndex, columnName) As WiseCellValue	Gets the cell wrapper by column name
AdvancedHelpCellValue	(row, columnName) As WiseCellValue	Gets the cell wrapper using a row reference

SetList / GetList Behaviour

Property type	Has column?	Stored in	Survives row deletion?
Column-bound	✅ Yes	Cell value	❌ No
Virtual	❌ No	VirtualValues on row	✅ Yes (via GetDeletedList)

Typical Setup

' 1. Map columns to class properties
myGrid.SetPropertyColumnMap(NameOf(MyItem.Pack),      colPack.Name)
myGrid.SetPropertyColumnMap(NameOf(MyItem.Pricelist),  colPricelist.Name)
myGrid.SetPropertyColumnMap(NameOf(MyItem.PriceHT),    colPriceHT.Name)

' 2. Register virtual (hidden) properties
myGrid.AddVirtualProperty(
	NameOf(MyItem.Id),           ' Guid
	NameOf(MyItem.CreatedDate),  ' DateTime
	NameOf(MyItem.Version)       ' Integer
)

' 3. Load
myGrid.SetList(myRepo.GetItems())

' 4. Save
Dim remaining = myGrid.GetList(Of MyItem)()
Dim deleted   = myGrid.GetDeletedList(Of MyItem)()

For Each item In remaining
	myRepo.Save(item)
Next
For Each item In deleted
	myRepo.Delete(item.Id)
Next

---

WiseDataGridViewRow

Namespace: WiseProgress.UI.Grid
Inherits: DataGridViewRow

Member	Type	Description
VirtualValues	Dictionary(Of String, Object)	Per-row virtual property storage
AdvancedHelpCellValue(columnIndex)	WiseCellValue	Gets the cell wrapper by column index
AdvancedHelpCellValue(columnName)	WiseCellValue	Gets the cell wrapper by column name
SetAdvancedHelp(columnIndex, guid, strings())	Method	Assigns Guid + code/name to a help cell
SetAdvancedHelp(columnName, guid, strings())	Method	Same, by column name

---

WiseCellValue

Wrapper around AdvancedHelpCell for reading/writing its values.

Member	Type	Description
AdvancedHelpCell	AdvancedHelpCell	The underlying cell
SelectedGuid	Guid	Selected Guid value
SelectedCode	String	Selected code string
SelectedName	String	Selected name string
ToAdvancedHelpCell()	Method	Returns the raw AdvancedHelpCell
AssignValue(guid, value)	Method	Assigns Guid and a single value
AssignValue(guid, ParamArray strings())	Method	Assigns Guid with optional code and name

---

AdvancedHelpCellValue

Plain data container for advanced help cell binding via SetList/GetList.

Property	Type	Default	Description
Guid	Guid	Guid.Empty	Primary identifier
SelectedGuid	Guid	—	Alias for Guid
SelectedCode	String	""	Code part
SelectedName	String	""	Display name part

---

WiseAdvancedHelpColumn

Namespace: WiseProgress.UI.Grid
Inherits: DataGridViewColumn

A popup search column. Clicking the cell opens a lookup form to select a Guid + code + name.

Property	Type	Default	Description
TableName	String	""	Source table for the lookup
FieldCode	String	""	Code column name
FieldName	String	""	Name/description column name
FieldGuid	String	""	Guid column name
SelectCondition	String	""	Optional SQL WHERE clause
ConnectionInfo	ConnectionInfo	from EnvironmentSettings	Database connection

---

WiseDataGridViewDoubleColumn

Namespace: WiseProgress.UI.Grid
Inherits: DataGridViewColumn

A numeric column that formats values and parses math expressions on input.

Property	Type	Default	Description
Format	String	"N2"	Display format. Falls back to EnvironmentSettings.NumberFormat then "N2"

---

WiseDataGridViewCalendarColumn

Namespace: WiseProgress.UI.Grid
Inherits: DataGridViewColumn

A date column backed by a DateTimePicker editing control.

Property	Type	Default	Description
DataField	String	""	Bound data field name
Format	String	"d"	Date format. Falls back to EnvironmentSettings.DateFormat then "d"

---

WiseDataGridViewTextColumn

Namespace: WiseProgress.UI.Grid
Inherits: DataGridViewColumn

A plain text column with a custom editing control.

Property	Type	Default	Description
DataField	String	""	Bound data field name

---

DataGridViewRolloverCellColumn

Namespace: WiseProgress.UI.Grid
Inherits: DataGridViewColumn

Cells draw an orange border rectangle on mouse hover. No additional properties.

---

UI Dialogs

MessageBox

Namespace: WiseProgress.UI

A styled modal dialog replacing the standard MsgBox.

MessageBox.Show(Title, Message,
	Optional type As enmType = Info,
	Optional Buttons As MessageBoxButtons = OK,
	Optional FontSize As Integer = 10) As DialogResult

enmType

Value	Meaning
Success	Operation completed successfully
Warning	Caution needed
Error	Operation failed
Info	Informational

Example

Dim r = WiseProgress.UI.MessageBox.Show(
	"Confirm", "Delete this record?",
	WiseProgress.UI.MessageBox.enmType.Warning,
	MessageBoxButtons.YesNo)
If r = DialogResult.Yes Then ...

---

CustomizedMessageBox

Namespace: WiseProgress.UI

A message box with fully custom button labels. Returns the text of the clicked button.

' String buttons
CustomizedMessageBox.Show(Title, Message, ParamArray button() As String) As String

' With default button
CustomizedMessageBox.Show(Title, Message, DefaultButton As String, ParamArray button() As String) As String

' With Button objects
CustomizedMessageBox.Show(Title, Message, DefaultButton As String, Buttons As List(Of Button)) As String

Button Class

Property	Type	Description
Text	String	Label on the button
Value	String	Value returned when clicked

---

InputBox

Namespace: WiseProgress.UI

A simple text input dialog.

Properties

Property	Type	Description
Value	String	Text entered by the user

Methods

ShowDialogBox(PromptMessage As String,
	Optional Title As String = "",
	Optional DefaultValue As String = "",
	Optional PasswordBox As Boolean = False) As DialogResult

Example

Dim box As New WiseProgress.UI.InputBox()
If box.ShowDialogBox("Enter name:") = DialogResult.OK Then
	Dim name = box.Value
End If

---

Notification

Namespace: WiseProgress.UI

A non-blocking toast notification.

Notification.ShowNotification(msg As String, type As enmType)

enmType: Success · Warning · Error · Info

---

Security

Cryptography

Namespace: WiseProgress.Security
Implements: IDisposable

AES (Rijndael CBC) encryption/decryption.

Properties

Property	Type	Default	Description
Key	String	""	Encryption key. SHA-256 hashed internally

Constructors

New()
New(CryptKey As String)

Methods

Method	Returns	Description
EncryptText(plaintext)	String	Encrypts to Base64 (IV + ciphertext)
DecryptText(ciphertext)	String	Decrypts from Base64

Example

Using c As New WiseProgress.Security.Cryptography("MySecretKey")
	Dim enc = c.EncryptText("Hello")
	Dim dec = c.DecryptText(enc) ' "Hello"
End Using

---

Net

Email

Namespace: WiseProgress.Net
Implements: IDisposable

SMTP email sender with multi-recipient and attachment support.

Properties

Property	Type	Default	Description
FromEmail	String	""	Sender address
ToEmail	List(Of String)	Nothing	Recipient addresses
SmtpServer	String	""	SMTP host
Port	Integer	587	SMTP port
EnableSSL	Boolean	True	Use SSL/TLS
SmtpUser	String	""	SMTP username
SmtpPassword	String	""	SMTP password
Subject	String	""	Subject line
Body	String	""	Email body
IsBodyHtml	Boolean	False	HTML body flag
Attachments	List(Of String)	Nothing	File paths to attach

Events

Event	Description
SendingError(e As Exception)	Fired on failure
SendingCompleted()	Fired on success

Methods

SendEmail()   ' Uses instance properties

SendEmail(FromEmail, ToEmail As String, SmtpServer, Port, EnableSSL,
		  SmtpUser, SmtpPassword, Subject, Body, IsBodyHtml, Attachments)

SendEmail(FromEmail, ToEmail As List(Of String), SmtpServer, Port, EnableSSL,
		  SmtpUser, SmtpPassword, Subject, Body, IsBodyHtml, Attachments)