RecordsNavigationController Class
Represents a ViewController descendant, that contains the PreviousObject and NextObject Actions.
Namespace: DevExpress.ExpressApp.SystemModule
Assembly: DevExpress.ExpressApp.v19.1.dll
Declaration
Remarks
The RecordsNavigationController is intended for presenting the PreviousObject and NextObject Actions.
In a Windows Forms application:
In an ASP.NET application:
This Controller is activated for every View. To determine what object collection to use and how to get required objects from it, when the NextObject and PreviousObject Actions are executed, this Controller uses an OrderProviderSource. This object provides access to the currently assigned OrderProvider. Order Providers implement members of the IOrderProvider interface. They are: GetObjectByIndex and GetOrderedObjects. There are several OrderProviders implemented in XAF. They implement either the IObjectOrderProvider or IKeyOrderProvider interface. Both these interfaces are inherited from the IOrderProvider interface. The difference is that the IObjectOrderProvider interface has the GetIndexByObject method, and the IKeyOrderProvider has the GetIndexByObjectKey method. The following table details the built-in Order Providers:
Order Provider | Iterface Implemeted | Description | When is it used? | |
|---|---|---|---|---|
ListEditorOrderProvider | IObjectOrderProvider | Works with a List View passed to it in its constructor. Uses the corresponding methods of its ControlOrderProvider - the List View’s Editor that implements the IControlOrderProvider interface. The built-in List Editors, the GridListEditor, ASPxGridListEditor, SchedulerListEditorBase and TreeListEditor, implement this interface. If the current List View’s editor does not contain these interface methods, the DefaultOrderProvider‘s corresponding methods are used. This Order Provider is passed to the ListEditorOrderProvider in its constructor. | Used when the RecordsNavigationController is activated for a List View. | |
DefaultOrderProvider | IObjectOrderProvider | Works with any View passed to it in its constructor. If the View is a List View, this Order Provider uses the DataSource of the ListEditor. If the View is a Detail View, it returns null in the GetObjectByIndex and GetOrderedObjects methods, and -1 by the GetIndexByObject method. | Used when the RecordsNavigationController is activated for a List View, but the View’s Editor does not implement the IControlOrderProvider interface. Used when the RecordsNavigationController is activated for a Detail View. | |
NullOrderProvider | IObjectOrderProvider | Returns null (nothing in VB) in the GetObjectByIndex and GetOrderedObjects methods, and -1 by the GetIndexByObject method. | Used by the ListEditorOrderProvider when the passed DefaultOrderProvider is null. | |
StandaloneOrderProvider | IKeyOrderProvider | Works with the ordered list of objects passes to it in its constructor. | Used when the current RecordsNavigationController is deactivated. The previously used Order Provider passes the objects it worked with to this Order Provider. This is required to keep a Detail View’s RecordsNavigationController that uses the OrderProvider of a List View’s RecordsNavigationController working. See the description of this scenario below. |
So by default, when the RecordsNavigationController is activated for a List View, it passes this View to its OrderProvider. The NextObject and PreviousObject Actions can then navigate within the List View’s objects. When the RecordsNavigationController is activated for a standalone Detail View, there is no a collection within which to navigate; so the NextObject and PreviousObject Actions are disabled. There is, however, one more scenario. A Detail View can be invoked in a separate Window from a List View to display the object selected in the List View. This scenario is processed by the RecordsNavigationController in a special manner. So that you can navigate within the List View objects using the NextObject and PreviousObject Actions in the Detail View, the OrderProviderSource used by the List View’s RecordsNavigationController is assigned to the RecordsNavigationController.OrderProviderSource property of the Detail View’s RecordsNavigationController. So, the List View’s collection is actually used for navigation in the Detail View, since the Order Provider works with the List View.
You can inherit from this Controller, or subscribe to its events to modify its behavior. In addition, you can access its NextObject and PreviousObject Actions via the RecordsNavigationController.NextObjectAction and RecordsNavigationController.PreviousObjectAction properties, and modify their behavior.
If you need to inherit from the RecordsNavigationController, take into account that the WebRecordsNavigationController descendant exists in the ASP.NET system module. Therefore, in an ASP.NET application, you should inherit WebRecordsNavigationController instead of RecordsNavigationController. In a WinForms application, you can inherit RecordsNavigationController directly. The following protected virtual methods are available for overriding:
Method | When is it called? | Description |
|---|---|---|
MoveToNext | Invoked as a result of executing the NextObject Action. | Represents the NextObject Action’s SimpleAction.Execute event handler. It gets the current object’s index in the collection, finds the following object and sets it as the current object for the Controller’s current View. |
MoveToPrevious | Invoked as a result of executing the PreviousObject Action. | It represents the Action’s SimpleAction.Execute event handler. It gets the current object’s index in the collection, finds the previous object and sets it as the current object for the Controller’s current View. |
OnViewShowing | Invoked as a result of raising the XafApplication.ViewShowing event. | If the target View is a Detail View that will be displayed in a separate Window, this method creates an OrderProviderInitializer, passing the RecordsNavigationController.OrderProviderSource to it. After the Detail View has been shown, this OrderProviderInitializer will set the OrderProviderSource for the View’s RecordsNavigationController. This is required for the special scenario described above. |
CreateDefaultOrderProvider | Invoked when the RecordsNavigationController is activated. | Returns a newly created DefaultOrderProvider. |
UpdateActionsState | Invoked when the RecordsNavigationController is activated, and when the Controller’s RecordsNavigationController.OrderProviderSource is changed. In addition, it is called when the following events are raised: | Updates the NextObject and PreviousObject Actions’ “active” and “enabled” state. |
Public members are described individually in the documentation.
To ascertain whether the Controller is active, use the Controller.Active property. If you need to know the reason for its deactivation or activation at runtime, use the DiagnosticInfo Action.
Information on the RecordsNavigationController and its PreviousObject and NextObject Actions is available in the Application Model‘s ActionDesign node. To access it, use the Model Editor.