PART FOUR - A DCAL FOR DELPHI PRIMER - _DoMenu FUNCTIONS
Posted: Sun Sep 17, 2017 3:38 pm
PART FOUR - A DCAL FOR DELPHI PRIMER - _DoMenu FUNCTIONS
This posting covers the 'Big Kahoona' for operating D4D macros. Structuring and managing the menu loop function is both the most important and complex coding required in creating a macro. In this post we will examine the structure of a <name>_doMenu function in detail to understand how the data from these pointers direct the focus of the macro during its execution. This is a big subject and so the full discussion in this post is divided into several sections included as separate replies.
Overview
As discussed in previous postings, all Datacad macros operate as a loop, but PART TWO described that D4D macros can end up calling D4D in different drawing files, using different data and at different points in execution. That is why the p_LR & p_DR arguments are used to pass all relevant information in each loop iteration. The opportunity for a user to change drawings and require different argument values to be passed to the macro occurs every time keyboard and mouse control passes back to Datacad. The DCAL & D4D programming environment provides many procedures and function for working within a Datacad drawing. All available methods are listed in the 'uinterfaces.pas' file. For our purposes here they can be divided into two categories, operational and interfaces. Operational methods perform calculations or interrogate the drawing file. Interface methods require user input and can be identified in the 'uinterfaces.pas' file by their use of an argument of the type 'wanttype'. Any function or procedure that contains a 'wanttype' argument can potentially lead to a change in drawing file requiring different argument values passed to the macro. There are quite a few of these interface methods including the most common ones such as getesc() and getPoint(). To work correctly your macro should end execution at the point of any of these user input interface methods.
In the PART ONE posting we discussed the original DCAL doMenu function as the following:
The 'Repeat' loop continues until the user selects an menu option to exit the macro (usually a 'S0' function key). The difference with D4D macros is that the macro releases control during the current loop when a Datacad user interface function call is made. All data and status information is passed back to Datacad by arguments Act, p_LRr, & p_DR to be, in turn, handed back at the next call to the macro in the current drawing. At this point the macro does not retain any previous iteration information such as whether it must perform display and input steps or execute an action next. In order to correctly pick up where we left off we must add code to route focus in the <name>_doMenu to the correct location. To start this process the D4D <name>_doMenu function looks like:
First notice that although DCAL and D4D structures initially appear to be different, both menu structures inlcude the same steps. In this discussions, for simplicity, the D4D menu is divided into a STARTUP and EXECUTE SECTION. In practice, this division is not a strict requirement, and is not always strictly followed in sample macros provided by Datacad, but is described as such here to assist users in understanding what is happening in the menu flow. Each step is discussed in more detail below with code snippets for each section. Full template versions of the complete menu procedure are provided in the PART FIVE postings. Additional reply posts in this Post will discuss how to code the menu in parts including:
1. Declaring Variables
2. Defining the START SECTION
3. Defining the EXECUTE SECTION
4. Understanding DataRecord Flow
This posting covers the 'Big Kahoona' for operating D4D macros. Structuring and managing the menu loop function is both the most important and complex coding required in creating a macro. In this post we will examine the structure of a <name>_doMenu function in detail to understand how the data from these pointers direct the focus of the macro during its execution. This is a big subject and so the full discussion in this post is divided into several sections included as separate replies.
Overview
As discussed in previous postings, all Datacad macros operate as a loop, but PART TWO described that D4D macros can end up calling D4D in different drawing files, using different data and at different points in execution. That is why the p_LR & p_DR arguments are used to pass all relevant information in each loop iteration. The opportunity for a user to change drawings and require different argument values to be passed to the macro occurs every time keyboard and mouse control passes back to Datacad. The DCAL & D4D programming environment provides many procedures and function for working within a Datacad drawing. All available methods are listed in the 'uinterfaces.pas' file. For our purposes here they can be divided into two categories, operational and interfaces. Operational methods perform calculations or interrogate the drawing file. Interface methods require user input and can be identified in the 'uinterfaces.pas' file by their use of an argument of the type 'wanttype'. Any function or procedure that contains a 'wanttype' argument can potentially lead to a change in drawing file requiring different argument values passed to the macro. There are quite a few of these interface methods including the most common ones such as getesc() and getPoint(). To work correctly your macro should end execution at the point of any of these user input interface methods.
In the PART ONE posting we discussed the original DCAL doMenu function as the following:
Code: Select all
procedure Dcal_MenuLoop;
var
//declare any variables
begin
//initialize variables
repeat //menu loop
//display section - display the menu
//input section - get the user's selection
//execute section - act upon selection made
until done;
//finalize loose ends before exit
end;
The 'Repeat' loop continues until the user selects an menu option to exit the macro (usually a 'S0' function key). The difference with D4D macros is that the macro releases control during the current loop when a Datacad user interface function call is made. All data and status information is passed back to Datacad by arguments Act, p_LRr, & p_DR to be, in turn, handed back at the next call to the macro in the current drawing. At this point the macro does not retain any previous iteration information such as whether it must perform display and input steps or execute an action next. In order to correctly pick up where we left off we must add code to route focus in the <name>_doMenu to the correct location. To start this process the D4D <name>_doMenu function looks like:
Code: Select all
function <name>_doMenu (act : action; P_LR, P_DR : Pointer) : wantType;
var //declare required and optional variables
begin
//START SECTION
//SIZING STEP - Datacad inquiry for memory allocation
//INITIALIZE STEP - startup activities
//ROUTER STEP - Determine route based upon input
//SPECIAL EXIT STEP - interrupted macro activities
//EXECUTE SECTION
//DISPLAY STEP - display the menu
//INPUT STEP - Get user input
//EXECUTE STEP - Act upon user input
end;
First notice that although DCAL and D4D structures initially appear to be different, both menu structures inlcude the same steps. In this discussions, for simplicity, the D4D menu is divided into a STARTUP and EXECUTE SECTION. In practice, this division is not a strict requirement, and is not always strictly followed in sample macros provided by Datacad, but is described as such here to assist users in understanding what is happening in the menu flow. Each step is discussed in more detail below with code snippets for each section. Full template versions of the complete menu procedure are provided in the PART FIVE postings. Additional reply posts in this Post will discuss how to code the menu in parts including:
1. Declaring Variables
2. Defining the START SECTION
3. Defining the EXECUTE SECTION
4. Understanding DataRecord Flow