Open

The function Open opens a project screen on the client with some specified settings.

Function Group Execution Windows Embedded Thin Client Mobile Access
Open Screen Asynchronous Supported Supported Supported Supported (see “Notes” below)

Syntax

  Open(strScreenAndProperties,optNumX1,optNumY1,optNumX2,optNumY2,optNumResizeFlag,optNumID,optStrMnemonicList)  
Web Studio Help opics2ffunctions screen open.xml d414595e120 Open

strScreenAndProperties
The name of the screen to be opened. (The screen file extension *.SCR is assumed, so you do not need to include it.)
If you specify only the screen name, then it will be opened with its default properties (as specified in Screen Attributes). You can, however, customize the properties as follows:
Property Syntax
Title Bar EnableTitleBar: Enable | Disable; TitleBar: title
System Menu SystemMenu: Enable | Disable
Maximize Box Maximize: Enable | Disable
Minimize Box Minimize: Enable | Disable
Style Style: Overlapped | Popup | Replace(Partial) | Dialog | Replace(Complete)
Border Border: None | Thin | Resizing

For more information, see “Examples” below.

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

These are optional parameters. If no values are specified, then the default screen size and location 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, then 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, then the parameters are ignored and the default screen size and location 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, then the objects will not be resized again.

This parameter is required if all four coordinates are specified.

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 function Close.)

This is an optional parameter. If no value is specified, then the default ID is 0.

optStrMnemonicList
A string that describes how the custom properties of any generic objects or linked symbols in the screen will be completed when the screen is opened. This string has the following syntax…
  #Label:Value  

…where Label is the name of the property and Value is the tag, expression, or literal value that the property will receive. You can declare more than one mnemonic as long as the mnemonics are separated by spaces.

You can also specify a external text file that contains the mnemonics separated by either spaces or line returns. The file must have the extension *.MNE, and it must be saved in the Web sub-folder of your project folder. Please note that the file extension is assumed, so you do not need to include it in parameter, and if you want to save the file in a deeper sub-folder, then you need to specify a file path relative to the Web sub-folder.

Note: Mnemonics are not supported when opening project screens in Mobile Access.

For more information, see “Examples” below.

Returned value

This function will return one of the following possible values:
Value Description
0 Failure
1 Success

Notes

If the option Enforce Web functionality equivalence is selected in the project settings, this function cannot be called from Global Procedures or Script worksheets. This is because the function is meaningful only when it is executed on stations that display project screens; it might cause unexpected behavior if it is called from background tasks that are executed on the project runtime server. For more information, see Preferences tab.

The following limitations also apply to how the function can be used in project screens in Mobile Access:
  • The function cannot be called from the sub-routine Screen_OnClose in the Screen Script; and
  • You should avoid creating a script that both shows a dialog box (e.g., a message box that is shown using the VBScript function MsgBox or the IWS built-in function ShowMessageBox) and opens or closes a screen. The Mobile Access web interface can display only one screen at a time, and opening a new screen will automatically close the previous one. Depending on the order of execution, this can lead to unexpected behavior such as a dialog box being orphaned or not being shown at all.

Examples

Open the screen using the default screen size, location, 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 location, 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 location, use the default ID, and replace the custom properties with values defined in the mnemonics file located at: projectnameWebmnemonic.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: projectnameWebmnemonic.mne
  Open("main",500,250,500,250,0,10,"mnemonic")  
Open the screen using the default screen size and location, assign it an ID of 2, and replace the custom properties with values defined in the mnemonics file located at: projectnameWebMnemonicsmnemonic.mne
  Open("main",−1,−1,−1,−1,0,2,"Mnemonicsmnemonic")  
Open the screen using the default screen size and location, 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