Viewtron

Allows for advanced electron BrowserView layouts in an electron BrowserWindow. See viewtron-sample-app for a small usage example.

Table of Contents

• Installation
• Usage
• API
  • Core Types
  • ipcMain Process
  • ipcRenderer Process

Installation

$ npm i -S viewtron

Please note that electron is a peer-dependency.

Usage

ipcMain:

import {BrowserWindow} from 'electron'
import {ipcMainHandlers, ViewtronConfig} from 'viewtron';

const {
    addViewtron
} = ipcMainHandlers
/* OR
import {
    addViewtron
} from 'viewtron/dist/ipc-main';
*/

const config: Partial<ViewtronConfig> = {}
const mainWindow = new BrowserWindow()

const {
  viewtronWindow,
  state,
  removeViewtron,
} = addViewtron(mainWindow, config);

ipcRenderer:

Tested in preload process, could probably also be done in the renderer process. See BrowserWindow options.webPreferences.preload

import {ResizeSensor} from "css-element-queries";
import {ViewtronUpdateData} from "viewtron";
import {
    addColumnHandler,
    addRowHandler,
    addViewHandler,
    columnResetHandler,
    columnResizeHandler,
    columnVisibilityHandler,
    removeColumnHandler,
    removeRowHandler,
    removeViewHandler,
    reorderColumnHandler,
    reorderRowHandler,
    reorderViewHandler,
    rowResetHandler,
    rowResizeHandler,
    rowVisibilityHandler,
    viewResetHandler,
    viewtronInitHandler,
    viewtronLayoutHandler,
    viewtronResizeHandler,
    viewtronUpdateHandler,
    viewResizeHandler,
    viewVisibilityHandler
} from "viewtron/dist/ipc-renderer";

// All of the Node.js APIs are available in the preload process.
// It has the same sandbox as a Chrome extension.
window.addEventListener("DOMContentLoaded", () => {
    const appArea = document.getElementById("viewtron-area");

    // @todo: init logic
    viewtronInitHandler(appArea.getBoundingClientRect().toJSON());

    // @ts-ignore
    new ResizeSensor(appArea, () => {
        // @todo: resize logic
        viewtronResizeHandler(appArea.getBoundingClientRect().toJSON())
    });

    viewtronUpdateHandler((update: ViewtronUpdateData) => {
        // @todo: update logic
    });

    document.getElementById("foo").addEventListener("bar", () => {
        // @todo: add logic
        addRowHandler({}); // or any other handler
    });
});

API

Core Types

import {Store} from 'redux';
import {BrowserView, BrowserViewConstructorOptions, BrowserWindow, Rectangle} from 'electron';

import {AppAction, AppState} from '<internal>';

export type ViewtronInstance = {
    viewtronWindow: ViewtronWindow,
    state: Store<AppState, AppAction>,
    removeViewtron: () => void,
}

export type ViewtronConfig = {
    spacing: number,
    minWidth: number,
    minHeight: number,
    responsive: boolean,
    destroyOnClose: boolean,
    browserViewDefaultOptions: BrowserViewConstructorOptions,
}

export type ViewtronWindow = {
    id: string,
    instance: BrowserWindow,
    rect?: Rectangle,
    config: ViewtronConfig
}

export type Column = {
    id: string,
    windowId: string;
    rowId: string,
    name?: string,
    width?: number,
    hidden?: boolean
};

export type Row = {
    id: string,
    windowId: string;
    name?: string,
    height?: number,
    hidden?: boolean
};

export type ViewtronView = {
    id: string;
    url: string;
    name?: string;
    windowId: string;
    columnId: string;
    rect?: Rectangle;
    instance: BrowserView;
    height?: number;
    options?: BrowserViewConstructorOptions,
    hidden?: boolean
}

ipcMain Process

• addViewtron

addViewtron

Applies handlers to the main electron window instance. Should be called on each new main window instance

import {BrowserWindow} from 'electron';
import {ViewtronInstance, ViewtronConfig} from 'viewtron';

export type addViewtron = (mainWindow: BrowserWindow, config: Partial<ViewtronConfig> = {}) => ViewtronInstance

ipcRenderer process

Tested in preload process, could probably also be done in the renderer process.

• viewtronInitHandler
• viewtronResizeHandler
• viewtronUpdateHandler
• viewtronLayoutHandler
• viewtronBroadcastHandler
• addRowHandler
• removeRowHandler
• reorderRowHandler
• rowResizeHandler
• rowResetHandler
• rowVisibilityHandler
• addColumnHandler
• removeColumnHandler
• reorderColumnHandler
• columnResizeHandler
• columnResetHandler
• columnVisibilityHandler
• addViewHandler
• removeViewHandler
• reorderViewHandler
• viewResizeHandler
• viewResetHandler
• viewVisibilityHandler

viewtronInitHandler

Initialises a viewtron area on the specified rectangle.

import {Rectangle} from 'electron';

export default function viewtronInitHandler(viewtronAreaRect: Rectangle): void

viewtronResizeHandler

sets new dimensions of the viewtron main area.

import {Rectangle} from 'electron';

export default function viewtronResizeHandler(viewtronAreaRect: Rectangle): void;

viewtronUpdateHandler

Calls supplied callback whenever viewtron data is updated in main process. Passes updated viewtron state.

import {Row, Column, ViewtronView} from 'viewtron';

export type ViewtronUpdateData = {
    rows: Row[]
    columns: Column[]
    views: ViewtronView[]
}

export default function viewsUpdatedHandler(callback: (update: ViewtronUpdateData) => void): void

viewtronLayoutHandler

Allows for setting a pre-defined layout in viewtron. Will replace any and all existing rows/columns/views.

import {AddColumnData, AddRowData} from 'viewtron';

type LayoutView = {
    url: string,
    name?: string;
    height?: number;
    options?: any,
    hidden?: boolean
}

type LayoutColumn = Omit<AddColumnData, 'rowId'> & {
    views: LayoutView[];
}

export type LayoutRow = Omit<AddRowData, 'windowId'> & {
    columns: LayoutColumn[];
}

export type SetLayoutData = {
    layout: LayoutRow[]
}

export default function viewtronLayoutHandler(data: SetLayoutData): void

viewtronBroadcastHandler

Allows for sending data to all or specified views.

export type BroadcastData = {
    channel: string,
    args: any[],
    viewIds?: string[]
}

export default function viewtronBroadcastHandler(data: BroadcastData): void

addRowHandler

Adds a row to the viewtron area.

export type AddRowData = {
    name?: string,
    height?: number
}

export default function addRowHandler(data: AddRowData): void

removeRowHandler

Removes a row from the viewtron area.

export type RemoveRowData = {
    rowId: string
}

export default function removeRowHandler(data: RemoveRowData): void

reorderRowHandler

Moves a row in the viewtron area.

export type ReorderRowData = {
    rowId: string
    newIndex: number
}

export default function reorderRowHandler(data: ReorderRowData): void

rowResizeHandler

Sets height for a specific row.

export type RowResizeData = {
    rowId: string,
    height: number
}

export default function rowResizeHandler(data: RowResizeData): void

rowResetHandler

Resets heights for all or specified rows.

export type RowResetData = {
    rowIds?: string[]
}

export default function rowResetHandler(data: RowResetData): void

rowVisibilityHandler

Sets visibility of a row

export type RowVisibilityData = {
    rowId: string,
    visible: boolean
}

export default function rowVisibilityHandler(data: RowVisibilityData): void

addColumnHandler

Adds a column to the viewtron area.

export type AddColumnData = {
    rowId: string,
    name?: string,
    width?: number
}

export default function addColumnHandler(data: AddColumnData): void

removeColumnHandler

Removes a column from the viewtron area.

export type RemoveColumnData = {
    columnId: string
}

export default function removeColumnHandler(data: RemoveColumnData): void

reorderColumnHandler

Moves a column inside a row.

export type ReorderColumnData = {
    columnId: string
    newIndex: number
}

export default function reorderColumnHandler(data: ReorderColumnData): void

columnResizeHandler

Sets width for a specific column.

export type ColumnResizeData = {
    columnId: string
    width: number
}

export default function columnResizeHandler(data: ColumnResizeData): void

columnResetHandler

Resets widths for all or specified columns.

export type ColumnResetData = {
    columnIds?: string[]
}

export default function columnResetHandler(data: ColumnResetData): void

columnVisibilityHandler

Sets visibility of a column

export type ColumnVisibilityData = {
    columnId: string
    visible: boolean
}

export default function columnVisibilityHandler(data: ColumnVisibilityData): void

addViewHandler

Adds a view instance.

import {BrowserViewConstructorOptions} from 'electron';

export type AddViewData = {
    url: string,
    columnId: string,
    name?: string;
    height?: number;
    options?: BrowserViewConstructorOptions,
    hidden?: boolean
}

export default function addViewHandler(data: AddViewData): void

removeViewHandler

Removes a view instance.

export type RemoveViewData = {
    viewId: string
}

export default function removeViewHandler(data: RemoveViewData): void

reorderViewHandler

Movers a view instance inside a column.

export type ReorderViewData = {
    viewId: string
    newIndex: number
}

export default function reorderViewHandler(data: ReorderViewData): void

viewResizeHandler

Sets height for a specific view instance.

export type ViewResizeData = {
    viewId: string,
    height: number
}

export default function viewResizeHandler(data: ViewResizeData): void

viewResetHandler

Resets all views, or a specified view, to default dimensions.

export type ViewResetData = {
    viewIds?: string[]
}

export default function viewResetHandler(data: ViewResetData): void

viewVisibilityHandler

Sets visibility of a view.

export type ViewVisibilityData = {
    viewId: string,
    visible: boolean
}

export default function viewVisibilityHandler(data: ViewVisibilityData): void