nsIControllers

Represents a list of nsIController elements.
Inherits from: nsISupports Last changed in Gecko 1.9 (Firefox 3)

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

void appendController(in nsIController controller);
nsIController getControllerAt(in unsigned long index);
nsIController getControllerById(in unsigned long controllerID);
unsigned long getControllerCount();
nsIController getControllerForCommand(in string command);
unsigned long getControllerId(in nsIController controller);
void insertControllerAt(in unsigned long index, in nsIController controller);
void removeController(in nsIController controller);
nsIController removeControllerAt(in unsigned long index);

Attributes

Attribute Type Description
commandDispatcher nsIDOMXULCommandDispatcher Obsolete since Gecko 1.9

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