retro-terminaljs

Create retro terminals feeding live data.

Usage no npm install needed!

<script type="module">
  import retroTerminaljs from 'https://cdn.skypack.dev/retro-terminaljs';
</script>

README

Retro-TerminalJS

DETAILS:

Name: Retro-TerminalJS

Latest official build: 1.2.30

Latest unbuggy builds:

  • 1.2.30 - Complete functionality (fixed EventListeners).

Recommended builds:

  • 1.2.30

License: by-nd 4.0

Discord Server: https://discord.gg/pah9SGv

NOTES:

Bugs:

  • Doesn't render display screen once in a while upon startup.
  • You can notice once a while that in the Dev Tools, it will say addEventListener is not defined.

Expected fixes in the close future:

  • Doesn't render display screen once in a while upon startup. | Not Absolute: 1.3.0
  • You can notice once a while that in the Dev Tools, it will say addEventListener is not defined. | Not Absolute: 1.3.0

SETUP

You can install the package by simply writing into your directory with:

npm i retro-terminaljs

or

npm install retro-terminaljs

(retro-terminaljs runs off of electron)

If for some odd reason electron doesn't get installed with retro-terminaljs, simply use either of these commands:

npm i electron

or

npm install electron

RUNNING

You can run retro-terminaljs using npm start after you put this in your scripts query in your package.json file:

"scripts": {
    "start": "electron ."
}

CREATING A TERMINAL APPLICATION

The start of the retro-terminaljs is quite similar to electron.

Setting Up:

To set up the playground, we will start by using this:

const { terminal, screen, display, deleteDisplay, eventListener } = require('retro-terminaljs');
// ***
terminal.on('ready', function() {
    // ***
});

This will bring in all the essential items we will be using.

terminal - The program that will be running our program.

Creating A Room:

A room is a function running a set of json code to determind the preferences of the application, these are the default preferences:

screen: {
    devTools: false
},
width: 450,
height: 450,
fullscreen: true

To set these into our terminal we will write:

// ***
let room;
terminal.on('ready', function() {
    // ***
    room = new screen({
        screen: {
            devTools: false
        },
        width: 450,
        height: 450,
        fullscreen: true
    });
    // ***
});
// ***

These can help the developer debug the program.

room - A panel in which will be given default preferences unless changed by developer.

screen - The programs screen in which we will be using.

Creating A Display:

Displays are what we will be defining in our terminal window. To set a display up, we will code this into our terminal:

// ***
terminal.on('ready', function() {
    // ***
    let disp_home;
    disp_home = new display([]);
    // ***
});
// ***

This will create a display for our user to interact with. To program objects into our terminal UI, we will code this into our display (this is an example):

// ***
terminal.on('ready', function() {
    // ***
    let disp_home;
    disp_home = new display([
        {
            type: "text",
            id: "txt_question",
            left: 0.5,
            top: 5,
            width: 99,
            height: 5,
            context: "Do you know the muffin man?",
            textalign: "center",
            background: true
        },
        {
            type: "button",
            id: "btn_no",
            left: 0.5,
            top: 11,
            width: 49,
            height: 5,
            context: "No",
            textalign: "center",
            hoverEvents: {
                hoverEffect: "left-to-right"
            }
        },
        {
            type: "button",
            id: "btn_yes",
            left: 50.5,
            top: 11,
            width: 49,
            height: 5,
            context: "Yes.",
            textalign: "center",
            hoverEvents: {
                hoverEffect: "left-to-right"
            }
        }
    ]);
    // ***
});
// ***

From this we can display a unique terminal application. Please note that the numbers for positioning are in percentage.

display - A UI placed on the terminal UI.

(WARNING: Displays can overlap, yes, you can make multiple displays like pages, we will cover how to delete displays in the next section.)

(This next section is for all the display elements we can add with their styles we can apply.)

LIBRARY:

{
    type: "text",
    id: "txt_myTextElement",
    left: 0.5,
    top: 5,
    width: 99,
    height: 5,
    context: "Example Text.",
    textalign: "center", // center
    background: true // true | false
}
{
    type: "button",
    id: "btn_myButtonElement",
    left: 50.5,
    top: 11,
    width: 49,
    height: 5,
    context: "Example Text.",
    textalign: "center", // center
    hoverEvents: {
        hoverEffect: "left-to-right" // left-to-right
    }
}

Deleting The Display:

Currently, you cannot delete a single display, you can only delete all displays that are on the UI, however, you can re-use old displays you have created. This is how you can delete all displays (changing in the near future to single displays or all displays):

// ***
terminal.on('ready', function() {
    // ***
    deleteDisplays();
    // ***
});
// ***

Deleting a display is quite vital if your making multiple displays.

deleteDisplays - Deletes all displays currently being displayed.

EventListeners:

Event Listeners are extremely vital to making your terminal application functional. Currently it is only avaliable for buttons. It's just like a single trigger event. You can write one into your terminal by programming:

// ***
terminal.on('ready', function() {
    // ***
    eventListener.listen(type, id, function() {
        // ***
    });
    // ***
});
// ***

Making this functional is quite simple, change the type to the type you can use from this list:

  • button

Than finally you would modify the id to be the id of the type you want it to listen to. To play a function upon interaction simply place it inside the function after the id.

Close Terminal:

To close the terminal application is a simple process. Just do something simple like this:

// ***
terminal.shutdown();
// ***

This will simply close the program without warning.

shutdown - Terminates the terminal application.

CONTACTS:

Discord Server: https://discord.gg/pah9SGv