1 package com.vaadin.contextmenu; 2 3 import java.io.Serializable; 4 import java.util.List; 5 6 import com.vaadin.contextmenu.Menu.Command; 7 import com.vaadin.server.Resource; 8 9 public interface MenuItem extends Serializable { 10 11 /** 12 * Checks if the item has children (if it is a sub-menu). 13 * 14 * @return True if this item has children 15 */ 16 boolean hasChildren(); 17 18 /** 19 * Adds a separator to this menu. A separator is a way to visually group 20 * items in a menu, to make it easier for users to find what they are 21 * looking for in the menu. 22 * 23 * @author Jouni Koivuviita / Vaadin Ltd. 24 * @since 6.2.0 25 */ 26 MenuItem addSeparator(); 27 28 MenuItem addSeparatorBefore(MenuItem itemToAddBefore); 29 30 /** 31 * Add a new item inside this item, thus creating a sub-menu. Command can be 32 * null, but a caption must be given. 33 * 34 * @param caption 35 * the text for the menu item 36 * @param command 37 * the command for the menu item 38 */ 39 MenuItem addItem(String caption, Command command); 40 41 /** 42 * Add a new item inside this item, thus creating a sub-menu. Icon and 43 * command can be null, but a caption must be given. 44 * 45 * @param caption 46 * the text for the menu item 47 * @param icon 48 * the icon for the menu item 49 * @param command 50 * the command for the menu item 51 * @throws IllegalStateException 52 * If the item is checkable and thus cannot have children. 53 */ 54 MenuItem addItem(String caption, Resource icon, Command command) 55 throws IllegalStateException; 56 57 /** 58 * Add an item before some item. If the given item does not exist the item 59 * is added at the end of the menu. Icon and command can be null, but a 60 * caption must be given. 61 * 62 * @param caption 63 * the text for the menu item 64 * @param icon 65 * the icon for the menu item 66 * @param command 67 * the command for the menu item 68 * @param itemToAddBefore 69 * the item that will be after the new item 70 * @throws IllegalStateException 71 * If the item is checkable and thus cannot have children. 72 */ 73 MenuItem addItemBefore(String caption, Resource icon, Command command, 74 MenuItem itemToAddBefore) throws IllegalStateException; 75 76 /** 77 * For the associated command. 78 * 79 * @return The associated command, or null if there is none 80 */ 81 Command getCommand(); 82 83 /** 84 * Gets the objects icon. 85 * 86 * @return The icon of the item, null if the item doesn't have an icon 87 */ 88 Resource getIcon(); 89 90 /** 91 * For the containing item. This will return null if the item is in the 92 * top-level menu bar. 93 * 94 * @return The containing {@link MenuItem} , or null if there is none 95 */ 96 MenuItem getParent(); 97 98 /** 99 * This will return the children of this item or null if there are none. 100 * 101 * @return List of children items, or null if there are none 102 */ 103 List<MenuItem> getChildren(); 104 105 /** 106 * Gets the objects text 107 * 108 * @return The text 109 */ 110 java.lang.String getText(); 111 112 /** 113 * Returns the number of children. 114 * 115 * @return The number of child items 116 */ 117 int getSize(); 118 119 /** 120 * Get the unique identifier for this item. 121 * 122 * @return The id of this item 123 */ 124 int getId(); 125 126 /** 127 * Set the command for this item. Set null to remove. 128 * 129 * @param command 130 * The MenuCommand of this item 131 */ 132 void setCommand(Command command); 133 134 /** 135 * Sets the icon. Set null to remove. 136 * 137 * @param icon 138 * The icon for this item 139 */ 140 void setIcon(Resource icon); 141 142 /** 143 * Set the text of this object. 144 * 145 * @param text 146 * Text for this object 147 */ 148 void setText(java.lang.String text); 149 150 /** 151 * Remove the first occurrence of the item. 152 * 153 * @param item 154 * The item to be removed 155 */ 156 void removeChild(MenuItem item); 157 158 /** 159 * Empty the list of children items. 160 */ 161 void removeChildren(); 162 163 void setEnabled(boolean enabled); 164 165 boolean isEnabled(); 166 167 void setVisible(boolean visible); 168 169 boolean isVisible(); 170 171 boolean isSeparator(); 172 173 void setStyleName(String styleName); 174 175 String getStyleName(); 176 177 /** 178 * Sets the items's description. See {@link #getDescription()} for more 179 * information on what the description is. This method will trigger a menu 180 * item repaint. 181 * 182 * @param description 183 * the new description string for the component. 184 */ 185 void setDescription(String description); 186 187 /** 188 * <p> 189 * Gets the items's description. The description can be used to briefly 190 * describe the state of the item to the user. The description string may 191 * contain certain XML tags: 192 * </p> 193 * 194 * <p> 195 * <table border=1> 196 * <tr> 197 * <td width=120><b>Tag</b></td> 198 * <td width=120><b>Description</b></td> 199 * <td width=120><b>Example</b></td> 200 * </tr> 201 * <tr> 202 * <td><b></td> 203 * <td>bold</td> 204 * <td><b>bold text</b></td> 205 * </tr> 206 * <tr> 207 * <td><i></td> 208 * <td>italic</td> 209 * <td><i>italic text</i></td> 210 * </tr> 211 * <tr> 212 * <td><u></td> 213 * <td>underlined</td> 214 * <td><u>underlined text</u></td> 215 * </tr> 216 * <tr> 217 * <td><br></td> 218 * <td>linebreak</td> 219 * <td>N/A</td> 220 * </tr> 221 * <tr> 222 * <td><ul><br> 223 * <li>item1<br> 224 * <li>item1<br> 225 * </ul></td> 226 * <td>item list</td> 227 * <td> 228 * <ul> 229 * <li>item1 230 * <li>item2 231 * </ul> 232 * </td> 233 * </tr> 234 * </table> 235 * </p> 236 * 237 * <p> 238 * These tags may be nested. 239 * </p> 240 * 241 * @return item's description <code>String</code> 242 */ 243 String getDescription(); 244 245 /** 246 * Gets the checkable state of the item - whether the item has checked and 247 * unchecked states. If an item is checkable its checked state (as returned 248 * by {@link #isChecked()}) is indicated in the UI. 249 * 250 * <p> 251 * An item is not checkable by default. 252 * </p> 253 * 254 * @return true if the item is checkable, false otherwise 255 * @since 6.6.2 256 */ 257 boolean isCheckable(); 258 259 /** 260 * Sets the checkable state of the item. If an item is checkable its checked 261 * state (as returned by {@link #isChecked()}) is indicated in the UI. 262 * 263 * <p> 264 * An item is not checkable by default. 265 * </p> 266 * 267 * <p> 268 * Items with sub items cannot be checkable. 269 * </p> 270 * 271 * @param checkable 272 * true if the item should be checkable, false otherwise 273 * @throws IllegalStateException 274 * If the item has children 275 * @since 6.6.2 276 */ 277 void setCheckable(boolean checkable) throws IllegalStateException; 278 279 /** 280 * Gets the checked state of the item (checked or unchecked). Only used if 281 * the item is checkable (as indicated by {@link #isCheckable()}). The 282 * checked state is indicated in the UI with the item, if the item is 283 * checkable. 284 * 285 * <p> 286 * An item is not checked by default. 287 * </p> 288 * 289 * <p> 290 * The CSS style corresponding to the checked state is "-checked". 291 * </p> 292 * 293 * @return true if the item is checked, false otherwise 294 * @since 6.6.2 295 */ 296 boolean isChecked(); 297 298 /** 299 * Sets the checked state of the item. Only used if the item is checkable 300 * (indicated by {@link #isCheckable()}). The checked state is indicated in 301 * the UI with the item, if the item is checkable. 302 * 303 * <p> 304 * An item is not checked by default. 305 * </p> 306 * 307 * <p> 308 * The CSS style corresponding to the checked state is "-checked". 309 * </p> 310 * 311 * @return true if the item is checked, false otherwise 312 * @since 6.6.2 313 */ 314 void setChecked(boolean checked); 315 316 }