OOUI/Toolbars/fr

Barres d'outils
Les barres d'outils sont des composants complexes d'interface qui permettent aux utilisateurs d'accéder facilement à une variété d'outils (comme les commandes de mise en forme) et d'actions. Ces outils sont des commandes supplémentaires faisant partie de la barre d'outils mais ils ne sont pas configurés comme telles.

Les développeurs créent et personnalisent les outils individuels puis les enregistrent avec une ToolFactory, qui crée les outils à la demande. Chaque outil a un nom symbolique (utilisé lors de son enregistrement), un titre (par exemple, ‘Insérer une image’), et une icône.

Les outils individuels sont organisés en groupes d'outils et affichés dans les menus, les listes ou une unique barre d'outils. Vous pouvez personnaliser l'organisation et l'ordre des groupes quand vous configurez la barre d'outils. Les outils peuvent apparaître dans n'importe quel ordre mais chaque outil ne peut figurer qu'une fois dans la barre d'outils.

Vous trouverez ci-après un exemple basique de barre d'outils. Nous détaillerons plus précisément chaque composant de cet exemple ultérieurement dans cette documentation. Pour avoir un aperçu réel de cette démonstration, voir la documentation du code générée.

Outils
Les outils sont créés par l'extension de la classe abstraite Tools ou l'une de ses sous-classes PopupTool ou ToolGroupTool. Chaque outil doit être configuré avec les propriétés de nom statique, de titre et d'icône :


 * &mdash; Le nom symbolique est utilisé en interne pour enregistrer l'outil via ToolFactory. Les outils doivent être enregistrés via une usine d'outils (tool factory) avant de pouvoir être utilisés dans une barre d'outils.
 * &mdash; Le texte du titre est utilisé de différentes manières en fonction du type de groupe dans lequel l'outil est placé
 * le groupe des barres d'outils ToolBarGroup, le groupe des barres de menus ToolMenuGroup, ou le groupe des listes d'outils ToolListGroup. Pour les groupes d'outils de type 'bar' où il n'y a qu'une icône pour identifier l'outil, le texte du titre est utilisé comme une bulle d'aide affichée quand l'utilisateur survole l’outil avec la souris. Pour les groupes d'outils de type 'list', le texte du titre est utilisé pour identifier les outils dans les menus déroulants de l'interface utilisateur. Si un raccouci a été défini pour l'outil, il sera automatiquement affiché. Pour les groupes d'outils de type 'bar', le raccourci clavier est affiché dans une bulle; pour les outils des groupes de type 'menu' et 'list', le raccouci apparait à droite de chaque élément du menu déroulant.


 * &mdash; L'icône est aussi utilisée de différentes manières en fonction du type de groupe dans lequel se trouve l'outil. Pour les groupes d'outils de type 'bar', l'icône est affichée dans la barre d'outils afin d'identifier ces derniers. Pour les groupes d'outils de type 'list', l'icône est affichée à côté du texte du titre dans le menu déroulant. Pour les groupes d'outils de type 'menu', l'icône est ignorée.

En plus des propriétés statiques, les outils doivent aussi implémenter les méthodes suivantes :


 * onSelect &mdash; utilisé pour spécifier l'action réalisée par l'outil quand il est sélectionné
 * onUpdateState &mdash; utilisé pour synchroniser l'état de l'outil avec l'état de son contexte le plus grand. Par exemple cette méthode peut être utilisée pour sélectionner l'outil 'bold’ de la barre d'outil quand le curseur du texte est placé dans une zone de texte en gras.

Les outils peuvent aussi être configurés avec la propriété statique 'group' qui pourra être utilisée ultérieurement quand l'outil sera ajouté dans une barre, un menu ou à une liste de groupe d'outils (voir ToolGroups pour un exemple de réalisation) :

For a complete list of supported methods and configuration options, please see the code-level documentation for the Tool class.

PopupTool
Popup tools open a popup window when they are selected from the toolbar. Unlike standard tools, popup tools do not require that developers specify an  or   method, as these methods have been implemented already.

La liste complète des méthodes prises en charge ainsi que les options de configuration, sont décrites dans la documentation du code pour la classe PopupTool.

ToolGroupTool
A ToolGroupTool is a special sort of tool that can contain other tools and toolgroups. The ToolGroupTool was specifically designed to be used inside a ‘bar’ toolgroup to provide access to additional tools from the bar item.

For a complete list of supported methods and configuration options, please see the code-level documentation for the ToolGroupTool class.

ToolGroups
Tools are organized into toolgroups, which are created by a ToolGroupFactory and then added to the toolbar when the toolbar is set up. Individual tools can be added to any type of toolgroup (bar, list, or menu). The type of toolgroup determines how the included tools are arranged in the toolbar:
 * &mdash; Tools are displayed by icon in a single row.
 * &mdash; Tools are displayed with a label and icon in a dropdown menu. The tool's title is used as the label text. The list can be configured to be collapsed and expanded with the allowCollapse config.
 * &mdash; Tools are displayed by label in a dropdown menu. The tool's title is used as the label text. ‘menu’ tool groups are generally used for sets of mutually exclusive tools, such as a group of text formatting commands (paragraph, heading, etc).

Tools can be added to a toolgroup in one of several ways: by symbolic name, by group name, or with the ' * ' (asterisk) catch-all:

Add tools by :

Add tools by. A tool's group name is specified with the tool's static 'group' property (see Tools for an example).

Add tools with the :

Developers can further curate the arrangement of the tools using the toolgroup’s  and   configuration options, which will arrange the tools at the top of the tool list (or front of the toolbar) or end, respectively. These settings are particularly useful when tools have been added to the toolbar en masse (e.g., with the asterisk catch-all or when a group of tools is added to a toolgroup) to manage their priority.

BarToolGroup
Tools in a   are displayed by icon in a single row. The title of the tool is displayed when users move the mouse over the tool.

For a complete list of supported methods and configuration options, please see the code-level documentation for the BarToolGroup class.

ListToolGroup
Tools in a   are displayed by icon and label in a dropdown menu. The tool's title is used as the label text. List groups can be configured to be expanded and collapsed. Collapsed lists will have a ‘More’ option that users can select to see the full list of tools. If a collapsed toolgroup is expanded, a ‘Fewer’ option permits users to collapse the list again.

In addition to a,   can also be configured with a   and  :

Use the  config to designate tools as collapsible (‘help’ and ‘stuff’, in the following example). By default, the list opens in its collapsed state, and users must click the 'More' option to see the collapsed tools:

To display a collapsible list in its expanded state when the list is opened, set the  config to  :

Alternatively, you may wish to specify the names of tools that should never be collapsed. This is done with the  config. In the following example, only the ‘help’ tool has been designated as expanded; all other tools are collapsed by default.

For a complete list of supported methods and configuration options, please see the code-level documentation for the ListToolGroup class.

MenuToolGroup
Tools in  s are displayed by label in a dropdown menu. The tool's title is used as the label text, and the menu label is updated to reflect which tool or tools are currently selected. Note that all tools must define an  method if a   is used.



Configurer la barre d'outils
In addition to containing toolgroups, the toolbar can be configured with actions, CSS, accelerator keys, and/or an optional shadow.

Note that ‘actions’ in the context of the toolbar are different from ActionWidgets. For toolbars, ‘actions’ refers to an empty container that is right-aligned and can contain whatever you’d like.



Ajouter des groupes d'outils
Toolgroups are added to the toolbar with the toolbar's  method:

Adding actions
Toolbars have an optional 'actions' area, which contains commands that are available to users but are not configured as tools. In the following example, the toolbar has been configured to use actions, in this case two additional buttons, ‘Action’ and ‘Disabled’. For the purpose of brevity, only the action-specific code is included in the example (the rest is just the same as the basic toolbar).



Utiliser CSS pour formater l'étiquette des outils
Tool labels can be styled with built-in CSS classes that are named after each tool: oo-ui-tool-name-&lt;symbolic name of tool> (e.g., oo-ui-tool-name-picture). The following example uses CSS classes to customize the appearance of the 'picture' and the 'help' tool labels.





Utiliser les touches de raccourci
The OOUI library does not contain an accelerator system, but the Toolbar class does contain a hook for one. To use an accelerator system, subclass the toolbar and override the  method, which is meant to return a label that describes the accelerator keys for the tool passed (by symbolic name) to the method.

Accelerator labels (e.g., Ctrl + M ) are displayed in different ways depending on the type of toolgroup used:


 * For bar toolgroups, the accelerator label appears in the tooltip displayed when users move the mouse over the tool.
 * For menu and list toolgroups, the accelerator label is right-aligned and rendered in gray text, which still complies to WCAG level AA.

Building the toolbar
The toolbar must be appended to the document before it can be built. Once it is appended, the toolbar can be initialized:

For a complete list of supported methods and configuration options, please see the code-level documentation for Toolbars.