splash

User Docs




Dev Docs


Documentation


Installation Instructions

  • Click on this link to download splash for windows.
  • Now extract the archive. The folder you extract the archive to is important as you cannot change it later without interfering with the installation. Open the extracted folder and click on splash.exe. Wait for it to be installed.
  • Splash installation is complete. To install themes checkout this link.
  • Take note of important shortcuts. Ctrl+Q to quit, Ctrl+R to refresh and Ctrl+D to open dev tools.
  • Encountered an error? Report an issue on github or use the contact me form. I will revert back as soon as possible.

Installing a theme

  • Video instruction available at YouTube.
  • Download a desired theme from the themes section of the splash website.
  • Unarchive the theme, if it is archived.
  • Move the theme folder (generally with the same name as that of the theme) into any directory or location where it would be safe and not be deleted. I recommend you to move it inside the documents folder under the splash/themes folder.
  • Now with the splash application running go to the system tray (where audio and battery icons are in the taskbar).
  • There you will find the splash icon, right click on it would reveal a menu.
  • From the menu, choose the 'Load File' option.
  • The file explorer would appear, find the theme folder you moved/extracted and find a file with the same name as that of the theme itself and ends with '.html' extension. Example: themeName.html.
  • Select the 'Open' option at the bottom of the file explorer.
  • The selected file would be rendered. Check your homescreen.
  • If you encountered any problem during any procedure, please reach out to me via contact me page or by opening an issue on github.




Developer Documentation


Getting Ready

This section of the Documentation will guide you through the journey of creating stunning and productive desktop screens for the splash application.

Prerequisites:

  • Atleast Beginner level html, css and javascript knowledge.
  • Splash application is installed and you have read through the basic user documentation above.

It is important to understand how the splash application works in order to be comfortable developing with it.
Splash renders a frameless, non-movable and non-resizable window. The width of the window is equal to the width of the available screen and the height is equal to the total height minus 5 pixels. It cannot be made fullscreen by the user by using the F11 key will always be at the bottom of the z-index of the desktop. The window is capable of rendering html, css and javascript just as a browser can; complete with the chrome dev tools.

Important Shortcuts

Action Binding
Refresh Ctrl+R
Open Dev Tools Ctrl+D
Quit Ctrl+Q
For these shortcuts to work, splash window must be in focus.


config.json File

This file can be found in the documents under the splash folder of the PC. It contains the path of the html file to be rendered, and should not be disturbed.



File Structure

Whenever splash application is installed a folder by the name of splash is created under the documents directory of the PC. Splash icon is available at the system tray where you have options to load html file, refresh the window, and toggle dev tools.

While creating or adding themes, I recommend that you store the theme folder inside the splash folder where they cannot be disturbed. Always remember to refresh the splash window when updating any theme in development either by hitting Ctrl+r or using the system tray refresh option.



Hello World

This section will help you display a hello world message in your main window.

  • Create a new folder with whatever name you want to associate your theme with. Example: helloWorld
  • Head inside the folder and create the following files:
    • index.html
    • index.js
    • index.css
  • Open the index.html file inside a text editor and add the following code: 
    <!DOCTYPE html>                                         
<html> 
    <head> 
        <meta charset="UTF-8"> 
        <title>Splash</title> 
        <link rel="stylesheet" href="./index.css">
    </head> 
    
    <body> 
        <div> 
            <h1> 
                Hello World!!
            </h1> 
        </div> 

        <script src="./index.js"></script>
    </body> 

</html>

  • Save the index.html file and open the index.css file inside a text editor and add the following styles: 
    div {                                                      

    background-color: black; 
    flex-wrap: wrap; 
    display: flex; 
    flex-direction: column; 
    align-content: center;
}

h1 {

    color: white;
}

  • Save the index.css file and open the index.js file inside a text editor and add the following code: 
    window.alert('Success Creating my own Theme!!');

  • Save the index.css file. Now go to your desktop home-screen and click once on the wallpaper and hit Ctrl+r or use the system tray refresh option under the splash icon.


From the above example it must be clear to you that the html, css and javascript needed to create your own theme in splash is the same as the standard html needed for websites. I encourage you to look at the winter's kiss' code as an example to create your own theme.

Available Functions

To aid in the development process splash offers certain functions that will allow you to perform certain tasks that are otherwise tedious, inherent or very common towards the development of themes. A list of the objects that provide these functions:

api Use
terminal Provides a way to communicate with the terminal of the operating system via the terminal.execute('command') method.
os Provides info that provides platform specific details.
disk Provides for interacting with the local storage to store and delete data.
element Provides for functions that deal with html elements.

terminal.execute

This method allows you to execute commands in the terminal or command line of the operating system. This can be used to create docks and for almost anything.
Syntax: terminal.execute('command');

os.cpu

This method allows you to obtain data regarding the cpu utilization.
Syntax: os.cpu( (usage) => {console.log(usage*100)} );
The parameter usage is passed along with the callback function that stores the percentage of cpu that is being utilized by all the processes. As usage is in percentage multiply it by 100 to get the numerical value.

os.ram

This method returns the percentage of RAM that is currently free.
Syntax: var memory = os.ram();

disk.store

This method is used to store data in string or boolean format which can be identified via the key.
Syntax: disk.store('key', 'value');

disk.get

This method will retrive the data that is associated with the specified key.
Syntax: var value = disk.get('key');

disk.free

This method will delete the data that is associated with the specified key.
Syntax: disk.free('key');

disk.length

This method will return the number of items stored inside the local storage.
Syntax: var length = disk.length();

disk.clear

This method will clear all data stored inside the local storage.
Syntax: disk.clear();

element.draggable

This method will allow an existing html element to become a draggable element.
Syntax: element.draggable('htmlElement', 'nameOfElement');