Lesson 3 - Creating and Navigating Containers

Having provided an overview of what Containers are and how they can be used in the previous Lesson, in this Lesson we will discuss the details of creating, navigating and using Containers.

Let’s start by opening a new model and inserting a Container. You will find the Container under the element category of the same name (“Containers”). After inserting the element, you will see that the dialog for a Container element looks like this:

For now, we will just note that like other elements, a Container has an Element ID (name it C1) and a Description. It also has a number of other options that we will ignore for now.  We will discuss these later in this Unit. Create a second Container and name it C2.

Containers in a model are easily identified in the graphics pane: they all have a small arrow in their upper left-hand corner:

As pointed out in the previous Lesson, you can "enter" a particular Container (view its contents) by clicking on the arrow. You can also enter a Container via a Crtl+double-click on the element (holding the Ctrl key down while double-clicking the left mouse button). 

Let’s enter one of the Containers (C1) you just created. When you create a new Container element, it is initially empty (it contains no elements or objects of any kind). You place new elements in a Container by entering it and inserting elements.  Insert a new Data element (and name it A).  You can leave it at its default definition of 0.  While still inside Container C1, create a third Container, and name it C3. Then enter that Container. Inside C3 create another Data element and name it B.

Now that we have some Containers created, we can discuss the basics of Container navigation. We already know how to enter a Container.  But how do we leave a Container (or jump to another Container)?  One way to do this is through the navigation bar at the top of the graphics pane:

Follow these steps to explore this navigation bar:

1. The button furthest to the left jumps to the “top” of the model (the “Model” Container). Try it now.  You will jump from C3 all the way to the top of the model. Note that the current location (i.e., the navigation path) is indicated to the right of the buttons.
2. The left arrow button moves back to the previously viewed Container.  Press it now and you will return to C3.
3. The right arrow button (furthest to the right) moves “forward” (after you have moved back).  Press it now and you will return to the top of the model.
4. Press the left arrow button again to return again to C3.
5. The second button from the left moves up one level.  Press it now and you jump up to C1.

The navigation path is shown just to the right of the four buttons.  If you click on an arrow in this list (e.g., the arrow between “Model” and “C1”), it will show a drop-list with all the other Containers that are at the same level (in this case, C2 is at the same level of containment as C1 – one level down from the top):

If you click on C2 in this list, it will jump to that Container.  Do that now, and then repeat the process to jump back into C1.

Although the navigation bar is convenient and you will use it often to move between Containers, in a very large model with many levels of containment, this would not be the most efficient way to move deep into the containment hierarchy.  Instead, you will use the browser.  The key thing to understand about the browser is that it is synchronized with the graphics pane. That is, if you click on an element in the browser, the Container in which the object resides will be shown in the graphics pane. To illustrate this, do the following:

1. Go to the browser and (if it is not already expanded), expand C3 (by clicking on the arrow to its left).  You will see that it contains B:
   
2. Now click on B in the browser and you will jump inside C3 (i.e., the contents of C3 will be shown in the graphics pane).

Now navigate your way back into C1. Looking inside C1, we see the element A and the Container C3.  Suppose we want to move A inside of C3.  How would we do this?  The easiest way is as follows:

1. Left-click on A and drag it to C3. 
2. When you do so, a blue box will be drawn around C3. 
3. Release the drag (i.e., stop left-clicking), and A will be moved into C3.

Now enter C3.  You will see both A and B inside the Container.  Now let’s move B to a different Container (C2).  We can’t drag and drop it, because there is no place to drag it to (i.e., we can’t see C2, as it is not located in the same Container as A and B).  Instead, do the following:

1. Right-click on B, and in the context menu that is shown, you will see an option to Move to… 
2. Left-click on this and a browser will be displayed that shows the containment hierarchy.
3. Select C2 and press OK.  B will then be moved into C2.

Finally, let’s navigate our way inside C2 (which now contains B). Instead of moving B, let’s copy and paste it to a different location:

1. Select B.
2. Press Ctrl-C to copy it to the clipboard.
3. Navigate to the top level of the model.
4. Press Ctrl-P to paste a copy of B to this Container.

When you do this, you will note that the new Data element is named B_1 instead of B.  That is, when you pasted this element, GoldSim automatically renamed it. Why? As mentioned in Unit 5, by default, all element names must be unique (i.e., they are “global” variables).  This is because at some point you will reference the element in another element (e.g., when creating an Expression).  If two elements had the same name, it would be ambiguous which element was being referenced. 

Having said that, if indeed all element names were required to be unique in a GoldSim model, it would be very difficult and cumbersome to build large, complex models.  All advanced programming languages provide an ability to create “local” variables (such that a variable can only be referenced within a specified scope or region of the model), and hence GoldSim provides such a capability. By creating local variables, you can build models which have elements with non-unique names. In fact, as we will discuss later in this Unit, we will use a special property of Containers to create local variables (such that you could have multiple elements named B in the same model).

We’ve now learned the basics of creating and navigating Containers.  In the next Lesson, we’ll do a simple Exercise to give you some more practice with Containers. (You don’t need to save the small example we have just been working on).