Selection Goodness

Today’s post is on selections.  Selections are a great way to script changes to multiple objects and a great way to make your custom methods more flexible.
Selections are just what they sound like, a group of objects, placed into a collection for processing.  Let’s jump right in with a simple example:

Dim mySel
Set mySel = ActiveModel.CreateSelection
mySel.AddObjects ActiveModel, cls_table, false, true

The first two lines declare and create your selection.  The third line adds all objects of the given class, in this case tables, to the selection.  The last two parameters (false, true) tell the script to skip shortcuts and to recurse through sub-packages.­­  Now that we have our selection, how do we use it.  The following lines will loop through the collection.  For my examples, I’m using SetNameAndCode to rebuild the codes on all the objects in the selection, just to demonstrate the concept.

Dim myObj
Dim mySel
Set mySel = ActiveModel.CreateSelection
mySel.AddObjects ActiveModel, cls_table, false, true
For each myObj in mySel.Objects
 With myObj
 Output .Name
 .SetNameAndCode .Name, "", True
 end with
Next

So far, so good.  It gets better though.  You’re not restricted to a single class in a selection.  So if you’d like to rebuild the codes for both tables and views, you can add both classes.  Our revised code looks like:

Dim mySel
Dim myObj
Set mySel = ActiveModel.CreateSelection
mySel.AddObjects ActiveModel, cls_table, false, true
mySel.AddObjects ActiveModel, cls_view, false, true
For each myObj in mySel.Objects
 With myObj
 Output .Name
 .SetNameAndCode .Name, "", True
 end with
Next

Without a selection, we’d be stuck doing something like:

For each tab in ActiveModel.tables
 Output tab.Name
 Tab.SetNameAndCode Tab.Name, "", True
Next
For each view in ActiveModel.views
 output view.name
 view.SetNameAndCode view.Name, "", True
Next

That’s not too bad, but notice our SetNameAndCode sample is very short. Also, we’re only dealing with two classes and we’re only dealing with objects in the root of the model.  If we want to recurse through packages, there’s a lot of additional work yet to be done.
Now, suppose we don’t want to include all objects of a particular class, but we’d like to be a bit more choosey.  We have a couple of options:

• AddActiveSelectionObjects
• ShowObjMultiSelection
• ShowObjectPicker

The first, AddActiveSelectionObjects method, does exactly what it says it does.  Whatever objects you currently have selected, either in the browser or the active diagram are added to your current selection.  I’ll focus on the other two.
The second two provide dialog boxes which you can use to define your selection manually.
Here’s an example:

Dim mySel
Set mySel = ActiveModel.CreateSelection
mySel.ShowObjMultiSelection ActiveModel, "Tables"

The first parameter is the name of the parent object.  In this case, the active model.  The second parameter, this case “Tables” is the name of the collection you want to select from.  You’ll get a dialog that looks like this:

Choose the objects you want and processing using the same select loop.  Instead of the active model, the first parameter can be changed a particular table, view, etc.  This allows you to choose from objects that apply only to that object.  This is very handy in a custom method.  For example, this method would allow you to select references on a particular table.  Keep in mind that the selection itself is still a property of the model, not Obj.

Sub %Method%(obj)
   dim mySel
   dim myObj
   Set mySel = ActiveModel.CreateSelection
   mySel.ShowObjMultiSelection Obj, "InReferences"
   for each myObj in mySel.Objects
      With myObj
         Output .Name
         .SetNameAndCode .Name, "", True
      end with
   next
End Sub

If you’ve looked at the VBScript help file, you probably know there’s a great example of how to build your own custom selection list for the multi-selection method.  I’m going to change it just a bit to show you how to get a single selection dialog with both inReferences and outReferences.  This also demonstrates the Add method available to any collection.

Sub %Method%(obj)
   dim myObj
   dim ref'add all of the objects we’re interested in to the collection
   Set mySel = ActiveModel.CreateSelection
   For each ref in Obj.inReferences
      mySel.Objects.Add(ref)
   next
   For each ref in Obj.outReferences
      mySel.Objects.Add(ref)
   next
   'now show the objects in the selection in your dialog
   mySel.ShowObjMultiSelection mySel, "Objects"
   for each myObj in mySel.Objects
      With myObj
         Output .Name
         .SetNameAndCode .Name, "", True
      end with
   next
End

The other method of adding objects to a selection, SubShowObjectPicker, behaves quite a bit differently.  I don’t use this method nearly as often, but we’ll cover it just for completeness.
Unlike the mult-selection dialog, ShowObjectPicker always (as far as I can tell) starts from the active model.  You can choose which class of object the user gets to choose from (e.g. tables or columns) but you can’t choose to show only columns belonging to a specific table.  You can filter by stereotype but unless you’re going to change the stereotype for an object at runtime (and set it back when you’re done), this isn’t an approach I find particularly useful.  Anyway, here’s a code snippet and the result.

Dim mySel
Set mySel = ActiveModel.CreateSelection
mySel.ShowObjectPicker "Table:Column"

This gives you the following dialog:
Well, that’s enough for now.  More to come.