Chapter 2: The Launch Program

Hello World!

By now, you will be really keen to write, compile and run your first real Windows program using HMG! Before we do this, you need to plan ahead and establish how you will keep backup copies of the files you create at each stage. This is an important discipline in programming to learn early on and the reason for this is that there will be times when you need to go back to an earlier working version when you encounter a problem with the next stage of development!

In developing this guide, I have devised a naming convention for the majority of the files that you will create whilst following this guide. I have done this as I strongly recommend that you learn to backup each file once you have completed each stage of development.

The file name convention for source code files is as follows HMGGuide-Ch<chapter number>.prg where <chapter number> is replaced with the number of the chapter.

Using your chosen editor (such as Komodo) enter the program code exactly as you see in the box below. It is critical that you type in exactly what you see below into the source code file including all semi-colons (;), hash signs (#) etc or the file will fail to compile. It is less important that you use exactly the same spacing you see below to layout the file, although there is a good reason for this which I will discuss later.

Save this file to the MySourceCode folder naming it HMGGuide-Ch2.PRG. You must ensure that you save it with a .prg file  name extension as most editors will add a .txt extension by default, so ensure you change save as type dialogue to ‘All Files’ from the default ‘.txt’.

  #INCLUDE "hmg.ch"

  FUNCTION Main()

  DEFINE WINDOW Win_1 ;
    AT 0,0 ;
    WIDTH 760
    HEIGHT 640 ;
    TITLE "Hello World!" ;
    WINDOWTYPE MAIN
  END WINDOW

  ACTIVATE WINDOW Win_1

  Return Nil

You can download a copy of the source code file from here -  HMGGuide-Ch2.prg

You will now need to compile the program to enable it to run. As referenced above, a compiler is a computer program that transforms your HMG program code (also known as source code) into a form that a computer can execute (usually known as an executable). Open a Command Prompt and navigate to your source code folder where your program file is saved or use the MySourceCode.BAT file you created above.

At the command prompt, type "..\build HMGGuide-ch2" (exclude the inverted commas) and then press the Enter (or Return) key as per below. The two full stops before "build" are important so ensure you include them!

Once the source code has compiled, the program will automatically start and will look like this depending on which version of Windows you are running. This guide, the source code and all screen shots was written on a PC running Microsoft Windows 7.

Understanding Your First Program

Now that you have been able to write and run your first Windows program, we need to understand what the code does. To do this, I will describe the code file line by line.

However, before we explore this is further detail, it is important that you understand the significance of the semi-colons you see in the source code. The semi-colon is, in effect, ignored when the program is compiled because it is used to make your code easier to read by breaking very long commands into a series of lines rather than just one long line. Apart from making your source code easier to read, especially when you print it out, you will also find your code is much easier to debug when it fails to compile correctly.

It is not at all necessary to do this if you choose to do so. However, compare the following two commands, both of which are completely valid, and then decide for yourself whether or not to write your own source code in a manner that makes it easier to read or not. In my opinion, it really is a "no brainer"!

  Example 1: Making your code easier to read

  DEFINE WINDOW Win_1 ;
    AT 0,0 ;
    WIDTH 760
    HEIGHT 640 ;
    TITLE "Hello World!" ;
    WINDOWTYPE MAIN

  Example 2: Less easy to easy to read?

  DEFINE WINDOW Win_1 AT 0,0 WIDTH 760 HEIGHT 480 TITLE "Hello World!" WINDOWTYPE MAIN

Hopefully, you are now convinced of the importance of writing you code in a way that makes it as easy to read as possible. Let’s now review your first program line by line so that you can start to understand it.

#include "hmg.ch"

The #include directive instructs the compiler to include a file defined elsewhere. In this example, it is including the main HGM "header file" which is installed by the HMG installation program. This file, which you can find in the \INCLUDE folder in the main HMG installation folder, links in a number of other header files and these ultimately contain definitions and instructions (known as directives). All you need to know at this stage is that it is critical that you include this and that it must be at the top of any of your source code files.

FUNCTION Main()

FUNCTION is the first statement in your code file. A statement is, in effect, an instruction that your program will execute and in this case the statement is to create a User Defined Function (a UDF) which is unique to your program. As the name suggests, a function performs specific actions within the program. A function name, in this case Main(), can be of any length, but only the first 10 characters are significant with the rest being ignored. Names can contain any combination of characters, numbers, or underscores, but must begin with a character or an underscore. Leading underscores are not recommended since they are reserved for built-in functions. 

All programs must contain at least one function at start up but, in reality, you will develop many UDFs as you become more familiar with HMG so don't worry if you find this concept confusing at this stage. All you need to know now is that UDFs are very powerful and allow you to execute instructions many times without having to write the same code over and over again.

DEFINE WINDOW Win_1 ;

The DEFINE WINDOWcommand instructs the computer to create a window which will be displayed at a later stage. A command, like a statement, is an instruction your program will execute to perform a specific task. In this case, we are instructing the program to define (or create) a window which the user will see at a later stage. All windows in your program must have a unique name, in this case WIN_1.

AT 0,0

This is the first property of the command. A property is "passed" to the command to customise how the computer executes the command. Most commands require at least one property (known as mandatory properties) when they are executed and, equally, most commands also accept properties that are optional. Optional properties only need to be included when you wish to achieve a certain outcome. The use of mandatory and optional properties with a command is a small part of what is known as syntax. This is a set of rules that include the sequence and order of the text entered as computer code including words, numbers, and punctuation, in much the same way as most human languages are written.

Don't worry too much if this also sounds a little confusing and daunting. As you become more familiar and experienced with using HMG, you will find that your understanding of properties and syntax becomes more natural.

The AT property, in this case, is mandatory and it is used by the command to establish where on the screen the top, left corner of the window will be displayed on your screen. In this case the window will be displayed at the top, left side of your computer screen. The AT property accepts two arguments separated by a comma. An argument is a variable (which, as the name suggest, can be changed) used by the command, in this case, to locate the top edge of the window on row 0 and the left edge at column 0. These are defined in pixels which are the "dots" which make up the resolution of the computer screen display.

To understand this a little further and to also encourage you to start modifying your own code as you read this guide, change your own source code to display the window in a different position such as AT 50,600.

After you save and compile the code, your first program should now open slightly lower down the screen and a lot further away from the left hand edge of your computer screen.

This kind of experimentation by changing some parts of the code will be invaluable in helping you to get to grips with the language and its usage including building your understanding of the properties and arguments each command uses. I will continue to suggest where you may want to try this for yourself until such a time as you should have become more proficient in using HMG. You may also be relieved to know that this guide will start to become a little easier to follow now that I have introduced you to some of the fundamentals of programming!

WIDTH 760

The WIDTH property is used by the command to define how wide the window is when it is first displayed on your screen. In this case, the window will be displayed as 760 pixels wide. This is not a fixed width once the window is displayed. If you launch the program you have compiled by either recompiling the source code file or by double clicking on the executable file, you will notice that you can use the mouse to resize, maximum, minimise and close the window with your mouse in exactly the same way as you do with any windows program.

HEIGHT 640

The HEIGHT property defines how high the window is, when initially displayed, from the top edge to the bottom.

Try changing the two values for width and height for yourself to WIDTH 900 and HEIGHT 200. The resultant window will now be a different width and height.

TITLE "Hello World!"

This defines the text that will be displayed on the window title bar next to the window bar icon at the top left of the window as defined by the argument you pass to it which must be enclosed in inverted commas (both double and single inverted commas are valid ). Again, feel free to experiment by changing the text of the argument.

WINDOWTYPE MAIN

The WINDOWTYPE MAIN property defines the named window as being the main or master application window, in this case, Win_1. All HMG applications that use the Graphical User Interface (GUI) must have one, and only one, MAIN window. As you will probably gather, this infers that other types of window can be defined and displayed and will we come on to that later in this guide.

END WINDOW

The END WINDOW command is required once all of the various properties, arguments and elements of your window have been defined. At this stage, it probably appears that there isn't really a lot to defining a window but you will see later on that there is a lot more involved in this than it may appear at this time.

ACTIVATE WINDOW

The ACTIVATE WINDOW command instructs the computer to actually display the window of the computer screen. It is completely possible to define several windows but only display these in certain circumstances depending on what your program is intended for. Examples of other windows that may be used in addition to the main window include pop-up warning messages, requests for user input such as clicking on "Yes" or "No" and these will be covered in a later chapter.

RETURN Nil

The RETURN command is the final command in your first program. This actually defines the end of the user defined function (or UDF) that we started creating with the FUNCTION command and all functions must end with a RETURN. In this case we are returning a value as an argument, in this case, Nil which is, believe it or not, actually a valid value. Later in this guide, the reasons for returning a value will be explored in more detail but for now, you only need to understand that you must finish a UDF with a return command.

A Little Experimentation

Earlier in this chapter, I suggested that the height and width of your windows was only fixed when the window is initially displayed and you will remember you can use the mouse to resize, maximum, minimise and close the window with your mouse in exactly the same way as you do with any windows program. As you probably suspect by now, HMG is a very powerful language and you'd expect to be able to control such aspects if you wanted to do so and the good news is that you certainly can!

I've previously mentioned that all commands accept a number of properties and arguments and you should already have experimented with changing a few of the arguments which define the window position, width and height. So let's now experiment further by exploring a couple of the optional properties that can be passed to the DEFINE WINDOW command. For your first experiment, let's prevent the user from being able to resize the window but still allow them to maximise and minimise it. Add the NOSIZE property to your DEFINE WINDOW command. Don't forget the semi-colon!

  #include "hmg.ch"

  FUNCTION Main()

  DEFINE WINDOW Win_1 ;
    AT 0,0 ;
    WIDTH 760
    HEIGHT 640 ;
    TITLE "Hello World!" ;
    NOSIZE ;
    WINDOWTYPE MAIN
  END WINDOW

  ACTIVATE WINDOW Win_1

  RETURN Nil

Once the program launches, try and resize the window using the mouse on the window edges as you normally would. If you also click on the small window icon at the top left edge of the window, you will notice the system menu for the window now has the 'Size' option greyed out.

You can also stop the user from being able to minimise or maximise the window. Add the NOMINIMIZE and NOMAXIMIZE properties to the DEFINE WINDOW command and you will notice that the user is now prevented from being able to perform such actions.

Layout of Code Files

Earlier in this chapter, I said that it was critical that you type in exactly what you see source code examples (all of which are laid out in text boxes). I said that it was not as important that you use the spacing you see in these samples for the layout of your files and I would exampling why later.

As I suggested, the reason for the layout you choose is important to make the file more readable as this will, when the time comes (and it will), make it far easier for you to debug your code. Debugging is a method or process of finding and reducing the number defects in a computer program that prevents it from being compiled in the first place or, in more complex scenarios, debugging is used to ensure a program that does compile actually works as it is intended to work.

At this early stage, it is probably difficult for you to see how your use of spacing in the general layout of the source code file helps with making it more readable but you will, I hope, have recognised the value of breaking up long command definitions into several lines by using the semi-colon. As this guide builds and we starting including many more commands and additional functions, the use of spacing in the layout should become clearer and I will, in a later chapter, go into this in a little more detail.

As you learn more, you will also come to realise that there are certain 'words' that you cannot use (think of these as reserved by the HMG language) and some that you can use. To make this even more confusing for the beginner, you can use some 'reserved' words but in different contexts! An example of this is the use of Main in your first program where the word Main was used to give your first function a name and to declare your first window as the Main window. When used in the context of a window definition Main is a reserved word but in a different context such as naming a function it is not.

I again want to stress that you should not be put off or too daunted by this! As with most things, when you start to learn a new skill for the first time it can be extremely hard to imagine that you will ever fully understand and be able to use that new skill. Most babies take a long time to learn to crawl and walk, let alone run and most of you will have fallen off a bicycle a few times when you started learning but you eventually mastered all of these skills. The same is true of learning a new computer language, especially if it is the first language you are learning. Keep going with the guide. You have, after all, managed by now to write and customise your first program even if it doesn't actually do much. When you reach the end of this guide, you will have developed a program that does do something useful and you will have learnt and be able to use a great deal of the power available in HMG for your own applications.

Chapter 1: First Steps <<     >> Chapter 3: Adding Labels