com.leafdigital.ui.api
Interface UI

All Superinterfaces:
Singleton

public interface UI
extends Singleton

Main UI singleton.

Access this to create new UI objects or control global UI features.

The leafChat UI is, in general, thread-safe.


Field Summary
static int BUTTON_CANCEL
          'Cancel' button bitfield constant for showQuestion
static int BUTTON_NO
          'No' button bitfield constant for showQuestion
static int BUTTON_YES
          'Yes' button bitfield constant for showQuestion
static int UISTYLE_MULTIWINDOW
          UI style: multi-window style
static int UISTYLE_SINGLEWINDOW
          UI style: single window 'classic' style
static int UISTYLE_TABBED
          UI style: tabbed
 
Method Summary
 void activate()
          Activates the app.
 Dialog createDialog(org.w3c.dom.Document d, java.lang.Object callbacks)
          Deprecated. Use createDialog(String, Object) instead
 Dialog createDialog(java.lang.String xml, java.lang.Object callbacks)
          Creates a Dialog from an XML document.
 Page createPage(org.w3c.dom.Document d, java.lang.Object callbacks)
          Deprecated. Use createPage(String, Object) instead
 Page createPage(java.lang.String xml, java.lang.Object callbacks)
          Creates a Page from an XML document.
 Widget createWidget(org.w3c.dom.Document d, WidgetOwner owner)
          Creates a Widget from an XML document.
 Window createWindow(org.w3c.dom.Document d, java.lang.Object callbacks)
          Deprecated. Use createWindow(String, Object) instead
 Window createWindow(java.lang.String xml, java.lang.Object callbacks)
          Creates a Window from an XML document.
 Theme[] getAvailableThemes()
          Obtains the list of available themes.
 Theme getTheme()
          Obtains the user's selected theme.
 java.io.File getThemeFolder(boolean system)
          Obtains the folder used for themes.
 int getUIStyle()
           
 void installUserTheme(java.io.File newTheme)
          Installs a new theme file into the user's theme folder, checking it for errors.
 boolean isAppActive()
           
 BorderPanel newBorderPanel()
           
 Button newButton()
           
 ButtonPanel newButtonPanel()
           
 CheckBox newCheckBox()
           
 ChoicePanel newChoicePanel()
           
 DecoratedPanel newDecoratedPanel()
           
 Dialog newDialog(java.lang.Object callbacks)
          Creates a new Dialog.
 Dropdown newDropdown()
           
 EditArea newEditArea()
           
 EditBox newEditBox()
           
 GroupPanel newGroupPanel()
           
 HorizontalPanel newHorizontalPanel()
           
 Widget newJComponentWrapper(javax.swing.JComponent c)
          Creates a widget wrapper for a JComponent.
 Label newLabel()
           
 ListBox newListBox()
           
 Page newPage()
           
 Page newPage(java.lang.Object callbacks)
          Creates a new Page.
 Pic newPic()
           
 PopupMenu newPopupMenu()
           
 Progress newProgress()
           
 RadioButton newRadioButton()
           
 ScrollPanel newScrollPanel()
           
 Spacer newSpacer()
           
 SplitPanel newSplitPanel()
           
 Table newTable()
           
 TabPanel newTabPanel()
           
 TextView newTextView()
           
 TreeBox newTreeBox()
           
 VerticalPanel newVerticalPanel()
           
 Window newWindow(java.lang.Object callbacks)
           
 void refreshTheme()
          Refreshes the current theme to take account of user style changes (userstyle.css).
 void registerTool(Tool t)
          Registers a new Tool that will be placed on the toolbar.
 void resizeToolbar()
          Tools can call this command to make the system resize the toolbar as appropriate given changed content.
 void runInThread(java.lang.Runnable r)
          Runs a task in the user-interface/event thread.
 void setTheme(Theme t)
          Sets the selected theme (should be called by preferences, which for technical reasons has to be in a different plugin).
 void setUIStyle(int uiStyle)
          Changes the current UI style and remembers it in preferences.
 java.awt.Color showColourSelect(WidgetOwner parent, java.lang.String title, java.awt.Color original)
          Shows a colour-select dialog.
 java.io.File showFileSelect(WidgetOwner parent, java.lang.String title, boolean saveMode, java.io.File folder, java.io.File file, java.lang.String[] extensions, java.lang.String filterName)
          Shows a file-select dialog as appropriate for the platform.
 java.io.File showFolderSelect(WidgetOwner parent, java.lang.String title, java.io.File folder)
          Shows a folder-select dialog as appropriate for the platform.
 void showLatest()
          Switches to the window with most recent changes (if any window has changes).
 int showOptionalQuestion(java.lang.String prefID, WidgetOwner parent, java.lang.String title, java.lang.String message, int buttons, java.lang.String yesLabel, java.lang.String noLabel, java.lang.String cancelLabel, int defaultButton)
          Shows a dialog with don't-show-this-again feature.
 int showQuestion(WidgetOwner parent, java.lang.String title, java.lang.String message, int buttons, java.lang.String yesLabel, java.lang.String noLabel, java.lang.String cancelLabel, int defaultButton)
          Show a yes/no/cancel confirm dialog.
 void showUserError(WidgetOwner parent, java.lang.String title, java.lang.String message)
          Displays an alert dialog indicating some kind of error, with an OK button
 void unregisterTool(Tool t)
          Unregisters an existing Tool and removes it from the toolbar.
 

Field Detail

BUTTON_YES

static final int BUTTON_YES
'Yes' button bitfield constant for showQuestion

See Also:
Constant Field Values

BUTTON_NO

static final int BUTTON_NO
'No' button bitfield constant for showQuestion

See Also:
Constant Field Values

BUTTON_CANCEL

static final int BUTTON_CANCEL
'Cancel' button bitfield constant for showQuestion

See Also:
Constant Field Values

UISTYLE_SINGLEWINDOW

static final int UISTYLE_SINGLEWINDOW
UI style: single window 'classic' style

See Also:
Constant Field Values

UISTYLE_MULTIWINDOW

static final int UISTYLE_MULTIWINDOW
UI style: multi-window style

See Also:
Constant Field Values

UISTYLE_TABBED

static final int UISTYLE_TABBED
UI style: tabbed

See Also:
Constant Field Values
Method Detail

newWindow

Window newWindow(java.lang.Object callbacks)
Parameters:
callbacks - Object used for callback methods
Returns:
A new Window

newDialog

Dialog newDialog(java.lang.Object callbacks)
Creates a new Dialog.

The use of dialogs should be avoided as they are modal; while a dialog is shown, users cannot access other windows.

Parameters:
callbacks - Object used for callback methods
Returns:
A new Dialog

newPage

Page newPage(java.lang.Object callbacks)
Creates a new Page. Pages can be inserted within other windows or dialogs and have an independent set of IDs.

Parameters:
callbacks - Object used for callback methods
Returns:
A new Page

newPage

Page newPage()
Returns:
A new Page (as a widget within an existing dialog)

newBorderPanel

BorderPanel newBorderPanel()
Returns:
A new BorderPanel

newSplitPanel

SplitPanel newSplitPanel()
Returns:
A new SplitPanel

newVerticalPanel

VerticalPanel newVerticalPanel()
Returns:
A new VerticalPanel

newHorizontalPanel

HorizontalPanel newHorizontalPanel()
Returns:
A new VerticalPanel

newGroupPanel

GroupPanel newGroupPanel()
Returns:
A new GroupPanel

newTabPanel

TabPanel newTabPanel()
Returns:
A new TabPanel

newChoicePanel

ChoicePanel newChoicePanel()
Returns:
A new ChoicePanel

newScrollPanel

ScrollPanel newScrollPanel()
Returns:
A new ScrollPanel

newDecoratedPanel

DecoratedPanel newDecoratedPanel()
Returns:
A new DecoratedPanel

newButtonPanel

ButtonPanel newButtonPanel()
Returns:
A new ButtonPanel

newLabel

Label newLabel()
Returns:
A new Label

newPic

Pic newPic()
Returns:
A new Image

newTextView

TextView newTextView()
Returns:
A new TextView

newButton

Button newButton()
Returns:
A new Button

newRadioButton

RadioButton newRadioButton()
Returns:
A new RadioButton

newCheckBox

CheckBox newCheckBox()
Returns:
A new CheckBox

newDropdown

Dropdown newDropdown()
Returns:
A new dropdown list

newEditBox

EditBox newEditBox()
Returns:
A new EditBox

newEditArea

EditArea newEditArea()
Returns:
A new EditArea

newListBox

ListBox newListBox()
Returns:
A new ListBox

newTreeBox

TreeBox newTreeBox()
Returns:
A new TreeBox

newTable

Table newTable()
Returns:
A new Table

newProgress

Progress newProgress()
Returns:
A new Progress

newSpacer

Spacer newSpacer()
Returns:
A new Spacer

newPopupMenu

PopupMenu newPopupMenu()
Returns:
A new PopupMenu

newJComponentWrapper

Widget newJComponentWrapper(javax.swing.JComponent c)
Creates a widget wrapper for a JComponent.

Though leafChat UI is thread-safe, this of course does not apply to the Swing component. Be careful when calling methods on the Swing component.

Parameters:
c - Swing component
Returns:
Widget wrapping the JComponent

createWidget

Widget createWidget(org.w3c.dom.Document d,
                    WidgetOwner owner)
Creates a Widget from an XML document.

Parameters:
d - XML widget document
owner - Window that maintains a list of IDs for the created widgets
Returns:
Top-level widget
Throws:
BugException - If the XML document is invalid

createWindow

Window createWindow(org.w3c.dom.Document d,
                    java.lang.Object callbacks)
Deprecated. Use createWindow(String, Object) instead

Creates a Window from an XML document.

Parameters:
d - XML document describing the window
callbacks - Object used for callback methods
Returns:
Window object
Throws:
BugException - If the XML document is invalid

createWindow

Window createWindow(java.lang.String xml,
                    java.lang.Object callbacks)
Creates a Window from an XML document. The XML document will be loaded relative to the given callback object.

Parameters:
xml - Name of XML file without the '.xml' at the end
callbacks - Callback object, which must have UIHandler annotation including this xml file
Returns:
Window object
Throws:
BugException - If the XML document is invalid or can't be loaded

createPage

Page createPage(org.w3c.dom.Document d,
                java.lang.Object callbacks)
Deprecated. Use createPage(String, Object) instead

Creates a Page from an XML document.

Parameters:
d - XML document describing the page
callbacks - Object used for callback methods
Returns:
Page object
Throws:
BugException - If the XML document is invalid

createPage

Page createPage(java.lang.String xml,
                java.lang.Object callbacks)
Creates a Page from an XML document.

Parameters:
xml - Name of XML file without the '.xml' at the end
callbacks - Callback object, which must have UIHandler annotation including this xml file
Returns:
Page object
Throws:
BugException - If the XML document is invalid

createDialog

Dialog createDialog(org.w3c.dom.Document d,
                    java.lang.Object callbacks)
Deprecated. Use createDialog(String, Object) instead

Creates a Dialog from an XML document.

The use of dialogs should be avoided as they are modal; while a dialog is shown, users cannot access other windows.

Parameters:
d - XML document describing the dialog
callbacks - Object used for callback methods
Returns:
Dialog object
Throws:
BugException - If the XML document is invalid

createDialog

Dialog createDialog(java.lang.String xml,
                    java.lang.Object callbacks)
Creates a Dialog from an XML document.

The use of dialogs should be avoided as they are modal; while a dialog is shown, users cannot access other windows.

Parameters:
xml - Name of XML file without the '.xml' at the end
callbacks - Callback object, which must have UIHandler annotation including this xml file
Returns:
Dialog object
Throws:
BugException - If the XML document is invalid

showQuestion

int showQuestion(WidgetOwner parent,
                 java.lang.String title,
                 java.lang.String message,
                 int buttons,
                 java.lang.String yesLabel,
                 java.lang.String noLabel,
                 java.lang.String cancelLabel,
                 int defaultButton)
Show a yes/no/cancel confirm dialog.

Parameters:
parent - Parent that dialog will be aligned with
title - Dialog title
message - Message in XML
buttons - Bitfield e.g. BUTTON_YES|BUTTON_CANCEL
yesLabel - Label for Yes button (null = Yes)
noLabel - Label for No button (null = No)
cancelLabel - Label for Cancel button (null = Cancel)
defaultButton - Default button BUTTON_xx constant
Returns:
BUTTON_xx constant

showOptionalQuestion

int showOptionalQuestion(java.lang.String prefID,
                         WidgetOwner parent,
                         java.lang.String title,
                         java.lang.String message,
                         int buttons,
                         java.lang.String yesLabel,
                         java.lang.String noLabel,
                         java.lang.String cancelLabel,
                         int defaultButton)
Shows a dialog with don't-show-this-again feature. If don't-show-this-again has been selected, the function will immediately return with the relevant value. (Cancelling does not enable don't-show, but yes or no do.)

Parameters:
prefID - ID used to disable appearance
parent - Parent that dialog will be aligned with
title - Dialog title
message - Message in XML
buttons - Bitfield e.g. BUTTON_YES|BUTTON_CANCEL
yesLabel - Label for Yes button (null = Yes)
noLabel - Label for No button (null = No)
cancelLabel - Label for Cancel button (null = Cancel)
defaultButton - Default button BUTTON_xx constant
Returns:
Result of user's choice (BUTTON_xx constant)

showUserError

void showUserError(WidgetOwner parent,
                   java.lang.String title,
                   java.lang.String message)
Displays an alert dialog indicating some kind of error, with an OK button

Parameters:
parent - Parent that dialog will be aligned with
title - Dialog title
message - Message in XML

showFileSelect

java.io.File showFileSelect(WidgetOwner parent,
                            java.lang.String title,
                            boolean saveMode,
                            java.io.File folder,
                            java.io.File file,
                            java.lang.String[] extensions,
                            java.lang.String filterName)
Shows a file-select dialog as appropriate for the platform.

Parameters:
parent - Parent that dialog will be aligned with, or null for default
title - Title of dialog
saveMode - True for save, false for load (in save mode, the user will be asked to confirm overwrite if they select a file that exists, and the confirm prompt will change to 'Save' instead of 'Open')
folder - Initial folder or null for none
file - Initial file or null for none (overrides folder)
extensions - Array of supported extensions in the form ".jpg" (not case-sensitive) or null to show all files
filterName - Name describing supported extensions e.g. 'Image files' or null for default
Returns:
Selected file or null if the user cancelled

showFolderSelect

java.io.File showFolderSelect(WidgetOwner parent,
                              java.lang.String title,
                              java.io.File folder)
Shows a folder-select dialog as appropriate for the platform.

Parameters:
parent - Parent that dialog will be aligned with, or null for default
title - Title of dialog
folder - Initial folder or null for none
Returns:
Selected folder or null if the user cancelled

showColourSelect

java.awt.Color showColourSelect(WidgetOwner parent,
                                java.lang.String title,
                                java.awt.Color original)
Shows a colour-select dialog.

Parameters:
parent - Parent that dialog will be aligned with, or null for default
title - Title of dialog
original - Initial colour
Returns:
New colour or null if the user cancelled

registerTool

void registerTool(Tool t)
Registers a new Tool that will be placed on the toolbar.

Parameters:
t - SimpleTool or ComplexTool implementor
Throws:
BugException - If there is any problem registering the tool

unregisterTool

void unregisterTool(Tool t)
Unregisters an existing Tool and removes it from the toolbar.

Parameters:
t - Tool to remove

resizeToolbar

void resizeToolbar()
Tools can call this command to make the system resize the toolbar as appropriate given changed content.


getTheme

Theme getTheme()
Obtains the user's selected theme.

Returns:
Theme

getAvailableThemes

Theme[] getAvailableThemes()
Obtains the list of available themes.

Returns:
List of themes

setTheme

void setTheme(Theme t)
Sets the selected theme (should be called by preferences, which for technical reasons has to be in a different plugin).

Parameters:
t - New theme

refreshTheme

void refreshTheme()
Refreshes the current theme to take account of user style changes (userstyle.css).


getThemeFolder

java.io.File getThemeFolder(boolean system)
Obtains the folder used for themes.

Parameters:
system - If true, returns the system theme folder, otherwise returns the per-user theme folder
Returns:
Theme folder; the user theme folder is guaranteed to exist after this call, but the system theme folder might not

installUserTheme

void installUserTheme(java.io.File newTheme)
                      throws GeneralException
Installs a new theme file into the user's theme folder, checking it for errors.

Parameters:
newTheme - New theme file
Throws:
GeneralException - If there is an error with the theme or with copying

setUIStyle

void setUIStyle(int uiStyle)
Changes the current UI style and remembers it in preferences.

Parameters:
uiStyle - One of the UISTYLE_xx constants

getUIStyle

int getUIStyle()
Returns:
Current UI style

runInThread

void runInThread(java.lang.Runnable r)
Runs a task in the user-interface/event thread.

Parameters:
r - Task to run

isAppActive

boolean isAppActive()
Returns:
True if the application (or one of its windows) is currently active

activate

void activate()
Activates the app. (If the app is minimised to tray, this method must be called to make it visible again.)


showLatest

void showLatest()
Switches to the window with most recent changes (if any window has changes).



Copyright © 2011 Samuel Marshall. All rights reserved.