@DISPLAY [id,] table
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:
X,Y:
BGPic:
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:
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:
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:
FullScreenScale
and FakeFullScreen
modes
below.
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)
SystemScale
mode will automatically scale your script to 1280x960 pixels so that it doesn't look
tiny just because the system uses a high-DPI monitor. Note that by default, using SystemScale
will activate the auto scaling engine. If you want it to use layer scaling instead, just
use the ScaleMode
tag to change this to layer scaling. Note that SystemScale
uses the same
scale mode as ScaleFactor
internally, so displays using SystemScale
will behave as if ScaleFactor
was specified. It is even possible to specify the ScaleFactor
tag on top of SystemScale
, in that
case the value specified in ScaleFactor
will be multiplied by host system's default scaling factor.
See Scaling engines for details. Note that on Windows you must also set the
DPIAware
tag to True
in the @OPTIONS preprocessor command in order to use
SystemScale
. See OPTIONS for details. (V8.0)
By default, windowed mode will be used.
Borderless:
True
if this display shall be a borderless
window. Defaults to False
.
Sizeable:
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:
True
, Hollywood will create a
fixed, non-draggable window. This is especially useful on
full screen displays. Defaults to False
.
Backfill:
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:
Color
, Gradient
,
Texture
or Picture
. The type must be passed as a
string here.
Color:
Color
as backfill type, pass the
desired backfill color in this field.
StartColor, EndColor:
Gradient
as backfill type, use these
two fields to define the start and end colors for the
gradient.
Brush:
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:
Picture
as backfill type, you can use
these two fields to position the picture on the screen.
They both default to #CENTER
.
HideTitleBar:
True
, the backfill will also shield
the host screen's title bar (for example Finder's title bar
on macOS 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:
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:
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:
Picture
you can specify a RGB color
here that shall be shown transparently. Defaults to
#NOTRANSPARENCY
. (V4.0)
ScalePicture:
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:
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:
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:
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:
False
. (V3.0)
NoModeSwitch:
True
, it will not be possible to
switch this display between windowed and full screen mode
by pressing the CMD+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:
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:
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
either the ScaleWidth
and ScaleHeight
arguments or the
ScaleFactor
or the SystemScale
display mode to define the
scaling dimensions (see below). See Scaling engines for more information on Hollywood's scaling engines. (V4.5)
ScaleWidth, ScaleHeight:
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:
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:
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:
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:
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:
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:
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:
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 macOS will always
use Quartz 2D. Defaults to False
. (V4.5)
NoClose:
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:
#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:
#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:
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:
#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:
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:
FillStyle
has been set to
#FILLTEXTURE
. See SetFillStyle for details. (V5.0)
GradientStyle:
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:
#FILLGRADIENT
. The angle is expressed in
degrees. Only possible for #LINEAR
and #CONICAL
gradients. (V5.0)
GradientStartColor, GradientEndColor:
#FILLGRADIENT
. (V5.0)
GradientCenterX, GradientCenterY:
#RADIAL
or
#CONICAL
. Must be a floating point value between 0.0
and 1.0. See CreateGradientBGPic for details. (V5.0)
GradientBalance:
#CONICAL
. Must be a floating point value between 0.0
and 1.0. See CreateGradientBGPic for details. (V5.0)
GradientBorder:
#RADIAL
. Must be a floating point value between 0.0 and
and 1.0. See CreateGradientBGPic for details. (V5.0)
GradientColors:
GradientStartColor
and GradientEndColor
tags
are ignored. See CreateGradientBGPic for details. (V5.0)
KeepScreenOn:
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
scripts that do not require user input. Defaults to
False
. (V5.1)
PubScreen:
HideFromTaskbar:
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:
True
. Defaults to False
. (V5.3)
Orientation:
#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:
DisableBlanker:
True
if you want to disable the screen blanker while this display
is open. Defaults to False
. (V6.0)
Menu:
Monitor:
Monitor
tag. This tag defaults to 1 which means that the display should open
on the primary monitor. (V6.0)
XServer:
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:
ScreenName:
RememberPosition:
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:
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:
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:
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:
True
. (V7.0)
NativeUnits:
True
, Hollywood will use the host system's native coordinate space and
units instead of pixels. This currently only has an effect on macOS 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:
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)
NoCyclerMenu:
False
. This is supported only on Android. Defaults to False
. (V8.0)
HideTitleBar:
True
to hide the status bar on iOS or the action bar on Android. By default,
both the status bar and the action bar are always visible. Defaults to False
. (V8.0)
Subtitle:
Title
tag above. By default, there is no subtitle. (V8.0)
SingleMenu:
True
. This is especially useful if there are only a few menu items and
it doesn't make sense to place them in submenus. This tag is only available on Android.
Defaults to False
. (V8.0)
ScaleFactor:
ScaleMode
tag (see above), this tag
can be used to apply a global scaling factor to your display. The scaling factor must be
specified as a fractional number indicating the desired scaling coefficient, e.g. a value
of 0.5 shrinks everything to half of its size whereas a value of 2.0 scales everything to
twice its size. Note that setting ScaleFactor
will make the script behave slightly different
than setting ScaleWidth
and ScaleHeight
(see above). The latter will enforce a fixed display size
which will never be changed unless the user manually uses the mouse to change the display size.
Setting ScaleFactor
, however, will apply the scale factor to all new BGPics and display sizes
so the display size may change if the BGPic size changes or the script changes the display size.
Thus, using ScaleFactor
is perfect for scaling a script for a high dpi display because it
makes sure that the script behaves exactly the same but just appears larger (or smaller if you want!).
You can also set the Mode
tag to SystemScale
to automatically apply the host system's scaling factor
to your display (see above). See Scaling engines for details. (V8.0)
ImmersiveMode:
ImmersiveMode
to one of the following tags. All those modes
only differ in the way the user can bring back the system bars and whether or not your
script is notified about it.
#IMMERSIVE_NORMAL:
ShowSystemBars
and HideSystemBars
event handlers.
#IMMERSIVE_LEANBACK:
ShowSystemBars
and HideSystemBars
event handlers.
#IMMERSIVE_STICKY:
#IMMERSIVE_NORMAL
except that there will
be no notification when the system bar visibility changes. Instead, the raw swipe
events will be forwarded to you even if they caused the system bars to reappear.
Note that both #IMMERSIVE_NORMAL
and #IMMERSIVE_LEANBACK
will notify your script about
system bar visibility changes using the ShowSystemBars
and HideSystemBars
event handlers.
You can listen to those events using InstallEventHandler().
See InstallEventHandler for details. (V9.0)
Palette:
#PALETTE_AGA
. See SetStandardPalette for a list of inbuilt palettes.
(V9.0)
FillPen:
Palette
tag is set (see above), you can use the FillPen
tag to set the pen that
should be used for filling the display's background. (V9.0)
SoftwareRenderer:
True
to disable Hollywood's GPU-accelerated
Direct2D renderer on Windows systems. Hollywood will use its CPU-based renderer for
maximum compatibility then. This is mostly useful for testing purposes. Normally, there
shouldn't be any reason for setting this tag to True
. (V9.0)
VSync:
True
to force Hollywood's renderer to throttle
refresh to the monitor's refresh rate. This means that you'll no longer have to use
functions like VWait() to throttle drawing. However, do note that if
you set this to True
, you must make sure to draw in full frames only otherwise drawing
will become extremely slow. Full frame drawing can be achieved e.g. by either using
a double buffer or by using BeginRefresh() and EndRefresh().
Also note that VSync
is currently only supported on Windows and only if Hollywood uses
its Direct2D backend. Direct2D is not available before Windows Vista SP2. (V9.0)
ScaleSwitch:
#DISPMODE_MODESWITCH
mode to
ChangeDisplayMode(), Hollywood will not change the monitor's screen
mode on systems where hardware-accelerated scaling is available. On those systems, Hollywood
will just simulate full screen mode by scaling the display to the monitor's current
resolution. Only on older systems or platforms that don't support hardware-accelerated
scaling will Hollywood switch the monitor to a new resolution. The reason why switching
the monitor's resolution is no longer done by default is that it often takes considerable
time for the monitor to do so and not all display devices support it (e.g. laptop screens
often don't support it). If you want to force Hollywood to always change the monitor's
resolution when going full screen and never simulate full screen mode by scaling, just set
this tag to True
. Defaults to False
. (V9.0)
UserTags:
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.
@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.