CATIA V5 Automation

VBA userform display techniques

Advertisements

First off, the website improvement survey results have been steadily coming in over the last two weeks.  If you were one of the survey participants, thank you very much!  So far I am getting a lot of good information and using it to plan upcoming topics.

One subject area where many people have shown interest is VBA userforms (I will just call them forms).  Adding forms to your CATIA programming project can really enhance it and provide a better experience for the end users. So in this article, I will cover some techniques for displaying, hiding and closing forms.  I’ll discuss a few of the common things you might encounter and how to handle them.

Creating the forms used in this article

The explanations in this article will be based on some very simple forms.  If you are familiar with forms, you can probably skip this section.  However, if you are new to VBA and/or using forms, I have included some quick instructions below so you can create them and try the techniques yourself.

Setting up a new VBA macro library

  1. In CATIA V5, go to Tools-Macro-Macros or just press Alt-F8
  2. Click the “Macro libraries…” button at the top right
  3. Set the library type to “VBA projects” from the drop down menu
  4. Click the “Create new library…” button and either accept the proposed VBA file location or enter your own.
  5. Click close two times.

Creating the forms

  1. Press ALT-F11 to open the VBA editor.
  2. In the Project explorer window (top left side), right click on the project then select Insert – UserForm.  Make sure it is named UserForm1 in the Properties window
  3. Find the controls Toolbox.  If you do not see it, select View – Toolbox from the main menu.
  4. On the Toolbox, click the CommandButton icon then click on the Form and drag to add a CommandButton control to the form.  Make sure it is named CommandButton1 in the Properties window.
  5. Set the Caption property for the CommandButton1 control to “Show Form2” in the properties window.
  6. Repeat steps 2-4 to create another Form and CommandButton.  The names of these objects should be UserForm2 and CommandButton1.  Set the CommandButton Caption property value to “Close” on this form.

At this point, you should have something like this:

Displaying a form modal vs. modeless

Forms are displayed by the Show method of the form object.  This method has an optional argument to specify whether the form should displayed modal or modeless.  By default, if you don’t specify anything for this argument, the form will be modal.

So what do these terms mean?  Basically, a modal form will not let you interact with any other part of the application until that form is closed.  This means that you cannot interactively use other CATIA commands or interact with any other forms that might be displayed at the time.  Modal forms are an effective way to force the user to respond or complete some task before doing something else.  One of the simplest and most familiar examples of this sort of behavior is a msgbox.  Once it is displayed, you cannot do anything until you respond by clicking one of the msgbox buttons.

The code – modal

On Userform1, double click CommandButton1.  This will bring you into the code editor and will create an empty subroutine to handle the click event for that button at runtime.  Add code as shown below to display UserForm2 as modal.


Private Sub CommandButton1_Click()
     UserForm2.Show vbModal
End Sub

On the other hand, when a form is displayed modeless the user still has complete freedom to interact with other forms in the project or even run other commands in CATIA itself.  Once a modeless form is displayed, it will just patiently sit there waiting for you to give it some attention.

The code – modeless

Add a new module to the project by right clicking on the project in the Project Explorer window and selecting Insert – Module.  In this module, create a subroutine called “Main” and add one line of code as shown to display UserForm1 modeless.


Sub Main()
     UserForm1.Show vbModeless
End Sub

Testing it out

To run the project, activate Module1 then place your cursor anywhere inside Sub Main() then click on the triangle button on the Standard toolbar. You should see UserForm1 appear.  Since we displayed it modeless, you should be able to work in CATIA as if the form was not even there.  Go ahead and create a new part, create geometry, save, etc. – the form just sits there the whole time.   Now click the button that says “Show Form2” and you will see UserForm2 appear.  However, since UserForm2 is modal, you will not be able to do anything else until you close that form.

Note that since we did not yet add any code for the click event of the Close button, you will have to close the form by clicking the X in the top right corner.

When to use each

The point here is to take a second and think about how each of your forms should be displayed to the user.  Here are some scenarios when you might use modal vs. modeless forms:

Modal

  • You have a form that displays some options related to your application.  In this case, the user should not be doing anything else until the options are set and confirmed.
  • You may have some important information to display and you want to force the user to acknowledge it before moving on to some other task.

Modeless

  • Your program automates some tasks but also requires the user to manually perform some related operations on their own in CATIA along the way.  A modeless form will provide that flexibility.
  • You want to be able to display multiple forms and allow the user to view and interact with all of them.  Just don’t go crazy here.  It’s possible to confuse the user with too many and possibly even confuse yourself when trying to program it!
  • The form requires selections of objects in CATIA.  If it is displayed modal, the user will not be able to make those selections

Important note! You cannot display a modeless form when a modal form is already displayed.  If you try it you will get a run time error.  However, it is permitted to display either a modal or modeless form while a modeless form is already displayed.

Hiding a form

Form objects provide a Hide method to make the form invisible.  Sounds simple enough, but make sure you understand what is going on behind the scenes.  The Hide method does not actually destroy the Form and remove it from memory.  Instead, the form is still running only you can’t see it.  I primarily use the Hide method for things like temporarily hiding a form while some other task is taking place then I show it again.   Another reason is the form might have data associated with it that you don’t want the user to have to fill in again if the form was destroyed and recreated.

The code – Hide

To try the hide method, activate Userform2 then double click CommandButton1.  Then enter the code below.  Note that any code written inside the form can also make use of the Me keyword to refer to the form itself.


Private Sub CommandButton1_Click()
     Me.Hide
End Sub

Try running the project again.  This time when you click the Close button on UserForm2, it will disappear.  Just remember that since we used the Hide method, it is still running behind the scenes…

Unloading a form

When it’s time to close a form for good, you should always unload it as opposed to hiding it.  The Unload statement will destroy the form and remove it from memory.  You will typically use Unload much more frequently than the Hide method in your projects.  Common uses for Unload would be the click event for an “OK”, “Cancel” or “Close” button.  Always be sure to Unload the main Form for a project when it is time to end the program, otherwise the project will actually keep running in the background but the user can’t see it!

The code – Unload

If you want to try the Unload command, go back to UserForm2 and change the code for the Close button click event as shown below.  You will not viusally see any difference at runtime but now the form is destroyed rather than just hidden.


Private Sub CommandButton1_Click()
     Unload Me
End Sub

Using the QueryClose event

Now for a more advanced topic related to forms.  It’s an event called QueryClose which will occur just before a form tries to close.  When I say close, I really mean when it gets unloaded – this event does not occur when a form is hidden.  This event gives you the programmer a chance to take some action before the form closes and do some interesting things.

When the QueryClose event occurs, two variables are passed into the subroutine as arguments.  The first variable called CloseMode lets you know how the close was initiated.  After checking this value, you can decide whether you want to take some action.  There are four possible values:

0      The user clicked the X at the top right corner of the form.
1      The Unload statement is invoked from code.
2      The current Windows operating environment session is ending.
3      The Windows Task Manager is closing the application.

The second variable passed in is called Cancel and it allows you to cancel the attempt to close the form if you decide it is necessary.

The code – QueryClose

To add code for the QueryClose event, right click on UserForm2 then pick “View Code”.  Once you are in the code editor, find the two drop down boxes at the top.  The left one lists the objects that support events and the right one lists their events.  So select UserForm on the left and QueryClose on the right and a new empty procedure will be added.  Then, simply add the following code:


Private Sub UserForm_QueryClose(Cancel As Integer, CloseMode As Integer)
     If CloseMode = 0 Then
          MsgBox “The X was clicked.  This is not allowed!”
          Cancel = 1  ‘A value of 1 Cancels the close operation
     Else
          MsgBox “Unload statement was called.  This is OK”
     End If
End Sub

Now test the project.  It really doesn’t need much explanation.  If you wanted to simply disable the X with no other messages or actions (as mentioned earlier) you might use this code instead:


Private Sub UserForm_QueryClose(Cancel As Integer, CloseMode As Integer)
     If CloseMode = 0 Then
           Cancel = 1  ‘A value of 1 Cancels the close operation
     End If
End Sub

Conclusion

This article showed you best practices to display, hide and unload forms as well as a powerful way to respond to a form closing.  I have used these techniques in many projects with great results and I hope they prove useful in yours as well.  If you have any questions, just post a comment below.

Please take a moment to rate this article…Just click the stars up near the title.

Add to: del.icio.us, StumbleUpon, Digg, Google

Advertisements