Module: bajaux/commands/CommandGroup

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 displayName directly

Properties
Name Type Argument Description
displayName String

A format display name that will be used
when toDisplayName is called.

commands Array.<(module:bajaux/commands/CommandGroup|module:bajaux/commands/Command)> <optional>

specify
the initial set of children of this command group

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.

Type
module:bajaux/commands/CommandGroup

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 to deferred.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.

Type
module:bajaux/commands/CommandGroup

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).

Type
module:bajaux/commands/Command

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 to Command.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:
Type
module:bajaux/commands/Command | module:bajaux/commands/CommandGroup

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 one

params 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 whose merge() function
returns a new Command will be included

Returns:

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.

Type
module:bajaux/commands/CommandGroup

removeAll(options)

Remove all children of this command group that match the input flag,
optionally emptying out child groups as well. Triggers a
bajaux: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 to Command.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 a bajaux: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.