DEFINE A MODAL WINDOW
Creates a MODAL Window Definition
Description:
A Window definition creates a Windows Graphics User Interface (GUI) Window object. This is a system of interactive visual components used by computer programs to display information and allow interaction with users of the computer program
A MODAL Window is defined in an HMG program and contains visual functionality and processing that needs the attention of the user before processing in it's "parent" Window can continue. A MODAL Window always stays 'topmost' over the Window that has called it and the user is unable to return to that Window, or any other Window in the program, until such time as the MODAL Window has been responded too, released or closed by the user. The standard HMG messaging functions such as MsgInfo() are created as MODAL Windows
Syntax:
DEFINE WINDOW <cWindowName>
[ ROW <nRow> ]
[ COL <nRow> ]
[ WIDTH <nWidth> ]
[ HEIGHT <nHeight> ]
[ VIRTUALWIDTH <nVirtualWidth> ]
[ VIRTUALHEIGHT <nVirtualHeight> ]
[ TITLE <cTitle> ]
[ ICON <cIconName> ]
WINDOWTYPE MODAL
[ FONTNAME <cFontName> ]
[ FONTSIZE <nFontSize> ]
[ BACKCOLOR <anBackColour> ]
[ SIZABLE <lValue> ]
[ SYSMENU <lValue> ]
[ TITLEBAR <lValue> ]
[ CURSOR <lValue> ]
[ VISIBLE <lValue> ]
[ AUTORELEASE <lValue> ]
[ ONINIT <ProcName | bBlock> ]
[ ONRELEASE <ProcName | bBlock> ]
[ ONINTERACTIVECLOSE <ProcName | bBlock> ]
[ ONMOUSECLICK <ProcName | bBlock> ]
[ ONMOUSEDRAG <ProcName | bBlock> ]
[ ONMOUSEMOVE <ProcName | bBlock> ]
[ ONSIZE <ProcName | bBlock> ]
[ ONPAINT <ProcName | bBlock> ]
[ ONGOTFOCUS <ProcName | bBlock> ]
[ ONLOSTFOCUS <ProcName | bBlock> ]
[ ONSCROLLUP <ProcName | bBlock> ]
[ ONSCROLLDOWN <ProcName | bBlock> ]
[ ONSCROLLLEFT <ProcName | bBlock> ]
[ ONSCROLLRIGHT <ProcName | bBlock> ]
[ ONHSCROLLBOX <ProcName | bBlock> ]
[ ONVSCROLLBOX <ProcName | bBlock> ]
[ HELPBUTTON <lValue> ]
[ SHORTTITLEBAR ]
[ ... Other Control Definitions (eg. LABEL) ... ]
END WINDOW
Notes:
The order in which properties are declared before and after the WINDOWTYPE MODAL declaration is important. If any of the properties available for this type of Window are used, they should be declared before or after declaring WINDOWTYPE MODAL as per the order shown in the Syntax section above or the program may fail to compile (build)
ROW, COL, WIDTH and HEIGHT. If any of these properties is not specified during the Window defnition a default value is used;
ROW and/or COL - Both default to a value of 0
WIDTH and/or HEIGHT - These will be set to the maximum width and/or height of the primary display screen
The MODAL style of Window is best suited to being used purely to display warnings, errors or questions that require the attention of the user to ensure processing can continue
Note that the VISIBLE property is ignored when defining a MODAL Window. A number of approaches have been tested and none prevents the from being displayed on screen immediately after it is activated
When declaring a MODAL Window, you cannot use the MAXBUTTON or MINBUTTON Properties and cannot declare any ONMAXIMIZE or ONMINIMIZE Window Events; doing so will result in an error when building the program
However, the MAXIMIZE and MINIMIZE Methods can be used and both the ISMAXIMIZED and ISMINIMIZED Properties also become available. Using these is not recommended as testing of these resulted in some instability after the RESTORE Method is used to restore the Window to its original size!
Similarly, both the NOMAXIMIZE and NOMINIMIZE Properties are available for use. During testing, no issues were found when changing these values but it would appear that the original design of a MODAL Window excluded the ability to maximize or minimize the Window. Therefore, it is not recommended that you change these values
If you intend to use a TOOLBAR, do not create a MODAL Window that is virtually dimensioned with VIRTUALWIDTH or VIRTUALHEIGHT. The program will compile and appear to run until you attempt to use the virtual dimension controls at which point it will crash with a fatal error
VIRTUALWIDTH and VIRTUALHEIGHT. The values for these properties must be greater than the values set for their respective WIDTH and HEIGHT properties
AUTORELEASE. When this property is used with a value of true (.T.), the window is hidden rather than released from memory when the window is closed
SHORTTITLEBAR. This property is only available for use with a MODAL Window. It changes the appearance of the Titlebar by reducing it's size a little and by using a Close box that is different from the standard Windows Close box
ACTIVATE WINDOW ALL. If this command is used at program start-up, then all windows apart from MAIN will automatically have AUTORELEASE set to true (.T.)
If the HIDE Method is used to hide a Window from the screen, the Program becomes a Background Process under Windows Task Manager. Any processing that is running continues as normal. Once the Program is made visible again using the SHOW Method, it returns to Apps section of Windows Task Manager
VSCROLLBAR and HSCROLLBAR. These are pre-defined controls that are "built in" when a virtually dimensioned Window is declared that includes the capability to scroll vertically and/or horizontally
The original version of the help file for this item can be viewed here
Window Properties:
The following Window Properties are available to use when defining the MODAL Window
Name | Data Type | Control | Description |
---|---|---|---|
ROW | Numeric | D, R, W | Sets the row number on the screen to place the top edge of Window |
COL | Numeric | D, R, W | Sets the column number on the screen to place the left edge of Window |
WIDTH | Numeric | D, R, W | Sets the width of the Window |
HEIGHT | Numeric | D, R, W | Sets the height of the Window |
VIRTUALWIDTH | Numeric | D | Sets the virtual width of the Window |
VIRTUALHEIGHT | Numeric | D | Sets the virtual height of the Window |
TITLE | Character | D, R, W | Sets the title to display in the title bar of the Window |
ICON | Character | D | Specifies the file name of the icon to display on the title bar of the Window and on the Windows taskbar |
WINDOWTYPE | N/A | D | Defines which style of Window to create |
FONTNAME | Character | D | Sets the default font to use on any Window elements and any controls that don't have their own specific FONTNAME defined |
FONTSIZE | Numeric | D | Sets the default font size to use on any Window elements and any controls that don't have their own specific FONTSIZE defined |
BACKCOLOR | Character | D | Sets the background colour to display in the client work area of the Window |
SIZABLE | Logical | D | Specifies if the Window can or cannot be resized by the user |
SYSMENU | Logical | D | Specifies if the Window should include a system menu on the title bar |
TITLEBAR | Logical | D | Specifies if the Window should include a titlebar at the top of the window |
CURSOR | Character | D | Specifies the file name of the mouse cursor to use with the Window |
VISIBLE | Logical | D | Defines if the Window should be visible when activated or remain hidden |
AUTORELEASE | Logical | D | Specifies if the Window should be released from memory when closed or be hidden and have its definition retained in memory |
HELPBUTTON | Logical | D | Specifies if the Window should include a helpbutton on the title bar |
SHORTTITLEBAR | N/A | Nil | Changes the appearance of the Windows title bar |
Each of the following Window Properties are available after the MODAL Window has been defined
Name | Data Type | Control | Description |
---|---|---|---|
FOCUSEDCONTROL | Character | R | Gets the name of the control that is currently in focus within a Window |
NAME | Character | R | Returns the name defined for the Window |
HANDLE | Numeric | R | Returns the operating system Window handle number |
INDEX | Numeric | R | Returns the program's Window index number. Please refer to notes in the associated Help documentation |
ISMAXIMIZED | Logical | R | Returns a logical value indicating if the Window is or is not maximized |
ISMINIMIZED | Logical | R | Returns a logical value indicating if the Window is or is not minimized |
CLIENTAREAHEIGHT | Numeric | R | Returns a numeric value indicating of height of the work area within the Window |
CLIENTAREAWIDTH | Numeric | R | Returns a numeric value indicating of width of the work area within the Window |
NOCAPTION | Logical | R, W | Enables and disables the Window Titlebar. Please refer to notes in the associated Help documentation |
NOCLOSE | Logical | R, W | Enables and disables the capability to close the Window. Please refer to notes in the associated Help documentation |
NOMAXIMIZE | Logical | R, W | Enables and disables the capability to maximize the Window. Please refer to notes in the associated Help documentation |
NOMINIMIZE | Logical | R, W | Enables and disables the capability to minimize the Window. Please refer to notes in the associated Help documentation |
NOSIZE | Logical | R, W | Enables and disables the capability to re-size the Window. Please refer to notes in the associated Help documentation |
NOSYSMENU | Logical | R, W | Enables and disabless the Window System Menu. Please refer to notes in the associated Help documentation |
ENABLED | Logical | R, W | Enables and disables the Window |
HSCROLL | Logical | R, W | Enables and disables the Horizontal Scroll Bar Control on a virtually dimensioned Window |
VSCROLL | Logical | R, W | Enables and disables the Vertical Scroll Bar Control on a virtually dimensioned Window |
ALPHABLENDTRANSPARENT | Numeric | W | Sets the level of transparency of a Window |
BACKCOLORTRANSPARENT | Array | W | Sets the Window's background transparency colour |
D - Properties of this type can be used when defining a Window
R - Properties of this type can only be accessed (read) after the Window has been defined
W - Properties of this type can be changed (write) after the Window has been defined
See GETPROPERTY and SETPROPERTY functions for further infomation on accessing or changing properties or use semi-OOP syntax
Windows Event Properties:
Each of the following Windows Event Properties are available to use when defining the MODAL Window. When used, they contain the name of a procedure to run or a code block to evaluate if that event occurs;
Event | Description |
---|---|
ONINIT | Runs once when the Window is initialised by the ACTIVATE WINDOW <FormName> command |
ONRELEASE | Runs once before the Window is released from memory when the Window is closed by the RELEASE method or when it is closed by any other means |
ONINTERACTIVECLOSE | Runs once before the Window is released from memory when the Window is closed using by any means other than with the Window RELEASE Method |
ONMOUSECLICK | Runs whenever the left mouse button is clicked in any free space in the client work area (ie. not when over a Control) |
ONMOUSEDRAG | Runs for every movement of the mouse pointer when the left mouse button is clicked, held and dragged in any free space in the client work area (ie. not when over a Control) |
ONMOUSEMOVE | Runs for every movement of the mouse pointer within any free space in the client work area (ie. not when over a Control). This includes when the Window is not actually in focus |
ONSIZE | Runs for every change in the Window size when using the mouse to click and drag to re-size the Window |
ONPAINT | Should execute when the Window is painted. Testing shows erratic and unpredictable behaviour! Activates on EVERY paint (label, text ANYTHING) |
ONGOTFOCUS | Runs each time the program Window gains focus |
ONLOSTFOCUS | Runs each time the program Window loses focus |
ONSCROLLUP | Runs once for every click on the vertical scroll up arrow |
ONSCROLLDOWN | Runs once for every click on the vertical scroll down arrow |
ONSCROLLLEFT | Runs once for every click on the horizontal scroll left arrow |
ONSCROLLRIGHT | Runs once for every click on the horizontal scroll right arrow |
ONHSCROLLBOX | Runs once for each click within horizontal scroll box or once after dragging and releasing the horizontal scroll box. Menu appears when right mouse button clicked. |
ONVSCROLLBOX | Runs once for each click within vertical scroll box or once after dragging and releasing the vertial scroll box. Menu appears when right mouse button clicked. |
Windows Methods:
Each of the following Methods can be used to perform an action that accesses, changes or modifies the Window;
Method | Description |
---|---|
CAPTURE | Captures a screenshot of the Window as a bitmap file (.BMP) which can be saved |
Prints a screenshot of the Window | |
SHOW | Makes the Window visible on screen after activation. See Note 13, above |
HIDE | Hides a Window from the screen after activation. See Note 13, above |
CENTER | Centers the Window on the desktop screen |
MAXIMIZE | Maximises the Window to take up the entire desktop screen. Using this Method with a MODAL Window is not recommended |
MINIMIZE | Minimises the Window from the desktop screen to the task bar. Using this Method with a MODAL Window is not recommended |
ACTIVATE | Activates a Window after definition and places it in memory |
RESTORE | Restores a Window to its previous size and position when it has been maximized or minimized. Using this Method with a MODAL Window is not recommended |
RELEASE | Releases a Window after activation and removes it from memory |
SETFOCUS | Sets focus onto the Window |
REDRAW | Redraws the Window? |
CENTERWORKAREA | Centers the Window on the desktop screen. WinName.CENTERWORKAREA does not compile! |
CENTERIN(<FormName2>) | Centers the Window over another Window's position on the desktop screen |
Windows Commands:
Each of the following Window Commands can be used to perform an action with or on the Window;
Command | Description |
---|---|
ACTIVATE WINDOW <FormName> | ALL | Activates the defined Window and all Controls associated with that Window |
CENTER WINDOW <FormName> [ DESKTOP ] | Centers a Window when it is displayed (shown) on screen |
CENTER WINDOW <FormName1> IN <FormName2> | Centers a Window over another Window when it is displayed (shown) on screen |
SET WINDOW <FormName> TRANSPARENT ... | Sets the level of a Window's transparency when it is displayed on screen |
FLASH WINDOW <FormName> ... | Flashes visible components of the Window to attract the users attention |
ANIMATE WINDOW <FormName> ... | Animates a Window when it is displayed (shown) on screen |