Text Customization and Styling Options

A feature that allows developers to control how the numerical words are formatted and styled, including negative number notation and casing preferences.

Overview

The Text Customization & Styling Options feature provides properties that enable developers to fine-tune the appearance and style of the converted text. This includes setting a custom prefix for negative numbers, controlling the casing of the output text, inserting "and" in hundreds as per style preferences, converting cardinal numbers to ordinal words, and optionally formatting numbers as Roman numerals.

---

Key Points

Aspect	Description
Negative Number Prefix	Use the NegativePrefix property to define the introductory text for negative numbers (e.g., "minus" or "negative").
Output Casing	Use the OutputCasing property to specify the text casing (Upper, Lower, or Title) for the converted words.
Inserting "and" in Hundreds	The UseAndInHundreds property controls whether the conjunction "and" appears between hundreds and tens (e.g., "one hundred and twenty").
Ordinal Conversion	The UseOrdinal property transforms cardinal numbers into their ordinal counterparts (e.g., "one" becomes "first").
Roman Numerals	The UseRomanNumerals property converts numbers into their ancient Roman numeral representations when enabled.

Code Example

// Initialize the control for text customization
var humanizer = new SiticoneHumanizerInt();

// Set negative number prefix to "negative" instead of the default "minus"
humanizer.NegativePrefix = "negative";

// Set the output casing to Upper
humanizer.OutputCasing = Casing.Upper;

// Enable insertion of "and" between hundreds and tens
humanizer.UseAndInHundreds = true;

// Enable ordinal conversion for a more descriptive representation
humanizer.UseOrdinal = true;

// Optionally, convert numbers to Roman numerals by enabling this flag
humanizer.UseRomanNumerals = false; // Set to true to enable Roman numeral conversion

---

Best Practices

Practice	Recommendation
Consistent Styling	Choose a consistent style (casing, negative prefix, ordinal or cardinal) across your application to maintain a uniform user interface.
Testing Variations	Test different combinations of the styling options to ensure that the final output meets the application's design requirements.
Dynamic Updates	Changing styling properties (such as NegativePrefix or OutputCasing) will force an update on the Number property, so plan accordingly if updates are dynamic.

Code Example

// Example: Switching output casing dynamically in response to user selection
void UpdateTextStyle(Casing selectedCasing)
{
    humanizer.OutputCasing = selectedCasing;
    // Reset the number to force an update in the styling
    humanizer.Number = humanizer.Number;
}

---

Common Pitfalls

Pitfall	Explanation
Inconsistent Casing	Changing the casing without resetting the number property may not update the text output immediately.
Invalid Negative Prefix	Setting an empty or null string to NegativePrefix will throw an exception; ensure the prefix is always a valid non-empty string.
Overlapping Features	Enabling both UseOrdinal and UseRomanNumerals may lead to unexpected outputs; choose one representation style that suits the context.

Code Example

// Incorrect: Attempting to set an invalid NegativePrefix
try
{
    humanizer.NegativePrefix = "";
}
catch (ArgumentException ex)
{
    Console.WriteLine("Invalid NegativePrefix: " + ex.Message);
}

---

Usage Scenarios

Scenario	How It Works
Negative Number Display	When displaying negative numbers, the NegativePrefix property allows customization of how negatives are represented.
Customized Text Appearance	Use OutputCasing to control whether the conversion output is in Upper, Lower, or Title case, based on application design guidelines.
Detailed Numerical Descriptions	By enabling UseOrdinal, numbers are converted to their ordinal forms, useful for ranking or descriptive text in reports or educational apps.
Historical Presentation	When required, enable UseRomanNumerals to show numbers in their Roman numeral form, adding a historical or stylistic flavor to the UI.

Code Example

// Scenario: Customizing the display of a negative number with ordinal styling
humanizer.NegativePrefix = "negative";
humanizer.OutputCasing = Casing.Title;
humanizer.UseOrdinal = true;
humanizer.Number = -45;
Console.WriteLine("Styled conversion: " + humanizer.Words);

---

Real Life Usage Scenarios

Scenario	Explanation
Educational Software	Use ordinal conversion to display number sequences (first, second, third) to assist students learning number concepts.
Financial Reporting	Customize negative number representation (e.g., using "negative" and proper casing) to clearly indicate deficits or losses in reports.
Thematic Applications	In historical or themed applications, enabling Roman numeral conversion provides a unique presentation style for dates or chapters.

Code Example

// Example: In an educational app, convert a number to its ordinal word representation
humanizer.UseOrdinal = true;
humanizer.OutputCasing = Casing.Title;
humanizer.Number = 7;
Console.WriteLine("Ordinal representation: " + humanizer.Words); // Expected output: "Seventh"

---

Troubleshooting Tips

Tip	Details
Verify Property Changes	After modifying any styling property, ensure that the number is reset (or updated) so that the changes reflect in the output.
Debugging Output	Use debugging statements to verify that the correct properties are set before conversion, ensuring that the final output matches the desired style.
Handle Exceptions	Implement try-catch blocks around property updates to catch exceptions from invalid values (e.g., setting an empty NegativePrefix).

Code Example

// Example: Troubleshooting property update
try
{
    humanizer.NegativePrefix = "negative";
    humanizer.Number = -100;
    Console.WriteLine("Conversion output: " + humanizer.Words);
}
catch (Exception ex)
{
    Console.WriteLine("Error encountered during text styling: " + ex.Message);
}

---

Review

Aspect	Consideration
Flexibility	The feature allows a high degree of customization, accommodating various presentation needs (casing, ordinal, negative prefix, and historical numeral options).
Integration Complexity	Simple property assignments and event-triggered updates make integration straightforward.
Potential Overlap	Developers should be cautious when enabling multiple conversion modes (e.g., ordinal and Roman numeral) simultaneously, as they may conflict in output formatting.

---

Summary

Summary Point	Description
Customizable Output	Developers can control the style and formatting of number-to-word conversions using several customizable properties.
Event-Driven Updates	Changes to styling properties trigger an update on the conversion output, ensuring the UI reflects the latest settings.
Developer-Friendly	Clear property names and straightforward usage scenarios make it easy to integrate this feature into WinForms applications.

Final Integration Example

using System;
using SiticoneNetFrameworkUI;

namespace DemoTextCustomization
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize the humanizer control
            var humanizer = new SiticoneHumanizerInt();

            // Subscribe to conversion events
            humanizer.OnNumbersChanged += (sender, e) =>
            {
                Console.WriteLine($"Conversion update: {e.Words}");
            };

            humanizer.OnError += (sender, e) =>
            {
                Console.WriteLine($"Error: {e.Exception.Message}");
            };

            // Set styling properties for a customized output
            humanizer.NegativePrefix = "negative";
            humanizer.OutputCasing = Casing.Title;
            humanizer.UseAndInHundreds = true;
            humanizer.UseOrdinal = true;
            humanizer.UseRomanNumerals = false;

            // Convert a negative number with the custom styles
            humanizer.Number = -256;
            Console.WriteLine("Final conversion result: " + humanizer.Words);
        }
    }
}

---

This comprehensive documentation should provide developers with clear guidance on using and integrating the Text Customization & Styling Options feature within their applications, including key points, best practices, and troubleshooting tips for a smooth integration experience.