== .overlay ==

$p.gui.overlay (UI Overlay Module)

This module provides a page //modal// overlay that can be used for certain UI elements. A //modal overlay// is a (semi-)transparent element that is placed between certain UI elements that are displayed in a modal mode (e.g. a menu or popup) and the rest of the interface, in order to catch clicks outside of the modal elements. ===== The show() Method ===== The //show// method opens the overlay. It has the following parameters:

Parameters:: - callback – a [[mdn>Web/JavaScript/Reference/Global_Objects/Function|function]] to be called before the overlay is closed (optional). - zIdx – the CSS ''[[mdn>Web/CSS/z-index|z-index]]'' that the overlay should be displayed on (optional). - color – the [[mdn>Web/CSS/color|colour]] of the overlay, overriding any possible CSS colour that was previously defined (optional). Hint: use CSS colours with transparency for best results, e.g. ''%%'#66779988'%%''.

==== Examples ==== To simply open the overlay, call:


$p.gui.overlay.show();

Open the overlay with a callback function, a ''z-index'', and a background colour:


$p.gui.overlay.show(mycallback, 99, '#66779988');

==== Notes ==== * The ''.show()'' method can be called multiple times. All the callback references will be added to the internal list, and all all called when the overlay is closed. * The ''zIdx'' and ''color'' attributes will be set by the latest call to ''.show()'', if specified. ===== The hide() Method ===== The ''.hide()'' method closes the overlay. This method is also called when the user clicks in the overlay element. When this method is called (either by code or by the user clicking in the element), each stored callback reference is called and then removed from the internal list. The overlay is then hidden. ==== Examples ==== To close the overlay, simply call:


$p.gui.overlay.hide();

Regardless how the ''.hide()'' function is called (by code or by the user clicking on the overlay), all callback functions will always be called. ===== CSS styling ===== Except for a possible ''z-index'' and ''background-color'' setting, no CSS is provided for the overlay element. Therefore the developer must make sure that the overlay element is styled via the web site’s own CSS code. The following is the //suggested// default styling for this element:


#overlay {
  display: block;
  position: fixed;
  top: 0; left: 0;
  width: 100%; height: 100%;
  background-color: rgba(0,0,0,0);
  z-index: 99;
}

===== See also ===== * [[framework:page:p-gui:index|$p.gui]] (GUI core)