[00:00] In this lesson, we're going to examine the scripting functions available to manipulate and navigate between Windows and Vision. For starters, let's examine the project we'll be using. Here, in the designer, I've got three windows opened. This green main window, an orange main window, and a yellow popup window. Each of these windows has two or more buttons on it, which will trigger various underlying navigation script actions between the windows as noted on the button labels. So let's first take a look at a client to see how this project behaves and the underlying scripting which makes it happen. So we'll open this minimized client down here in the task bar, and we will log in as an admin user, like so. Then we see we start out in the green main window, which simply means that the window begins with its start maximized property equal to true. By pressing on the swap to orange button, or the swap to green button, we see we can swap back and forth at will between the green and orange windows.

[01:09] And in the windows pull down menu at the upper left, note that we only have one main window open at a time. Then, when we click the open popup from either window, an added yellow popup window appears, and that popup knows exactly who opened it, in this case, green. And, in the pull down, we see that now we really do have two windows open. It added an additional popup window to the list. Then, from this popup window, we can also swap the main window behind it. And by clicking on Close, this popup window can close itself. And again, in the pull down, we see we really are back down to only one open window. Then, from this orange window, we can open the popup window once again, and again the popup knows it was opened by orange this time. This is all done with parameter passing, and we'll see how that's done shortly. Next, let's visually summarize what we've just seen. Here's a state chart, a high level visual summary of all the navigation transitions we just saw between the four possible states.

[02:10] So we began in green, then we went back and forth between orange and green alone. And from either window, we could open the popup at the same time. That popup allowed us to swap back and forth between the background main windows, and then either popup could close itself, taking us back to one window alone. Next, let's go back to the designer to see how all of this was implemented in navigation script functions. If we examine the swap to buttons in either the greener orange windows, we'll see that they are actually very straightforward. Here, in the action perform script, we simply call system.nav.swapTo with a full path of the window to swap to. Here, in the green window pop up, it's the orange window, and in the other case, of course it would be the green window. Now, swapping inherently involves two windows, the window you're swapping from and the window you're swapping to, but you'll notice this function only requires the window we're swapping to.

[03:07] It doesn't need to know the window we're swapping from. This is by design. Ignition expects most projects to be configured such that there's only ever one main window open at a time. The reason is that having multiple main windows open at once is really just a waste of resources. So if you ever wind up in a situation where you have more than one main window open, you can only see one window at a time anyway, so it's probably a mistake. So swapTo leverages the idea that there's only one main window open at a time. So when you try to swap to another window, it can detect the maximized window it should be swapping from by just looking at the window that's currently open. By contrast, let's consider the popup window, where we have two dedicated buttons to swap between the green and orange main windows. In this case, we use the system.nav.swapWindow function, which now takes two windows as its inputs, the window to swap from and the window to swap to.

[04:09] Here, we're swapping from the green window to the orange window. For the orange window, of course, it'd be the opposite order of this. And this might be important for a number of reasons. We might have a dock north header window that's swapping out the main windows beneath it. We might be swapping popup windows. We might have some Wizard type setup that has a sequence of popup windows that need to blend into each other and appear like a seamless sequence of windows. In the end, swapping isn't inherently something that only main windows should do. Any window can swap into another window. All swapping is, is closing one window and opening another one in the exact same position as the original window. By the way, if we recall from the earlier client execution, this popup knows which main window opened it with some labeling text, which just isn't shown yet. But let's see how that's going to be done and how the popup window came to be opened in the first place.

[05:04] Here, we're using the navigation builder, and we open and center the specified popup window. And here, note that we're also passing a parameter, called open by, whose value here is green, and in the other window, of course, it would be orange. All this results in the script editor code getting automatically written for us. You can use the navigation builder, but it's not required. You can also write this script by hand for simple actions. Here, we're now using system.nav.openWindow with the specified window to open, and on the next line we center that window, then we make use of the optional parameter passing input. This is in the form of a Python dictionary, where the keys are the names of root container properties on the target window, and the values are the values you'd like to pass for those parameters. Parameter passing is really an important concept for window navigation.

[06:04] It's very common to create a parameterized window, where the same window is opened in multiple places throughout your project, but a different context based upon the past in parameters, like so. So here, the value green, the window from which the popup was opened, is passed along to the popup window's root container to its open by custom property down here at the bottom, which is also seen in the custom properties popup of the popup window root container. Now that we have green or orange window name available to consume here on the popup window, it's very easy to display that value, as we'll do on this hidden label. And we'll scroll down, or up rather, to its data section and look at the binding on the text property. And we've got an expression binding, like so. So we've got some labeling text, and this is where we consume that opened by property.

[07:08] And all of this is how each popup window can know and display which main window invoked it, or maybe consume that, or any other parameters for other purposes. Finally, closing the popup window, or any other window, is actually very simple. All we need to do is use system.nav.closeWindow and give it the name of the window to be closed. That's it. We've just gone over lots of details. Let's see if we can summarize everything into one place. This is the same state transition diagram as before, except this time adding the functions we just used. All of these methods are found in the system.nav library. As you might imagine from context, O, G, and P stand for the orange, green, and popup windows. To swap between the main windows, we use swapTo and the desired windows name. To open the popup window and pass along a parameter, we used openWindow, the popup window name, and an optional dictionary input.

[08:11] To swap between background main windows from the popup, we used swapWindow, along with a from and to windows, and to close the popup window, we simply used closeWindow and the popup name. So in summary, we've now seen how to implement some basic window navigation using methods of the system.nav library. If we ever need to implement some more elaborate navigation system, there are other useful functions available in there to do such things as opening additional instances of a window to have multiple copies, implementing back forward home navigation. There's lots of useful capability available to users of Ignition Navigation Scripting in the system.nav library.