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
// 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:
|
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.
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.
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.
// 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;
}