The docCursor() method is used by Document handling. Anytime the system needs to know which record you are focused on so that it can display the Document handling form or even just the Document handling icon on the status bar or the action pane (which becomes highlighted when records are attached), it calls .docCursor() on the active form to retrieve the record. Some forms have lots of records, and .docCursor() is a good place to restrict or enforce which records are used by Document handling within a given form. For example, the Customers form has a number of additional data sources, i.e. DirPartyTable to show the customer's name, LogisticsPostalAddress to show the delivery and invoice addresses, etc. When a user clicks Document handling in standard AX, it literately just uses whatever record contains the field with current focus, which can (quite accidentally) be the DirPartyTable because the cursor happens to be on the customer's name. So if we want the guarantee that any Document handling attached while using the Customers form gets attached to the CustTable record, we override the .docCursor() method and always return CustTable. That's the proper use for the .docCursor() method on a form. The super() call in .docCursor() just fetches the record which contains the record with current focus.
When the user clicks a menu item button, that MenuFunction (a hidden class in the AOT) is called to launch it. When that menu item is attached to a form, the form is created, the element.init() method is called, then the element.run() method, and then the form is available for user interaction. The form's .init() method initializes all data sources, which means the .init() method for each data source is called, and then the .executeQuery() method is called, and so on. Eventually when a record is given focus, the data source .active() is called.
There are some articles that cover this event sequence.
Event Method Sequences in Form Scenarios [AX 2012]
msdn.microsoft.com/.../aa655101.aspx
The original menu item button on the caller form can be tied to a specific data source on that form, or it can be blank (for which AX uses the data source with current focus). When the MenuFunction class is executed, it creates an Args object, into which it stores the calling form as .caller(), the selected/focused data source record as .record(), and even the menu item name and type, etc., and then supplies that Args object to the launched form. The Args object serves as a container of data about the caller to the launched form, allowing the launched form to retrieve them as needed using the element.args(). You can typically use element.args().record() to fetch the record that is being sent between forms.
When the data source .init() method fires, part of standard functionality of AX is to investigate if there is a standard relationship between that data source and the data source of the caller form record. If there is, AX automatically constructs a relationship between them (this is called a dynalink), which provides for an automatically filtering of the child form based on the record of the parent form. These relationships are defined on the Relations node under either the parent or child table in the AOT.
You can see this in the constructed Query quite easily. Override the .init() method, add a QueryBuildDataSource qbds; variable declaration, and after the super() call add a line like qbds = this.queryBuildDataSource(); and then inspect that object after stepping over it with the debugger. You will be able to see the automatically added query ranges that make up the relationship to the caller record.
You can also work with the data source directly, altering the query, removing and adding ranges, sorting, relationships, more data sources, etc.
