1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Eclipse Public License, Version 1.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.eclipse.org/org/documents/epl-v10.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.menubar;
18
19import org.eclipse.swt.widgets.Display;
20import org.eclipse.swt.widgets.Menu;
21
22
23/**
24 * Interface to the platform-specific MenuBarEnhancer implementation returned by
25 * {@link MenuBarEnhancer#setupMenu}.
26 */
27public interface IMenuBarEnhancer {
28
29    /** Values that indicate how the menu bar is being handlded. */
30    public enum MenuBarMode {
31        /**
32         * The Mac-specific About and Preferences are being used.
33         * No File > Exit menu should be provided by the application.
34         */
35        MAC_OS,
36        /**
37         * The provided SWT {@link Menu} is being used for About and Options.
38         * The application should provide a File > Exit menu.
39         */
40        GENERIC
41    }
42
43    /**
44     * Returns a {@link MenuBarMode} enum that indicates how the menu bar is going to
45     * or has been modified. This is implementation specific and can be called before or
46     * after {@link #setupMenu}.
47     * <p/>
48     * Callers would typically call that to know if they need to hide or display
49     * menu items. For example when {@link MenuBarMode#MAC_OS} is used, an app
50     * would typically not need to provide any "File > Exit" menu item.
51     *
52     * @return One of the {@link MenuBarMode} values.
53     */
54    public MenuBarMode getMenuBarMode();
55
56    /**
57     * Updates the menu bar to provide an About menu item and a Preferences menu item.
58     * Depending on the platform, the menu items might be decorated with the
59     * given {@code appName}.
60     * <p/>
61     * Users should not call this directly.
62     * {@link MenuBarEnhancer#setupMenu} should be used instead.
63     *
64     * @param appName Name used for the About menu item and similar. Must not be null.
65     * @param display The SWT display. Must not be null.
66     * @param callbacks Callbacks called when "About" and "Preferences" menu items are invoked.
67     *          Must not be null.
68     */
69    public void setupMenu(
70            String appName,
71            Display display,
72            IMenuBarCallback callbacks);
73}
74