DialogInitPos

(System Library)

Description: Attempts to position a dialog so that it is not started beyond the left, right, top, or bottom of the visible screen.
Returns: Nothing
Usage: Script Only.
Function Groups: Graphics
Related to:  
Format: System.DialogInitPos(XPosPtr, YPosPtr [, XOffset, YOffset, Width, Height, SuppressCentering, WinOptions, RefWindow])
Parameters:  
XPosPtr   
Required. A pointer to the dialog's X-position. The X-position will be modified by this function if the dialog is beyond the left or right edge of the screen.
YPosPtr   
Required. A pointer to the dialog's Y-position variable. The Y-position will be modified by this function if the dialog is beyond the top or bottom edge of the screen.
XOffset  
Optional. Any numeric expression giving the default X-position to use if the value of the XPosPtr is Invalid. It is also the X-position that will be used if the dialog is beyond the right edge of the screen and Width is Invalid. Default is 0.
YOffset  
Optional. Any numeric expression giving the default Y-position to use if the value of the YPosPtr is Invalid. It is also the Y-position that will be used if the dialog is beyond the bottom edge of the screen and Height is Invalid. Default is 0.
Width   
Optional. Any numeric expression giving the width of the dialog.
Height   
Optional. Any numeric expression giving the height of the dialog.
SuppressCentering
Optional Boolean. If TRUE, this function won't center off-screen windows, instead shifting windows on-screen. Note that when this is true and *pXPosition and *pYPosition are valid, then XOffset and YOffset are not used because VTScada will always shift the positions given in the pointers on-screen rather than falling back on XOffset/YOffset.
WinOptions

Optional structure, defined as follows:

Struct [
    BorderWidth    { Width of left or right border (each), if any  };
    BorderHeight   { Height of top or bottom border (each) , if any};
    TitleBarHeight { Height of titlebar (not including top
                     BorderHeight), if any                         };
  ]; 

Defaults to a window with a titlebar and thick borders

RefWindow
Optional Window object. If provided, and if the values of pXPosition and pYPosition are not preset or would cause the dialog to appear outside of the screen, the module will try to center the dialog to this window instead of the screen.
Comments: This module is a member of the System Library, and must therefore be prefaced by \System. as shown in the "Format" section. If your application predates version 11.2, use the backslash notation rather than dot: \System\

XPosPtr and YPosPtr are absolute coordinate positions of the Windows desktop.

XOffset and YOffset are suggested to be used for calculating the new coordinates for the top left corner, and are relative to the current monitor. If they are left invalid, they will be calculated to attempt to center the window on the current monitor.

Width and Height are used to help center the window on the current monitor. If they are invalid, they are assumed to be one third the size of the current monitor.

AllowVirtualDisplay - This setting can be added to SETUP.INI and set to 1 in order to force the DialogInitPos constraint rectangle to be the entire virtual display, i.e. the Windows desktop.

Calling this function before starting a Window() call will reposition a dialog's starting position so it will not be drawn entirely off-screen. This is only necessary if the dialog's X- or Y-coordinates are retained. The width and height of the dialog are optional. If provided, the dialog will be prevented from being drawn partially beyond the bottom/right edge of the screen. Otherwise only the top/left corner of the dialog will be guaranteed to be drawn on-screen. There is no return value.

Example:

[
  Width                       { Dialog width                                };
  Height                      { Dialog height                               };
  Retained XPos               { Window X Location                           };
  Retained YPos               { Window Y Location                           };
...
]
Init [ If 1 Main;
  [
  ...
    Width =  { calculation or constant to set width  };
    Height = { calculation or constant to set height };
 
       { Determine the X and Y position of the dialog }
    \System\DialogInitPos(&XPos, &YPos, 100, 100, Width, Height);
  ]
]