Decors

hBasic Manual

System Decors

Changes to the system bars appearence and behaviour.

Behaviour and Colors	Behaviour and appearence window_bg actionbar_bg matching shading
Decors	Opening parameters Immersive mode
Action Bar	i.e the Title bar
Known Issues	Known behaviours and glitches

See Also : system Directives

Behaviour and Colors

System bars appearence and behaviour.

Since hBasic v5.20, the app targets Api 35+. The following behaviour and appearences have changed as indicated below.

(hBasic targets to Api 35+)
Decors behaviours
	Status Bar		Navigation Bar
	Always transparent bg		Always Translucent bg*
Running Device Api	Shown (permanent)	Hidden (swipe down to show)	Shown (permanent)	Hidden (swipe up to show)
< Api 30 **	white text on window_bg	white text on scrim	white icon on window_bg	white icon on window_bg
>= Api 30	(light/dark) text on window_bg	white text on scrim	(light/dark) icons on window_bg or grey*	grey icons on translucent
>= Api 35 actionbar_on	(light/dark) text on actionbar_bg	white text on scrim	grey icons on window_bg	grey icons on translucent
>= Api 35 actionbar_off	(light/dark) text on window_bg	(same as above)	(same as above)	(same as above)

* Some manufacturers may furthur color the navigation bars which may override your settings.
** v5.25+ furthur added support for older devices between Api 23-30 for System bar text and icons.

window_bg is the background color of the window. It can be set with;

for console @@window_bg

also CONSOLE.SET "window_bg <color>"

for graphics GR.OPEN , , , , , , { window_bg_sexp }
for webview HTML.OPEN , , { window_bg_sexp }
for some dialogs DIALOG.SET

Normally you do not see this color because it is under several layers of other backgrounds,
but since hBasic v5.20, it can be used to determine the background color of the statusbar, navbar
and even the empty lines of the console or certain dialogs, depending on their configuration.

actionbar_bg is the background color of the actionbar. It can be set with;

for console CONSOLE.TITLE {title_sexp} {, textcolor_sexp} {, backcolor_sexp}
for graphics GR.TITLE {title_sexp} {, textcolor_sexp} {, backcolor_sexp}
for webview HTML.TITLE {title_sexp} {, textcolor_sexp} {, backcolor_sexp}

Note that for devices >= Api 35, the statusbar bg will follow the actionbar_bg only if the actionbar is on.
If the actionbar is off, the statusbar bg will follow the window_bg. (see action_bar).

System bars color matching.

As a general rule, if you set the actionbar_bg the same as the window_bg, you will have the same color for both the status bar and navigation bar.

(see also notch_hiding)

System bars Text and Icon shading.

Status bar text and Navigation bar icons can be made light or dark if they a permanently on (depending on the device Api), with;
CONSOLE.SET or the decors flags for GR.OPEN and HTML.OPEN
Here is a sample program.

@@hide_actionbar
@@window_bg "lightgrey"
CONSOLE.SET "StatusTxt dark"              % Api 23 and later
CONSOLE.SET "NavBarTxt dark"              % Api 26 to Api 34 only
? "Console> tap BackKey to graphics"
bk=0: do:pause 100: until bk

                            % dark text, no actionbar
sdark=1: ndark=1: nav=1: act=0: sta=1
decors = ndark*16 + sdark*8 + (!nav)*4 + act*2 + sta*1
winBG$ = "lightgrey"
                            % for GRAPHICS
GR.OPEN "grey", decors ,1, winBG$
gr.text.size 50 : gr.color "white"
gr.text.draw oT,50,50,"Graphics> tap BackKey to web"
gr.render
bk=0: do:pause 100: until bk
GR.CLOSE
                            % for WEB
HTML.OPEN decors, 1, winBG$
html.load.string "<big>Web> tap BackKey to End</big>"
    do : html.get.datalink data$
    until starts_with ("BAK:",data$)
HTML.CLOSE
cls: ? "Console> Done."
END

OnBackKey:
bk=1
Back.Resume

Status bar text shading only works for Api 23 and later.
Navigation bar icon shading only works between Api 26 - Api 34.

The above behaviours and effects only apply for a running program, i.e console, graphics and webview.
For Standard hBasic (i.e Editor, Load, Delete.. etc), the system will follow the manufacturer's theme if possible.

Decors for GR.OPEN and HTML.OPEN

GR.OPEN {<color>} ,{ decors_flags_nexp} ,{ orientation_nexp} {, window_bg_sexp}

HTML.OPEN { decors_flags_nexp} , { orientation_nexp} {, window_bg_sexp}

window_bg is an optional color string which sets the color of the background window (default black).
The statusbar and navbar may show the window_bg color depending on if they are hidden and the device's Api.

The legacy statusbar_flag_lexp has been replaced with decors_flags_nexp.

The first 3 bits control the visibilty of the system bars.

Bit	Set to mean	Default	Mask	In general
Bit 0	statusbar_SHOW	1 = show	1
Bit 1	actionbar_SHOW	0 = hide	2
Bit 2	navbar_HIDE	0 = show	4

Bit 3	dark_StatusText	0 = light text	8	( only works for Android 11+ )
Bit 4	dark_NavBar_Icons	0 = light icons	16	( only works Android 8-14 )
Bit 5	immersive_mode	0 = non-immersive	32	( only useful for notch area )

If you don't specify this flag (e.g ",,") the default is decors_flags=1 or bin ("001").
This shows the statusbar and navbar but hides the actionbar.

This is different from legacy Basic which hides the statusbar by default ("000").
The reason being that a hidden statusbar may affect the navbar color for Android 11+ for some devices.

Some examples;

actionbar hidden only, e.g Decors = bin ("001")     % i.e 1 *
statusbar hidden only, e.g Decors = bin ("010")     % i.e 2
navbar    hidden only, e.g Decors = bin ("111")     % i.e 7
statusbar shown only, e.g Decors = bin ("101")     % i.e 5
navbar    shown only, e.g Decors = bin ("000")     % i.e 0 *
show all bars          e.g Decors = bin ("011")     % i.e 3
hide all bars      e.g Decors = bin ("100")     % i.e 4

* The scheme is compatible with legacy programs which either sets the legacy flag to 0 or 1.

Example

Decors = bin("011") % show all
GR.OPEN "blue", Decors, 1 % last param is portrait

Alternatively

nav=0 : act=1 : sta=1 % show all
GR.OPEN "blue", nav*4 + act*2 + sta*1, 1

or
nav=1 : act=1 : sta=1 % nav to be inverted to show
GR.OPEN "blue", (!nav)*4 + act*2 + sta*1, 1

Hidden Bars

If either the statusbar or navbar is hidden, then you need a swipe from the top or bottom edge to show it.

It disappears after 3 secs.

Immersive Mode

This flag sets a full screen mode in which the status bar is forced hidden (even if you turned it on).
If either the action bar or navigation bar is on, then they will overlap with your content.
For some devices with a camera notch, it also enables your content to be displayed inside the notch area.
(This might not work for some devices).

Action Bar

The actionbar is the bar on the screen containing the Title and Menu. It is usually under the statusbar.
The Title, Subtitle and Colors can be changed with

CONSOLE / GR / HTML.TITLE and CONSOLE / GR / HTML.SUBTITLE

The Menu can be changed with MENU commands and is shared between console, graphics and webview.

Title Background color

The Title background is the actionbar background color. It can be set with CONSOLE.TITLE.
If you do not set this background color, then it will default to transparent and the window_bg color
(default black) will show through

Hiding the Console Action Bar

The console actionbar can be hidden before the program starts.
To hide the actionbar, use the directive @@hide_actionbar (see directives)
This can be useful to hide the image of the actionbar if you are immediatley going into the graphics screen.
To bring back the actionbar, use CONSOLE.TITLE.

Note: The Action Bar is the only bar that can be brought back after hiding for the console only.
It can only be hidden and brought back once.

If you have hidden the actionbar for graphics or webview with decors, it will not come back.

Known Issues

Stuck Navbar

On some older devices e.g Android 5, a hidden navbar might not disappear (after being swiped to show) if a dialog is up at the same time (e.g DIALOG.MESSAGE).

Notch Hiding

For devices that are able to hide the camera notch, they may keep the statusbar high to cover the notch.
In doing so, you will probably get a black statusbar bg instead of window_bg if the statusbar is permanent.