Programming Windows in Assembler

Using EasyCode routines

I did say in the last chapter that EasyCode would make your assembly life a lot easier and I think you've seen some of that already. But it gets better. EasyCode has a bunch of ready-made routines built into it to help you do things which would otherwise need a good chunk of code. Let's have a look at them by bringing up the EasyCode help manual, clicking the "Index" button and then typing in "Easycode". You'll see an entry marked "Easy Code methods". Select that one and a list of around 50 functions (also known as "methods" in programming) will appear. Once again, this is not meant to be a manual eithe on goAsm or on EasyCode, so I will not be examining every one of these (or even most of them). We'll use the ones we need for our purposes and, by doing so, you'll understand how to use the others.

The ones I particularly want to use here are those to do with strings. Now, strings really belong to high-level languages like BASIC and Java. A string is a number of characters all related to one another like beads on a string. Thus the name. In assembly, as in "C", your string also needs to have a final character with a value of 0. This is not the character "0" but the value 0. It acts as a terminator which tells the system "this string finishes here".

It's very important to draw a distinction between numbers and string representations of numbers. For example, let's take the number 100. Because this is less than 255, it can fit inside a single 8-bit byte, as we know. Let's imagine we want to change the text inside our window caption to this value. We cannot just give it the byte containing this value. It's a number and the function which changes the caption needs a string. We therefore need some code which will take the byte containing the 100 and to convert it into three bytes containing three letters joined together - "1", "0" and "0", all strung together. Characters can exist independently as you can see in this conceptual image but the characters in strings are stored in consecutive "boxes" with an additional character with the code 0 in the last one. The illustration shows our "100" with is final character.

That's not as easy as it sounds. Each letter is represented by a code. The value "65", for example, represents the letter "A", while 48 represents the letter "0". Some characters are not printable. For example, character 32 is the space character. Anything lower than that is known as a control character. Character 0 is one of those. To convert the value 100 to a string of letters, we would have to repeatedly divide it by 10 and take the remainder each time, using it to determine which code would be needed to represent that value as a letter. Then we would have to append it to the string ...

You can see the values which represent the main characters in what is known as the ASCII (pronounced "Ass-Key") code in this illustration but it is also important that there is another standard called ANSI which uses two bytes to represent each character to allow the vast range of symbols you can see, for example, while using a word processor like Microsoft Word.

All of this should worry you not in the least when you learn that EasyCode has its own function - String - which will convert a number into a string for you. All you need to do is to provide it with the location of the value (or an absolute number), a pointer to the series of boxes which will contain the string and an indication of the number base you want the string to be in (at the moment only decimal and hexadecimal are available).

So, before we can do the conversion, we need to set up a label with the correct number of boxes assigned to it. We can easily imagine that the width is going to be less than 9999 and the same goes for the height. We want our caption to have both values, separated by a comma and a space. That gives 4 + 4 + 2 = 10 bytes. But we also need to remember the final character '0', giving us a maximum of 11 characters to make sure we have the right space for any values. We create our string in the .Data section using the following code:

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

	clientRect		RECT
	clientDimensions	DB 11 Dup 0

You can see that we are using the "DB" instruction which stands for "Data Byte". It's followed by the value 11 to indicate that we need 11 of these bytes reserved. The "Dup 0" means that we need to fill these 11 bytes with the character 0. We have our string.

Now all we have to do is to call the String function. Take a look at this function in the EasyCode help manual. As you can see, this function works out the number of characters in the string and places it in the EAX register. We first want to convert the width of the client area to a text string. To do this using our information we would say:

	Invoke String, [clientRect.right], Addr clientDimensions, ecDecimal

The Addr clientDimensions should pose no problems for you by now. Nor should the "ecDecimal" - that's in the help file - it's the notation for the clientRect that's a bit puzzling. Well, I told you earlier that the clientRect "box" is split into 4 compartments and that each of these had a pre-determined name. To use one of these compartments we use that name of the compartment and the name of the whole box, separated by a period, as shown.

Let's pretend that we only wanted to display the width in our caption bar. We could go ahead now and set the caption to this string. We have to use another EasyCode function for this. Use the Index to find the entry for setText. As you can see, it needs a handle to the window or other object and a long pointer to the zero-terminated string we want to make the caption. We have our window - hWnd - and we have our string - clientDimensions - so we're good to go:

	Invoke SetText, [hWnd], Addr clientDimensions

Lastly in our handler, we need to return from it and get back to the main event loop so that we can listen out for new events. This is done using the command:

	Return (TRUE)

The "TRUE" merely says that we're telling the rest of the program that everything went well. We cannot do much about the alternative, again because we don't know anything about "Jump" instructions but we'll get there. In summary, then, our handler looks like this:

	OnResize:
		UseData winMainProcedure

		Invoke GetClientRect, [hWnd], Addr clientRect

		Invoke String, [clientRect.right], Addr clientDimensions, ecDecimal

		Invoke SetText, [hWnd], Addr clientDimensions

		Return (TRUE)

	EndU
	; End OnResize

Compile this and try it out. The number in the caption bar should change when you resize the window horizontally but not when you do it vertically. Congratulations!

Select page