Ok, you requested data, now what did you get?

Ok, so you have messed around with the RDATA function and you want to select an element, like a circle.  So you create a new RDATA function with the fallowing parameters:

• Cursor:  RDC_PICK
• Flags:  RDF_C
• Type:  RD_Pick1

 Now create a data store variable of type pEntRec.

A pEntRec type is a very important type in writing XP's.  The pEntRec type is the generic entity pointer that can point to any type of drawing entity.  So, if you selected a circle with your RDATA call, pEntRec will point to the the circle entry within the "Drawing Database"

The "Drawing Database" is the collection of all the visible elements in the map.  When we select elements, Campaign Cartographer returns a pointer to the selected element in the "Drawing Database".

Once you get a pointer to an entity, you can edit, interrogate or delete it.

Every entity shares some common data - appropriately named: CSTUFF

CStuff is defined as:

Code Snippet - CSTUFF

1. typedef struct
2. {
3.     int              ERLen;        // entity record length
4.     unsigned char    EType;        // entity type code
5.     char             EFlags;       // erase/select bits
6.     char             EFlags2;      // extra flags
7.     char             EColor;       // entity color
8.     char             EColor2;      // fill (2nd) color
9.     char             EThick;       // pen thickness 0..25.4 mm
10.     short            WPlane;       // workplane (0 = XY plane)
11.     short            ELayer;       // layer
12.     short            ELStyle;      // line style (0=solid)
13.     short            GroupID;      // group id (0 = not grouped)
14.     short            EFStyle;      // fill style (0=hollow)
15.     float            LWidth;       // line width
16.     int              Tag;          // entity tag id
17. } CSTUFF;

For example you have a pEntRec named pENTREC and you want to get the entities color:

pENTREC->CStuff.EColor

Requesting data from CC3 - RDATA

Last post I introduced the two most important functions exposed by CC3: RDATA & FORMST.

In this post I'll discuss the internals of RDATA.

Here are the important elements you need to configure for every time you declare an RDATA.

• Name - This is simply the name the holds all the separate RDATA elements together
• Type - This is where you declare what kind of data you are requesting
• Flags - These flags are the switches that tweak the RDATA call to do exactly what you want
• Data Store - Where to "put" what you have requested after it has been selected
• Prompt - This is the text that will be displayed to the user
• FormSt declaration - This is where you decide if you want to include the prompt declaration. If you already have exactly the prompt you want already declared, you can reuse it instead of creating a new one
• Cursor - Obviously selecting a single item you want a different cursor than if you want them to type in some text
• Return Procedure

When I first started to write XP's, Super Guru Peter Olsen sent me a little tool that he wrote to automatically generate the RDATA call. When I was preparing for this post, I asked Peter if he still had the app. Well, he did, but he suggested that I create an online version of the tool. So, here is a Silverlight 4 application that generates an RDATA structure for you.



In my next post, I'll use the tool to generate our RDATA and select our first element. Plus, we will start to discuss what it is exactly, that we get back from our ReqData call.

Part 2 of a Campaign Cartographer 3 XP - Or, the best part for last.

In a previous post, I discussed how an XP is in three distinct parts. This post is about the second part: Where the rubber meets the road.

Because this is the main part of the XP, describing this section in any detail would be like trying to describing how any a website works by describing how HTML works.

But, there are two main functions of every XP. Input and Communicating with the user.

Input: Feeding data from you map into your XP is a major function. If you cannot select elements or locations (points), you cannot have much of an impact on your drawing.

Communication: Having the ability to select something without telling the user what your command is expecting the user to do.

These two functions are accomplished using RDATA (Request Data) and FORMST (Format String). Using these two together, we can prompt the user, with FORMST, that we currently want a type of data (a string, a point, an element etc.) and with RDATA, we are informing CC3 that it needs to let the user collect the data we want.

Here is a simple example that implements an XP command to enter a text word:

Code Snippet: XP dll Part #2

1. void XPCALL GotText(int Result, int Result1, int Result2);
2.  
3. FORMST(lpszGetText, "Enter Text:")
4.  
5. RDATA rGetText = {sizeof(RDATA), RD_TxWord, NULL, RDF_C, (DWORD *)Text,
6. (DWORD *)&lpszGetText, RDC_NONE, GotText, NULL, NULL, 0, NULL, 0};
7.  
8. void XPCALL GetText(void)
9. {
10.     ReqData(&rGetText);
11. }
12.  
13. void XPCALL GotText(int Result, int Result1, int Result2)
14. {
15.     if(Result==X_OK)
16.     {
17.     }
18.     else
19.     {
20.         CmdEnd();
21.     }
22. }

Line 1: This is the prototype for the method that RDATA will call when it has gotten a hold of the data you requested.

Line 3: This is the FORMST declaration. This declaration creates a variable (lpszGetText) and assigns it the text "Enter Text:".  True, we could have created a string with this text, but RDATA is expecting a FORMST variable.  Plus, when we get further into the power of FORMST, you will see that is it not merely a replacement for a char array.

Lines 5 & 6:  This is the RDATA declaration.  When you learn to read it, you will see that it says it is going to go get a "Word" (a string of characters without whitespace), store it in the char array Text (not declared in the code snippet), diplaying no visible cursor, displaying the text in the FORMST as our prompt and calling our method, GotText, when the user is done entering the request.

Line 8 - 11: This is our commands original method.  It would have been declared and prototyped in Part 1 of the XP code.

Line 10:  This is the call that invokes our RDATA.

Line 13 - 22: This is our method that RDATA will call when it has gotten a hold of the data you requested.

Line 15:  This line shows that the Result parameter contains the "Status" of the request we made.  If it is "OK" then we can further process what we got.

Line 20:  CmdEnd() is the XP command that notifies CC3 that our XP function has come to an end.