A bajaux Command that can be invoked by a user to 'do something'.
new (require("bajaux/commands/Command"))(params [, func])
A Command is essentially an asynchronous function with a nicely formatted
display name attached.
Parameters:
Name | Type | Argument | Description | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
String | Object | An Object Literal or the display name for Properties
|
|||||||||||||||||||||||||||||
func |
function |
<optional> |
the function to invoke, if using the two-argument |
Example
new Command("baja.Format compatible display name", function () { alert("I'm a command!"); }); new Command("Format compatible display name", function () { return new Promise(function (resolve, reject) { setTimeout(function () { wobble.foo(); resolve; }, 1000); }); }); new Command({ displayName: "I'll be converted to a Format: %lexicon(baja:january)%", description: "I'll be converted to a Format too: %lexicon(baja:true)%", func: function () { alert("I'm a command!"); } }); new Command({ module: "myModule", // Create a Command that gets its displayName, description lex: "myCommand", // and icon from a module's lexicon. func: function () { alert("I'm a command!"); } });
Requires
- module:lex
- module:jquery
- module:bajaux/events
Members
-
<static> flags
-
Namespace containing numbers for comparing flag bits. C&P'ed directly
from MgrController in workbench module. -
<static> flags.ALL
-
Match all flags.
-
<static> flags.MENU_BAR
-
Makes the command be available in the main menu.
-
<static> flags.TOOL_BAR
-
Makes the command be available in the main toolbar.
Methods
-
getAccelerator()
-
Return the accelerator for the Command or null if
nothing is defined.Returns:
The accelerator or null if nothing is defined.
- Type
- Object
-
getDescriptionFormat()
-
Get the unformatted description of the command.
Returns:
- Type
- String
-
getDisplayNameFormat()
-
Return the format display name of the command.
Returns:
- Type
- String
-
getFlags()
-
Get this command's flags.
Returns:
- Type
- Number
-
getFunction()
-
Return the raw function associated with this command.
Returns:
- Type
- function
-
getIcon()
-
Return the Command's icon.
Returns:
- Type
- String
-
getId()
-
Return a unique numerical id for the Command.
This is id unique to every Command object created.
-
hasFlags(flags)
-
Check to see if this command's flags match any of the bits of the
input flags.Parameters:
Name Type Description flags
Number The flags to check against
Returns:
- Type
- Boolean
-
invoke()
-
Invoke the Command. Triggers a
bajaux:invokecommand
orbajaux:failcommand
event, as appropriate.Arguments can be passed into
invoke()
that will be passed into the
function's Command Handler.Returns:
A promise object that will be resolved (or rejected)
once the Command's function handler has finished invoking.- Type
- Promise
-
isCommand()
-
Always returns true.
-
isEnabled()
-
Gets this command's enabled status.
Returns:
- Type
- Boolean
-
isLoading()
-
Return true if the Command is still loading.
Returns:
true if still loading.
- Type
- Boolean
-
isToggleCommand()
-
Always returns false.
-
jq( [jqDom])
-
If a jQuery DOM argument is specified, this will set the DOM.
If not specified then no DOM will be set.
This method will always return the jQuery DOM associated with this Command.Parameters:
Name Type Argument Description jqDom
jQuery <optional>
If specified, this will set the jQuery DOM.
Returns:
A jQuery DOM object for firing events on.
- Type
- jQuery
-
loading()
-
Return the loading promise for the Command.
The returned promise will be resolved once the Command
has finished loading.Returns:
The promise used for loading a Command.
- Type
- Promise
-
merge(cmd)
-
Attempt to merge this command with another command, and return a new
Command that does both tasks. If the two commands are mutually
incompatible, return a falsy value.Parameters:
Name Type Description cmd
module:bajaux/commands/Command Returns:
Example
Here is an example to show the basic concept. Commands that simply add two numbers together can easily be merged together thanks to the associative property.
var AddCommand = function AddCommand(inc) { this.$inc = inc; Command.call(this, { displayName: 'Add ' + inc + ' to the given number', func: function (num) { return num + inc; } }); }; AddCommand.prototype = Object.create(Command.prototype); AddCommand.prototype.merge = function (cmd) { if (cmd instanceof AddCommand) { return new AddCommand(this.$inc + cmd.$inc); } }; var addOneCommand = new AddCommand(1), addFiveCommand = new AddCommand(5), addSixCommand = addOneCommand.merge(addFiveCommand); addSixCommand.invoke(10) .then(function (result) { console.log('is 16? ', result === 16); });
-
off( [event] [, handler])
-
Unregister a function callback handler for the specified event.
Parameters:
Name Type Argument Description event
String <optional>
The name of the event to unregister.
If name isn't specified, all events for the Command will be unregistered.handler
function <optional>
The function to unregister. If
not specified, all handlers for the event will be unregistered. -
on(event, handler)
-
Register a function callback handler for the specified event.
Parameters:
Name Type Description event
String The event id to register the function for.
handler
function The event handler to be called when the event is fired.
-
setAccelerator(acc)
-
Set the accelerator information for the Command.
Parameters:
Name Type Description acc
Object | String | Number | null | undefined The accelerator keyboard information. This can
be a keyCode number, a character (i.e. 'a') or an Object that contains the accelerator information.
If no accelerator should be used the null/undefined should be specified.Properties
Name Type Argument Description keyCode
String | Number The key code of the accelerator. This can be a character
code number or a character (i.e. 'a').ctrl
Boolean <optional>
true
if the control key needs to be pressed.shift
Boolean <optional>
true
if the shift key needs to be pressed.alt
Boolean <optional>
true
if the alt key needs to be pressed.meta
Boolean <optional>
true
if a meta key needs to be pressed. -
setDescriptionFormat(description)
-
Set the description format of the command. Triggers a
bajaux:changecommand
event.Parameters:
Name Type Description description
String the command description - supports baja Format
syntax -
setDisplayNameFormat(displayName)
-
Set the display name format of the command. Triggers a
bajaux:changecommand
event.Parameters:
Name Type Description displayName
String display name - supports baja Format syntax
-
setEnabled(enabled)
-
Sets this command's enabled status. Triggers a
bajaux:changecommand
event.Parameters:
Name Type Description enabled
Boolean -
setFlags(flags)
-
Set this command's flags.
Parameters:
Name Type Description flags
Number -
setFunction(func)
-
Set the Command's function handler.
Parameters:
Name Type Description func
function The new function handler for the command.
-
setIcon(icon)
-
Sets the icon for this Command. Triggers a
bajaux:changecommand
event.Parameters:
Name Type Description icon
String The Command's icon.
-
toDescription()
-
Access the Command's description.
In order to access the description, a promise will be returned
that will be resolved once the command has been loaded and
the description has been found.Returns:
Promise to be resolved with the description
- Type
- Promise
-
toDisplayName()
-
Access the Command's display name.
In order to access the display name, a promise will be returned
that will be resolved once the command has been loaded and
the display name has been found.Returns:
Promise to be resolved with the display name
- Type
- Promise
-
trigger(name)
-
Triggers an event from this Command.
Parameters:
Name Type Description name
String -
visit(func)
-
Visit this Command with the specified function.
Parameters:
Name Type Description func
function Will be invoked with this
Command passed in as an argument.