Introduction

Welcome to the Uphany Shell documentation page!

Shortcuts

This are the shortcuts that are available while running Uphany Shell:

CTRL + SHIFT + ESC: Quits Uphany Shell and return to explorer

CTRL + SHIFT + U: Opens Uphany Shell's settings

Themes

Uphany Shells starts up and looks for theme.json files to load by default. The current defaults are in themes/default/taskbar and themes/default/background. They are the configs for the windows that should be opened for that theme. The following are the json parameters that can be specified:

theme.json

{
    // Unique ID, can be anything right now. No space.
    "themeID": "default-taskbar",

    // Identifiable Name
    "themeName": "Default Uphany Shell Taskbar",

    /* 
     *  Settings Array
     *
     *      enableAutomaticReload: Whenever a file changes in this file's directory, it will reload all files and create windows anew with the changes.
     */
    "settings":
    {
        "enableAutomaticReload": true
    },

    /*
     *  Elements Array
     *
     *      Each element is a theme window you want to create. Each element is composed of the following properties:
     */

    "elements":
    [
        {
            // Identifiable Window Name
            "name": "taskbar",

            // Window's top left x position in percentage of monitor from 0 to 1
            "x": 0,

            // Window's top left y position in percentage of monitor from 0 to 1
            "y": 0.973,

            // Window's width in percentage of monitor from 0 to 1
            "width": 1,

            // Window height in percentage of monitor from 0 to 1
            "height": 0.027,

            // HTML file to load, relative to this file
            "url": "taskbar.html",

            // Type of window, choose between taskbar, background, titleless or normal.
            //  taskbar: titleless and always on top
            //  background: titleless and always on bottom
            //  titleless: does not have window's default window border and top
            //  normal: regular os window.
            "type": "taskbar",

            // Make the background of the window transparent
            "transparent": true
        }
    ]
}

How to load a new theme

By pressing CTRL+SHIFT+U you can open the Uphany Settings window. You will see all the monitors listed, you can then change the current theme on that monitor by pressing the edit button besides the type of theme you want to load.

Creating a new theme

All that is needing is to create a JSON text file. Use the content from the sample

Working with transparent window

After creating a transparent window, in order to make it fully transparent you must use css to set the background color to transparent of the html and body.

API Reference

All html pages contain the Shell object, which contains all functions to interact with the desktop and system in various ways. All objects and functions presented in the API are in the main Shell object. Documentation uses typescript notation to specify the members and classes in an object, note however there are no actual class definitions. Outside of that, all html pages have most of ES6 javascript functionality

Audio

// Mute audio
Shell.Audio.SetMute(true);

Audio.SetMute(bool mute)

Sets the current mute state of the default audio device

// Set volume to max
Shell.Audio.SetVolume(100);

Audio.SetVolume(int volumeLevel)

Pass a number from 0 to 100 to set the current volume of the default audio device

// Get list of audio devices
Shell.Audio.GetDevices();

Audio.GetDevices() -> array

Returns an array of all output AudioDevice

// Get list of audio devices
Shell.Audio.SetDefaultDevices(audioDeviceId);

Audio.SetDefaultDevice(string deviceId)

Accepts the id of an AudioDevice and sets it as the default audio device

AudioDevice

Class

Retrieved with Audio.GetDevices()

id : string

Special string identifier

name : string

User friendly audio device name

CreateContextMenu(array)

Spawns a dynamic context menu. Accepts an array of elements to define the context menu options Each element must be an array with 2 values, first value being the option name (displayed title), and second must be a function to run on click, or an array to present a sub context menu

Shell.CreateContextMenu([
  [ "Option 1", () => console.log("Option 1 Clicked") ],
  [ "Option 2", () => console.log("Option 2 Clicked") ],
  [ "Nested Options",
    [
      [ "Nested Option 1", () => console.log("Nested Option 1 Clicked") ]
    ]
  ]
]);

Desktop

GetIcons() -> array

Returns an array of DesktopIcon

DesktopIcon

Structure

displayName : string

path : string

type : DesktopIconType

DesktopIconType

Enum

Unknown

Invalid file type

Folder

The path points to a folder

File

The path points to a regular file

Archive

The path points to a compressed file

Shortcut

The path points to a shortcut file

Executable

The path points to a executable

OpenFileModal(object) -> promise

Returns a promise. Will open a File Modal window to the user to select one or multiple files. Will resolve the promise with the path the user selected, or reject the promise if the user canceled the selection

Shell.OpenFileModal({
  // File modal title
  title: "Select JSON file",

  // Name shown on the file extension selection list
  typeName: "JSON",

  // Array of type wildcards to allow
  types: ["*.json"]
})
.then(filePath => console.log(filePath));

Quit()

Quits Uphany Shell completely and restores Window's Explorer

Shell.Quit();

StartMenu

StartMenu.GetPrograms() -> array

Returns an array of all program listing, as presented by the Window's native start menu

let list = Shell.StartMenu.GetPrograms();

System

Shell.System.Shutdown();

Shutdown()

Shutdown the computer

Shell.System.Restart();

Restart()

Restarts the computer

let username = Shell.System.GetUsername();

GetUsername() -> string

Get the username of the current user

TaskEvent

Enum Enum value returned by Tasks GetAll and BindEvent callback parameter

TaskEvent.Created

A task was created

TaskEvent.Destroyed

A task was destroyed

TaskEvent.Focus

A task has been focused

TaskEvent.IconChange

Task event for when the icon changes

TaskEvent.TitleChange

Task event for when the title changes

TaskEvent.Unfocus

A task has been unfocused. This task only runs specifically when a task unfocused and no new task is focused

Tasks

let tasks = Shell.Tasks.GetAll();

Tasks.GetAll() -> array

Returns array of all active Window's Tasks

Shell.Tasks.Focus(taskId);

Tasks.Focus(string taskId)

Focuses the specified task

Shell.Tasks.Minimize(taskId);

Tasks.Minimize(string taskId)

Minimizes the specified task

Shell.Tasks.Close(taskId);

Tasks.Close(string taskId)

Quits the specified task

Shell.Tasks.TrayIconHoverEnter(taskId);

Tasks.TrayIconHoverEnter(string taskId)

Sends the tray icon hover enter event to the specified task

Shell.Tasks.TrayIconHoverLeave(taskId);

Tasks.TrayIconHoverLeave(string taskId)

Sends the tray icon hover leave event to the specified task

Shell.Tasks.Run(executablePath, false);

Tasks.Run(string executablePath, bool runAsAdmin = false)

Runs the specified executable

Shell.Tasks.GetExecutableIconPath(executablePath).then(p => element.src = p);

Tasks.GetExecutableIconPath(string executablePath) -> promise

Returns a promise, when resolved it will pass the image url of the executable's icon Url is ready to use as an image's source

let defaultIcon = Shell.Tasks.GetDefaultIcon();

Tasks.GetDefaultIcon() -> string

Returns an image url to the default icon to use when application does not have icon

let folderIcon = Shell.Tasks.GetFolderIcon();

Tasks.GetFolderIcon() -> string

Return image url to use for folders

Shell.Tasks.BindEvent(function(task_event, task) {
  // Do something with the task
});

Tasks.BindEvent(function callback)

Register a task event callback. Will be called every time a task event occurs. Receives TaskEvent and a WindowTask as parameters.

ThemeElementType

Enum

Specified the kind of window

ThemeElementType.Normal

A normal window with titlebar

ThemeElementType.Titleless

A borderless, titleless window

ThemeElementType.Titleless_Tool

A borderless, titleless window that does not show on the taskbar

ThemeElementType.Taskbar

Same as ThemeElementType.Titleless_Tool, but the window is always forced to the front

ThemeElementType.Background

Same as ThemeElementType.Titleless_Tool, but the window is always forced to the back

ThemeSettings

ThemeSettings saves values to a theme specific setting file

let folderIcon = Shell.ThemeSettings.Set("key", "value");

ThemeSettings.Set(string name, string value)

Sets the property name to the specified value. If you want to store an object/array use JSON.stringify on it

let value = Shell.ThemeSettings.Get("key");

ThemeSettings.Get(string name) -> string

Retrieve the saved property

Window

The Window Shell object is used to control the current HTML window

Shell.Window.Create({
  // top left x position of the new window
  x: 0, 

  // top left y position of the new window
  y: 0, 

  // width of the new window
  width: 0, 

  // height of the new window
  height: 0, 

  // A Shell.ThemeElementType enum value
  type: Shell.ThemeElementType.*, 

  // A Shell.WindowPosType enum value
  posType: Shell.WindowPosType.*, 

  // Unique id for this window.
  // If reused and original window is still active, it will refresh the original window
  id: "Window Id", 

  // Url of the page to load
  // Url must the relative to initial url of this theme element.
  url: "index.html"
});

Window.Create(object)

Creates a new windows, the following parameters can be passed in as an object

Shell.Window.Close();

Window.Close()

Close the current window

Shell.Window.Hide();

Window.Hide()

Will minimize the current window

Window.Show()

Unminize and focuses the current window

Window.GetPos(WindowPosType posType) -> object

Gets the current position of the window, specify postType to a WindowPosType or WindowPosType.Global if none defined. Returns an object with x and y based on the specified WindowPosType

Shell.Window.GetPos({
  posType: Shell.WindowPosType.*
});

Window.MoveTo(object)

Moves the current window to the specified position. Pass x, y and your desired WindowPosType

Shell.Window.MoveTo({
  x: 100,
  y: 0,
  posType: Shell.WindowPosType.*
});

MoveBy(object)

Moves the current by the specified amount relative to the current position

Shell.Window.MoveBy({
  x: 100,
  y: 0
});

Window.Resize(int width, int height)

Resize the current window to the specified size

Window.BindEvent(function((WindowEvents)[#windowevents]) callback)

Add a callback function every time a window event occurs. Callback function must accept a single (WindowEvents)[#windowevents] enum value

Window.OpenInspector()

Opens a inspector view for the current window in a separate window

Window.Maximize()

Maximizes the current window

Window.Minimize()

Minimizes the current window

WindowEvents

Enum Values received by the Window's BindEvent callback

WindowEvents.Focus

The current window has gained focus

WindowEvents.Unfocus

The current window has lost focus

WindowPosType

Enum

Enumerator used to define the position type.

WindowPosType.Local

This type indicates a position relative to the top left of the window

WindowPosType.Monitor

This type indicates a position relative to the top left of the monitor

WindowPosType.Global

This type indicates a position relative to the top left of the main monitor

WindowTask

Class Object returned by Tasks' GetAll and BindEvent callback

id : numeric

Unique numeric identifier. Is reused

title : string

Title of the task

active : boolean

Is the current task the current active application?

execName : string

Name of executable

execPath : string

Full path to executable

execID : string

Unique identifier specified by the executable, or the program's name if none specified

iconPath : string

Path to load the image icon

isWindow : boolean

Is this a window application, or a tray icon