Модуль создания главного меню

Модуль gui-menu, выполненный по технологии OSGi, предназначен для создания главного меню в приложении Jabricks согласно описанной структуры во внешнем XML-файле. Главная строка меню может состоять из одной или двух частей для отображения пунктов меню либо в левой/правой части главного фрейма, либо в обеих частях. Заголовки пунктов меню определяются текущим значением языка локализации приложения и могут быть изменены в режиме run-time без перезагрузки модуля при смене Locale приложения.

Описание бандла gui-menu

Модуль gui-menu включает интерфейс MenuService и класс реализации методов интерфейса MenuServiceImpl. Конструктор класса реализации в качестве параметра получает контекст бандла BundleContext.

Интерфейс MenuService

Функциональность модуля gui-menu определяется методами интерфейса MenuService, исходный код которого включает следующие методы :

Листинг

public interface MenuService 
{
  public JMenuBar getJMenuBar ();

  public void   createMenu       (Properties props, 
                                  String fpath,
                                  ActionListener listener);
  public void   createMenu       (Properties props, 
                                  Document doc_menu,
                                  ActionListener listener);
  public void   changeLocale     (Properties props);
  public void   changeMenuCaption(final String menuName, 
                                  final String caption);
  public Bundle getLinkedBundle  (JMenuItem menuItem);
  public void   addActionListener(String menuName,
                                  ActionListener listener);
}

Интерфейс MenuService модуля gui-menu определяет методы создания меню типа JMenuBar, смены языка локализации, чтения связанного с пунктом меню бандла и подключение к пункту меню обработчика события. В таблице представлено описание методов.

Примечание :
1. Описание структуры главного меню фрейма (приложения) хранится во внешнем файле «configuration/menu.xml». Это позволяет наращивать функционал приложения подключением дополнительных бандлов без перекомпиляции модуля gui-menu.
2. При открытой конфигурации приложения можно использовать метод createMenu с текстовым параметром, определяющим путь к внешнему файлу «configuration/menu.xml».
3. В случае, если конфигурация приложения (директория «configuration») закрыта и файл «configuration/menu.xml» недоступен, то следует использовать метод readMenuStructure ресурсного модуля util-resources, имеющего доступ к закрытой конфигурации и возвращающего описание меню в виде XML Document'a. После этого методом createMenu с параметром описания структуры меню в виде Document создается объект главного меню.

Описание структуры меню

Структура меню главного фрейма приложения JaBricks описывается в файле configuration/menu.xml. Для описания структуры используются теги и атрибуты.

Теги описания структуры меню

Тег menubar является корневым элементом иерархической структуры меню и в интерфейсе не отображается. Тег menu определяет пункты меню в главной строке. Тег stub делит меню на 2 части; все пункты меню menu после заглушки попадают в правую часть меню. Теги menuitem являются дочерними элементами menu и отображаются в выпадающем списке. Каждый пункт меню может иметь несколько menuitem. Тег menuitem также может включать дочерние элементы menuitem, образуя иерархическую структуру.

Иерархическая структура меню определяет только именованные пункты меню и связанные с ними бандлы. При выборе/выделении пункта меню приложение стартует связанный с ним бандл.

Атрибуты пунктов меню

Каждый значимый пункт меню, определенный тегами <menu>, <menuitem>, имеет следующие атрибуты :

Примечание :
1. При выборе мышкой пункта меню типа type="button" модуль gui-menu стартует связанный с ним бандл.
2. Пункты меню типа type="check" и type="radio" имеют информативный характер и не могут стартовать бандл.

Пример описания структуры меню

Следующий листинг демонстрирует пример описания меню, включающего два пункта (menu.file, menu.view) в левой части меню и один пункт меню (menu.help) — в правой. Левая и правая части главной строки меню отделяются тегом <stub /> Каждый пункт меню содержит по несколько подпунктов меню.

Листинг

<?xml version="1.0" encoding="UTF-8"?>
<menubar name="mainMenu">
    <menu name="menu.file">
        <menuitem name="menu.open" enabled="true" />
        <menuitem name="separator"/>
        <menuitem name="menu.exit" />
    </menu>
    <menu name="menu.view">
        <menuitem name="menu.line" type="check" />
        <menuitem name="menu.grid" type="check" />
        <menuitem name="menu.navigation" 
                  type="check" enabled="false" />
        <menuitem name="separator"/>
        <menuitem name="menu.style" >
            <menuitem name="menu.style.bold" type="radio"  />
            <menuitem name="menu.style.normal" type="radio"/>
            <menuitem name="menu.style.font" />
        </menuitem>
    </menu>
    <stub />
    <menu name="menu.help" >
        <menuitem name="menu.settings" image="gear.png"
                  groupId="com.bundle.settings"
                  artifactId="form-settings"
                  version="1.0.0" />
        <menuitem name="menu.about" image="question.png"
                  groupId="com.bundle.about"
                  artifactId="form-about"
                  version="1.0.0" />
    </menu>
</menubar>

На скриншоте представлено графическое изображение меню, созданное согласно вышеописанной структуре. Пункт меню «Вид» на скриншоте представлен в раскрытом виде. Пункт меню «Справка» (menu.help) имеет два подпункта (menu.settings, menu.about), которые связаны с бандлами атрибутами groupId, artifactId и version. При выборе данных пунктов меню будут стартованы связанные с ними бандлы (см. слушатель событий).

Пример создания меню

Представленный ниже метод createMenu демонстрирует создание Главной строки меню. В качестве параметра метод createMenu получает описанный ниже слушатель событий, который должен обрабатывать события выбора пунктов меню.

Если структура файла "configuration/menu.xml" соответствует определенному выше формату, то будет создан объект сервиса меню типа MenuService, возвращающий меню JMenuBar методом getJMenuBar. Если по каким-либо причинам меню не будет создано (отсутствие файла, нарушение структуры), то необходимо обнулить объект управления меню, чтобы избежать возникновения ошибок при дальнейшем его использовании, например, изменения локализации интерфейса.

Листинг

BundleContext  context;
JFrame         frame  ;
MenuService    menu   ;
...
private void createMenu(ActionListener listener)
{
    if (listener == null) {
        menu = null;
        return;
    }

    IResources resources = new ResourcesImpl();
    Document   doc       = resources.readMenuStructure();

    if (doc == null) {
        menu = null;
        return;
    }

    String     sn   ;
    Properties props;

    sn    = context.getBundle().getSymbolicName();
    props = resources.getBundleResources(sn);

    try {
        // Создание сервиса меню
        menu = new MenuServiceImpl(context);

        /*
         * Создание Главной строки меню
         */
        menu.createMenu(props, doc, listener);
        // Подключение строки меню
        if (menu.getJMenuBar() != null)
            frame.setJMenuBar(menu.getJMenuBar());
        else
            menu = null;
    } catch (Exception e) {}
}

Пример использования gui-menu в приложении JaBricks представлен в Уроке 3.

Описание слушателя событий

Представленный ниже слушатель событий menuListener позволяет в автоматическом режиме стартовать бандл при выборе соответствующего пункта меню. Если пункт меню не связан с бандлом, то необходимо в коде описать соответствующий обработчик события. Например, следующий пример демонстрирует старт связанного с «выделенным» пунктом меню бандла.

Листинг

MenuService menu;

private ActionListener menuListener = new ActionListener()
{
    public void actionPerformed(ActionEvent event)
    {
        JMenuItem menuItem = (JMenuItem) event.getSource();

        Bundle  bundle = null;
        bundle = menu.getLinkedBundle(menuItem);
        if ((bundle != null) && 
            (bundle.getState() != Bundle.ACTIVE)) {
            try {
                /* Старт связанного с выделенным пунктом 
                 * меню бандла
                 */
                bundle.start();
            } catch (BundleException e) {}
        } else {
            /*
             * Обработка события по выделению пункта меню,
             * не связанного с бандлом
              */
            if (menuItem.getName()
                        .equalsIgnoreCase("menu_name"))
                // ...
        }
    }
};

Обновление заголовков меню при смене Locale

При смене языка локализации в приложении можно в режиме run-time без перезагрузки бандла gui-menu обновить заголовки пунктов меню. Для этого следует подписаться на рассылку сообщения jabricks/LocaleEvent, отправляемое бандлами form-locale и form-settings. Следующий код демонстрирует чтение соответствующего внешнего файла свойств бандла согласно определенной в приложении locale и обновление наименований пунктов меню.

MenuService  menu;
. . .
IResources resources = new ResourcesImpl();
if ((resources != null) && ((menu != null)) {
    String sn = context.getBundle().getSymbolicName();
    Properties props = resources.getBundleResources(sn);
    // Обновление пунктов меню согласно локализации
    menu.changeLocale(props);
}

Примечание : пример «организации подписки» на сообщение jabricks/LocaleEvent приведен в описании бандла form-locale.

Локализованные наименования пунктов меню

Локализованные наименования пунктов меню хранятся во внешних файлах свойств типа *.properties главного фрейма приложения. Следующий код демонстрирует описание англоязычных заголовков пунктов меню в файле свойств configuration/resources/properties/xxx_en.properties, где 'xxx' соответствует наименованию модуля/бандла главного фрейма приложения JaBricks.

menu.file=File
menu.exit=Exit
menu.view=View
menu.line=Line
menu.grid=Grid
menu.navigation=Navigation
menu.style=Style
menu.style.bold=Bold
menu.style.normal=Normal
menu.style.font=Font
menu.settings=Settings
menu.help=Help

Динамическое изменение заголовка пункта меню

Модуль gui-menu позволяет в режиме run-time изменить заголовок пункта меню. В качестве примера можно привести пункт меню «Подключения» к серверу БД. Связанный с данным пунктом меню модуль может как устанавливать соединение с сервером БД, так и разрывать соединение. В этом случае пункт меню может иметь заголовок, отражающий наличие или отсутствие соединения.

Приведенный в листинге метод changeConnect устанавливает заголовок пункта меню menu_connection в зависимости от наличия соединения (метод isConnected) с сервером БД.

Листинг

String  connection    = "menu.connection";
String  disconnection = "menu.disconnection";

public void changeConnect(Properties props)
{
    String key     = null;
    String caption = null;
    if (isConnected())
        key = disconnection;
    else
        key = connection;
    // Чтение свойства
    if (props.containsKey(key))
        caption = props.getProperty(key);

    // Переименование пункта меню
    if ((menu != null) && (caption != null))
        menu.changeMenuCaption(menu_connection, caption);
}

Пример

Пример использования gui-menu представлен в описании к Уроку 3.

Версия 1.0.1

Версия модуля 1.0.1 поддерживает функциональность предыдущей версии 1.0.0. и позволяет использовать в приложении одинаковые бандлы разных версий.

Зависимости

Модуль gui-menu связан с ресурсным бандлом util-resources для чтения текущего объекта локализации приложения Locale.

Подключение модуля к приложению

Для подключения модуля gui-menu к приложению Jabricks необходимо :

• разместить модуль в поддиректории «configuration/bundles/»;
• внести в файл инициализации бандлов «bundles.ini» запись : gui-menu-1.0.1.jar;
• определить соответствующую структуру меню в файле «configuration/menu.xml».

GAV параметры модуля form-menu имеют следующие значения :

Подробнее о включении модуля в приложение Jabricks представлено здесь.

Скачать gui-menu

Рассмотренный на странице модуль создания меню gui-menu упакован в архивный файл gui-menu-1.0.1.zip (15.3 Кб).