Developing Add-ins for Campaign Cartographer 3

Monday, March 11, 2013

Starting Fresh

If you did not know before, I have a set of tutorials on how to get up and running on creating CC3 add-ins. But, they were written for the Visual Studio 2005 Express Editions. Anyone that can do math knows they were done over 8 years ago, and in the computer age that is almost forever.

So, I will be starting to “sort of” redo them. They are individually large and complex, so I will be breaking them up into bite size chunks here on this blog.

Lets Start!

The current version of Visual Studio Express is 2012. Unfortunately, it only works on Windows 8. Because of this limitation, we will be using the Visual Studio Express 2010 versions.

To download VS 2010 C++ Express go to:

http://www.microsoft.com/visualstudio/eng/downloads#d-2010-express

You will also what to download and install the associated windows SDK:

http://www.microsoft.com/en-us/download/details.aspx?id=8279

Next time, we will create a native exe in C++ to prove that we have everything downloaded and working properly.

Saturday, February 4, 2012

Creating C# objects mapped to CC3 objects

When Simon and I discussed how to fully integrate the city creator, code named “Map Invoker”, the idea of it working like a Wizard surfaced.

With a wizard like interface, each layer of objects (Waterways, Roads, Walls, etc.) would each be generated by a different page on the wizard. A “generate” button would draw the objects directly in CC3. If the results were not what the user wanted, the user could press the “generate” button again and the old objects would be removed and the new ones drawn. Once the user liked the output, the “next” button would take the user to the next wizard page.

Now this sounded like a great design to me. But …. I had some technical issues to overcome and some design work to make life a little easier.

The main technical issue was that the built-in dialog system was not made to ever run custom code and call XP functions while the dialog was still visible. This was solved by using C# to write the Dialog code and communicating with CC3 via a simple callback class and a delegate. I will go into this solution in depth in a later post. Right now I want to go over the design work I did to make life easier passing data back and forth between C++ & C#.

Here is the diagram of my classes thus far. They are simple value classes, with no behavior. In a previous experiment, I created a REAL object (data & behavior) but because of the fact that a real class crosses native and managed code, it worked great in a all C++/cli environment, but I could not use it in C#. So I decided to split data and behavior into two separate dlls. The cc3objects.dll, a C# set of value classes and cc3actions.dll, the C++/cli dll that implements the behavior.

diagram

Now, what this does is let me create an entire object, or set of objects that can be directly converted to native CC3 objects. So, I actually build my objects in C# then pass them to my C++/cli XP dll. Plus, once I get done with this project everyone will be able to use these dlls.

Thursday, October 6, 2011

Looking under the hood of the .FCW file format

First a warning – The .FCW file format is BINARY! If you do not feel comfortable playing with bits and bytes, this may not be for you. But if you do enjoy this type of challenge, the .FCW file format is one of the best ways to output to CC3.
Imagine you have a random maze generator and you want to output it to CC3. You could export a script. It would redraw your maze one line at a time.
But there are also some problems with scripts:

You have to run them. This may sound obvious but consider that you have to either know the text command to open and run a script file, or you need to know where in the menu system it is.
Scripts are slow. CC3 will have to take your script and run it line-by-line. Its as if you had set down and typed in the commands directly into CC3.
Scripts are not exactly fragile, but they are not very robust either. And, if your script fails, your users are the ones that are going to get frustrated.

Where as if you exported a .FCW file, simply the action of opening the file is all that is needed. So … if you are still with me, here we go!
One last twist – the .FCW file could be compressed.
The .FCW file format is made up of many different “Blocks” of data. The first 4 bytes of each block (except for the first block) contains the number of bytes that the following block contains. It starts with the FileID block. The FileID block is the only block that is guaranteed to be uncompressed. This 128 byte block contains quite a bit of general info on the file. It identifies what type of file it is to other programs, and the version and sub-version number of the file format is was built with. Last, but not least, it informs the reader that bytes after byte 128 are compressed or not. (To save an uncompressed file, after you have clicked "Save As ...", you will be presented with the save file dialog. If you click on the options button, you will be presented with a small dialog box. Uncheck the "File Compression" option)
For this first blog post on the .FCW file format, I will show you how to read a binary file into a byte array and how to display it, byte-by-byte in a textbox similar to all the binary editors display it. Being able to look inside a binary file will come in very handy in the future. Last but not least I will show you FILEID object.

Code Snippet – How to read an entire file into a byte array
public byte[] ConvertFileToByteArray(string fileName)

{

    byte[] buffer;

    using (var fileStream = new FileStream(fileName, FileMode.Open, FileAccess.Read))

    {

        using (var binaryReader = new BinaryReader(fileStream))

        {

            buffer = binaryReader.ReadBytes((int)new FileInfo(fileName).Length);

            binaryReader.Close();

        }

        fileStream.Close();

    }

    return buffer;

}

Once the file is read into a byte array, I pull the first 128 bytes out of the file byte array, using an extension method to Arrays to create sub-arrays.

Code Snippet – SubArray extension method
public static class Extensions

{

    public static T[] SubArray<T>(this T[] data, int index, int length)

    {

        var result = new T[length];

        Array.Copy(data, index, result, 0, length);

        return result;

    }

}

Then I feed the sub-array to my FILEID object. This object converts the bytes into the fields of the FILEID object. We can then check the Compressed property. If the file is compressed, the rest of the data is meaningless, so if the file is compressed, I set the background color of the textbox to a Rose color.

Code Snippet
using System;

using System.Text;

namespace DisplayBinaryFile

{

    public class FILEID

    {

        #region Fields

        public char[] ProgId = new char[26];

        public char[] VerText = new char[4];

        public char[] VerTextS = new char[14];

        public byte[] DosChars = new byte[3];

        public byte DBVer;

        public bool Compressed;

        public byte[] Filler = new byte[78];

        public byte EndFileID;

        #endregion

        public int Length { get; set; }

        public FILEID(byte[] buffer)

        {

            ProgId = Encoding.ASCII.GetChars(buffer.SubArray(0, 26));

            VerText = Encoding.ASCII.GetChars(buffer.SubArray(26, 4));

            VerTextS = Encoding.ASCII.GetChars(buffer.SubArray(30, 14));

            DosChars = buffer.SubArray(44, 3);

            DBVer = buffer.SubArray(47, 1)[0];

            Compressed = BitConverter.ToBoolean(buffer.SubArray(48, 1), 0);

            Filler = buffer.SubArray(49, 78);

            EndFileID = buffer.SubArray(127, 1)[0];

            Length = 128;

        }

        public byte[] GetBytes()

        {

            var returnValue = new byte[Length];

            Array.Copy(Encoding.ASCII.GetBytes(ProgId), 0, returnValue, 0, 26);

            Array.Copy(Encoding.ASCII.GetBytes(VerText), 0, returnValue, 26, 4);

            Array.Copy(Encoding.ASCII.GetBytes(VerTextS), 0, returnValue, 30, 14);

            Array.Copy(DosChars, 0, returnValue, 44, 3);

            Array.Copy(BitConverter.GetBytes(DBVer), 0, returnValue, 47, 1);

            Array.Copy(BitConverter.GetBytes(Compressed), 0, returnValue, 48, 1);

            Array.Copy(Filler, 0, returnValue, 49, 78);

            Array.Copy(BitConverter.GetBytes(EndFileID), 0, returnValue, 127, 1);

            return returnValue;

        }

    }

}

Here is a link to the entire Visual Studio 2010 project

Sunday, May 1, 2011

A more modern example of Intercom

In the last post, I introduced Intercom with an old example I wrote using VB6. This post will be a much more modern example using C#.

I’ve also included a “Round Trip” example where the command is initiated via CC3. By adding this small macro, you now have a command that draws a diamond on the screen.

Code Snippet
 MACRO DIAMOND  
GP TEMP ^DCenter:  
SENDM 2 TEMP  
ENDM 

What this does is as the user to get a point (GP) and then send it via Intercom to the c# application.

Once it gets to the c# code, it takes the string from CC3 (all data sent from CC3 via Intercom is in strings), splits it on the comma and converts the two substrings into doubles. Then it creates a command string and passes it back to CC3.

Code Snippet
 var strNumbers = System.Text.Encoding.ASCII.GetString(bytMsg).Split(',');  
var x = double.Parse(strNumbers[0]);  
var y = double.Parse(strNumbers[1]);  
  
var strDiamond = "LINE \n" +  
                    (x - 100) + "," + y + " \n" +  
                    x + "," + (y - 100) + " \n" +  
                    (x + 100) + "," + y + " \n" +  
                    x + "," + (y + 100) + " \n" +  
                    (x - 100) + "," + y + " \n\n" +  
                    "ENDM";  
  
icSendMsg(20, strDiamond); 

Here is a link to the C# portion

Monday, April 11, 2011

An introduction to Intercom

Intercom was originally written in C code for inclusion in C programs. For C programmers this was quite acceptable. Unfortunately the vast majority of non-professional programmers do not work in C, so something needed to be done.

I've taken the original C code and placed it into a plain C DLL. Most higher level languages like C#, VB.Net, VB6 and Delphi can utilize the subroutines in a C DLL. When I originally wrote about Intercom (way back in 1999 – You can tell, because the title of the example application reads: “Intercom with CC2), I was a professional Visual Basic programmer I used VB6 as my language of choice in the following example.

First, what is intercom? Intercom is code that creates a memory-mapped file that both CC3 and your program can use. What this means is that in memory a chuck of space is set aside, half for you and half for CC3. You can only read your half and you can only write to CC3's half. CC3 on the other hand can do just the opposite.

Whenever a new message is written, a 'New mail flag' is raised. CC3 looks for a raised flag automatically. Your program needs to check periodically.

Second, what is it that is sent back and forth between CC3 and a program? Intercom sends an integer and a string back and forth. To CC3 these have very strict meanings. The integer is part of the name of the macro it will now run and the string is used as input data.

If you sent CC3 via intercom the number 123 then the macro CC3 will attempt to run in named RCV123 and the string will now reside inside the variable RCVDATA.

CC3 ships with an important macro: RCV20. If you run the exe in the VBIntercom zip file (Intercom.exe) and enter 20 and LINE 0,0 1000,1000 you will see.

See? The macro RCV20 contains nothing but RCVDATA in it. This macro will run whatever text is sent to it, so this means that the calling program can dynamically build and run scripts/control CC3.

To connect to the DDL, you need to use Declare Statements. See the code in the VB6 form for the exact syntax, later l will post C# examples.

Here is a link to the original C code for Intercom.

Here is a link to the Intercom code wrapped into a plain C DLL plus the old VB6 example.

Thursday, December 9, 2010

Creating a Path element without adding it to the Drawing List

Wow, its been a while since I’ve written a post here. The holidays are always a busy family blur. Well, here is the latest installment …

The path/poly element is the most used element in CC3. You really cannot get much done with it. Try building anything in CC3 without it (Sure you can just use more primitive elements and use multipoly & group for joining and filling, but really you are just re-creating the path/poly element). So if you want to get something done in an XP, odds are you are going to be working with paths/polys.

If you have been following this blog or the cc2-dev-list on groups.yahoo.com, you have seen code that creates path. The code always creates a empty drawing list element then works on this record entity to “change” it into a path/poly. I’ve always had a bit of a bad feeling about that. It seems that it would be more “correct” to only add completed elements to the drawing list. So, after quite a bit of frustration, I’ve successfully worked out the code to create a path/poly element independent of the drawing list.

The code below creates a closed path (poly) with with four points:

Code Snippet – Build a PATH2 Element
 PATH2 *pathPtr = (PATH2*)malloc(sizeof(PATH2));  
  
pathPtr->CStuff.ERLen = sizeof(PATH2);    // entity record length  
pathPtr->CStuff.EType = ET_PATH2;         // entity type code  
pathPtr->CStuff.EFlags = 0;               // erase/select bits  
pathPtr->CStuff.EFlags2 = 0;              // extra flags  
pathPtr->CStuff.EColor = 1;               // entity color  
pathPtr->CStuff.EColor2 = 1;              // fill (2nd) color  
pathPtr->CStuff.EThick = 0;               // pen thickness 0..25.4 mm  
pathPtr->CStuff.WPlane = 0;               // workplane (0 = XY plane)  
pathPtr->CStuff.ELayer = 1;               // layer  
pathPtr->CStuff.ELStyle = 0;              // line style (0=solid)  
pathPtr->CStuff.GroupID = 0;              // group id (0 = not grouped)  
pathPtr->CStuff.EFStyle = 0;              // fill style (0=hollow)  
pathPtr->CStuff.LWidth = 0.0;             // line width  
pathPtr->CStuff.Tag = 0;                  // entity tag id  
pathPtr->Path.SmType = 0;                 //SmType  
pathPtr->Path.SRes = 8;                   //SRes  
pathPtr->Path.SParm = 0.0;                //SParm  
pathPtr->Path.EParm = 0.0;                //EParm  
pathPtr->Path.Count = 0;                  //Count  
pathPtr->Path.Flags = 0;                  //Flags  
pathPtr->Path.unused = 0;                 //unused  
  
GetCStuff((pENTREC)pathPtr);  
  
pathPtr = (PATH2*)realloc(pathPtr, sizeof(PATH2) + sizeof(GPOINT2) * 4);  
  
pathPtr->CStuff.ERLen = sizeof(PATH2) + sizeof(GPOINT2) * 4;  
  
pathPtr->Path.Nodes[0].x = 0.0;            //Nodes[0]  
pathPtr->Path.Nodes[0].y = 0.0;            //Nodes[0]  
pathPtr->Path.Nodes[1].x = 0.0;            //Nodes[1]  
pathPtr->Path.Nodes[1].y = 1000.0;         //Nodes[1]  
pathPtr->Path.Nodes[2].x = 1000.0;         //Nodes[2]  
pathPtr->Path.Nodes[2].y = 1000.0;         //Nodes[2]  
pathPtr->Path.Nodes[3].x = 1000.0;         //Nodes[3]  
pathPtr->Path.Nodes[3].y = 0.0;            //Nodes[3]  
  
pathPtr->Path.Count = 4;  
pathPtr->Path.EParm = 4.0;  
pathPtr->Path.Flags = NL_CLS;  
  
pENTREC pEntRec = DLApnd(NULL, (pENTREC)pathPtr);  
  
EDraw(pEntRec);  
  
free(pathPtr); 

Thursday, November 4, 2010

Quick development tip

For those of us that are not super c/c++ gurus, like me, debugging an XP add-on can be quite challenging. Over the years I've tried numerous different ways to see into the inner workings of the code.

I first tried placing lots of InfoBox() calls to report on the code state. This worked to a point, but when I needed to see what way going on in a dynamic cursor, or anywhere that the user needed to interact with CC3, the InfoBox() tended to interfere. Plus building a string, that usually included numbers, just to output it to a message box seemed like a lot of work.
Then I added a bunch of code to write to a text file. This worked great but is was quite a bit of code and if I forgot to remove it, the end users got debug files that the shouldn't have. Plus you still needed to do all that code for creating your output string. And, if you wanted the file readable, you needed to include newlines, tabs etc.

Well, when we are first all taught c/c++ it is via the command line. The command printf/cout is king. We learn to output data to the console window in very simple ways. As we start to develop more and more complex applications, we could, for development purposes, interject tons of these little commands to see exactly what was happening.

Unfortunately, with the development of windowing software we no longer have the console window. Or do we?

If you are developing an XP add-on, (or any windows application for that matter) adding a console window is quite easy. Simply slip into your code two commands: AllocConsole & FreeConsole.

Simply change your code to match the code bellow and start some searious debugging!

Code Snippet - Display Console Window
BOOL WINAPI DllMain (HINSTANCE hDLL, DWORD dwReason, LPVOID lpReserved)
{ 
    switch (dwReason)
    {
        case DLL_PROCESS_ATTACH:
        {
            AllocConsole(); 
            MyXP.ModHdl=hDLL;
            XPRegCmd(&MyXP);
            break;
        }
        case DLL_PROCESS_DETACH:
        {
            FreeConsole();
            XPUnregCmd(&MyXP);
            break;
        }
    }
 
    return TRUE;

Monday, October 25, 2010

Code name: Map Invoker

As Simon mentioned in previous post here, I am working on an application, which I am developing under the code name "Map Invoker". It will generate random towns, from small little hamlets to large walled cities. I've been concentrating on the algorithm side and am truely quite a ways towards a "feature complete" logic set.

So Simon was correct in stating that "He’s gone beyond proof of concept". Soon I will be turning from generation to the interface so that all the parameters that I've included in the algorithms are exposed to the user so that the user can create an incredable range of different towns.

Once the paramter inputs are down and tested, then we will be looking into adding all the "garnish" that makes programs like this come alive. So if you have any ideas, practical or "pie in the sky", I'd love to here them. Either post your idea or email me at: SAUNDERL (at) HOTMAIL (dot) COM.

Tuesday, September 28, 2010

The Spiral Command - In Three Parts (Part #1)

The Spiral Command - In Three Parts (Part #1)
In this post and the next two posts, I will be building a spiral command. In this post we will be dealing with the algorithm. When we are done with this post, we will have a command that draws a spiral that would have 20 loops if it started in the middle, but we also told the algorithm to not draw the innermost 10 loops. We have also hard currently coded the command to draw the spiral with a distance of 10 between each loop.

I will be using the name MYSPIRALM for this temporary command. When finished, this will be the command for the macro version.

Note: There is a naming convention that states if you have both a dialog driven command and a comand that is all command line for macros, the macro version ends with an M.

Hardcoded values:

Distance Between Loops: 10
Number of Inner Loops Not Drawn: 10
Total Number of Loops: 20
Clockwise/Counter Clockwise: Clockwise
Growth Between Loops: None

Our next post will implement RecData's to get the values that we currently are hardcoded. Then, we will finish up with a dialog driven command.

Friday, August 20, 2010MyLine Command (A Complete Example)
We have finally reached the point where we can produce an entire example. In my previous post I explained how, conceptually, this command will work. Now, here is the actual code for the command along with a lot of comments.

I have also copied and commented out the definitions for the relevant elements that we are going to create.

I hope that you fire up Visual Studio and try building this code; if you are impatient though and want to just run it, here

Code Snippet - MySpiralM Command
////////////////////////////////////////////////////////////////////////////
//
//    File Name: MySpiral.cpp
//    Written by: L. Lee Saunders
//    (C)2010 Beer & Pretzel Games
//    All rights reserved
//
////////////////////////////////////////////////////////////////////////////
 
#include <windows.h>
#include <math.h>
 
extern "C"
{
    #include <xp.h>
    #include <Extend/Mysvc.h>
}
 
extern XP MyXP;
 
////////////////////////////////////////////////////////////////////////////
  
void XPCALL DrawSpiral (int Result,int Result2,int Result3); 
GPOINT2 CenterPoint;
 
FORMST(lpszCenterPoint,"Center Point:\0") 
  
RDATA PCenterReq = 
   { sizeof(RDATA), RD_2DC, NULL, RDF_C, (DWORD*)&CenterPoint, 
  (DWORD*)&lpszCenterPoint, RDC_XH, DrawSpiral, NULL, NULL, 0, NULL, 0};
////////////////////////////////////////////////////////////////////////////
  
  
////////////////////////////////////////////////////////////////////////////
void XPCALL MySpiralM (void) 
{ 
    ReqData(&PCenterReq);  //get center point 
} 
////////////////////////////////////////////////////////////////////////////
 
 
////////////////////////////////////////////////////////////////////////////
void XPCALL DrawSpiral (int Result,int Result2,int Result3)
{ 
    if (Result != X_OK) { CmdEnd(); return; }
 
    float Growth = 1;
    float LoopDistance = 10;
 
    int Rotations = 20;
    int InnerLoopsToSkip = 10;
    const char * Direction = "0\0";
 
    pENTREC pEntRec;  //Create a new drawing database entity
    
    float CenterX = CenterPoint.x;
    float CenterY = CenterPoint.y;
 
    int iDirection;
 
    MarkUndo();
 
    // Insert an empty path into the drawing list
    pEntRec=DLApndE(NULL, ET_PATH2, sizeof(PATH2)+sizeof(GPOINT2));
 
    // Get the common stuff
    GetCStuff(pEntRec);
 
    // Set the smoothing to Parabolic Blend (through-point)
    pEntRec->Path.Path.SmType = SM_PB;
 
    // Set the centerpoint of the spiral
    pEntRec->Path.Path.Nodes[0].x = CenterPoint.x;    
    pEntRec->Path.Path.Nodes[0].y = CenterPoint.y;
 
    // How many points to draw per circle
    const double STEPS_PER_ROTATION = 50;
    
    // Amount to add to angle at each step
    double increment = M_PI/STEPS_PER_ROTATION;  // Splitting up 
 
    double theta = 2*M_PI*InnerLoopsToSkip;  // This allows for an open area 
    // inside the spiral
 
    // Determines if the loops rotates clockwise or counter clockwise
    iDirection = strcmp(Direction, "0") == 0 ? 1 : -1;
 
    while(theta < (Rotations * 2) * M_PI) 
    {
        pEntRec=DLResize(pEntRec, pEntRec->Path.CStuff.ERLen + 
          sizeof(GPOINT2));
 
        pEntRec->Path.Path.Nodes[pEntRec->Path.Path.Count].x=(float)
          (CenterX + theta * cos(theta) * (1/(M_PI * 2)) * LoopDistance * 
          iDirection);
        pEntRec->Path.Path.Nodes[pEntRec->Path.Path.Count].y=(float)
          (CenterY + theta * sin(theta) * (1/(M_PI * 2)) * LoopDistance);
        
        pEntRec->Path.Path.EParm=(float)pEntRec->Path.Path.Count;
        pEntRec->Path.Path.Count++;
        
        LoopDistance = LoopDistance * Growth;
        theta = theta + increment; //If theta grows faster then increment, 
        //it will have wider spaces between each loop    
    }
                
    EDraw(pEntRec);  //Draw our line 
    ShowChanges();   //Needed for CC3 to "Show Changes" to the DB 
 
    CmdEnd(); 
    return;
} 
////////////////////////////////////////////////////////////////////////////

Thursday, September 2, 2010

How to walk the "Drawing List"

In trying to decide what element of CC3 XP programming I was going to blog about next, I started to re-read all of the old posts on the cc2-dev-l email list @ groups.yahoo.com.

Wow, I had forgotten how much valuable information was out there. If you have the time (And it will take a bit of time) just start at the beginning and read through the threads. I promise that you will learn something – I did!

I found a request by Linda Kekumu. It seemed that she had a large number of maps that had lots of Notes attached to them and they were wrong. She needed a quick way to clear out all the notes on a map, instead of manually removing them one at a time. Peter responded with this dash of code.

The reason I selected it for this post is that it is probably the smallest piece of code that displays how to use DLScan. Now DLScan does exactly as the name says, it scans the “Drawing List” (i.e. the drawing database) and calls a function for every “identified” element. I say “identified” because there are times when you only want to look at a subset of the entire Drawing List.

In this new XP command, we scan the Drawing List with the DLS_Std flag, telling DLScan that we want to scan the Drawing List for “all standard all non-erased elements”.

Then in our called function (ClearNotesScan) we check the EType of each identified element (pEntRec) . If the EType equals ET_Note, we know it is a Note and we call DLErase to remove the element from the Drawing List.

So, with this, you can now scan through a map and look at every identified element!

Code Snippet – MyClearNotes Command
/////////////////////////////////////////////////////////////////////////////
//
// Program: CC3DeveloperBlog.dll
// File Name: MyClearNotes.cpp
// Written by Peter Olsson (Copied here by L. Lee Saunders)
// (C)2010 Beer &amp; Pretzel Games
// All rights reserved
//
/////////////////////////////////////////////////////////////////////////////


#include <windows.h>
#include <math.h>


extern"C"
{
    #include <xp.h>
    #include <math.h>
}
extern XP MyXP;
///////////////////////////////////////////////////////////////////////////// 




///////////////////////////////////////////////////////////////////////////// 
DWORD XPCALL ClearNotesScan(hDLIST hDList, pENTREC pEntRec, PARM p1, PARM p2)
{
    //If the Entity Record is of type "Note" then erase the Entity from DL
    if(pEntRec->CStuff.EType==ET_NOTE) { DLErase(pEntRec); }
    return 0;
}
/////////////////////////////////////////////////////////////////////////////




/////////////////////////////////////////////////////////////////////////////
void XPCALL MyClearNotes(void)
{
    //Description copied from FCW32.TXT
    //---------------------------------------------------------------
    // ClearSel - Clear All Selection bits
    //---------------------------------------------------------------
    ClearSel();


    //This sets an undo point so that every action after this to the end of 
    //the command will be reversed if the user selects UNDO.
    MarkUndo();


    //Drawing list scan. We are interested in only the first three parameters
    // Param #1: Drawing list - If null, it is the main list
    // Param #2: Our Callback function for every identified element in the DL
    // Param #3: DSFlags. How we identify what DL elements we want 
    DLScan(NULL, ClearNotesScan, DLS_Std, 0, 0);


    //End the command
    CmdEnd();
}
/////////////////////////////////////////////////////////////////////////////

Friday, August 20, 2010

MyLine Command (A Complete Example)

We have finally reached the point where we can produce an entire example. In my previous post I explained how, conceptually, this command will work. Now, here is the actual code for the command along with a lot of comments.

I have also copied and commented out the definitions for the relevant elements that we are going to create.

I hope that you fire up Visual Studio and try building this code; if you are impatient though and want to just run it, here is the dll.

Code Snippet - MyLine Command (A Complete Example)
////////////////////////////////////////////////////////////////////////////
//
//    Written by: L. Lee Saunders
//    Date: 8/15/2010
//    (C)2010 BeerAndPretzelGames.com
//    All rights reserved
//
////////////////////////////////////////////////////////////////////////////
#include <windows.h>
 
extern "C" 
{  
    #include <XP.H>
    #include <Extend/Mysvc.h>
}
 
#define XPID 0xF000
 
void XPCALL About(void);
void XPCALL MYLINE(void);
 
char CList[]="MYLINE\0";
PCMDPROC PList[]={About,MYLINE};
 
XP MyXP = 
   { 0, CList, PList, 0, 0, 0, XPID, 0, 500, 0, 0, 500 };
////////////////////////////////////////////////////////////////////////////
 
 
////////////////////////////////////////////////////////////////////////////
FORMST(MyAPkt,"BLOG DLL commands:\n\n"
       "\tMYLINE - Duplicating the Line Command #s\n\0")
 
void XPCALL About (void)
{
    FormSt(&MyAPkt,RSC(FD_MsgBox));
}
////////////////////////////////////////////////////////////////////////////
 
 
////////////////////////////////////////////////////////////////////////////
void XPCALL MYLINE2 (int Result,int Result2,int Result3);
void XPCALL MYLINE3 (int Result,int Result2,int Result3);
 
//This is the definition of LINE2
//==========================================================================
//typedef struct
//{
//    CSTUFF    CStuff;              // entity properties
//    GLINE2    Line;                // line properties
//} LINE2;
 
//This is the definition of GLINE2
//==========================================================================
//typedef struct
//{
//    GPOINT2 p1;                    // starting point
//    GPOINT2 p2;                    // ending point
//} GLINE2;
 
//This is the definition of GPOINT2
//==========================================================================
//typedef struct 
//{
//    float x;
//    float y;
//} GPOINT2;
 
//This is the definition of CSTUFF
//==========================================================================
//typedef struct
//{
//    int    ERLen;                    // entity record length
//    unsigned char    EType;          // entity type code
//    char    EFlags;                  // erase/select bits
//    char    EFlags2;                 // extra flags
//    unsigned char    EColor;         // entity color
//    unsigned char    EColor2;        // fill (2nd) color
//    char    EThick;                  // pen thickness 0..25.4 mm
//    short    WPlane;                 // workplane (0 = XY plane)
//    short    ELayer;                 // layer
//    short    ELStyle;                // line style (0=solid)
//    short    GroupID;                // group id (0 = not grouped)
//    short    EFStyle;                // fill style (0=hollow)
//    float    LWidth;                 // line width
//    int    Tag;                      // entity tag id
//} CSTUFF;
 
//This is the working structure that we will use to create all the lines
LINE2 BuildL = { 
    sizeof(LINE2),                // entity record length 
    ET_LINE2,                     // entity type code
    0,                            // erase/select bits
    0,                            // extra flags
    1,                            // entity color
    1,                            // fill (2nd) color
    0,                            // pen thickness 0..25.4 mm
    0,                            // workplane (0 = XY plane)
    1,                            // layer
    0,                            // line style (0=solid)
    0,                            // group id (0 = not grouped)
    0,                            // fill style (0=hollow)
    0.0,                          // line width
    0,                            // entity tag id
    0.0,                          // starting point: x
    0.0,                          // starting point: y
    1.0,                          // ending point: x
    1.0                           // ending point: y
};
 
FORMST(lpszFirstPoint,"1st point:\0")
 
FORMST(lpszNextPoint,"Next point:\0")
 
RDATA P1Req =
   { sizeof(RDATA), RD_2DC, NULL, RDF_C, (DWORD*)&BuildL.Line.p1,
    (DWORD*)&lpszFirstPoint, RDC_XH, MYLINE2, NULL, NULL, 0, NULL, 0};
 
RDATA P2Req =
   { sizeof(RDATA), RD_2DC, NULL, RDF_C, (DWORD*)&BuildL.Line.p2,
    (DWORD*)&lpszNextPoint, RDC_RBAND, MYLINE3, NULL, NULL, 0, NULL, 0};
 
////////////////////////////////////////////////////////////////////////////
 
 
////////////////////////////////////////////////////////////////////////////
void XPCALL MYLINE (void)
{
    ReqData(&P1Req);  //get first point
}
////////////////////////////////////////////////////////////////////////////
 
 
////////////////////////////////////////////////////////////////////////////
void XPCALL MYLINE2 (int Result,int Result2,int Result3)
{
    if (Result != X_OK) { CmdEnd(); return; } //If we did not get valid info
    
    MarkUndoAdd();  //Enable Undo
    NewCsrOrg(BuildL.Line.p1.x, BuildL.Line.p1.y);  //Set cursor origin
    ReqData(&P2Req);  //Get next point
}
////////////////////////////////////////////////////////////////////////////
 
 
////////////////////////////////////////////////////////////////////////////
void XPCALL MYLINE3 (int Result,int Result2,int Result3)
{
    pENTREC pEntRec;  //Create a new drawing database entity
 
    if (Result != X_OK) { CmdEnd(); return; } //If we did not get valid info
 
    //This gets all the current stuff like current color and assigns it
    //to our line entity.
    GetCStuff(&BuildL.CStuff); 
 
    //Append a copy of our line to the DB and return a pointer to the new
    //entity in the database.  We assign it to pEntRec.
    pEntRec=DLApnd(NULL,(pENTREC)&BuildL); 
    
    EDraw(pEntRec);  //Draw our line
    ShowChanges(); //Needed for CC3 to "Show Changes" to the DB
 
    BuildL.Line.p1.x=BuildL.Line.p2.x;  //move 2nd x to 1st x 
    BuildL.Line.p1.y=BuildL.Line.p2.y;  //move 2nd y to 1st y 
    
    NewCsrOrg(BuildL.Line.p1.x,BuildL.Line.p1.y);  //Set cursor origin
 
    ReqData(&P2Req);  //Get next point
}
////////////////////////////////////////////////////////////////////////////
 
 
////////////////// DllMain - XP initialization & Unload code ///////////
BOOL WINAPI DllMain (HINSTANCE hDLL, DWORD dwReason, LPVOID lpReserved)
{ 
    switch (dwReason)
    {
        case DLL_PROCESS_ATTACH:
        {
            MyXP.ModHdl=hDLL;
            XPRegCmd(&MyXP);
            break;
        }
        case DLL_PROCESS_DETACH:
        {
            XPUnregCmd(&MyXP);
            break;
        }
    }
    return TRUE;
}
////////////////////////////////////////////////////////////////////////////

Sunday, August 15, 2010

Beads – How to Wait for Input

[Note: This is copied from the "FastCAD XP Programming Reference" that comes with the XP toolkit. I copied this, with editing only for clarity, because it was so descriptive]

Nowhere in the Windows programming environment will you find a greater need to change your thinking than with regard to getting input.

In Windows, our programs receive messages that inform us of discrete user input - a mouse movement, button click, or a keyboard press. Other than dialog boxes, there is no way provided to wait for a complete word or line of text or other aggregate input in your program and then continue. We must write our program so that each keystroke is processed and then control is returned all the way to Windows.

This means that in a piece of code (creating a text entity, for example) we can not have one procedure that calls another to get a line of text and then continues with the next instruction when it is available, as would be done in a DOS or Unix program. The current position within that first command procedure is normally maintained on the stack, perhaps as a nested chain of procedure calls.

In Windows, after every event (such as a single key press), we have to return all the way up the stack back to Windows! This is why most Windows programs do all of their input through dialog boxes.

The FastCAD solution to this problem is to think of a command as a string of "beads" - little pieces of a command that each do one small part of the overall command, each a piece that can be done in response to an appropriate input event.

Lets take as an example a command to create a line entity. In traditional programming, its logic might be:

LineCommand:

prompt the user for the first point
- Get the first point if there was a problem getting it, end the command

prompt the user for the second point
- Get the second point if there was a problem getting it, end the command

Create the line entity

Append it to the drawing database

Draw the line entity

End the command

In FastCAD, we have an API service, ReqData, that handles data requests. We call ReqData with a packet that tells it about the data request, and then we go back to Windows.

When the data becomes available, ReqData will call another procedure specified in our original request packet to continue with our command. This means that we write our command as a series of procedures, linked together by RDATA packets, each one executing when its data becomes available, and returning to Windows when it needs to wait for more input.

The sequence looks like this:
==========================
Event: Action (Bead procedure):
- LINE function entered
- - Request first point by calling ReqData
- Line function ends

User enters the first request for a point:

Event: Action (Bead procedure):
- Second LINE function entered
- - Did the user cancel the request?
- - - End Command
- - Request second point by calling ReqData
- Second Line function ends

User enters the second request for a point:

Event: Action (Bead procedure):
- Third LINE function entered
- - Did the user cancel the request?
- - - End Command
- - Else
- - - Create the line entity
- - - Append it to the drawing database
- - - Draw the line entity
- - - End Command
- Third Line function ends

The LINE command is implemented in 3 beads, each of which is called in response to a single event, such as a mouse click or a RETURN keypress. The ReqData service provides all of the intermediate beads that track mouse movement and build up strings of characters into words like "LINE" for you.

Next post, we will start to implement the LINE command.

Tuesday, August 3, 2010

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
typedef struct
{
    int              ERLen;        // entity record length
    unsigned char    EType;        // entity type code
    char             EFlags;       // erase/select bits
    char             EFlags2;      // extra flags
    char             EColor;       // entity color
    char             EColor2;      // fill (2nd) color
    char             EThick;       // pen thickness 0..25.4 mm
    short            WPlane;       // workplane (0 = XY plane)
    short            ELayer;       // layer
    short            ELStyle;      // line style (0=solid)
    short            GroupID;      // group id (0 = not grouped)
    short            EFStyle;      // fill style (0=hollow)
    float            LWidth;       // line width
    int              Tag;          // entity tag id
} CSTUFF;

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

pENTREC->CStuff.EColor

Sunday, July 25, 2010

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.

Saturday, July 24, 2010

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
void XPCALL GotText(int Result, int Result1, int Result2);
 
FORMST(lpszGetText, "Enter Text:")
 
RDATA rGetText = {sizeof(RDATA), RD_TxWord, NULL, RDF_C, (DWORD *)Text,
(DWORD *)&lpszGetText, RDC_NONE, GotText, NULL, NULL, 0, NULL, 0};
 
void XPCALL GetText(void)
{
    ReqData(&rGetText);
}
 
void XPCALL GotText(int Result, int Result1, int Result2)
{
    if(Result==X_OK)
    {
    }
    else
    {
        CmdEnd();
    }
}

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.