Skip to content

API Reference

Jump to bottom
Tingkai Liu edited this page Nov 2, 2020 · 5 revisions

Session API

The concept of a session is meant to reflect the state of a widget:

  1. The kernel that the widget is connected to and the related information (Kernel id, Kernel Path, Kernel Name)
  2. The Processor that the widget is connected in the backend
  3. The CommTarget and CommId of the comm that the widget uses to communication with its kernel.

All information can be accessed by the built-in icon on each FBLwidget's toolbar:

Processor API

The concept of Processor is directly related to the backend servers in Crossbar, an in fact synonymous with the Servers described here.

In essence, the processor keeps track of the backend databases that a given widget is connected to. It is a string attribute that corresponds to an entry in the backend server settings schemas.

Related APIs

All the following APIs are specified in the base FBLWidget class which are then inherited by the children widgets (Neu3DWidget, NeuGFXWidget). New widget classes should put custom logic for when processor is changed inside the set processor(newProcessor: string) setter, and use processorChanged signal to monitor processor changes.

  1. FFBOProcessor.NO_PROCESSOR = "No Processor": a constant that indicates no processor connected.
  2. get processor(): string: a getter that returns the string name of the processor currently connected to.
  3. setProcessor(newProcessor: string, startUp=false): a function that sets the value of the processor
    1. Sets the hasClient and dirty states of the widget if either the newProcessor is FFBOProcessor.NO_PROCESSOR or is different from the current processor.
    2. In children classes (Neu3D), the startUp flag allows for a different behavior at the initialization stage of the widget.
  4. set processor(newProcessor: string): a setter that calls the setProcessor(newProcessor: string, startUp=false) API, with additional logic specified in the inherited child classes (like showing meshes associated with a given processor in Neu3D).
  5. processorChanged: a signal that emits the name of the new processor when changed.

Dirty State API

The dirty state of the widget reflects whether there is unsaved changes that is required to be manually saved to layout restorer for state-persistence. The dirty state of widget will set the dirty state of the entire JupyterLab application, which will prompt user to save the state of the widgets to the widget tracker for restoration is user leaves or refreshes the webpage. It will not prompt the user to save the widget state if the user closes the widget directly from within the JLab interface. See the related issue for more details.

Related API

The intended way of using the API is to call setDirty which will trigger an event dirty which can be used to handle changes in the dirty state.

  1. setDirt(state: boolean): void
    1. setDirty to true (dirty) is typically emitted by the widget when the state changes.
    2. setDirty for false (clean) is typically emitted by the extension when the state changes have been saved by the user to the layout restorer's stateDB.
  2. isDirty: boolean: a value to check if the state is dirty
  3. dirty: a signal that emits the dirty state when changed

Client API

In commit db9eeed, a new API that tracks the status of ClientConnection was introduced.

This API allows for the front-end to keep track of whether a client object is associated with the current front-end widget. The status of the client can be checked by the hasClient getter or set by the setHasClient() function call. A call to setHasClient would always emit a clientConnect signal that emits a boolean flag of whether the widget has client.

Additionally, to force a manual check, user can use the checkForClient() function which will communicated with the kernel to check for client.

The API has been used to change the Neu3DWidget's input search bar placeholder and disable the search bar when the client is not found.

Clone this wiki locally