# FTRCard

## Overview

`FTRCard` is a modern Windows Forms container control for organizing related content inside a visually styled card.

It can provide:

- A header area with a title
- Optional close, maximize/restore, and collapse/expand buttons
- An optional footer area
- Custom border and separator colors
- Rounded corners
- A soft drop shadow
- Automatic support for FTR theme changes
- Normal Windows Forms child controls inside the card

`FTRCard` inherits from `Panel`, so you can add controls to it using the standard Windows Forms `Controls` collection.

**Namespace:** `FTRControls`  
**Base class:** `Panel`  
**Designer:** Available as a Windows Forms Toolbox control

---

## Basic Usage

After adding the FTR Controls assembly to your Windows Forms project:

1. Add `FTRCard` from the Toolbox, or create it in code.
2. Set the properties you need.
3. Add your application controls to the card.
4. Optionally handle the card events.

### Example

```csharp
var card = new FTRCard
{
    HeaderText = "Sales",
    ShowFooter = true,
    FooterText = "Updated today",
    BorderRadius = 12,
    Dock = DockStyle.Fill
};

card.Controls.Add(chart);
```

Because `FTRCard` is a `Panel`, existing controls such as `Label`, `Button`, `DataGridView`, charts, custom controls, and other containers can be placed inside it normally.

---

# Properties

## Header

### `HeaderText`

**Type:** `string`  
**Default:** `"Card title"`

Text displayed in the card header.

```csharp
card.HeaderText = "Customer Information";
```

---

### `ShowHeader`

**Type:** `bool`  
**Default:** `true`

Controls whether the header area is displayed.

```csharp
card.ShowHeader = false;
```

When the header is hidden, the card no longer reserves space for the header.

---

### `HeaderHeight`

**Type:** `int`  
**Default:** `40`  
**Minimum:** `15`  
**Premium:** Yes

Sets the height of the header area in pixels.

```csharp
card.HeaderHeight = 48;
```

This property changes the layout area available for the card's child controls.

---

### `HeaderFont`

**Type:** `Font`  
**Default:** Segoe UI, 10pt, Bold

Controls the font used for the header title.

```csharp
card.HeaderFont = new Font("Segoe UI", 11, FontStyle.Bold);
```

---

### `HeaderForeColor`

**Type:** `Color`  
**Default:** `Color.Black`

Sets the header title color.

```csharp
card.HeaderForeColor = Color.DarkBlue;
```

---

### `HeaderBackColor`

**Type:** `Color`  
**Default:** `Color.Transparent`  
**Premium:** Yes

Sets the background color of the header area.

```csharp
card.HeaderBackColor = Color.WhiteSmoke;
```

Use `Color.Transparent` when the header should use the card's normal background.

---

# Footer

### `ShowFooter`

**Type:** `bool`  
**Default:** `false`

Controls whether the footer area is displayed.

```csharp
card.ShowFooter = true;
```

---

### `FooterText`

**Type:** `string`  
**Default:** `"Footer text"`

Text displayed in the footer.

```csharp
card.FooterText = "Last updated: Today";
```

---

### `FooterHeight`

**Type:** `int`  
**Default:** `35`  
**Minimum:** `10`  
**Premium:** Yes

Sets the footer height in pixels.

```csharp
card.FooterHeight = 40;
```

---

### `FooterFont`

**Type:** `Font`

Controls the footer text font.

```csharp
card.FooterFont = new Font("Segoe UI", 9);
```

---

### `FooterForeColor`

**Type:** `Color`  
**Default:** `Color.DimGray`

Sets the footer text color.

```csharp
card.FooterForeColor = Color.Gray;
```

---

### `FooterBackColor`

**Type:** `Color`  
**Default:** `Color.Transparent`  
**Premium:** Yes

Sets the footer background color.

```csharp
card.FooterBackColor = Color.WhiteSmoke;
```

---

# Card Appearance

### `CardBackColor`

**Type:** `Color`  
**Default:** `Color.White`

Sets the main background color of the card.

```csharp
card.CardBackColor = Color.White;
```

> Use `CardBackColor` instead of `BackColor` for the visible card surface.

---

### `BorderColor`

**Type:** `Color`  
**Default:** `Color.LightGray`

Sets the color of the card border.

```csharp
card.BorderColor = Color.Silver;
```

---

### `BorderThickness`

**Type:** `int`  
**Default:** `1`  
**Range:** `0–20`

Sets the border thickness in pixels.

```csharp
card.BorderThickness = 2;
```

Use `0` to disable the visible border.

---

### `BorderRadius`

**Type:** `int`  
**Default:** `0`  
**Range:** `0–200`  
**Premium:** Yes

Sets the radius of the card's rounded corners.

```csharp
card.BorderRadius = 12;
```

A value of `0` produces square corners.

---

### `SeparatorColor`

**Type:** `Color`  
**Default:** `Color.LightGray`

Controls the color of the separator lines between the header, content, and footer areas.

```csharp
card.SeparatorColor = Color.Gainsboro;
```

---

### `Padding`

**Type:** `Padding`

Controls the user's additional padding around the child content.

```csharp
card.Padding = new Padding(10);
```

`FTRCard` also reserves internal space automatically for the border, shadow, header, and footer. Therefore, the effective content area is not identical to the raw `Padding` value.

This means you normally do **not** need to manually move child controls down to make room for the header.

---

# Shadow

### `ShadowDepth`

**Type:** `int`  
**Default:** `5`  
**Range:** `0–30`  
**Premium:** Yes

Controls the depth of the card's soft shadow.

```csharp
card.ShadowDepth = 8;
```

Use `0` to remove the shadow.

---

### `ShadowColor`

**Type:** `Color`  
**Default:** `Color.FromArgb(40, 0, 0, 0)`  
**Premium:** Yes

Controls the base color and transparency of the shadow.

```csharp
card.ShadowColor = Color.FromArgb(50, 0, 0, 0);
```

The alpha channel controls transparency.

---

# Header Buttons

The header can contain three optional action buttons.

## `ShowCloseButton`

**Type:** `bool`  
**Default:** `true`  
**Premium:** Yes

Shows or hides the close button.

```csharp
card.ShowCloseButton = false;
```

When the close button is clicked:

1. `CardClosed` is raised.
2. The card's `Visible` property is set to `false`.

The close button does **not** dispose the control.

---

## `ShowMaximizeButton`

**Type:** `bool`  
**Default:** `true`  
**Premium:** Yes

Shows or hides the maximize/restore button.

```csharp
card.ShowMaximizeButton = true;
```

When clicked, the card switches between:

- Its normal bounds/layout
- `DockStyle.Fill`

The previous `Bounds`, `Dock`, and `Anchor` values are restored when the card is returned to its normal state.

---

## `ShowCollapseButton`

**Type:** `bool`  
**Default:** `true`  
**Premium:** Yes

Shows or hides the collapse/expand button.

```csharp
card.ShowCollapseButton = true;
```

When collapsed, the card keeps its header visible and reduces its height. Clicking the button again restores the previous expanded height.

If the card is maximized when collapse is requested, it first returns to its normal layout and then collapses.

---

# Events

## `CardClosed`

Raised when the user clicks the close button.

```csharp
card.CardClosed += (sender, e) =>
{
    // Perform any application-specific action here.
};
```

The control automatically sets:

```csharp
card.Visible = false;
```

You can use the event when your application needs to react to the card being closed.

---

## `CardCollapsed`

Raised after the card changes from expanded to collapsed state.

```csharp
card.CardCollapsed += (sender, e) =>
{
    // Card is now collapsed.
};
```

---

## `CardExpanded`

Raised after the card changes from collapsed to expanded state.

```csharp
card.CardExpanded += (sender, e) =>
{
    // Card is now expanded.
};
```

---

# Theme Support

`FTRCard` supports the FTR Controls theme system.

When the global FTR theme changes, the card updates its standard palette automatically.

The control supports the following theme modes:

- Light
- Dark
- Color
- Duotone

The theme can affect the card's:

- Background
- Border
- Header text color
- Footer text color
- Separator color
- Shadow color
- General foreground color

### Important

Theme application can replace manually assigned appearance colors.

If your application requires fixed custom colors instead of the global theme palette, configure the card after the theme has been applied or use the application's theme configuration accordingly.

---

# Licensing and Premium Properties

Some visual and layout features are available only when the FTR Controls license is active.

Premium properties are:

| Property | Premium |
|---|:---:|
| `BorderRadius` | Yes |
| `ShadowDepth` | Yes |
| `ShadowColor` | Yes |
| `HeaderBackColor` | Yes |
| `HeaderHeight` | Yes |
| `FooterBackColor` | Yes |
| `FooterHeight` | Yes |
| `ShowCloseButton` | Yes |
| `ShowMaximizeButton` | Yes |
| `ShowCollapseButton` | Yes |

When a premium property is changed without an active license, the control requests activation and does not apply the requested value.

Non-premium properties continue to be available according to the assembly/license configuration.

---

# Working with Child Controls

`FTRCard` is a normal Windows Forms container.

For example:

```csharp
var card = new FTRCard
{
    HeaderText = "User Details",
    ShowFooter = true,
    FooterText = "Account information"
};

var nameLabel = new Label
{
    Text = "Name:"
};

var nameTextBox = new TextBox
{
    Location = new Point(10, 10),
    Width = 200
};

card.Controls.Add(nameLabel);
card.Controls.Add(nameTextBox);
```

The card automatically reserves space for its visual header/footer, border, and shadow so that child controls are placed inside the usable content area.

---

# Designer Usage

`FTRCard` can be used from the Visual Studio Windows Forms Designer.

Typical workflow:

1. Build/reference the FTR Controls assembly.
2. Add the control to the Visual Studio Toolbox if required.
3. Drag `FTRCard` onto the form.
4. Configure its properties through the Properties window.
5. Add child controls to the card.
6. Connect events such as `CardClosed`, `CardCollapsed`, and `CardExpanded` when needed.

Premium properties may require an active FTR Controls license before they can be changed.

---

# Recommended Configurations

## Simple Content Card

```csharp
var card = new FTRCard
{
    HeaderText = "Customer",
    ShowFooter = false,
    ShowCloseButton = false,
    ShowMaximizeButton = false,
    ShowCollapseButton = false,
    BorderRadius = 10,
    ShadowDepth = 5,
    Dock = DockStyle.Fill
};
```

## Dashboard Card

```csharp
var card = new FTRCard
{
    HeaderText = "Monthly Sales",
    ShowHeader = true,
    ShowFooter = true,
    FooterText = "Updated today",
    ShowCloseButton = false,
    ShowCollapseButton = false,
    BorderRadius = 12,
    ShadowDepth = 6
};
```

## Closable Panel

```csharp
var card = new FTRCard
{
    HeaderText = "Notifications",
    ShowCloseButton = true,
    ShowMaximizeButton = false,
    ShowCollapseButton = false
};

card.CardClosed += (s, e) =>
{
    // Application-specific close handling.
};
```

---

# Layout and Docking Notes

Because `FTRCard` inherits from `Panel`, standard Windows Forms layout features such as:

- `Dock`
- `Anchor`
- `Location`
- `Size`
- `MinimumSize`
- `Margin`

can be used normally.

The default size of the control is approximately:

**300 × 200 pixels**

The minimum size is:

**150 × 90 pixels**

The maximize button temporarily uses:

```csharp
DockStyle.Fill
```

and restores the previous docking, anchoring, and bounds when restored.

---

# Right-to-Left Layout

`FTRCard` supports Windows Forms `RightToLeft`.

When `RightToLeft` is set to `Yes`, the header title and header action-button layout are adjusted for right-to-left interfaces.

```csharp
card.RightToLeft = RightToLeft.Yes;
```

This is useful for applications that require RTL user interfaces.

---

# Important Notes

### `BackColor`

The standard `BackColor` property is intentionally hidden from the Properties window for `FTRCard`.

Use:

```csharp
card.CardBackColor
```

to change the visible card background.

---

### Close Does Not Dispose the Control

The close button only hides the card by setting:

```csharp
Visible = false;
```

If your application needs to permanently remove or dispose of the card, handle `CardClosed` and perform that action in application code.

---

### Collapse Changes Height

Collapse/expand is a layout operation. The control remembers the previous expanded height and restores it when expanded again.

---

### Theme Changes

If the application changes its global FTR theme, the card may update its themed appearance properties. Applications that require a fixed custom appearance should account for this behavior.

---

# Quick Reference

| Property / Event | Type | Default | Premium |
|---|---|---:|:---:|
| `HeaderText` | `string` | `"Card title"` | No |
| `ShowHeader` | `bool` | `true` | No |
| `HeaderHeight` | `int` | `40` | Yes |
| `HeaderFont` | `Font` | Segoe UI Bold | No |
| `HeaderForeColor` | `Color` | Black | No |
| `HeaderBackColor` | `Color` | Transparent | Yes |
| `FooterText` | `string` | `"Footer text"` | No |
| `ShowFooter` | `bool` | `false` | No |
| `FooterHeight` | `int` | `35` | Yes |
| `FooterFont` | `Font` | Segoe UI | No |
| `FooterForeColor` | `Color` | DimGray | No |
| `FooterBackColor` | `Color` | Transparent | Yes |
| `CardBackColor` | `Color` | White | No |
| `BorderColor` | `Color` | LightGray | No |
| `BorderThickness` | `int` | `1` | No |
| `BorderRadius` | `int` | `0` | Yes |
| `SeparatorColor` | `Color` | LightGray | No |
| `ShadowDepth` | `int` | `5` | Yes |
| `ShadowColor` | `Color` | `ARGB(40,0,0,0)` | Yes |
| `ShowCloseButton` | `bool` | `true` | Yes |
| `ShowMaximizeButton` | `bool` | `true` | Yes |
| `ShowCollapseButton` | `bool` | `true` | Yes |
| `Padding` | `Padding` | Empty | No |

### Events

| Event | Trigger |
|---|---|
| `CardClosed` | Close button clicked |
| `CardCollapsed` | Card becomes collapsed |
| `CardExpanded` | Card becomes expanded |

### Public Method

| Method | Purpose |
|---|---|
| `ApplyTheme()` | Applies the current FTR theme to the card |

---

# See Also

- `FTRDashboard`
- `ThemeManager`
- FTR Controls licensing documentation