From 2b5f8a751a088c1bcc873e6ec0dc82eebe1b4e2d Mon Sep 17 00:00:00 2001 From: Matthieu Baumann Date: Mon, 10 Jun 2024 11:51:44 +0200 Subject: [PATCH] add some docs on UI customization, a jsdoc conf file, fix some class links in the doc --- examples/al-gw.html | 2 + examples/al-init-custom-options.html | 42 ++++++++-------- jsdoc.json | 22 +++++++++ package.json | 4 +- src/js/A.js | 37 ++------------- src/js/Aladin.js | 2 +- src/js/Catalog.js | 11 ++--- src/js/DefaultActionsForContextMenu.js | 2 +- src/js/MOC.js | 12 ++--- src/js/Overlay.js | 12 ++--- src/js/shapes/Circle.js | 10 +--- src/js/shapes/Ellipse.js | 4 +- src/js/shapes/Polyline.js | 53 ++------------------- src/js/shapes/{Line.js => Vector.js} | 34 ++++++------- tutorials/UIGuide.md | 66 ++++++++++++++++++++++++++ 15 files changed, 152 insertions(+), 161 deletions(-) create mode 100644 jsdoc.json rename src/js/shapes/{Line.js => Vector.js} (91%) create mode 100644 tutorials/UIGuide.md diff --git a/examples/al-gw.html b/examples/al-gw.html index 9d3b54df..c09ab433 100644 --- a/examples/al-gw.html +++ b/examples/al-gw.html @@ -1,6 +1,8 @@ + +
diff --git a/examples/al-init-custom-options.html b/examples/al-init-custom-options.html index 7d2f5287..1b02b5d9 100644 --- a/examples/al-init-custom-options.html +++ b/examples/al-init-custom-options.html @@ -1,14 +1,16 @@ - - + + + -
- + +
+ + - + \ No newline at end of file diff --git a/jsdoc.json b/jsdoc.json new file mode 100644 index 00000000..ab7a367a --- /dev/null +++ b/jsdoc.json @@ -0,0 +1,22 @@ +{ + "plugins": [], + "recurseDepth": 10, + "source": { + "includePattern": ".+\\.js(doc|x)?$", + "excludePattern": "(^|\\/|\\\\)_" + }, + "sourceType": "module", + "tags": { + "allowUnknownTags": true, + "dictionaries": ["jsdoc","closure"] + }, + "templates": { + "cleverLinks": true, + "monospaceLinks": true + }, + "opts": { + "readme": "./README.md", + "destination": "./docs/", + "tutorials": "./tutorials" + } +} \ No newline at end of file diff --git a/package.json b/package.json index ab6bfcab..49c95f52 100644 --- a/package.json +++ b/package.json @@ -41,8 +41,8 @@ "preview": "vite preview", "test:build": "cd src/core && cargo test --release --features webgl2", "test:unit": "vitest run", - "doc": "jsdoc -d doc --readme README.md src/js src/js/shapes && cp aladin-logo.png doc/", - "doc:dev": "npm run doc && open doc/index.html" + "doc": "jsdoc -c jsdoc.json src/js src/js/shapes && cp aladin-logo.png docs/", + "doc:dev": "npm run doc && open docs/index.html" }, "devDependencies": { "happy-dom": "^10.11.0", diff --git a/src/js/A.js b/src/js/A.js index 7b7994c8..8cf68555 100644 --- a/src/js/A.js +++ b/src/js/A.js @@ -33,7 +33,7 @@ import { GraphicOverlay } from "./Overlay.js"; import { Circle } from "./shapes/Circle.js"; import { Ellipse } from "./shapes/Ellipse.js"; import { Polyline } from "./shapes/Polyline.js"; -import { Line } from "./shapes/Line.js"; +import { Vector } from "./shapes/Vector.js"; import { Catalog } from "./Catalog.js"; import { ProgressiveCat } from "./ProgressiveCat.js"; @@ -192,14 +192,7 @@ A.marker = function (ra, dec, options, data) { * @returns {Polyline} */ A.polygon = function (raDecArray, options) { - const numVertices = raDecArray.length; - - if (numVertices < 3) { - // Cannot define a polygon from that - throw 'Cannot define a polygon from less than 3 vertices'; - } - - const lastVertexIdx = numVertices - 1; + const lastVertexIdx = raDecArray.length - 1; // User gave a closed polygon, so we remove the last vertex if (raDecArray[0][0] == raDecArray[lastVertexIdx][0] && raDecArray[0][1] == raDecArray[lastVertexIdx][1]) { @@ -208,7 +201,7 @@ A.polygon = function (raDecArray, options) { } options = options || {}; - options.closed = true; + //options.closed = true; return new Polyline(raDecArray, options); }; @@ -268,26 +261,6 @@ A.ellipse = function (ra, dec, radiusRaDeg, radiusDecDeg, rotationDeg, options) return new Ellipse([ra, dec], radiusRaDeg, radiusDecDeg, rotationDeg, options); }; -/** - * Creates a line shape - * - * @function - * @memberof A - * @name line - * - * @param {number} ra1 - Right Ascension (RA) coordinate of the center in degrees. - * @param {number} dec1 - Declination (Dec) coordinate of the center in degrees. - * @param {number} ra2 - Right Ascension (RA) coordinate of the center in degrees. - * @param {number} dec2 - Declination (Dec) coordinate of the center in degrees. - * @param {CooFrame} [frame] - Frame in which the coordinates are given. If none, the frame used is icrs/j2000. - * @param {ShapeOptions} options - Options for configuring the line. - * - * @returns {Line} - */ - A.line = function (ra1, dec1, ra2, dec2, frame, options) { - return new Line(ra1, dec1, ra2, dec2, frame, options); -}; - /** * Creates a vector shape * @@ -301,12 +274,12 @@ A.ellipse = function (ra, dec, radiusRaDeg, radiusDecDeg, rotationDeg, options) * @param {number} dec2 - Declination (Dec) coordinate of the center in degrees. * @param {ShapeOptions} options - Options for configuring the vector. * - * @returns {Line} + * @returns {Vector} */ A.vector = function (ra1, dec1, ra2, dec2, options) { options['arrow'] = true; - return A.line(ra1, dec1, ra2, dec2, options); + return new Vector(ra1, dec1, ra2, dec2, options); } /** diff --git a/src/js/Aladin.js b/src/js/Aladin.js index b9baa3f6..020f5dce 100644 --- a/src/js/Aladin.js +++ b/src/js/Aladin.js @@ -1988,7 +1988,7 @@ aladin.on("positionChanged", ({ra, dec}) => { * Select specific objects in the view * * @memberof Aladin - * @param {?Array.} objects - If null is passed then nothing will be selected and sources already selected will be deselected + * @param {?Array.} objects - If null is passed then nothing will be selected and sources already selected will be deselected */ Aladin.prototype.selectObjects = function (objects) { if (!objects) { diff --git a/src/js/Catalog.js b/src/js/Catalog.js index 80c0549a..6e7cdf1f 100644 --- a/src/js/Catalog.js +++ b/src/js/Catalog.js @@ -34,23 +34,22 @@ import { VOTable } from "./vo/VOTable.js"; import { ObsCore } from "./vo/ObsCore.js"; import A from "./A.js"; import { Polyline } from "./shapes/Polyline.js"; -import { Line } from "./shapes/Line.js"; +import { Vector } from "./shapes/Vector.js"; import { Ellipse } from "./shapes/Ellipse.js"; import { Circle } from "./shapes/Circle.js"; import { Footprint } from "./Footprint.js"; /** - * Represents a catalog with configurable options for display and interaction. * * @namespace * @typedef {Object} Catalog */ export let Catalog = (function () { /** - * Constructor function for creating a new catalog instance. + * Represents a catalog with configurable options for display and interaction. * - * @constructor - * @memberof Catalog + * @class + * @constructs Catalog * @param {Object} options - Configuration options for the catalog. * @param {string} options.url - The URL of the catalog. * @param {string} [options.name="catalog"] - The name of the catalog. @@ -583,7 +582,7 @@ export let Catalog = (function () { shape instanceof Circle || shape instanceof Polyline || shape instanceof Ellipse || - shape instanceof Line + shape instanceof Vector ) { shape = new Footprint(shape, source); } diff --git a/src/js/DefaultActionsForContextMenu.js b/src/js/DefaultActionsForContextMenu.js index 8b0f0aba..9915725a 100644 --- a/src/js/DefaultActionsForContextMenu.js +++ b/src/js/DefaultActionsForContextMenu.js @@ -180,7 +180,7 @@ export let DefaultActionsForContextMenu = (function () { files.forEach(file => { const url = URL.createObjectURL(file); - A.catalogFromURL(url, { name: file.name, onClick: 'showTable'}, (catalog) => { + A.catalogFromURL(url, { name: file.name, hoverColor: 'yellow', onClick: 'showTable'}, (catalog) => { a.addCatalog(catalog); }, false); }); diff --git a/src/js/MOC.js b/src/js/MOC.js index 9c490a36..4b04829d 100644 --- a/src/js/MOC.js +++ b/src/js/MOC.js @@ -30,18 +30,12 @@ import { ALEvent } from "./events/ALEvent.js"; * @property {number} [options.opacity=1.0] - The opacity of the MOC */ -/** - * Represents a Multi-Order-Coverage with configurable options for display and interaction. - * - * @namespace - * @typedef {Object} MOC - */ export let MOC = (function() { /** - * Constructor function for creating a new catalog instance. + * Represents a Multi-Order-Coverage with configurable options for display and interaction. * - * @constructor - * @memberof MOC + * @class + * @constructs MOC * @param {MOCOptions} options - Configuration options for the MOC. */ let MOC = function(options) { diff --git a/src/js/Overlay.js b/src/js/Overlay.js index fa6b4ad2..6d595007 100644 --- a/src/js/Overlay.js +++ b/src/js/Overlay.js @@ -45,18 +45,12 @@ import { Color } from './Color'; * @property {Array.} [options.lineDash=[]] - Dash line option. See the segments property {@link https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash#segments| here} */ -/** - * Represents an overlay containing Footprints, whether it is - * - * @namespace - * @typedef {Object} GraphicOverlay - */ export let GraphicOverlay = (function() { /** - * Constructor function for creating a new graphical overlay instance. + * Represents an overlay containing Footprints, whether it is * - * @constructor - * @memberof GraphicOverlay + * @class + * @constructs GraphicOverlay * @param {GraphicOverlayOptions} options - Configuration options for the overlay. */ let GraphicOverlay = function(options) { diff --git a/src/js/shapes/Circle.js b/src/js/shapes/Circle.js index 07a7e1ed..f35631ca 100644 --- a/src/js/shapes/Circle.js +++ b/src/js/shapes/Circle.js @@ -31,18 +31,12 @@ import { Utils } from "./../Utils"; import { GraphicOverlay } from "./../Overlay.js"; -/** - * Represents an circle shape - * - * @namespace - * @typedef {Object} Circle - */ export let Circle = (function() { /** * Constructor function for creating a new circle. * - * @constructor - * @memberof Circle + * @class + * @constructs Circle * @param {number[]} centerRaDec - right-ascension/declination 2-tuple of the circle's center in degrees * @param {number} radius - radius in degrees * @param {ShapeOptions} options - Configuration options for the circle diff --git a/src/js/shapes/Ellipse.js b/src/js/shapes/Ellipse.js index c1dbb640..9d827369 100644 --- a/src/js/shapes/Ellipse.js +++ b/src/js/shapes/Ellipse.js @@ -36,8 +36,8 @@ export let Ellipse = (function() { /** * Constructor function for creating a new ellipse. * - * @constructor - * @memberof Ellipse + * @class + * @constructs Ellipse * @param {number[]} centerRaDec - right-ascension/declination 2-tuple of the ellipse's center in degrees * @param {number} a - half-major axis length in degrees * @param {number} b - half-minor axis length in degrees diff --git a/src/js/shapes/Polyline.js b/src/js/shapes/Polyline.js index 95f1129d..f2fd9598 100644 --- a/src/js/shapes/Polyline.js +++ b/src/js/shapes/Polyline.js @@ -51,12 +51,6 @@ import { ProjectionEnum } from "../ProjectionEnum.js"; * @property {string} [options.hoverColor] - A hovered color */ -/** - * Represents a polyline shape - * - * @namespace - * @typedef {Object} Polyline - */ export let Polyline = (function() { function _calculateMag2ForNoSinProjections(l, view) { @@ -106,10 +100,10 @@ export let Polyline = (function() { }*/ /** - * Constructor function for creating a new polyline. + * Represents a polyline shape * - * @constructor - * @memberof Polyline + * @class + * @constructs Polyline * @param {Array.} raDecArray - right-ascension/declination 2-tuple array describing the polyline's vertices in degrees * @param {ShapeOptions} options - Configuration options for the polyline. Additional properties: * @param {boolean} [options.closed=false] - Close the polyline, default to false. @@ -348,47 +342,6 @@ export let Polyline = (function() { return true; }; } - /*} else if (view.projection === ProjectionEnum.HPX) { - drawLine = (v0, v1) => { - const line = new Line(v0.x, v0.y, v1.x, v1.y); - - if (_isAcrossCollignonZoneForHpxProjection(line, view)) { - return; - } - - if (line.isInsideView(view.width, view.height)) { - const mag2 = _calculateMag2ForNoSinProjections(line, view); - - if (mag2 < 0.1) { - line.draw(ctx); - } - } - }; - - if (this.closed && this.fill) { - fillPoly = (v0, v1, index) => { - const line = new Line(v0.x, v0.y, v1.x, v1.y); - - if (_isAcrossCollignonZoneForHpxProjection(line, view)) { - return; - } - - const mag2 = _calculateMag2ForNoSinProjections(line, view); - - if (mag2 < 0.1) { - if (index === 0) { - ctx.beginPath(); - ctx.moveTo(line.x1, line.y1); - } else { - ctx.lineTo(line.x1, line.y1); - } - - return true; - } else { - return false; - } - }; - }*/ } else { drawLine = (v0, v1) => { const l = {x1: v0.x, y1: v0.y, x2: v1.x, y2: v1.y}; diff --git a/src/js/shapes/Line.js b/src/js/shapes/Vector.js similarity index 91% rename from src/js/shapes/Line.js rename to src/js/shapes/Vector.js index 1f8888bb..a223624f 100644 --- a/src/js/shapes/Line.js +++ b/src/js/shapes/Vector.js @@ -22,9 +22,9 @@ /****************************************************************************** * Aladin Lite project * - * Class Line + * Class Vector * - * A line is a graphical overlay connecting 2 points + * A vector is a graphical overlay connecting 2 points with end or begin arrows on it * * Author: Matthieu Baumann[CDS] * @@ -34,28 +34,24 @@ import { Utils } from '../Utils'; import { GraphicOverlay } from "../Overlay.js"; import { Ellipse } from "./Ellipse.js"; -/** - * Represents an line shape - * - * @namespace - * @typedef {Object} Line - */ -export let Line = (function() { +export let Vector = (function() { /** - * Constructor function for creating a new line. + * Represents an vector. + * + * A vector is a graphical overlay connecting 2 sky positions with end or begin arrows on it * - * @constructor - * @memberof Line + * @class + * @constructs Vector * @param {number} ra1 - Right Ascension (RA) coordinate of the center in degrees. * @param {number} dec1 - Declination (Dec) coordinate of the center in degrees. * @param {number} ra2 - Right Ascension (RA) coordinate of the center in degrees. * @param {number} dec2 - Declination (Dec) coordinate of the center in degrees. - * @param {ShapeOptions} options - Options for configuring the line. Additional properties: + * @param {ShapeOptions} options - Options for configuring the vector. Additional properties: * @param {boolean} [options.arrow=false] - Add an arrow pointing from (ra1, dec1) to (ra2, dec2) * - * @returns {Line} - The line shape object + * @returns {Vector} - The vector shape object */ - let Line = function(ra1, dec1, ra2, dec2, options) { + let Vector = function(ra1, dec1, ra2, dec2, options) { options = options || {}; this.color = options['color'] || undefined; this.opacity = options['opacity'] || undefined; @@ -65,7 +61,7 @@ export let Line = (function() { this.arrow = options["arrow"] === undefined ? false : options["arrow"]; // All graphics overlay have an id - this.id = 'line-' + Utils.uuidv4(); + this.id = ' vector-' + Utils.uuidv4(); this.overlay = null; @@ -79,7 +75,7 @@ export let Line = (function() { this.dec2 = dec2; }; - Line.prototype = { + Vector.prototype = { setOverlay: Polyline.prototype.setOverlay, isFootprint: Polyline.prototype.isFootprint, show: Polyline.prototype.show, @@ -154,8 +150,6 @@ export let Line = (function() { xh = v2[0]; yh = v2[1]; - //ctx.moveTo(xh, yh); - var t = angle + Math.PI * 3 / 4; x = arrowRad * Math.cos(t) + v2[0]; y = arrowRad * Math.sin(t) + v2[1]; @@ -184,5 +178,5 @@ export let Line = (function() { };*/ }; - return Line; + return Vector; })(); \ No newline at end of file diff --git a/tutorials/UIGuide.md b/tutorials/UIGuide.md new file mode 100644 index 00000000..41d3482c --- /dev/null +++ b/tutorials/UIGuide.md @@ -0,0 +1,66 @@ +# User guide + +This is a guide for users wanting to customize the apparence of Aladin Lite user interface. + +## CSS class names + +There are distincts CSS class names for users wanting to personnalize the default elements. These classes are listed below: + +* `aladin-stack-control` targets the stack opener button +* `aladin-fullScreen-control` targets the fullscreen control button +* `aladin-simbadPointer-control` targets the Simbad pointer control button +* `aladin-grid-control` targets the coordinate grid trigger button +* `aladin-settings-control` targets the settings menu opener button +* `aladin-share-control` targets the share menu opener button +* `aladin-projection-control` targets the projection selector button +* `aladin-stack-box` targets the stack box +* `aladin-status-bar` targets the status bar frame +* `aladin-cooFrame` targets the frame selector element +* `aladin-location` targets the search bar and location information element +* `aladin-fov` targets the field of view information display element + +This example changes the position of the Aladin Lite search bar to the very top-left of Aladin Lite and it disables the frame. + +```js + + + + + + + +
+ + + + + +```