overwolf.windows

Use the overwolf.windows API to create, interact and modify your app’s windows.

Declaring windows in the manifest.json

The starting point of working with Overwolf windows is declaring your app’s windows in the manifest.json file.

Under the section: data.windows – you declare your window objects by giving the object a name (which will be the way you create the windows from your code) and adding different properties that you want the window to inherit when created (transparency, size, starting position, etc.).

 

NOTE: You can NOT create an Overwolf window without declaring it in your manifest.json (window.open is not an Overwolf window).
The idea behind declaring the window in the manifest is that you are actually declaring a window class with properties and later creating an instance of that class.
Currently, you can NOT create multiple instances of a window class. (having many windows is discouraged – because it might make your app more complicated than required).

 

Your app will always have a “main” window, the main window is the first window to be shown when your app is launched, and it MUST exist in order for the other windows to exist – if you close your main window (or if the user closes it) all other windows will be closed (and, in fact, your entire app is turned off).

 

data.start_window is used to declare your app’s main window.

 

Here are some window properties worth mentioning:

  1. file – The most basic property of your window – this is the HTML file to be loaded into your window when it is opened. This can only be a local file. If you wish to host your app in a remote web-site, you’ll have to have a local page that redirects to the remote website (in such cases, you need to make sure that the block_top_window_navigation property is set to false)
  2. transparent – When set to true – your window has no window borders or background. Any part of your window that has a transparent background (“background: transparent;”) will be a see-through area that blends with the game or desktop.
    If this is false, your window will have the common Overwolf window borders and background (white)
  3. grab_keyboard_focus – The default value is false. Indicates whether the window will grab the keyboard focus when it is opened. Some windows can be opened automatically (e.g. based on a game event or a notification) or even by hotkey – you might not want to “steal” the keyboard focus from the game in such cases.
    grab_focus_on_desktop is the complementary property when outside of the game (however, unlike grab_keyboard_focus, the default value is true)
  4. size – Allows you to set the default size of the window when it is first opened. If your window is not resizable, this will be the constant size of your window.
    However, if your app is resizable – the app size is saved by Overwolf when closed so that the next time it is opened, it will preserve this size.

Accessing your declared windows

There are two types of window identifiers: name and id.

  • When accessing a window by it’s name – you need to pass the name value as it appears in your manifest.json window declaration.
  • When accessing a window by it’s id (which means you already have an instance of your window) – you need to retrieve this id from one of the overwolf.windows functions – currently, there are two:

A few notes to remember:

  1. A window name is always a value set/declared by the developer of the app
  2. A window id is always a value set by the Overwolf API. This value is subject to change in future Overwolf versions – so do not use hardcoded values.
  3. Because we currently do not support creating multiple instances of a window class – most functions that accept a window id also accept the window’s name.

How to open a new window

  1. Call overwolf.windows.obtainDeclaredWindow passing it the window’s name (as declared in your manifest.json) – this, in turn, will create an instance of your window (currently a single instance) and return basic window information (id, name, width, height etc…)
  2. Call overwolf.windows.restore passing it either the window name or id (the id is retrieved from obtainDeclaredWindow)
    NOTE: you can not skip overwolf.windows.obtainDeclaredWindow and call overwolf.windows.restore on the window’s name – it will just NOT work

Communication between windows

We’ve had a long history of methods used to communicate between Overwolf windows: localStorage events, cookies, etc…

We believe the best methods for communicating between windows of the same app are:

  1. overwolf.windows.getOpenWindows – this function allows you to get direct access to another window’s HTML Window object (and thus any JS function or DOM element).
    Using this method, you can share a “communications-bus” class between windows to allow them to register and send events to one another.
    NOTE: the current version of Overwolf only supports calling this function from the main window – this will be fixed in the near future.
  2. overwolf.windows.sendMessage – allows for sending messages directly to a window. The window receiving the message needs to listen on the: overwolf.windows.onMessageReceived event.

Transparent vs. Non-Transparent Windows

There are two main types of Overwolf app windows:

  1. A standard Overwolf window – This window has borders, window control buttons, opacity slider and a white background. In order to create this window you should set the ‘transparent’ window property in the manifest.json to ‘false’.
    "transparent": false

    In order to enable the maximize button, you need to set the 'show_maximize' property to 'true'.

    "show_maximize": true

    Here you can see an example for a standard Overwolf window:

  2. A “transparent” window – The term transparent might be a bit misleading, we consider the non-standard Overwolf window as a “transparent” window. This window has no borders, window control buttons or background – you should create those elements by yourself in your HTML/CSS.
    In order to create this window type, the ‘transparent’ property in the manifest.json should be set to ‘true’.
    "transparent" : true

    Here you can see a few examples of “transparent” windows in Overwolf apps:

    Here is a sample app that shows you how a “transparent” window should be created.

Best practices for using windows

  1. A window should call getCurrentWindow once during startup and then store the results in a variable for all later access. It can save a lot of code like:
    overwolf.windows.getCurrentWindow(function(result) {
        If(result.status === “success”) {
            overwolf.windows.dragMove(result.window.id);
        }
    });
  2. Overwolf apps are supposed to act like native desktop applications and not a website – therefore, don’t be tempted to create a full-screen transparent window with draggable HTML elements (e.g. <div>) as windows.
    Doing so will:
    1. Create a laggy experience
    2. Use a lot more CPU than required + can hurt the game’s performance
    3. Doesn’t support dual screens (i.e. dragging an element to the second screen)
    4. Risk of having the entire game covered with a broken html page
    5. Risk of grabbing the game’s focus without the gamer understanding why
  3. Overwolf apps are supposed to act like native desktop applications (part 2): Unlike a website, where it is “okay” to allow the user to select text from the page or perform a mouse-wheel movement on the page – in a desktop application, this doesn’t look/feel natural and might even break your app’s design.
    Treat your app as an application, not as a website.
  4. Keep it small – when Overwolf renders transparent windows – it does it’s best to do it efficiently, however, large windows do have a performance cost. If possible, don’t use large windows (It’s hard to define what a large window’s dimensions are, but we hope you get the point)
  5. Unless you know otherwise, always set: block_top_window_navigation to true in the manifest.
    This will make sure that no bugs or accidental calls like: window.top.href = … take control of your entire app.
    The only reason this isn’t set by default, is for backwards compatibility (e.g. apps that want to host themselves on a remote server)
  6. Consider using your main window as a hidden/background window (that the user doesn’t see) – it then can act as a controller/service that runs in the background and controls or communicate with other visible windows of the app. It is a MUST for apps that just want to popup notifications.
    This kind of “hidden” window should have the following App Window properties in the app’s manifest.json file:
    "index" : {
                    "file" : "index.html",
                                                             // window size is 0x0 px
                    "size": {                                       
                        "width": 0,                                 
                        "height": 0
                    },                                       // start position is 0,0
                    "start_position": {
                        "top": 0,                                     
                        "left": 0
                    },
                    "transparent": true,                     //  the window will be transparent and borderless
                    "clickthrough": true,                    // the window will not receive clicks in-game    
                    "show_in_taskbar": false,                // the window won't be displayed in the Windows taskbar
                    "desktop_only": true,                    // the window won't be shown in-game
                    "grab_keyboard_focus": false,            // the window won't grab the keyboard focus
                    "grab_focus_on_desktop": false,          //  the window won't grab focus on desktop
                }

Methods

getCurrentWindow(callback)

Version added: 0.78

Calls the given callback function with the current window object as a parameter.

  • Parameter: callback <function>

    A callback function which will be called with the current window object as a parameter. See ODKWindow.

Callback argument:
{
    "status": "success",
    "window": {
        "id": "Window_Extension_onemchifcjibofkgemelmnjeialamgnigfpomeih",
        "name": "index",
        "width": 891,
        "height": 753,
        "top": 179,
        "left": 354,
        "isVisible": true,
        "Parent": null
    }
}

obtainDeclaredWindow(windowName, callback)

Version added: 0.78

Creates or returns a window by the window name that was declared in the manifest.

  • Parameter: windowName <string>

    The name of the window that was declared in the data.windows section in the manifest.
  • Parameter: callback <function>

    A callback function which will be called with the requested window as a parameter. See ODKWindow.
Callback argument:
{
    "status": "success",
    "window": {
        "id": "Window_Extension_onemchifcjibofkgemelmnjeialamgnigfpomeih_settings",
        "name": "settings",
        "width": 420,
        "height": 274,
        "top": 403,
        "left": 760,
        "isVisible": false,
        "Parent": null
    }
}

dragMove(windowId, callback)

Version added: 0.78

Start dragging a window.

  • Parameter: windowId <string>

    The id or name of the window to drag.

  • Parameter: callback <function> — Optional

    A callback which is called when the drag is completed.
Callback argument:
{
    "status": "success",
    "horizontalChange": -51,
    "verticalChange": 6
}

dragResize(windowId, edge)

Start resizing the window from a specific edge or corner.

dragResize(windowId, edge, contentRect)

Version added: 0.100.0

Start resizing the window from a specific edge or corner.

  • Parameter: windowId <string>

    The id or name of the window to resize.

  • Parameter: edge <overwolf.windows.enums.WindowDragEdge>

    The edge or corner from which to resize the window.

  • Parameter: contentRect <ODKRect>

    The real content of the window (for the ingame drawing resizing white area)

changeSize(windowId, width, height, callback)

Version added: 0.78

Changes the window size to the new width and height, in pixels.

  • Parameter: windowId <string>

    The id or name of the window for which to change the size.

  • Parameter: width <int>

    The new window width in pixels.

  • Parameter: height <int>

    The new window height in pixels.

  • Parameter: callback <function> — Optional

    A callback which is called when the size change is completed with the status of the request.

Callback argument:
{
  "status": "success"
}

changePosition(windowId, left, top, callback)

Version added: 0.78

Changes the window position in pixels from the top left corner.

  • Parameter: windowId <string>

    The id or name of the window for which to change the position.

  • Parameter: left <int>

    The new window position on the X axis in pixels from the left.

  • Parameter: top <int>

    The new window position on the Y axis in pixels from the top.

  • Parameter: callback <function> — Optional

    A callback which is called when the position change is completed with the status of the request.

Callback argument:
{
  "status": "success"
}

close(windowId, callback)

Version added: 0.78

Closes the window.

  • Parameter: windowId <string>

    The id or name of the window to close.
  • Parameter: callback <function> — Optional

    Called after the window is closed.

minimize(windowId, callback)

Version added: 0.78

Minimizes the window.

  • Parameter: windowId <string>

    The id or name of the window to minimize.

  • Parameter: callback <function> — Optional

    Called after the window is minimized.
Callback argument:
{
  "status": "success",
  "window_id": "Window_Extension_mhlpbbigoglahfnkpekoamfknlnaneebgodenaam"
}

maximize(windowId, callback )

Version added: 0.81.7

Maximizes the window.

  • Parameter: windowId <string>

    The id or name of the window to maximize.

  • Parameter: callback <function> — Optional

    Called after the window is maximized.

Callback argument:
{
  "status": "success",
  "window_id": "Window_Extension_mhlpbbigoglahfnkpekoamfknlnaneebgodenaam"
}

restore(windowId, callback)

Version added: 0.78

Restores a minimized window.

  • Parameter: windowId <string>

    The id of the window to restore.

  • Parameter: callback <function> — Optional

    Called after the window is restored.

Callback argument:
{
  "status": "success",
  "window_id": "Window_Extension_mhlpbbigoglahfnkpekoamfknlnaneebgodenaam"
}

restore(windowName, callback)

Version added: 0.78

Restores a minimized window.

  • Parameter: windowName <string>

    The name (as declared in the manifest.json) of the window to restore. 

  • Parameter: callback <function> — Optional

    Called after the window is restored.

Callback argument:
{
  "status": "success",
  "window_id": "Window_Extension_mhlpbbigoglahfnkpekoamfknlnaneebgodenaam"
}

getWindowState(windowId, callback)

Version added: 0.85.0

Returns the state of the window (normal/minimized/maximized/closed).

  • Parameter: windowId <string>

    The id or name of the window.

  • Parameter: callback <function>

    Called with the window state.

Callback argument:
{
    "status": "success",
    "window_id": "Window_Extension_onemchifcjibofkgemelmnjeialamgnigfpomeih",
    "window_state": "normal"
}

getWindowsStates(callback)

Version added: 0.90.200

Returns the state of all windows owned by the app (normal/minimized/maximized/closed).

  • Parameter: callback <function>

    Called with an array containing the states of the windows.

Callback argument:
{
    "status": "success",
    "result": {
        "index": "normal",
        "settings": "minimized",
        "notice": "closed"
    }
}

openOptionsPage(callback)

Version added: 0.89.0

Opens the options page specified in the manifest file. Does nothing if no such page has been specified.

  • Parameter: callback <function>

    Opens the options page specified in the manifest file. Does nothing if no such page has been specified.

setDesktopOnly(windowId, shouldBeDesktopOnly, callback)

Version added: 0.89.100

Sets whether the window should be injected to games or not.

  • Parameter: windowId <string>

  • Parameter: shouldBeDesktopOnly <bool>

  • Parameter: callback <function>

Callback argument:
{
  "status": "success",
  "window_id": "Window_Extension_mhlpbbigoglahfnkpekoamfknlnaneebgodenaam"
}

setRestoreAnimationsEnabled(windowId, shouldEnableAnimations, callback)

Version added: 0.89.100

Sets whether the window should have minimize/restore animations while in game.

  • Parameter: windowId <string>

  • Parameter: shouldEnableAnimations <bool>

  • Parameter: callback <function>

Callback argument:
{
  "status": "success",
  "window_id": "Window_Extension_mhlpbbigoglahfnkpekoamfknlnaneebgodenaam"
}

setTopmost(windowId, shouldBeTopmost, callback)

Version added: 0.89.100

Change the window’s topmost status. Handle with care as topmost windows can negatively impact user experience.

  • Parameter: windowId <string>

  • Parameter: shouldBeTopmost <bool>

  • Parameter: callback <function>

Callback argument:
{
  "status": "success"
}

sendToBack(windowId, callback)

Version added: 0.91.200

Sends the window to the back.

  • Parameter: windowId <string>

    The id or name of the window.

  • Parameter: callback <function>

    Called with the result of the request.

Callback argument:
{
  "status": "success"
}

sendMessage(windowId, messageId, messageContent, callback)

Version added: 0.92.200

Sends a message to an open window.

  • Parameter: windowId <string>

    The id or name of the window to send the message to.

  • Parameter: messageId <string>

    A message id.

  • Parameter: messageContent <object>

    The content of the message.

  • Parameter: callback <function>

    Called with the status of the request

Callback argument:
{
  "status": "success"
}

setWindowStyle(windowId, style, callback)

Version added: 0.98.200

Add Window In Game styling (for example, allowing mouse clicks to be passed through the window into the game)

  • Parameter: windowId <string>

    The id or name of the window to send the message to.

  • Parameter: style <overwolf.windows.enums.WindowStyle>

    The style to be added

  • Parameter: callback <function>

    Called with the status of the request

Callback argument:
{
  "status": "success"
}

removeWindowStyle(windowId, style, callback)

Version added: 0.98.200

Remove window style

  • Parameter: windowId <string>

    The id or name of the window to send the message to.

  • Parameter: style <overwolf.windows.enums.WindowStyle>

    The style to be added

  • Parameter: callback <function>

    Called with the status of the request

Callback argument:
{
  "status": "success"
}

getOpenWindows(callback)

Version added: 0.92.200

Returns an array of all open windows as objects. The objects can be manipulated like any other window

  • Parameter: callback <function>

    A callback function which will be called with a map object of (window-name, Window Object) items

setMute(mute, callback)

Version added: 0.102.1

Set the current window mute state (on/off)

  • Parameter: mute <boolean>

    Window mute state (true - mute is on, false - mute is off)

  • Parameter: callback <function>

    Called with the result of the request

muteAll(callback)

Version added: 0.102.1

Mutes all sound sources for the current window.

  • Parameter: callback <function>

    Called with the result of the request.

isMuted(callback)

Version added: 0.102.1

Get the window’s mute state (true/false)

  • Parameter: callback <function>

    Called with the result of the request ({"muted": true/false}).

isWindowVisibleToUser(callback)

Version added: 0.102.1

Visibility state of the window – to be used only with windows without a transparent border. 

  • “hidden” – The window is completely hidden.
  • “fully” – The window is fully visible to the user.
  • “partial” – The window is partially visible to the user (and partially covered by other window/s).
  • Parameter: callback <function>

    Called with the result of the request:

    {"status": "error","reason": the reason}

    or

    {"status": "success","visible": "hidden" | "fully" | "partial"}

Callback argument:
{"status":"success","visible":"partial"}

Events How to use events

onMainWindowRestored

Version added: 0.85.0

Fired when the main window is restored.

onStateChanged

Version added: 0.85.0

Fired when the state of a window is changed.

Event value:
{
    "window_id": "Window_Extension_onemchifcjibofkgemelmnjeialamgnigfpomeih",
    "window_state": "minimized",
    "window_previous_state": "normal"
}

onMessageReceived

Version added: 0.92.200

Fired when this window received a message.

Event value:
{
  "id": "1",
  "content": "hello"
}

Types

ODKWindow

An object that holds information about a requested window.

Properties

id

Version added: 0.78

Gets the window ID.

Type: string

name

Version added: 0.86.0

Gets the window name as declared in the manifest.

Type: string

width

Version added: 0.78

Gets the window width in pixels.

Type: int

height

Version added: 0.78

Gets the window height in pixels.

Type: int

top

Version added: 0.78

Gets the window Y coordinate in pixels from the top of the screen.

Type: int

left

Version added: 0.78

Gets the window X coordinate in pixels from the left of the screen.

Type: int

isVisible

Version added: 0.78

Indicates if the window is currently visible or minimized.

Type: bool

parent

The parent window id

Type: string

overwolf.windows.enums.WindowDragEdge

Indicates the edge or corner to drag in order to move or resize a window.

Options

None

No window edge or corner to drag.

Left

Drag the left window edge in order to resize it.

Top

Drag the top window edge in order to resize it.

Bottom

Drag the bottom window edge in order to resize it.

TopLeft

Drag the top-left window corner in order to resize it.

TopRight

Drag the top-right window corner in order to resize it.

BottomLeft

Drag the bottom-left window corner in order to resize it.

BottomRight

Drag the bottom-right window corner in order to resize it.

overwolf.windows.enums.WindowStyle

An object which specifies the window style (used by setWindowStyle, removeWindowStyle

Options

InputPassThrough

Mouse and keyboard input will pass through the window to the game (no input blocking)

ODKRect

Properties

top

Version added: 0.100.0

Type: int

left

Version added: 0.100.0

Type: int

width

Version added: 0.100.0

Type: int

height

Version added: 0.100.0

Type: int