IndependentModeler/src/cz/cvut/promod/services/menuService/MenuService.java

   1 package cz.cvut.promod.services.menuService;
   2
   3 import cz.cvut.promod.services.Service;
   4 import cz.cvut.promod.services.actionService.actionUtils.ProModAction;
   5 import cz.cvut.promod.services.menuService.utils.MenuItemPosition;
   6 import cz.cvut.promod.services.menuService.utils.InsertMenuItemResult;
   7
   8
   9 import javax.swing.*;
  10
  11
  12 /**
  13  * ProMod, master thesis project
  14  * User: Petr Zverina, petr.zverina@gmail.com
  15  * Date: 17:45:27, 10.10.2009
  16  */
  17
  18 /**
  19  * Menu Service allows developer to insert items into the main menu, project tree navigation popup menu
  20  *  or notation specific menus.
  21  */
  22 public interface MenuService extends Service{
  23
  24     // Separator for hierarchical placement of menu items, e.g. "File;Export;Image"
  25     public static final String PLACEMENT_DELIMITER = ";";
  26
  27
  28     // Determines whether a menu separator is supposed to be inserted (before or after a menu item) or not.
  29     public static enum MenuSeparator {
  30         AFTER, // insert menu separator before the item
  31         BEFORE, // insert menu separator after the item
  32         NONE // do not insert menu separator
  33     }
  34
  35     /**
  36      * Inserts a new action to the main menu structure.
  37      *
  38      * @param proModAction is the action that will be triggered by the menu item, the action has to be registered by the
  39      * ActionService before, promod action cannot have an empty string as it's name (text).
  40      *
  41      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
  42      * of the menu item in menu. Hierarchical position cannot be null or an empty string for main menu.
  43      *
  44      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
  45      *
  46      * @param menuSeparator determines whether a menu separator is supposed to be inserted after or before the menu
  47      * item or not
  48      *
  49      * @param checkable if true, than the menu item is designated to be selectable (has a small checkbox)
  50      *
  51      * @return an value from InsertMenuItemResults enumeration
  52      *
  53      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
  54      * and their meanings
  55      */
  56     public InsertMenuItemResult insertMainMenuItem(final ProModAction proModAction,
  57                                                    final MenuItemPosition menuItemPosition,
  58                                                    final MenuSeparator menuSeparator,
  59                                                    final boolean checkable);
  60
  61     /**
  62      * Inserts a new action to the main menu structure. This menu item won't be checkable (does not have the little
  63      * checkbox on it).
  64      *
  65      * @param proModAction is the action that will be triggered by the menu item, the action has to be registered by the
  66      * ActionService before, promod action cannot have an empty string as it's name (text).
  67      *
  68      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
  69      * of the menu item in menu. Hierarchical position cannot be null or an empty string for main menu.
  70      *
  71      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
  72      *
  73      * @param menuSeparator determines whether a menu separator is supposed to be inserted after or before the menu
  74      * item or not
  75      *
  76      * @return an value from InsertMenuItemResults enumeration
  77      *
  78      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
  79      * and their meanings
  80      */
  81     public InsertMenuItemResult insertMainMenuItem(final ProModAction proModAction,
  82                                                    final MenuItemPosition menuItemPosition,
  83                                                    final MenuSeparator menuSeparator);
  84
  85     /**
  86      * Inserts a new action to the main menu structure without any menu separator.
  87      *
  88      * @param proModAction is the action that will be triggered by the menu item, the action has to be registered by the
  89      * ActionService before, promod action cannot have an empty string as it's name (text).
  90      *
  91      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
  92      * of the menu item in menu. Hierarchical position cannot be null or an empty string for main menu.
  93      *
  94      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
  95      *
  96      * @param checkable if true, than the menu item is designated to be selectable (has a small checkbox)
  97      *
  98      * @return an value from InsertMenuItemResults enumeration
  99      *
 100      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
 101      * and their meanings
 102      */
 103     public InsertMenuItemResult insertMainMenuItem(final ProModAction proModAction,
 104                                                    final MenuItemPosition menuItemPosition,
 105                                                    final boolean checkable);
 106
 107     /**
 108      * Inserts a new action to the main menu structure without any menu separator.
 109      * This menu item won't be checkable (does not have the little checkbox on it).
 110      *
 111      * @param proModAction is the action that will be triggered by the menu item, the action has to be registered by the
 112      * ActionService before, promod action cannot have an empty string as it's name (text).
 113      *
 114      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
 115      * of the menu item in menu. Hierarchical position cannot be null or an empty string for main menu.
 116      *
 117      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
 118      *
 119      * @return an value from InsertMenuItemResults enumeration
 120      *
 121      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
 122      * and their meanings
 123      */
 124     public InsertMenuItemResult insertMainMenuItem(final ProModAction proModAction,
 125                                                    final MenuItemPosition menuItemPosition);
 126
 127
 128     /**
 129      * Inserts new action to the project navigation tree popup menu.
 130      * This menu is invoked anytime the right mouse button is clicked on any items in the project navigation tree.
 131      *
 132      * @param proModAction that will be triggered when by the menu item, the action has to be registered by the
 133      * ActionService before, promod action cannot have an empty string as it's name (text).
 134      *
 135      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
 136      * of the menu item in menu. An empty string in hierarchical position means that the menu item will be inserted
 137      * into the root of the popup menu (menu item that are immediately visible when the popup menu is shown).
 138      *
 139      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
 140      *
 141      * @param menuSeparator insert any possible value (see InsertMenuSeparator enum) or null
 142      *
 143      * @return an value from InsertMenuItemResults enumeration
 144      *
 145      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
 146      * and their meanings
 147      */
 148     public InsertMenuItemResult insertProjectNavigationPopupMenuItem(final ProModAction proModAction,
 149                                                                      final MenuItemPosition menuItemPosition,
 150                                                                      final MenuSeparator menuSeparator);
 151
 152     /**
 153      * Inserts new action to the project navigation tree popup menu without any menu separator.
 154      * This menu is invoked anytime the right mouse button is clicked on any items in the project navigation tree.
 155      *
 156      * @param proModAction that will be triggered when by the menu item, the action has to be registered by the
 157      * ActionService before, promod action cannot have an empty string as it's name (text).
 158      *
 159      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
 160      * of the menu item in menu. An empty string in hierarchical position means that the menu item will be inserted
 161      * into the root of the popup menu (menu item that are immediately visible when the popup menu is shown).
 162      *
 163      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
 164      *
 165      * @return an value from InsertMenuItemResults enumeration
 166      *
 167      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
 168      * and their meanings
 169      */
 170     public InsertMenuItemResult insertProjectNavigationPopupMenuItem(final ProModAction proModAction,
 171                                                                      final MenuItemPosition menuItemPosition);
 172
 173
 174     /**
 175      * Inserts new action to the notation specific popup menu.
 176      * Not all notations support the popup menu feature.
 177      *
 178      * @param notationIdentifier is the identifier of notation to which popup menu is the menu item (action)
 179      * supposed to be inserted. When one specifies the identifier of Modeler, the menu item will be the inserted
 180      * into the project navigation tree popup menu.
 181      *
 182      * @param proModAction that will be triggered when by the menu item, the action has to be registered by the
 183      * ActionService before, promod action cannot have an empty string as it's name (text).
 184      *
 185      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
 186      * of the menu item in menu. An empty string in hierarchical position means that the menu item will be inserted
 187      * into the root of the popup menu (menu item that are immediately visible when the popup menu is shown).
 188      *
 189      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
 190      *
 191      * @param menuSeparator insert any possible value (see InsertMenuSeparator enum) or null
 192      *
 193      * @return an value from InsertMenuItemResults enumeration
 194      *
 195      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
 196      * and their meanings
 197      */
 198     public InsertMenuItemResult insertPopupMenuItem(final String notationIdentifier,
 199                                                     final ProModAction proModAction,
 200                                                     final MenuItemPosition menuItemPosition,
 201                                                     final MenuSeparator menuSeparator);
 202
 203     /**
 204      * Inserts new action to the notation specific popup menu without any menu separator.
 205      * Not all notations support the popup menu feature.
 206      *
 207      * @param notationIdentifier is the identifier of notation to which popup menu is the menu item (action)
 208      * supposed to be inserted. When one specifies the identifier of Modeler, the menu item will be the inserted
 209      * into the project navigation tree popup menu.
 210      *
 211      * @param proModAction that will be triggered when by the menu item, the action has to be registered by the
 212      * ActionService before, promod action cannot have an empty string as it's name (text).
 213      *
 214      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
 215      * of the menu item in menu. An empty string in hierarchical position means that the menu item will be inserted
 216      * into the root of the popup menu (menu item that are immediately visible when the popup menu is shown).
 217      *
 218      * @see cz.cvut.promod.services.menuService.utils.MenuItemPosition
 219      *
 220      * @return an value from InsertMenuItemResults enumeration
 221      *
 222      * @see cz.cvut.promod.services.menuService.utils.InsertMenuItemResult for more details about return values
 223      * and their meanings
 224      */
 225     public InsertMenuItemResult insertPopupMenuItem(final String notationIdentifier,
 226                                                     final ProModAction proModAction,
 227                                                     final MenuItemPosition menuItemPosition);
 228     /*
 229      * Inserts a new action into given popup menu. This function can be used by notation using JIDE to handle their
 230      *  popup menus.
 231      *
 232      * @param parentMenu  is the parent menu item of added action
 233      *
 234      * @param parentPopupMenu the popup menu to be extended by defined action
 235      *
 236      * @param proModAction that will be triggered when by the menu item, the action has to be registered by the
 237      * ActionService before, promod action cannot have an empty string as it's name (text).
 238      *
 239      * @param menuItemPosition is an instance of MenuItemPosition specifying hierarchical, absolute or relative position
 240      * of the menu item in menu. An empty string in hierarchical position means that the menu item will be inserted
 241      * into the root of the popup menu (menu item that are immediately visible when the popup menu is shown).
 242      *
 243      * @param checkable  determines whether the menu item will be checkable or not
 244      *
 245      * @return an information about inserting success
 246      */
 247     public InsertMenuItemResult insertAction(final JMenu parentMenu,
 248                                                final JPopupMenu parentPopupMenu,
 249                                                final ProModAction proModAction,
 250                                                final MenuSeparator menuSeparator,
 251                                                final MenuItemPosition menuItemPosition,
 252                                                final boolean checkable);
 253
 254
 255 }