spinbox

 

spinbox - Crée et manipule spinbox widgets


SYNTAXE

 spinbox pathName ?options?

OPTIONS STANDARD


 -activebackground
 -background
 -borderwidth
 -cursor
 -exportselection
 -font
 -foreground
 -highlightbackground
 -highlightcolor
 -highlightthickness
 -insertbackground
 -insertborderwidth
 -insertofftime
 -insertontime
 -insertwidth
 -justify
 -relief
 -repeatdelay
 -repeatinterval
 -selectbackground
 -selectborderwidth
 -selectforeground
 -takefocus
 -textvariable
 -xscrollcommand

OPTIONS SPÉCIFIQUES AU WIDGET


Command-Line Name: -buttonbackground Database Name: buttonBackground Database Class: Background Couleur d'arrière-plan à utiliser pour les boutons spin.

Command-Line Name: -buttoncursor Database Name: buttonCursor Database Class: Cursor Curseur à utiliser au-dessus des boutons spin. Si vide (par défaut), le curseur par défaut sera utilisé.

Command-Line Name: -buttondownrelief Database Name: buttonDownRelief Database Class: Relief Relief à utiliser pour le bouton spin inférieur.

Command-Line Name: -buttonuprelief Database Name: buttonUpRelief Database Class: Relief Relief à utiliser pour le bouton spin supérieur.

Command-Line Name: -command Database Name: command Database Class: Command Indique la commande Tcl à appeler chaque fois que le spinbutton est appelé. La commande reconnaît plusieurs substitutions pourcentage: %W pour le chemin du widget path, %s pour la valeur courante du widget, et %d pour la direction du bouton cliqué(up ou down).

Command-Line Name: -disabledbackground Database Name: disabledBackground Database Class: DisabledBackground Indique la couleur d'arrière-plan à utiliser quand le spinbox est désactivé. Si cette option est une chaîne vide, la couleur normale d'arrière-plan est utilisée.

Command-Line Name: -disabledforeground Database Name: disabledForeground Database Class: DisabledForeground Indique la couleur de premier plan à utiliser quand le spinbox est désactivé. Si cette option est une chaîne vide, la couleur normale de premier plan est utilisée.

Command-Line Name: -format Database Name: format Database Class: format Indique un format alternatif à utiliser en fixant la valeur chaîne à l'utilisation de l'étendue de -from à -to . Doit être un spécificateur de format de la forme%<pad>.<pad>f, car doit formater un nombre flottant.

Command-Line Name: -from Database Name: from Database Class: From Valeur flottante correspondant à la valeur la plus basse d'un spinbox, à utiliser en conjonction avec -to et -increment. Quand tous sont spécifiés correctement, le spinbox utilisera ces valeurs pour contrôler son contenu. Cette valeur doit être inférieure à l'option -to. Si -values est spécifié, ecrase cette option.

Command-Line Name: -invalidcommand ou -invcmd Database Name: invalidCommand Database Class: InvalidCommand Indique le script à évaluer quand validateCommand retourne 0. Le positionner à une chaîne vide désactive cette fonctionnalité (par défaut). Le meilleur usage de cette option est de la fixer à bell. Voir Validation ci-dessous pour plus d'information.

Command-Line Name: -increment Database Name: increment Database Class: Increment Valeur flottante donnant l'incrément. Quand elle est utilisée avec -from et -to, la valeur dans le widget sera ajustée de -increment quand on clique sur un spin bouton (up ajoute la valeur, down la soustrait).

Command-Line Name: -readonlybackground Database Name: readonlyBackground Database Class: ReadonlyBackground Indique la couleur d'arrière-plan à utiliser quand le spinbox est en lecture seule. Si cette option est une chaîne vide, la couleur normale d'arrière-plan est utilisée.

Command-Line Name: -state Database Name: state Database Class: State Indique un des trois états du spinbox: normal, disabled, ou readonly. Si le spinbox est en lecture seule, alors la valeur ne sera pas modifiée en utilisant les commandes widget et aucun curseur d'insertion ne sera affiché, même si le focus est dans le widget; le contenu du widget sera néanmoins sélectionné. Si le spinbox est désactivé, la valeur ne sera pas modifiée, aucun curseur d'insertion ne sera affiché, le contenu ne sera pas sélectionnable, et le spinbox sera affiché d'une couleur différente, dépendante des valeurs des options -disabledforeground et -disabledbackground.

Command-Line Name: -to Database Name: to Database Class: To Valeur flottante correspondant à la plus haute valeur du spinbox, à utiliser en conjonction avec -from et -increment. Quand toutes les valeurs seront spécifiées correctement, le spinbox les utilisera pour contrôler son contenu. Cette valeur doit être supérieure à l'option-from . Si -values est spécifié, écrase cette option.

Command-Line Name: -validate Database Name: validate Database Class: Validate Indique le mode dans lequel validation opère: none, focus, focusin, focusout, key, ou all. Est par défaut de none. Quand vous désirez une validation, vous devez explicitement indiquer le mode que vous souhaitez utiliser. Voir Validation ci-dessous.

Command-Line Name: -validatecommand ou -vcmd Database Name: validateCommand Database Class: ValidateCommand Indique le script à évaluer quand vous désirez valider la valeur du widget. Le positionner à une chaîne vide désactive cette fonctionnalité (par défaut). La validation se produit en accord avec la valeur de -validate. cette commande doit retourner une valeur Tcl valide. Si elle retourne 0 (ou l'équivalent booléen Tcl valide ) alors la valeur du widget ne changera pas et invalidCommand sera evalué si elle est fixée. Si elle retourne 1, alors la valeur sera modifiée. Voir Validation ci-dessous pour une plus ample information.

Command-Line Name: -values Database Name: values Database Class: Values Doit être une valeur de liste correcte. Si spécifiée, le spinbox utilisera ces valeurs pour contrôler son contenu, commençant avec la première valeur. Cette option a précédence sur l'étendue -from et -to.

Command-Line Name: -width Database Name: width Database Class: Width Indique une valeur entière indiquant la largeur désirée de la fenêtre spinbox, en taille de caractères de la police du widget. Si la valeur est inférieure ou égale à zéro, le widget prend la taille juste suffisante pour contenir son texte courant.

Command-Line Name: -wrap Database Name: wrap Database Class: wrap Doit être une valeur booléenne correcte. Si vraie, le spinbox passe à la ligne.


DESCRIPTION


La commande spinbox crée une nouvelle fenêtre (indiquée par l'argument pathName) en en fait un widget spinbox. Des options supplémentaires, décrites ci-dessus, peuvent être spécifiées sur la ligne de commande ou dans la base de données d'options pour configurer des aspects du spinbox comme ses couleurs, fontes, et relief. La commande spinbox retourne son argument pathName. A l'instant ou cette commande est appelée, il ne doit pas exister de fenêtre nommée pathName, mais son parent doit exister.

Un spinbox est un widget entry qui permet à l'utilisateur de se déplacer, ou 'spin', parmi un ensemble de valeurs ascendantes ou descendantes comme des heures ou des dates en éditant la valeur comme dans un entry. A sa création, la chaîne du spinbox est vide. Une partie du spinbox peut être sélectionnée comme décrit ci-dessous. Si un spinbox exporte sa sélection (voir l'option exportSelection ), alors il respecte les protocoles standards pour gérer la sélection; les sélections spinbox sont disponibles entant que type string. Les spinbox respectent également les règles standard Tk pour la gestion du focus d'entrée. Quand un spinbox a le focus il affiche un curseur d'insertion pour indiquer où les nouveaux caractères seront insérés.

Les spinbox sont capables d'afficher des chaînes qui sont trop longues pour tenir entièrement à l'intérieur du widget. Dans ce cas, seule une partie de la chaîne sera affichée; les commandes décrites ci-dessous peuvent être utilisées pour changer la vue dans la fenêtre. Les spinbox utilisent le mécanisme standard xScrollCommand pour interagir avec les scrollbars (voir la description de l'option xScrollCommand pour les détails). Ils supportent également le scan, comme décrit ci-dessous.


VALIDATION


La validation fonctionne en positionnant l'option validateCommand vers un script qui sera évalué conformément à l'option validate comme suit:

none Default. Aucune validation.

focus validateCommand sera appelée quand le spinbox reçoit ou perd le focus.

focusin validateCommand sera appelée quand le spinbox reçoit le focus.

focusout validateCommand sera appelée quand le spinbox perd le focus.

key validateCommand sera appelée quand le spinbox est édité.

all validateCommand sera appelée pour toutes les conditions ci-dessus.

Il est posible d'utiliser les substitutions pourcentage pour les validateCommand et invalidCommand, comme vous pourriez le faire pour un script bind. Les substitutions suivantes sont admises:

%d Type de l'action: 1 pour insert, 0 pour delete, ou -1 pour une validation focus, forced ou textvariable .

%i Index du caractère à insérer/effacer, s'il existe, autrement -1.

%P La valeur que le spinbox doit prendre. Si vous configurez une nouvelle textvariable pour le spinbox, ce sera la valeur de cette textvariable.

%s La valeur courante du spinbox avant édition.

%S La chaîne à insérer/effacer, si elle existe. Autrement une chaîne vide.

%v Le type de validation en cours.

%V Le type de validation qui a déclenché le callback (key, focusin, focusout, forced).

%W Le nom du spinbox.

En général, textVariable et validateCommand peuvent être dangereuses à mélanger. Tous les problèmes sont evités en ne faisant pas interférer validateCommand avec le comportement traditionnel du widget spinbox. L'utilisation de textVariable en lecture seule ne cause jamais de problèmes. Le danger serait de positionner textVariable à une valeur que validateCommand n'accepterait pas, ce qui fixerait validate à none ( invalidCommand ne sera pas déclenchée). La même chose arrive quand une erreur se produit pendant l'évaluation de validateCommand.

Premièrement, une erreur se produira quand validateCommand ou invalidCommand rencontrent une erreur pendant l'évaluation de leurs script ou que validateCommand ne retourne pas une valeur booléenne Tcl valide. L'option validate se positionnera elle-même à none quand vous éditez le spinbox soit à l'intérieur de validateCommand ou de invalidCommand. De telles éditions surchargeraient celle en cours de validation. Si vous souhaitez éditer la valeur du widget pendant la validation et conserver l'option validate, vous devrez inclure la commande

 ''%W config -validate %v''

dans validateCommand ou invalidCommand (selon celle à partir de laquelle vous éditiez le spinbox). Il est également recommandé de ne pas modifier la textVariable associée pendant la validation, ce qui désynchroniserait le spinbox de sa textVariable.


COMMANDES DE WIDGET


La commande spinbox crée une nouvelle commande Tcl dont le nom est pathName. cette commande peut être utilisée pour appeler diverses opérations sur le widget. Elle a la forme générale suivante:

 ''pathName option ''?''arg arg ...''?

Option et les args déterminent le comportement exact de la commande.

Plusieurs des commandes widget des spinbox attendent un ou plusieurs indices comme arguments. Un index indique un caractère particulier dans la chaîne du spinbox, d'une des façons suivantes:

numéro Indique le caractère comme index numérique, où 0 correspond au premier caractère de la chaîne.

anchor Indique le point d'ancrage de la sélection, qui est fixé avec les commandes select from et select ajuste.

end Indique le caractère juste après le dernier dans la chaîne du spinbox. Équivalent à la spécification d'un index numérique égal à la longueur de la chaîne du spinbox.

insert Indique le caractère adjacent au et immédiatement suivant le curseur d'insertion.

sel.first Indique le premier caractère de la sélection. C'est une erreur d'utiliser cette forme si la sélection n'est pas dans le spinbox.

sel.last Indique le caractère juste après le dernier de la sélection. C'est une erreur d'utiliser cette forme si la sélection n'est pas dans le spinbox.

@nombre Sous cette forme, nombre est traité comme coordonnée x dans le spinbox; le caractère occupant cette coordonnée x est utilisé. Par exemple, ``@0'' indique le caractère le plus à gauche dans la fenêtre.

Des abréviations peuvent être utilisées pour n'importe quelle des formes ci-dessus, ex. ``e ou ``sel.f. En général, les indices hors de l'étendue sont automatiquement arrondis à la valeur autorisée la plus proche.

La commandes suivantes sont possible pour les spinbox:

pathName bbox index Retourne une liste of quatre nombres décrivant les coordonnées de confinement du caractère indiqué par index. Les deux premiers éléments de la liste donnent les coordonnées x et y du coin supérieur gauche de la zone écran occupée par le caractère (en pixels relatifs au widget) et les deux derniers éléments donnent la largeur et hauteur du caractère, en pixels. La boite de confinement peut référencer une région en dehors de la partie visible de la fenêtre.

pathName cget option Retourne la valeur courante de l'option de configuration indiquée par option. Option peut prendre n'importe quelle des valeurs acceptées par la commande spinbox.

pathName configure ?option? ?valeur option valeur ...? Interroge ou modifie les options de configuration du widget. Si aucune option n'est spécifiée, retourne une liste décrivant toutes les options disponibles pour pathName (voir ConfigWidg pour une information sur le format de cette liste). Si option est spécifiée sans valeur, alors la commande retourne une liste décrivant l'option désignée (cette liste sera identique à la correspondante sous-liste de la valeur retournée si aucune option n'est spécifiée). Si une ou plusieurs paires option-valeur sont spécifiés, alors la commande donne aux option(s) les valeur(s) indiquées; dans ce cas la commande retourne une chaîne vide. Option peut prendre n'importe quelle des valeurs acceptées par la commande spinbox.

pathName delete premier?last? Efface un ou plusieurs éléments du spinbox. First est l'index du premier caractère à effacer, et last est l'index du caractère juste après le dernier à effacer. Si last n'est pas spécifié il est par défaut de first+1, c.a.d. un seul caractère est effacé. cette commande retourne une chaîne vide.

pathName get Retourne la chaîne du spinbox.

pathName icursor index Prépare le curseur d'insertion à être affiché juset avant le caractère indiqué par index. Retourne une chaîne vide.

pathName identify x y Retourne le nom de l'élément de fenêtre correspondant aux coordonnées x et y dans le spinbox. La valeur retournée est une de: none, spindown, spinup, entry.

pathName index index Retourne l'index numérique correspondant à index.

pathName insert index chaîne Insère les caractères de chaîne juste avant le caractère indiqué par index. Retourne une chaîne vide.

pathName invoke élément Provoque l'appel de l'élément spécifié, soit spindown soit spinup, et déclenche l'action associée.

pathName scan option args cette commande est utilisée pour implémenter le balayage des spinbox. Elle a deux formes, dépendantes de option:

pathName scan mark x Enregistre x et la vue courante dans le spinbox; utilisée en conjonction avec des commandes scan dragto ultérieures. Généralement cette commande est associée avec un clic de souris dans le widget. Elle retourne une chaîne vide.

pathName scan dragto x Cette commande calcule la différence entre son argument x et l'argument x de la dernière commande scan mark du widget. Elle ajuste alors la vue à gauche ou à droite de 10 fois la différence en coordonnées x. cette commande est généralement associée à des événements déplacement de souris dans le widget, pour produire un effet de glissement du spinbox à grande vitesse au travers de la fenêtre. La valeur de retour est une chaîne vide.

pathName selectionoption arg cette commande est utilisée pour ajuster la sélection à l'intérieur d'un spinbox. Elle a plusieurs formes, dépendantes de option:

pathName selection ajuste index Localise la fin de la sélection la plus proche du caractère indiqué par index, et ajuste cette fin de sélection à index (ex. incluant mais pas au-delà d'index). L'autre extrémité de la sélection sera le point d'ancrage pour les commandes select to futures. Si la sélection n'est pas actuellement dans le spinbox, alors une nouvelle sélection est créé pour inclure les caractères entre index et le plus récent point d'ancrage de la sélection, inclus. Retourne une chaîne vide.

pathName selection clear Efface la sélection si elle est actuellement dans ce widget. Si la sélection n'est pas dans ce widget alors la commande n'a pas d'effet. Retourne une chaîne vide.

pathName selection élement ?élément? Fixe ou lit l'élément actuellement sélectionné. Si un élément spinbutton est spécifié, il sera affiché enfoncé.

pathName selection fromindex Fixe le point d'ancrage de la sélection juste avant le caractère indiqué par index. Ne change pas la sélection. Retourne une chaîne vide.

pathName selection present Retourne 1 s'il y a des caractères sélectionnés dans le spinbox, 0 si rien est sélectionné.

pathName selection rangestart end Fixe la sélection en incluant les caractères commençant par celui indexé par start et finissant avec celui juste avant end. Si end se réfère au même caractère que start ou un précédent, alors la sélection du spinbox est effacée.

pathName selection to index Si index est avant le point d'ancrage, fixe la sélection aux caractères de index jusqu'au mais non inclus le point d'ancrage. Si index est le même que le point d'ancrage, ne fait rien. Si index est après le point d'ancrage, fixe la sélection aux caractères depuis le point d'ancrage jusqu'à mais non inclus index. Le point d'ancrage est déterminé par la commande select from ou select adjustla plus récente dans ce widget. Si la sélection n'est pas dans ce widget alors un nouvelle sélection est créée en utilisant le plus récent point d'ancrage spécifié pour le widget. Retourne une chaîne vide.

pathName set ?chaîne? Si chaîne est spécifiée, le spinbox tentera de fixer son contenu à cette valeur, autrement il retourne juste la chaîne du spinbox. Si la validation est active, elle se produira quand la chaîne sera fixée.

pathName validate cette commande est utilisée pour forcer une évaluation de validateCommand indépendante des conditions spécifiées par l'option validate. Ceci est réalisé en fixant temporairement l'option validate à all. Retourne 0 ou 1.

pathName xview args cette commande est utilisée pour consulter et changer la position horizontale du texte dans la fenêtre du widget. Elle peut prendre n'importe quelle des formes suivantes:

pathName xview Retourne une liste de deux éléments. Chaque élément est une fraction réelle entre 0 et 1; ensemble ils decrivent la partie horizontale visible dans la fenêtre. Par exemple, si le premier élément est .2 et le second élément est .6, 20% du texte du spinbox est hors écran à gauche, les 40% du milieu sont visibles dans la fenêtre, et 40% du texte est hors écran à droite. Ce sont les même valeurs transmises aux scrollbars via l'option -xscrollcommand.

pathName xview index Ajuste la vue dans la fenêtre, le caractère indiqué par index est affiché à l'extrémité gauche de la fenêtre.

pathName xview moveto fraction Ajuste la vue dans la fenêtre, le caractère fraction du texte apparaît à l'extrémité gauche de la fenêtre. Fraction doit être une fraction entre 0 et 1.

pathName xview scroll nombre what cette commande décale la vue dans la fenêtre à gauche ou à droite en accord avec nombre et what. Nombre doit être un entier. What doit être soit unités ou pages ou une abréviation de l'un des deux. Si what est unités, la vue se décale à gauche ou à droite de nombre taille moyenne des caractères à l'écran; si il est pages alors la vue se décale de nombre écrans. Si nombre est négatif alors les caractères les plus à gauche deviennent visibles; si il est positif alors les caractères les plus à droite deviennent visibles.


BINDINGS PAR DÉFAUT


Tk crée automatiquement des bindings de classe pour les spinbox qui leur donne le comportement par défaut suivant. Dans les descriptions ci-dessous, ``word se réfère à un groupe contigu de lettres, chiffres, ou caractères``_ , ou n'importe quel caractère autre que ceux-ci.

[1] Cliquer sur le bouton 1 de la souris positionne le curseur d'insertion juste avant le caractère sous le curseur de la souris, place le focus d'entrée dans ce widget, et efface toute sélection dans le widget. Glisser avec le bouton1 de la souris produit une sélection entre le curseur d'insertion et le caractère sous la souris.

[2] Double cliquer avec le bouton 1 de la souris sélectionne le mot sous la souris et positionne le curseur d'insertion au début du mot. Glisser après un double clic déplace la sélection du mot sélectionné.

[3] Triple cliquer avec le bouton1 de la souris sélectionne tout le texte et positionne le curseur d'insertion avant le premier caractère.

[4] La fin de la sélection peut être ajustée en glissant avec le bouton 1 de la souris et en appuyant sur la touche Shift; ceci ajustera la fin de la sélection proche du curseur de la souris quand le bouton 1 a été cliqué. Si le bouton est double-cliqué avant de glisser alors la sélection sera ajustée en unités de mots entiers.

[5] Cliquer sur le bouton1 de la souris avec la touche Contrôle enfoncée positionne le curseur d'insertion dans le spinbox sans affecter la sélection.

[6] Si quelconques caractères imprimables sont saisis dans un spinbox, ils sont insérés à l'emplacement du curseur d'insertion.

[7] La vue dans le spinbox peut être ajustée en cliquant-tirant avec le bouton 2 de la souris. Si le bouton 2 de la souris est cliqué sans déplacer la souris, la sélection est copiée dans le spinbox à la position du curseur de la souris.

[8] Si la souris est déplacée hors du spinbox sur la gauche ou la droite alors que le bouton 1 est enfoncé, l'entrée de texte "scrolle" automatiquement pour rendre le texte visible (s'il y a plus de texte hors écran du coté ou la souris est sortie de la fenêtre).

[9] Les touches flèche Droite et flèche Gauche déplacent le curseur d'insertion d'un caractère vers la gauche ou la droite; elles effacent également toute sélection dans le spinbox et positionnent le point de sélection. Si les touches flèche Droite ou flèche Gauche sont tapées avec la touche Shift enfoncée, alors le curseur d'insertion se déplace et la sélection est étendue au caractère suivant. Control-Gauche et Control-Droite déplacent le curseur d'insertion d'un mot, et Control-Shift-Gauche et Control-Shift-Droite déplacent le curseur d'insertion d'un mot et étendent également la sélection. Control-b et Control-f se comportent de même que flèche Gauche et flèche Droite, respectivement. Meta-b et Meta-f se comportent de même que Control-Gauche et Control-Droite, respectivement.

[10] La touche Home, ou Control-a, déplace le curseur d'insertion au début du spinbox et efface toute sélection du spinbox. Shift-Home déplace le curseur d'insertion au début du spinbox et étend également la sélection jusqu'à ce point.

[11] La touche Fin, ou Control-e, déplace le curseur d'insertion à la fin du spinbox et efface toute sélection du spinbox. Shift-End déplace le curseur à la fin et étend la sélection jusqu'à ce point.

[12] Les touches Select et Control-Espace positionnent le point de sélection à la position du curseur d'insertion. Elles n'affectent pas la sélection courante. Shift-Select et Control-Shift-Space ajustent la sélection à la position courante du curseur d'insertion, en sélectionnant du point de sélection jusqu'au curseur d'insertion s'il n'existait pas de sélection précédemment.

[13] Control-/ sélectionne tout le texte dans le spinbox.

[14] Control-\ efface toute sélection dans le spinbox.

[15] La touche F16 (marquée Copy sur de nombreuses stations Sun) ou Meta-w copie la sélection du widget vers le presse-papier, s'il y a une sélection.

[16] La touche F20 (marquée Cut sur de nombreuses stations Sun) ou Control-w coupe la sélection du widget vers le presse-papier. S'il n'y a pas de sélection dans le widget alors ces touches n'ont pas d'effet.

[17] La touche F18 (marquée Paste sur de nombreuses stations Sun) ou Control-y insère le contenu du presse-papier à la position du curseur d'insertion.

[18] La touche Delete efface la sélection, s'il y en a une, du spinbox. S'il n'y a pas de sélection, elle efface le caractère à droite du curseur d'insertion.

[19] Les touche BackSpace et Control-h effacent la sélection, s'il y en a une, du spinbox. S'il n'y a pas de sélection, efface le caractère à gauche du curseur d'insertion.

[20] Control-d efface le caractère à droite du curseur d'insertion.

[21] Meta-d efface le mot à droite du curseur d'insertion.

[22] Control-k efface tous les caractères à droite du curseur d'insertion.

[23] Control-t inverse l'ordre des deux caractères à droite du curseur d'insertion.

Si le spinbox est désactivé en utilisant l'option -state , alors la vue du spinbox peut toujours être ajustée et le texte dans le spinbox peut toujours être sélectionné, mais aucun curseur d'insertion ne sera affiché et aucune modification de texte ne se produira.

Le comportement des spinbox peut être changé en définissant de nouveaux bindings pour des widgets individuels ou en redéfinissant les bindings de classe.


Traduit par Michel Salvagniac 2002-2003

Copyright © 2003 - Le Wiki Tcl/Tk Francophone.


VOIR ÉGALEMENT


Catégorie Manuel Tcl/Tk