A CommandGroup is a container for Commands and other CommandGroups.
new (require("bajaux/commands/CommandGroup"))(params)
Maintains a group of Commands. Can also contain sub-CommandGroups.
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | parameters - or just pass the Properties
|
Requires
Methods
-
add(command)
-
Add a command to this group. Triggers a
bajaux:changecommandgroup
event. Multiple arguments can be specified to
add many commands at once.Parameters:
Name Type Description command
module:bajaux/commands/Command The command to add.
Returns:
Return the CommandGroup instance.
-
doSort(kids)
-
Does the work of sorting this command group. By default, does nothing.
When overriding this method, be sure to return the sorted array as a
parameter todeferred.resolve
.Parameters:
Name Type Description kids
Array An array of the command group's children - this may
include commands or sub-CommandGroups.Returns:
an array containing the sorted children, or
a promise to be resolved with same- Type
- Array | Promise
-
filter(options)
-
Filters the commands in this command group based on the results of
a test function, and returns a new, filtered CommandGroup instance.Parameters:
Name Type Description options
Object An options object literal
Properties
Name Type Argument Description include
function <optional>
A function that will receive a
command object and return true or false depending on whether to include
that command in the filtered results. If omitted, defaults to always
return true.flags
Number <optional>
A number containing flag bits to test on
each command. If omitted, defaults to Command.flags.ALL.Returns:
A filtered command group.
-
findCommand()
-
Find a Command in this CommandGroup (or sub CommandGroup) via its id and return it.
Returns:
return the found Command (or null if nothing found).
-
flatten(options)
-
Return a listing of the commands (not command groups) contained within
this group. Can optionally recursively visit down through any
sub-CommandGroups contained in this group (depth first) to return all
commands. Can optionally filter commands by flags as well.Parameters:
Name Type Description options
Object An options object.
Properties
Name Type Argument Description flags
Number <optional>
flags Used to filter commands. If omitted,
defaults toCommand.flags.ALL
.recurse
Boolean <optional>
true
if should recurse down through any
sub-groups.Returns:
An array of Commands.
- Type
- Array
Example
cmdGroup.flatten(); cmdGroup.flatten(Command.flags.MENU); cmdGroup.flatten({ flags: Command.flags.MENU, recurse: true });
-
get(index)
-
Return a Command/CommandGroup based upon the index or
null if nothing can be found.Parameters:
Name Type Description index
Number Returns:
-
getChildren()
-
Returns a defensive copy of this group's array of children.
Returns:
- Type
- Array
-
getDisplayNameFormat()
-
Return the format display name of this command group.
Returns:
- Type
- String
-
getFlags()
-
Returns this group's flags.
Returns:
- Type
- Number
-
hasFlags(flags)
-
Check to see if this group's flags match any of the bits of the
input flags.Parameters:
Name Type Description flags
Number The flags to check against
-
isCommand()
-
Always returns false.
-
isEmpty()
-
Return true if this CommandGroup doesn't contain any children.
Returns:
true if empty.
-
isLoading()
-
Returns:
true if any of the Commands are 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 CommandGroup.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 promise that will be resolved once all the Commands in this
group have been loaded.Returns:
A promise that will be resolved once all of the
child Commands have loaded.- Type
- Promise
-
merge(group [, params])
-
Merges an input command group with this one, and returns a new
command group with the merged results.Parameters:
Name Type Argument Description group
module:bajaux/commands/CommandGroup The group to merge with
this oneparams
object <optional>
Properties
Name Type Argument Default Description mergeCommands
boolean <optional>
true set to false to cause commands
to be merged by a simple instanceof check, and all child commands of this
group will be included; otherwise, only commands whosemerge()
function
returns a new Command will be includedReturns:
the merged group, or
null if the merge could not be completed- Type
- module:bajaux/commands/CommandGroup | null
-
remove(command)
-
Remove a command from this group. Triggers a
bajaux:changecommandgroup
event. Multiple arguments
can be specified so multiple commands can be removed at once.Parameters:
Name Type Description command
module:bajaux/commands/Command | Number The command or index
of the Command to remove.Returns:
Return the CommandGroup instance.
-
removeAll(options)
-
Remove all children of this command group that match the input flag,
optionally emptying out child groups as well. Triggers abajaux:changecommandgroup
event.Parameters:
Name Type Description options
Object An options object
Properties
Name Type Argument Description flags
Number <optional>
Flags to use to filter commands. Only
children that match one of these flags will be removed.
If omitted, defaults toCommand.flags.ALL
meaning all
children will be removed.recurse
Boolean <optional>
true
if should also empty out any
sub-groups.Example
cmdGroup.removeAll(); cmdGroup.removeAll(Command.flags.MENU_BAR); cmdGroup.removeAll({ flags: Command.flags.MENU_BAR, recurse: true });
-
setChildren(children)
-
Sets this group's array of commands/groups wholesale. Triggers a
bajaux:changecommandgroup
event.Parameters:
Name Type Description children
Array -
setDisplayNameFormat(displayName)
-
Set the display name format of the command group. Triggers a
bajaux:changecommandgroup
event.Parameters:
Name Type Description displayName
String display name - supports baja Format syntax
-
setFlags(flags)
-
Sets this group's flags. Triggers a
bajaux:changecommandgroup
event.Parameters:
Name Type Description flags
Number -
size()
-
Return the number of children the CommandGroup has
(this covers both Commands and CommandGroups).Returns:
- Type
- Number
-
sort()
-
Sorts this command group. Typically will not be overridden; override
doSort
instead. Triggers abajaux:changecommandgroup
event.Returns:
A promise that will be invoked once the CommandGroup
has been sorted.- Type
- Promise
-
toDisplayName()
-
Formats the command's display name.
Returns:
Promise to be resolved with the display name
- Type
- Promise
-
trigger(name)
-
Triggers an event from this CommandGroup.
Parameters:
Name Type Description name
String -
visit(func)
-
Visit through all of the Commands and CommandGroups.
The function passed it will be called for every Command and CommandGroup
found (including this CommandGroup).Parameters:
Name Type Description func
Called for every CommandGroup and Command found. Each
Command/CommandGroup is passed in as the first argument to the function.
If the function returns a false value then iteration stops.