TCPmaker : Visual Tour    Making a New Project Based on an Existing One  

Page 1


As we mentioned in our previous tutorial, there are times when you will want to make a copy of your project files to a new directory, and re-generate code there.

There are lots of reasons why you might want to do that, but the most compelling reason is that you want to leave the original project completely intact, so there is no possibility of it getting changed.  That way, you are sure that you can go back to something that you know is still working, if your new approach doesn't work out.

In this tutorial, we'll make a copy of the project we worked on in the previous tutorial, in which we added several variables and controls to our layout, regenerated code, and then used Beyond Compare 3 to copy our "real I/O" code to the newly regenerated files.

We'll use more powerful directory comparison and multi-file copy capabilities of Beyond Compare 3 (or BC3 for short) to speed up the process of "cloning" our existing project.





Page 2


Here's what we want to do this time:

  1. First, we want to review the appearance of our existing project, to see what particular visual elements we need to change.
  2. Next, we will copy just the project files to a clean new directory.
  3. We will then load the copy of the project into TCPmaker Pro, and turn it into a multi-page project that has a Master Template.
  4. In the process of doing that, we will make a few modifications to the appearance.
  5. We'll generate C18 code for the new project.
  6. Then we'll use Beyond Compare 3 to copy the "real I/O" code from our old project to the new one, to get at least part of the new project working very quickly.

 





Page 3


Reviewing the appearance of our existing TCPmaker layout is really easy.

All we have to do is run Windows Explorer or My Computer, and find our top level project directory. In our case, it is C:\Trace\TCPmakerPro\Projects\Partial\ .

In that directory, we just need to double click on file index.htm (pointed at by the big red arrow) to view our layout in Internet Explorer.

  Click on the image for page view.




Page 4


Looking critically at our existing layout (shown below), we see one thing we want to change right away: we want to get rid of the word "Masters" (in small rotated text: see arrow) in the title.  We might change it to some other word, such as "Template", or delete it entirely, along with its "reflection."

That's the most critical change.  We might consider changing background colors as well. 

  Click on the image for page view.




Page 5


Having reviewed our layout and deciding what to change, we close Internet Explorer, create a new empty directory, called C:\Trace\TCPmakerPro\Projects\Multi\.

Then, we select all the files in the top level project directory only (arrow 1), and hold down the right mouse button as we drag them over to our new project directory Multi\ (arrow 2).

 

  Click on the image for page view.




Page 6


As we release the right mouse button on the destination directory, a popup menu will ask if we want to move these files or copy them.  We click the menu item "Copy Here", and we see (below) that our files have been copied.

 

  Click on the image for page view.




Page 7


Next, we run TCPmaker Pro, and we click the menu item File | Open Project...

 

  Click on the image for page view.




Page 8


When the file Open dialog appears, we navigate to our new project directory Multi, and open the TCPmaker project file located there.  In our case, it is still called Partial.tpr.

Then we click the Open button.

  Click on the image for page view.




Page 9


This will load the project file, and advance to the "Select compilers" page of the TCPmaker wizard.

Before we go any further, we want to change the project name and comment, so we click the Back button

  Click on the image for page view.




Page 10


On the Project Information page, we first change a few items (see red arrows 1 and 2).

Then, we use menu item File | Save As... to re-name our project file to Multi.tpr.

When we have renamed our project file, click the Next button to get back to the "Select compilers" page.

  Click on the image for page view.




Page 11


Back at the "Select compilers" page, we check one or more compilers for which we will want to generate code.

C18 is what we want, so we click the "Next" button. We see the program pause, and display a little progress bar, as it copies files to the destination directory tree.

  Click on the image for page view.




Page 12


Then, click the  "Design Your Web Page..." button to enter the Visual Page Designer.

  Click on the image for page view.




Page 13


On the Step 2 page of the Visual Page Designer, we find that we can change the vertical text label from displaying the word "MASTERS" to the word "Template", and it fits!

So, we don't have to delete that vertical text item after all.

  Click on the image for page view.




Page 14


Now we have a much more time-consuming task: we want to move all the labels and background elements to the Master Template.

The first thing we need to do is to tell the Visual Page Designer that our project should now USE a Master Template at all. To do this, we check menu item Edit | Project Uses Master <template>.

 

  Click on the image for page view.




Page 15


Next, we ought to set up the background colors of the Master Template.

Since we want to start out by trying to match the background colors of the regular index page, we first click on the background of the index page to see its background color pickers (arrows 1 and 2).

The color picker on the left (arrow 1) is for the top color of the background color gradient of the page.  The solid color bar just to the left of the color picker shows the actual selected color, and it looks like it is black.

The color picker on the right (arrow 2) is for the bottom color of the background color gradient of the page. This looks like a royal blue color, probably the bottom-most color square on the pure blue colors column on the far right.

After noting those colors, we click on menu item Edit | Edit Master <template>, to edit the Master Template itself.

 

 

  Click on the image for page view.




Page 16


This brings up the Master Template page, which is currently empty of any controls or background elements.  It also has a default set of gray background colors.

Remember from an earlier tutorial how we can tell we are looking at the Master Template:

  1. The Step 2 tab at the top says Page id = "<template>" (arrow 1)
  2. The Go to Page drop down list in the Commands panel is blank (arrow 2)

 

 

 

  Click on the image for page view.




Page 17


We try clicking some color swatches on the two color pickers, and decide to use the two swatches that are pointed at by red arrows 1 and 2 shown below.

When we've made our background color choices, we use the Go to Page drop down list to select the regular index page again (arrow 3).

 

  Click on the image for page view.




Page 18


This next part, the actual process of moving controls and background elements to the Master Template, is somewhat tedious in the current version of TCPmaker Pro, because we can only select one item at a time.

First we'll select an easy one to demonstrate the basic process.

We click on the lower right corner of the Al background element that is behind our buttons, LEDs, Plotter control, etc, to select this background element.  We see that it is selected because of the small white arrow pointing to its upper left corner, and the property page says we have selected an Alpha Box or Al item.

Then, we right click on this same element to bring up a popup menu, and click menu item Move selected item to page...

  Click on the image for page view.




Page 19


To move the item, we select <template> from the drop down list on the dialog that comes up (arrow 1), and the close the dialog box (arrow 2).

It is not sufficient to just use the page name that is already showing in this combo box: you have to actually drop down the list and select the page you want from the drop down list, or the control will not actually be moved to the new page.

 

  Click on the image for page view.




Page 20


To get a visual indication that this item has moved, try un-checking the box "This Page Uses <template> Elements" on the Commands group panel (arrow 1).

  • When you un-check this box, the element you just moved should disappear.
  • When you check the box again, you should see the item reappear.

If the appearance doesn't change when you un-check and check this box, then you didn't successfully move the item to the Master Template, so go back and try again. (Remember that you must actually drop down the list on the dialog box and select your new destination page, or the item will not actually be moved.)

As you continue to move other items to the Master Template page, it will be helpful to un-check both of the checkboxes pointed to by arrow 1.  That way, the item will seem to disappear as soon as you move it to the Master Template, and you will know right away if you successfully moved the item or not.

Before we move any more items, be sure to read the next page of this tutorial.

 

  Click on the image for page view.




Page 21


What we just did, grabbing any one of our background elements without thinking about it, could get us into a little trouble later on, because Z-Order is really important for background elements. 

What we should do first is to get a record of the Z-Order of the controls and background elements, so we can make sure that when we move them to the Master Template, we can get them into the right Z-Order again.

What we just did, by arbitrarily selecting one element and moving it to the Master Template before any other elements, was to place this element behind any other elements that we move to the Master Template.  This could have an undesirable effect on the appearance of our layout.

Fortunately, it's very easy to get a record of the Z-Order of all the controls and background elements on our index page, before we make any further changes.  We just print out an Item List Report: click menu item Reports | Item List, and print the report when it comes up.

The items are listed in Z-Order, with the items farthest in the background (i.e., drawn first) at the top of the list, and the item in the foreground (i.e., drawn last, on top of everything else) is the last item of the list.

Here is the list of controls as it appears right now in our project, copied from the Item List Report at this stage of our work:

**************************************************
         Master Page Template
         ====================

  Name=Master Class=Pg Id=<template>
    Control: name=Al1 Class=Al Id=al1
**************************************************

 

  Page: name=Index Class=Pg Id=index
    Control: name=Gb1 Class=Gb Id=gb1
    Control: name=Ac1 Class=Ac Id=ac1
    Control: name=Tx1 Class=Tx Id=tx1
    Control: name=Tx2 Class=Tx Id=tx2
    Control: name=Tx3 Class=Tx Id=tx3
    Control: name=Pl1 Class=Pl Id=pl1
    Control: name=Pb1 Class=Pb Id=pb1
    Control: name=Pb2 Class=Pb Id=pb2
    Control: name=Pb3 Class=Pb Id=pb3
    Control: name=Pb5 Class=Pb Id=pb5
    Control: name=Pb4 Class=Pb Id=pb4
    Control: name=Al2 Class=Al Id=al2
    Control: name=Tx4 Class=Tx Id=tx4
    Control: name=Ld2 Class=Ld Id=ld2
    Control: name=Ld4 Class=Ld Id=ld4
    Control: name=Ld3 Class=Ld Id=ld3
    Control: name=Hg1 Class=Hg Id=hg1
    Control: name=Px1 Class=Px Id=px1
    Control: name=Tx5 Class=Tx Id=tx5
    Control: name=Tx7 Class=Tx Id=tx7
    Control: name=Tx9 Class=Tx Id=tx9
    Control: name=Ld1 Class=Ld Id=ld1

Note that background element named Al1 (Id =al1) has already been copied to the Master Template, but we still see the Z-Order of all the other items on the index page, so we can move things to the Master Template, and fix their Z-Order at the end, using the Z-Order dialog, if necessary.

It probably will be necessary to adjust the Z-Order after we copy all the background elements, because some of them will be behind other elements, and could be hard to select until we move some other elements out of the way first.

 

 





Page 22


At this point, we continue the process of selecting and moving the rest of the background elements to the Master Template.

Follow these steps:

  1. First, print an Item List Report to get a record of the Z-Order of the items we wish to move
  2. Select an element we want to move
  3. Right click on this selected element to bring up a popup menu
  4. Click menu item "Move selected item to page..." to bring up the move item dialog
  5. Explicitly drop down the list of destination pages from the drop down list, to actually move the item
  6. Close the "move item" dialog
  7. Verify that, if the checkbox "This Page Uses <template> Elements" is UN-checked, the item should disappear, indicating that it has been successfully moved.
  8. Repeat steps 2-7 to move other items to the Master Template
  9. Use menu item Edit | Edit Master <template> to view just the Master Template and all items you have moved to it.
  10. When all items have been moved to the Master Template, use the Z-Order button on the Commands group panel to put the items into the correct relative Z-Order in the Master Template.
  11. Use the Go to Page drop down list to select the index page again
  12. Re-check the checkboxes "This Page Uses <template> Color" and "This Page Uses <template> Elements" and verify that the layout looks correct when the Master Template is applied to this page
  13. Apply the Master Template to any other pages in your multi-page layout. 




Page 23


When we're done moving background elements from to the Master Template, our index page now looks like this, with the checkbox "This Page Uses <template> Elements" un-checked:

 

  Click on the image for page view.




Page 24


Here is what our Master Template looks like, by itself.

 

  Click on the image for page view.




Page 25


Here is what our index page looks like with the Master Template applied.  It looks just like the original, but now we have a Master Template that we can apply to additional pages of this project, or to other projects.

Well, almost.

If we add any more pages to our project, we would need to add some navigation buttons, so we can move between the multiple pages. 

It would make the most sense to add these navigation buttons to the Master Template, so they will be present on all pages that use the template.  So, let's edit the Master Template and add two buttons, so we can add a second page.

  Click on the image for page view.




Page 26


Here is what our two new navigation buttons look like on the Master Template. The red arrow points to the properties we have chosen for the Home button

  Click on the image for page view.




Page 27


Now that we have our new Master Template, complete with a couple of navigation buttons, we'll click the Add Page button and add a couple of controls to our new pg1 page.

We added an extra Numeric Variable called Slider1, and we have associated it with both the Horizontal Slider control and the new Pl plotter control on this new page. We did this so we can test this page locally in our browser without having to generate code yet.

 

  Click on the image for page view.




Page 28


As usual, we use the buttons on the Step 3 page of the Visual Page Designer to test our layout. We verify that our navigation buttons work, and we see that sliding the slider on the second page traces out a curve.

We close the browser, exit the Visual Page Designer, and generate code for our project, making sure to save our project file as we exit TCPmaker.

 

  Click on the image for page view.




Page 29


Now that we have modified the layout for our new project and have generated code for it, let's take a look at the directories again, using Windows Explorer.

Our old project directory was named Partial\ and our new project directory is named Multi\ . You can see that TCPmaker created some subdirectories beneath each of these project directories, each of which contains a lot of files.

For both project directories, the subdirectory that we are concerned with is the

  PIC\MCHP_C18\TCPmaker\

subdirectory.  This is where our MPLAB project files reside, and where we find the source code files that TCPmaker has specifically generated for your particular project.

In order to copy "real I/O" code into our new project, we will now use Beyond Compare 3 in a different way: to compare whole directory trees.  As we'll see in the next few screen shots, first we will right click on the TCPmaker directory (arrow 1) in the old Partial project, and on the popup menu that comes up, we will click menu item "Select Left Folder for Compare."

Then, we'll right click on the TCPmaker subdirectory (arrow 2) in the new Multi project, and on the popup menu that comes up, we'll click on menu item Compare to "TCPmaker".  That will bring up Beyond Compare 3 showing a side by side comparison of two whole directory trees.

 

 

  Click on the image for page view.




Page 30


Let's try this. we right click on the TCPmaker directory pointed to by arrow 1, and click the menu item "Select Left Folder for Compare."

 

  Click on the image for page view.




Page 31


Next, we right click on the folder pointed to by arrow 2, and click Compare to "TCPmaker".

  Click on the image for page view.




Page 32


When we click the Compare to "TCPmaker" menu item on the second directory, Beyond compare comes up showing the two directory trees side by side.

You see files on both sides, and some directory icons that you can expand as well.

There is a color scheme for file names that conveys information:

  • A file name shown in black is a file that has already been compared to a corresponding file on the other side, and has been found to be identical.
  • A file name shown in blue is a file that has no corresponding file on the other side.
  • A file name shown in red is a file that has the same name as a corresponding file on the other side, but which has a newer date than the file on the other side (and thus may or may not be different).

Folder icons use a similar color scheme:

  • A folder colored blue contains at least 1 file that is not present on the other side.
  • A folder colored red contains at least 1 file that is newer than the corresponding file on the other side.
  • Sometimes a folder can be colored partly red and partly blue, to indicate that both of the above conditions are met.

You can very quickly copy multiple files from one side to the other by:

  1. Selecting one or more files or even one or more whole folders on one side,
  2. And then clicking the yellow arrow on the tool bar that points to the other side. 

This is a very powerful tool for building up a disk image of the software that you will be deploying to your customers.

You can very quickly compare two corresponding files by simply double clicking the file on one side or the other.  This will compare the two files side by side, as we saw in the previous tutorial, and allow you to quickly copy groups of lines from one side to the other.

Let's do that now: we'll double click on the file mtGen.c on the left side (red arrow).

  Click on the image for page view.




Page 33


When we double click on a file, we see the same sort of side-by-side file comparison that we used in the previous tutorial. 

Arrow 1 shows that it has found a line of "real I/O" code that is present in the older Partial project, but which needs to be copied to the corresponding place in the new Multi project. We can just click on the little yellow arrow in the left gutter (big red arrow 1) to copy one or more lines to the other side, just as we did before.

Notice that we are looking at one page of a multi-page tabbed display: comparing files named mtGen.c.

We can click on the TCPmaker tab (big red arrow 2)...

  Click on the image for page view.




Page 34


..and we see our directory comparison view again.

We can double click on yet another pair of files, mtGen.h ...

  Click on the image for page view.




Page 35


..and we see that a new tab (big red arrow 2) is now open, showing the differences between files named mtGen.h on the two sides.

(The differences between these two mtGen.h files are entirely due to variables and controls that were added to the new project.  No lines need to be copied from the old version to the new one.)

Big red arrow 1 shows that our comparison of the two mtGen.c files is still available for viewing, as is the comparison of the two file directories in the TCPmaker tab.

This ability to view the comparisons between multiple sets of files can be very useful in more complicated projects.

 

  Click on the image for page view.




Page 36


We have covered a lot of more advanced material In this tutorial.

We have shown an example where it makes sense "clone" a project: i.e. to copy an existing project to a clean new directory, so you can make substantial changes to the clone without affecting the original.

We showed how to move parts of a single page layout to a Master Template, so you can re-use that template on multiple pages in the same project, or load the template into a separate project in the future if you like.

In the process of moving items to the Master Template, we pointed out how Z-Order is important with background elements, and showed how to get a record of the original Z-Order so you can get the desired appearance from your new Master Template.

After we finished our layout changes and generated code for the new project, we used Beyond Compare 3's file folder comparison capabilities to view multiple file comparisons at the same time.





Page 37


We find that Beyond Compare is an ideal companion tool for TCPmaker and HIDmaker, and believe it is highly useful for anyone who does software development.  The new version 3 has added a lot of new capabilities, and the ability to compare the contents of many file formats that you just couldn't compare before.

In addition to the uses we have shown you in these tutorials, we find that Beyond Compare is extraordinarily helpful in putting together a distibution image for your software: a set of files and directories on your development PC, that forms the model for the disk image that you will install on your end users' PCs.

Making a distribution image is work that has to be done carefully and correctly: any slipups at this stage can cost you a lot of unnecessary tech support calls, and can give your company and your product a bad name.

Because Beyond Compare combines (in one program) the ability to look at (and compare) multiple files, with the ability to copy them, this tool really helps you get this job done right. You can easily check and make sure that you are putting the right version of every file into that all-important distribution image.

We use Beyond Compare all the time, and we highly recommend it.

 




Text Author: Dr. Bob Miller   Copyright Notice and Author Information