JSWindows (a JavaScript Inheritance Demo) Documentation

© 2013, Martin Rinehart

Overview

The JSWindows (a JavaScript Inheritance Demo) system provides a windowing frontend (such as KDE, Gnome, MS Windows, OSX) for applications running in browsers. The design goal is to make life simple for the frontend engineer who wishes to add a JSWindows application to a website, or to create an app that can be loaded into a JSWindows website.

The user functionality should be immediately obvious to anyone familiar with a multi-windowing system. Actions such as moving, reshaping, maximizing, minimizing and closing applications should be "intuitive" (you've done them before).

A secondary goal has been to make the styling of such an app so simple that no designer is ever content to use the default skin. While we want all JSWindows apps to present a consistent, no-learning-curve usability, we want JSWindows apps to all look unique.

Creating a JSWindows-Capable App

The Basics

Create a background using your favorite techniques. At the end of the <body> load the JSWindows script(s). You get a default window the size of the browser client area. It's border is two-pixels wide, solid gold. (You can reduce this to zero pixels, or make a nice border—see SKIN.) It's background is transparent, so you can see your own background. You now have a full-screen container in which you can launch your own apps. It is called jsw.SCREEN.

To launch your own app create a Window or a Window_M_BS. The former has a closing button. The latter is a Window plus sizing buttons and a title bar. The min/max buttons have their traditional functions plus you get three restore sizes. The title bar is also a handle for dragging the window. The window corners and borders should have their traditional resize/reshape capabilities but don't, yet (20130806).

Code your application inside your window. It includes an empty div, window.delem ("delem" for DOM element). Use this div as the container for your app. Be careful not to overwrite the JSWindows widgets (buttons, title bar) and you have a JSWindows application. Yes, it's that simple.

Multi-Window Apps

You may create as many windows as your app wants, within jsw.SCREEN. Each JSW window is also a JSW container. To limit your application to run in a particular location, use a jsw.Rect. (This is a window without the closing button.) For a more flexible app, use a jsw.Window. You start in jsw.SCREEN, this way:

var my_app = new jsw.WindowMM( jsw.SCREEN, ... );

With your own app's window, you create other windows inside it, this way:

var dialog01 = new jsw.Window( my_app, ... );

If you prefer, you could build your app as an object:

var my_app = {
	main: new jsw.Window_M_BS( jsw.SCREEN, ... );
};
my_app.dialog01 = new jsw.Window( my_app.main, ... );
my_app.dialog02 = ...

The Arguments

The number of arguments needed to create a window is not small. This is unavoidable. What do you want for borders (color, style, width, radii)? Where should the app be placed (position, size)? How should it be styled other than borders? What title (if it's a Window_M_BS)?

In general, we thought you should have the same flexibility that you would have if you were just creating your own screen objects.

The Details

Remember that JSWindows will take the top-right corner for its control buttons, and a stripe just left of these buttons for your title. (The title is also the drag handle).

Check the API and code any necessary event handlers.

The API

Skinning—Provide Your Own Look and Feel

You must know what you are doing to skin a JSWindows app. Diving into the skinning file without knowing what's where and which comes first is a prescription for failure. So read this section carefully. Reread it even more carefully. And if anything is unclear, stop.

Is something unclear? Email the author explaining the issue. While you are waiting for a response, reread once more. Is your answer there already? Email again. Don't be too apologetic. If you missed it, someone else might miss it, too. We consider getting the doc correct to be every bit as important as getting the code correct. Don't be bashful.

The jsw-xxx.js Files

You should not need to look at these files, excepting the jsw-data.js file (below), unless you want to dive into the internals. Email the author before you do this. Our support ends when you make the first change here. We implement ideas we like so you don't have to. There are only two valid reasons for looking at this file.

First, you may want to see how the insides of something work. One should never stop learning, of course. On the other hand, one should never write code that depends on the internals of a foreign system remaining the same. Code to the API, not to your knowledge of internals!

Second, you may want to have a custom version, based on your own proprietary ideas that will give your organization its own competitive advantage. We want to discourage this. Aren't there other places where you could get a competitive advantage? Make a better widget? Provide better service? If you really want to customize JSWindows internals, you can. Just because you can do something doesn't mean you should do it.

The jsw-data.js File

The jsw.SKIN Objects

To change the look of your app, start with jsw.SKINbasics. Change the values here and see what your objects look like. Move on to the jsw.SKIN object for more detailed styling.

A Wobj is as wide and high as you specify. (Note: everything you see on the screen is a Wobj. It's the base for Rect, all the Buttons, all the Windows, etc.) Your specs are for the content area plus the padding and borders. An element that is 100 pixels high has 70 pixels for content if the padding is 5 pixels (top and bottom) and the border is 10 pixels (top and bottom). If you change the border to 20 pixels, the content area shrinks to 50 pixels tall. The height remains 100 pixels.

Site Map, Page Children


Feedback: MartinRinehart at gmail dot com

# # #