Fan

 

class

fwt::Command

sys::Obj
  fwt::Command

@js

Command packages up the diplay name, icon, execution, and undo support for a user command. You can create a command two ways:

  1. use a closure (or any function) for onInvoke
  2. subclass Command and override invoked

If the command supports undo, then you must create a a subclass and override undo.

Commands are often used to centralize control of multiple widgets. For example if a Command is associated with both a menu item and a toolbar button, then disabling the command will disable both the menu item and toolbar button.

See docLib for details.

Slots

acceleratorSource

Key? accelerator

Accelerator of the command or null.

enabledSource

Bool enabled := true

The enable state of the command automatically controls the enabled state of all the registered widgets.

iconSource

Image? icon

Icon of the command or null. Typically a 16x16.

invokeSource

Void invoke(Event? event)

Invoke the command. If the user event is known then is passed, otherwise it might be null.

invokedSource

virtual protected Void invoked(Event? event)

Subclass hook to handle invoke event.

makeSource

new make(Str name := "", Image? icon := null, |Event|? onInvoke := null)

Construct a command with the specified onInvoke function. If onInvoke is not specified, then the invoke method must be overridden to execute the command.

makeLocaleSource

new makeLocale(Pod pod, Str keyBase, |Event|? onInvoke := null)

Construct a localized command using the specified pod name and keyBase. The command is initialized from the following localized properties:

  • "{keyBase}.name.{plat}": text string for the command
  • "{keyBase}.icon.{plat}": uri for the icon image
  • "{keyBase}.accelerator.{plat}": string representation of Key

The {plat} string comes from Desktop.platform. If the paltform specific key is not found, then we attempt to fallback to a generic key. For example:

back.name=Back
back.accelerator=Alt+Left
back.accelerator.mac=Command+[

On all platforms the command name would be "Back". On Macs the accelerator would be Command+[, and all others it would be Alt+Left. If running on a Mac and an explicit ".mac" property was not specified, then automatically swizzle Ctrl to Command.

modeSource

CommandMode mode := CommandMode.push

The command mode determines who associated widgets are visualized. The CommandMode maps to the ButtonMode and MenuItemMode. The default is push.

nameSource

Str name

Name of the command.

onInvokeSource

@transient
readonly EventListeners onInvoke := EventListeners()

The function to invoke when the command is executed. If empty, then invoke must be overridden.

onInvokeErrorSource

virtual protected Void onInvokeError(Event? event, Err err)

Subclass hook to handle when an exception is raised by invoke. Default implementation raises an error dialog.

redoSource

virtual Void redo()

This method is invoked when the command invoked as a redo. It is not called on the first invocation. Default calls invoke with a null event.

registerSource

Void register(Widget w)

Register a widget with this command. This is done automatically by the widget. You only need to call this method if you are developing a custom widget.

selectedSource

Bool selected := false

If this command is using toggle mode, then set the selected state and update all the registered widgets.

toStrSource

override Str toStr()

Overrides sys::Obj.toStr

Return name.

undoSource

virtual Void undo()

This method is invoked to undo the command. This method is only used if undoable returns true.

undoableSource

virtual Bool undoable()

Return if the command can be undone. Default implementation returns true if the undo method has been overridden.

unregisterSource

Void unregister(Widget w)

Unregister a widget with this command. This is done automatically by the widget. You only need to call this method if you are developing a custom widget.

widgetsSource

Widget[] widgets()

Get the associated widgets with this command. Widgets are automatically associated with their command field is set.

windowSource

Window? window()

Get the window associated with this command. If this command is being used as the action of a dialog, then return the dialog. Otherwise try to map to a window via one of the widgets bound to this command. Return null if no associated window can be found.