# LMathPluginAPI

This is a documentation-ish for the `LMathPluginAPI` object, revealed to plugins at the init phase.

## Common
These methods and variables are available on both the backend part and the frontend part.

### api.getVersion()
Returns current L'Math version.

### api.getSettings()
Returns the settings object. If you need to modify settings, please see ___ (WIP).

### api.getUserSetting()
Returns the user settings object. If you need to modify settings, please see ___ (WIP).

----

### api.events
The event-specific API
#### events.on(eventName, callback)
Allows you to listen to L'Math-specific events.
#### events.fire(eventName, eventData)
Allows you to fire a custom-named event. The data will be passed as 

----

### api.messages
The messaging-specific API
#### messages.on(messageName, callback)
Allows you to listen to plugin-specific IPC messages between the backend and the frontend.
Any data sent will be passed as an argument to the callback function.
**Just like with regular ipc messaging, you can't send functions or other non-json types.**
#### messages.send(messageName, messageData)
Allows you to send plugin-specific IPC messages between the backend and the frontend.
The messageData object will be converted to JSON and passed as a parsed object to any listeners on the other process.
**Just like with regular ipc messaging, you can't send functions or other non-json types.**



## Backend

### api.getSessionId() (`String`)
Returns the current session identifier
### api.getLogger() (lo4js logger)
Returns the `log4js` logger.
### api.getWindow() (`BrowserWindow`)
Returns the main Electron window of the app
### api.getDataFolder() (`String`)
Returns the absolute path to L'Math's data folder
### api.getTempFolder() (`String`)
Returns the absolute path to the session-specific temp folder
### api.getPluginsFolder() (`String`)
Returns the absolute path to L'Math's plugin folder

### events

* `fileOpened`
    * Called when a file has been succesfully opened 
    * Event data:
        * `file` - the absolute path to the file
        * `content` - a brief content description of the file
* `fileSaved`
    * Called when a file has been succesfully saved
    * Event data:
        * `file` - the absolute path to the file
* `pageImport`
    * Called when a page is about to be loaded from file (and possibly safe-checked)
    * Event data:
        * `pageId` - the id of the page
        * `content` - the HTML contents, **can be modified**
* `pageLoaded`
    * Called when a page has been loaded (from file or from cache) and is about to be sent to the frontend
    * Event data
        * `pageId` - the id of the page
        * `content` - the HTML contents, **can be modified**
* `pageSave`
    * Called before saving a page to its temporary file
    * Event data 
        * `pageId` - the id of the page
        * `content` - the HTML contents, **can be modified**
* `pageSaved`
    * Called when a page has been succesfully saved to its temporary file
    * Event data 
        * `pageId` - the id of the page

## Frontend

### api.getWindow() (`window`)
Returns the vanilla JS `window` object.
### api.getDocument() (`document`)
Returns the vanilla JS `window.document` object.
### api.getJQuery() (`jQuery`)
Returns the jQuery (`$`) object of the window.

### api.gui
All returned elements are **plain DOM objects**, not jQuery objects.

#### gui.getEditor()
Returns the main ContentEditable editor area (`#_editor_area`) 
#### gui.getSidebar()
Returns the left-hand side sidebar (`#_work_tabs`) 
#### gui.getToolbox()
Returns the main top toolbar (`#_toolbox`) 
#### gui.getTextToolbar()
Returns the text toolbar (`#_bottom_row`) 
#### gui.getCalc()
Returns the T'Calc addon calculator window (`#_minicalc`)
#### gui.getImageToolbox()
Returns the floating image toolbox (`#_image_editor`)
#### gui.getSpinner()
Returns the loading spinner
#### gui.getSpinnerDimmer()
Returns the loading spinner dimmer
#### gui.getDialogContainer()
Returns the special dialog container (that contains e.g. the welcome and settings dialogs)



### events
* `worksheetLoading`
    * Called when a worksheet is being loaded
* `worksheetOpened`
    * Called when a worksheet has been opened (probably from a file)
    * Event data:
        * `content` - the brief contents of the file, **can be modified**, but please don't
* `worksheetSaved`
    * Called when a worksheet has been saved
* `worksheetReset`
    * Called when a new worksheet has been initialized
* `formulaRender`
    * Called before a LaTeX formula is sent to the renderer
    * Event data:
        * `latex` - the LaTeX input, **can be modified**
* `pageSave`
    * Called before saving the contents of a page 
    * Event data:
        * `pageId` - the id of the page
        * `content` - the HTML content, **can be modified**
        * `data` - page metadata object, **can be modified**
* `pageLoad`
    * Called before loading a page 
    * Event data 
        * `pageId` - the id of the page to be loaded
* `pageLoaded`
    * Called when a page has been loaded and is about to be shown
    * Event data
        * `content` - the HTML content, **can be modified**
* `pageAdd`
    * Called when a page is about to be created 
    * Event data:
        * `pageName` - the name of the new page, **can be modified**