34.1 Overview

Hollywood offers you a powerful yet easy to use layer system which should be able to realize everything you need for your application. Layers are children of a background picture. Every background picture has its own attached layers. Hollywood's layer system is not enabled at startup. You have to enable it manually by calling the EnableLayers() command. Alternatively, you can use the Layers tag in @DISPLAY or CreateDisplay(). Once layers are enabled, every object displayed on the screen will be on its own layer.

Note that layers are enabled/disabled on a per display basis. Thus, it is absolutely possible to mix layered and non-layered displays. For instance, if you have two displays, display 1 could use layers and display 2 could be non-layered. This is perfectly possible.

What you should try to avoid is disabling layers in a display in which they have been enabled before. This is possible to do but it should be avoided in any case because layered and non-layered modes are distinctly different.

Let's have a look at a brief example now:

 
EnableLayers()
DisplayBGPic(2)
DisplayBrush(1, #CENTER, #CENTER)
Plot(100, 100, #RED)
Print("Hello World!")
Box(50, 50, 100, 100, #BLUE)

The above code displays 4 different object types and attaches at the same time 4 layers to the background picture number 2 because layers were enabled. Every displayed object gets its own layer now, therefore we have the following layers now for background picture 2:

 
Layer id 1: Brush 1 at coordinates #CENTER : #CENTER
Layer id 2: A red pixel at 100 : 100
Layer id 3: Text "Hello World!"
Layer id 4: A blue box at 50 : 50 with dimensions 100 : 100

Now you can do everything you like with those layers, e.g. you can hide them, move them, swap foreground priorities or remove them. Hollywood offers many functions that can handle layers.

Please note that layer ids are dynamic. For example if the above code would now call the command

 
RemoveLayer(2)

then the layer ids would be changed. After this command returns we would have the following layers for background picture 2:

 
Layer id 1: Brush 1 at coordinates #CENTER : #CENTER
Layer id 2: Text "Hello World!"
Layer id 3: A blue box at 50 : 50 with dimensions 100 : 100

You see that the text "Hello World!" has now layer id 2 and the box is now at layer 3.

Starting with Hollywood 2.0, there is a new command available: SetLayerName(). You can use it to give your layers a unique name so you can simply address the layer through its name a instead of its id. This is very useful if you have many layers and you do not want to remember their ids. All functions that work with layers accept a name string in addition to a numeric id now. Here is our example again:

 
Layer id 1: Brush 1 at coordinates #CENTER : #CENTER
Layer id 2: A red pixel at 100 : 100
Layer id 3: Text "Hello World!"
Layer id 4: A blue box at 50 : 50 with dimensions 100 : 100

Now we do the following:

 
SetLayerName(1, "brush: 1")
SetLayerName(2, "red pixel")
SetLayerName(3, "text: hello world")
SetLayerName(4, "blue box")

Now we could remove layer 2 by calling

 
RemoveLayer("red pixel")

We do not have to care about the fact that the layer ids have changed now because all layers have names and so we can easily address them.

Please keep in mind that layers are always background picture private. For example if you now call a

 
DisplayBGPic(3)

you will not have any layers you could access. If you call now

 
DisplayBGPic(2)

again, Hollywood will display your background picture 2 together with all layers attached to it. So you can safely switch between background pictures and you do not have to display all your data again. If you have layers enabled, Hollywood will display all layers attached to a background picture automatically with DisplayBGPic().

To save memory it is advised however to call FreeLayers() when you do not need them any longer.

Please also make sure that you call EnableLayers() before displaying the objects you want to access as layers. For example, the following code will not work:

 
DisplayBrush(1, #CENTER, #CENTER)
EnableLayers()
Undo(#BRUSH, 1)

Every command that outputs graphics will check if layers are enabled and if they are, it will add a layer. Therefore the above example cannot work because layers are enabled after DisplayBrush() is called. So you have to use the following code:

 
EnableLayers()
DisplayBrush(1, #CENTER, #CENTER)
Undo(#BRUSH, 1)

This will work fine then.

If you plan to use layers in your whole application, it is recommended to call EnableLayers() right at the start of your code. This ensures that layers are always enabled.

Once a layer is on the display you can change its appearance very easily. Hollywood offers a wide range of layer manipulation function. The most powerful of them is SetLayerStyle() which can be used to change nearly all of the layer's attributes with just a single call. It can even change the attributes of multiple layers at once! Furthermore, you can rotate a layer using RotateLayer() and scale it using ScaleLayer(). It is also possible to show and hide layers with an effect from Hollywood's wide range of transition effects using the ShowLayerFX() and HideLayerFX() functions.


Show TOC