Previous: Bitmaps and panels

Workshop 05: Digits and Windows


Ok, so now we know how to create panels... what comes next? Let's play with digits, a panel element that can display numerical values. Start Lite-C and open the file named script05 from inside workshop05:

PANEL* first_pan =
  digits(320, 200, 2, "Arial#150b", 1, sys_seconds); 
  flags = SHOW | OUTLINE;

I like short examples, but I see something strange here: I thought that a panel definition must include a "bmap = some_bitmap;" line and numerical values for pos_x and pos_y! We will only display some figures here - we don't need a bitmap for that, so we don't have to add the bmap line of code. And if pos_x and / or pos_y are omitted, they are assumed to be 0. 

The "digits" definition doesn't look that complicated. Let's discuss it right away:

digits (320, 200, 2, "Arial#150b", 1, sys_seconds);

- "digits" is the keyword that must be used whenever we want to display a figure on the screen;

- the first two numbers (x = 320 and y = 200) show the position of the digit on the panel. If the panel would have pos_x = 20 and pos_y = 30 and this digit definition has x = 410 and y = 200 we would see the figure on the screen at x = 430 and y = 230, get it?

- 2 is a format code. In this case it's just the number of digits that will be used to display our number. In my digits example I can display numbers up to 99 (2 digits), but if I would replace 2 with 5 I would set the limit to 99,999. There are more complicated format codes that give the number of decimals or allow to use texts as well (just like in our workshop02 example); you can learn everything about them in the Gamestudio manual. I've added the link to the relevant page of the online manual below.

- "Arial#150b" tells the engine to use its Arial font with a size of 150 points in bold letters. We could have used * instead, which means the default font, a small set of predefined characters that will be used to display figures or texts for testing purposes. We can define and use any other fancy Truetype or bitmap fonts.

- 1 is a factor that multiplies the value which needs to be displayed. Don't worry about it for now; we will use 1 here most (if not all) of the time;

- finally, sys_seconds is the name of the variable that will be displayed. You can replace it with any other variable.

Ok, now that we have talked about all these things, we can write down a more general digit definition:

digits (x, y, format, font, factor, variable);

(Tip: you might see older scripts which use a different digits definition, like "digits = x, y, format, font, factor, variable;". This definition was used in the older version of the Acknex engine, which is included in lite-C).

Let's Test Run this script file:

I can see my digit on the screen and its value changes every second, just like a clock! I'm sure that "sys_seconds" is a predefined variable, because I didn't have to write its definition at all. You can play with "320" and "200" to change the position of the digit on the screen. If you would change pos_x and pos_y too, you would see that the panel changes its position; however, the digit will keep its offset in relation with the panel. By the way, the OUTLINE flag in the panel is responsible for the black border around the digits.

These digits are cool! I could use them to display player's health, armor, number of bullets, lives... every time I need to display a value I will use a digit! But wait... how can we display several digits? Simply add several "digits" lines of code to your panel definition (this time with the small default font):

digits (370, 200, 2, *, 1, sys_hours);
digits (390, 200, 2, *, 1, sys_minutes);
digits (410, 200, 2, *, 1, sys_seconds);

If you are as bold as you should be, replace the single "digits" line in script05 with the 3 lines above to get a simple (yet fully flavoured) clock:


No, I'm not talking about the operating system here; I want to show you how to create a window, a panel element that uses a variable in order to display a certain part of a bitmap. If you aren't so sure if this "window" is useful, you'll have to trust me: it is. You will want to use windows whenever you want to create a compass or maybe a (horizontal or vertical) bar that changes its length or width, for example some health bars for your fighting game.

Let me show you how these windows work and then you will be able to decide when and why you would want to use them.

Let's imagine that we want to use a flashlight in our game. We'd like to have an indicator for the batteries: when they are full of energy, we would like to display a small green picture on the screen. When the batteries start to run out of energy, we'd like to have a yellow picture and when the batteries are dead we'd like to see a red picture.

Of course that the flashlight indicator would look even better if the transitions from one color to another would be smoother...

Don't worry, all this stuff can be created using a simple "window" definition. First of all, we create a long bitmap that looks like this:

Next we use a window definition that makes this bitmap slide along the small frame, like in the picture below:

The parts of the bitmap that are placed outside the frame are (you've guessed) invisible, so the player can only see the picture inside the frame. You simply change a variable that moves the bitmap to the left or to the right using a "window" definition and you are set!

Now that you've grasped the basics, let's create an altitude meter (altimeter) for our plane:

It is pretty clear that we need a bitmap that looks like this:

We want to display only a part of the bitmap, the one that corresponds to a certain altitude for our plane. How do we do that?

We have to define a variable and a window - use the code from script05_2.c:

var altitude = 0; // height of the plane 

PANEL* first_pan =
  bmap = "frame.pcx";
  window (40, 10, 178, 160, "height.pcx", 0, altitude);
  flags = SHOW;

Let's see the changes: we have a new var named altitude and are using two bitmaps in the panel; one of them is used as a frame for the altimeter (we don't really "need" it, but it looks cool) and the other one is used inside the window definition. And of course, we have the window definition inside the panel named first_pan!

Time to run our script! Press Test run and you will see the following image:

Don’t be surprised to see these bitmaps on the screen; I have created them and I have placed them inside the workshop05 folder. Now press Tab on your keyboard to show the console and then type the following line of code and press Enter:

altitude = 150;

You can see that the bitmap has changed and we are coming close to 185 feet / miles / whatever. You can type any other values but you will notice that big values like this:

altitude = 1000;

won't be displayed correctly; this happens because the bitmap used for the window has a height of only 780 pixels. Use smaller variable ranges or bigger bitmaps if you need to.

Let's see a typical window picture and its step by step definition :

window (x, y, size_x, size_y, bitmap, variable_x, variable_y);

- window is the keyword that must be used every time we define a window;

- x and y give the position of the window on the panel. If the panel has pos_x = 200 and pos_y = 100 and our window has x = 30 and y = 20, the bitmap used for the window will be placed at x = 230 and y = 120 on the screen.

- size_x and size_y give the size of the cutout "window" on x and y. Remember that the window bitmap itself is huge; these figures will set the size of the visible part of the bitmap on x and y;

- bitmap is the name of a previously defined BMAP* or the file name of the bitmap used for the window (height_pcx);

- variable_x gives the horizontal offset of the bitmap that will be used for the window. We don't want to move the red bitmap to the left or to the right so we use zero as variable_x in our example;

- variable_y gives the vertical offset of the bitmap used for the window. We wanted to be able to move the red bitmap up and down, so we have put a variable name here (var altitude).

Conclusion: When you create a window, you will only see a small part of the bitmap used for it. Change variable_x or variable_y (altitude in our script) and the long bitmap will be shifted along the x or y axis, displaying other parts of the bitmap on the screen. The size of the cutout window in pixels (the visible part of the bitmap) is given by size_x and size_y.

Next: Buttons and sliders

Further reading: Gamestudio manual ► digits, window.