An Exclusive Event…Only a Select Few Can Even Hear About It

November 16, 2015 / 0 comments / in API  Applied Engineering  General  Studio Tips  / by Blake Miller

Consider this scenario.  I have an overview grid screen that has a list of wells with some high level information.  I click on one of the wells and a separate screen opens with more detail.  On that detail screen, I click on a button that opens another screen that has a trend with various well points.   Cool, I have separate dedicated screens that I’m able to view the various bits of information I desire at the same time.  Now I want to be able to select on a different well on the first screen and have the other screens follow.  And, I want to be able to look at multiple sets of these screens for different wells at the same time.  How can I do that

In my last post, I discussed the topic of custom events and you certainly could use that technique to solve this problem if I hadn’t thrown in the last part about viewing two different wells.  So what’s a CygNet Admin to do?  In that post, I teased the idea of raising group custom events.  And you guessed it, that’s the secret to solve this problem.  So let’s get to it.

Like a custom event, a group custom event is an event that is “heard” by open screens; however, the difference is that group custom events are only “heard” by screens that are in the same view group. So, before we can talk about raising this type of event, we must first answer the question “What is a screen view group?”

By default a Studio screen can only be opened once. When you attempt to open a screen that is already opened, that screen is just brought into focus. However, by using a parameter of the HyperLink, you can open a single screen multiple times. Below is an example of what the same screen opened twice looks like.

You will see in the title bar of each screen the “Title” property of the screen followed by a colon and then a number. That number is the View Group ID. This is a run-time property of the screen and can be utilized in scripting. More on that in a bit.

A brief note about the View Group ID number. Studio will generate this number each time a new group is needed. In this example, the View Group IDs are 1 and 2. This is because I started Studio and opened the screens straight away and there weren’t any screens opened in a group. If I were to close one of the screens and reopen it, the View Group ID will be something different.

In this example, we have two groups with one screen in each group. In the following example, I have two groups with two screens in each group. The screens in the first group are on the top and the screens on the bottom belong to group two.

So that’s the idea behind screen groups. Let’s look closer at how we open screens into a group.

I created a simple launch screen with two buttons on it.

The first button is the standard way of issuing a HyperLink. In this example, I’m using script to issue the HyperLink but you can use a HyperLink button to do the job. When you click on this button, a screen will open but subsequent clicks will not open up multiple screen instances. Nothing new here.

The second button is the way to configure a HyperLink to open up a screen multiple times. There are a couple of ways to do this. The first is via the Property Sheet of a HyperLink button. The NewViewGroup property is used to specify if the supplied file path should be opened into a new view group.

The second way to open a screen into a new view group is via the HyperLinkEx method in script. This is what I am doing in the sample screens. There are four parameters of the method and the fourth one is what CygNet Help calls “OpenMultipleInstances”. Check out the Help file for more information on the other parameters.

When the NewViewGroup property is “1-Yes” or the “OpenMultipleInstances” parameter is “True” and the button is selected at run-time, the file specified is opened into a new view group.

So far so good, right? But what about the second screen in each group? How did they get opened in the appropriate group? Well, that’s easy. It’s just another HyperLink.

When a HyperLink is issued the screen is opened in the same view group as the calling screen (assuming that it wasn’t issued with the NewViewGroup property set). This is what I’m doing in the example. Screen 1 has a HyperLink button (I’m scripting it) that opens up Screen 2 in the same View Group. If that HyperLink were configured for multiple instances, the screen will open into yet another View Group.

So, with this we can have the same screen opened multiple time. And with each one of them being fed different facility and site.service settings (via the other HyperLink parameters), you can create some interesting workflows. The next logical step is to create some interactions that are shared between all open screens within a group. For example, say I have several screens opened in the same group and all of them have were fed the same facility. Now, I want to look at a different facility and I want all the screens in the group to change to that same facility. This is where raising a group custom event comes into play.

Raising a group custom event is very similar to raising a custom event. Instead of using the RaiseCustomEvent method, we are going to use the RaiseGroupCustomEvent method. The parameters of each method are the same, with the exception of a fourth parameter for RaiseGroupCustomEvent. The four parameters of this method are EventID, Data, ViewID, and ViewGroupID.

In the example below, I have the same two screens in the same two groups as above. When I click on the “Raise Custom Event” button on Screen1, Screen 2 changes the text on the textbox on the screen. The text is dynamic and shows the View Group ID in its string.

The code behind the “Raise Custom Event” button on Screen 1 is fairly simple.

Workspace.RaiseGroupCustomEvent “ACTION”, “Hello from ” & theframe.Title & vbCrlf & “(View Group ” & theview.ViewGroupID & “)”, theview.ViewID, theview.ViewGroupID

Notice the last parameters of the call. This is the View Group ID run-time property I spoke of earlier. You don’t necessarily need to know the View Group ID in order to use the method. If you are driving a group of screens from say a main jump point (Screen 1 in my example), then you can just dynamically use the main screen’s View Group ID to raise the event to other screens in the same group.

On Screen 2, you can check out the script in EventCustom on TheView to see how the event is being processed.

A quick note about the ViewID, the third parameter in the method call. The RaiseGroupCustomEvent will raise an event that all screens in the view group will hear, including the calling screen. The ViewID can be used to suppress any action on the calling screen when it hears the custom event it just called.

The RaiseCustomEvent and RaiseGroupCustomEvent methods of the Workspace are very powerful and can be used to create some interesting screen applications. I’d love you hear how you are going to use them.

Here are my sample screens used in this post.

View Group Screens