Le widget SpinButton est généralement utilisé pour permettre à l’utilisateur de choisir une valeur dans une plage de données. Il comprend une boite de saisie de texte avec deux boutons fléchés en haut et en bas sur le côté. Cliquer sur un des boutons entraîne l'incrément ou le décrément dans la plage de valeurs possibles. La boite de saisie peut également être éditée directement pour renseigner une valeur spécifique. SpinButton est une instance de EditableClass, les fonctions et attributs qui sont associés à cette classe sont donc disponibles.
Le bouton compteur permet de définir le nombre de décimales et les incréments. Le fait d'appuyer de façon prolongée sur les boutons entraîne une accélération du changement des valeurs en fonction de la durée de pression du bouton.
SpinButton utilise un objet Adjustment pour conserver les informations des valeurs et de la page que le bouton compteur peut prendre. Rappelons qu'un widget Adjustment se crée avec la fonction suivante:
Ces attributs issus de Adjustment sont utilisés par le SpinButton de la façon suivante
La valeur initiale du SpinButton
La valeur minimale
La valeur maximale
La valeur qui doit être incrémentée ou décrémenté quand le bouton 1 de la souris est pressé.
La valeur qui doit être incrémentée ou décrémenté quand le bouton 2 de la souris est pressé.
Inusité
En complément, le bouton 3 de la souris peut être utilisé pour aller directement aux valeurs maximums ou minimum en cliquant sur un des boutons.
Voyons maintenant comment créer un bouton compteur:
Le deuxième argument (climbRate) prend une valeur entre 0.0 et 1.0 et indique à quelle vitesse le bouton compteur est modifié quand une flèche est cliquée. Le troisième argument spécifie le nombre d'emplacements dans lesquels la valeur doit être affichée.
Il y a aussi un constructeur qui permet la création d'un bouton compteur sans avoir à créer manuellement un Adjustment.
Les trois arguments, tous de type Double spécifient respectivement la valeur minimum, la valeur maximum, l'incrément ajouté ou soustrait par le widget compteur.
Un SpinButton peut être reconfiguré après la création en utilisant la fonction suivante:
Le premier argument le SpinButton qui doit être reconfiguré, les autres arguments sont le climbRate et le nombre de décimales à afficher.
Les attributs du SpinButton qui peuvent être récupérés et changés avec les fonctions génériques get et set sont:
Les trois premières ont été abordées auparavant. L'attribut spinButtonSnapToTicks détermine si les valeurs erronées sont automatiquement changées vers l'incrément le plus proche (False par défaut). L'attribut spinButtonNumeric détermine si les caractères non-numériques doivent être ignorés (False par défaut) et spinButtonWrap détermine si le bouton compteur doit reboucher sur la plage de valeur lorsque les limites sont dépassées (False par défaut).
L'attribut spinButtonValue est utilisé pour lire la valeur courante ou définir une nouvelle valeur (par défaut 0).
Pour changer la valeur d'un bouton compteur, on peut aussi utiliser:
ou SpinType détermine le type de changement et Double détermine la valeur.
SpinType
possède les constructeurs suivant:
SpinStepForward
SpinStepBackward
SpinPageForward
SpinPageBackward
SpinHome
SpinEnd
SpinUserDefined
Beaucoup de ces réglages utilisent des valeurs de l'objet Adjustment qui est associé au bouton compteur. SpinStepForward et SpinStepBackward changent la valeur du bouton compteur du nombre d'incréments spécifié, à moins qu'il soit égal à 0, auquel cas, la valeur est remplacée par la valeur de stepIncrement. SpinPageForward et SpinPageBackward modifient simplement la valeur du SpinButton par l'incrément. SpinPageHome et SpinPageEnd mettent la valeur respectivement au maximum ou au minimum de la plage de Adjustment. SpinUserDefined modifie la valeur du bouton compteur par la valeur spécifiée.
Un bouton compteur a également une politique de mise à jour:
spinButtonUpdatePolicy :: SpinButtonClass self => Attr self SpinButtonUpdatePolicy
Les constructeurs de SpinButtonUpdatePolicy sont soit UdateAlways ou UpdateIfValid. Ces politiques affectent le comportement d'un SpinButton lorsque qu'un texte est inséré et que sa valeur est synchronisée avec celle de Adjustment. Dans le cas de UpdateIfValid, le bouton compteur est changé seulement si le texte rentré est une valeur numérique dans la plage spécifiée par Adjustment. Dans le cas ou cela n'est pas vrai, le texte est réinitialisé à la valeur courante. Dans le cas de UpdateAlways, les erreurs sont ignorées pendant la conversion du texte en valeur numérique.
Au final, vous pouvez demander explicitement qu'un SpinButton se mette à jour lui-même:
On peut maintenant prendre un nouvel exemple. Voici une capture d'écran après avoir modifié certains réglages:
Les boutons compteurs ont tous été créés avec la fonction suivante qui utilise spinButtonNewWithRange.stepIncrement est toujours fixé à 1.0 et n'est donc pas un paramètre de myAddSpinButton.
Dans la fonction main, on utilise un des boutons compteurs qui existe déjà mais en lui donnant un nouveau paramétrage avec spinButtonConfigure. L'ancienne limite de -1000.0 à 1000.0 est dorénavant remplacée par -100.0 et 100.0 (Notez les parenthèses autour des valeurs négatives). La valeur d'origine est définie à 0.0 et l'incrément à 0.25. L'incrément de page est défini à 10.0. La taille de page (qui n'est pas utilisée ici) est fixée à 0.0.
Le nouveau signal ici est onValueSpinned, qui est émis quand l'utilisateur change la valeur du bouton compteur. Ici, il est utilisé pour contrôler le nombre de décimales qui sont affichées dans le bouton spinLarge. Notez qu'il est nécessaire d'arrondir la valeur pour convertir le Double en en type Integral (entier).
Dans cet exemple, nous avons utilisé les fonctions get et set sur les attributs plutôt que les fonctions spécifiques qui sont également disponibles. C'est la façon de programmer qu'il est recommandé d'utiliser avec Gtk2Hs car dans l'avenir certaines fonctions risqueront d'être obsolètes.