Display Options

Display Options allow developers to control how progress information is visually presented, including the display of percentage text, text formatting, and text alignment within the control.

Overview

This section details the customization options related to the textual display of progress information. Developers can enable or disable the percentage display, customize the numeric format, and align the text to enhance clarity and match the application's design.

---

Properties and Methods

The table below summarizes the key properties that influence the display of progress information:

Property	Type	Default Value	Description
ShowPercentage	bool	false	Determines whether the progress percentage is displayed as text over the control.
FormatString	string	"0"	Specifies the numeric format used when rendering the progress percentage (e.g., "0" for integers).
TextAlignment	ContentAlignment	MiddleCenter	Sets the alignment of the percentage text within the control (e.g., TopLeft, MiddleCenter, BottomRight).

Note: Changing these properties triggers an Invalidate() call, causing the control to refresh and display the updated text formatting and alignment immediately.

---

Code Examples and Samples

Below are extensive code examples demonstrating how to integrate and utilize the Display Options features.

Example 1: Enabling Percentage Display

This example shows how to enable the display of the progress percentage and customize the format.

// Instantiate the progress bar control
SiticoneVBarsProgress progressBar = new SiticoneVBarsProgress
{
    Location = new System.Drawing.Point(50, 50),
    Size = new System.Drawing.Size(30, 200),
    Minimum = 0,
    Maximum = 100,
    Value = 45,
    
    // Enable percentage display and set a custom format
    ShowPercentage = true,
    FormatString = "0"  // Display as an integer percentage
};

// Add the control to the form
this.Controls.Add(progressBar);

Example 2: Customizing Text Alignment

This sample demonstrates how to adjust the text alignment for the displayed percentage to better fit various UI layouts.

// Set up the progress bar control
SiticoneVBarsProgress progressBar = new SiticoneVBarsProgress
{
    Location = new System.Drawing.Point(100, 50),
    Size = new System.Drawing.Size(30, 200),
    Minimum = 0,
    Maximum = 100,
    Value = 70,
    
    // Enable the percentage display
    ShowPercentage = true,
    
    // Set the text alignment to BottomRight
    TextAlignment = ContentAlignment.BottomRight
};

// Add the control to the form
this.Controls.Add(progressBar);

Example 3: Dynamic Update of Display Options

This example illustrates how to dynamically update display options in response to user interaction.

// Assume a button click event triggers the update
private void btnUpdateDisplayOptions_Click(object sender, EventArgs e)
{
    // Toggle the display of percentage text
    progressBar.ShowPercentage = !progressBar.ShowPercentage;
    
    // Update the text format to include one decimal place when enabled
    progressBar.FormatString = progressBar.ShowPercentage ? "0.0" : "0";
    
    // Cycle through different text alignments
    if (progressBar.TextAlignment == ContentAlignment.MiddleCenter)
    {
        progressBar.TextAlignment = ContentAlignment.TopCenter;
    }
    else if (progressBar.TextAlignment == ContentAlignment.TopCenter)
    {
        progressBar.TextAlignment = ContentAlignment.BottomCenter;
    }
    else
    {
        progressBar.TextAlignment = ContentAlignment.MiddleCenter;
    }
    
    // Refresh the control to reflect changes
    progressBar.Invalidate();
}

---

Key Points

Key Point	Details
Percentage Visibility	Use ShowPercentage to toggle the display of progress information as text, ensuring it complements the visual design of the control.
Numeric Format	FormatString allows precise control over how numeric values are displayed, which is essential for meeting design or localization requirements.
Text Alignment	Adjust TextAlignment to position the progress text in a way that best suits the layout and usability of your application.

---

Best Practices

Best Practice	Recommendation
Consistent Formatting	Use a consistent FormatString across the application to maintain a uniform presentation of progress values.
Test Across Layouts	Verify that the chosen TextAlignment works well with different control sizes and container layouts to ensure the text is always readable and well-placed.
Conditional Display	Consider toggling ShowPercentage based on user preference or context (e.g., enabling it only for detailed views) to keep the UI uncluttered when necessary.

---

Common Pitfalls

Common Pitfall	Solution
Overlapping Text	Ensure that the control’s dimensions and text alignment settings do not cause the percentage text to overlap with the progress indicator graphics.
Misleading Format Values	Setting an inappropriate FormatString (e.g., a format that shows excessive decimals) can lead to misleading progress information; choose a format that suits the context.
Ignoring Refresh Calls	Failing to call Invalidate() after updating Display Options may result in outdated visuals; always refresh the control to apply changes immediately.

---

Usage Scenarios

Scenario	Description	Sample Code Snippet
Detailed Progress Reporting	In data-intensive applications, display the percentage to provide users with detailed feedback on progress (e.g., during long-running operations).	progressBar.ShowPercentage = true; progressBar.FormatString = "0.0";
Minimalistic UI Design	For applications with a minimalist design, disable the percentage display to avoid clutter and focus solely on the graphical representation.	progressBar.ShowPercentage = false;
Adaptive Text Positioning	In responsive applications, adjust the TextAlignment dynamically based on available space or container orientation to maintain readability.	See Example 3 for dynamic text alignment adjustments.

---

Review

Display Options offer flexible control over how progress information is presented as text. With the ability to toggle the visibility of the percentage, customize the numeric format, and adjust the text alignment, developers can create a progress indicator that is both informative and visually integrated with the overall application design.

---

Summary

Display Options in the control provide:

• The ability to show or hide the progress percentage using ShowPercentage.

• Customizable numeric formatting through FormatString.

• Flexible text positioning via TextAlignment.

These features enhance the clarity and usability of progress information, allowing developers to tailor the control to meet diverse design and functional requirements in .NET WinForms applications.

---

Additional Sections

Integration Tips

Tip	Details
Test Format on Multiple Resolutions	Ensure that the selected FormatString displays correctly on various screen sizes and resolutions for consistent user experience.
Combine with Other Features	Leverage Display Options in combination with Color and Appearance settings for a cohesive look that matches the application’s overall design.
Utilize Event Feedback	Consider using ProgressChanged or AnimationCompleted events to update Display Options dynamically, reflecting changes in the underlying progress state.

Demo Application Sample

Below is a complete sample demonstrating the integration of Display Options features in a basic WinForms application.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace DemoApplication
{
    public partial class MainForm : Form
    {
        private SiticoneVBarsProgress progressBar;

        public MainForm()
        {
            InitializeComponent();
            InitializeProgressBar();
            InitializeDisplayOptionsButton();
        }

        private void InitializeProgressBar()
        {
            // Instantiate and configure the progress bar control
            progressBar = new SiticoneVBarsProgress
            {
                Location = new Point(50, 50),
                Size = new Size(30, 200),
                Minimum = 0,
                Maximum = 100,
                Value = 55,
                
                // Enable percentage display and set default text options
                ShowPercentage = true,
                FormatString = "0",
                TextAlignment = ContentAlignment.MiddleCenter
            };

            // Add the control to the form
            this.Controls.Add(progressBar);
        }

        private void InitializeDisplayOptionsButton()
        {
            // Button to toggle display options dynamically
            Button btnToggleDisplay = new Button
            {
                Text = "Toggle Display Options",
                Location = new Point(100, 50),
                Size = new Size(160, 30)
            };

            btnToggleDisplay.Click += (sender, e) =>
            {
                // Toggle percentage display and cycle through text alignments
                progressBar.ShowPercentage = !progressBar.ShowPercentage;
                progressBar.FormatString = progressBar.ShowPercentage ? "0.0" : "0";

                if (progressBar.TextAlignment == ContentAlignment.MiddleCenter)
                {
                    progressBar.TextAlignment = ContentAlignment.TopLeft;
                }
                else if (progressBar.TextAlignment == ContentAlignment.TopLeft)
                {
                    progressBar.TextAlignment = ContentAlignment.BottomRight;
                }
                else
                {
                    progressBar.TextAlignment = ContentAlignment.MiddleCenter;
                }

                // Refresh the control to apply the new settings
                progressBar.Invalidate();
            };

            this.Controls.Add(btnToggleDisplay);
        }
    }
}

This demo application illustrates how to initialize the control with specific display options and dynamically adjust them in response to user actions.

---

By following this comprehensive guide, developers can effectively leverage Display Options to create a progress indicator that not only conveys accurate progress information but also integrates seamlessly with the application's visual design.