Библиотека компонентов

Библиотека компонентов gui-widgets предназначена для формирования графического интерфейса как desktop'ных Swing-приложений, так и приложений на платформе Jabricks. Библиотека выполнена по технологии OSGi и содержит следующий набор визуальных компонентов :

Примечание :
1. Скриншоты использования библиотеки визуальных компонентов gui-widgets представлены на странице описания приложения «Домашние финансы».
2. Библиотека визуальных компонентов gui-widgets имеет прототип base-gui, представленный и подробно описанный на сайте, включая примеры использования. Отличия касаются только возможности использования библиотеки gui-widgets в OSGi-приложении и дополнительного включения в библиотеку панели с набором вертикально располагаемых кнопок ToolButtons, а также интерфейса org.jabricks.widgets.constants.IWidgetsConstants, включающего константы как для создания интерфейса, так и для межмодульного взимодействия при реализации механизма «публикация/подписка».

Описанные в библиотеке base-gui примеры можно также использовать с библиотекой gui-widgets.

Описание библиотеки

Список классов, интерфейсов и ресурсов библиотеки представлен в таблице по-пакетно :

Активатор модуля, org.jabricks.widgets

Активатор модуля WidgetsActivator включает «пустые» методы start и stop. Основная функция активатора связана с формированием бандла (bundle) по технологии OSGI.

Компоненты числовых значений, org.jabricks.widgets.numberfields

Компоненты представления числовых значений в интерфейсе приложения : IntegerField, FloatField, DoubleField. Описания компонентов и примеры их использования представлены на странице Числовые компоненты библиотеки прототипа base-gui.

Таблица Grid, org.jabricks.widgets.grid

Табличный компонент предназначен для представления ограниченного количества записей в интерфейсе приложения. Компонент таблицы локализован и позволяет без «перезагрузки» формы определить заголовки колонок таблицы согласно текущему значению языка локализации. Классы визуализаторов позволяют настроить представление значений разных типов в ячейках таблицы. API Grid, представленное на странице прототипа библиотеки base-gui, позволяет управлять записями (добавлять, обновлять, удалять) и организовать в таблице редактируемую колонку с компонентом JCheckBox для выделения записей. Использование таблицы в java-приложении рассмотрено на странице описания примера Grid прототипа библиотеки. Создание редактируемой колонки с возможностью выделения записей рассмотрено в примере JCheckBox в таблице.

Таблица Gridp с панелью навигации, org.jabricks.widgets.gridp

Табличный компонент Gridp с панелью навигации предназначен для постраничного разбиения записей и представления в интерфейсе неограниченного количества записей. Как правило, данный компонент следует использовать для просмотра записей «рабочих» таблиц с большим набором данных. Также, как и для обычной таблицы Grid, данный компонент позволяет заменить используемые по умолчанию визуализаторы записей.

Компонент Gridp отображает в таблице набор данных в виде одной страницы. Представленное на странице прототипа библиотеки API Gridp демонстрирует возможности управления записями (добавление, обновление, удаление) и включает методы, вызываемые компонентом для перемещения по страницам. Разработчик должен переопределить данные методы для чтения записей определенной страницы в хранилище (сервере БД).

Пример Gridp прототипа библиотеки демонстрирует возможности таблицы панелью навигации и включает исходные коды.

Дерево Tree, org.jabricks.widgets.tree

Компонент дерева Tree позволяет представить в интерфейсе приложения иерархическую многоуровневую структуру записей, основой которых является класс TreeRecord. API дерева (ITree) позволяет добавлять, обновлять и удалять записи в дереве. При выделении записи в дереве вызывается callback-функция интерфейса ITreeListener, передающая родителю выбранный объект. Подробное описание визуального компонента Tree представлено на странице примера API Tree прототипа библиотеки base-gui. Использование Tree в java-приложении рассмотрено на странице описания пример Tree.

TreeTable, org.jabricks.widgets.treetable

JTreeTable предназначен для многоуровнего иерархичного отображения набора записей в табличном виде. Компонент таблицы локализован и позволяет без «перезагрузки» формы определить заголовки колонок таблицы согласно текущему значению языка локализации. API JTableTable позволяет управлять записями (добавлять, обновлять, удалять). Использование таблицы в java-приложении рассмотрено на странице описания примера JTreeTable.

Компонент JTreeTable используется в интерфейсном бандле Справочник единиц измерения.

Панель кнопок инструментов, org.jabricks.widgets.toolbuttons

Панель с набором вертикально располагаемых кнопок ToolButtons, выполняющих роль панели инструментов, имеет API, которое позволяет адаптировать интерфейс как панели, так и кнопок (размер, шрифт, цвет и т.д), под заданные требования, а также выделить подсветкой одну из активных кнопок в наборе. ToolButtons имеет два конструктора; второй конструктор в качестве параметра получает «слушателя» IButtonsListener. Слушатель представляет родительский класс, единственный метод которого onButtonItemClick (String) вызывается при нажатии на одну из кнопок панели инструментов. В метод onButtonItemClick (String) передается наименование/заголовок нажимаемой кнопки.

public ToolButtons ();
public ToolButtons (final IButtonsListener listener);

В таблице представлены методы ToolButtons, которые можно использовать для формирования интерфейса панели вертикально расположенных кнопок :

Пример использования компонента ToolButtons представлен в примере ExampleToolbuttons :

Пример использования ToolButtons

Листинг

import java.awt.Font;
import java.awt.Color;
import java.awt.Dimension;
import java.awt.BorderLayout;

import javax.swing.JFrame;
import javax.swing.JPanel;
import javax.swing.ImageIcon;
import javax.swing.BorderFactory;
import javax.swing.border.Border;

import org.jabricks.widgets.common.VerticalLayout;
import org.jabricks.widgets.toolbuttons.ToolButtons;
import org.jabricks.widgets.toolbuttons.IButtonsListener;

public class ExampleToolbuttons extends JFrame 
                                implements IButtonsListener
{
    private  ToolButtons  bp = null;

    private  final  String[]  UNITS_names = {"btnCash",
                                             "btnBank",
                                             "btnEmoney"};
    private  final  String[]  UNITS_text  = {"Cash",
                                             "Bank",
                                             "Emoney"};
    private  final  ImageIcon[]  UNITS_icons = {
                       null, // new ImageIcon("D:/db.png"),
                       null, // new ImageIcon("D:/ln.png"),
                       null};
    //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    public ExampleToolbuttons()
    {
        super("Toolbuttons example");
        setDefaultCloseOperation(EXIT_ON_CLOSE);
        setSize(640, 480);
        createGUI();
        setVisible(true);
    }
    //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    private void createGUI()
    {
        JPanel pnl = new JPanel();
        pnl.setBackground(Color.blue);

        bp = new ToolButtons(this);
        bp.addTitle("Список счетов");
        bp.setTitleHeight(36);
        bp.setTitleFont(new Font("Arial", Font.BOLD, 14)); 
        bp.setVerticalLayout (new VerticalLayout(8, 10));

        bp.setButtonItems(UNITS_names, 
                          UNITS_text,
                          UNITS_icons);
        getContentPane().add(pnl, BorderLayout.CENTER);
        getContentPane().add(bp , BorderLayout.WEST);
    }
    //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    @Override
    public void onButtonItemClick(String name)
    {
        bp.selectButtonItem(name);
        System.out.println("selectedButtonItem = " + 
                            bp.getSelectedButtonItem());
    }
    //~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    public static void main(String[] args)
    {
        new ExampleToolbuttons();
    }
}

Интерфейсные константы, org.jabricks.widgets.interface

Интерфейс IwidgetsConstants включает набор констант для формирования интерфейса и организации межмодульного взаимодействия бандлов OSGi-приложениий по технологии «публикация/подписка». Модификаторы public final для всех констант в листинг не включены, чтобы не загромождать описание. Комментарии к константам недвусмысленно говорят об их назначении в приложении.

Листинг

public interface IWidgetsConstants 
{
    String  EMPTY           = ""   ;
    String  POINT           = "."  ;
    String  COMMA           = ","  ;
    String  COLON           = ":"  ;
    String  SEMICOLON       = ";"  ;
    String  LF              = "\n" ;
    String  SPLIT_point     = "\\.";
    String  SLASH           = "/"  ;
    String  SPACE           = " "  ;
    String  EQUAL           = "="  ;
    String  LOW_LINE        = "_"  ;
    String  ENCODING_UTF8   = "UTF-8";

    String   GUI_dir        = "gui/" ;
    String   EXT_xml        = ".xml" ;
    String   dbObject_table = "table";
    String   dbObject_view  = "view" ;

    // Константы объекта локализаций интерфейса
    String  LANG_ru         = "ru" ;
    String  COUNTRY_RU      = "RU" ;
    String  LANG_en         = "en" ;
    String  COUNTRY_EN      = "US" ;
    String  LANG_de         = "de" ;
    String  COUNTRY_DE      = "DE" ;

    // Константы протоколирования сообщений
    int     LOG_LEVEL_SQL   = 5    ;
    int     LOG_LEVEL_OSGi  = 6    ;

    // Шаблоны протоколируемых  сообщений
    String  LOG_EVENT_topic = " get event on topic : "     ;
    String  LOG_EVENT_prop  = " : propertyName (%s) = %s"  ;
    String  LOG_EVENT_send  = " : send '%s'"               ;

    String  LOG_MSG_create  = "DB Object '%s' was created" ;

    // Размер разделителя панелей (по ширине)
    int     DIVIDER_SIZE    = 6;  
    
    // Ресурсные константы
    String  RESOURCES_props = "properties/props"           ;
    String  EXT_properties  = ".properties"                ;
    String  RESOURCE_title  = "title"                      ;

    // Настройки приложения
    String INI_page_records = "page.records"               ;
    String INI_date_format  = "date.format"                ;
    String INI_money_format = "money.format"               ;

    // Директория конфигурации приложения
    String  DIR_config      = "configuration/"             ;
    
    String  BUNDLE_id       = "bundle.id"                  ;
    String  BUNDLE_SN       = "bundle.symbolicName"        ;
    String  BUNDLE_VERSION  = "bundle.version"             ;

    // Сообщения межмодульного обмена информацией
    String  EVENT_locale    = "jabricks/LocaleEvent"       ;
    String  EVENT_connect   = "jabricks/DBConnect"         ;

    String  EVENT_request   = "jabricks/Container/Request" ;
    String  EVENT_response  = "jabricks/Container/Response";

    String  EVENT_mode_req  = "jabricks/GuiMode/Request"   ;
    String  EVENT_mode_resp = "jabricks/GuiMode/Response"  ;

    String  EVENT_pnl_req   = "jabricks/Panel/Request"     ;
    String  EVENT_pnl_resp  = "jabricks/Panel/Response"    ;

    // Константы сообщений
    String  PROP_locale     = "locale"                     ;
    String  PROP_connect    = "connect"                    ;
    String  PROP_container  = "container"                  ;

    // Константа отображения надписей в «нормальном стиле»
    String  SPAN_normal = "<html> span "
                        + "<style=\"font-weight:normal\">";
}

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

Визуализаторы табличных значений, org.jabricks.widgets.renderers

Используемые по умолчанию визуализаторы записей таблиц Grid и Gridp реализуют (implements) функции интерфейса TableCellRenderer и расширяют (extends) свойства метки типа JLabel. Это позволяет выравнивать значения в колонках для каждого типа либо по левому/правому краю, либо по центру. Кроме этого, визуализаторы позволяют определить подсветку выделенных строк/ячеек таблиц.

Разработчик может подключить собственный визуализатор с индивидуальными настройками, как это представлено в примере Grid.

Компонент JDdatePicker для выбора даты из календаря, org.jdatepicker.*

Компонент JDatePicker представляет текстовое поле с кнопкой, при нажатии на которую открывается окно с календарем для выбора даты. В основе компонента лежит код, созданный группой разработчиков Juan Heyns, JC Oosthuizen, Yue Huang. Доработанный компонент локализован для русского, английского и немецкого языков, позволяет определить первый день недели [Воскресенье, Понедельник]. Кроме этого, выпадающее окно календаря автоматически привязывается к правому/левому краю текстового поля даты в зависимости от расположения компонента на экране.

Подробное описание компонента представлено на странице API JDatePicker прототипа библиотеки base-gui. Использование компонента в java-приложении рассмотрено на странице описания примера JDatePicker.

Ресурсы модуля, resources

Ресурсы модуля base-gui.jar в виде файлов изображений (*.png) и файлов свойств (*.properties) располагаются в директории resources/images и resources/properties. Файлы изображений используются в панели навигации табличного компонента Gridp, в компоненте даты JDatePicker, при отображении записей в иерархической структуре дерева Tree. Файлы свойств хранят локализованные надписи 3-х языков («ru» русский, «en» английский, «de» немецкий) для панели навигации таблицы Gridp и компонента даты JDatePicker.

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

Версия 1.0.2

Библиотека компонентов версии 1.0.2 реализует свойства своих предшественников и дополнительно включает следующие методы, используемые для именования таблиц Grid, Gridp :

public interface org.jabricks.widgets.grid.IGrid 
{
    . . .

    public  void    setGridName(final String name);
    public  String  getGridName();

    . . .
}

public interface org.jabricks.widgets.gridp.IGridp 
{
    . . .

    public  void    setGridName(final String name);
    public  String  getGridName();

    . . .
}

Данные методы облегчают процесс именования табличных компонентов типа Grid, Gridp, необходимого при реализации функции сохранения и восстановления значений.

Версия 1.0.3

Библиотека компонентов версии 1.0.3 дополнительно включает числовой компонент типа LongField. Подробнее о числовых компонентах библиотеки представлено здесь.

Компонент целочисленного значения включает методы определения и чтения значений поля типа long и Long, метод разрешения/запрета использования отрицательного значения, как это представлено в следующем листинге :

public long getLong();
public void setLong(long value);

public Long getValue();
public void setValue(Long value);

public void setNegativeAccepted(boolean negativeaccepted);

Версия 1.0.4

В библиотеке gui-widgets версии 1.0.4 доработан интерфейс компонента определения даты JDdatePicker. Всплывающее окно календаря, при размещении компонента в "приграничных" частях экрана, не выходит за его пределы.

Версия 1.0.5

В библиотеку gui-widgets версии 1.0.5 добавлен интерфейсный компонент TreeTable табличного представления иерархического набора данных; иерархия набора представлена в первой колонке таблицы.

Зависимости

Модуль gui-widgets имеет следующие зависимости, определенные в секции Import-Package манифеста (MANIFEST.MF) и загружаемые фреймворком при старте приложения :

• org.osgi.framework – фреймворк Felix
• javax.swing.*, javax.imageio классы пакетов

В секции Export-Package манифеста (MANIFEST.MF) определены следующие доступные в приложении OSGi пакеты

• org.jabricks.widgets.* – представленные выше визуальные компоненты;
• org.jdatepicker.* – компонент выбора даты из календаря

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

Для подключения бандла gui-widgets в приложение Jabricks достаточно :

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

Стартовать бандл gui-widgets не требуется. Для модулей приложения, использующих бандл gui-widgets необходимо его инсталлировать во фреймворк.

GAV параметры

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

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

Скачать gui-widgets

Рассмотренный на странице модуль с компонентами формирования графического интерфейса gui-widgets-1.0.5.jar имеет размер 139 Кб.