Tutorial:Window
About Windows
When Amiga was released in 1985 the availability of two interfaces to interact with the computer was a novel feature. Amiga's can be operated via command line interface and graphical user interface. For the later free movable windows are very important. In this tutorial we will open a window using AmigaOS routines and makes some simple drawing. On the way we have to deal with Tags, variable parameter, messaging, drawing principles and intuition structures.
The part of AmigaOS handle Windows, Mouse/Keyboard inputs is named Intuition and is accessible to the developer with the intuition.library in combination with the graphics.library for drawing routines. There are more things involved but this two are the most important. This two libraries are represented in Free Pascal with the unit intuition and agraphics. There is already a unit named graphics in the Lazarus component library. To prevent problems of double unit names we decided to change the name to agraphics. This happens for some library/unit names and also other structures a list can be found at Specifics Page.
Tags, Taglists
Some really cool invention of Amiga are hidden to the average user. The Taglist feature is such invention.
Imagine you want to design a function to open a window then you need a lot of parameters, like x,y position, width, height, kind of window and some more. If you put them all into the parameter list it become very long and hard to use. The usual way is to create a record so you supply only a pointer to the record which contains all this informations. But now after some years developing you noticed that you need more parameters because the function/window become much more powerful. One way to solve that without destroying compatibility to old programs is, to create a new function or record which includes new fields as well. Windows for example did that very often. You will find many functions/records with an additional ending "Ex" which is the extended version to support new properties.
Amiga took a different path: Tags. You supply a list of Tags and Value pairs to the function. Every Tags is just a simple integer number and stands for one property of the window. Just as an example (not real example: Left = 1, Top = 2, Width = 3, Height = 4). And if you ignore all Tags you don't know and fill properties which are not supplied with some meaningful default values then you can later add some more Tags for more properties to it, without harm the compatibility forward and backwards.
A taglist could look like this (part of a real taglist to open a window):
| Tag | Value |
|---|---|
| WA_Width | 300 |
| WA_Height | 200 |
| WA_Title | 'My Window' |
| WA_DepthGadget | True |
| WA_SizeGadget | True |
As visible in the table, the value can have very different types. But we need to transfer them using the same interface. The solution for that is "PtrUInt" (or "NativeUInt", which is the same). An unsigned integer value which is guaranteed to have enough space for a pointer as well. We cast all our Values to PtrUInt. Strings need to be converted to a PChar (zero terminated C like strings) and then treated like a common Pointer. For the casting special wrapper functions are inserted to utility unit. AsTag() converts all possible types to PtrUInt. Every Taglist must end with TAG_END to tell the program where your list ends, it does not requires an vlaue. Adding these things to the list now looks like that:
| Tag | Value |
|---|---|
| WA_Width | AsTag(300) |
| WA_Height | AsTag(200) |
| WA_Title | AsTag('My Window') |
| WA_DepthGadget | AsTag(True) |
| WA_SizeGadget | AsTag(True) |
| TAG_END |
Free Pascal is smart enough to create the string for WA_Title as PChar. Take care that is not possible if the string is calculated at this point. Besides one have to care about if the PChar supplied to the function is copied we will later come back to this.
How to open the window using this knowledge. For OpenWindow you will find a lot of different functions in Amiga API:
- OpenWindow() [1] - The old interface before taglist where invented, still there for compatibility
- OpenWindowTagList() [2] - requires a link to a task list as second parameter. You create the tag list before the call. Very handy if you want to have it configurable.
- OpenWindowTags() [3] - which have a
array of PtrUIntas second parameter which can be used to directly supply the tags with values to the function.