mobile/android/android-components/components/browser/menu/README.md

   1 # [Android Components](../../../README.md) > Browser > Menu
   2
   3 A generic menu with customizable items primarily for browser toolbars.
   4
   5 ## Usage
   6
   7 ### Setting up the dependency
   8
   9 Use Gradle to download the library from [maven.mozilla.org](https://maven.mozilla.org/) ([Setup repository](../../../README.md#maven-repository)):
  10
  11 ```Groovy
  12 implementation "org.mozilla.components:browser-menu:{latest-version}"
  13 ```
  14
  15 ### BrowserMenu
  16 Sample code can be found in [Sample Toolbar app](https://github.com/mozilla-mobile/android-components/tree/main/samples/toolbar).
  17
  18 There are multiple properties that you customize of the menu browser by just adding them into your dimens.xml file.
  19
  20 ```xml
  21 <resources xmlns:tools="http://schemas.android.com/tools">
  22
  23    <!--Change how rounded the corners of the menu should be-->
  24     <dimen name="mozac_browser_menu_corner_radius" tools:ignore="UnusedResources">4dp</dimen>
  25
  26     <!--Change how much shadow the menu should have-->
  27     <dimen name="mozac_browser_menu_elevation" tools:ignore="UnusedResources">4dp</dimen>
  28
  29     <!--Change the width of the menu-->
  30     <dimen name="mozac_browser_menu_width" tools:ignore="UnusedResources">250dp</dimen>
  31
  32     <!--Change the dynamic width of the menu-->
  33     <dimen name="mozac_browser_menu_width_min" tools:ignore="UnusedResources">200dp</dimen>
  34     <dimen name="mozac_browser_menu_width_max" tools:ignore="UnusedResources">300dp</dimen>
  35
  36     <!--Change the top and bottom padding of the menu-->
  37     <dimen name="mozac_browser_menu_padding_vertical" tools:ignore="UnusedResources">8dp</dimen>
  38
  39 </resources>
  40 ```
  41 BrowserMenu can have a dynamic width:
  42 - Using the same value for `mozac_browser_menu_width_min` and `mozac_browser_menu_width_max` means BrowserMenu will have a fixed width - `mozac_browser_menu_width`.
  43 _This is the default behavior_.
  44 - Different values for `mozac_browser_menu_width_min` and `mozac_browser_menu_width_max` means BrowserMenu will have a dynamic width depending on the widest BrowserMenuItem and between the aforementioned dimensions also taking into account display width.
  45
  46
  47 ### BrowserMenuDivider
  48 ```kotlin
  49
  50     BrowserMenuDivider()
  51
  52 ```
  53
  54 To customize the divider you could use a 1. Quick customization or a 2. Full customization:
  55
  56 1) If you just want to change the height of the divider, add this item your ``dimes.xml`` file, and your
  57 prefer height size.
  58
  59 ```xml
  60     <dimen name="mozac_browser_menu_item_divider_height" tools:ignore="UnusedResources">YOUR_HEIGHT</dimen>
  61 ```
  62 2) For full customization, override the default style of the divider by adding this style item in your `style.xml` file, and customize to your liking.
  63 ```xml
  64         <style name="Mozac.Browser.Menu.Item.Divider.Horizontal" tools:ignore="UnusedResources">
  65             <item name="android:background">YOUR_BACKGROUND</item>
  66             <item name="android:layout_width">match_parent</item>
  67             <item name="android:layout_height">YOUR_HEIGHT</item>
  68         </style>
  69 ```
  70
  71 ### BrowserMenuImageText
  72 ```kotlin
  73     BrowserMenuImageText(
  74        label = "Share",
  75        imageResource = R.drawable.mozac_ic_share_android_24,
  76        iconTintColorResource = R.color.photonBlue90
  77     ) {
  78         Toast.makeText(applicationContext, "Share", Toast.LENGTH_SHORT).show()
  79     }
  80 ```
  81
  82 To customize the menu you could use separate properties 1 or full access to the style of the menu 2:
  83
  84 1) If you just want to change a specify property, just add one these dimen items to your ``dimes.xml`` file.
  85
  86 ```xml
  87     <!--Menu Item -->
  88        <!--Change the text_size for ALL menu items NOT only for the BrowserMenuImageText -->
  89         <dimen name="mozac_browser_menu_item_text_size" tools:ignore="UnusedResources">16sp</dimen>
  90     <!--Menu Item -->
  91
  92     <!--Icon-->
  93        <!--Change the icon's width-->
  94         <dimen name="mozac_browser_menu_item_image_text_icon_width" tools:ignore="UnusedResources">24dp</dimen> <!--Default value-->
  95
  96        <!--Change the icon's height-->
  97         <dimen name="mozac_browser_menu_item_image_text_icon_height" tools:ignore="UnusedResources">24dp</dimen> <!--Default value-->
  98
  99     <!--Icon-->
 100
 101     <!--Label-->
 102            <!--Change the separation between the label and the icon-->
 103             <dimen name="mozac_browser_menu_item_image_text_label_padding_start" tools:ignore="UnusedResources">20dp</dimen> <!--Default value-->
 104
 105     <!--Label-->
 106 ```
 107
 108 2) For full customization, override the default style of menu by adding this style item in your `style.xml` file, and customize to your liking.
 109
 110 ```xml
 111     <!--Change the appearance of all text menu items-->
 112     <style name="Mozac.Browser.Menu.Item.Text" parent="@android:style/TextAppearance.Material.Menu" tools:ignore="UnusedResources">
 113         <item name="android:background">?android:attr/selectableItemBackground</item>
 114         <item name="android:textSize">@dimen/mozac_browser_menu_item_text_size</item>
 115         <item name="android:ellipsize">end</item>
 116         <item name="android:lines">1</item>
 117         <item name="android:focusable">true</item>
 118         <item name="android:clickable">true</item>
 119     </style>
 120
 121     <style name="Mozac.Browser.Menu.Item.ImageText.Icon" parent="" tools:ignore="UnusedResources">
 122         <item name="android:layout_width">@dimen/mozac_browser_menu_item_image_text_icon_width</item>
 123         <item name="android:layout_height">@dimen/mozac_browser_menu_item_image_text_icon_height</item>
 124     </style>
 125
 126     <style name="Mozac.Browser.Menu.Item.ImageText.Label" parent="Mozac.Browser.Menu.Item.Text" tools:ignore="UnusedResources">
 127         <item name="android:layout_width">wrap_content</item>
 128         <item name="android:layout_height">wrap_content</item>
 129         <item name="android:paddingStart">@dimen/mozac_browser_menu_item_image_text_label_padding_start</item>
 130     </style>
 131 ```
 132
 133 ## Facts
 134
 135 This component emits the following [Facts](../../support/base/README.md#Facts):
 136
 137 | Action | Item                    | Extras            | Description                          |
 138 |--------|-------------------------|-------------------|--------------------------------------|
 139 | Click  | web_extension_menu_item | `menuItemExtras`  | Web extension menu item was clicked. |
 140
 141
 142 #### `menuItemExtras`
 143
 144 | Key  | Type   | Value                                                    |
 145 |------|--------|----------------------------------------------------------|
 146 | "id" | String | Web extension id of the clicked web extension menu item. |
 147
 148 ## License
 149
 150     This Source Code Form is subject to the terms of the Mozilla Public
 151     License, v. 2.0. If a copy of the MPL was not distributed with this
 152     file, You can obtain one at http://mozilla.org/MPL/2.0/