Skip to content

Latest commit

 

History

History
133 lines (94 loc) · 10.5 KB

README.adoc

File metadata and controls

133 lines (94 loc) · 10.5 KB
Raw

documentation of mmm-ui-api

This mmm-ui-api provides a portable and toolkit-agnostic API to build user-interfaces (UIs). For a detailed introduction see our motivation. It defines central interfaces like UiNotifier or UiLocalizer that provide functinal services for your UI. Such interfaces therefore have a static get method that allows you to get access to the singleton instance.

widgets

The heart of this API are the many widget interfaces starting with UiWidget. First, you should understand the following type of widgets:

  • UiNativeWidget is the super-interface of all native widgets. When programming with interfaces we need to know what interfaces are "instantiable" (non-abstract). Therefore these widget interfaces extend UiNativeWidget. As widgets are technically created via UiWidgetFactoryNative and the create method only takes classes that extend UiNativeWidget, we even get type-safety and cannot create widgets from non-native interfaces. However, all interfaces extending UiNativeWidget will have one or multiple static of methods. These methods act as a "constructor" that allows you to easily instantiate the widget. In the below UML diagrams native widgets are highlighted with green color.

  • UiRegularWidget is the super-interface of all regular widgets. A regular widget can be added as child widget to any normal panel or composite widget. This applies to most widgets but some like UiMenuBar, UiTab, UiColumn, etc. are not regular.

  • UiComposite is the super-interface of all composite widgets. A composite widget can contain one or typically multiple child widgets. Widgets extending UiMutableComposite are very flexible composite widgets and allow to dynamically add and remove any number of children. Panels are composite widgets that are used as generic containers to layout their children in a specific way. Most of them extend UiMutablePanel.

  • UiAbstractWindow is the super-interface of all window widgets. UiMainWindow is the main window of your client app. If your client runs in the browser this will represent the browser window or more technically the document body. You can create UiWindows or modal UiPopups that can be opened and closed dynamically by your client app.

  • UiCustomWidget is the interface for custom widgets. AbstractUiCustomWidget is an abstract class implementing this interface and is part of mmm-ui-api. When you create your client from only interfaces it is kind of hard to build reusable units of your UI. To make this API cool and fun to use, we introduce custom widgets that are implemented as regular Java classes and act as a delegate wrapping a native widget. This allows you to create any kind of composite panel for your UI as a regular class that can be instantiated with a regular constructor and reused easily. We already ship with abstract base classes for common panels and composite inputs.

  • UiInput is the super-interface of all input widgets. Such input widget is used to display and edit values. There are native widget interfaces for all kind of inputs such as UiTextInput, UiTextArea, UiRadioChoice, UiComboBox, UiDateTimeInput, and whatever you need. The smart thing is that each input widget has a name and UiLabel (lazily created) associated. This makes it much simpler to create forms and gives you according accessibility ascpects automatically. Further, input widgets extend from UiValidatableWidget what brings validation support and also comes with build-in dirty check and many other higher-level features.

Controllers

A UiController defines a routing place in your client app. It implements any place you can navigate to. Typically a UiController simply creates a view (dialog) and defines where to embed it into your UI. The UiNavigationManager is a singleton that allows you to navigate back, forward or to new places and controllers. Your end-user will also be able to navigate back, forward and to specific places even if your client does not run in the browser but as JavaFx desktop app or on android.

Getting started

The best way to understand how things work is looking at our demo app mmm-ui-demo. If you want to create your own app based on our mmm framework, please use our app template.

UML Diagrams

To quickly get an overview of the rich and therefore manybe complex mmm-ui-api we provide the following UML diagrams. Important types are colored so you can easily find the more important things.