Skip to main content

Using Overwolf windows

Every Overwolf app uses Overwolf windows, whether in-game or on desktop. When developoing your app, the first step is declaring your app’s windows in the manifest.json file. You will NOT be able to create an Overwolf window without declaring it in the manifest.

You should declare a window class with its properties, then create and use an instance of that class. It's not currently possible to create multiple instances of a window class. Having many windows is discouraged because it might make your app more complicated than required or hurt the user's experience.

Declaring windows in manifest.json​

Declare your window objects by giving the object a name under the data.windows section. Add the properties you want the window to inherit when its created. Properties can include size, starting position, transparency and others.

For example:

 "data": {
        "start_window": "MainWindow",
        "windows": {
            "MainWindow": {
                "file": "Files/index.html",
                "transparent": true,
                "resizable": true,
                "size": {"width": 400, "height": 300},
                "min_size": {"width": 200, "height": 200},
                "max_size": {"width": 600, "height": 500}
            }
        }
 }

Essential window properties​

  • start_window—the default window which is the first to be shown when your app is launched. A Start Window MUST exist in order for the other windows to exist. If your main window is closed, all other app windows will be closed as well resulting in your app closing in its entirety.

  • file—the core HTML file which will be loaded into your window when it's opened. This can only be a local file. If you host your app on a remote web-site, you’ll have to build a local page that redirects to that website. In this case, make sure that the block_top_window_navigation property is set to false.

  • transparent—set this property to true so that your window will have no borders or background. Any part of your window that has a transparent background (background: transparent) will become a see-through area that blends with the game or desktop behind it. If this property is set to false, your window will have the common Overwolf window borders and white background.

  • grab_keyboard_focus—default is false. When set to true, this opens your window and automatically takes the user's keyboard focus and any keystrokes to the app instead of the running game. It is recommended to keep this set to false since some windows open surprisingly or automatically or by using a hotkey. grab_focus_on_desktop is the complementary property which describes out-of-game behavior and is set to true by default because the user is not playing when launching the app in desktop mode.

  • size—sets the size of your app window when its first opened. If your window is not resizable, this will be its permanent size. 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 open with the same size as it was closed with by the user. This persists even if the app is uninstalled and then reinstalled. For more information, see window size tips.

  • min_size and max_size— define the smallest and largest your app window can be in pixels.

Accessing your declared windows​

Use the name and id properties to identify windows.

Using window.name​

When accessing a window by name, you need to use the name value exactly as it appears in your manifest.json window declaration.

A window name is always a value declared by the developer of the app.

Using window.id​

Accessing a window by id is possible when you already have an instance of your window declared. You can retrieve this id the following functions:

A window id is set by the Overwolf API. This value is subject to change in future Overwolf versions, so avoid using hardcoded values.

Generating multiple instances of the same window class is not supported. Most functions will accept name or id properties to reference the correct window.

How to create a new window​

Call obtainDeclaredWindow()​

First call overwolf.windows.obtainDeclaredWindow() using the window’s name as declared in your manifest.json. This will create a single instance of your window and return basic window information including id, name, width, height and other properties.

Call restore()​

Then call overwolf.windows.restore() using either the window's name or id retrieved from obtainDeclaredWindow.

warning

Skipping obtainDeclaredWindow() and calling restore() with the window’s name will not work unless the window is already instantiated and minimized (in which case it will be restored).