Opening a window

Opening a window in Emergence BASIC is easily done with the OPENWINDOW function. When you use EBASIC to write Windows based software your program becomes event driven. Every action a user takes when running your program is sent to a special subroutine as a message. Your program must then decide whether or not to respond to this message. A message is really just a number. This number represents an action taken by the user.

handler - The address of a subroutine to handle messages for the window. Use the & operator.

The OPENWINDOW command will return 1 if the window was created successfully or 0 if the window could not be created. You can also check the window variable to see if it equals 0. If so then the window could not be opened.

REM define a window variable
DEF w1 as WINDOW
REM open the window
OPENWINDOW w1,0,0,350,350,@MINBOX|@MAXBOX|@SIZE,NULL,"Simple Window",&main
REM print a message
PRINT w1,"Hello World"
REM when w1 = 0 the window has been closed
WAITUNTIL w1 = 0
END

REM every time there is a message for our window
REM the operating system will GOSUB here
SUB main
    IF @MESSAGE = @IDCLOSEWINDOW
        REM closes the window and sets w1 = 0
        CLOSEWINDOW w1
    ENDIF
RETURN
ENDSUB

The example shows the steps necessary to open a window and wait for a message. Windows will call your handler subroutine anytime there is a message for the window you created.

The previous example also introduces the ‘@’ symbol. Emergence BASIC defines a number of constants for use in your program. Special variables contain information about the message sent to a window. In either case the ‘@’ symbol is used to differentiate these names from variables you define in your program. System variables like @MESSAGE are set by EBASIC and cannot be used as normal variables. You can define your own constants with the SETID statement.

In the above example we used @SIZE in the flags parameter. This tells EBASIC that the window should be resizable. More than one flag can be used and combined with the '|' symbol (meaning OR). EBASIC contains many predefined flags:

NAME	PURPOSE/STYLE
@SIZE	Creates a window that is resizable
@MINBOX	The window has a minimize box
@MAXBOX	The window has a maximize box
@MINIMIZED	Creates a window that is initially minimized
@MAXIMIZED	Creates a window that is initially maximized
@CAPTION	Default. Creates a window with a caption
@NOCAPTION	Creates a window with no caption
@SYSMENU	Default. Creates a standard system menu
@BORDER	Creates a bordered window. Use with the @NOCAPTION flag
@HSCROLL	Window has a horizontal scroll bar
@VSCROLL	Window has a vertical scroll bar
@MDIFRAME	Creates a frame window that can contain child client windows.
@USEDEFAULT	Child windows can use this for the 'left' parameter to let windows pick a default size for the window
@TOOLWINDOW	Creates a window with a half sized caption.
@NOAUTODRAW	Allows your program to handle @IDPAINT messages
@TOPMOST	Creates a window that stays on top of all others. Cannot be used with MDI child windows.
@AUTOSCALE	Creates a window that scales the contents automatically
@FIXEDSIZE	Use to create an autodrawn window that will remain the same size throughout the life of the window.
@HIDDEN	Creates a window that is initially hidden.

In the previous example, we introduced a few new ideas. The WAITUNTIL command tells EBASIC to process messages until a condition is true. The WAITUNTIL command sleeps until something is done with one of the windows your program is using. When a message is sent to your window, the handler subroutine is called that was defined when the window was opened. After your subroutine executes a RETURN statement, your program will continue waiting for messages. In our example, we check the value of the variable ‘w1’ to see of we should wait for more messages or end the program. The syntax of WAITUNTIL is:

Emergence BASIC also contains another statement for processing messages. The WAIT statement can be used when more control over message processing is desired. WAIT processes any messages that are available for your window, sleeps if none are available, and then returns. The syntax of WAIT is:

If the optional NoSleep parameter is set to 1 then the WAIT command will check for messages and return immediately. WAIT will be covered in more detail in the Messages and Message loops section

When your windows handler subroutine is called, the system variable @MESSAGE will contain the message ID. This variable can then be compared against any of the messages you wish to handle using an IF or SELECT statement. Some messages contain additional information and set @WPARAM and @LPARAM accordingly. A good example of this is information from the keyboard. When a key is pressed your window will receive, among others, the message @IDCHAR. In this case @WPARAM will contain the ASCII value of the key.

For backwards compatibility with other languages you can use @CLASS, @CODE and @QUAL in place of @MESSAGE, @WPARAM and @LPARAM respectively.

SUB mywin
SELECT @MESSAGE
            CASE @IDCHAR
                        Key = @WPARAM
            CASE @IDCLOSEWINDOW
                        run = 0
ENDSELECT
RETURN
ENDSUB

When developing your handler subroutine you can handle as many or as few messages as you need. Any messages that you do not respond to are simply 'thrown away' by the system. At a minimum you should check for @IDCLOSEWINDOW to handle the close button of the window.

If a particular message requires a return value you can specify it in the RETURN statement.