# IupOpen

Definition: | include pGUI.e IupOpen(nullable_string dll_root=NULL)
Description: | Initialise IUP
pwa/p2js: | Supported. (But any parameter is simply ignored.)
Comments: | This procedure must be called before creating any controls, etc. The optional dll_root, if provided, should be something like `C:\Program Files (x86)\Phix\demo\pGUI`, such that the appropriate win32/win64/lnx32/lnx64 subdirectory can be located. If you bundle a copy of pGUI.e and the appropriate dll/so subdirectory(ies) with your distribution, there should be no need to supply anything for dll_root. See also the technicalia. It may also be necessary to call IupControlsOpen() as well. However in all cases that I know of, pGUI takes care of that automatically, not that accidentally invoking it twice w/should cause any problems. See also IupClose, which should be called at the end of the program.
Ancilliary function: | (Windows only) sequence res = IupCheckVCRuntime(bool bCrash=true) has been factored out of IupOpen() for use in 'pw pdemo -settings' as run during installation: whereas IupOpen() displays a reasonable message and crashes, demo\pGUI\pdemo\installation.e attempts to download and initiate the needed Microsoft Visual C++ Redistributable Packages. It returns {} should nothing need to be downloaded and installed, and will crash if called on Linux or under p2js.
Example: |
    include pGUI.e

    IupOpen()
    Ihandle main_dialog = IupDialog(IupLabel("Hello","PADDING=80x10"),"TITLE=test")
    IupShow(main_dialog)
    if platform()!=JS then
        IupMainLoop()
        IupClose()
    end if
See Also: | IupClose, IupMainLoop
Technicalia | If dll_root is not provided, get_proper_dir(command_line()[2]) is used. In some setups it may be better to start from command_line()[1], assuming that locates pw.exe|p correctly, as follows. In cases such as Phix\pdemo.exw which includes Phix\demo\pGUI\pdemo.exw, some trickery is required for both pdemo.exw files to work. Slightly simpler, Phix\test\terror.exw needs to use ..\demo\pGUI, whereas Phix\demo\edix\edix.exw needs ..\pGUI. Refer to the above mentioned files (which may have changed since this documentation was written) for more details. For cross-platform operation, it may be better to use join_path({"..","pGUI"},1) instead of `..\pGUI\`. The value of dll_path may be a relative or absolute directory. While relative directories promise to be more portable (as in the app still works if moved to a different directory), personally I find absolute directories much easier to debug, especially on a remote machine, for instance ..\demo\pGUI looks fine, whereas C:\Program Files (x86)\Phix\demo\demo\pGUI (in an ex.err file) immediately pinpoints an error with surgical precision (ie that demo\demo\ should be just demo\). Hence my recommendation is an absolute directory, ideally manually constructed from a relative fragment, perhaps something like get_proper_path(“..\demo\pGUI”) [the literal forgiven as per the last point below]. It may also be worth noting that builtins\pGUI.e is a stub include that simply contains `include ..\demo\pGUI\pGUI.e`, and that most builtin functions and include statements usually work well enough with '\\' or '/' on any platform.