Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Folder Picker

Siticone Folder Picker

The SiticoneFolderPicker is a composite input control that simplifies directory selection in Windows Forms applications. It wraps the native FolderBrowserDialog interaction into a stylish, customizable UI element consisting of a text path display and an action button.

Functional Properties

These properties control the core data binding and behavior of the picker.

Property Type Description & Usage Example
Text string picker.Text = @"C:\Program Files"; The primary writable property for setting the folder path programmatically. Setting this updates the visual display and fires the FolderPathSelected event.
SelectedPath string string path = picker.SelectedPath; A read-only accessor for the currently selected path. To change the path via code, you must use the Text property.
FolderDialogDescription string picker.FolderDialogDescription = "Select a backup destination"; Sets the descriptive label that appears inside the popup FolderBrowserDialog window, guiding the user on what to select.
Enabled bool picker.Enabled = false; Disables the entire control (both the text area and the button). When disabled, the control automatically applies the visual styles defined in DisabledColors.
UltraFastPerformance bool picker.UltraFastPerformance = true; If true, disables all complex animations (fades, ripples) to maximize rendering performance. Recommended for complex forms with many picker instances.

Text & Container Appearance

Properties for customizing the look of the text entry area.

Property Type Description & Usage Example
BackgroundColor Color picker.BackgroundColor = Color.White; The background color of the main text area.
TextColor Color picker.TextColor = Color.Black; The color of the path text when a folder is selected.
Font Font picker.Font = new Font("Segoe UI", 10f); The font used for the path text.
PlaceholderText string picker.PlaceholderText = "Click button to browse..."; Text displayed when the path is empty. Automatically hidden when a path is selected.
PlaceholderColor Color picker.PlaceholderColor = Color.Gray; The color of the placeholder text.

Borders & Corners

Customize the frame of the control with state-aware colors and rounded corners.

Property Type Description & Usage Example
BorderColor Color picker.BorderColor = Color.LightGray; The border color in the default (idle) state.
HoverBorderColor Color picker.HoverBorderColor = Color.Gray; The border color when the mouse hovers over the control.
FocusBorderColor Color picker.FocusBorderColor = Color.DodgerBlue; The border color when the control has input focus (e.g., after clicking text area).
BorderWidth int picker.BorderWidth = 2; The thickness of the border stroke.
TopLeftCornerRadius int picker.TopLeftCornerRadius = 5;
TopRightCornerRadius int picker.TopRightCornerRadius = 5;
BottomLeftCornerRadius int picker.BottomLeftCornerRadius = 5;
BottomRightCornerRadius int picker.BottomRightCornerRadius = 5;

Action Button

The integrated button triggers the folder selection dialog. It supports distinct visual states for idle, hover, and press interactions.

Property Type Description & Usage Example
ButtonColor Color picker.ButtonColor = Color.RoyalBlue; The button background color in the idle state.
ButtonHoverColor Color picker.ButtonHoverColor = Color.CornflowerBlue; The button background color when hovered.
ButtonPressColor Color picker.ButtonPressColor = Color.MidnightBlue; The button background color when pressed (active).
ButtonImage Image picker.ButtonImage = Properties.Resources.FolderIcon; The primary icon displayed on the button. If null, the button renders "..." text using ButtonPlaceholderColor.
ButtonImageHover Image picker.ButtonImageHover = Properties.Resources.IconHover;
ButtonImagePress Image picker.ButtonImagePress = Properties.Resources.IconPressed;
ButtonSize int picker.ButtonSize = 30; The fixed width and height of the button square.
ButtonCornerRadius int picker.ButtonCornerRadius = 4; The rounding radius for the button corners.

Events

Events Wiring & Descriptions
// FolderPathSelected Event
// This is the primary event for this control.
// It fires whenever the SelectedPath changes, whether by user interaction
// with the dialog or by setting the .Text property in code.
picker.FolderPathSelected += (s, e) => 
{
                // Access the new path via Event Args
                string newPath = e.FullPath;
                Console.WriteLine($"Folder changed to: {newPath}");
    
                // Enable a 'Next' button if the path is valid
    btnNext.Enabled = !string.IsNullOrEmpty(newPath);
};

Designer & Smart Tags

The SiticoneFolderPicker includes a powerful Smart Tag menu in the Visual Studio Designer. This menu allows for rapid styling without writing code.

Feature Description
Theme Presets Apply comprehensive color schemes instantly via the Smart Tag menu actions. Available presets include:
  • Standard: Light, Dark, Modern (Rounded).
  • Vibrant: Blue, Green, Purple, Red, Orange, Teal, Pink, Yellow, Cyan.
  • Nature & Mood: Ocean, Forest, Sunset, Royal, Mint, Cherry, Gray, Indigo.
Copy/Paste Settings Copy Settings: Captures all visual properties (Colors, Radius, Borders) of the current picker.
Paste Settings: Applies the copied configuration to another picker instance.
Useful for maintaining consistency across multiple inputs on a form.
Performance Toggle A quick checkbox to enable UltraFastPerformance directly from the designer surface.

Detailed Usage Examples

Example 1: Setting a Default Path

You cannot set SelectedPath directly as it is read-only. Instead, set the Text property during form initialization.

C# - Initialization
public Form1()
{
                InitializeComponent();
    
                // Correct way to pre-select a folder
                // This updates the internal SelectedPath automatically
    siticoneFolderPicker1.Text = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
    
                // Customize the dialog title
    siticoneFolderPicker1.FolderDialogDescription = "Please select your document source folder";
}

Example 2: Validation Logic

Using the FolderPathSelected event to ensure the user picked a valid directory before proceeding.

C# - Validation
private void pickerOutput_FolderPathSelected(object sender, FolderPathSelectedEventArgs e)
{
                // 1. Check if the path exists (it usually does coming from the dialog, 
                // but good practice if set programmatically)
                if (!Directory.Exists(e.FullPath))
    {
        lblStatus.Text = "Invalid directory selected.";
        lblStatus.ForeColor = Color.Red;
        btnSave.Enabled = false;
                return;
    }

                // 2. Check for write permissions (simplified example)
                try
    {
                string testFile = Path.Combine(e.FullPath, ".write_test");
                File.WriteAllText(testFile, "test");
                File.Delete(testFile);
        
                // Success
        lblStatus.Text = "Ready to save.";
        lblStatus.ForeColor = Color.Green;
        btnSave.Enabled = true;
    }
                catch (UnauthorizedAccessException)
    {
        lblStatus.Text = "No write permission in this folder.";
        lblStatus.ForeColor = Color.Orange;
        btnSave.Enabled = false;
    }
}

Example 3: Dynamic Dark Theme Application

Applying a custom dark theme configuration at runtime.

C# - Dark Theme Styling
// Configure picker for a dark themed UI
private void ApplyDarkTheme(SiticoneFolderPicker picker)
{
                // 1. Main Container
    picker.BackgroundColor = Color.FromArgb(30, 30, 30);
    picker.TextColor = Color.FromArgb(240, 240, 240);
    picker.PlaceholderColor = Color.FromArgb(100, 100, 100);
    
                // 2. Borders (Subtle dark grays)
    picker.BorderColor = Color.FromArgb(60, 60, 60);
    picker.HoverBorderColor = Color.FromArgb(80, 80, 80);
    picker.FocusBorderColor = Color.FromArgb(100, 149, 237); // Cornflower Blue accent
    
                // 3. Button (Matches border/background style)
    picker.ButtonColor = Color.FromArgb(50, 50, 50);
    picker.ButtonHoverColor = Color.FromArgb(70, 70, 70);
    picker.ButtonPressColor = Color.FromArgb(100, 149, 237);
    picker.ButtonPlaceholderColor = Color.White;
    
                // 4. Geometry
    picker.BorderWidth = 1;
    picker.TopLeftCornerRadius = 4;
    picker.TopRightCornerRadius = 4;
    picker.BottomLeftCornerRadius = 4;
    picker.BottomRightCornerRadius = 4;
    picker.ButtonCornerRadius = 3;
}