Redesign of Widget API

[letsfindaway]

Rationale

The current web widget APi is divided into two parts:

1. The widget API, mainly with functions to retrieve general information about the widget.
2. The sankore API with functions to interact with the board.

But the split is not very clear. E.g. sankore.resize() could just as well belog to the widget API. sankore.showMessage() is neither related to the widget nor to the board. It is also questionable whether the preference related functions would not better belong to the widget, as they already did some time ago.

I general, the name sankore is something people will only understand if they know the history of OpenBoard.

Also the current way to expose the async functions is more a patch than a feature.

Before creating more extensions to the API, we should think of a redesign of the API structure. We can do this in a way, which keeps the current API as it is, but adds a new, much better structured API including new functions. The previous API can then be deprecated.

API structure

The API could be structured along the following topics:

• Application
• Widget metadata
• Widget instance
• Document
• Board

I would propose to expose the API behind a single window.api object as follows:

• window.api.appl
• window.api.meta
• window.api.widget
• window.api.doc
• window.api.board

Note that window can be omitted when using an API function, so it would be sufficient to access a function e.g. as api.board.setTool().

Asynchronous functions

I would also like to have a more natural interaction with asynchronous functions. As described in the Wiki and documented in the Qt documentation an asynchronous function is exposed by the QWebChannel mechanism as a function with an additional callback parameter. The current API adds another layer on top of this to convert this to a function returning a Promise.

I would like to make the Promise based calls the main way to expose the function in the API. So retrieving a property should just look like this:

async function myFunc() {
	var value = await api.widget.prefecence("key");
}

API

Proposal based on current API and proposal for extension. Some of the Slots listed below should perhaps better be functions returning a success value.

appl

Properties

• appl.lang

Signals

Slots

• appl.openURL
• appl.showMessage

Functions

---

meta

Properties

• meta.id
• meta.name
• meta.description
• meta.author
• meta.authorEmail
• meta.authorHref
• meta.version

Signals

Slots

Functions

---

widget

Properties

• widget.uuid
• widget.width
• widget.height
• widget.dropData

Signals

• widget.onenter
• widget.onleave
• widget.onremove

Slots

• widget.resize
• widget.setPreference
• widget.enableDropOnWidget

Functions

• widget.preference
• widget.preferenceKeys

---

doc

Properties

• doc.pageCount
• doc.currentPageNumber

Signals

Slots

Functions

• doc.pageThumbnail
• doc.nextPage
• doc.previousPage
• doc.gotoPage
• doc.insertPage
• doc.deletePage
• doc.deletePages
• doc.movePage
• doc.copyPage

---

board

Properties

Signals

Slots

• board.setTool
• board.setPenColor
• board.setMarkerColor
• board.zoom
• board.pan (was: move)
• board.moveTo
• board.drawLineTo
• board.eraseLineTo
• board.clear
• board.setBackground
• board.addObject
• board.centerOn
• board.addText

Functions

---

[letsfindaway]

I was even thinking of further splitting the board API into

• view with functions affecting the view of the scene: zoom, pan and centerOn
• board (or scene?) with functions affecting the scene (all others)

but the three setTool, setPenColor and setMarkerColor neither affect the view nor the scene directly. And introducing too many distinct groups might also not be helpful.

[letsfindaway]

Item manipulation

More functions for manipulating items could be possible:

• Let board.addObject() and board.addText() return an instance id
• Function board.itemsAt(x, y) returning a list of instance ids at the given scene coordinates
• Slot board.moveItem(id, x, y)
• Slot board.resizeItem(id, w, h)
• Slot board.rotateItem(id, a)
• Slot board.deleteItem(id)
• Function board.duplicateItem(id) returning the id of the duplicate