---
title: SAIFDropDownList
summary: API reference for SAIFDropDownList.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-08-17
library: SAIF.Presentation.Web.Controls.V2
reference_type: package
---

# SAIFDropDownList

`SAIFDropDownList` is a `DropDownList` subclass adding two independent conveniences: binding directly to a `.NET` enum's values/names (`EnumDatasource`/`SelectedItemAsEnum`), and the same `[ReadOnly]` static-rendering convention used by the other `SAIF*` input controls — here rendered as a disabled-style text box rather than an image ([BR-V2-003](../../business-rules.md#br-v2-003-read-only-input-controls-render-as-static-images-not-native-controls)).

## Purpose
- Simplify binding a dropdown's options directly to an enum type, optionally converting underscores to spaces for display (`MapUnderscore`).
- Provide a `[ReadOnly]` mode that renders a disabled-style text box showing the selected value, rather than the interactive dropdown.

## Context
- Namespace: `SAIF.Presentation.Web.Controls.V2`
- Assembly/package: Compiled into `SAIF.BOF.Presentation.Web.Infragistics103`*

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `MapUnderscore` | `Public Property MapUnderscore As Boolean` | Controls whether underscores in enum member names are converted to/from spaces when binding and reading `SelectedItemAsEnum`; defaults to `True`. |
| `SelectedItemAsEnum` | `Public Property SelectedItemAsEnum As [Enum]` | The strongly typed conversion boundary between the dropdown's text-based selection and an `EnumDatasource` member: the getter parses the selected item's display text back into the enum type, and the setter formats an enum value to select the matching item, both applying `MapUnderscore` substitution. |
| `EnumDatasource` | `Public Property EnumDatasource As [Enum]` | The enum instance whose type's member names populate the dropdown's options on `DataBind`. |
| `DataBind()` | `Public Overrides Sub DataBind()` | When `EnumDatasource` is set, populates the base `DataSource` from `System.Enum.GetNames`, applying the `MapUnderscore` substitution, before calling the base `DataBind`. |
| `[ReadOnly]` | `Property [ReadOnly] As Boolean` | Switches the control from its native interactive `DropDownList` rendering to a disabled-style text box showing the selected value, per [BR-V2-003](../../business-rules.md#br-v2-003-read-only-input-controls-render-as-static-images-not-native-controls). |
| `ValueText` | `Public Property ValueText As String` | Fallback display text used in read-only rendering when `SelectedValue` is empty but a value was previously captured. |

## Inherited public members

`SAIFDropDownList` inherits from `DropDownList` (`System.Web.UI.WebControls`), a framework base class rather than a documented SAIF dependency library.

| Member | Signature | Purpose |
| --- | --- | --- |
| `AppendDataBoundItems` | `Public Property AppendDataBoundItems As Boolean` | Determines whether data binding appends to existing items instead of replacing them. |
| `AutoPostBack` | `Public Property AutoPostBack As Boolean` | Determines whether changing the selection immediately posts the page back to the server. |
| `DataTextField` | `Public Property DataTextField As String` | Name of the data-source field used for item display text during binding. |
| `DataValueField` | `Public Property DataValueField As String` | Name of the data-source field used for the posted item value during binding. |
| `Items` | `Public ReadOnly Property Items As ListItemCollection` | Collection of selectable dropdown items managed by the control. |
| `SelectedIndex` | `Public Property SelectedIndex As Integer` | Zero-based index of the currently selected item. |
| `SelectedItem` | `Public ReadOnly Property SelectedItem As ListItem` | Currently selected dropdown item. |
| `SelectedValue` | `Public Property SelectedValue As String` | Posted value of the currently selected item. |
| `Text` | `Public Property Text As String` | Display text associated with the selected item. |
| `SelectedIndexChanged` | `Public Event SelectedIndexChanged As EventHandler` | Standard selection-change event raised after postback. |

Standard `DropDownList`/`Control` members (`ID`, `ClientID`, `Controls`, `Visible`, `DataBind`, `FindControl`, etc.) are not re-documented here as they are unmodified framework behavior**.

## Behavioral notes
- `Render` in read-only mode constructs a disabled `TextBox` sized to roughly match the dropdown, copying the selected item's text (or `ValueText` as a fallback) and applying the same inline styles.
- In non-read-only mode, `Render` wraps the base `Render` call in a `Try`/`Catch` that deselects the current item and retries if the base render throws — a defensive workaround for a selection-related rendering error*.

## Constraints and usage notes
- `SelectedItemAsEnum`'s getter throws if `SelectedItem.Text` does not match a member name of `EnumDatasource`'s type (after underscore substitution).

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Presentation.Web.Controls.V2\SAIFDropDownList.vb