Cette page a été traduite par l'API Cloud Translation.

Ressource de menu

Une ressource de menu définit un menu d'application (menu d'options, menu contextuel ou sous-menu) qui peut être gonflé avec MenuInflater.

Pour découvrir comment utiliser les menus, consultez la section Ajouter des menus.

Emplacement du fichier :

res/menu/filename.xml
Le nom de fichier est utilisé comme ID de ressource.

Type de données de la ressource compilée :

Pointeur vers une ressource (ou sous-classe) Menu.

Référence de la ressource :

En Java : R.menu.filename
En XML : @[package:]menu.filename

Syntaxe :

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@[+][package:]id/resource_name"
          android:title="string"
          android:titleCondensed="string"
          android:icon="@[package:]drawable/drawable_resource_name"
          android:onClick="method name"
          android:showAsAction=["ifRoom" | "never" | "withText" | "always" | "collapseActionView"]
          android:actionLayout="@[package:]layout/layout_resource_name"
          android:actionViewClass="class name"
          android:actionProviderClass="class name"
          android:alphabeticShortcut="string"
          android:alphabeticModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:numericShortcut="string"
          android:numericModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:checkable=["true" | "false"]
          android:visible=["true" | "false"]
          android:enabled=["true" | "false"]
          android:menuCategory=["container" | "system" | "secondary" | "alternative"]
          android:orderInCategory="integer" />
    <group android:id="@[+][package:]id/resource name"
           android:checkableBehavior=["none" | "all" | "single"]
           android:visible=["true" | "false"]
           android:enabled=["true" | "false"]
           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
           android:orderInCategory="integer" >
        <item />
    </group>
    <item >
        <menu>
          <item />
        </menu>
    </item>
</menu>

Éléments :

<menu>

Obligatoire. Il doit s'agir du nœud racine. Contient des éléments <item> et/ou <group>.

Attributs :

xmlns:android: Espace de noms XML. Obligatoire. Définit l'espace de noms XML, qui doit être "http://schemas.android.com/apk/res/android".

<item>

Élément de menu. Peut contenir un élément <menu> (pour un sous-menu). Doit être l'enfant d'un élément <menu> ou <group>.

Attributs :

android:id

ID de ressource. ID de ressource unique. Pour créer un ID de ressource pour cet élément, utilisez le format suivant : "@+id/name". Le signe plus indique qu'il s'agit d'un nouvel ID.

android:title

Ressource de chaîne. Titre du menu en tant que ressource de chaîne ou chaîne brute.

android:titleCondensed

Ressource de chaîne. Titre condensé en tant que ressource de chaîne ou chaîne brute. Ce titre est utilisé lorsque le titre normal est trop long.

android:icon

Ressource drawable. Image utilisée comme icône d'élément de menu.

android:onClick

Nom de la méthode. Méthode à appeler lorsque l'utilisateur clique sur cet élément de menu. La méthode doit être déclarée dans l'activité comme publique. Elle accepte MenuItem comme seul paramètre unique, ce qui indique que l'élément a enregistré un clic. Cette méthode est prioritaire sur le rappel standard de onOptionsItemSelected(). Consultez l'exemple au bas de cette page.

Avertissement : Si vous obscurcissez votre code avec ProGuard (ou un outil similaire), veillez à ne pas renommer la méthode que vous spécifiez dans cet attribut, car cela pourrait briser la fonctionnalité.

Introduit dans le niveau d'API 11.

android:showAsAction

Mot clé. Indique quand et comment cet élément doit apparaître comme une tâche dans la barre d'application. Une tâche ne peut s'afficher en tant que telle que si l'activité inclut une barre d'application. Valeurs correctes :

Valeur	Description
`ifRoom`	Ne placez cet élément dans la barre d'application que si l'espace est suffisant. S'il n'y a pas assez de place pour tous les éléments marqués `"ifRoom"` : ceux ayant les valeurs `orderInCategory` les plus faibles sont affichés en tant qu'actions, tandis que les autres apparaissent dans le menu à développer.
`withText`	Incluez également le texte du titre (défini par `android:title`) avec la tâche. Vous pouvez inclure cette valeur avec l'une des autres en tant qu'indicateur défini, en les séparant par une barre verticale `\|`.
`never`	Ne placez jamais cet élément dans la barre d'application, mais plutôt dans le menu à développer.
`always`	Placez toujours cet élément dans la barre d'application. Évitez de l'utiliser, sauf s'il est essentiel que l'élément apparaisse toujours dans la barre d'action. Si vous configurez plusieurs éléments pour qu'ils apparaissent toujours en tant qu'actions, ils risquent de se chevaucher avec d'autres interfaces de la barre d'application.
`collapseActionView`	La vue d'action associée à cette tâche (déclarée par `android:actionLayout` ou `android:actionViewClass`) peut être réduite. Introduit au niveau d'API 14.

Pour en savoir plus, consultez la section Ajouter la barre d'application.

Introduit dans le niveau d'API 11.

android:actionLayout

Ressource de mise en page. Mise en page à utiliser comme vue d'action.

Pour en savoir plus, consultez la section Utiliser des vues d'action et des fournisseurs d'action.

Introduit dans le niveau d'API 11.

android:actionViewClass

Nom de classe. Nom de classe complet de l'élément View à utiliser comme vue d'action. Par exemple, "android.widget.SearchView" permet d'utiliser SearchView comme vue d'action.

Pour en savoir plus, consultez la section Utiliser des vues d'action et des fournisseurs d'action.

Avertissement : Si vous obscurcissez votre code avec ProGuard (ou un outil similaire), veillez à ne pas renommer la classe que vous spécifiez dans cet attribut, car cela pourrait briser la fonctionnalité.

Introduit dans le niveau d'API 11.

android:actionProviderClass

Nom de classe. Nom de classe complet pour l'élément ActionProvider à utiliser à la place de la tâche. Par exemple, "android.widget.ShareActionProvider" pour utiliser ShareActionProvider.

Pour en savoir plus, consultez la section Utiliser des vues d'action et des fournisseurs d'action.

Introduit dans le niveau d'API 14.

android:alphabeticShortcut

Caractère. Caractère de la touche de raccourci alphabétique.

android:numericShortcut

Nombre entier. Chiffre correspondant à la touche de raccourci numérique.

android:alphabeticModifiers

Mot clé. Modificateur du raccourci alphabétique de l'élément de menu. La valeur par défaut correspond à la touche Ctrl. Valeurs correctes :

Valeur	Description
`META`	Correspond à la touche méta `Méta`.
`CTRL`	Correspond à la touche méta `Ctrl`.
`ALT`	Correspond à la touche méta `Alt`
`MAJ`	Correspond à la touche méta `Maj`
`SYM`	Correspond à la touche méta `Sym`.
`FUNCTION`	Correspond à la touche méta `Fonction`

Remarque : Vous pouvez spécifier plusieurs mots clés dans un attribut. Par exemple, android:alphabeticModifiers="CTRL|SHIFT" indique que pour déclencher l'élément de menu correspondant, l'utilisateur doit appuyer simultanément sur les touches méta Ctrl et Maj ainsi que sur le raccourci.

Vous pouvez utiliser la méthode setAlphabeticShortcut() pour définir les valeurs d'attribut de manière automatisée. Pour en savoir plus sur l'attribut alphabeticModifier, consultez alphabeticModifiers.

android:numericModifiers

Mot clé. Modificateur du raccourci numérique de l'élément de menu. La valeur par défaut correspond à la touche Ctrl. Valeurs correctes :

Valeur	Description
`META`	Correspond à la touche méta `Méta`.
`CTRL`	Correspond à la touche méta `Ctrl`.
`ALT`	Correspond à la touche méta `Alt`
`MAJ`	Correspond à la touche méta `Maj`
`SYM`	Correspond à la touche méta `Sym`.
`FUNCTION`	Correspond à la touche méta `Fonction`

Remarque : Vous pouvez spécifier plusieurs mots clés dans un attribut. Par exemple, android:numericModifiers="CTRL|SHIFT" indique que pour déclencher l'élément de menu correspondant, l'utilisateur doit appuyer simultanément sur les touches méta Ctrl et Maj ainsi que sur le raccourci.

Vous pouvez utiliser la méthode setNumericShortcut() pour définir les valeurs d'attribut de manière automatisée. Pour en savoir plus sur l'attribut numericModifier, consultez numericModifiers.

android:checkable

Booléen. "True" si l'élément est contrôlable.

android:checked

Booléen. "True" si l'élément est coché par défaut.

android:visible

Booléen. "True" si l'élément est visible par défaut.

android:enabled

Booléen. "True" si l'élément est activé par défaut.

android:menuCategory

Mot clé. Valeur correspondant aux constantes Menu CATEGORY_*, qui définissent la priorité de l'élément. Valeurs correctes :

Valeur	Description
`container`	Pour les éléments faisant partie d'un conteneur.
`system`	Pour les éléments fournis par le système.
`secondary`	Pour les éléments correspondant à des options secondaires (rarement utilisées) fournies par l'utilisateur.
`alternative`	Pour les éléments qui correspondent à des actions alternatives sur les données affichées.

android:orderInCategory

Nombre entier. Ordre d'importance de l'élément dans un groupe.

<group>

Un groupe de menu (pour créer une collection d'éléments partageant des caractéristiques en commun, telles que leur visibilité, leur activation ou la possibilité de les sélectionner). Contient un ou plusieurs éléments <item>. Doit être un enfant d'un élément <menu>.

Attributs :

android:id

ID de ressource. ID de ressource unique. Pour créer un ID de ressource pour cet élément, utilisez le format suivant : "@+id/name". Le signe plus indique qu'il s'agit d'un nouvel ID.

android:checkableBehavior

Mot clé. Type de comportement sélectionnable pour le groupe. Valeurs correctes :

Valeur	Description
`none`	Non sélectionnable.
`all`	Tous les éléments peuvent être sélectionnés (cases à cocher).
`single`	Vous ne pouvez sélectionner qu'un seul élément (cases d'option).

android:visible

Booléen. "True" si le groupe est visible.

android:enabled

Booléen. "True" si le groupe est activé.

android:menuCategory

Mot clé. Valeur correspondant aux constantes Menu CATEGORY_*, qui définissent la priorité du groupe. Valeurs correctes :

Valeur	Description
`container`	Pour les groupes faisant partie d'un conteneur.
`system`	Pour les groupes fournis par le système.
`secondary`	Pour les groupes qui sont des options secondaires (rarement utilisées) fournies par l'utilisateur.
`alternative`	Pour les groupes qui correspondent à des actions alternatives sur les données affichées.

android:orderInCategory

Nombre entier. Ordre par défaut des articles de la catégorie.

Exemple :

Fichier XML enregistré sous res/menu/example_menu.xml :

<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item android:id="@+id/item1"
          android:title="@string/item1"
          android:icon="@drawable/group_item1_icon"
          app:showAsAction="ifRoom|withText"/>
    <group android:id="@+id/group">
        <item android:id="@+id/group_item1"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item1"
              android:icon="@drawable/group_item1_icon" />
        <item android:id="@+id/group_item2"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item2"
              android:icon="@drawable/group_item2_icon" />
    </group>
    <item android:id="@+id/submenu"
          android:title="@string/submenu_title"
          app:showAsAction="ifRoom|withText" >
        <menu>
            <item android:id="@+id/submenu_item1"
                  android:title="@string/submenu_item1" />
        </menu>
    </item>
</menu>

Le code d'application suivant agrandit le menu du rappel onCreateOptionsMenu(Menu) et déclare le rappel lors d'un clic pour deux des éléments :

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    menuInflater.inflate(R.menu.example_menu, menu)
    return true
}

fun onGroupItemClick(item: MenuItem) {
    // One of the group items (using the onClick attribute) was clicked.
    // The item parameter passed here indicates which item it is.
    // All other menu item clicks are handled by Activity.onOptionsItemSelected.
}

Java

public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.example_menu, menu);
    return true;
}

public void onGroupItemClick(MenuItem item) {
    // One of the group items (using the onClick attribute) was clicked.
    // The item parameter passed here indicates which item it is.
    // All other menu item clicks are handled by Activity.onOptionsItemSelected.
}

Mise en page

Chaîne