Programming Windows in Assembler

Using Win32 routines

Very well. We have created the label for our event handler and we have requested the event loop information. What now? This is the point at which we need to call a Win32 routine. This, again, is what makes goAsm such a powerful piece of equipment. It allows us to call these routines very simply by means of the Invoke keyword.

Open your Win32 Help application. This is part of the Microsoft Win32 SDK and can be downloaded from their site. Each time the WM_SIZE event occurs and our handler is activated, we want to discover the size of the client area (the working area) of the window. Select the "Index" button and type in the text "getClientRect". Click the "Display" button to see the results.

	BOOL getClientRect(
		HWND hWnd,
		LPRECT lpRect
	);

If that looks a bit mystifying, don't worry - it's in "C" format. Let's dissect it:

BOOL - this means that when the routine finishes what you have asked it to do, it will answer "True" or "False" to you as to whether it succeeded or not. Answer like this are known as Boolean, so "BOOL" is a type of "box" which can handle only one value and that must be one of the above values.
getClientRect( - the name of the routine we want to ask. This particular routine needs us to supply it with two items of information. These go inside the brackets.
HWND hWnd - This is first item of information (known as a parameter) needed by this routine. It needs to know the location of the box in which Windows stored this window's details. Do remember that Windows needs to know the type information to be stored in each box so that it makes maximum use of the available storage. In addition, it helps us track down mistakes. This type of information is known as a "handle" - we can grab our window by this handle. There are other types of handle and so Windows needs to know that this is the handle to a window - thus, HWND. OK, so that's the type of data. What do we want to call the box in which this informaiton is stored? That's the "hWnd" part. Bu where did that come from? Well, when we said UseData winMainProcedure, that gave us some information, prominent amongst which is the location of the window's handle and EasyCode always gives this the name "hWnd".
LPRECT lpRect - When this function finishes, we said that it would tell us that it had succeeded or failed. But we really want a bit more than that, don't we? We want to know how big the client area is now that it has been resized. It's going to give us this information in a special kind of box whic holds information of type RECT. This is a box which is split into 4 smaller compartments with the pre-made names "left", "top", "bottom", "right". We can call the box whatever we want but these "internal" names are fixed. What we need to do is to create a box of this type and then tell this routine the location where Windows has stored it. That is why the type specified in the routine is LPRECT - the "LP" part stands for "Long Pointer". Our problem is that we don't know how to make a box to hold a RECT but don't worry - that's what we'll do next. The actual name of the box is given here as "lpRect" but since you are going to create it, you can call it whatever you want.
); - This is the end of the routine we are calling. In "C", we need to use a semi-colon at the end of commands but, as you will see, they are not needed in assembler.

So, before we do anything else, we need to create this RECT box. We'll call it "clientRect" and it needs to go in the .Data section of our program, up at the top just below the MESSAGES label, like this:

	MESSAGES		DD WM_CREATE, OnCreate
				DD WM_CLOSE, OnClose
				DD WM_SIZE, OnResize

	clientRect		RECT

Note well that we haven't given it a type like "DD" or "DW". This isn't an assembler data type. Since we're calling a Win32 function, this is a Win32 type so we specify the actual type as indicated in the help manual - RECT.

OK - back to our handler. We're now in a position to use the getClientRect function. We use the keyword Invoke followed by a comma and then the two parameters, also separated by commas:

	Invoke GetClientRect, [hWnd], Addr clientRect

Again, there's a couple of things to mention. Notice how the handle to the window is surrounded by square brackets? Well, I did say that the handle was stored in a box which EasyCode has called "hWnd". So "hWnd" is not the actual handle - it's the location of the box. You could look upon the square brackets as meaning "the box called ...". In reality, it's a pointer to the box containing the handle. The second thing is also along the same lines. Remember earlier when we said that we needed not just a RECT but a long pointer to one? We do this by creating the "box" (as we have done) and then giving the address of that box to the function. This is done by means of the abbreviation ADDR followed by the name of the box (clientRect, in our case).

So, what will happen after this function completes? We know that it returns a Boolean value - the help manual told us so. That means if it was successful, EAX would now hold the value "True" (normally this is represented by the value "1"). If, for some reason, it could not do its work (perhaps your windows handle is not stored at hWnd, for example), EAX would hold "False" (normally "0"). We should really have some code here to check this value and to react sensibly if the result came back "False". But that would entail our knowing about "jump" instructions and that come later in the series. So, with our current level of knowledge, we have to assume that it was successful and to carry on under that assumption. As regards the values of the client areas dimensions, they have now been stored in the clientRect structure, since we gave the Win32 function the equivalent of its zip code. Basically, it sent a letter there containing the values. We can use them now.

Select page