HOME - - - - - Lazarus Tutorials TOC - - - - - - Other material for programmers

The basic framework of any Lazarus/ Delphi unit file

A general discussion of a topic of core knowledge

file: lt1N-unit-frame.htm

Many of my tutorials are of the "this is how you do..." variety.

This one is a bit different, in that it describes some basics- the general form of "unit" files (the ones with extension ".pas") If you know the general form, you will spend less time trying to "fix" things because you will accidentally break them less often. It will help you know "where things go"..

Of course, a Lazarus project is made up of many files, but most of a beginner's work will be with the .pas file. (He/ she will also, of course, be changing the file that controls the appearance of the form... but that work is done via GUI in the IDE, and so you are less likely to introduce syntax problems.)

How this material has been uploaded

For these essays, I wanted to provide you with images of the Lazarus unit code at different stages of completion, with color used to highlight things.

I decided that I would use .pdf's for that.

In what follows, you will find links to click on which will provide you with copies of those .pdf's. What happens when you click on the link will depend on your system. You should also know that you will find things most useable if you can have the .pdf and this text side by side in front of you. (The .pdf's are all only one or two pages long.)

The first step, of course, is not to have your browser filling your whole screens. (To those of you reading on a smartphone... sorry... I don't particularly cater to that environment, given that the material I create seems to me to require more screen space.)

If when you click on the link it doesn't appear that anything has happened, your system may have downloaded the .pdf as a file. Again, depending on how your system is set up, there will be a way to open that "outside" of your web browser. Or it may be that the browser opened the file in a new tab, but that it hasn't switched to the tab. Or, if your browser is set to open .pdf's in the browser, it may be best to right-click on the link, and ask for it to be opened in a new window.

((q-alt text for image))

For this the first .pdf, I have created an image of an early edition of it, so you know what you're trying to obtain. The .pdf is of a much better resolution.

Skim the text below, using the low resolution image at the right to "see where this is going", and if you like what you find, fetch the .pdf so you can re-read the text below, following the detail in the color- highlighted copy of the unit's code.

Click here for lt1N-unit-frame-1.pdf... there's a way to jump back here at the bottom of the text I've suggested you skim before fighting whatever your system's configuration creates for fetching the .pdf.

What you could read if you fetch the .pdf is a brief statement of what the programmer has done so far (opened up a new project, of the application type), and then the source, as it would be at that stage of building the application.

Even at this early stage, there are things to note about what's in the source. There are elements of the present- every- time "framework" that I want you to know about.

The small green bit at the top says "unit Unit1". It is "partner to" the small green bit at the bottom which says "end." (There are more details in the .pdf)

After the green bit at the top, is "{{1}}", which is a link to ....

At {{1}} in the .pdf we see unit Unit1; Every unit starts with the reserved word "unit", followed by a space, then the unit's name... which will be the name of the associated .pas file, among other things... and then a semi-colon.

(In all Pascal-based languages, such as Lazarus and Delphi, if in doubt, put in a semicolon. But know the various places where you don't insert them, too!)

{{2}}: The orange line: This is a "compiler directive". They always start "{$", and can be "sprinkled" into the code just about anywhere. None are required... by the language. But you may not get the results you want for a specific system, compiled on (possibly some other system) without a few basic compiler directives which Lazarus ordinarily supplies for you. You do not put a semi-colon at the end of a line holding a compiler directive.

Do not confuse compiler directives... which start, as I said, "{$" with comments enclosed in {'s...

   {like this}

(As long as the first character isn't a dollar sign, you can put anything you want between {'s, and the compiler just ignores it. You have created a comment, aka "remark" or "rem".)

Moving on....

{{3}}: The beginning of the block of two shades of blue lines...

This is the "interface" block. The block starts with the reserved word "interface"... with no semi-colon after it. That word MAKES the "interface section" start.

Unlike most things in Pascal languages, there is no explicit word to end the interface block. (It ends where ever the implementation block... which we will come to... begins.

The first thing in the interface block is marked {{4}}. It is a "uses" clause, spread across two lines. It starts with the word "uses", is followed by the names of some units used by the present unit, separated by commas, and doesn't end until you reach a semi-colon. In this case, the semi-colon doesn't appear until after you've started a new line on the screen. The new screen line is ignored by the compiler. It treats all of what is between "uses" and the semi-colon just before the "{{4}}" as one long (virtual) "line". (The various units... "Classes", "SysUtils", etc, that you see here are standard, supplied- with- Lazarus units. Anyone write units to be added to "uses" clauses... but you don't need those skills in your early Lazarus/ Delphi programming days.

{{5}} Now we come to a very long "single" "virtual" line... the seven lines colored light blue. They are all part of one "thing", hence the shared shade. They are just one of the things in the interface section, hence the blue.

{{5}} is the start of a "type declaration". You will be learning more and more about "type declarations" for a long time to come. For now it is enough to know that you need to be careful not to mess them up, even though you will be "sticking things in". (We'll discuss this more later.)

{{6}} Is a line that will appear, in some form or other, in all of your units in the early days. Happily, it is provided for you by the system, and doesn't need (or welcome) any tweaking.

{{7}}: The reserved word "implementation" brings the "interface" section to a close, and begins the "interface" section. What goes in interface, what goes in implementation? This isn't something that is easily explained to a novice... but you will get a feel for it, as you do more and more Lazarus programming.

{{8}} This is "merely" another compiler directive... similar to the one up on the line identified with "{{1}}".

{$R *.lfm} is a compiler directive that is inserted by the system. Novices should leave it alone.

There is a different compiler directive I recommend inserting. It can go just below the one we've just discussed. It is...

{$R+}

You might think that {$R+} is related to {$R *.lfm}... but it isn't. (It turns on "range checking", which you can either look up, or just take my word as something that is, for a novice, a Good Thing. Yes, the way will come when sometimes you turn it off... but you can leave that worry for later.)

That's it! That's what's in the first .pdf

If this is the first time you've reached this point in the essay, and you haven't had the .pdf to read, Click this to go back to where the link to the .pdf version of the image is, above, and read the text between there and here again. And then we'll start the second .pdf....

The second .pdf

The second .pdf shows the same application, but after you've added a button, and created an event handler for the event that is every button's most commonly used event... the "Click" event.

As a result of those small actions, the code has changed. In the .pdf, we have what we had before... now not highlighted, and with the previous references like "{{1}}" removed. New references have been added, new lines... the changes and additions... have been colored.

{{1}} This is inserted for you when you use the Lazarus GUI to add a button to the form. The button is assigned the name "Button1", it is an object of "type" "TButton". (You can change the button's name. (And you probably should... make it something meaningful, like "buStartGame", if clicking it would start a game. (The "bu" prefix is arbitrary, my system... but a Good Idea.) You change the name with the Object Inspector, and that will take care of various necessary changes... including changing this line. In general... try to avoid tinkering directly with the code, apart from adding things that can't be added other ways. So... this line is one you should mostly leave alone. But you will see it. And now you understand what it is, where it comes from.

{{2}} This too was supplied automatically by the system. That happened when you double clicked on the button you'd put on the form, and it is part of creating the handler for Button1's OnClick event.

{{3}} The stuff in light yellow was also supplied by the system when you double clicked on the button.

{{4}} The stuff in dark yellow ("French mustard" color?) ("//By hand bit...") was typed by hand by the programmer in charge of creating the app. The system won't do it all for you!

(Beware... it is prone to try to "help", by supplying "end"s at times I've never fully understood. Just watch out for them. Use them, if you see them in time. Weed them, if you get extras!)

The third .pdf

The third .pdf shows the same application, but after some more work was done. (That work is explained at the top of the .pdf)

The first line discussed is not the first new line in the code. I've numbered the lines to show you the sequence used while building the new elements into the growing app.

If what I've done and what has appeared where is a little hard to follow, start from here: The changes merely add a label to the form, and the label shows you how many times the button has been clicked.

The fourth .pdf

The fourth .pdf carries on the good work, as before.

In this step, what you do to move the project forward is described at the top of the .pdf.

Further to that, a few explanations...

The blue and yellow colors, by the way, here and elsewhere, are to distinguish things added to the interface section and things added to the implementation section.

{{1}} (Nothing remarkable about this)

{{2}} For a long time, I suspect, you won't need to add variables or subroutines in any part of the "interface" section other than the "private" section. (The entries you are making, by the way, are "forward declarations".

Within the "private" section, you enter any variable declarations FIRST. (They can be in any order) AFTER the variable declarations come the subroutine declarations. Some will declare procedures, some will declare functions. They too can be in any order, as long as they are all after the last variable declaration.

{{3}} All of the code you see has to be typed by hand. You can, of course, use "copy/paste" in the usual way to do the first line with a copy of the earlier declaration line. (At {{2c}}). NOTE, however, that in the "implementation" section, because of how we've done things... which is The Right Way... that "TForm1." has to be added to the first line of block {{3}}. (It will only be TForm1 if you haven't renamed the app's form. It is a good idea to rename the form. If I were calling the app "MySpecialThing", I'd call the form fMySpecialThing, and we'd have "TMySpecialThing." to add in front of sDoubleIt, here in the implementation section. Look at the other things in the section. Find the patterns. Use them. See "TForm1", elsewhere? If you'd renamed the form, you'd see something different where you see TForm1.

{{4}} This is almost unremarkable. It is very like what we did to put the number of clicks on Label1. But that "sDoubleIt" we used so casually wasn't a word that the language understood at the outset. We have "added a word to the language" with the code done earlier in this Stage.

I've written more... much more!... about creating subroutines (procedures and functions) in other, more usual tutorials. In this one, the "take away" information is the things about WHERE stuff goes, WHAT stuff is needed. The other tutorials will help you with the whys and wherefores, and the details of the "What"s.

The fifth... and last!... .pdf

You can probably skip downloading this .pdf.

It only shows a change to the implementation of the function.

The function is edited to make it...

function TForm1.sDoubleIt:string;
//This is "bad" in several ways! But will do to illustrate SOME things...
   var sTmp:string;// local to sDoubleIt      {{1}}
begin
   sTmp:= inttostr( iCountOfClicks*2);   {{2}}
   result:=sTmp;   {{2}}
end;

But if you want the pdf, this fetches the fifth .pdf.

It finishes things off. You will, I hope, be pleased to see how little is required.

{{1}} This creates a "local variable". Again, the whys and wherefores of local and global variables are the subject of other tutorials. In a nutshell: A local variable can only be "seen" inside the "block" it was created for, in this case the function "sDoubleIt". This is a Good Thing. Why? See those other tutorials!

{{2}} is the code to multiply the number in the global variable iCountOfClicks times two, and then convert the result to a "string type datum". By "result:=sTmp;", we "send" that "back" to where ever the app uses "sDoubleIt".

Abrupt stop! As ever!

Sorry for the abrupt stop. This has taken hours. and I want to turn to some of the things I've been neglecting. Comments appreciated!





Search across all my sites with the Google search...

Custom Search
            powered by FreeFind
  Site search Web search
Site Map    What's New    Search This search merely looks for the words you enter. It won't answer "Where can I download InpOut32?"
Ad from page's editor: Yes.. I do enjoy compiling these things for you. I hope they are helpful. However... this doesn't pay my bills!!! Sheepdog Software (tm) is supposed to help do that, so if you found this stuff useful, (and you run a Windows or MS-DOS PC) please visit my freeware and shareware page, download something, and circulate it for me? Links on your page to this page would also be appreciated!
Click here to visit editor's freeware, shareware page.

Link to Lazarus Tutorials main page
How to contact the editor of this page, Tom Boyd


Valid HTML 4.01 Transitional Page tested for compliance with INDUSTRY (not MS-only) standards, using the free, publicly accessible validator at validator.w3.org. Mostly passes. There were two "unknown attributes" in Google+ button code. Sigh.


If this page causes a script to run, why? Because of things like Google panels, and the code for the search button. Why do I mention scripts? Be sure you know all you need to about spyware.

....... P a g e . . . E n d s .....