Модуль создания панели инструментов

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

Описание модуля gui-toolbar

Модуль gui-toolbar включает интерфейс ToolbarService класс реализации методов интерфейса ToolbarServiceImpl. Класс реализации интерфейса содержит конструктор ToolbarServiceImpl(BundleContext), которому в качестве параметра передается контекст бандла BundleContext.

Листинг интерфейса ToolbarService

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

Листинг

import java.util.Properties;
import javax.swing.JToolBar;
import org.osgi.framework.Bundle;
import java.awt.event.ActionListener;

public interface ToolbarService 
{
  public JToolBar getJToolBar ();
  
  public void   createToolbar (final Properties props,
                               final String fpath, 
                               ActionListener listener);
  public void   createToolbar (final Properties props,
                               final Document doc_toolbar,
                               ActionListener listener);
  public void   createToolbar (final Properties props, 
                               final String xml_struct);

  public void   changeLocale     (Properties props);
  public Bundle getLinkedBundle  (final String name);
  public void   addActionListener(String name, 
                                  ActionListener listener);
}

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

Описание методов интерфейса

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

Описание структуры панели инструментов в формате XML

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

При описании структуры панели инструментов используется корневой элемент <root>, включающий одну или две секции <toolbar>. Каждая секция <toolbar> может быть либо пустой, либо включать несколько элементов <item>, описывающих визуальные компоненты панели инструментов. Следующий листинг описывает структуру панели инструментов, включающую две части. В левой части размещается одна кнопка, в правой части — три кнопки.

Описание

<?xml version="1.0" encoding="UTF-8"?>
<root name="root" rollover="true" borderpainted="true">
    <toolbar>
        <item name="toolbar.add" type="button"
              image="configuration/resources/images/add.png" />
    </toolbar>
    <toolbar>
        <item name="toolbar.settings" type="button" 
              image="configuration/resources/images/gear.png"
              groupId="com.bundle.settings"
              artifactId="form-settings"
              version="1.0.0" />
        <item name="toolbar.about" type="button"
              image="configuration/resources/images/question.png"
              groupId="com.bundle.about"
              artifactId="form-about" version="1.0.0" />
        <item name="toolbar.exit" type="button"
              image="configuration/resources/images/exit.png" />
    </toolbar>
</root>

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

Корневой элемент описания структуры <root> включает необязательный атрибут name, атрибут rollover, определяющий выделение компонента при наведении на него мыши, и атрибут borderpainted для обрамления панели инструментов рамкой. По умолчанию атрибуты rollover и borderpainted имеют значения true.

Каждая часть панели инструментов описывается секцией <toolbar>. Если необходимо в интерфейсе представить только правую часть панели инструментов, то при описании структуры следует обязательно включить первую секцию <toolbar> без дочерних элементов.

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

Визуальные компоненты панели инструментов определяются тегами <item>, атрибуты которых описывают свойства компонентов. В таблице представлены возможные значения атрибутов :

Примечание :
1. Изображения для кнопок панели инструментов следует хранить вне бандла в директории ресурсов, чтобы поддерживать «родственность» графического интерфейса различных бандлов.
2. Атрибуты, связанные с представлением надписей кнопок (text, textposition) и их размеров (width, height), являются не обязательными.
3. При вертикальном расположении иконки и надписи (textposition = TOP | BOTTOM) надпись располагается над/под иконкой и выравнивается по центру.
4. Параметры GAV компонента можно не определять, если обработка события при его «выборе» обрабатывается самим бандлом, например, закрытие формы или выход из приложения.

Панель инструментов в форме OSGi-приложения

Ресурсные файлы свойств формы хранятся внутри бандла. При создании графического интерфейса формы необходимо извлечь соответствующий локализованный файл свойств, включающий подсказки кнопок панели инструментов, и описать структуру панели инструментов.

Метод чтения локальных свойств бандла

Для чтения соответствующего файла свойств можно использовать метод loadProperties, листинг которого представлен ниже. В качестве параметра методу необходимо передать объект текущей локализации Locale, который можно получить в бандле ресурсов util-resources. Сначала в методе формируется путь к соответствующему файлу свойств, после чего выполняется чтение содержимого файла с использованием методов загрузчика класса.

Описание

private final String RESOURCES = "properties/props";

private Properties loadProperties(final Locale locale)
{
    // Определение пути к файлу свойств
    String path = RESOURCES + "_" + locale.getLanguage()
                                  + ".properties";
    Properties properties = new Properties();
    InputStream is;
    try {
        // Чтение файла свойств
        is = getClass().getClassLoader()
                       .getResourceAsStream(path);
        properties.load(is);
    } catch (IOException e) {
        e.printStackTrace();
    }
    return properties;
}

Файлы свойств .properties

Подсказки кнопок панели инструментов хранятся в файлах свойств типа .properties. Следующий код демонстрирует описание англоязычных подсказок в файле свойств xxx_en.properties.

toolbar.add=Add
toolbar.about=About
toolbar.settings=Settings
toolbar.exit=Exit

Создание панели инструментов в форме OSGi-приложения

В следующем листинге приводится функция createToolbar, которая создает панель инструментов и возвращает объект JToolBar для его размещения в интерфейсе формы. В качестве параметров функция принимает контекст бандла context и объект текущей локализации. Структура панели инструментов описана в переменной TOOLBAR_xml.

Листинг

private ToolbarService toolbar = null;

private final String TOOLBAR_xml = 
    "<?xml version=\"1.0\" encoding=\"UTF-8\"?> "
  + "<root name=\"root\" rollover=\"true\" "
  +                     "borderpainted=\"true\"> "
  +  "<toolbar> "
  +   "<item name=\"toolbar.add\" type=\"button\" "
  +    "image=\"configuration/resources/images/add.png\" />"
  +  "</toolbar>"
  + "</root>";

private JToolBar createToolbar(final BundleContext context, 
                               final Locale locale)
{
    Properties props = loadProperties(locale);
    toolbar = new ToolbarServiceImpl(context);
    toolbar.createToolbar(props, TOOLBAR_xml);
    if (toolbar.getJToolBar() == null) {
        toolbar = null;
        return null;
    }
    return toolbar.getJToolBar();
}

Подключение обработчика события

Для выполнения определенного действий при выборе компонента панели инструментов к нему необходимо подключить соответствующего слушателя ActionListener. Следующий код демонстрирует подключение слушателя к кнопке "toolbar.add".

toolbar.addActionListener("toolbar.add", addListener);
. . .
ActionListener addListener = new ActionListener()
{
    public void actionPerformed(ActionEvent event) {
        System.out.println("Нажитие на кнопку ADD");
    }
};

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

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

Properties props = loadProperties(locale);
toolbar.changeLocale(props);

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

Панель инструментов во фрейме OSGi-приложения

Слушатель обработки событий

Во фрейме с кнопками панели инструментов связывают, как правило, другие бандлы, которые необходимо «активировать». Следующий пример показывает, как можно получить связанный бандл, проверить его активность и, при необходимости, стартовать.

Листинг

private JFrame frame;
. . .
ActionListener toolbarListener = new ActionListener() {
    public void actionPerformed(ActionEvent event) {
        if (event.getSource() instanceof JButton) {
          JButton button = (JButton) event.getSource();
          Bundle bundle;
          if (button != null) {
            bundle = frame.getToolbarCreater()
                          .getLinkedBundle(button.getName());
            if ((bundle != null) &&
                (bundle.getState() != Bundle.ACTIVE)) {
                try {
                    bundle.start();
                } catch (BundleException e) {
                    e.printStackTrace();
                }
            } else {
                System.out.println("ToolButton '" +
                                    button.getName()+ "'");
            }
          }
        }
    }
};

Создание панели инструментов

Описание структуры панели инструментов фрейма, а также локализованные свойства хранятся во внешних файлах приложения. Следующий метод демонстрирует чтение необходимых файлов, создание панели инструментов и размещение ее в интерфейса фрейма.

Листинг

private JFrame          frame  ;
private ToolbarService  toolbar;
. . .
private void createToolbar(ActionListener listener)
{
    if (listener == null) {
        toolbar = null;
        return;
    }
    IResources rsc = new ResourcesImpl();
    Document   doc = rsc.readToolbarStructure();

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

    String     sn   ;
    Properties props;

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

    toolbar = new ToolbarServiceImpl(context);
    toolbar.createToolbar(props, doc, listener);
    if (toolbar.getJToolBar() != null)
       frame.add(toolbar.getJToolBar(),BorderLayout.NORTH);
    else
       toolbar = null;
}

Если по каким-либо причинам панель иструментов не будет создана (нарушение структуры описания или отсутствие файла) объект управления панелью инструментов следут обнулить.

Обновление панели инструментов при смене Locale

Метод changeLocale обновляет подсказки панели инструментов формы согласно текущей Locale.

Листинг

ToolbarService  toolbar;
. . .
public void changeLocale()
{
    // Получение текущей Locale
    Properties props = null;
    IResources rsc  = new ResourcesImpl();
    if (rsc != null) {
        props = rsc.getResources(context.getBundle()
                                        .getSymbolicName());
        if (toolbar != null)
            toolbar.changeLocale(props);
    }
}

Пример

Пример использования gui-toolbar в приложении JaBricks представлен в Уроке 2. В Уроке 17 модуль используется в приложении с динамической загрузкой разноверсионных бандлов с одинаковым наименованием.

Версия 1.0.1

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

Зависимости

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

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

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

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

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

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

Скачать gui-toolbar

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