You can change the appearance and behavior of the pages in your application. There are two levels of access to the characteristics of pages: at the developer's level, page characteristics are set using the Idea Studio and its associated tools. At the programmer's level, page characteristics can be set within a page's source file. Developer tools are described elsewhere in this guide.
The code for user-created widgets is very similar to that of page modules, and therefore much the following information also applies to them.
Where to find the code for your pages:
For each page, there is a resource file stored within your application in a folder named, "Pages". These are user-editable copies but note that any change must be imported into the application by an authorized user before it will become part of the running application. The file is named after the initial title of the page and have the extension ".SRC". Changes to the page title do not affect the name of the file.
The code of a page is a standard VTScada module
A collection of states, scripts, variables, parameters, comments and possibly other modules, all of which make up a VTScada program.
Modules are separate tasks that run simultaneously in an application. Behind every page is a module and behind every tag on that page is an instance of another module (usually with submodules controlling separate tasks)., following all the rules of the VTScada language. It may begin with an optional set of parameters.
( parmName <:"description text":> data_type; )
Following the parameters (if any) will be the variable declarations.
[ Title = "Overview"; Color = 89; ... ]
Most pages will have one state, named "Main" by default when the page is created within the VTScada development tools. Typically, this is the only state in a page.
Pages are called modules that return their object value. Therefore all states within the page that display the user interface must include a Return(Self); statement.
All graphic entities added to a page within the Idea Studio will use the GUI- functions (GUIPipe, GUITransform, etc.), but you are free to use Z- functions if you are adding objects using code.
The order of the graphical statements within the page's state determines their display order (later statements have a higher z-order than earlier statements) and also the tab-order for user-input elements.
Tags are drawn using widget code, placed within GUITransforms. The widget code controls the appearance (meter, topbar, slider, etc.). The GUITransform controls the scaling and location.
As with all graphics, pages have a reference box, defined either explicitly or implicitly. Unless otherwise specified, the reference box of a page matches the area of all objects drawn on that page using GUI-statements. Z-graphic objects don't count and will only be displayed inside the reference area. (The Z-graphic objects are an older technology that should rarely, if ever, be used in a modern application.)
Within the page code, each tag is referred to by its unique ID. This enables developers to rename tags at will without losing the associated graphic. If you copy the graphic, then paste it into an editor, VTScada will automatically look up the current name of the tag, and use that instead. (The absolute name will be used rather than the relative name, as indicated by the angle brackets.) Note that the result cannot be used in another page's source code; for that, copy from one .SRC file to another.
On Working With Page Code:
Do not edit a page's source code while simultaneously editing the page using the Idea Studio. Attempting to do so is likely to cause a conflict in the version control system.
To reduce the likelihood of a conflict, and to protect your source code, you can hide the page from the Idea Studio. Do so by adding the following line to the variable declaration section of your page:
CONSTANT HiddenPage = HPF_NOTINLISTS;
With this addition, your page can only be edited in code.
Standard Variables within a Page’s Source File
All of the page elements that are accessible from the page editing dialogs are stored in the page's source code file and can be modified there. Variables will not be present if not set. (Defaults are not stored in the source code file.)
The display title for the page. In a multilingual application, the value will be a phrase identifier key.
May also be set as an expression within the body of the page's main state.
Text to display as a tool-tip when the page has been added to the navigation bar.
Color
Alpha-RGB string setting the background color of the page.
Bitmap
Name of the image to use for the page background.
The NoStretch variable is associated with the ScaleDisplayContent configuration variable, both of which enable you to control scaling for the pages comprising your application. When set to a non-zero value, ScaleDisplayContent causes the graphics on all pages to scale to fit the dimensions of the window. ScaleDisplayContent affects all pages in an application, however, there may be selected pages to which you do not wish the scaling to apply. The NoStretch variable enables you to inhibit scaling for such pages. If NoStretch has a non-zero value, then the page will not be scaled regardless of the setting of the ScaleDisplayContent configuration variable.
Automated display scaling works reasonably well when enlarging the page. It cannot do as good a job when shrinking a display for a smaller screen. In particular, labels embedded within buttons or widgets are more likely to be truncated than scaled down.
Always design for the smallest screen that the application will be displayed upon. Further information is provided in Size Pages for Differing Screens
The PageWinOpt variable overrides the Style parameter options used for windowed pages. (Refer to the Window function for a description of the style parameter options.) Note that bits are counted from right to left and that examples you may see in pages often exclude the unset bits to the left of the highest numbered bit being set.
Refer also to Bitwise Parameters & Operations.
The PageX variable enables you to set the X coordinate for the top left corner of a windowed page. If PageX is not set for a windowed page, a default value is used.
The PageY variable enables you to set the Y coordinate for the top left corner of a windowed page. If PageY is not set for a windowed page, a default value is used.
The PageHeight variable overrides the normal PageHeight calculation for a windowed page (see the Window function for details). If not specified, the height is calculated from the page components.
As above, but for width.
Minimum number of pixels to use for the height when the page is displayed in its own window.
Minimum number of pixels to use for the width when the page is displayed in its own window.
Maximum width, in pixels, of a windowed page.
Maximum height, in pixels, of a windowed page.
A Boolean value (1 or 0) controlling whether a margin should be used when a windowed page displays an image.
Left margin to use when PageBMPMarginsWin is enabled.
Bottom margin to use when PageBMPMarginsWin is enabled.
Right margin to use when PageBMPMarginsWin is enabled.
Top margin to use when PageBMPMarginsWin is enabled.
If present and set to 1 (TRUE) the page will be ignored by any task that seeks to open a page where a tag has been drawn.
Note that the opposite may be true, where a developer wishes to add pages that might not normally be searched, to the cache of those that are. For this case, it is possible to create a hook to let an application provide a set of pages + parameters to be checked whenever a "Go To Page" operation (for a tag) is performed. This is useful for custom-coded applications that access pages through a means other than the page menu and page change widgets.
The callback module must be named "GetPagesForTagsHook" and must return an array of structures, each with three fields: Name, Parms, and Label. The array is limited to 10,000 entries.
The following structure may also be used:
\PageTagRefMgr.GetPagesForTagsHookPageInfo(--Name of the custom page--,
--array of parameters needed by the page--,
--the page label--);
Display Manager Bit Flags for Page Display
In addition to the modifiable variables within a page’s source file, the Display Manager defines and uses a set of bit flags that determine how a VTScada page is displayed.
Constant PSTTB = 0x0001 { Page Style - Show Title Bar };
Constant PSBMP = 0x0002 { Page Style - Show Title Bar Bitmap };
Constant PSLGN = 0x0004 { Page Style - Show Title Bar Logon Button };
Constant PSCFG = 0x0008 { Page Style - Show Title Bar Configure Button };
Constant PSDTE = 0x0010 { Page Style - Show Title Bar Date & Time };
Constant PSIND = 0x0020 { Page Style - Show Title Bar Alarm indicators };
Constant PSTTT = 0x00FF { Page Style - Show all Title Bar decorations };
Constant PSMBR = 0x0100 { Page Style - Show Task Bar };
Constant PSMNU = 0x0200 { Page Style - Show Menu Button and Menu };
Constant PSMPB = 0x0400 { Page Style - Show Task bar Page buttons };
Constant PSMFB = 0x0800 { Page Style - Show Task bar "<" and ">" buttons};
Constant PSMPM = 0x1000 { Page Style - Show Task bar "+" and "-" buttons};
Constant PSMHD = 0x2000 { Page Style - Hold page btn changes target };
Constant PSMMM = 0xFF00 { Page Style - Show all Menu Bar decorations };
There is a public variable, PageStyle, defined in the Graphics module in each session, which is an OR of the style bits that apply to a page. The initial setting is PSMMM + PSTTT, which is all decorations.
The address of the PageStyle variable is passed as a parameter to the MenuBar and TitleBar plug-ins.
Although PageStyle is public (because the MenuBar and TitleBar plug-ins need to see it) setting its value directly is ineffective because it is reset with each page change.
Whenever a new page is displayed, PageStyle is set as follows (in priority order)…
Normal page:
- Default value of a PageStyle variable in the page.
- The value of DefaultPageStyle.
Windowed page:
- Default value of a PageWStyle variable in the page.
- The values supplied in parameter 4 of the Display Manager method, ShowStyledPage.
- The value of DefaultPageStyle.
DefaultPageStyle defaults to the value that shows all decorations. This can be overridden by the configuration settings \DispMgrWPageStyle and \DispMgrPageStyle, or by parameter three of the DisplayManager method ShowStyledPage.
For example, to disable in all pages, the feature whereby a navigation bar button changes if you hold it down for more than 1.5 seconds, you have to set the configuration variable \DispMgrPageStyle to the value 0xFDFF (you cannot use the constant values defined in DisplayManager).
Application properties for pages
- DispMgrPageStyle - For all normal pages
- DispMgrWPageStyle - For windowed pages
(Please refer to Application Properties for the Display Manager for further information on these and other modifiable variables.)
For Custom pages you can use code similar to the following example to offset the top and bottom of the page in the Display Manager:
TopOffset = PickValid(And(Caller(Self())\PageStyle, \DisplayManager\PSTTB), 0) ?
\DisplayManager\Task_Height : 0;BottomOffset = PickValid(And(Caller(Self())\PageStyle, \DisplayManager\PSMBR), 0) ?
\DisplayManager\Menu_Height : 0;
