nsIControllers

This interface is used to manage instances of the nsIController interface. Windows and text inputs have default controllers that allow commands such as cmd_copy to act on the focused element or window. XUL elements can also have controllers, although they do not have any default controllers.

Implemented by: @mozilla.org/xul/xul-controllers;1. You should not normally need to create an instance, as you normally need to alter the window or element's existing list of controllers. To create an instance, use:

var controllers = Components.classes["@mozilla.org/xul/xul-controllers;1"]
                            .createInstance(Components.interfaces.nsIControllers);

Method overview

Attributes

Methods

appendController()

Adds a controller to the end of the list.

void appendController(
  in nsIController controller
);

Parameters

controller

A controller to be added to the list of controllers.

Exceptions thrown

NS_ERROR_OUT_OF_MEMORY

getControllerAt()

Returns the controller instance at the given position.

nsIController getControllerAt(
  in unsigned long index
);

Parameters

index

The position of the wanted controller.

Return value

The controller at the given position.

Exceptions thrown

NS_ERROR_FAILURE

The given index is out of range.

getControllerById()

Returns a controller given by its order, rather than position, of insertion.

nsIController getControllerById(
  in unsigned long controllerID
);

Parameters

controllerID

The ID (insertion order) of a controller.

Return value

The controller element that was inserted with that ID.

Exceptions thrown

NS_ERROR_FAILURE

The ID is greater than the number of controllers that have been inserted, or the controller has since been removed.

getControllerCount()

Returns the current number of controllers.

unsigned long getControllerCount();

Parameters

None.

Return value

The number of controllers currently in the list of controllers.

getControllerForCommand()

Searches for a controller that supports the given command.

nsIController getControllerForCommand(
  in string command
);

Parameters

command

The name of a command, e.g. cmd_copy

Return value

The first controller in the list that supports the given command.

getControllerId()

Returns the order of insertion of a controller.

unsigned long getControllerId(
  in nsIController controller
);

Parameters

controller

The controller for which you want to retrieve the insertion index.

Return value

The ID in which the controller was inserted.

Exceptions thrown

NS_ERROR_FAILURE

The controller is not in the list of controllers.

insertControllerAt()

Inserts a controller at a specific position in the list of controllers. If the position is out of range, nothing happens.

void insertControllerAt(
  in unsigned long index,
  in nsIController controller
);

Parameters

index

The position within the list where you want the controller to be inserted.

controller

The controller to be inserted into the list.

Exceptions thrown

NS_ERROR_OUT_OF_MEMORY

removeController()

Removes a controller from the list of controllers.

void removeController(
  in nsIController controller
);

Parameters

controller

The controller to be removed from the list.

Exceptions thrown

NS_ERROR_FAILURE

The controller was not in the list of controllers.

removeControllerAt()

Removes a controller from the list of controllers.

nsIController removeControllerAt(
  in unsigned long index
);

Parameters

index

The index of the controller to be removed.

Return value

The controller that was removed.

Exceptions thrown

NS_ERROR_FAILURE

The index was out of range.

See also

• nsIController
• nsICommandController
• XUL Tutorial/Commands