Home Page > Programming Samples and Tutorials > C++ Samples > Patch Tutorial
VC Patch Tutorial
Patch Programming Tutorial
Patch Programming Tutorial demonstrates incorporation of KernelCAD ActiveX
control into a simple dialog-based application using Visual C++ and Microsoft
Visual Studio 6.0. Source code for Patch tutorial is available in
Samples\Tutorials\VC\Patch folder of the installation directory. It is recommended to
copy whole VC directory to location outside of the installation folder
before loading or compilation. Patch is an MFC dialog-based application which
displays a DInsight model consisting of a single patch of surface using KernelCAD ActiveX control and allows to modify geometrical parameters of the
model.
See also: C# Patch Tutorial
Visual Basic .NET Patch Tutorial,
All C++ Samples,
All samples
Running the Application
Patch application loads ArcPatch.glm located in the Models folder of the
installation directory. The
dialog displays parameters, which can be modified to assign any shape valid for a
model with single cross-sectional element (See Elements).
To be able to compare behavior, two edges of ArcPatch.glm are not of the same type. The first edge (the right one) consists of arcs. The second edge
consists of straight line elements. The first edit box "Cross-section
position" specifies z coordinate for cross-sectional plane where all other
parameter modifications will be applied. The next four edit boxes allow
modification of coordinates of edge in the cross-section plane. Note that type of
modifications is different depending whether the cross-section position is at the end (
z=0 or z=10 ) or anywhere in the middle of the axial range.
Note that curvature can be negative. Valid range for the curvature is [-cMax,
cMax], where cMax is 1/ (half distance between the edges at the current
cross-section)
To enter new value of the parameters press "Apply" button. If entered values are
valid, the model will change in 3D.
Step 1. Creating the project
- Open Visual Studio. Select File > New > Project in the menu. In Projects
tab select MFC AppWizard(exe). Enter
"Patch" in the Project Name edit box on the right. Select location for the project folder and click OK.
- In Step 1 of the application wizard select "Dialog based" and click
"Next". In the step 2 clear "About box" and press
"Finish" to accept defaults for all other settings. The project will
be created and the main dialog will be opened in resource editor.
- Delete "TODO.." label in the center of the dialog. Adjust size of
the dialog to 400x250 (the size is displayed at the bottom in the right hand
pane of the status bar). Move "OK" and "Cancel" buttons to
the bottom of the dialog.
Step 2. Inserting the KernelCAD component
- In the menu select Project > "Add to Project" > "Components and
controls".
In the opened dialog double-click "Registered ActiveX Controls" and
select "KernelCAD Control". Press Insert button. Press OK to confirm
insertion of the component. In "Confirm Classes" dialog press OK to
accept defaults. Close "Components and Controls Gallery" dialog.
At this stage icon
of the control should appear in the controls palette (if the palette in hidden
right-click on the menu bar outside all options and select
"Controls"). n addition to that files kernelcad.cpp and kernelcad.h should be added to
the project and CKernelCAD class should appear in the "Class View" tab
of the Project View.
Opening CKernelCAD node in the Class View will display available methods and
properties of the control. (See also Properties and Methods
)
- Select the KernelCAD control in the controls palette and position it on the
left in the dialog. The control should display default model Cube.glm.
- Right-click on the control and select "Properties". In the opened
Properties dialog open Control tab. Click "Browse" button and select ArcPatch.glm
in the Models folder of the installation directory, which is "C:\Program Files\DInsight"
by default.
- On Render page of the dialog turn "Show global axes" check box on
and select background color you like using the "Modify" button.
- Click "Save All" button in the tool bar. Select Build Patch.exe from Build
submenu. Press F5 key to run the application. Check that the model can be
rotated (left mouse button). Pan (shift + left mouse button) and zoom (right
mouse button) should work too.
Step 3. Programming access to the model
- Let us create a variable of type CKernelCAD in the main dialog class of the
project to get programmatic access to the control. Open Class Wizard (View >
"Class Wizard" in the Visual Studio menu). Open "Member Variables" tab, select IDC_KERNELCADCTRL1
in the list and press "Add Variable" button. In the "Member
Variable Name" edit box type m_ctrlCAD and press OK. Variable m_ctrlCAD
will appear under CPatchDlg in the Class View.
- Next we will get access to the IModel interface implemented by the
control. Double-click OnInitDialog() node under CPatchDlg in the Class View.
Replace "// TODO:" line with the next one:
IModel * pIModel =
(IModel*)m_ctrlCAD.GetModel(); //(A)
- Now we have access to the root interface, from which all other interfaces can
be queried. The next step is obtain access to ISection interface of the first (and only)
object in the model. In
this application it is make sense to store the interface pointer in a dialog's
variable. Generally storing interface pointers should be done with caution as
the object can be volatile and after some manipulations the pointer cam quickly
become invalid and its usage can cause access violations and other problems.
- Right-click on the CPatchDlg node in the Class View and select "Add
Member Variable". Enter ISection* for the type and m_pISection for the name.
Press OK. The header file PatchDlg.h now will contain line :
ISection * m_pISection;
m_pISection
= NULL;
to constructor of CPatchDlg .
- In OnInitDialog() enter the next line just
below the line (A):
pIModel->GetSection(0, &m_pISection);
//(B)
Note that in a real life application prior to the previous call it is necessary
to verify that the model contains at least one object with the help of
IModel::GetSectionCount(). Other available methods of IModel and all other
interfaces can be found either in this documentation (See
Interface List) or directly from file Samples\VC\Include\DIInterface.h in the installation folder.
Step 4. Accessing Surface of the Object.
We need to retrieve another interface, which will be stored permanently in a
dialog's variable. It is the IStrip interface. For objects of this type (Generic
3D Section) IStrip acts as a container of joined surface patches, of which
the object's surface consists. In this case the model consists of a
single patch.
- Add a public variable m_pIStrip of IStrip* type to the dialog with a
line
IStrip *
m_pIStrip;
in the PatchDlg.h and set its value to NULL in the dialog constructor.
- To
retrieve the interface add line
m_pISection->QueryInterface( IID_IStrip, (void**)&m_pIStrip);
//(C)
below the line (B) in the
CPatchDlg::OnInitDialog() function.
Before compiling the project it is necessary to add reference to definition
of KernelCAD interfaces. C++ definitions are contained in file
Samples\VC\Include\DIInterface.h
file. The best place for it is the StdAfx.h file.
#include
"C:\Program Files\DInsight\Samples\VC\Include\DIInterface.h"
To StdAfx,h file just before the line
//{{AFX_INSERT_LOCATION}}.
- Build the project (F7 key) to make sure that no compilation errors where
introduced so far.
Step 5. Accessing the base.
To be able to retrieve z-extents of the object and modify the current
cross-section position it is needed to obtain IAxiBase interface.
IAxiBase * m_pIAxiBase;
to the main dialog header file and set the variable to NULL in the
constructor.
m_pISection->QueryInterface( IID_IAxiBase, (void**)&m_pIAxiBase);
to the CPatchDlg::OnInitDialog() function next to line (C).
Step 6. Obtaining parameters of the object
Here we will get access to geometrical parameters of the only object in the
model and display them in controls of the dialog.
- Open the dialog in resource editor and place an edit box with id IDC_EDIT_ZCROSSPOSN
in the top right hand corner. Add label "Cross-section position:" next
to it.
- Bind this edit box to variable m_dZCrossPosn of double type using
"Member variables" page of the Class Wizard. Change its initial value
in the dialog constructor to 5.0.
Let us separate obtaining access to edges of the patch into a different function.
- Add new void function UpdateSurfaceInfo() to the dialog class using
right-click on the class in the Class View or otherwise.
- At the beginning of the function add line
m_pIAxiBase->SetCrossPosition( m_dZCrossPosn ); //
(D)
which sets the current
crosos-section position in the KernelCAD component at position
currently entered in the dialog.
IElement * m_pIElemEdge1;
IElement * m_pIElemEdge2;
IElement * m_pIElemPatch;
next to definition of m_pIAxiBase in the PatchDlg.h header
file and set them to NULL in the constructor.
IElement interface manages parameters of basic geometric primitives. In
this case elements are lines of two (right and left, see Surface Patches
topic) edges and the
adjoined surface patch represented by m_pIElemSegment.
m_pIStrip->GetElement(0, false, &m_pIElemEdge1);
m_pIStrip->GetElement(1, false, &m_pIElemEdge2);
just below the line (D). They will obtain IElement interfaces of the edges.
- The last line in the function will be:
m_pIStrip->GetElement(0, true, &m_pIElemPatch);
which will retrieve IElement interface of the surface patch.
- Add call to the implemented function UpdateSurfaceInfo() in the end of
CPatchDlg::OnInitDialog().
- Add remaining controls to the dialog so that it looks like:
- Create variables m_dX1, m_dY1, m_dX2, m_dY2 and m_dCurvature of double type and
bind them to the correspondent edit boxes.
- Create another void function UpdatePage() in the dialog. Whenever necessary,
this function will update information displayed by the dialog.
- Copy the code below and paste into the function's body
m_pIElemEdge1->GetParam(0, &m_dX1);
m_pIElemEdge1->GetParam(1, &m_dY1);
m_pIElemEdge2->GetParam(0, &m_dX2);
m_pIElemEdge2->GetParam(1, &m_dY2);
m_pIElemPatch->GetParam(0, &m_dCurvature);
UpdateData(FALSE);
Edge1 is a line, which at the current z cross-section position gives a point,
x and y coordinates of which are retrieved by the first two calls to GetParam()
methods of IElement interface.
The last call to GetParam() retrieves the only parameter of the surface
patch, namely radius of cross-sectional arc. UpdateData() is a standard MFC library
function, which updates controls with new values of the bound variables.
- Add call to UpdatePage() to the end of CPatchDlg::OnInitDialog().
- In the end of CPatchDlg::OnInitDialog() add another line:
pIModel->Release();
It
is important to release whenever an interface is no longer needed, otherwise a
memory leak and sometimes more serious problems may occur.
- Build the application and check that edit boxes display meaningful values.
Step 7. Programming modifications of the model
Here we will add code to update the model with new values of entered
parameters.
- Add a handler of Apply buttons clicks by holding Ctrl key and double-clicking
the button in resource editor.
- Fill the body of the handler with the code below:
UpdateData();
// Force cross position into valid range
if(m_dZCrossPosn<0.0)
m_dZCrossPosn = 0.0;
if(m_dZCrossPosn>10.0)
m_dZCrossPosn = 10.0;
m_pIAxiBase->SetCrossPosition( m_dZCrossPosn );
m_pIElemEdge1->SetParam(0, m_dX1) ;
m_pIElemEdge1->SetParam(1, m_dY1);
m_pIElemEdge2->SetParam(0, m_dX2);
m_pIElemEdge2->SetParam(1, m_dY2);
m_pIElemPatch->SetParam(0, m_dCurvature);
m_ctrlCAD.UpdateSurface();
UpdatePage();
Invalidate(FALSE);
UpdateWindow();
UpdataData() here is an MFC function which will copy contents of
edit boxes into correspondent variables. For simplicity we have hard coded here
actual minimal and maximal z coordinates in the model.
SetParam() calls make actual changes in the model. In
real application it is necessary to check that all call succeeded and returned
S_OK.
Failure is quite common and does means only that the parameter value was
rejected by the software because it would make impossible the geometry, like an
attempt to make ends of an arc too far for the given radius or attempt to make
radius too small for the given distance between the ends.
UpdateSurface() call is needed to recalculate the surface after
changes in the geometry.
The last two calls is the standard MFC way to make the control to
redraw itself.
Step 8. Cleanup
Add virtual destructor to the declaration of the dialog. Add the
code below to the implementation file, so that the destructor looks like:
CPatchDlg::~CPatchDlg()
{
if(m_pIElemPatch)
m_pIElemPatch->Release();
if(m_pIElemEdge1)
m_pIElemEdge1->Release();
if(m_pIElemEdge2)
m_pIElemEdge2->Release();
if(m_pIStrip)
m_pIStrip->Release();
if(m_pIAxiBase)
m_pIAxiBase->Release();
if(m_pISection)
m_pISection->Release();
}
Step 9. Testing the application
Try to enter different values in the edit boxes and observe how the geometry
of the model changes. Note that the result depends dramatically on whether the cross
position is at the end of z (base ) range, namely 0.0 and 10.0 or anywhere in the
middle.
Note also that when the cross-section position is inside the range, left and
right hand edges behave differently because the right hand edge is a curve and
the left hand one is a straight line. This can be verified using 3D Debugger.
|