|
Purpose |
WINMAIN (or its synonym MAIN) is a user-defined function called by Windows to begin execution of an application. |
|
Syntax |
FUNCTION {WINMAIN | MAIN} ( _ BYVAL hInstance AS DWORD, _ BYVAL hPrevInst AS DWORD, _ BYVAL lpszCmdLine AS ASCIIZ PTR, _ BYVAL nCmdShow AS LONG ) AS LONG |
|
Remarks |
The WINMAIN function is called by Windows when an executable application first loads and begins to run. It is often referred to as the "entry point" for the application. When the execution of WINMAIN is completed, the application is deemed to be finished, and Windows releases the application memory back to the heap. WINMAIN receives the following parameters: |
|
hInstance |
The executable's (EXE) instance handle. Each instance of a Windows application has a unique handle. It is used as a parameter to a number of Windows API functions which may need to distinguish between multiple instances of an application. |
|
hPrevInst |
Not used by 32-bit Windows. It is present merely for compatibility with existing 16-bit code, and always returns zero in 32-bit applications. |
|
lpszCmdLine |
A pointer to an ASCIIZ string that contains a command-line. Note that the string passed in lpszCmdLine is not the same as the string returned by the GetCommandLine API call. The string in lpszCmdLine contains the command-line arguments only (like COMMAND$), but GetCommandLine returns the program name (including path) followed by the arguments. |
|
nCmdShow |
Specifies how to display the application's main window. For example, the calling application can specify %SW_NORMAL or %SW_MINIMIZE, etc. It is up to the programmer to honor this parameter, and to do so is recommended. |
|
Return |
The return value assigned to WINMAIN is optional, but by convention, the return value is derived from the wParam& parameter of a %WM_QUIT message. Typically, a GUI-based application uses the WINMAIN function to create the initial GUI application window, and then enters a message loop. This loop should terminate when a %WM_QUIT message is received, and the wParam& parameter of that message should be passed on as the return value for WINMAIN. If WINMAIN terminates before entering the message loop, WINMAIN should return zero. Console applications may use the return value to set an error level that can be passed back to the calling application, in the range 0 to 255 inclusive. Batch files may act on the result through the IF [NOT] ERRORLEVEL batch command. If the parameters passed to WINMAIN are not required by the application itself, the PBMAIN function may be used in place of WINMAIN. |
|
Restrictions |
Pointers may not be passed BYREF, so the lpszCmdLine parameter of WINMAIN must be declared to be passed BYVAL. |
|
See also |
|
|
Example |
#COMPILE EXE FUNCTION WINMAIN(BYVAL hInst???, BYVAL hPrevInst???, BYVAL pCmdLine AS ASCIIZ PTR, BYVAL nCmdShow&) AS LONG ... FUNCTION = 1 END FUNCTION |