Name
DISPLAY -- define display attributes (V2.0)
Synopsis
@DISPLAY [id,] table
Function
This preprocessor command creates a new display using the attributes specified in the optional table argument. Specifying an identifier for the display is only needed if your script uses multiple displays. If you are using just a single display, you can leave out the identifier completely and Hollywood will then use the identifier 1 for the display. If you are using multiple displays, style guide suggests that you use the identifier 1 for your first/main display.

If you want to create displays dynamically at run time, you can use the function CreateDisplay() for this.

The style of the new display is configured by setting a number of tags in the optional table argument. The following style tags are currently supported by @DISPLAY:

Title:
Use this field to set the title for this display. This title will be shown then in display's window bar (if the window has a border). Default title is "Hollywood".

X,Y:
These two allow you to define where on the host screen this display should open. Using absolute values here is rather counterproductive because you mostly do not know the size of the screen your window will be opened on (except you are using full screen mode). It is wiser to use Hollywood's special coordinate constants here. If you do not set these fields, the display will always be opened in the center of the screen. You can also move the display later by calling MoveDisplay().

BGPic:
Specifies the BGPic that shall be attached to the new display. Every display needs an associated BGPic. Thus, if you do not specify this tag, Hollywood will create a new BGPic for this display automatically using the fill style specified in the FillStyle tag (see below) and the size specified in Width and Height. An exception is made for the display that uses the identifier 1: For reasons of compatibility the display number 1 will automatically be associated with the BGPic number 1 if there is one. (V4.5)

Width, Height:
You only have to use these fields if you did not specify a background picture in BGPic (see above) and if you want your display size's dimensions to be different from the default size 640x480. If this applies, set these fields to the desired dimensions and Hollywood will open such an initial display for you. These tags are ignored if you specify a BGPic. Starting with Hollywood 7.0 you can also set these tags to the special constant #NATIVE. In that case, Hollywood will use the dimensions of the display's host device.

Desktop:
If you set this field to True, the initial background picture will be a copy of your desktop screen. This can be used for some nice effects with that screen. Hollywood will also automatically open a borderless window if this field is True.

Mode:
This tag allows you to specify the mode the display should be opened in. You have to pass one of the following strings to this tag:

Windowed
Open display in windowed mode.

FullScreen
Open in full screen mode. This can change your monitor's resolution to the dimensions which fit best to your display's dimensions. If you don't want that, take a look at the FullScreenScale and FakeFullScreen modes below.

FullScreenScale
This is a special full screen mode which won't change your monitor's resolution. Instead, Hollywood's display will be resized to fit your monitor's dimensions. Additionally, this full screen mode will activate the auto scaling engine so that your display is automatically scaled to fit your monitor's dimensions. FullScreenScale will use auto scaling by default. If you would like it to use layer scaling, you have to set ScaleMode to #SCALEMODE_LAYER as well. FullScreenScale is especially useful on mobile devices whose display hardware has a hard-coded resolution and doesn't support resolution changes in the same way as an external monitor connected to a desktop computer does. The downside of FullScreenScale is that it is slower because Hollywood has to scale all rendering operations to the monitor's dimensions. (V7.0)

FakeFullScreen
Open in fake full screen mode. This means that Hollywood will not change the monitor's resolution but the backfill window will be configured to shield the desktop completely. Thus, the user gets the impression as if Hollywood was running full screen, although it is running on the desktop.

ModeRequester
This will open a display mode requester allowing the user to choose the desired full screen mode for this display.

Ask
This will open a requester asking the user to choose between windowed and full screen mode.

By default, windowed mode will be used.

Borderless:
Set this field to True if this display shall be a borderless window. Defaults to False.

Sizeable:
Set this field to True if this display shall be resizeable by the user. If Borderless is also set to True, the size widget will be invisible in the bottom right window corner. Defaults to False.

Fixed:
If you set this field to True, Hollywood will create a fixed, non-draggable window. This is especially useful on full screen displays. Defaults to False.

Backfill:
This tag can be used to configure the backfill settings for this display. Backfills can be used to create a shielding window that covers the whole area not occupied by your main display. They are only supported if Mode has been set to FullScreen or FakeFullScreen. You can use a static color as a backfill, a gradient, an image, or a texture. You have to pass a table in this tag. The following table tags are currently recognized:

Type:
This field is obligatory. It can be Color, Gradient, Texture or Picture. The type must be passed as a string here.

Color:
If you've specified Color as backfill type, pass the desired backfill color in this field.

StartColor, EndColor:
If you've specified Gradient as backfill type, use these two fields to define the start and end colors for the gradient.

Brush:
If you've specified Texture or Picture as backfill type, specify the identifier of the brush to use as the source image here. If you want to pass the file name directly, use the BrushFile tag instead.

X,Y:
If you've specified Picture as backfill type, you can use these two fields to position the picture on the screen. They both default to #CENTER.

HideTitleBar:
If you set this tag to True, the backfill will also shield the host screen's title bar (for example Finder's title bar on Mac OS X or the Workbench title bar on AmigaOS compatibles). Note that you can also specify HideTitleBar outside the Backfill tag because on Android and iOS HideTitleBar can also be used without a backfill. When used without a backfill, HideTitleBar hides the device's status bar on Android and iOS.

BrushFile:
If you've specified Texture or Picture as backfill type, you can specify the file name of the brush to use as the source image here. The file specified here will be linked to the applet/executable on compilation unless you set LinkBrushFile to False. If you want to pass a brush identifier, use the Brush tag instead. (V4.0)

LinkBrushFile:
If BrushFile is specified this tag can be used to declare whether or not the brush file shall be linked into the applet/executable on compilation. Defaults to True which means that the brush file will be linked. (V4.0)

Transparency:
If backfill type is Picture you can specify a RGB color here that shall be shown transparently. Defaults to #NOTRANSPARENCY. (V4.0)

ScalePicture:
If backfill type is Picture you can use this tag to define whether or not the picture shall be scaled to fit the backfill window's dimensions. Defaults to False. (V4.0)

SmoothScale:
Set this tag to True if you want to have interpolated scaling of the picture that should be used as a backfill image. This tag is only handled if ScalePicture has been set to True. Defaults to False. (V6.0)

ScrWidth, ScrHeight:
If Mode has been set to FullScreen, these tags allows you to set the desired dimensions for the full screen mode. Defaults to what has been set when creating the display. Starting with Hollywood 7.0 you can also set these tags to the special constant #NATIVE. In that case, Hollywood will use the dimensions of the display's host device. (V3.0)

ScrDepth:
If Mode has been set to FullScreen, this tag allows you to set the desired depth for the full screen mode. Defaults to what has been set when creating the display. (V3.0)

HidePointer:
If you specify this field, the mouse pointer will automatically be hidden as soon as Hollywood enters full screen or fake full screen mode. This argument has the advantage over the HidePointer() command in that it only hides the mouse pointer in full screen mode. If Hollywood opens in windowed mode, the mouse pointer will remain visible because hiding the mouse pointer in windowed mode usually causes confusion with the user. Defaults to False. (V3.0)

NoModeSwitch:
If you set this tag to True, it will not be possible to switch this display between windowed and full screen mode by pressing the COMMAND+RETURN (LALT+RETURN on Windows) hotkey. If NoModeSwitch is specified, this display will always remain in its initial display mode and no switches between windowed and full screen will be allowed. Defaults to False. (V3.0)

NoHide:
Set this tag to True if you do not want this display to have an iconify widget. If you do not specify this tag, your display will always get an iconify widget. Defaults to False. (V4.5)

ScaleMode:
By setting this argument, you can choose a scaling engine for this display. ScaleMode can be set to one of the following parameters: #SCALEMODE_LAYER (uses layer scale engine), #SCALEMODE_AUTO (uses auto scaling engine) or #SCALEMODE_NONE (uses no scaling engine). If ScaleMode is not specified, the display's scaling mode will be set to #SCALEMODE_NONE, i.e. no scaling is active. When specifying ScaleMode, you will usually also want to set the ScaleWidth and ScaleHeight arguments to define the scaling dimensions (see below). See Scaling engines for more information on Hollywood's scaling engines. (V4.5)

ScaleWidth, ScaleHeight:
These two can be used to specify the desired scaling dimensions if a scaling engine is active (check the documentation of ScaleMode above). You can pass the size either as a direct value or you can pass a percentage string (i.e. ScaleWidth="200%"). If you pass a percentage string, the scaling size is set relative to the original size (i.e. ScaleWidth="200%" means twice the original width). Starting with Hollywood 7.0 you can also set these tags to the special constant #NATIVE. In that case, Hollywood will use the dimensions of the display's host device. (V4.5)

SmoothScale:
If ScaleMode is set, you can use this argument to specify whether or not Hollywood shall use anti-aliased scaling. Defaults to False which means no anti-aliasing. Note that anti-aliased scaling is much slower than normal scaling. (V4.5)

Hidden:
Set this to True if you want this display to be initially hidden. If you set this to True, the display will not be shown until you call OpenDisplay() on it. You could also use this tag to run a Hollywood script that does not open a display at all but please keep in mind that some commands (e.g. WaitLeftMouse()) only work with a visible display. (V4.5)

Active:
This tag allows you to specify the display that will be active on startup. Please note that only one display can be the active one so it is not valid to set Active to True for multiple displays. This will yield undefined results. If you do not specify Active for any of your displays, Hollywood will make the display number 1 the active one by default. (V4.5)

DragRegion:
This tag allows you to define a custom drag region for this display. Custom drag regions are only supported for borderless displays, so you need to set Borderless to True too if you use this tag. You can define multiple drag regions with this tag; this is why you have to pass a table which contains a list of tables, each defining a single rectangular region, to this tag. Each table in the list must have the following tags specified: Type, X, Y, Width, and Height. Type currently must always be set to #BOX because currently, only rectangular regions are supported. This might sound pretty complicated, but in fact it is really easy. All you have to remember is to pass a list of tables to this tag. Even if you only want a single rectangular drag region, you have to pass a list. See below for an example. (V4.5)

SizeRegion:
This tag allows you to define a custom size region for this display. Custom size regions are only supported for borderless displays, so you need to set Borderless to True, too if you use this tag. You can define multiple size regions with this tag; this is why you have to pass a table which contains a list of tables, each defining a single rectangular region, to this tag. Each table in the list must have the following tags specified: Type, X, Y, Width, and Height. Type currently must always be set to #BOX because currently, only rectangular regions are supported. This might sound pretty complicated, but in fact it is really easy. All you have to remember is to pass a list of tables to this tag. Even if you only want a single rectangular size region, you have to pass a list. See below for an example. (V4.5)

Layers:
Set this tag to True if you want to enable layers for this display. If you set this tag to True, you do not have to call EnableLayers() for this display again. See Layers introduction for more information on layers.. This tag is set to False by default. (V4.5)

UseQuartz:
This tag is only supported if Hollywood is running on Mac OS X. If you set this tag to True, this display will draw its graphics using the Quartz 2D API. If it is set to False, QuickDraw will be used. Note that this argument is only supported by the PowerPC version of Hollywood. The x86/x64 versions of Hollywood for Mac OS X will always use Quartz 2D. Defaults to False. (V4.5)

NoClose:
Set this tag to True if this display shall not have a close box in its window frame. Think twice before using this tag because it might confuse the user and you must provide a replacement for closing the display (e.g. by listening to the escape key etc.). Defaults to False. (V4.5)

FitScale:
This tag is only handled when either #SCALEMODE_AUTO or #SCALEMODE_LAYER is active in ScaleMode (see above). In that case, setting FitScale to True will set the scaling resolution of the display to the current screen's resolution so that the script will always fill out the whole screen. This is basically the same as passing the current screen's dimensions in ScaleWidth and ScaleHeight. Note that using FitScale might distort the appearance of your script in case the current screen resolution uses a different aspect-ratio than your script. To prevent distortion, you have to use KeepProportions (see below). Defaults to False. (V4.7)

KeepProportions:
This tag is only handled when either #SCALEMODE_AUTO or #SCALEMODE_LAYER is active in ScaleMode (see above). In that case, passing True here will not allow the user to distort the resolution of the current script by resizing the window to odd sizes. Instead, black borders will be used to pad the non-proportional window regions. The display itself will always keep its aspect-ratio. This is very useful for scripts that should not be distorted. (V4.7)

FillStyle:
This tag allows you to define a background fill style for this display. This tag is only handled if the BGPic tag is not specified. The default setting for this tag is #FILLCOLOR. See SetFillStyle for information on all available fill styles. (V5.0)

Color:
This tag is only handled if you did not specify a BGPic and fill style is set to #FILLCOLOR. In that case, you can use this tag to specify the color for the background picture that will be automatically created for this display.

TextureBrush:
If the FillStyle tag has been set to #FILLTEXTURE, you can use this tag to specify the identifier of the brush that shall be used for texturing. (V5.0)

TextureX, TextureY:
These tags control the start offset inside the texture brush and are only supported if FillStyle has been set to #FILLTEXTURE. See SetFillStyle for details. (V5.0)

GradientStyle:
If the FillStyle tag has been set to #FILLGRADIENT, you can use this tag to specify the gradient type to use. This can be #LINEAR, #RADIAL, or #CONICAL. (V5.0)

GradientAngle:
Specifies the orientation of the gradient if filling style style is set to #FILLGRADIENT. The angle is expressed in degrees. Only possible for #LINEAR and #CONICAL gradients. (V5.0)

GradientStartColor, GradientEndColor:
Use these two to configure the colors of the gradient if filling style is set to #FILLGRADIENT. (V5.0)

GradientCenterX, GradientCenterY:
Sets the center point for gradients of type #RADIAL or #CONICAL. Must be a floating point value between 0.0 and 1.0. See CreateGradientBGPic for details. (V5.0)

GradientBalance:
This tag controls the balance point for gradients of type #CONICAL. Must be a floating point value between 0.0 and 1.0. See CreateGradientBGPic for details. (V5.0)

GradientBorder:
This tag controls the border size for gradients of type #RADIAL. Must be a floating point value between 0.0 and and 1.0. See CreateGradientBGPic for details. (V5.0)

GradientColors:
This tag can be used to create a gradient between more than two colors. This has to be set to a table that contains sequences of alternating color and stop values. If this tag is used, the GradientStartColor and GradientEndColor tags are ignored. See CreateGradientBGPic for details. (V5.0)

KeepScreenOn:
This tag is only supported if Hollywood is running on Android and iOS. If you set this tag to True, battery saving mode will be disabled on mobile devices. This means that the device's screen will never be dimmed or turned off to save energy. Useful for presentations that do not require user input. Defaults to False. (V5.1)

PubScreen:
This tag can be used to specify the public screen this display should be opened on. You have to pass a string that contains the name of the public screen to use here. This is only supported on AmigaOS compatible operating systems. Please note that if you use multiple displays on multiple public screens, it is absolutely mandatory that the individual public screens use the same pixel format, i.e. it is not allowed to have one display on a 16-bit public screen while the other display is on a 32-bit public screen. The pixel format must be identical for all public screens. (V5.2)

HideFromTaskbar:
This tag is only supported if Hollywood is running on Windows. If you set this tag to True, your display will not get an entry in the Windows taskbar. This is useful if your application has added an icon to the system tray and you want it to be accessible from the system tray only. Defaults to False. (V5.3)

HideOptionsMenu:
This tag is only supported on Android devices. When the user opens the options menu on Android devices, Hollywood will allow the user to configure several display parameters like enabling or disabling autoscaling or layerscaling. If you do not want to give the user this possibility to change the display parameters via the app's options menu, set this tag to True. Defaults to False. (V5.3)

Orientation:
This tag is only supported on mobile platforms. It allows you to specify a hard-coded orientation for your script. If you set this tag, Hollywood will not react to orientation changes when the user rotates the device. Instead, it will keep the orientation mode that you specified here. The following values are possible:

 
#ORIENTATION_NONE
#ORIENTATION_PORTRAIT
#ORIENTATION_LANDSCAPE
#ORIENTATION_PORTRAITREV
#ORIENTATION_LANDSCAPEREV

Defaults to #ORIENTATION_NONE which means that there is no fixed orientation and that Hollywood should dynamically adapt to orientation changes. (V5.3)

NoHardwareScale:
This tag is only supported on Android. For performance reasons Hollywood will try to use hardware-accelerated scaling when autoscaling is enabled on Android devices by default. Some devices, however, do not implement hardware-accelerated scaling properly so if you experience strange behaviour when using autoscale mode, try to disable hardware-accelerated scaling using this tag and see if it helps. (V5.3)

DisableBlanker:
Set this tag to True if you want to disable the screen blanker while this display is open. Defaults to False. (V6.0)

Menu:
This tag can be used to attach a menu strip to this display. You have to pass the identifier of a menu strip that has been created using the @MENU preprocessor command or the CreateMenu() function to this tag. It is also possible to attach a single menu strip to multiple displays. See MENU for details. (V6.0)

Monitor:
This tag allows you to specify the monitor this display should be opened on. Monitors are counted from 1 to the number of monitors available to the system. Please note that if you set this tag, functions that accept display coordinates, e.g. MoveDisplay(), will interpret them as values relative to the origin of the monitor specified in the Monitor tag. This tag defaults to 1 which means that the display should open on the primary monitor. (V6.0)

XServer:
This tag can be used to specify the X Server that should host this display. By default, Hollywood will use the X Server that has been specified in the DISPLAY environment variable. If you want Hollywood to use a different X Server for your display, use this tag. This tag is only available in the Linux version of Hollywood. (V6.0)

ScreenTitle:
On AmigaOS, this tag can be used to set the text that should be shown in the screen's title bar whenever the display is active. By default, "Workbench screen" will be shown. This tag is only available in the AmigaOS compatible versions of Hollywood. (V6.0)

ScreenName:
If this display is to be opened in full screen mode, you can set the desired public screen name of the display's own screen with this tag. By default, Hollywood will use "HOLLYWOOD.X" where "X" is replaced by a vacant index. This tag is only available in the AmigaOS compatible versions of Hollywood. (V6.0)

RememberPosition:
Set this to True if you want this display to remember its position and size. This is obviously only possible with windowed displays. It won't work for full screen displays. You also have to specify a unique identifier for your application using the @APPIDENTIFIER preprocessor command if you want to use this tag. The display also must use a numeric identifier, i.e. you cannot use this tag for displays which use automatic id selection. Note that this tag can be overridden by the ‘-overrideplacement’ argument. If you start Hollywood or your compiled script using the ‘-overrideplacement’ argument, any saved position or size information is ignored. See Console arguments for details. (V6.1)

Maximized:
If you set this tag to True, the display will open in maximized mode. This is only possible if the display is sizeable. This tag is currently only supported on Windows. (V7.0)

TrapRMB:
On AmigaOS, if this is set to True, Hollywood will deliver right mouse button events also when a menu strip is associated with this display. The downside is that menu access will only be possible via the screen's title bar then. This tag is only handled in case your display has a menu strip, otherwise it has no effect at all. TrapRMB defaults to False which means that when a menu strip is associated with a display, right mouse button events aren't generated. This tag is only available in the AmigaOS compatible versions of Hollywood. (V7.0)

NoScaleEngine:
This tag is only handled if Mode is set to FullScreenScale for your display. In that case Hollywood will not use any scaling engine but will simply open your display in the same dimensions as the monitor's resolution. Your script then needs to manually adapt to the monitor's resolution. This allows you to write scripts which can dynamically adapt to different resolutions without simply scaling their graphics. (V7.0)

NoLiveResize:
On many platforms Hollywood will use live resizing when the user is resizing a display. This means that the display's contents will be automatically scaled while the user is resizing the display. If you don't want this, you can set this tag to True. (V7.0)

NativeUnits:
If you set this tag to True, Hollywood will use the host system's native coordinate space and units instead of pixels. This currently only has an effect on Mac OS and iOS because both operating systems use custom units instead of pixels when running on a Retina device. By default, Hollywood will enforce the use of pixels on Retina Macs and iOS devices for cross-platform compatibility reasons but you may want to override this setting by using this tag. (V7.0)

AlwaysOnTop:
If you set this tag to True, the display will always stay on top of other windows. Use this tag with care because it can be quite annoying to the user. (V7.1)

Many of the tags from above - especially the ones used to configure the appearance of the display - are also available from the command line to give the user some flexibility in controlling the appearance of the script. For example, it is possible to change the display mode of your script (windowed, full screen, etc.) or window style (borderless, sizeable, etc.) from the command line as well. If you do not want that, you have to use the -locksettings argument when compiling your scripts. This will forbid any user changes to the settings defined by you in this preprocessor command.

Inputs
table
a table containing one or more of the fields listed above
Example
@DISPLAY {Title = "My App", X = #LEFT, Y = #TOP, Width = 320,
    Height = 240, Color = #WHITE}
The above declaration opens a 320x240 sized display with a white colored background. The display is positioned at top-left edge of the host screen. The window title will be "My App".


@DISPLAY {Width = 640, Height = 480, Borderless = True,
DragRegion = {
{Type = #BOX, X=0, Y=460, Width=640, Height=20}, ; bottom drag bar
{Type = #BOX, X=0, Y=0, Width=20, Height=480} ; left drag bar
}
}
The code above will open a borderless 640x480 display. The drag bar of the display will not be in the top region of the display but it will be put into the bottom and the left regions of the display by specifying a custom drag region using the DragRegion tag. Note that the DragRegion tag always requires you to pass a list of rectangular regions, even if you are only using a single region. See above for more information.

Show TOC