Shell Windows: Top-Level Layout Containers in RedEye

Shell windows are the top-level containers in every RedEye layout. Each window maps to a .NET Windows Forms Form and is declared with a <window> element at the root of an RWML file. Windows host all widgets and define the boundaries, appearance, and behavior of each desktop surface — your taskbar, start menu, desktop overlays, and any custom panels are each their own shell window. You can show, hide, or toggle windows at any time using expression functions.

Defining a window

A window is declared as a <window> element with attributes that control its type, size, position, and appearance. Widgets are nested directly inside the element.

<window
  id="myPanel"
  x="0"
  y="0"
  width="400"
  height="60"
  type="top"
  border="none"
  backgroundColor="#1e1e1e">

  <label text="Hello, RedEye" dock="fill" align="middleCenter" color="#ffffff" />

</window>

Window attributes

string

required

Unique identifier for the window. Required to reference the window in expression functions such as window.show, window.hide, and window.toggle. Also used in onDeactivate and other event expressions.

title

string

Title bar text. Shown in the taskbar and window title bar when border is not none.

number

default:"0"

Horizontal screen position in pixels. Supports RWML expressions, for example x="${taskbar.margin}".

number

default:"0"

Vertical screen position in pixels. Supports expressions, for example y="calc('${taskbar.margin} + ${taskbar.height}')".

width

number

default:"0"

Window width in pixels. Supports expressions.

height

number

default:"0"

Window height in pixels. Supports expressions.

type

string

default:"Normal"

Controls the Win32 window type and z-order behavior. Accepted values:

Value	Behavior
`Normal`	Standard resizable form shown in the taskbar.
`Shell`	Tool window hidden from the taskbar and task switcher. Cannot be closed by the user. Suitable for the taskbar itself.
`Top`	Tool window that stays above all normal windows without being always-on-top. Raises itself to the top on every `WM_WINDOWPOSCHANGING` message.
`TopMost`	Always-on-top tool window. Stays above all other windows at all times.
`Background`	Tool window locked to the bottom of the z-order. Suitable for desktop wallpaper replacements.

border

string

default:"Normal"

Windows Forms border style. Accepted values:

Value	Description
`None`	No border or title bar. Produces a borderless window.
`Normal`	Default resizable border with title bar.
`FixedDialog`	Fixed-size dialog border.
`FixedSingle`	Fixed-size single-line border.
`FixedToolWindow`	Fixed tool window border without minimize/maximize buttons.
`SizableToolWindow`	Resizable tool window border.

backgroundColor

string

Window background color as an HTML color string, for example #1e1e1e or black.

color

string

Default foreground (text) color inherited by child widgets that do not set their own color.

opacity

number

default:"1.0"

Window opacity from 0.0 (fully transparent) to 1.0 (fully opaque). Values below 1.0 require the OS compositor and may affect performance.

allowTransparency

boolean

default:"false"

When true, enables per-pixel alpha compositing using the transparency key color defined in the core config. Required for widgets that use isTransparent="true".

transparent

boolean

Alias for enabling transparency. When set, combines with allowTransparency to let the desktop show through transparent widget areas.

autoShow

boolean

default:"true"

When true, the window is shown automatically when the shell starts. Set to false for windows that should start hidden and be revealed on demand, such as a start menu or shutdown dialog.

allowClose

boolean

default:"true"

When true and allowRealClose is false, clicking the close button hides the window instead of destroying it. When false, the close button is disabled.

allowRealClose

boolean

default:"false"

When true, clicking the close button destroys the window. Use with caution: closing a shell-type window that is your primary taskbar can leave you with no shell controls.

minimizeButton

boolean

default:"true"

Show or hide the minimize button in the title bar. Has no visual effect when border="none".

maximizeButton

boolean

default:"true"

Show or hide the maximize button in the title bar. Has no visual effect when border="none".

autoSize

boolean

default:"false"

When true, the window resizes itself to fit its child controls.

padding

string

Inner padding between the window edge and its child widget area. Accepts one to four comma-separated pixel values: all, left,top,right,bottom.

icon

string

Resource ID of the window icon. Pass an empty string to hide the icon. When set, the icon bitmap is retrieved from the resource manager and used as the form’s Icon.

Event attributes

Event attributes on <window> follow the same on* convention as widget event attributes. Any Windows Forms Form event can be handled. Common examples:

onDeactivate

string

Expression evaluated when the window loses focus. Typically used to auto-hide panels: onDeactivate="window.hide(startMenu)".

Showing and hiding windows

You can control window visibility at any time using the built-in window expression functions. These are commonly used in onClick handlers and onDeactivate events.

Function	Description
`window.show(id)`	Show a hidden window.
`window.hide(id)`	Hide a visible window.
`window.toggle(id)`	Show the window if hidden, hide it if visible.

<!-- Show the start menu when the button is clicked -->
<button text="Start" onClick="window.toggle(startMenu)" />

<!-- Hide the start menu when it loses focus -->
<window id="startMenu" autoShow="false" onDeactivate="window.hide(startMenu)">
  ...
</window>

Use autoShow="false" together with onDeactivate="window.hide(id)" for pop-up panels like start menus and context overlays. The panel appears on demand and dismisses itself as soon as focus leaves it.

Example: the default taskbar window

The taskbar in the default RedEye layout demonstrates the typical configuration for a shell-type window — borderless, anchored to the top-left, hidden from the taskbar, and not closeable.

<window
  id="taskbar"
  x="${taskbar.margin}"
  y="${taskbar.margin}"
  width="${taskbar.width}"
  height="${taskbar.height}"
  type="shell"
  border="none"
  allowClose="false"
  backgroundColor="${theme.color.background}">

  <import from="config/ui/startButton.xml" />

  <windowList
    x="${taskbar.item.size}"
    y="0"
    width="calc('${taskbar.width} - ${taskbar.tray.width} - ${taskbar.item.size}')"
    height="${taskbar.height}">

    <panel
      width="${taskbar.item.size}"
      height="${taskbar.item.size}"
      margin="${theme.paddingMiddle},${theme.paddingMiddle},0,${theme.paddingMiddle}"
      padding="${theme.paddingMiddle}"
      backgroundColor="if(${window.isActive}, ${theme.color.backgroundActive}, ${theme.color.backgroundChild})">

      <image
        id="icon"
        src="${window.icon}"
        dock="fill"
        onClick="wapi.toggleWindow(${window.handle})"
        toolTip="${window.title}" />

      <contextMenu for="icon">
        <item action="wapi.closeWindow(${window.handle})">Close window</item>
        <item action="killProcess(${window.handle})">Kill process</item>
      </contextMenu>

    </panel>
  </windowList>

  <import from="config/ui/tray.xml" />

</window>

Key choices in this configuration:

type="shell" — hides the window from the Windows taskbar and task switcher and prevents the user from closing it.
border="none" — removes the title bar for a clean bar appearance.
allowClose="false" — disables the close gesture entirely so the shell cannot be accidentally dismissed.
All dimensions use theme variables so the layout adapts when variables are changed.

Built-in widgets

Reference for every widget you can place inside a shell window.

Expression functions

Full list of built-in functions available in attribute expressions, including window control functions.

Layout markup (RWML)

Learn the full RWML syntax, imports, scripts, and expression evaluation rules.

IShellWindow API

C# interface for programmatically controlling windows from plugins.

Get Started

Configuration

Widgets

Plugin Development

Shell Windows: Top-Level Layout Containers in RedEye

Defining a window

Window attributes

Event attributes

Showing and hiding windows

Example: the default taskbar window

Built-in widgets

Expression functions

Layout markup (RWML)

IShellWindow API

Build docs developers (and LLMs) love

Get Started

Configuration

Widgets

Plugin Development

Documentation Index

​Defining a window

​Window attributes

​Event attributes

​Showing and hiding windows

​Example: the default taskbar window

​Related pages

Built-in widgets

Expression functions

Layout markup (RWML)

IShellWindow API

Build docs developers (and LLMs) love

Defining a window

Window attributes

Event attributes

Showing and hiding windows

Example: the default taskbar window

Related pages