JEP Panel positioning

ZER0 edited this page Mar 21, 2013 · 11 revisions

Currently there are no options to set the position of the panel within the browser window; but only the size (width and height). If is not anchored to a widget, the panel is always centered.

Goals

  • Show a panel specifying the coordinates in pixel
  • Show a panel specifying the alignment (e.g. the top right corner of the content area)
  • Be consistent with the current UI behavior in Firefox (= don't break the UX guidelines)

Proposed API

Adding one property called position to the Panel's options, that will contains an object with top, right, bottom and left should help us to achieve the goals above.

Positioning and alignment

The new top, right, bottom and left properties are familiar to web developers and web designers:

// Show the panel to 200px top and 400px left of the content area
require("panel").Panel({
  width: 320,
  height: 200,
  position: {
    top: 200,
    left: 400
  }
}).show();
// Show the panel to the bottom right corner of the content area 
require("panel").Panel({
  width: 320,
  height: 200,
  position: {
    bottom: 0,
    right: 0
  }
}).show();

The default's behavior won't change, therefore:

require("panel").Panel().show();

Shows a centered 320x240 panel.

Because the default alignment is centered, to leave one axis centered, the relative option has just to be omitted:

// Show the panel to the centered horizontally and aligned to the bottom of the content area 
require("panel").Panel({
  position: {
   bottom: 0
  }
}).show();

// Show the panel to the centered vertically and aligned to the left of the content area 
require("panel").Panel({
  position: {
    left: 0
  }
}).show();

In the same way of their CSS counterpart, set both top and bottom, or left and right, will results in determined the height and width:

// Show the panel centered horizontally, that is distant 40px from the top and 100px from the bottom
require("panel").Panel({
  position: {
    top: 40,
    bottom: 100
  }
}).show();

Set implicitly height will makes the panel ignore the bottom property, as the CSS homonym properties does:

// Show the panel centered horizontally, that is distant 40px from the top and has 400px as height
require("panel").Panel({
  position: {
    top: 40,
    bottom: 100,
  },
  height: 400
}).show();

// This is equivalent to:

require("panel").Panel({
  position {
    top: 40
  },
  height: 400
}).show();

For the width is the same as height: set left, right and width at the same time makes right ignored.

Temporary position

It's possible specify a temporary position for the panel, passing the panel's options in the show method. Notice that only position, width and height options will be parsed. Any other property will be ignored.

let panel = require("panel").Panel({
  position: {
    top: 100,
    left: 200
  },
  width: 200,
  height: 400
});

// show the a 100x400 panel, to 100px from the bottom and centered horizontally
panel.show({
  position: {
    bottom: 100
  }, 
  width: 100
});

// show a 200x400 panel to the default position (top: 100, left 200)
panel.show();

As the example shows, the options given to the show method overrides the namesake default values. So, position property will override the default position property, in the same way of width and height if given.

let panel = require("panel").Panel({
  position: {
    top: 100,
    bottom: 100,
  },
  height: 400
});

// bottom will be ignored
panel.show();

// Here the `bottom` will be ignored too, because the default
// `position` is overridden, but the `height` is inherited from 
// constructor's option
panel.show({
  position: {
    top: 10,
    bottom: 10
  }
});

// Here `height` is explicitly set to `null`, so the constructor's `height`
// will be ignored
panel.show({
  position: {
    top: 10,
    bottom: 10
  },
  height: null
});

Anchoring

With the introduction of position property, it would be possible pass other objects too. That could be handy to show panel anchored to some elements, like a Widget. For example:

let panel = require("panel").Panel();

panel.show({ position: widget });

That would helps to fix Bug 638142 too.

Relevant bugs

Discussions