RepositoryItem.CustomDisplayText Event

Enables custom display text to be provided for an editor.

Namespace: DevExpress.XtraEditors.Repository

Assembly: DevExpress.XtraEditors.v20.1.dll

Declaration

[DXCategory("Events")]
public event CustomDisplayTextEventHandler CustomDisplayText
<DXCategory("Events")>
Public Event CustomDisplayText As CustomDisplayTextEventHandler

Event Data

The CustomDisplayText event's data class is CustomDisplayTextEventArgs. The following properties provide information specific to this event:

Property Description
DisplayText Gets or sets an editor's display text.
Value Gets an editor's current value.

Remarks

IMPORTANT

If an editor's TextEditStyle property is not DisableTextEditor, the CustomDisplayText event fires only when this editor is not focused. Editors with disabled text editors fire this event with no limitations.

The CustomDisplayText event can be used to provide custom display text for an editor. To provide custom text, assign it to the event's DisplayText parameter. Initially, this property contains the current display text, which is a formatted representation of the editor's edit value. To access the editor's edit value, use the Value parameter.

For ImageComboBoxEdit editors, the CustomDisplayText event only fires when no value is selected in the editor (the ComboBoxEdit.SelectedIndex is set to -1). When a value is selected, the CustomDisplayText event doesn't fire. In this instance, the display text is specified by the selected item's ImageComboBoxItem.Description property.

The CustomDisplayText event also fires for cells in a container control (e.g GridControl, etc) if a repository item object is assigned to the control's column/cell for in-place editing. In display mode (when an in-place editor is not active), the CustomDisplayText event fires with the sender parameter, specifying a corresponding repository item object (the RepositoryItem class' descendant). When an in-place editor is activated, the CustomDisplayText event doesn't fire. However, it's possible to disable the text editing feature via the RepositoryItemButtonEdit.TextEditStyle property. In this instance, when the editor is activated, the CustomDisplayText event fires with the sender parameter specifying a corresponding editor object (the BaseEdit class' descendant).

After your CustomDisplayText event handler is complete, the display text may be modified according to the RepositoryItemTextEdit.CharacterCasing option.

The BaseEdit.CustomDisplayText event is equivalent to the current event.

Example

The code below shows how to provide custom display text for a ProgressBarControl by handling the BaseEdit.CustomDisplayText event.

In the example, the ProgressBarControl displays a countdown timer.

ProgressBarControl-CountDown.gif

using DevExpress.XtraEditors;

System.Windows.Forms.Timer timer = new System.Windows.Forms.Timer();

private void Form1_Load(object sender, EventArgs e) {
    progressBarControl1.Properties.ShowTitle = true;
    progressBarControl1.Properties.PercentView = false;
    progressBarControl1.CustomDisplayText += ProgressBarControl1_CustomDisplayText;
    timer.Tick += timer1_Tick;
}

private void btnStartTimer_Click(object sender, EventArgs e) {
    timer.Enabled = false;
    int totalSeconds = 5;
    DateTime startTime = DateTime.Now;
    progressBarControl1.Tag = startTime;
    progressBarControl1.Properties.Minimum = 0;
    progressBarControl1.Properties.Maximum = totalSeconds;
    progressBarControl1.Position = progressBarControl1.Properties.Minimum;
    timer.Enabled = true;
}

private void ProgressBarControl1_CustomDisplayText(object sender, DevExpress.XtraEditors.Controls.CustomDisplayTextEventArgs e) {
    ProgressBarControl pb = sender as ProgressBarControl;
    if (pb.Tag == null) { e.DisplayText = "Stopped"; return; }
    int currentPosition = Convert.ToInt32(e.Value);
    int maximum = pb.Properties.Maximum;
    int secondsLeft = maximum - currentPosition;
    TimeSpan timeLeft = new TimeSpan(0, 0, secondsLeft);
    string s = string.Format("{0:dd} days {0:hh} hours {0:mm} minutes {0:ss} seconds", timeLeft);
    e.DisplayText = s;
}

private void timer1_Tick(object sender, EventArgs e) {
    ProgressBarControl pb = progressBarControl1;
    if (pb.Tag == null || !(pb.Tag is DateTime)) return;
    DateTime startTime = (DateTime)pb.Tag;
    DateTime currentTime = DateTime.Now;
    int elapsedSeconds = Convert.ToInt32((currentTime - startTime).TotalSeconds);
    int totalSeconds = pb.Properties.Maximum;
    if (elapsedSeconds >= totalSeconds) {
        (sender as System.Windows.Forms.Timer).Enabled = false;
        pb.Tag = null;
        BeginInvoke(new MethodInvoker(delegate
        {
            MessageBox.Show("Stop");
        }));
    }
    pb.Position = elapsedSeconds;
}
See Also