Linee guida per la progettazione di controlli utente

Questo articolo fornisce linee guida per la creazione di controlli utente. È consigliabile seguire queste linee guida per assicurarsi di progettare un controllo utente coerente con altri controlli Windows Form.

Definizione di eventi

Gli eventi comunicano comunemente la modifica dello stato e segnalano come l'utente interagisce con un controllo Windows Form. Per ulteriori informazioni su eventi e delegati, vedere Gestire e sollevare eventi.

Quando si definiscono eventi personalizzati, seguire questi suggerimenti:

• Usare il delegato dell'evento EventHandler quando si definisce un evento che non dispone di dati associati. Utilizzare il delegato dell'evento EventHandler<TEventArgs> quando si dispone di dati associati.
• Derivare da EventArgs ed estenderlo con i dati correlati all'evento.
• Passa l'istanza di controllo come parametro sender.
• Creare un metodo denominato On{EventName} che genera l'evento, contrassegnato come protected e virtual (in C#) o Protected e Overridable (in Visual Basic).
• Applicare il {PropertyName}Changed modello.

// The event
public event EventHandler AllowInteractionChanged;

// The backing field for the property
private bool _allowInteraction;

// The property
[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]
public bool AllowInteraction
{
    get => _allowInteraction;
    set
    {
        // When the value has changed, call the method to raise the event
        if (_allowInteraction != value)
        {
            _allowInteraction = value;
            OnAllowInteractionChanged();
        }
    }
}

// Raises the event
public virtual void OnAllowInteractionChanged() =>
    AllowInteractionChanged?.Invoke(this, EventArgs.Empty);

'The event
Public Event AllowInteractionChanged As EventHandler

'The backing field for the property
Private _allowInteraction As Boolean

'The property
<DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)>
Public Property AllowInteraction() As Boolean
    Get
        Return _allowInteraction
    End Get
    Set(value As Boolean)
        _allowInteraction = value
        OnAllowInteractionChanged()
    End Set
End Property

'Raises the event
Public Overridable Sub OnAllowInteractionChanged()
    RaiseEvent AllowInteractionChanged(Me, EventArgs.Empty)
End Sub

Eventi di modifica delle proprietà

Se si desidera che il controllo invii notifiche quando viene modificata una proprietà, definire un evento denominato {PropertyName}Changed. Si tratta della convenzione di denominazione usata in Windows Form. Quando la proprietà segue questa convenzione di denominazione, viene fornito il supporto per il data binding bidirezionale.

Il tipo di delegato di evento associato per gli eventi di modifica della proprietà è EventHandlere il tipo di dati dell'evento è EventArgs. La classe Control base definisce molti eventi modificati dalle proprietà, ad esempio BackColorChanged, BackgroundImageChangedFontChanged, e LocationChanged.

Gli stessi suggerimenti della sezione Definizione degli eventi si applicano anche qui, nella sezione.

public class ProgressReportEventArgs : EventArgs
{
    public readonly int Value;
    public readonly int Maximum;

    public ProgressReportEventArgs(int value, int maximum) =>
        (Value, Maximum) = (value, maximum);
}

public event EventHandler<ProgressReportEventArgs> ProgressChanged;

public virtual void OnProgressChanged(int value, int maximum) =>
    ProgressChanged?.Invoke(this, new ProgressReportEventArgs(value, maximum));

Public Class ProgressReportEventArgs
    Inherits EventArgs

    Public ReadOnly Value As Integer
    Public ReadOnly Maximum As Integer

    Public Sub New(value As Integer, maximum As Integer)
        Me.Value = value
        Me.Maximum = maximum
    End Sub
End Class

Public Event ProgressChanged As EventHandler(Of ProgressReportEventArgs)

Public Overridable Sub OnProgressChanged(value As Integer, maximum As Integer)
    RaiseEvent ProgressChanged(Me, New ProgressReportEventArgs(value, maximum))
End Sub

Proprietà e Progettazione visiva

Le proprietà del controllo dovrebbero supportare il Progettazione Visiva di Windows Forms. La finestra proprietà interagisce con le proprietà del controllo e gli utenti si aspettano di usarla per modificare le proprietà del controllo. Aggiungere il DefaultValueAttribute alla proprietà oppure creare metodi corrispondenti Reset<PropertyName> e ShouldSerialize<PropertyName>. Per altre informazioni, vedere DefaultValueAttribute e Reset e ShouldSerialize.

Le proprietà che non si desidera esporre nella Progettazione visiva di Windows Forms devono aggiungere il BrowsableAttribute alla proprietà, passando false come parametro dell'attributo. In questo modo la proprietà viene nascosta dalla finestra Proprietà. Per altre informazioni, vedere Definire una proprietà e attributi di per le proprietà.