Implémenter les événements de molette de la souris dans les SDK .NET¶

Video Capture SDK .Net Video Edit SDK .Net Media Player SDK .Net

Introduction aux événements de molette de la souris¶

Les événements de molette de la souris offrent un moyen intuitif aux utilisateurs d'interagir avec le contenu vidéo dans les applications multimédias. Que vous développiez un lecteur vidéo, un éditeur ou une application de capture, l'implémentation correcte de la gestion des événements de molette améliore l'expérience utilisateur en permettant un zoom fluide, un défilement ou une navigation temporelle.

Dans les applications .NET, l'événement MouseWheel est déclenché lorsque l'utilisateur fait tourner la molette de la souris. Cet événement fournit des informations cruciales sur la direction et l'intensité du mouvement de la molette via le paramètre MouseEventArgs.

Pourquoi implémenter les événements de molette de la souris ?¶

La fonctionnalité de la molette offre plusieurs avantages pour vos applications vidéo :

• Expérience utilisateur améliorée : active une fonctionnalité de zoom intuitive dans les visionneuses vidéo
• Navigation enrichie : permet un défilement rapide de la timeline dans les éditeurs vidéo
• Contrôle du volume : fournit un ajustement pratique du volume dans les lecteurs multimédias
• Interaction d'UI efficace : réduit la dépendance aux contrôles à l'écran

Implémentation de base¶

Configuration des gestionnaires d'événements¶

Pour implémenter la fonctionnalité de molette dans votre application .NET, vous devez configurer trois gestionnaires d'événements clés :

1. MouseEnter : garantit que le contrôle obtient le focus à l'entrée du curseur
2. MouseLeave : libère le focus lorsque le curseur sort
3. MouseWheel : gère l'événement réel de rotation de la molette

Voici une implémentation de base :

private void VideoView1_MouseEnter(object sender, EventArgs e) 
{ 
  if (!VideoView1.Focused) 
  { 
    VideoView1.Focus(); 
  } 
}

private void VideoView1_MouseLeave(object sender, EventArgs e) 
{ 
  if (VideoView1.Focused) 
  { 
    VideoView1.Parent.Focus(); 
  } 
}

private void VideoView1_MouseWheel(object sender, MouseEventArgs e) 
{ 
  mmLog.Text += "Delta: " + e.Delta + Environment.NewLine; 
}

Le gestionnaire d'événements MouseWheel reçoit un paramètre MouseEventArgs qui inclut la propriété Delta. Cette valeur indique la direction et la distance parcourues par la molette :

• Delta positif : la molette a tourné vers l'avant (loin de l'utilisateur)
• Delta négatif : la molette a tourné vers l'arrière (vers l'utilisateur)
• Magnitude du Delta : indique l'intensité de la rotation

Techniques d'implémentation avancées¶

Implémenter la fonctionnalité de zoom¶

Une utilisation courante de la molette dans les applications vidéo est de zoomer et dézoomer. Voici comment implémenter une fonctionnalité de zoom :

private void VideoView1_MouseWheel(object sender, MouseEventArgs e)
{
    // Déterminer la direction du zoom en fonction du delta
    if (e.Delta > 0)
    {
        // Code de zoom avant
        ZoomIn(0.1); // Augmenter le zoom de 10 %
    }
    else
    {
        // Code de zoom arrière
        ZoomOut(0.1); // Diminuer le zoom de 10 %
    }
}

private double _zoomRatio = 1.0;

private void ZoomIn(double factor)
{
    // Le zoom est exposé sur le moteur de rendu (moteur classique) ou via un ZoomEffect sur le moteur X,
    // pas sur VideoView. Le moteur classique utilise `videoCapture1.Video_Renderer.Zoom_Ratio`
    // (et Zoom_ShiftX / Zoom_ShiftY pour le décalage du centre).
    _zoomRatio = Math.Min(_zoomRatio + factor, 3.0); // Zoom max de 300 %
    videoCapture1.Video_Renderer.Zoom_Ratio = _zoomRatio;
    videoCapture1.Video_Renderer_Update();
}

private void ZoomOut(double factor)
{
    _zoomRatio = Math.Max(_zoomRatio - factor, 0.5); // Zoom min de 50 %
    videoCapture1.Video_Renderer.Zoom_Ratio = _zoomRatio;
    videoCapture1.Video_Renderer_Update();
}

Navigation dans la timeline¶

Pour les applications d'édition vidéo, la molette peut être utilisée pour naviguer dans la timeline :

private void TimelineControl_MouseWheel(object sender, MouseEventArgs e)
{
    // Calculer le déplacement en fonction du delta et de la longueur de la timeline
    double moveFactor = e.Delta / 120.0; // Normaliser en incréments de 1.0
    double moveAmount = moveFactor * 5.0; // 5 secondes par « cran » de molette

    // Déplacer la position
    double newPosition = TimelineControl.CurrentPosition + moveAmount;

    // S'assurer de rester dans les limites
    newPosition = Math.Max(0, Math.Min(newPosition, TimelineControl.Duration));

    // Appliquer la nouvelle position
    TimelineControl.CurrentPosition = newPosition;
}

Contrôle du volume¶

Un autre cas d'usage courant est de contrôler le volume dans les applications de lecteur multimédia :

private void VideoView1_MouseWheel(object sender, MouseEventArgs e)
{
    // Le volume est au niveau du moteur (pas sur VideoView). Le moteur classique expose
    // Audio_OutputDevice_Volume dans la plage 0–100 pourcent ; le moteur X expose
    // Audio_OutputDevice_Volume dans la plage 0.0–1.0. L'exemple ci-dessous cible le moteur
    // classique VideoCaptureCore / MediaPlayerCore — ajustez l'arithmétique pour une
    // proportion 0–1 si vous êtes sur le moteur X.
    int volumeChangePercent = (int)Math.Round(e.Delta / 120.0 * 5.0); // 5 points de pourcentage par « cran » de molette

    int newVolume = videoCapture1.Audio_OutputDevice_Volume + volumeChangePercent;
    newVolume = Math.Max(0, Math.Min(newVolume, 100));

    videoCapture1.Audio_OutputDevice_Volume = newVolume;

    // Optionnel : afficher l'indicateur de volume (proportion 0–1 pour l'UI de l'indicateur)
    ShowVolumeIndicator(newVolume / 100f);
}

Gestion du focus¶

Une gestion correcte du focus est cruciale pour que les événements de molette fonctionnent correctement. Le code d'exemple montre une implémentation de base, mais dans des applications plus complexes, vous pourriez avoir besoin d'une approche plus sophistiquée :

private void VideoView1_MouseEnter(object sender, EventArgs e)
{
    // Stocker le contrôle précédemment focalisé
    _previouslyFocused = Form.ActiveControl;

    // Focaliser notre contrôle
    VideoView1.Focus();

    // Optionnel : indication visuelle que le contrôle a le focus
    VideoView1.BorderStyle = BorderStyle.FixedSingle;
}

private void VideoView1_MouseLeave(object sender, EventArgs e)
{
    // Rendre le focus au contrôle précédent si pertinent
    if (_previouslyFocused != null && _previouslyFocused.CanFocus)
    {
        _previouslyFocused.Focus();
    }
    else
    {
        // Si pas de contrôle précédent, focaliser le parent
        VideoView1.Parent.Focus();
    }

    // Réinitialiser l'indication visuelle
    VideoView1.BorderStyle = BorderStyle.None;
}

Considérations de performance¶

Lors de l'implémentation des événements de molette, prenez en compte ces conseils de performance :

1. Anti-rebond des événements de molette : les molettes peuvent générer beaucoup d'événements en succession rapide
2. Optimisez les calculs : évitez les calculs complexes dans le gestionnaire d'événements de molette
3. Utilisez l'animation : pour un zoom fluide, envisagez d'utiliser une animation plutôt que des changements abrupts

Voici un exemple d'anti-rebond des événements de molette :

private DateTime _lastWheelEvent = DateTime.MinValue;
private const int DebounceMs = 50;

private void VideoView1_MouseWheel(object sender, MouseEventArgs e)
{
    // Vérifier si suffisamment de temps s'est écoulé depuis le dernier événement
    TimeSpan elapsed = DateTime.Now - _lastWheelEvent;
    if (elapsed.TotalMilliseconds < DebounceMs)
    {
        return; // Ignorer l'événement s'il arrive trop tôt
    }

    // Traiter l'événement de molette
    ProcessWheelEvent(e.Delta);

    // Mettre à jour l'heure du dernier événement
    _lastWheelEvent = DateTime.Now;
}

Considérations multiplateformes¶

Si vous développez des applications .NET multiplateformes, sachez que le comportement de la molette de la souris peut varier :

• Windows : typiquement 120 unités par « cran »
• macOS : peut avoir des paramètres de sensibilité différents
• Linux : peut varier selon la distribution et la configuration

Votre code doit tenir compte de ces différences :

private void VideoView1_MouseWheel(object sender, MouseEventArgs e)
{
    // Normaliser le delta en fonction de la plateforme
    double normalizedDelta;

    if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
    {
        normalizedDelta = e.Delta / 120.0;
    }
    else if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
    {
        normalizedDelta = e.Delta / 100.0;
    }
    else
    {
        normalizedDelta = e.Delta / 120.0; // Par défaut pour Linux et autres
    }

    // Utiliser le delta normalisé pour les calculs
    ApplyZoom(normalizedDelta);
}

Dépannage des problèmes courants¶

Les événements de molette ne se déclenchent pas¶

Si vos événements de molette ne se déclenchent pas, vérifiez :

1. Problèmes de focus : assurez-vous que le contrôle a le focus lorsque le curseur est dessus
2. Inscription de l'événement : vérifiez que le gestionnaire d'événements est correctement inscrit
3. Propriétés du contrôle : certains contrôles ont besoin de propriétés spécifiques pour recevoir les événements de molette

Comportement incohérent¶

Si les événements de molette se comportent de manière incohérente :

1. Normalisation du delta : assurez-vous de bien normaliser les valeurs delta
2. Paramètres utilisateur : tenez compte des paramètres de souris spécifiques à l'utilisateur
3. Variations matérielles : différents matériels de souris peuvent produire différentes valeurs delta

Conclusion¶

La gestion des événements de molette de la souris est un aspect essentiel pour créer des applications vidéo intuitives et conviviales. En implémentant les techniques décrites dans ce guide, vous pouvez enrichir vos applications vidéo .NET de contrôles fluides et intuitifs qui améliorent l'expérience utilisateur globale.

L'implémentation peut varier selon vos exigences spécifiques, mais les principes centraux restent les mêmes : gérer le focus correctement, normaliser les valeurs delta de la molette et appliquer les changements appropriés en fonction de l'entrée utilisateur.

Visitez notre page GitHub pour obtenir d'autres exemples de code.