# Win32 Tutorial Lesson 3

As promised we are going to play around with Windows controls. But as I think I have been a little too theoretical, I will put in more practice examples from now on. I'm sorry for the people that want to dive deeper into the 'guts'of Windows programming, but for the moment my aim will be to develop a quite simple application, building up slowly step by step.

The application I have in mind will be an 'address manager', to build a sort of database of your friends names (someone once said to me: "If you are serious about programming a database of your friends, in the end you will have a database, but no friends to put into it"). The program should be able to add, change, delete data and sort them in different ways. But, as said before, the main aim of developing it will be 'educational'.

So, the first item I concentrate upon will be: message_box(). 'But that's not in Cuny's library!', I hear you say. No, that's right, but it comes standard with Euphoria!

Look at the msgbox.e file in the include directory. This could give you some insight into using the API functions, and you don't have to write event handlers or build controls for it. This time all this is already done for you! Just type in this little demo program: ( all the lines starting with -- are optional comments. )

-- messagebox1.exw

    -- a message_box demo program.

    include msgbox.e
    -- ^^ any program code which is in the Euphoria "include" folder, or is in
    -- a separate file outside of your main program must be pointed to by this
    -- command.

    integer result
    -- ^^ all variables and constants must be declared as to TYPE before
    -- actually using them.

    result = message_box("Got the message?", "", 0)
    -- ^^ This is an example of a FUNCTION, which is  code that executes and
    -- returns a value. ( the value is not actually used here, though! )

    -- end of messagebox1.exw

That's all! If you run it, the message box will appear with only an 'OK' button, like this.

But of course there's more that can be done with it. Look at the function. It has three parameters: a sequence holding the message, a sequence for the caption ( title ) of the box and an object for the 'box style'. And it returns an integer that can be used by the rest of your application.

The box style is an object variable; it can hold an atom, for instance '0' for the default behavior, but it can also hold a sequence of atoms, that get or-ed together and represent different styles.
The 'result' variable can have a value from 0 to 7, the meaning of the values is listed in the msgbox.e file.
As homework to experiment with, I give you messagebox2.exw:

-- messagebox2.exw

    include msgbox.e

    integer result
    sequence text

    result = message_box("Got the message?", "messagebox2 demo",
                         {MB_YESNO, MB_ICONQUESTION})

    if result = IDYES then
    -- ^^ an if statement tests an expression to see if it is 0 (false) or
    -- non-zero (true) and then executes the appropriate series of statements.

        text = "You got the message!"
    elsif result = IDNO then
        text = "Haven't you got the message?"
    else
        -- this should never happen.
        text = "What have you been doing?"
    end if

    result = message_box(text, "Message Confirmation", MB_ICONINFORMATION)
    -- end of messagebox2.exw

..and you will get an opening screen like this.

..remember, you will have to select this second demo manually in the OPEN dialog box to run it.

A 'note' about msgbox.e .

Perhaps only of historical interest, but here it is! I hope addendums like this do not confuse new users too much.

...I've got memory leaks, ...what in heaven's name are memory leaks ?

The little message below describes a 'bug' in the include file msgbox.e, for EUPHORIA version 2.0 which serves as a handy introduction to what functions actually do. It also provides an illustration, of how using allocate() incorrectly can sometimes cause minor errors in any 'not so simple' code you might write in the future. Incidentally, this 'bug' will be fixed in future releases of Euphoria !

At the beginning of the message_box() function, some memory is reserved for the call to user32.dll, which essentially provides us with the means to communicate to the actual Windows message_box "code" in this .dll.

    -- An example line which does this is:

        text_ptr = allocate_string(text)

This 'pokes' the value of (text) into memory. The problem with this, is that if you do not later free() the memory which you reserved it will never be returned to your system. As the code below illustrates, you actually exit this function "before" freeing any memory,

( from the Euphoria mailing list )

    RE:	Re: message_box bug?

    Terry Constant writes:
    > The last four lines of the message_box function in msgbox.e are:

    >        return c_func(msgbox_id, {NULL, text_ptr, title_ptr, or_style})
    >        free(text_ptr)
    >        free(title_ptr)
    > end function

    > Since the function returns the return value of c_func(), are the two
    > free() statements after the return ever reached. That is, everytime
    > we call message_box, aren't we losing memory?

    Yes, you are right. This creates a small storage leak. Thanks!
    In the next release I'll change the code to:

       ret = c_func(msgbox_id, {NULL, text_ptr, title_ptr, or_style})
       free(text_ptr)
       free(title_ptr)
       return ret

    where ret will be declared as a private variable:
        atom ret
    inside message_box()

    Fortunately, very few programs are going to pop up
    thousands of message boxes during one run.

    Regards,
         Rob Craig
         Rapid Deployment Software

** This 'bug' was fixed in Euphoria version 2.1.

..end of lesson.

CONTENTS