Shadow & Elevation Effects

This feature enables developers to add depth and realism to the control by applying shadows and material design-inspired elevation levels.

Overview

The Shadow and Elevation Effects feature provides properties to control the depth, opacity, and color of the shadow cast by the SiticoneContainer control, as well as a material design elevation level that automatically maps to shadow properties. Developers can enhance the visual hierarchy and create a sense of depth in their applications by adjusting properties such as ShadowDepth, ShadowOpacity, ShadowColor, and Elevation.

---

Key Points

Property	Description	Default Value
ShadowDepth	Determines the distance (in pixels) the shadow extends from the control.	10
ShadowOpacity	Sets the opacity of the shadow, with values ranging from 0 (transparent) to 255 (fully opaque).	3
ShadowColor	Specifies the color of the shadow that is rendered.	Black
Elevation	Defines the material design elevation level (0–24) which automatically adjusts ShadowDepth and ShadowOpacity.	0

---

Best Practices

Practice	Description
Align elevation with design guidelines	Use the Elevation property to follow material design standards, ensuring shadows and depth are consistent across the UI.
Test across different backgrounds	Verify that the shadow’s color and opacity provide sufficient contrast on various backgrounds to maintain visual clarity.
Use subtle shadows for minimal elevation	Lower elevation values should produce gentle shadows to avoid overpowering the design, while higher values create more dramatic effects.

---

Common Pitfalls

Pitfall	Description	Recommendation
Overusing high elevation values	High elevation can create an exaggerated shadow that may distract from the primary content.	Use moderate elevation levels that complement the overall design.
Inconsistent shadow settings across controls	Inconsistent shadow properties may lead to a disjointed appearance within the application.	Standardize shadow and elevation values for a uniform look.
Ignoring the interplay between shadow color and opacity	A mismatched combination of ShadowColor and ShadowOpacity may result in either an invisible or overly dominant shadow effect.	Adjust both properties in tandem for balanced visual impact.

---

Usage Scenarios

Scenario	Description	Example Use Case
Standard Panel Design	Apply a moderate shadow to standard panels to provide a subtle lift from the background.	Use a low Elevation value to produce a gentle, realistic shadow effect.
Highlighting Active Components	Increase the elevation of an active or focused control to draw user attention through a pronounced shadow.	Temporarily raise Elevation on a control when it gains focus.
Material Design Theming	Utilize the Elevation property to adhere to material design principles across an application’s UI.	Map elevation levels to predefined shadow depths and opacities for consistency.

---

Code Examples

Example 1: Basic Shadow Customization

This example shows how to customize the shadow of the SiticoneContainer control by directly setting the ShadowDepth, ShadowOpacity, and ShadowColor properties.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Ensure the correct namespace is referenced

public class ShadowForm : Form
{
    public ShadowForm()
    {
        // Create an instance of the SiticoneContainer control
        SiticoneContainer container = new SiticoneContainer
        {
            Size = new Size(300, 200),
            Location = new Point(20, 20),
            // Set shadow properties directly
            ShadowDepth = 15,
            ShadowOpacity = 100,
            ShadowColor = Color.Gray
        };

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

    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new ShadowForm());
    }
}

Example 2: Material Design Elevation

This example demonstrates how to use the Elevation property to automatically adjust the shadow’s depth and opacity following material design principles.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Ensure the correct namespace is referenced

public class ElevationForm : Form
{
    public ElevationForm()
    {
        // Create an instance of the SiticoneContainer control
        SiticoneContainer container = new SiticoneContainer
        {
            Size = new Size(300, 200),
            Location = new Point(30, 30),
            // Set the material design elevation level (values between 0 and 24)
            Elevation = 4 // This will internally set ShadowDepth and ShadowOpacity based on the mapping
        };

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

    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new ElevationForm());
    }
}

Example 3: Dynamic Elevation Change

This example shows how to dynamically change the elevation of the control (and thereby its shadow properties) in response to a user action.

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

public class DynamicElevationForm : Form
{
    private SiticoneContainer container;
    private Button elevationButton;

    public DynamicElevationForm()
    {
        container = new SiticoneContainer
        {
            Size = new Size(300, 200),
            Location = new Point(20, 20),
            Elevation = 2 // Initial elevation level
        };

        elevationButton = new Button
        {
            Text = "Increase Elevation",
            Location = new Point(20, 240)
        };

        elevationButton.Click += ElevationButton_Click;

        this.Controls.Add(container);
        this.Controls.Add(elevationButton);
    }

    private void ElevationButton_Click(object sender, EventArgs e)
    {
        // Increase the elevation level dynamically
        if (container.Elevation < 24)
        {
            container.Elevation += 2;
        }
    }

    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new DynamicElevationForm());
    }
}

---

Review

Aspect	Notes
Visual Depth	Provides a realistic shadow effect that adds depth to the control, enhancing the overall UI experience.
Consistency	The Elevation property ensures consistent mapping between elevation levels and shadow properties.
Ease of Implementation	Simple property adjustments and dynamic elevation changes facilitate easy integration into diverse applications.

---

Summary

The Shadow and Elevation Effects feature allows developers to create depth and dimension within the SiticoneContainer control through customizable shadow properties and a material design-based elevation system. By adjusting properties such as ShadowDepth, ShadowOpacity, ShadowColor, and Elevation, developers can fine-tune the visual hierarchy and create a modern, engaging UI.

---

Additional Tips

Tip	Explanation
Leverage material design standards	Use the Elevation property to automatically manage shadow attributes according to material design guidelines.
Combine with other visual effects	Integrate shadow effects with gradient backgrounds, border styling, and rounded corners for a cohesive design.
Test on multiple displays	Verify shadow visibility and consistency across different screen resolutions and background colors.

This comprehensive documentation should assist developers in effectively integrating and customizing the Shadow and Elevation Effects feature of the SiticoneContainer control within their .NET WinForms applications.