JSWindows (a JavaScript Inheritance Demo) Wobj Class

© 2013, Martin Rinehart

Prerequisites:

  1. Pos_size—an instance of the Pos_size class
  2. Borders—an instance of the Borders class
  3. styles—a styles object
  4. other—an other object

Overview

The Wobj is the basic DOM-element wrapper class from which all others inherit. It lets you create, often with a single line of code, rather complex DOM elements. This requires a good understanding of the prerequisites.

The Wobj greatly simplifies your subsequent coding. You can examine position/size by looking at wobj.pos_size, for example. A wobj's position and size include the wobj's border(s) which greatly simplifies layout.

The Wobj Constructor

The Wobj constructor is seldom called. It is documented here as the arguments are passed to the Wobj.init method that all classes extending Wobj will use. Arguments:

  1. container—a Wobj-based object or the SCREEN pseudo-Wobj
  2. name—a unique name (will be used as an ID)
  3. type—the DOM tag type ('div', 'span', ...)
  4. pos_size—an array used to construct a pos_size object
  5. borders—an optional Borders argument or a number specifying border width
  6. styles—an optional styles object
  7. other—an optional other argument

The container must be another Wobj or Wobj-based object. If you want the whole browser window as a root object, use jsw2.SCREEN.

The name will be used for an element ID. It will also be used as the root of other names. (A window creates a close button. If the window is named "foo" it might create the name "foo_close_button" for its close button.)

The type is a valid HTML tag name.

If the pos_size is an array, it will be passed to the Pos_size constructor. (Links are on bottom menu, above as well as in "prerequisites" box.)

If the borders argument is omitted, the default Borders instance will be used. To omit any but the last argument, supply an undefined placeholder.

The Wobj constructor passes its arguments to Wobj.int with these exceptions. The borders argument, if undefined, is replaced with a default Borders object or, if a border-width number is supplied, creates a new Borders with the specified width. It then adds the specified styles, if any, to the default Wobj styles.

The assumption in this class is that another class, inheriting from Wobj, will want to supply its own border and style defaults. A class that uses a wider border, for example, will want to create a Borders object in its own constructor before calling Wobj.init().

In adddition to the two exceptions noted above, the Wobj.init() method requires an object instance reference as its first argument, preceding the Wobj constructor arguments.

The Wobj Instance Methods

Save for toString() you should never need to call these directly. The Wobj constructor calls the get_all_styles() method, which in turn calls assign_sizes(). This puts a correctly styled element into the DOM tree. From then on, routine window operations (maximize, minimize, restore) will work correctly. You do not need to worry unless you want to do fancy things, such as rearranging the elements in a dialog.

The add_minbox() Method

wobj.add_minbox();

The "minbox" is the box that holds the minimized form of child windows (after clicking the minimized button, for instance). This method is called (automatically) when the Wobj first child window is minimized. Subsequently the minbox expands/contracts as needed to store minimized windows. It is hidden when empty.

The apend_child() Method

When a Wobj is created, its first argument is container, the Wobj that is the parent of the new one.(Or, at the topmost level, the SCREEN pseudo-Wobj.) The constructor will call the container's append_child() method.

The append_choice() Method

A Wobj used as a container for selectable Window objects maintains a Choices list of those windows. Clicking on a window "chooses" it (showing it as selected, reverting the former selection to non-selected). To be selectable, the child Wobj must call this method. This is automatic for Window objects and Window-based objects.

The chosen() Method

This method implements the choosable interface. See the Choices class.

wobj.chosen();

When multiple Wobj objects (not necessarily Windows) populate a container, one of them is "chosen" which is shown by highlighted borders. This method selects a wobj as the chosen object.

Also, to choose:

wobj.chosen( true );

Or, to make non-chosen:

wobj.chosen( false );

The draw() Method

wobj.draw();

Collects all styles (from Borders, Pos_size, etc.) and assigns them to the delem—DOM element— which causes the Wobj to be redrawn by the browser.

Call draw() after changes which indirectly modify styles. Changing radii in the borders object, for instance, does not change styles (and therefore does not change the view) until you draw().

The fit_inside() Method

This is the method called by the maximize buttons of windows. In modifies positions, sizes and border radii so that the window being maximized fits neatly inside its container.

The get_all_styles() Method

This begins with defining style.left (or style.right), style.top (or style.bottom), style.width and style.height (the latter two from wobj.content_width and wobj.content_height, respectively). It adds these styles to boders.get_styles(). Last, it adds in the specific styles specified in the styles argument (now saved as the wobj.styles property).

The implement() Method

window.implement('Sizable');

This method is called to implement a capability such as "Movable" or "Sizable".

The is_a_wobj() Method

This method returns true. The instanceof operator does not understand our inheritance. Use is_a_wobj() when you want to know if an object is based on the Wobj class.

The listen_for() Method

wobj.listen_for('click', click_func);

Provides an object-style calling method for the library listen_for() method.

The listen_on() Method

wobj.listen_on('click', click_func);

Provides an object-style calling method for the library listen_on() method.

The minimize() Method

    wobj.minimize();
    wobj.minimize(true); // same as minimize()

    wobj.minimize(false); // return to non-minimized

Minimizes a Wobj, if non-minimized. If called with false, returns a minimized Wobj to its non-minimized state.

The move_to_top() Method

wobj.move_to_top();

DOM elements are drawn from first to last (their order within the parent element). The last one, therefore, appears to be "on top" of the others if they overlap. This method moves the Wobj to the "top of the stack" by moving it to the last position in its parent element.

The remove() Method

wobj.remove(child_wobj);

Removes a child Wobj from a Wobj's list of children, from its list of choices (if it is a choice) and from the DOM.

The re_pos_size() Method

wobj.re_pos_size(left,top, width,height);

Changes the pos_size object's specs. This does not draw() the object on the screen.

The resize() Method

wobj.resize(width,height);

Changes the pos_size object's specs. This does not draw() the object on the screen.

The set_state() Method

wobj.set_state('minimized');
wobj.set_state('minimized', true); // same

wobj.set_state('minimized', false); // reset

The Wobj maintains a set of flags in its status object. This method sets (makes true) or resets (makes false) these flags.

The stop_listening_for() Method

wobj.stop_listening_for('click', click_func);

Provides an object-style call to the library stop_listening_for() method.

The stop_listening_on() Method

wobj.stop_listening_on('click', click_func);

Provides an object-style call to the library stop_listening_on() method. The click_func argument is optional.

The toString() Method

For convenience in alert() or console.log() messages, a separator argument (we use \n\t} may be supplied.

Inheriting from Wobj

The Rect class shows how a class may inherit from Wobj.

The technique of extending a class by calling its init() method does not provide automatic access to the extended class' instance methods. If Bar extends Foo and you want to be able to call Bar.meth() (where Foo.meth() exists) the simplest way is to make a copy of the method reference: Bar.prototype.meth = Foo.prototype.meth;. (There are lots of alternatives.)

Feedback: MartinRinehart at gmail dot com

# # #