flexui v0.2.0

FlexUI v0.2

Example: https://cdn.rawgit.com/rogual/flexui/master/ui-example.html

This implements a non-overlapping tabbed UI for Javascript. It's early days and, while it should work, you can easily break it by writing to properties you shouldn't.

Spaces and Panels

Spaces are arranged in a tree. Split spaces have 2 or more children; leaf spaces have 1 or more panels.

Split spaces can be horizontal or vertical. Each split space is the opposite orientation from its parent.

The above constraints are enforced by the function space.normalize(), or its recursive version space.normalizeTree(). These are usually called for you at the right times, but if you are reaching in and deleting spaces or moving panels around from code, you will need to normalize any spaces you touch if you want your tree to stay nice.

Inside each Space, one Panel can be active, and is displayed in the space.

Additionally, Spaces may reserve some of their screen area to draw some form of UI. By default, a tab bar is drawn.

Panels can be dragged to other Spaces, or to the dividing lines between spaces, which causes a new Space to open there.

Spaces must all share the same configuration, since FlexUI will need to create new ones on its own.

Things about Spaces which can be customized: - How to indicate the panel list and current panel - If using the default tabstrip view, then: - Tab elements can be customized - Tabstrip element itself can be customized - Otherwise, custom UI and drop targets can be defined.

Theming

Theming is by way of CSS -- see ui-example.html which implements two themes.

Caveats

• Do not keep references to Spaces -- FlexUI removes Spaces all the time when it's reshuffling the tree and your references will become invalid very quickly.

• While this rudimentary documentation exists, this is very much one of those “read the code” projects. The examples might be a good place to start.

API Reference follows.

Utility functions

FlexUI.installDefaultCSS()

Call this before using FlexUI.

OriTree interface

Tree node where: | Node either has n>=2 children or is a leaf | Node has a direction ('row' or 'column') | Node's direction must be different from its parent's direction | Root node can have either direction

Implementations: Frame, Area, Space

Properties: | oritree.parent | oritree.children | oritree.direction

Methods: | oritree.insertBeforeIndex(i, oritree) | oritree.insertAfterIndex(i, oritree) | oritree.insertBeforeChild(existingChild, oritree) | oritree.insertAfterChild(existingChild, oritree) | oritree.insertBeforeSelf(oritree) | oritree.insertAfterSelf(oritree) | oritree.deleteSelf() | oritree.replaceSelf(oritree) | oritree.getRoot() | oritree.normalize() -- call after deleting children

Frame: OriTree

OriTree implementation where nodes are HTML elements (frame.elem) laid out with CSS flexbox.

Examples: frames-fixed, frames-resizable, frames-dynamic

Constructors: | frame = FlexUI.frame(childFrames) | frame = FlexUI.separator()

Properties: frame.elem

Area: OriTree

Layer on top of Frames, where Areas maintain resize handles between themselves.

Example: areas-dynamic

Constructors: | area = FlexUI.area(childAreas)

Properties: | area.frame | area.elem (= area.frame.elem)

Space: OriTree

Layer on top of Areas implementing a user-configurable non-overlapping UI panel layout.

Constructors: | space = FlexUI.splitSpace(childSpaces) | space = FlexUI.leafSpace(panels)

Properties: | space.panels | space.activePanel

Methods: | space.addPanel(panel) | space.removePanel(panel) | space.setActivePanel(panel | index | null)

Panel

Panels are plain Javascript objects. Each panel needs to have an 'elem' property referring to its HTML element. The default tabbed space delegate also expects panels to have 'name' and 'closable' properties.

FlexUI will also create and maintain a 'space' property on each panel.

Drag & Drop Helpers

Utilities for allowing users to drag panels between Spaces. If you are using the default tabbed space delegate, you probably won't need these.

Functions: | FlexUI.makeDragSource(elem, panel) | FlexUI.removeDragSource(elem)

Elements which have been made into drag sources can be dragged to spaces. Their associated panels will then move to the chosen space.

| FlexUI.makeDragHandle(dragElem, separator)

Makes an element behave as if it were a separator between two spaces. The separator argument should be the separator element the dragElem should behave as, or a function returning such. While the function returns null, the element will not function as a separator.

Space Delegate

You can replace the Space Delegate using FlexUI.setSpaceDelegate(newDg).
The default Space Delegate is FlexUI.tabSpaceDelegate.

Methods:
  | delegate.init(space)
  | delegate.modified(space)
  | delegate.setPanels(space, panels)
  | delegate.setActivePanel(space, panel, index)

  | delegate.panelDraggedOver(event)
  | delegate.panelDraggingOver(event)
  | delegate.panelDraggedOut(event)
  | delegate.panelDropped(event)

  | delegate.makeTab(space, panel)
  | delegate.buildTabBar(space)

  | delegate.layout()
  | delegate.focusPanel(panel)