# Class: Panel

## Panel(parent)

A panel is an abstract class representing a subdivision of the LocusZoom stage to display a distinct data representation as a collection of data layers.

## Constructor

#### new Panel(parent)

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`layout.id` | string |  |  | An identifier string that must be unique across all panels in the plot. Required.
`layout.tag` | string | <optional> | 'custom_data_type' | Tags have no functional purpose, but they can be used as a semantic label for what is being displayed in this element. This makes it easy to write custom code like "find every panel that shows association scatter plots, anywhere": even if the IDs are different, the tag can be the same. Most built-in panels will contain a tag that describes, in human-readable terms, what kind of data is being shown. (see: LayoutRegistry.mutate_attrs)
`layout.show_loading_indicator` | boolean | <optional> | true | Whether to show a "loading indicator" while data is being fetched
`layout.data_layers` | Array.<module:LocusZoom_DataLayers> | <optional> |  | Data layer layout objects
`layout.toolbar.widgets` | Array.<module:LocusZoom_Widgets> | <optional> |  | Configuration options for each toolbar widget; module:LocusZoom_Widgets
`layout.title.text` | number | <optional> |  | Text to show in panel title
`layout.title.style` | number | <optional> |  | CSS options to apply to the title
`layout.title.x` | number | <optional> | 10 | x-offset for title position
`layout.title.y` | number | <optional> | 22 | y-offset for title position
`layout.legend.orientation` | 'vertical' | 'horizontal' | <optional> | 'vertical' | Orientation with which elements in the legend should be arranged. Presently only "vertical" and "horizontal" are supported values. When using the horizontal orientation elements will automatically drop to a new line if the width of the legend would exceed the right edge of the containing panel. Defaults to "vertical".
`layout.legend.origin.x` | number | <optional> | 0 | X-offset, in pixels, for the top-left corner of the legend (relative to the top left corner of the panel).
`layout.legend.origin.y` | number | <optional> | 0 | Y-offset, in pixels, for the top-left corner of the legend (relative to the top left corner of the panel). NOTE: SVG y values go from the top down, so the SVG origin of (0,0) is in the top left corner.
`layout.legend.padding` | number | <optional> | 5 | Value in pixels to pad between the legend's outer border and the elements within the legend. This value is also used for spacing between elements in the legend on different lines (e.g. in a vertical orientation) and spacing between element shapes and labels, as well as between elements in a horizontal orientation, are defined as a function of this value. Defaults to 5.
`layout.legend.label_size` | number | <optional> | 12 | Font size for element labels in the legend (loosely analogous to the height of full-height letters, in pixels). Defaults to 12.
`layout.legend.hidden` | boolean | <optional> | false | Whether to hide the legend by default
`layout.y_index` | number | <optional> |  | The position of the panel (above or below other panels). This is usually set automatically when the panel is added, and rarely controlled directly.
`layout.min_height` | number | <optional> | 1 | When resizing, do not allow height to go below this value
`layout.height` | number | <optional> | 1 | The actual height allocated to the panel (>= min_height)
`layout.margin.top` | number | <optional> | 0 | The margin (space between top of panel and edge of viewing area)
`layout.margin.right` | number | <optional> | 0 | The margin (space between right side of panel and edge of viewing area)
`layout.margin.bottom` | number | <optional> | 0 | The margin (space between bottom of panel and edge of viewing area)
`layout.margin.left` | number | <optional> | 0 | The margin (space between left side of panel and edge of viewing area)
`layout.background_click` | 'clear_selections' | null | <optional> | 'clear_selections' | What happens when the background of the panel is clicked
`layout.axes.x.extent` | 'state' | null | <optional> |  | If 'state', the x extent will be determined from plot.state (a shared region). Otherwise it will be determined based on data later ranges.
`layout.axes.x.label` | string | <optional> |  | Label text for the provided axis
`layout.axes.x.label_offset` | number | <optional> |  |
`layout.axes.x.render` | boolean | <optional> |  | Whether to render this axis
`layout.axes.x.tick_format` | 'region' | null | <optional> |  | If 'region', format ticks in a concise way suitable for genomic coordinates, eg 23423456 => 23.42 (Mb)
`layout.axes.x.ticks` | Array | <optional> |  | An array of custom ticks that will override any automatically generated)
`layout.axes.y1.label` | string | <optional> |  | Label text for the provided axis
`layout.axes.y1.label_offset` | number | <optional> |  | The distance between the axis title and the axis. Use this to prevent the title from overlapping with tick mark labels. If there is not enough space for the label, be sure to increase the panel margins (left or right) accordingly.
`layout.axes.y1.render` | boolean | <optional> | false | Whether to render this axis
`layout.axes.y1.ticks` | Array | <optional> |  | An array of custom ticks that will override any automatically generated)
`layout.axes.y2.label` | string | <optional> |  | Label text for the provided axis
`layout.axes.y2.label_offset` | number | <optional> |  |
`layout.axes.y2.render` | boolean | <optional> | false | Whether to render this axis
`layout.axes.y2.ticks` | Array | <optional> |  | An array of custom ticks that will override any automatically generated)
`layout.interaction.drag_background_to_pan` | boolean | <optional> | false | Allow the user to drag the panel background to pan the plot to another genomic region.
`layout.interaction.drag_x_ticks_to_scale` | boolean | <optional> | false | Allow the user to rescale the x axis by dragging x ticks
`layout.interaction.drag_y1_ticks_to_scale` | boolean | <optional> | false | Allow the user to rescale the y1 axis by dragging y1 ticks
`layout.interaction.drag_y2_ticks_to_scale` | boolean | <optional> | false | Allow the user to rescale the y2 axis by dragging y2 ticks
`layout.interaction.scroll_to_zoom` | boolean | <optional> | false | Allow the user to rescale the plot by mousewheel-scrolling
`layout.interaction.x_linked` | boolean | <optional> | false | Whether this panel should change regions to match all other linked panels
`layout.interaction.y1_linked` | boolean | <optional> | false | Whether this panel should rescale to match all other linked panels
`layout.interaction.y2_linked` | boolean | <optional> | false | Whether this panel should rescale to match all other linked panels
`parent` | Plot | null |  |  |

Source:
  - components/panel.js, line 60

### Members

#### (static, constant) default_layout :Object

Default panel layout

##### Type:

- Object

Source:
  - components/panel.js, line 18

#### (protected) _event_hooks :Object

Known event hooks that the panel can respond to

##### Type:

- Object

Source:
  - components/panel.js, line 277
See:
  - event:any_lz_event for a list of pre-defined events commonly used by LocusZoom

#### (protected) curtain :Object

##### Type:

- Object

Source:
  - components/panel.js, line 1015

#### data_layers :Object.<String, BaseDataLayer>

Direct access to data layer instances, keyed by data layer ID. Used primarily for introspection/ development.

##### Type:

- Object.<String, BaseDataLayer>

Source:
  - components/panel.js, line 202

#### id :String

##### Type:

- String

Source:
  - components/panel.js, line 152

#### layout :Object

A JSON-serializable object used to describe the composition of the Panel

##### Type:

- Object

Source:
  - components/panel.js, line 176

#### (protected) legend :Legend

Legend object, as defined by panel layout and child data layer layouts

##### Type:

- Legend

Source:
  - components/panel.js, line 1088

#### (protected) loader :Object

##### Type:

- Object

Source:
  - components/panel.js, line 1020

#### (protected) parent :Plot|null

##### Type:

- Plot | null

Source:
  - components/panel.js, line 134

#### (protected) parent_plot :Plot|null

##### Type:

- Plot | null

Source:
  - components/panel.js, line 139

#### (protected) toolbar :Toolbar

Create the toolbar object and hang widgets on it as defined by panel layout

##### Type:

- Toolbar

Source:
  - components/panel.js, line 1032

### Methods

#### (protected) addBasicLoader(show_immediately) → {Panel}

Add a "basic" loader to a panel. This is rarely used directly: the `show_loading_indicator` panel layout directive is the preferred way to trigger this function. The imperative form is useful if for some reason a loading indicator needs to be added only after first render. This method is just a shortcut for adding the most commonly used type of loading indicator, which appears when data is requested, animates (e.g. shows an infinitely cycling progress bar as opposed to one that loads from 0-100% based on actual load progress), and disappears when new data is loaded and rendered.

##### Parameters:

Name | Type | Default | Description
--- | --- | --- | ---
`show_immediately` | Boolean | true |

Source:
  - components/panel.js, line 786

##### Listens to Events:

- event:data_requested
- event:data_rendered

##### Returns:

Type
  Panel

#### addDataLayer(layout) → {BaseDataLayer}

Create a new data layer from a provided layout object. Should have the keys specified in `DefaultLayout` Will automatically add at the top (depth/z-index) of the panel unless explicitly directed differently in the layout provided.

NOTE: It is very rare that new data layers are added after a panel is rendered.

##### Parameters:

Name | Type | Description
--- | --- | ---
`layout` | object |

Source:
  - components/panel.js, line 436

##### Returns:

Type
  BaseDataLayer

#### clearSelections() → {Panel}

Clear all selections on all data layers

Source:
  - components/panel.js, line 533

##### Returns:

Type
  Panel

#### emit(event, eventDataopt, bubbleopt) → {Panel}

Handle running of event hooks when an event is emitted

There is a shorter overloaded form of this method: if the event does not have any data, the second argument can be a boolean to control bubbling

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`event` | string |  |  | A known event name
`eventData` | * | <optional> |  | Data or event description that will be passed to the event listener
`bubble` | boolean | <optional> | false | Whether to bubble the event to the parent

Source:
  - components/panel.js, line 356
See:
  - event:any_lz_event for a list of pre-defined events commonly used by LocusZoom

##### Returns:

Type
  Panel

#### off(event, hookopt) → {Panel}

Remove one or more previously defined event listeners

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`event` | String |  | The name of an event (as defined in `event_hooks`)
`hook` | eventCallback | <optional> | The callback to deregister

Source:
  - components/panel.js, line 323

##### Returns:

Type
  Panel

#### on(event, hook) → {function}

There are several events that a LocusZoom panel can "emit" when appropriate, and LocusZoom supports registering "hooks" for these events which are essentially custom functions intended to fire at certain times.

To register a hook for any of these events use `panel.on('event_name', function() {})`.

There can be arbitrarily many functions registered to the same event. They will be executed in the order they were registered.

##### Parameters:

Name | Type | Description
--- | --- | ---
`event` | String | The name of the event. Consult documentation for the names of built-in events.
`hook` | function |

Source:
  - components/panel.js, line 300
See:
  - event:any_lz_event for a list of pre-defined events commonly used by LocusZoom

##### Returns:

The registered event listener

Type
  function

#### removeDataLayer(id) → {Panel}

Remove a data layer by id

##### Parameters:

Name | Type | Description
--- | --- | ---
`id` | string |

Source:
  - components/panel.js, line 497

##### Returns:

Type
  Panel

#### render() → {Panel}

Update rendering of this panel whenever an event triggers a redraw. Assumes that the panel has already been prepared the first time via `initialize`

Source:
  - components/panel.js, line 546

##### Returns:

Type
  Panel

#### setTitle(title) → {Panel}

Set the title for the panel. If passed an object, will merge the object with the existing layout configuration, so that all or only some of the title layout object's parameters can be customized. If passed null, false, or an empty string, the title DOM element will be set to display: none.

##### Parameters:

Name | Type | Description
--- | --- | ---
`title` | string | object | null | The title text, or an object with additional configuration ###### Properties
Name | Type | Description
--- | --- | ---
`text` | string | Text to display. Since titles are rendered as SVG text, HTML and newlines will not be rendered.
`x` | number | X-offset, in pixels, for the title's text anchor (default left) relative to the top-left corner of the panel.
`y` | number | Y-offset, in pixels, for the title's text anchor (default left) relative to the top-left corner of the panel. NOTE: SVG y values go from the top down, so the SVG origin of (0,0) is in the top left corner.
`style` | object | CSS styles object to be applied to the title's DOM element.

Source:
  - components/panel.js, line 402

##### Returns:

Type
  Panel