Open

Open opens a project screen or screen group on the thin client with some specified settings.

Syntax

Open(strScreenAndProperties, optNumX1, optNumY1, optNumX2, optNumY2, optNumResizeFlag, optNumID, optStrMnemonicList)

strScreenAndProperties

The name of the project screen or screen group to be opened. If opening a screen, the screen file extension (either .scc or .scr) is assumed, so you do not need to include it if you are opening an individual project screen. If you are opening a screen group, include the screen group file extension (.sg).

Note: If you have two screen files with the same name but different extensions in your project folder (for example, MyScreen.scc and MyScreen.scr), the one with the preferred extension — as determined by whether the Use .scr extension for screen files option in the project settings is selected — will be opened. For more information, see Viewer tab.

If you specify only the screen name, it will be opened with its default properties (as specified in Screen Attributes). You can configure the properties as follows:

Concatenate the screen name and the customized properties as a single string, using semicolons (;) to separate the properties in the string. For more information, see "Examples" below.

There is also a Clear Data property (ClearData) that applies only to screens opened in Mobile Access. When a screen is opened in Mobile Access, some of that screen's data is cached so that it can be quickly opened again. This is useful when certain screens are repeatedly closed and then reopened. However, if you see unexpected or unwanted behavior when you open a screen in this way, you may enable the Clear Data property (for example, ClearData: Enable) to clear the cached data and open the screen as if for the first time.

optNumX1,optNumY1,optNumX2,optNumY2

The coordinates, in pixels, for the top-left (X1,Y1) and bottom-right (X2,Y2) corners of the screen.

These parameters are optional; if no values are specified, the default screen size and position are used.

Please note the following special circumstances:

• You can open the screen at the mouse's current position by using Open("screen",1), or Open("screen",1,-1,-1,-1,…) if the parameters at the end are needed.

• If optNumX1 equals optNumX2 and optNumY1 equals optNumY2, the default screen size is used but the screen is centered at (X1,Y1).

• If optNumX2 is less than optNumX1 and/or optNumY2 is less than optNumY1, or if all four parameters are set to -1, the parameters are ignored and the default screen size and position are used.

  optNumResizeFlag

  Specifies whether objects in the screen will be resized when the screen is opened:

  Value	Description
  0	Screen objects will not be resized.
  1	Screen objects will be automatically resized to fit the new dimensions of the screen, as specified by the coordinates described above. The resizing is done at the moment the screen is opened, so if the user changes the screen size after the screen is opened, the objects will not be resized again.

  This parameter is required if all four coordinates (optNumX1, optNumY1, optNumX2, optNumY2) are specified.

  Note:

  By default, text associated with a screen object (for example, the caption on a Button object) is not resized along with the object. This might result in unexpected behavior during project run time, but it is done to prevent more serious issues that might result from automatically resizing fonts.

  If you want to automatically resize fonts, manually edit your project file (<project name>.APP) to add the following entry:

  [Desktop]

  ResizeFontWithScreen=1

  optNumID

  An ID or instance number to be assigned to the screen, because you can open multiple instances of the same screen file. (This ID is required when a screen is closed using the Close function.)

  This parameter is optional; if no value is specified, the default value is 0.

  optStrMnemonicList

  A string that describes how the custom properties (also known as mnemonics) of screen objects and linked symbols will be completed when the screen is opened. This string must have the following syntax…

  #Label:Value

  …where Label is the name of the custom property and Value is the tag, expression, or literal value that the property will receive. If Value is a tag or expression, it will be evaluated when this function is executed.

  You can declare more than one custom property as long as they are separated by spaces. You can also specify an external text file that contains the custom properties separated by either spaces or line returns. The file must have the .mne extension, and it must be located in the Web sub-folder of your project folder. If you want to save the file in a deeper sub-folder, you must specify a file path that is relative to the Web sub-folder. The file extension is assumed, so you do not need to include it in the file name.

  For more information about how to use this parameter, see "Examples" below. For more information about custom properties in general, see Use custom properties to set property values when screens are opened.

Return value

This function returns one of the following values:

The function only checks whether the parameters are valid, before it tries to use those parameters to open the screen. The function does not return any value to indicate whether the screen is successfully opened.

Notes

If the Enforce Web functionality equivalence in local project screens option is selected in the project settings, this function cannot be called in VBScript Global Procedures, VBScript scripts (script groups), or other background tasks. This is because the function behaves differently depending on whether you view project screens locally (that is, on the same computer that hosts the project runtime) or remotely. For more information, see Preferences tab.

There are three known issues with using this function on Mobile Access. (These issues also affect IoT View, because Mobile Access is the only thin client supported by IoT View.) First, most of the additional properties for the strScreenAndProperties parameter are not supported. Only the Clear Data property (ClearData) is supported, and it applies only to screens opened in Mobile Access. Second, if you use the optStrMnemonicList parameter to complete custom properties in the specified project screen, but the screen also contains some VBScript that tries to set the same custom properties, the conflict will cause a VBScript compilation error and the screen will not open. For example, if you make the following function call to open a project screen…

Open("Screen", -1, -1, -1, -1, 0, 0, "#Mne3:1")

…but the screen contains a Button object that has the following VBScript attached to it…

$#Mne3:=1234

…the VBScript will not compile and the screen will not open.

Third, the function will fail and return a 0 (Invalid parameters) if incorrect data types are passed to its parameters.

Examples

Open the screen using the default screen size, position, and ID:

Open("main")

Open the screen at the mouse's current position:

Open("main", 1)

Open the screen at the mouse's current position and assign it an ID of 10:

Open("main", 1, -1, -1, -1, 0, 10)

Open the screen using the default screen size but centered at the coordinates (500,250), do not resize the screen objects, and assign the screen an ID of 10:

Open("main", 500, 250, 500, 250, 0, 10)

Open the screen using the default screen size and position, use the default ID, and replace the custom properties Mne1 and Mne2 with Tag1 and Tag2, respectively:

Open("main", -1, -1, -1, -1, 0, 0, "#Mne1:Tag1 #Mne2:Tag2")

Open the screen using the default screen size and position, use the default ID, and replace the custom properties with values defined in the mnemonics file located at: <project name>\Web\mnemonic.mne

Open("main", -1, -1, -1, -1, 0, 0, "mnemonic")

Open the screen using the default screen size but centered at the coordinates (500,250), do not resize the screen objects, assign the screen an ID of 10, and replace the custom properties with values defined in the mnemonics file located at: <project name>\Web\mnemonic.mne

Open("main", 500, 250, 500, 250, 0, 10, "mnemonic")

Open the screen using the default screen size and position, assign it an ID of 2, and replace the custom properties with values defined in the mnemonics file located at: <project name>\Web\Mnemonics\mnemonic.mne

Open("main", -1, -1, -1, -1, 0, 2, "Mnemonics\mnemonic")

Open the screen using the default screen size and position, do not resize the screen objects, use the default ID, and customize the screen properties:

Open("main; EnableTitleBar: Enable; TitleBar: Main Screen; SystemMenu: Enable; Maximize: Disable; Minimize: Disable; Style: Popup; Border: Thin", -1, -1, -1, -1, 0, 0, "")

Open the screen in Mobile Access and clear any cached data so the screen is opened as if for the first time:

Open("main; ClearData: Enable")