Chapter 4: Display a Button

Showing a Button

As I stated in chapter 3, Controls are an important aspect of all Windows programs. This is the term used to describe a very wide range of ways in which the user is able to interact with the program including being able to use buttons, icons, menus, images and lists. If you refer to the HMG Help (see 'More Help' in Chapter 1) and open the 'Controls' section, you will see a large list of these! Documenting and describing how to use every one of these, let alone all the Properties, Events, Methods and Functions also available would be challenging to say the least so it is my aim to introduce a selection of those that you might find the most useful. In time you will develop enough skills to be able to start exploring and using the ones I have not covered and there are a number of very useful internet resources available to help you such as the THE HMG Forum (which I recommend  joining).

The second control (you have already encountered the Label control) I would like to introduce is the Button control. In this chapter, I will show you how to display a plain button as well as one that uses an image (a Picture Button) on screen and, in chapter 5, we will make this button do something when the user clicks on it.

To get started, use your chosen editor and enter the code exactly as below and save the file to the MySourceCode folder naming it HMGGuide-Ch4.prg then compile the program using the "..\build HMGGuide-Ch4" command.

  #include "hmg.ch"

  FUNCTION Main()

  LOCAL cMainWinTitle := "ePortfolio"
  LOCAL cBtn1Cap := "Button 1"
  LOCAL nBtn1Row := 32
  LOCAL nBtn1Col := 64

  DEFINE WINDOW Win_1 ;
    AT 0,0 ;
    WIDTH 760 ;
    HEIGHT 640 ;
    TITLE cMainWinTitle ;
    WINDOWTYPE MAIN
   
    DEFINE BUTTON btn1
      COL nBtn1Col
      CAPTION cBtn1Cap
    END BUTTON

  END WINDOW

  CENTER WINDOW Win_1
  ACTIVATE WINDOW Win_1

  Return Nil

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

Understanding the Button Definition

As we did in the previous chapter, we have included a new section of code within the definition of WINDOW Win_1 that replaces the LABEL definition. By doing this, as we did previously with the LABEL, we are creating an Object which is associated with, and only with, the main window.

Detailed coverage of Object Orientated Programming (OOP) is a complex subject and not one that I currently plan to include within this guide although it will be necessary to include certain uses of it throughout the guide. In fact, we have already created a number of objects (the main window, a label) without having to explain OOP at all up to this point. At this stage, you only need to be aware that HMG is an OOP language. In time, and wherever necessary, I will introduce further ways to use or manipulate objects and explain these in further detail. For now, let's explore the new code introduced in this chapter.

DEFINE BUTTON btn1

As with the DEFINE WINDOW and DEFINE LABEL commands, we are instructing the program to create or define something that must be enclosed (or encapsulated) between a DEFINE and an END statement. I recognise that I am repeating myself by stating this, but I do so to re-enforce the point for the final time! To repeat another point (and also for the last time), everything you define must have a unique name; bnt1 in this case.

ROW nBtn1Row and COL nBtn1Col

These two properties, and their argument values, are used to identify where the top, left corner of the button appears in the window. Notice that we have defined two LOCAL numerical variables rather than hard coding the location by stating LOCAL nBtn1Row := 32 and LOCAL nBtn1Col := 64 at the beginning of FUNCTION Main().

CAPTION cBtn1Cap

As with a LABEL, where we used the property VALUE to define the text to display, we could also display something meaningful on the button. For a BUTTON the CAPTION property is used to define what this should be and, in line with good practice, we are using a LOCAL memory variable (in this case, LOCAL cBtn1Cap := "Test"). The CAPTION is not a mandatory property that must be included, so feel free to remove it and see how this changes the button.

Display a Picture Button

As I mentioned above, it is not mandatory to include a CAPTION although you will notice that the button becomes a bit of a mystery to the user if you remove it. Sometimes an icon looks better visually and this is easily done with buttons! Strictly speaking, HMG refers to these as a Picture Button rather than an icon but it may be easier to think of these as icons for now.

To achieve this, you actually need a picture that can be displayed and you need to direct your program to the location where you have stored the picture. A picture is, quite simply, an image with a valid file name image extension such as a bitmap (.BMP), a JPEG file etc.

I have created a very simple bitmap image to use with your code. Save this file - IconCh4.bmp - in folder c:\hmg.3.4.0\MySourceCode\Icons.

The next step is to change the source code file as follows and save the file to the MySourceCode folder naming it HMGGuide-Ch4a.prg then compile the program using the "..\build HMGGuide-Ch4a" command.

  #include "hmg.ch"

  FUNCTION Main()

  LOCAL cMainWinTitle := "ePortfolio"
  LOCAL nBtn1Row := 32
  LOCAL nBtn1Col := 64

  DEFINE WINDOW Win_1 ;
    AT 0,0 ;
    WIDTH 760 ;
    HEIGHT 640 ;
    TITLE cMainWinTitle ;
    WINDOWTYPE MAIN

    DEFINE BUTTON btn1
      ROW nBtn1Row
      COL nBtn1Col
      WIDTH 60
      HEIGHT 60
      PICTURE "c:\hmg.3.4.0\MySourceCode\Icons\IconCh4.bmp"
    END BUTTON

  END WINDOW

  CENTER WINDOW Win_1
  ACTIVATE WINDOW Win_1

  RETURN Nil

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

Once you save and recompile the code, the button will change to display the PICTURE rather than the CAPTION although nothing happens if you click on the picture button. You will also notice that WIDTH and HEIGHT properties have been included in the new definition. To understand how these affect the appearance of the picture button, we'll experiment with changing these and we will explore how the button appearance changes if both a PICTURE and a CAPTION is used.

A Few Things to Try

Firstly, try removing or changing the WIDTH and HEIGHT properties used to define the picture button, above. Depending on the resolution of the screen you are using, its appearance will change (or you might not even see it at all). By doing this, you will probably realise that these two properties are used to specify the width and height (in pixels) of the picture button! I chose argument values of 60 as these are the actual width and height, in pixels, of the image that I created for this chapter.

Secondly, add the WIDTH, HEIGHT and CAPTION properties back into button definition (as per below). You will now see that both a picture and a caption can be displayed. If the appearance is 'odd', adjust the width and height so that there is enough space for both the caption and the picture!

  DEFINE BUTTON btn1
    ROW nBtn1Row
    COL nBtn1Col
    WIDTH 60
    HEIGHT 100
    CAPTION "Test"
    PICTURE "c:\hmg.3.4.0\MySourceCode\Icons\IconCh4.bmp"
  END BUTTON

Finally, notice the 'bad practice' I employed by hard coding the caption, the width and the height? Now try replacing these to use LOCAL variables in the same way as we have used them to specify the ROW and COL at which the button appears.

Save this final version as HMGGuide-CH4b.prg which should look like this;

  #include "hmg.ch"

  FUNCTION Main()

  LOCAL cMainWinTitle := "ePortfolio"
  LOCAL cBtn1Cap := "Button 1"
  LOCAL nBtn1Row := 32
  LOCAL nBtn1Col := 64
  LOCAL nBtn1Wide := 60
  LOCAL nBtn1High := 100

  DEFINE WINDOW Win_1 ;
    AT 0,0 ;
    WIDTH 760 ;
    HEIGHT 640 ;
    TITLE cMainWinTitle ;
    WINDOWTYPE MAIN

    DEFINE BUTTON btn1
      ROW nBtn1Row
      COL nBtn1Col
      WIDTH nBtn1Wide
      HEIGHT nBtn1High
      CAPTION cBtn1Cap
      PICTURE "c:\hmg.3.4.0\MySourceCode\Icons\IconCh4.bmp"
    END BUTTON

  END WINDOW

  CENTER WINDOW Win_1
  ACTIVATE WINDOW Win_1

  Return Nil

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

Chapter 3: Adding Labels <<     >> Chapter 5: Using a Button