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 :
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 :
ValeurDescription
ifRoomNe 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.
withTextIncluez é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 |.
neverNe placez jamais cet élément dans la barre d'application, mais plutôt dans le menu à développer.
alwaysPlacez 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.
collapseActionViewLa 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.

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 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 :
ValeurDescription
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 :
ValeurDescription
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 :
ValeurDescription
containerPour les éléments faisant partie d'un conteneur.
systemPour les éléments fournis par le système.
secondaryPour les éléments correspondant à des options secondaires (rarement utilisées) fournies par l'utilisateur.
alternativePour 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 :
ValeurDescription
noneNon sélectionnable.
allTous les éléments peuvent être sélectionnés (cases à cocher).
singleVous 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 :
ValeurDescription
containerPour les groupes faisant partie d'un conteneur.
systemPour les groupes fournis par le système.
secondaryPour les groupes qui sont des options secondaires (rarement utilisées) fournies par l'utilisateur.
alternativePour 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.
}