pod fwt

Fantom Widget Toolkit

Classes

AsyncTask

AsyncTask models an asynchronous operation's progress and provides a list of callback handlers when the task completes (either successfully or fails).

BorderPane

BorderPane is used paint a CSS styled border around a content widget.

Button

Button displays a push, toggle, check, or radio button with text and/or an image.

Canvas

Canvas is a custom widget which paints itself.

Clipboard

Clipboard provides access to the system clipboard for data transfer.

Combo

Combo is a combination of a text field and a list drop down.

Command

Command packages up the diplay name, icon, execution, and undo support for a user command.

CommandStack

Manages a stack of commands for undo/redo.

ConstraintPane

ConstraintPane is used to constrain the preferred width and height of its content widget.

ContentPane

ContentPane is the base class for panes which only contain one child widget called content.

Cursor

Mouse cursor.

Desktop

Desktop is used to model the user's operating system, window manager, and display monitors.

Dialog

Dialog is a transient window, typically used to notify or input information from the user.

EdgePane

EdgePane is a container which lays out four children along the four edges and one child in the center.

Event

Event models a user input event for callbacks.

EventListeners

EventListeners manages a list of event callback functions.

FileDialog

FileDialog is used to prompt for file and directory selections.

GridPane

GridPane is a container which lays out its children in a grid from left to right with a new row started based on numCols.

InsetPane

InsetPane creates padding along the four edges of its content.

Key

Key models a keyboard key or key combination.

Label

Label displays text and/or an image.

Menu

Menu contains MenuItems.

MenuItem

MenuItem is an individual item on a Menu.

Monitor

Monitor represents a display device like an LCD screen.

Pane

Pane is a container widget responsible for the layout of its children.

ProgressBar

ProgressBar displays a progess bar.

RichText

RichText is used to view and edit text styled with different fonts and colors.

RichTextModel

RichTextModel models the document and styling of a RichText document.

RichTextStyle

Defines the font and color styling of a text segment in a RichTextModel.

SashPane

SashPane lays out its children in a row or column with a sash control between each one to allow resizing.

ScrollBar

ScrollBar is used to position a widget too wide or tall to be visible at one time.

ScrollPane

ScrollPane displays a scrollbars to scroll its content child.

Tab

Tab is the child widget of a TabPane.

TabPane

TabPane is a container used organize a set of Tabs.

Table

Table displays grid of rows and columns.

TableModel

TableModel models the data of a table widget.

Text

Text is used to enter and modify text.

TextChange

Wraps up information regarding a text modification.

TextWidget

TextWidget is the base class for Text and RichText.

ToolBar

ToolBar contains a bar of Button children.

Tree

Tree displays a hierarchy of tree nodes which can be expanded and collapsed.

TreeModel

TreeModel models the data of a tree widget.

WebBrowser

WebBrowser is used to display HTML text or view a URL.

Widget

Widget is the base class for all UI widgets.

Window

Window is the base class for widgets which represent top level windows.

Enums

ButtonMode

Enum for Button.mode.

CommandMode

Enum for Command.mode.

EventId

EventId identifies the type of widget Event.

FileDialogMode

Enum for FileDialog.mode.

MenuItemMode

Enum for MenuItem.mode.

RichTextUnderline

Defines how to paint the underline of a RichText segment.

SortMode

Enum for Table.sortMode.

WindowMode

Enum for Window.mode.

Overview

Fantom Widget Toolkit or FWT provides a toolkit for building both desktop and HTML5 browser based applications:

  • Widgets are reusable UI components such as buttons, text fields, dialogs, etc
  • Graphics for 2D rendering
  • Eventing for user input: keyboard, mouse, and focus eventing
  • UI layout

The fwt defines the basic low level infrastructure for applications. Flux is built on top of the fwt to provide a more advanced application framework for desktop apps.

Widgets

The Widget class is the root of the widget class hierarchy. Widgets represent UI components such as buttons or text fields.

Widget Tree

Widgets are structured as a tree. Typically the root of a visible widget tree is a Window on the screen. Any widget is a potential container for other widgets - although typically only Panes contain children. The following methods are used to work with the widget tree:

A widget may only be mounted under one parent. If you attempt to add a widget to multiple parents an exception is thrown.

Panes

Widgets come in two flavors: panes and controls. Panes are widgets which are designed to be containers for other widgets. Panes are responsible for laying out their children. Widgets which don't subclass from Pane are most often leaf widgets which provide some control such as a button or text field.

Custom Widgets

Most often you will use the predefined widgets in the toolkit. However you can create your own widgets too. Typically you will subclass Pane to create a new container widget or Canvas for a new control. Panes are responsible for deciding how to layout their children. Controls will typically define custom painting and eventing.

Painting

Canvas widgets may override the onPaint method to provide custom painting. Painting is done via the Graphics API:

  • draw geometries
  • fill geometries
  • draw text
  • draw images
  • coordinate system transformations
  • clipping

A Graphics instance maintains state for how it renders:

  • Pen defines how geometries are drawn
  • Brush defines how geometries and text are drawn and filled
  • Font defines how text is rendered
  • Image models an image - typically loaded from a png, gif, or jpeg file
  • current clipping region
  • current transform to apply to the coordinate system

You can use the push and pop methods to create a stack of Graphics instances and their associated state. A typical pattern is:

g.push
try
{
  g.translate(...)
  ...
}
finally
{
  g.pop
}

The following is a simple widget which paints itself as a red box with a blue outline:

using gfx
using fwt
class RedBox : Canvas
{
  override Void onPaint(Graphics g)
  {
    w := size.w
    h := size.h
    g.brush = Color.red
    g.fillRect(0, 0, w, h)
    g.brush = Color.blue
    g.drawRect(0, 0, w-1, h-1)
  }

  Void main()
  {
    Window { InsetPane { content = RedBox() }, }.open
  }
}

Layout

Every widget plays a role in how the UI is laid out. Leaf widgets define a preferred size by overriding the prefSize method. The prefSize method takes a Hints which contains an optional width and height constraint.

Panes which contain children implement a layout strategy by overriding the onLayout method. This callback is used to set the bounds of all the children widgets. Often panes will also override prefSize to compute the containers preferred size from the children.

Eventing

All widgets support a set of eventing callbacks which by convention start with the "on" prefix. Widget events are declared as fields of type EventListeners which maintain a list of callback functions. Event callbacks take a single Event argument. Refer to the fandoc of each event to see how the Event fields are used.

The following illustrates a simple text field with some event handlers:

class EventTest
{
  Void main()
  {
    text := Text
    {
      onAction.add |->| { echo("onAction!") }
      onModify.add |event| { echo(event) }
    }

    Window { GridPane { text, }, }.open
  }
}

The example illustrates creating two callbacks using closures. The onAction event handler is a closure with no arguments (remember that you can use functions which take fewer arguments). The onModify event handler takes an event parameter.

Commands

A common technique in user interfaces to separate the UI elements from the command logic. For example you might have both a menu item and a toolbar button for a "Save" command. The Command class is used to manage this design pattern.

Commands are responsible for the text, icon, accelerator, and how a command is executed. Commands may optionally handle undo/redo. Often the visual elements of a command are stored in a localization props file. For example to create a localized "Save" command:

// locale/en.props
save.name=Save
save.icon=fan://icons/x16/save.png
save.accelerator=Ctrl+S

// create Command instance
save := Command.makeLocale(Pod.find("flux"), "save") |->| { echo("save!") }

You can create UI widgets from commands:

menu.addCommand(save)
toolBar.addCommand(save)

Widgets which are mapped to a command are said to be registered. Registration occurs automatically when setting a widget's command field. If you create your own custom widgets with command support you should follow the pattern used by Button and MenuItem. Once a widget is registered with a command, it tracks the command's state. For example enabling or disabling the command will automatically enable/disable as its registered widgets. For toggle commands its widgets automatically track the command's select state.