Multi-Monitors with CitectSCADA

(v5.50 and v6.00)

Technical Paper
March 2005

Presented by:

Peter Horsley

Abstract

This document provides information on configuring a Citect v5.50 or v6.00 project (either based on the XP style or the standard templates) to work with multiple monitors. The reason this document is written specifically for v5.50 and above of CitectSCADA is that this version introduced the CSV (XP) style templates in the form of the CSV_Include project, which contains greatly improved multi-monitor functionality. The operating systems on which this document is based are Windows 2000 and XP.

It should be noted that in fact any version of Citect can be used in multi-monitor mode: for details of how to achieve this see Section 2.2.

Contacts

support@citect.com

Contents

Purpose. 3

1. Required Hardware. 4

1.1 Extended (or expanded) mode. 4

1.2 Spanned (or stretched) mode. 4

1.3 Number of monitors. 6

2. Setting up your project 6

2.1 Scenario A – The easy way. 7

2.2 Scenario B – The manual way. 7

3. Runtime Issues. 8

3.1 All / new windows appear on the left-most monitor 8

3.2 Popups appearing on the wrong monitor 8

3.3 Popups / tooltips appearing split across two monitors. 9

3.4 Effect of [Page]Startup and [MultiMonitors]StartPagex. 9

3.5 Window is crossing onto the next monitor by a few pixels. 9

3.6 Template based AN numbers. 10

3.7 Invalid Window prompt on startup. 10

Appendix A: Multi-monitor Cicode Functions. 11

Appendix B: Running in Extended Mode. 14

Purpose

This document provides information on configuring a Citect v5.50 or v6.00 project (either based on the XP style or the standard templates) to work with multiple monitors. The reason this document is written specifically for v5.50 and above of CitectSCADA is that this version introduced the CSV (XP) style templates in the form of the CSV_Include project, which contains greatly improved multi-monitor functionality. The operating systems on which this document is based are Windows 2000 and XP.

It should be noted that in fact any version of Citect can be used in multi-monitor mode: for details of how to achieve this see Section 2.2.

1. Required Hardware

When connecting multiple physical monitors to a PC, there are three possible hardware configurations:

1. A dual-head graphics card in spanned mode.

2. A dual-head graphics card in extended mode.

3. Two single-head graphics cards in extended mode.

1.1 Extended (or expanded) mode

This is the default multi-monitor mode in Windows where all monitors connected to the installed video cards are treated as individual desktops. Each monitor can use different settings (resolution, colour depth, refresh rate and coordinate system). Citect does not support this mode, and it is difficult to achieve correct multi-monitor functionality. However some information on how to do this is provided in Appendix B.

1.2 Spanned (or stretched) mode

This is where all monitors are combined into a single widescreen (or tallscreen) desktop. Each monitor must use the same display settings.

The most important thing to note is that all versions of CitectSCADA only support running in spanned mode, NOT extended mode. You can check which mode you are currently in by doing:

1. Start→Run
2. Type “asdf” (or any other sequence of random characters)
3. If you get a message box that is half on one monitor, half on the other, you are running in spanned mode. If the message box appears in the exact centre of either of the monitors, you are running in extended mode.

To change to spanned mode, right-click the desktop, choose Properties→Settings tab and do the following:

1. First make sure the dual-head functionality (called multi-display for Matrox G450 cards) is enabled by clicking Advanced→DualHead tab as indicated by Figure 2 on the next page.
2. Back on the Settings tab, choose the dual-head adapter and set the resolution to the complete width of both screens (e.g. 2048x768 – see Figure 1 on the next page. Note that the resolution setting on each screen could be different if you are using two different types of monitors for e.g. 1024x768 and 1280x768 so the complete width of both screens would be 2304x768). This should be configured as the primary monitor.

Figure 1: Spanned Mode

Figure 2: Enabling multi-display

Note that if for some reason you are not able to run in spanned mode (e.g. cost and / or availability of graphics hardware), it is still possible to get Citect working with multi-monitors in extended mode. See Appendix B for information on how to achieve this.

1.3 Number of monitors

To use more than two monitors is simply a case of adding extra dual- or single-head graphics cards; however this document only covers the configuration of two physical monitors. The CSV_Include project is capable of working with up to six monitors. Windows XP itself supports up to 10 monitors. The graphics cards used can be PCI or AGP; however AGP is recommended for performance reasons, especially if large screens are used. Also, the more memory available on the card the better (minimum 16Mb recommended). On-board graphics cards are not recommended and many do not work in multi-monitor mode at all.

2. Setting up your project

There are two scenarios:

A. Your project is based on the XP Style templates.

B. Your project is based on the standard templates.

In both of the above two scenarios, it is important to use pages with the same size as the resolution of one of your monitors. The XP style templates in v5.50 are designed for XGA (1024x768). In v6.00, XP style templates are provided for both XGA and SXGA (1280x1024). Other standard sizes are as follows:

Further, it is essential in both scenarios that the following two INI parameters are set in your INI file:

[Page] DynamicSizing=0

[Animator] FullScreen=1

Note that when you run Computer Setup Wizard, there is an option to “Display Title Bar” – this is actually the inverse of the setting for [Animator]FullScreen so make sure that is unchecked.

You may be aware that it is possible to integrate some of the CSV functionality into a project based on the standard templates by simply including the “CSV_Include” project manually (in Project Editor→ System→ Included Projects). You should also be aware that mixing templates is not supported (i.e. has not been tested by Citect’s Quality Team) and you have a good chance of running into a variety of issues at runtime. This is also the case with multi-monitors, so this configuration is not recommended.

2.1 Scenario A – The easy way

This is the simplest way to set up multi-monitors in Citect. Just edit your INI file using CiConfig[1][1] or Notepad and add the following three INI parameters under the [MultiMonitors] section (add one if non-existent): or Notepad and add the following three INI parameters under the section (add one if non-existent):

1. Monitors = n

Specify how many monitors you are using with the value n.

2. ScreenWidth = n

Specify the (horizontal) width of 1 screen (e.g. 1024 if you have two monitors set to this resolution). Note: all monitors must be set to the same width.

3. StartupPagen = PageName

For each monitor number (starting from 1), specify the page that should be displayed on startup. E.g. StartupPage1 = MainMenu and StartupPage2 = Alarms.

Then when you run your project, the specified number of pages will be displayed, one on each monitor, and you can browse back and forth throughout the project independently on each monitor. Note that each window is a parent window, and therefore closing any one window will close the runtime down completely. You can implement different functionality by either modifying the templates or handing the shutdown event yourself. Any message boxes that appear will appear on the correct monitor. Super genies should appear in the correct locations, relative to the monitor on which they were opened (e.g. using AssPopUp), as long as they aren’t hard-coded to open at a defined (x, y) position.

You can now also use all the new CSV_MM_* and CSV_* Cicode functions as listed in Appendix A.

2.2 Scenario B – The manual way

You can still achieve multi-monitors in Citect without relying on the CSV_Include functionality, as long as you are prepared to do a little extra tweaking of the project to make everything work (involvement is project dependent). This effectively means you can run multi-monitors in any version of Citect. Note that you still need to be running in spanned (as opposed to extended) mode.

To open up multiple windows on multiple monitors at startup, simply include a call to WinNewAt(“APageName”, x, y) in your startup Cicode function, where x = the horizontal screen coordinate for the start of the next monitor, and y = 0. Note that in some versions of CitectSCADA, a bug is present where if either x or y is specified as 0, the new window gets displayed at (0, 0) on the left-most monitor. If you find this is the case, simply set the x or y argument to 1 instead of 0. This problem has been rectified in v6.00.

The main problem that results from using multi-monitors in this scenario is the positioning of message boxes and other popups, such as super-genies. These appear by default in the centre of the set of monitors, which means the centre of the middle screen if you have three monitors, or halfway across both screens if you have two monitors. The recommend solution to this is to create your own super-genie to fulfil the purpose of a generic message box, and position it manually (using WinNewAt for example) based on the current coordinates of the mouse at the time of invocation (using DspGetMouse for example). The mouse coordinates should be evaluated depending on the number and width of your screens to determine where to position the popup. Alternatively, you can use the WinNumber or WinGetFocus Cicode functions to determine the currently active window number, and use that to determine the best coordinates for the popup.

3. Runtime Issues

Following is a list of known runtime issues when working with mult-monitors. This list should be updated as new issues are discovered. Unfortunately some of these issues are yet to be resolved – they appear here simply as known problems.

3.1 All / new windows appear on the left-most monitor

This is by far the most common problem reported by customers. The first thing to check is whether you are running with spanned or extended mode (see section 1.2). Spanned mode is the only multi-monitors mode supported by Citect at this stage. If you are running in spanned mode, the next thing to do is step through section 2, above. If the instructions provided in section 2 are followed, this problem should not occur. Make sure [Page]DynamicSizing = 0. If it still is a problem, we will need to obtain a copy of the project and INI file, as well as information on version of CitectSCADA, the graphics hardware and operating system being used, and set up a test in-house.

3.2 Popups appearing on the wrong monitor

This occurs when the project is based on the standard templates, and does not occur when the project is based on the XP Style templates. The CSV_Include project contains extra logic (in CSV_Multimonitors.ci) to determine the placement of message boxes and other popups, such as super genies. When using a project based on the standard templates with multi-monitors, you will have to manually cater for all instances of popups. There is a fair amount of scope to do this here, for example, creating an alternative to the Message() cicode function and pops up a super genie with the message depending on the mouse coordinates. See section 2.2 for more information.

3.3 Popups / tooltips appearing split across two monitors

There are two issues here:

a) If the project is based on the standard templates, all child windows are by default sent to the centre of the screen, i.e. the midpoint of the two screens in a two monitor setup. See section 2.2 and 3.2 for the solution.

b) There is a known issue that occurs regardless of whether the project is based on the standard or XP Style templates: tooltips and other popups that rely on the current mouse-coordinates to position themselves do not take into account the split between the physical monitors. For example, if you bring up a tooltip at the very left of the left-most monitor, the tooltip is positioned to the right of the mouse so that is is completely displayed on the screen. If you bring up a tooltip at the very right of the right-most monitor, the tooltip is positioned to the left of the mouse for the same reason. However, currently no intelligent positioning is done to cater for the virtual screen edges as you go from monitor to monitor. The only workaround is to implement your own tooltip / popup control in a genie.

3.4 Effect of [Page]Startup and [MultiMonitors]StartPagex

The page defined in [Page]Startup is displayed first, then the pages defined in [MultiMonitors]StartPagex are displayed, effectively overwriting the former. Note that the [MultiMonitors] parameters are only recognised when running a project based on the XP Style templates.

3.5 Window is crossing onto the next monitor by a few pixels

This is a known issue and is visible whilst the graphics pages are initially displayed. It is caused by the window border making the page size a couple of pixels larger than the screen resolution. As long as [Animator]FullScreen=1, just before the next graphics page is displayed, the window border is removed (along with the titlebar), bringing back the overlap to what looks like about 1 pixel. The next window covers the overlap. This means all windows are effectively shortened width-wise by 1 pixel. There is no solution to this problem at present.

3.6 Template based AN numbers

AN numbers common to multiple pages, such as the reserved AN number 2 for the prompt field, do not behave as expected with multi-monitors. Doing a Prompt(“Hi”) from the kernel only goes to the prompt field of the last opened window, rather than all windows as expected. However, clicking the Login dropdown button in the CSV_Example project and logging in as ‘Engineer’ results in a prompt “Login Successful” always on the first opened window, regardless of which window the command was actually executed from.

3.7 Invalid Window prompt on startup

This appears only when using the [MultiMonitors] INI parameters (i.e. the project is based on the XP Style templates. Further investigation would be needed to determine the cause and whether it is of any importance. On the surface it doesn’t seem to impede any project functionality and can just be ignored.

Appendix A: Multi-monitor Cicode Functions

Historically, the multi-monitor functionality was first introduced into Citect Facilities v5.41. It was then merged into the CSV_Include project supplied with CitectSCADA v5.50. However, the help for v5.50 does not include documentation for any of the CSV_* Cicode functions (including those used for multi-monitors). Interestingly, the help for CitectSCADA v5.42 does contain documentation for some of the functions; but not all appear and the applicability of the documentation to the v5.50 implementation of the functions should not be assumed. The help for CitectSCADA v6.00 does include documentation on all the CSV_* functions, however again the applicability to the v5.50 implementation cannot be assumed. Therefore you are advised to use the v6.00 help (or refer to CSV_IncludeFunctions_v6.00r1.chm) as a guide, and where you get unexpected results, refer to the actual Cicode file (in the CSV_Include project folder) in which the function is defined, and use the function header and code comments as a guide to the correct usage.

Below is a list of CSV_* functions documented as implemented in CitectSCADA v5.50. Where possible, you should use these function in place of their standard versions when running with multi-monitors.