From d5df803c2cd66fefdf35cf31efe92efddebde395 Mon Sep 17 00:00:00 2001 From: lxsang Date: Thu, 11 Jun 2020 18:43:20 +0200 Subject: [PATCH] Finish tag documenting --- Makefile | 2 +- README.md | 4 +- src/core/tags/CalendarTag.ts | 2 +- src/core/tags/ColorPickerTag.ts | 2 +- src/core/tags/FileViewTag.ts | 8 +- src/core/tags/GridViewTag.ts | 26 +-- src/core/tags/LabelTag.ts | 84 +++++++- src/core/tags/ListViewTag.ts | 322 ++++++++++++++++++++-------- src/core/tags/MenuTag.ts | 257 +++++++++++++++++------ src/core/tags/NSpinnerTag.ts | 46 ++-- src/core/tags/OverlayTag.ts | 44 ++-- src/core/tags/ResizerTag.ts | 70 +++++-- src/core/tags/SliderTag.ts | 76 +++++-- src/core/tags/SwitchTag.ts | 98 ++++++++- src/core/tags/SystemPanelTag.ts | 62 ++++-- src/core/tags/TabBarTag.ts | 69 +++--- src/core/tags/TabContainerTag.ts | 116 +++++++---- src/core/tags/TileLayoutTags.ts | 146 +++++++++++-- src/core/tags/TreeViewTag.ts | 347 +++++++++++++++++++++++++------ src/core/tags/WindowTag.ts | 215 ++++++++++++++++++- src/core/tags/tag.ts | 4 +- 21 files changed, 1571 insertions(+), 429 deletions(-) diff --git a/Makefile b/Makefile index 46f44fd..c6c4b80 100644 --- a/Makefile +++ b/Makefile @@ -158,7 +158,7 @@ uglify: release: main uglify doc: - typedoc --mode file --excludeNotExported --hideGenerator --out $(DOCDIR) + ./node_modules/.bin/typedoc --mode file --excludeNotExported --hideGenerator --name "AntOS API" --out $(DOCDIR) clean: rm -rf $(BUILDDIR)/resources diff --git a/README.md b/README.md index a03c35b..10db9a0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # antOS -**This version 1.0.0a will remove the dependencies on Riot.js by rewriting the major API for GUI and Announcement system** +**This version 1.0.0a removes the dependencies on Riot.js by reimplementing the major API for GUI and Announcement system. The entire core API is also rewritten in TypeScript** [![Build Status](https://travis-ci.org/lxsang/antos.svg?branch=master)](https://travis-ci.org/lxsang/antos) [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Flxsang%2Fantos.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Flxsang%2Fantos?ref=badge_shield) @@ -14,7 +14,7 @@ to the corresponding server side API. ## Demo -A demo of the VDE is available at my page [https://os.lxsang.me](https://os.lxsang.me) using username: demo and password: demo +A demo of the VDE is available at my page [https://os.iohub.dev](https://os.iohub.dev) using username: demo and password: demo ## AntOS applications diff --git a/src/core/tags/CalendarTag.ts b/src/core/tags/CalendarTag.ts index 90de1fa..5596f93 100644 --- a/src/core/tags/CalendarTag.ts +++ b/src/core/tags/CalendarTag.ts @@ -46,7 +46,7 @@ namespace OS { private _selectedDate: Date; /** - * holder for date select event callback + * placeholder for date select event callback * * @private * @type {TagEventCallback} diff --git a/src/core/tags/ColorPickerTag.ts b/src/core/tags/ColorPickerTag.ts index babc953..0fd7fae 100644 --- a/src/core/tags/ColorPickerTag.ts +++ b/src/core/tags/ColorPickerTag.ts @@ -74,7 +74,7 @@ namespace OS { private _selectedColor: ColorType; /** - * Holder for the color select event callback + * placeholder for the color select event callback * * @private * @type {TagEventCallback} diff --git a/src/core/tags/FileViewTag.ts b/src/core/tags/FileViewTag.ts index 153cab2..377cfe1 100644 --- a/src/core/tags/FileViewTag.ts +++ b/src/core/tags/FileViewTag.ts @@ -10,7 +10,7 @@ namespace OS { */ export class FileViewTag extends AFXTag { /** - * Holder for file select event callback + * placeholder for file select event callback * * @private * @type {TagEventCallback} @@ -19,7 +19,7 @@ namespace OS { private _onfileselect: TagEventCallback; /** - * Holder for file open event callback + * placeholder for file open event callback * * @private * @type {TagEventCallback} @@ -37,7 +37,7 @@ namespace OS { private _selectedFile: API.FileInfoType; /** - * Data holder of the current working directory + * Data placeholder of the current working directory * * @private * @type {API.FileInfoType[]} @@ -64,7 +64,7 @@ namespace OS { private _header: GenericObject[]; /** - * Holder for the user-specified meta-data fetch function + * placeholder for the user-specified meta-data fetch function * * @private * @memberof FileViewTag diff --git a/src/core/tags/GridViewTag.ts b/src/core/tags/GridViewTag.ts index cf4ce64..d906a07 100644 --- a/src/core/tags/GridViewTag.ts +++ b/src/core/tags/GridViewTag.ts @@ -29,7 +29,7 @@ namespace OS { */ export class GridRowTag extends AFXTag { /** - * Data holder for a collection of cell data + * Data placeholder for a collection of cell data * * @type {GenericObject[]} * @memberof GridRowTag @@ -55,7 +55,7 @@ namespace OS { protected mount(): void {} /** - * Init the tag before mounting: reset the data holder + * Init the tag before mounting: reset the data placeholder * * @protected * @memberof GridRowTag @@ -110,7 +110,7 @@ namespace OS { */ export abstract class GridCellPrototype extends AFXTag { /** - * Holder for cell selected event callback + * placeholder for cell selected event callback * * @private * @type {TagEventCallback} @@ -119,7 +119,7 @@ namespace OS { private _oncellselect: TagEventCallback; /** - * Holder for cell double click event callback + * placeholder for cell double click event callback * * @private * @type {TagEventCallback} @@ -128,7 +128,7 @@ namespace OS { private _oncelldbclick: TagEventCallback; /** - * Data holder of the current cell + * Data placeholder of the current cell * * @private * @type {GenericObject} @@ -179,7 +179,7 @@ namespace OS { } /** - * Get the current cell data holder + * Get the current cell data placeholder * * @type {GenericObject} * @memberof GridCellPrototype @@ -360,7 +360,7 @@ namespace OS { private _header: GenericObject[]; /** - * Grid rows data holder + * Grid rows data placeholder * * @private * @type {GenericObject[][]} @@ -396,7 +396,7 @@ namespace OS { private _selectedCell: GridCellPrototype; /** - * Cell select event callback holder + * Cell select event callback placeholder * * @private * @type {TagEventCallback} @@ -405,7 +405,7 @@ namespace OS { private _oncellselect: TagEventCallback; /** - * Row select event callback holder + * Row select event callback placeholder * * @private * @type {TagEventCallback} @@ -414,7 +414,7 @@ namespace OS { private _onrowselect: TagEventCallback; /** - * Cell double click event callback holder + * Cell double click event callback placeholder * * @private * @type {TagEventCallback} @@ -432,7 +432,7 @@ namespace OS { /** * Init the grid view before mounting. - * Reset all the holders to default values + * Reset all the placeholders to default values * * @protected * @memberof GridViewTag @@ -525,7 +525,7 @@ namespace OS { } /** - * get the header data holder + * get the header data placeholder * * @type {GenericObject[]} * @memberof GridViewTag @@ -746,7 +746,7 @@ namespace OS { } /** - * This function triggers the row selected event, a cell select + * This function triggers the row select event, a cell select * event will also trigger this event * * @param {TagEventType} e diff --git a/src/core/tags/LabelTag.ts b/src/core/tags/LabelTag.ts index a5d3425..4792413 100644 --- a/src/core/tags/LabelTag.ts +++ b/src/core/tags/LabelTag.ts @@ -1,33 +1,76 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { + /** + * This class defines basic AFX label tag. + * A label contains a text and an icon (optional) + * + * @export + * @class LabelTag + * @extends {AFXTag} + */ export class LabelTag extends AFXTag { + /** + * placeholder of the text to be displayed + * + * @private + * @type {(string | FormattedString)} + * @memberof LabelTag + */ private _text: string | FormattedString; + + /** + *Creates an instance of LabelTag. + * @memberof LabelTag + */ constructor() { super(); } - protected mount() { - - } + /** + * this implementation does nothing in this tag + * + * @protected + * @memberof LabelTag + */ + protected mount() {} + /** + * Refresh the text in the label + * + * @protected + * @param {*} d + * @memberof LabelTag + */ protected reload(d: any): void { this.text = this.text; } + /** + * Reset to default some property value + * + * @protected + * @memberof LabelTag + */ protected init(): void { this.icon = undefined; this.iconclass = undefined; this.text = undefined; } + /** + * This implementation of the function does nothing + * + * @protected + * @memberof LabelTag + */ protected calibrate(): void {} + /** + * Set the VFS path of the label icon + * + * @memberof LabelTag + */ set icon(v: string) { $(this.refs.i).attr("style", ""); $(this).attr("icon", v); @@ -42,6 +85,11 @@ namespace OS { } } + /** + * Set the CSS class of the label icon + * + * @memberof LabelTag + */ set iconclass(v: string) { $(this).attr("iconclass", v); $(this.refs.iclass).removeClass(); @@ -53,6 +101,11 @@ namespace OS { } } + /** + * Set the text of the label + * + * @memberof LabelTag + */ set text(v: string | FormattedString) { this._text = v; if (v && v !== "") { @@ -63,10 +116,23 @@ namespace OS { } } - get text(): string| FormattedString { + /** + * Get the text displayed on the label + * + * @type {(string| FormattedString)} + * @memberof LabelTag + */ + get text(): string | FormattedString { return this._text; } + /** + * Lqbel layout definition + * + * @protected + * @returns {TagLayoutType[]} + * @memberof LabelTag + */ protected layout(): TagLayoutType[] { return [ { diff --git a/src/core/tags/ListViewTag.ts b/src/core/tags/ListViewTag.ts index 4209042..234e64e 100644 --- a/src/core/tags/ListViewTag.ts +++ b/src/core/tags/ListViewTag.ts @@ -1,16 +1,15 @@ - namespace OS { export namespace GUI { export namespace tag { /** * List item event data type */ - export type ListItemEventData = TagEventDataType + export type ListItemEventData = TagEventDataType; /** * A list item represent the individual view of an item in the [[ListView]]. * This class is an abstract prototype class, implementation of any * list view item should extend it - * + * * * @export * @abstract @@ -18,9 +17,8 @@ namespace OS { * @extends {AFXTag} */ export abstract class ListViewItemTag extends AFXTag { - /** - * Data holder for the list item + * Data placeholder for the list item * * @private * @type {GenericObject} @@ -29,7 +27,7 @@ namespace OS { private _data: GenericObject; /** - * Holder for the item select event callback + * placeholder for the item select event callback * * @private * @type {TagEventCallback} @@ -47,7 +45,7 @@ namespace OS { private _onctxmenu: TagEventCallback; /** - * Click event callback holder + * Click event callback placeholder * * @private * @type {TagEventCallback} @@ -65,7 +63,7 @@ namespace OS { private _ondbclick: TagEventCallback; /** - * Item close event callback holder + * Item close event callback placeholder * * @private * @type {TagEventCallback} @@ -85,7 +83,7 @@ namespace OS { } /** - * + * Turn on/off the `closable` feature of the list item * * @memberof ListViewItemTag */ @@ -97,11 +95,18 @@ namespace OS { $(this.refs.btcl).hide(); } } + + /** + * Check whether the item is closable + * + * @type {boolean} + * @memberof ListViewItemTag + */ get closable(): boolean { return this.hasattr("closable"); } /** - * + * Set item select event handle * * @memberof ListViewItemTag */ @@ -110,7 +115,7 @@ namespace OS { } /** - * + * select/unselect the current item * * @memberof ListViewItemTag */ @@ -124,11 +129,18 @@ namespace OS { $(this.refs.item).addClass("selected"); this._onselect({ id: this.aid, data: this }); } + + /** + * Check whether the current item is selected + * + * @type {boolean} + * @memberof ListViewItemTag + */ get selected(): boolean { return this.hasattr("selected"); } /** - * + * Set the context menu event handle * * @memberof ListViewItemTag */ @@ -137,7 +149,7 @@ namespace OS { } /** - * + * Set the item click event handle * * @memberof ListViewItemTag */ @@ -146,7 +158,7 @@ namespace OS { } /** - * + * Set the item double click event handle * * @memberof ListViewItemTag */ @@ -155,7 +167,7 @@ namespace OS { } /** - * + * set the item close event handle * * @memberof ListViewItemTag */ @@ -164,7 +176,7 @@ namespace OS { } /** - * + * Mount the tag and bind some events * * @protected * @memberof ListViewItemTag @@ -190,7 +202,10 @@ namespace OS { } /** - * + * Layout definition of the item tag. + * This function define the outer layout of the item. + * Custom inner layout of each item implementation should + * be defined in [[itemlayout]] * * @protected * @returns {TagLayoutType[]} @@ -210,7 +225,8 @@ namespace OS { } /** - * + * Set the data of the list item. This will + * trigger the [[ondatachange]] function * * @memberof ListViewItemTag */ @@ -220,7 +236,7 @@ namespace OS { } /** - * + * Get the data of the current list item * * @type {GenericObject} * @memberof ListViewItemTag @@ -230,7 +246,8 @@ namespace OS { } /** - * + * Any subclass of this class should implement this + * function to provide its custom item layout * * @protected * @abstract @@ -240,7 +257,8 @@ namespace OS { protected abstract itemlayout(): TagLayoutType; /** - * + * This function is called when the item data is changed. + * It should be implemented in all subclass of this class * * @protected * @abstract @@ -250,19 +268,24 @@ namespace OS { } /** - * + * The layout of a simple list item contains only a + * AFX label * * @export * @class SimpleListItemTag * @extends {ListViewItemTag} */ export class SimpleListItemTag extends ListViewItemTag { + /** + *Creates an instance of SimpleListItemTag. + * @memberof SimpleListItemTag + */ constructor() { super(); } /** - * + * Reset some property to default * * @protected * @memberof SimpleListItemTag @@ -273,7 +296,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @memberof SimpleListItemTag @@ -281,7 +304,8 @@ namespace OS { protected calibrate(): void {} /** - * + * Refresh the inner label when the item data + * is changed * * @protected * @returns {void} @@ -303,7 +327,7 @@ namespace OS { } /** - * + * Re-render the list item * * @protected * @memberof SimpleListItemTag @@ -313,7 +337,7 @@ namespace OS { } /** - * + * List item custom layout definition * * @protected * @returns {TagLayoutType} @@ -325,23 +349,115 @@ namespace OS { } /** - * + * This tag defines a traditional or a dropdown list widget. + * It contains a collection of list items in which layout + * of each item may be variable * * @export * @class ListViewTag * @extends {AFXTag} */ export class ListViewTag extends AFXTag { + /** + * placeholder of list select event handle + * + * @private + * @type {TagEventCallback} + * @memberof ListViewTag + */ private _onlistselect: TagEventCallback; + + /** + * placeholder of list double click event handle + * + * @private + * @type {TagEventCallback} + * @memberof ListViewTag + */ private _onlistdbclick: TagEventCallback; - private _ondragndrop: TagEventCallback>; - private _onitemclose: (e: TagEventType) => boolean; + + /** + * placeholder of list drag and drop event handle + * + * @private + * @type {TagEventCallback>} + * @memberof ListViewTag + */ + private _ondragndrop: TagEventCallback< + DnDEventDataType + >; + + /** + * placeholder of list item close event handle + * + * @private + * @memberof ListViewTag + */ + private _onitemclose: ( + e: TagEventType + ) => boolean; + + /** + * placeholder of drag and drop mouse down event handle + * + * @private + * @memberof ListViewTag + */ private _onmousedown: (e: JQuery.MouseEventBase) => void; + + /** + * placeholder of drag and drop mouse up event handle + * + * @private + * @memberof ListViewTag + */ private _onmouseup: (e: JQuery.MouseEventBase) => void; + + /** + * placeholder of drag and drop mouse move event handle + * + * @private + * @memberof ListViewTag + */ private _onmousemove: (e: JQuery.MouseEventBase) => void; + + /** + * Reference to the latest selected DOM item + * + * @private + * @type {ListViewItemTag} + * @memberof ListViewTag + */ private _selectedItem: ListViewItemTag; + + /** + * A collection of selected items in the list. + * The maximum size of this collection is 1 if + * the [[multiselect]] feature is disabled + * + * @private + * @type {ListViewItemTag[]} + * @memberof ListViewTag + */ private _selectedItems: ListViewItemTag[]; + + /** + * Data placeholder of the list + * + * @private + * @type {GenericObject[]} + * @memberof ListViewTag + */ private _data: GenericObject[]; + + /** + * Event data passing between mouse event when performing + * drag and drop on the list + * + * @private + * @type {{ from: ListViewItemTag; to: ListViewItemTag }} + * @memberof ListViewTag + */ private _dnd: { from: ListViewItemTag; to: ListViewItemTag }; /** @@ -353,7 +469,9 @@ namespace OS { this._onlistdbclick = this._onlistselect = this._ondragndrop = ( e: TagEventType ) => {}; - this._onitemclose = (e: TagEventType) => { + this._onitemclose = ( + e: TagEventType + ) => { return true; }; this._onmousedown = this._onmouseup = this._onmousemove = ( @@ -364,7 +482,7 @@ namespace OS { } /** - * + * Reset the tag's properties to the default values * * @protected * @memberof ListViewTag @@ -382,7 +500,7 @@ namespace OS { } /** - * + * This function does nothing * * @protected * @param {*} [d] @@ -391,7 +509,7 @@ namespace OS { protected reload(d?: any): void {} /** - * + * toggle between dropdown and traditional list * * @memberof ListViewTag */ @@ -429,16 +547,18 @@ namespace OS { } /** - * + * Set drag and drop event handle * * @memberof ListViewTag */ - set ondragndrop(v: TagEventCallback>) { + set ondragndrop( + v: TagEventCallback> + ) { this._ondragndrop = v; } /** - * + * Set list select event handle * * @memberof ListViewTag */ @@ -447,7 +567,7 @@ namespace OS { } /** - * + * Set double click event handle * * @memberof ListViewTag */ @@ -456,16 +576,18 @@ namespace OS { } /** - * + * Set item close event handle * * @memberof ListViewTag */ - set onitemclose(v: (e: TagEventType) => boolean) { + set onitemclose( + v: (e: TagEventType) => boolean + ) { this._onitemclose = v; } /** - * + * Check whether the list is dropdown or traditional list * * @type {boolean} * @memberof ListViewTag @@ -475,7 +597,9 @@ namespace OS { } /** - * + * Set the default tag name of list's items. + * If the tag name is not specified in the + * data of a list item, this tag will be used * * @memberof ListViewTag */ @@ -484,7 +608,7 @@ namespace OS { } /** - * + * Get the default tag name of list item * * @type {string} * @memberof ListViewTag @@ -494,7 +618,7 @@ namespace OS { } /** - * + * Turn on/off of the `multiselect` feature * * @memberof ListViewTag */ @@ -503,7 +627,8 @@ namespace OS { } /** - * + * Check whether multi-select is allowed + * in this list * * @memberof ListViewTag */ @@ -515,7 +640,7 @@ namespace OS { } /** - * + * Enable/disable drag and drop event in the list * * @memberof ListViewTag */ @@ -524,7 +649,7 @@ namespace OS { } /** - * + * Check whether the drag and drop event is enabled * * @type {boolean} * @memberof ListViewTag @@ -534,7 +659,26 @@ namespace OS { } /** + * Set the buttons layout of the list. + * Button layout allows to add some custom + * behaviors to the list. * + * Each button data should define the [[onbtclick]] + * event handle to specify the custom behavior + * + * When the list is configured as dropdown. The buttons + * layout will be disabled + * + * Example of a button data: + * + * ``` + * { + * text: "Button text", + * icon: "home://path/to/icon.png", + * iconclass: "icon-class-name", + * onbtclick: (e) => console.log(e) + * } + * ``` * * @memberof ListViewTag */ @@ -555,7 +699,7 @@ namespace OS { } /** - * + * Get data of the list * * @type {GenericObject[]} * @memberof ListViewTag @@ -565,7 +709,7 @@ namespace OS { } /** - * + * Set data to the list * * @memberof ListViewTag */ @@ -588,7 +732,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @memberof ListViewTag @@ -596,7 +740,7 @@ namespace OS { protected ondatachange(): void {} /** - * + * Select list item(s) by their indexes * * @memberof ListViewTag */ @@ -628,7 +772,7 @@ namespace OS { } /** - * + * Get the latest selected item * * @readonly * @type {ListViewItemTag} @@ -639,7 +783,7 @@ namespace OS { } /** - * + * Get all the selected items * * @readonly * @type {ListViewItemTag[]} @@ -650,7 +794,7 @@ namespace OS { } /** - * + * Get the indexes of all selected items * * @type {(number | number[])} * @memberof ListViewTag @@ -667,10 +811,10 @@ namespace OS { } /** - * + * Add an item to the beginning of the list * * @param {GenericObject} item - * @returns + * @returns {ListViewItemTag} the added list item element * @memberof ListViewTag */ unshift(item: GenericObject) { @@ -678,7 +822,7 @@ namespace OS { } /** - * + * check whether the list has data * * @private * @param {GenericObject} v @@ -690,11 +834,11 @@ namespace OS { } /** + * Add an item to the beginning or end of the list * - * - * @param {GenericObject} item - * @param {boolean} [flag] - * @returns {ListViewItemTag} + * @param {GenericObject} item list item data + * @param {boolean} [flag] indicates whether to add the item in the beginning of the list + * @returns {ListViewItemTag} the added list item element * @memberof ListViewTag */ push( @@ -739,9 +883,9 @@ namespace OS { } /** + * Delete an item * - * - * @param {ListViewItemTag} item + * @param {ListViewItemTag} item item DOM element * @memberof ListViewTag */ delete(item: ListViewItemTag): void { @@ -761,7 +905,9 @@ namespace OS { } /** - * + * Select item next to the currently selected item. + * If there is no item selected, the first item will + * be selected * * @returns {void} * @memberof ListViewTag @@ -779,7 +925,7 @@ namespace OS { } /** - * + * Select the previous item in the list. * * @returns {void} * @memberof ListViewTag @@ -797,7 +943,7 @@ namespace OS { } /** - * + * Unselect all the selected items in the list * * @returns {void} * @memberof ListViewTag @@ -811,15 +957,18 @@ namespace OS { } /** - * + * This function triggers the click event on an item * * @private - * @param {TagEventType} e - * @param {boolean} flag + * @param {TagEventType} e tag event object + * @param {boolean} flag indicates whether this is a double click event * @returns {void} * @memberof ListViewTag */ - private iclick(e: TagEventType, flag: boolean): void { + private iclick( + e: TagEventType, + flag: boolean + ): void { if (!e.data) { return; } @@ -833,24 +982,27 @@ namespace OS { } /** - * + * This function triggers the double click event on an item * * @private - * @param {TagEventType} e + * @param {TagEventType} e tag event object * @returns * @memberof ListViewTag */ private idbclick(e: TagEventType) { - const evt: TagEventType = { id: this.aid, data: { item: e.data } }; + const evt: TagEventType = { + id: this.aid, + data: { item: e.data }, + }; this._onlistdbclick(evt); return this.observable.trigger("listdbclick", evt); } /** - * + * This function triggers the list item select event * * @private - * @param {TagEventType} e + * @param {TagEventType} e tag event object * @returns * @memberof ListViewTag */ @@ -909,7 +1061,7 @@ namespace OS { } /** - * + * Mount the tag and bind some basic event * * @protected * @returns {void} @@ -981,10 +1133,10 @@ namespace OS { } /** - * + * This function triggers the item close event * * @private - * @param {TagEventType} e + * @param {TagEventType} e tag event object * @returns {void} * @memberof ListViewTag */ @@ -992,7 +1144,7 @@ namespace OS { if (!e.data) { return; } - const evt = { id: this.aid, data: {item: e.data} }; + const evt = { id: this.aid, data: { item: e.data } }; const r = this._onitemclose(evt); if (!r) { return; @@ -1002,7 +1154,9 @@ namespace OS { } /** - * + * Show the dropdown list. + * This function is called only when the list is a dropdown + * list * * @protected * @param {*} e @@ -1028,7 +1182,9 @@ namespace OS { } /** - * + * Hide the dropdown list. + * This function is called only when the list is a dropdown + * list * * @protected * @param {*} e @@ -1041,7 +1197,7 @@ namespace OS { } /** - * + * calibrate the list layout * * @protected * @returns {void} @@ -1058,7 +1214,7 @@ namespace OS { } /** - * + * List view layout definition * * @protected * @returns {TagLayoutType[]} diff --git a/src/core/tags/MenuTag.ts b/src/core/tags/MenuTag.ts index e6a7927..0238888 100644 --- a/src/core/tags/MenuTag.ts +++ b/src/core/tags/MenuTag.ts @@ -1,16 +1,14 @@ -/* - * decaffeinate suggestions: - * DS101: Remove unnecessary use of Array.from - * DS102: Remove unnecessary code created because of implicit returns - * DS205: Consider reworking code to avoid use of IIFEs - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { - export type MenuEventData = TagEventDataType; /** - * + * Menu event data interface definition + */ + export type MenuEventData = TagEventDataType; + + /** + * This class defines the abstract prototype of an menu entry. + * Any implementation of menu entry tag should extend this class * * @export * @abstract @@ -18,10 +16,47 @@ namespace OS { * @extends {AFXTag} */ export abstract class MenuEntryTag extends AFXTag { + /** + * Data placeholder of the menu entry + * + * @private + * @type {GenericObject} + * @memberof MenuEntryTag + */ private _data: GenericObject; + + /** + * placeholder of `menu entry select` event handle + * + * @private + * @type {TagEventCallback} + * @memberof MenuEntryTag + */ private _onmenuselect: TagEventCallback; + + /** + * placeholder of `sub-menu entry select event` handle + * + * @private + * @type {TagEventCallback} + * @memberof MenuEntryTag + */ private _onchildselect: TagEventCallback; + + /** + * Reference to the parent menu entry of current one + * + * @type {MenuEntryTag} + * @memberof MenuEntryTag + */ parent: MenuEntryTag; + + /** + * Reference to the root menu entry + * + * @type {MenuTag} + * @memberof MenuEntryTag + */ root: MenuTag; /** @@ -36,7 +71,7 @@ namespace OS { } /** - * + * Init the tag before mounting * * @protected * @memberof MenuEntryTag @@ -45,7 +80,7 @@ namespace OS { this.nodes = undefined; } /** - * + * Set the `menu entry select` event handle * * @memberof MenuEntryTag */ @@ -54,7 +89,7 @@ namespace OS { } /** - * + * Set the `sub menu entry select` event handle * * @memberof MenuEntryTag */ @@ -63,7 +98,7 @@ namespace OS { } /** - * + * get the current `sub menu entry select` event handle * * @type {TagEventCallback} * @memberof MenuEntryTag @@ -72,7 +107,7 @@ namespace OS { return this._onchildselect; } /** - * + * Set data to the entry * * @memberof MenuEntryTag */ @@ -82,7 +117,7 @@ namespace OS { } /** - * + * Get data of the current menu entry * * @type {GenericObject} * @memberof MenuEntryTag @@ -92,7 +127,7 @@ namespace OS { } /** - * + * Check whether the current menu entry has sub-menu * * @protected * @returns {boolean} @@ -104,7 +139,7 @@ namespace OS { } /** - * + * Check whether the current menu entry is the root entry * * @protected * @returns @@ -119,8 +154,10 @@ namespace OS { } /** - * - * + * Layout definition of the menu entry + * This function define the outer layout of the menu entry. + * Custom inner layout of each item implementation should + * be defined in [[itemlayout]] * @protected * @returns {TagLayoutType[]} * @memberof MenuEntryTag @@ -143,7 +180,7 @@ namespace OS { } /** - * + * Set the sub-menu data * * @memberof MenuEntryTag */ @@ -169,7 +206,7 @@ namespace OS { } /** - * + * Get the sub-menu data * * @type {GenericObject[]} * @memberof MenuEntryTag @@ -181,7 +218,7 @@ namespace OS { return undefined; } /** - * + * Bind some base event to the menu entry * * @protected * @memberof MenuEntryTag @@ -191,7 +228,7 @@ namespace OS { } /** - * + * Hide the sub-menu of the current menu entry * * @private * @returns {void} @@ -207,7 +244,9 @@ namespace OS { } /** - * + * This function trigger two event: + * - the `onmenuselect` event on the current entry + * - the `onchildselect` event on the parent of the current entry * * @protected * @param {JQuery.ClickEvent} e @@ -233,11 +272,23 @@ namespace OS { } } + /** + * custom inner layout of a menu entry + * + * @protected + * @abstract + * @returns {TagLayoutType[]} + * @memberof MenuEntryTag + */ protected abstract itemlayout(): TagLayoutType[]; } /** - * + * This class extends the [[MenuEntryTag]] prototype. It inner layout is + * defined with the following elements: + * - a [[SwitchTag]] acts as checker or radio + * - a [[LabelTag]] to display the content of the menu entry + * - a `span` element that display the keyboard shortcut of the entry * * @class SimpleMenuEntryTag * @extends {MenuEntryTag} @@ -250,17 +301,39 @@ namespace OS { constructor() { super(); } + + /** + * Reset some properties to default value + * + * @protected + * @memberof SimpleMenuEntryTag + */ protected init(): void { super.init(); this.switch = false; this.radio = false; this.checked = false; } + + /** + * Do nothing + * + * @protected + * @memberof SimpleMenuEntryTag + */ protected calibrate(): void {} + + /** + * Do nothing + * + * @protected + * @param {*} [d] + * @memberof SimpleMenuEntryTag + */ protected reload(d?: any): void {} /** - * + * Turn on/off the checker feature of the menu entry * * @memberof SimpleMenuEntryTag */ @@ -274,7 +347,7 @@ namespace OS { } /** - * + * Check whether the checker feature is enabled on this menu entry * * @type {boolean} * @memberof SimpleMenuEntryTag @@ -284,7 +357,7 @@ namespace OS { } /** - * + * Turn on/off the radio feature of the menu entry * * @memberof SimpleMenuEntryTag */ @@ -298,7 +371,7 @@ namespace OS { } /** - * + * Check whether the radio feature is enabled * * @type {boolean} * @memberof SimpleMenuEntryTag @@ -308,7 +381,9 @@ namespace OS { } /** - * + * Toggle the switch on the menu entry, this setter + * only works when the `checker` or `radio` feature is + * enabled * * @memberof SimpleMenuEntryTag */ @@ -322,7 +397,7 @@ namespace OS { } /** - * + * Check whether the switch is turned on * * @type {boolean} * @memberof SimpleMenuEntryTag @@ -332,7 +407,7 @@ namespace OS { } /** - * + * Set the label icon using a VFS path * * @memberof SimpleMenuEntryTag */ @@ -348,7 +423,7 @@ namespace OS { } /** - * + * Set the label CSS icon class * * @memberof SimpleMenuEntryTag */ @@ -361,7 +436,7 @@ namespace OS { } /** - * + * Set the label text * * @memberof SimpleMenuEntryTag */ @@ -374,7 +449,7 @@ namespace OS { } /** - * + * Set the keyboard shortcut text * * @memberof SimpleMenuEntryTag */ @@ -388,7 +463,8 @@ namespace OS { } /** - * + * Uncheck all sub-menu items of the current menu entry + * that have the radio feature enabled * * @returns {void} * @memberof SimpleMenuEntryTag @@ -406,7 +482,7 @@ namespace OS { } /** - * + * Mount the current tag * * @protected * @memberof SimpleMenuEntryTag @@ -417,10 +493,10 @@ namespace OS { } /** - * + * Trigger the onmenuselect and onchildselect events * * @protected - * @param {JQuery.ClickEvent} e + * @param {JQuery.ClickEvent} e Mouse click event * @returns {void} * @memberof SimpleMenuEntryTag */ @@ -438,7 +514,7 @@ namespace OS { } /** - * + * Inner item layout of the menu entry * * @returns * @memberof SimpleMenuEntryTag @@ -453,17 +529,57 @@ namespace OS { } /** - * + * A menu tag contains a collection of menu entries in which each + * entry maybe a leaf entry or may contain a submenu * * @export * @class MenuTag * @extends {AFXTag} */ export class MenuTag extends AFXTag { + /** + * Reference to the parent menu entry of the current value. + * This value is `undefined` in case of the current menu is + * the root menu + * + * @type {MenuEntryTag} + * @memberof MenuTag + */ parent: MenuEntryTag; + + /** + * Reference to the root menu + * + * @type {MenuTag} + * @memberof MenuTag + */ root: MenuTag; - pid: number; + + /** + * The `pid` of the application that attached to this menu. + * This value is optional + * + * @type {number} + * @memberof MenuTag + */ + pid?: number; + + /** + * placeholder for menu select event handle + * + * @private + * @type {TagEventCallback} + * @memberof MenuTag + */ private _onmenuselect: TagEventCallback; + + /** + * Menu data placeholder + * + * @private + * @type {GenericObject[]} + * @memberof MenuTag + */ private _items: GenericObject[]; /** @@ -475,7 +591,7 @@ namespace OS { } /** - * + * Reset some properties to default value * * @protected * @memberof MenuTag @@ -484,11 +600,13 @@ namespace OS { this.contentag = "afx-menu-entry"; this.context = false; this._items = []; - this._onmenuselect = (e: TagEventType): void => {}; + this._onmenuselect = ( + e: TagEventType + ): void => {}; } /** - * + * Do nothing * * @protected * @memberof MenuTag @@ -496,7 +614,7 @@ namespace OS { protected calibrate(): void {} /** - * + * Do nothing * * @protected * @param {*} [d] @@ -505,7 +623,7 @@ namespace OS { protected reload(d?: any): void {} /** - * + * Set the menu items data * * @memberof MenuTag */ @@ -516,7 +634,7 @@ namespace OS { } /** - * + * Get menu items data * * @type {GenericObject[]} * @memberof MenuTag @@ -526,7 +644,7 @@ namespace OS { } /** - * + * Set whether the current menu is a context menu * * @memberof MenuTag */ @@ -541,7 +659,7 @@ namespace OS { } /** - * + * Check whether the current menu is a context menu * * @type {boolean} * @memberof MenuTag @@ -551,7 +669,7 @@ namespace OS { } /** - * + * Set menu select event handle * * @memberof MenuTag */ @@ -560,7 +678,9 @@ namespace OS { } /** - * + * Set the default tag name of the menu item. + * If the tag is not specified in an item data, + * this value will be used * * @memberof MenuTag */ @@ -569,7 +689,7 @@ namespace OS { } /** - * + * Get the default menu entry tag name * * @type {string} * @memberof MenuTag @@ -579,7 +699,8 @@ namespace OS { } /** - * + * Get the reference to the function that triggers + * the menu select event * * @readonly * @type {TagEventCallback} @@ -590,7 +711,7 @@ namespace OS { } /** - * + * This function triggers the menu select event * * @private * @param {TagEventType} e @@ -606,9 +727,10 @@ namespace OS { } /** + * Show the current menu. This function is called + * only if the current menu is a context menu * - * - * @param {JQuery.MouseEventBase} e + * @param {JQuery.MouseEventBase} e JQuery mouse event * @returns {void} * @memberof MenuTag */ @@ -623,7 +745,7 @@ namespace OS { } /** - * + * Test whether the current menu is the root menu * * @private * @returns {boolean} @@ -634,7 +756,7 @@ namespace OS { } /** - * + * Mount the menu tag and bind some basic events * * @protected * @returns {void} @@ -654,9 +776,10 @@ namespace OS { } /** + * Add a menu entry to the beginning of the current + * menu * - * - * @param {GenericObject} item + * @param {GenericObject} item menu entry data * @memberof MenuTag */ unshift(item: GenericObject): void { @@ -664,9 +787,9 @@ namespace OS { } /** + * Delete a menu entry * - * - * @param {MenuEntryTag} item + * @param {MenuEntryTag} item reference to the DOM element of an menu entry * @memberof MenuTag */ delete(item: MenuEntryTag): void { @@ -679,10 +802,10 @@ namespace OS { } /** + * Add an menu entry to the beginning or end of the menu * - * - * @param {GenericObject} item - * @param {boolean} flag + * @param {GenericObject} item menu entry data + * @param {boolean} flag indicates whether the entry should be added to the beginning of the menu * @returns {MenuEntryTag} * @memberof MenuTag */ @@ -713,7 +836,7 @@ namespace OS { } /** - * + * Menu tag layout definition * * @returns * @memberof MenuTag diff --git a/src/core/tags/NSpinnerTag.ts b/src/core/tags/NSpinnerTag.ts index dca621a..1f3876d 100644 --- a/src/core/tags/NSpinnerTag.ts +++ b/src/core/tags/NSpinnerTag.ts @@ -1,22 +1,38 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ - namespace OS { export namespace GUI { export namespace tag { /** - * + * A simple number sinner tag * * @export * @class NSpinnerTag * @extends {AFXTag} */ export class NSpinnerTag extends AFXTag { + /** + * Placeholder for value change event handle + * + * @private + * @type {TagEventCallback} + * @memberof NSpinnerTag + */ private _onchange: TagEventCallback; + + /** + * Placeholder for the spinner data + * + * @private + * @type {number} + * @memberof NSpinnerTag + */ private _value: number; + + /** + * Place holder for the spinner step + * + * @type {number} + * @memberof NSpinnerTag + */ step: number; /** @@ -29,7 +45,7 @@ namespace OS { } /** - * + * Init the spinner value to `0` and step to `1` * * @protected * @memberof NSpinnerTag @@ -40,7 +56,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @param {*} [d] @@ -49,7 +65,7 @@ namespace OS { protected reload(d?: any): void {} /** - * + * Set the value change event handle * * @memberof NSpinnerTag */ @@ -58,7 +74,7 @@ namespace OS { } /** - * + * Mount the tag and bind basic events * * @protected * @memberof NSpinnerTag @@ -93,7 +109,7 @@ namespace OS { } /** - * + * Calibrate the layout of the spinner * * @memberof NSpinnerTag */ @@ -133,7 +149,7 @@ namespace OS { } /** - * + * Set the spinner value * * @memberof NSpinnerTag */ @@ -146,7 +162,7 @@ namespace OS { } /** - * + * Get the spinner value * * @type {number} * @memberof NSpinnerTag @@ -156,7 +172,7 @@ namespace OS { } /** - * + * Spinner layout definition * * @protected * @returns {TagLayoutType[]} diff --git a/src/core/tags/OverlayTag.ts b/src/core/tags/OverlayTag.ts index 7ea58e2..ae4f7bf 100644 --- a/src/core/tags/OverlayTag.ts +++ b/src/core/tags/OverlayTag.ts @@ -1,20 +1,32 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { /** - * + * An overlay tag is a layout tag that alway stay on top of + * the virtual desktop environment. Tile layout elements ([[VBoxTag]], [[HboxTag]]) + * can be used inside this tag to compose elements * * @export * @class OverlayTag * @extends {AFXTag} */ export class OverlayTag extends AFXTag { + /** + * Tag width placeholder + * + * @private + * @type {string} + * @memberof OverlayTag + */ private _width: string; + + /** + * Tag height place holder + * + * @private + * @type {string} + * @memberof OverlayTag + */ private _height: string; /** @@ -29,7 +41,7 @@ namespace OS { //$(@refs.yield).css "flex", "1" /** - * + * Put the tag on top of the virtual desktop environment * * @protected * @memberof OverlayTag @@ -43,7 +55,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @param {*} [d] @@ -52,7 +64,8 @@ namespace OS { protected reload(d?: any): void {} /** - * + * Set the width of the tag, the tag width should be in form of: + * `100px` of `80%` * * @memberof OverlayTag */ @@ -65,7 +78,7 @@ namespace OS { } /** - * + * Get the tag width * * @type {string} * @memberof OverlayTag @@ -75,7 +88,8 @@ namespace OS { } /** - * + * Set the tag height, the tag height should be in form of: + * `100px` of `80%` * * @memberof OverlayTag */ @@ -88,7 +102,7 @@ namespace OS { } /** - * + * Get the tag height * * @type {string} * @memberof OverlayTag @@ -98,7 +112,7 @@ namespace OS { } /** - * + * Calibrate the element when mounting * * @protected * @returns {void} @@ -109,7 +123,7 @@ namespace OS { } /** - * + * Calibrate the width and height of the tag * * @returns {void} * @memberof OverlayTag @@ -126,7 +140,7 @@ namespace OS { } /** - * + * Layout definition of the tag * * @protected * @returns {TagLayoutType[]} diff --git a/src/core/tags/ResizerTag.ts b/src/core/tags/ResizerTag.ts index c9d877e..bdb0ca4 100644 --- a/src/core/tags/ResizerTag.ts +++ b/src/core/tags/ResizerTag.ts @@ -1,21 +1,54 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { /** + * A `resizer` tag is basically used to dynamically resize an element using mouse. + * It is usually put inside a [[TileLayoutTag]] an can be attached to any element. Example: * + * The resizer tag in the following example will be attached to the first `afx-vbox`, + * and allows to resize this element using mouse + * + * ```xml + * + * ... + * + * ... + * + * ``` * * @export * @class ResizerTag * @extends {AFXTag} */ export class ResizerTag extends AFXTag { + /** + * Reference to the element that this tag is attached to + * + * @private + * @type {*} + * @memberof ResizerTag + */ private _resizable_el: any; + + /** + * Reference to the parent tag of the current tag. + * The parent tag should be an instance of a [[TileLayoutTag]] + * such as [[VBoxTag]] or [[HBoxTag]] + * + * @private + * @type {*} + * @memberof ResizerTag + */ private _parent: any; + + /** + * Placeholder of the minimum value that + * the attached element can be resized + * + * @private + * @type {number} + * @memberof ResizerTag + */ private _minsize: number; /** @@ -27,7 +60,7 @@ namespace OS { } /** - * + * Set the properties of the tag to default values * * @protected * @memberof ResizerTag @@ -40,16 +73,17 @@ namespace OS { } /** - * + * Do nothing * * @protected * @param {*} [d] * @memberof ResizerTag */ - protected reload(d?: any): void { - } + protected reload(d?: any): void {} /** - * + * Set resize direction, two possible values: + * - `hz` - horizontal direction, resize by width + * - `ve` - vertical direction, resize by height * * @memberof ResizerTag */ @@ -58,7 +92,7 @@ namespace OS { } /** - * + * Get the resize direction * * @type {string} * @memberof ResizerTag @@ -68,7 +102,7 @@ namespace OS { } /** - * + * Mount the tag to the DOM tree * * @protected * @memberof ResizerTag @@ -111,7 +145,7 @@ namespace OS { } /** - * + * Enable draggable on the element * * @private * @memberof ResizerTag @@ -141,10 +175,10 @@ namespace OS { } /** - * + * Resize the attached element in the horizontal direction (width) * * @private - * @param {JQuery.MouseEventBase} e + * @param {JQuery.MouseEventBase} e JQuery mouse event * @returns {void} * @memberof ResizerTag */ @@ -165,10 +199,10 @@ namespace OS { } /** - * + * Resize the attached element in the vertical direction (height) * * @protected - * @param {JQuery.MouseEventBase} e + * @param {JQuery.MouseEventBase} e JQuery mouse event * @returns {void} * @memberof ResizerTag */ @@ -189,7 +223,7 @@ namespace OS { } /** - * + * Layout definition of the tag, empty layout * * @protected * @returns {TagLayoutType[]} diff --git a/src/core/tags/SliderTag.ts b/src/core/tags/SliderTag.ts index 53f54e3..c984ad9 100644 --- a/src/core/tags/SliderTag.ts +++ b/src/core/tags/SliderTag.ts @@ -1,25 +1,52 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { /** - * + * A slider or track bar is a graphical control element with which + * a user may set a value by moving an indicator, usually horizontally * * @class SliderTag * @extends {AFXTag} */ class SliderTag extends AFXTag { + /** + * Slider max value placeholder + * + * @private + * @type {number} + * @memberof SliderTag + */ private _max: number; + + /** + * Current slider value placeholder + * + * @private + * @type {number} + * @memberof SliderTag + */ private _value: number; + + /** + * Placeholder of the on change event handle + * + * @private + * @type {TagEventCallback} + * @memberof SliderTag + */ private _onchange: TagEventCallback; + + /** + * Placeholder of the on changing event handle + * + * @private + * @type {TagEventCallback} + * @memberof SliderTag + */ private _onchanging: TagEventCallback; /** - *Creates an instance of SliderTag. + * Creates an instance of SliderTag. * @memberof SliderTag */ constructor() { @@ -27,7 +54,9 @@ namespace OS { } /** - * + * Init the default value of the slider: + * - `max`: 100 + * - `value`: 0 * * @protected * @memberof SliderTag @@ -40,7 +69,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @param {*} [d] @@ -49,7 +78,9 @@ namespace OS { protected reload(d?: any): void {} /** - * + * Set value change event handle. + * This handle will be triggered when the + * slider indicator is released * * @memberof SliderTag */ @@ -58,7 +89,9 @@ namespace OS { } /** - * + * Set value changing event handle. + * This handle is triggered when moving the + * slider indicator * * @memberof SliderTag */ @@ -67,7 +100,7 @@ namespace OS { } /** - * + * Enable/disable the slider * * @memberof SliderTag */ @@ -88,7 +121,7 @@ namespace OS { } /** - * + * Check whether the slider is enabled * * @type {boolean} * @memberof SliderTag @@ -98,7 +131,7 @@ namespace OS { } /** - * + * Set the slider value * * @memberof SliderTag */ @@ -108,7 +141,7 @@ namespace OS { } /** - * + * Get the current slider value * * @type {number} * @memberof SliderTag @@ -118,7 +151,7 @@ namespace OS { } /** - * + * Set the maximum value of the slider * * @memberof SliderTag */ @@ -128,7 +161,7 @@ namespace OS { } /** - * + * Get the maximum value of the slider * * @type {number} * @memberof SliderTag @@ -138,13 +171,12 @@ namespace OS { } /** - * + * Mount the tag and bind some basic events * * @protected * @memberof SliderTag */ protected mount(): void { - this.enable_dragging(); $(this.refs.point).css("position", "absolute"); $(this.refs.point).hide(); @@ -165,7 +197,7 @@ namespace OS { } /** - * + * Calibrate the slide based on its value and max value * * @memberof SliderTag */ @@ -194,7 +226,7 @@ namespace OS { } /** - * + * enable dragging on the slider indicator * * @private * @memberof SliderTag @@ -231,7 +263,7 @@ namespace OS { } /** - * + * Layout definition * * @protected * @returns {TagLayoutType[]} diff --git a/src/core/tags/SwitchTag.ts b/src/core/tags/SwitchTag.ts index 78dece6..2337e52 100644 --- a/src/core/tags/SwitchTag.ts +++ b/src/core/tags/SwitchTag.ts @@ -1,19 +1,28 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { + /** + * A switch tag is basically used to visualize an boolean data value. + * + * @export + * @class SwitchTag + * @extends {AFXTag} + */ export class SwitchTag extends AFXTag { + /** + * Placeholder for the onchange event handle + * + * @private + * @type {TagEventCallback} + * @memberof SwitchTag + */ private _onchange: TagEventCallback; - private _onchanging: TagEventCallback; - constructor() { - super(); - - } + /** + * Turn on/off the switch + * + * @memberof SwitchTag + */ set swon(v: boolean) { this.attsw(v, "swon"); $(this.refs.switch).removeClass(); @@ -22,28 +31,65 @@ namespace OS { } } + /** + * Check whether the switch is turned on + * + * @type {boolean} + * @memberof SwitchTag + */ get swon(): boolean { return this.hasattr("swon"); } + /** + * Enable the switch + * + * @memberof SwitchTag + */ set enable(v: boolean) { this.attsw(v, "enable"); } + /** + * Check whether the switch is enabled + * + * @type {boolean} + * @memberof SwitchTag + */ get enable(): boolean { return this.hasattr("enable"); } + /** + * Set the onchange event handle + * + * @memberof SwitchTag + */ set onswchange(v: TagEventCallback) { this._onchange = v; } + /** + * Mount the tag and bind the click event to the switch + * + * @protected + * @memberof SwitchTag + */ protected mount(): void { $(this.refs.switch).click((e) => { return this.makechange(e); }); } + /** + * This function will turn the switch (on/off) + * and trigger the onchange event + * + * @private + * @param {JQuery.ClickEvent} e + * @returns + * @memberof SwitchTag + */ private makechange(e: JQuery.ClickEvent) { if (!this.enable) { return; @@ -54,6 +100,13 @@ namespace OS { return this.observable.trigger("switch", evt); } + /** + * Tag layout definition + * + * @protected + * @returns + * @memberof SwitchTag + */ protected layout() { return [ { @@ -63,12 +116,35 @@ namespace OS { ]; } + /** + * Init the tag: + * - switch is turn off + * - switch is enabled + * + * @protected + * @memberof SwitchTag + */ protected init(): void { this.swon = false; this.enable = true; - this._onchange = this._onchanging = (e) => {}; + this._onchange = (e) => {}; } + + /** + * Do nothing + * + * @protected + * @memberof SwitchTag + */ protected calibrate(): void {} + + /** + * Do nothing + * + * @protected + * @param {*} [d] + * @memberof SwitchTag + */ protected reload(d?: any): void {} } diff --git a/src/core/tags/SystemPanelTag.ts b/src/core/tags/SystemPanelTag.ts index f58ab26..3f54b01 100644 --- a/src/core/tags/SystemPanelTag.ts +++ b/src/core/tags/SystemPanelTag.ts @@ -1,22 +1,41 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { - /** - * + * A system panel contains the following elements: + * - Spotlight to access to applications menu + * - Current focused application menu + * - System tray for all running services running in background * * @export * @class SystemPanelTag * @extends {AFXTag} */ export class SystemPanelTag extends AFXTag { + /** + * Reference to spotlight data + * + * @private + * @type {(GenericObject)} + * @memberof SystemPanelTag + */ private _osmenu: GenericObject; + + /** + * Placeholder indicates whether the spotlight is currently shown + * + * @private + * @type {boolean} + * @memberof SystemPanelTag + */ private _view: boolean; + + /** + * Place holder for a private callback function + * + * @private + * @memberof SystemPanelTag + */ private _cb: (e: JQuery.MouseEventBase) => void; /** @@ -33,7 +52,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @memberof SystemPanelTag @@ -41,7 +60,7 @@ namespace OS { protected init(): void {} /** - * + * Do nothing * * @protected * @param {*} [d] @@ -50,7 +69,8 @@ namespace OS { protected reload(d?: any): void {} /** - * + * Attach a service to the system tray on the pannel, + * this operation is performed when a service is started * * @param {BaseService} s * @returns @@ -62,7 +82,8 @@ namespace OS { } /** - * + * Launch the selected application from the spotlight + * applications list * * @private * @returns {void} @@ -84,7 +105,7 @@ namespace OS { } /** - * + * Perform spotlight search operation on keyboard event * * @private * @param {JQuery.KeyboardEventBase} e @@ -126,7 +147,9 @@ namespace OS { } /** - * + * detach a service from the system tray of the panel. + * This function is called when the corresponding running + * service is killed * * @param {BaseService} s * @memberof SystemPanelTag @@ -138,7 +161,7 @@ namespace OS { } /** - * + * Layout definition of the panel * * @protected * @returns {TagLayoutType[]} @@ -222,7 +245,8 @@ namespace OS { } /** - * + * Refresh applications list on the spotlight widget + * from system packages meta-data * * @private * @memberof SystemPanelTag @@ -253,7 +277,7 @@ namespace OS { } /** - * + * Show/hide the spotlight * * @private * @param {boolean} flag @@ -264,7 +288,7 @@ namespace OS { if (flag) { $(this.refs.overlay).show(); this.refreshAppList(); - + this.calibrate(); $(document).on("click", this._cb); (this.refs.search as HTMLInputElement).value = ""; @@ -276,7 +300,7 @@ namespace OS { } /** - * + * Calibrate the spotlight widget * * @memberof SystemPanelTag */ @@ -287,7 +311,7 @@ namespace OS { } /** - * + * Mount the tag bind some basic event * * @protected * @memberof SystemPanelTag diff --git a/src/core/tags/TabBarTag.ts b/src/core/tags/TabBarTag.ts index 6333c9a..933ec19 100644 --- a/src/core/tags/TabBarTag.ts +++ b/src/core/tags/TabBarTag.ts @@ -1,23 +1,42 @@ -/* - * decaffeinate suggestions: - * DS101: Remove unnecessary use of Array.from - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { + /** + * Tag event data type definition + */ type TabEventData = TagEventDataType; /** - * + * a TabBar allows to control a collection of tabs * * @export * @class TabBarTag * @extends {AFXTag} */ export class TabBarTag extends AFXTag { + /** + * Placeholder of currently selected tab index + * + * @private + * @type {number} + * @memberof TabBarTag + */ private _selected: number; + + /** + * Placeholder of tab close event handle + * + * @private + * @memberof TabBarTag + */ private _ontabclose: (e: TagEventType) => boolean; + + /** + * Placeholder of tab select event handle + * + * @private + * @type {TagEventCallback} + * @memberof TabBarTag + */ private _ontabselect: TagEventCallback; /** @@ -31,7 +50,7 @@ namespace OS { } /** - * + * Init the tag * * @protected * @memberof TabBarTag @@ -41,7 +60,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @param {*} [d] @@ -50,7 +69,7 @@ namespace OS { protected reload(d?: any): void {} /** - * + * Enable/disable a tab to be closed * * @memberof TabBarTag */ @@ -59,7 +78,7 @@ namespace OS { } /** - * + * Check whether tabs can be closed * * @type {boolean} * @memberof TabBarTag @@ -69,9 +88,9 @@ namespace OS { } /** + * Add a tab in the end of the tab bar * - * - * @param {GenericObject} item + * @param {GenericObject} item tab data * @memberof TabBarTag */ push(item: GenericObject): ListViewItemTag { @@ -80,9 +99,9 @@ namespace OS { } /** + * Delete a tab * - * - * @param {ListViewItemTag} el + * @param {ListViewItemTag} el reference to DOM element of a tab * @memberof TabBarTag */ delete(el: ListViewItemTag) { @@ -90,9 +109,9 @@ namespace OS { } /** + * Add a tab to the beginning of the tab bar * - * - * @param {GenericObject} item + * @param {GenericObject} item tab data * @memberof TabBarTag */ unshift(item: GenericObject): ListViewItemTag { @@ -101,7 +120,7 @@ namespace OS { } /** - * + * Set tabs data * * @memberof TabBarTag */ @@ -113,7 +132,7 @@ namespace OS { } /** - * + * Get all tabs data * * @type {GenericObject[]} * @memberof TabBarTag @@ -123,7 +142,7 @@ namespace OS { } /** - * + * Select a tab by its index * * @memberof TabBarTag */ @@ -132,7 +151,7 @@ namespace OS { } /** - * + * Get the currently selected tab * * @type {(number | number[])} * @memberof TabBarTag @@ -142,7 +161,7 @@ namespace OS { } /** - * + * Set the tab close event handle * * @memberof TabBarTag */ @@ -151,7 +170,7 @@ namespace OS { } /** - * + * Set the tab select event handle * * @memberof TabBarTag */ @@ -160,7 +179,7 @@ namespace OS { } /** - * + * Mount the tab bar and bind some basic events * * @protected * @memberof TabBarTag @@ -178,7 +197,7 @@ namespace OS { } /** - * + * TabBar layout definition * * @protected * @returns {TagLayoutType[]} diff --git a/src/core/tags/TabContainerTag.ts b/src/core/tags/TabContainerTag.ts index bda7c6d..51f18cc 100644 --- a/src/core/tags/TabContainerTag.ts +++ b/src/core/tags/TabContainerTag.ts @@ -1,24 +1,54 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { + /** + * Tab container data type definition + * + * @export + * @interface TabContainerTabType + */ export interface TabContainerTabType { + /** + * Reference to the DOM element of the current container + * + * @type {HTMLElement} + * @memberof TabContainerTabType + */ container: HTMLElement; + [propName: string]: any; } export namespace tag { /** + * A tab container allows to attach each tab on a [[TabBarTag]] + * with a container widget. The attached container widget should be + * composed inside a [[HBoxTag]] * + * The tab bar in a tab container can be configured to display tabs + * in horizontal (row) or vertical (column) order. Default to vertical order + * + * Once a tab is selected, its attached container will be shown * * @export * @class TabContainerTag * @extends {AFXTag} */ export class TabContainerTag extends AFXTag { + /** + * Reference to the currently selected tab DOM element + * + * @private + * @type {TabContainerTabType} + * @memberof TabContainerTag + */ private _selectedTab: TabContainerTabType; + + /** + * Placeholder of the tab select event handle + * + * @private + * @type {TagEventCallback} + * @memberof TabContainerTag + */ private _ontabselect: TagEventCallback; /** @@ -28,11 +58,10 @@ namespace OS { constructor() { super(); this._ontabselect = (e) => {}; - } /** - * + * Init the tab bar direction to vertical (column) * * @protected * @memberof TabContainerTag @@ -42,7 +71,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @param {*} [d] @@ -51,7 +80,7 @@ namespace OS { protected reload(d?: any): void {} /** - * + * Set the tab select event handle * * @memberof TabContainerTag */ @@ -60,7 +89,9 @@ namespace OS { } /** - * + * Set the tab bar direction: + * - `row`: horizontal direction + * - `column`: vertical direction * * @memberof TabContainerTag */ @@ -73,7 +104,7 @@ namespace OS { } /** - * + * Get the tab bar direction * * @type {("row"| "column")} * @memberof TabContainerTag @@ -83,7 +114,8 @@ namespace OS { } /** - * + * Select a tab using the its tab data type. + * This will show the attached container to the tab * * @memberof TabContainerTag */ @@ -101,7 +133,7 @@ namespace OS { } /** - * + * Get the tab data of the currently selected Tab * * @type {TabContainerTabType} * @memberof TabContainerTag @@ -111,7 +143,9 @@ namespace OS { } /** - * + * Set the tab bar width, this function only + * works when the tab bar direction is set to + * `row` * * @memberof TabContainerTag */ @@ -124,7 +158,8 @@ namespace OS { } /** - * + * Set the tab bar height, this function only works + * when the tab bar direction is set to `column` * * @memberof TabContainerTag */ @@ -134,7 +169,7 @@ namespace OS { } /** - * + * Mount the tag and bind basic events * * @protected * @memberof TabContainerTag @@ -146,31 +181,38 @@ namespace OS { this.selectedTab = data; return this._ontabselect({ data: data, id: this.aid }); }; - this.observable.one("mounted", (id)=>{ - $(this.refs.yield).children().each((i, e) => { - const item = {} as GenericObject; - if ($(e).attr("tabname")) { - item.text = $(e).attr("tabname"); - } - if ($(e).attr("icon")) { - item.icon = $(e).attr("icon"); - } - if ($(e).attr("iconclass")) { - item.iconclass = $(e).attr("iconclass"); - } - item.container = e; - $(e).css("width", "100%").css("height", "100%").hide(); - const el = (this.refs.bar as TabBarTag).push(item); - el.selected = true; - }); - }) - + this.observable.one("mounted", (id) => { + $(this.refs.yield) + .children() + .each((i, e) => { + const item = {} as GenericObject; + if ($(e).attr("tabname")) { + item.text = $(e).attr("tabname"); + } + if ($(e).attr("icon")) { + item.icon = $(e).attr("icon"); + } + if ($(e).attr("iconclass")) { + item.iconclass = $(e).attr("iconclass"); + } + item.container = e; + $(e) + .css("width", "100%") + .css("height", "100%") + .hide(); + const el = (this.refs.bar as TabBarTag).push( + item + ); + el.selected = true; + }); + }); + this.observable.on("resize", (e) => this.calibrate()); this.calibrate(); } /** - * + * calibrate the tab container * * @memberof TabContainerTag */ @@ -179,7 +221,7 @@ namespace OS { } /** - * + * Layout definition * * @protected * @returns {TagLayoutType[]} diff --git a/src/core/tags/TileLayoutTags.ts b/src/core/tags/TileLayoutTags.ts index 4d0f713..a483c64 100644 --- a/src/core/tags/TileLayoutTags.ts +++ b/src/core/tags/TileLayoutTags.ts @@ -1,19 +1,49 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { + /** + * A tile layout organize it child elements + * in a fixed horizontal or vertical direction. + * + * The size of each child element is attributed based + * on its configuration of automatically based on the + * remaining space in the layout + * + * + * @export + * @class TileLayoutTag + * @extends {AFXTag} + */ export class TileLayoutTag extends AFXTag { + /** + *C reates an instance of TileLayoutTag. + * @memberof TileLayoutTag + */ constructor() { super(); } - // @setopt @conf.opt, "grow" - protected init(): void { - } + + /** + * Do nothing + * + * @protected + * @memberof TileLayoutTag + */ + protected init(): void {} + /** + * Do nothing + * + * @protected + * @param {*} [d] + * @memberof TileLayoutTag + */ protected reload(d?: any): void {} + + /** + * Set the name of the tile container, should be: `hbox` or `vbox` + * + * @memberof TileLayoutTag + */ set name(v: string) { if (!v) { return; @@ -25,10 +55,24 @@ namespace OS { this.calibrate(); } + /** + * Get the name of the tile container + * + * @type {string} + * @memberof TileLayoutTag + */ get name(): string { return $(this).attr("name"); } - set dir(v: "row"| "column") { + + /** + * SET the layout direction, should be: + * - `row`: horizontal direction + * - `column`: vertical direction + * + * @memberof TileLayoutTag + */ + set dir(v: "row" | "column") { if (!v) { return; } @@ -36,10 +80,24 @@ namespace OS { $(this.refs.yield).css("flex-direction", v); this.calibrate(); } - get dir(): "row"| "column" - { + + /** + * Get layout direction + * + * @type {("row"| "column")} + * @memberof TileLayoutTag + */ + get dir(): "row" | "column" { return $(this).attr("dir") as any; } + + /** + * Mount the element + * + * @protected + * @returns {void} + * @memberof TileLayoutTag + */ protected mount(): void { $(this).css("display", "block"); $(this.refs.yield) @@ -50,6 +108,12 @@ namespace OS { return this.calibrate(); } + /** + * re-organize the layout + * + * @returns {void} + * @memberof TileLayoutTag + */ calibrate(): void { if (this.dir === "row") { return this.hcalibrate(); @@ -59,6 +123,14 @@ namespace OS { } } + /** + * Organize the layout in horizontal direction, only work when + * the layout direction set to horizontal + * + * @private + * @returns {void} + * @memberof TileLayoutTag + */ private hcalibrate(): void { const auto_width = []; let ocwidth = 0; @@ -100,6 +172,14 @@ namespace OS { }); } + /** + * Organize the layout in vertical direction, only work when + * the layout direction set to vertical + * + * @private + * @returns {void} + * @memberof TileLayoutTag + */ private vcalibrate(): void { const auto_height = []; let ocheight = 0; @@ -142,6 +222,12 @@ namespace OS { }); } + /** + * Layout definition + * + * @returns + * @memberof TileLayoutTag + */ layout() { return [ { @@ -152,29 +238,61 @@ namespace OS { } } + /** + * A HBox organize its child elements in horizontal direction + * + * @export + * @class HBoxTag + * @extends {TileLayoutTag} + */ export class HBoxTag extends TileLayoutTag { + /** + * Creates an instance of HBoxTag. + * @memberof HBoxTag + */ constructor() { super(); } + /** + * Mount the tag + * + * @protected + * @memberof HBoxTag + */ protected mount(): void { super.mount(); this.dir = "row"; this.name = "hbox"; - } } + /** + * A VBox organize its child elements in vertical direction + * + * @export + * @class VBoxTag + * @extends {TileLayoutTag} + */ export class VBoxTag extends TileLayoutTag { + /** + *Creates an instance of VBoxTag. + * @memberof VBoxTag + */ constructor() { super(); - } + + /** + * Mount the tag + * + * @protected + * @memberof VBoxTag + */ protected mount(): void { super.mount(); this.dir = "column"; this.name = "vbox"; - } } diff --git a/src/core/tags/TreeViewTag.ts b/src/core/tags/TreeViewTag.ts index f17be2e..d415e92 100644 --- a/src/core/tags/TreeViewTag.ts +++ b/src/core/tags/TreeViewTag.ts @@ -1,40 +1,120 @@ -/* - * decaffeinate suggestions: - * DS101: Remove unnecessary use of Array.from - * DS102: Remove unnecessary code created because of implicit returns - * DS205: Consider reworking code to avoid use of IIFEs - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { /** - * + * Tree view data type definition * * @export * @interface TreeViewDataType */ export interface TreeViewDataType { + /** + * The child nodes data of the current tree node + * + * @type {TreeViewDataType[]} + * @memberof TreeViewDataType + */ nodes?: TreeViewDataType[]; + + /** + * Boolean indicates whether the current node is opened. + * Only work when the current node is not a leaf node + * + * @type {boolean} + * @memberof TreeViewDataType + */ open?: boolean; + + /** + * The node's path from the root node + * + * @type {string} + * @memberof TreeViewDataType + */ path?: string; + + /** + * Indicates whether this node should be selected + * + * @type {boolean} + * @memberof TreeViewDataType + */ selected?: boolean; [propName: string]: any; } - export type TreeItemEventData = TagEventDataType; /** - * + * Tree node event data type definition + */ + export type TreeItemEventData = TagEventDataType< + TreeViewItemPrototype + >; + /** + * Abstract prototype of a tree node. All tree node definition should + * extend this class * * @class TreeViewItemPrototype * @extends {AFXTag} */ export abstract class TreeViewItemPrototype extends AFXTag { + /** + * Node data placeholder + * + * @private + * @type {TreeViewDataType} + * @memberof TreeViewItemPrototype + */ private _data: TreeViewDataType; + + /** + * Placeholder for the indent level of the current node from root node + * + * @private + * @type {number} + * @memberof TreeViewItemPrototype + */ private _indent: number; + + /** + * private event object used by current node event + * + * @private + * @type {TagEventType} + * @memberof TreeViewItemPrototype + */ private _evt: TagEventType; + + /** + * Reference to the root node + * + * @type {TreeViewTag} + * @memberof TreeViewItemPrototype + */ treeroot: TreeViewTag; + + /** + * The tree path from the root node + * + * @type {string} + * @memberof TreeViewItemPrototype + */ treepath: string; + + /** + * Reference to the parent node of the current node + * + * @type {TreeViewTag} + * @memberof TreeViewItemPrototype + */ parent: TreeViewTag; + + /** + * Placeholder for the `fetch` function of the node. + * This function is used to fetch the child nodes of the + * current nodes. This function should a promise on + * a list of [[TreeViewDataType]] + * + * @memberof TreeViewItemPrototype + */ fetch: ( d: TreeViewItemPrototype ) => Promise; @@ -44,14 +124,20 @@ namespace OS { */ constructor() { super(); - } /** - * + * Update the tree, this function + * is used to refresh/expand/collapse the + * current node based on the input parameter * * @protected - * @param {*} p + * @param {*} p string indication, the value should be: + * - `expand`: expand the current node + * - `collapse`: collapse the current node + * - other string: this string is considered as a tree path of a node. If this value + * is the value of current node tree path, the node will be refreshed. Otherwise, nothing + * happens * @returns {void} * @memberof TreeViewItemPrototype */ @@ -75,7 +161,8 @@ namespace OS { } /** - * + * Set the data of the current node. This wll trigger the + * [[ondatachange]] function * * @memberof TreeViewItemPrototype */ @@ -94,7 +181,7 @@ namespace OS { } /** - * + * Get the current node's data * * @type {TreeViewDataType} * @memberof TreeViewItemPrototype @@ -104,7 +191,9 @@ namespace OS { } /** - * + * Select or unselect the current node. + * This will trigger the item select event + * on the tree root if the parameter is `true` * * @memberof TreeViewItemPrototype */ @@ -125,7 +214,7 @@ namespace OS { } /** - * + * Check whether the current node is selected * * @type {boolean} * @memberof TreeViewItemPrototype @@ -135,7 +224,9 @@ namespace OS { } /** - * + * Refresh the current node and expands its sub tree. + * This function only works if the current node is not + * a leaf node * * @memberof TreeViewItemPrototype */ @@ -169,13 +260,14 @@ namespace OS { "afx-tree-view-folder-open" ); } else { - $(this.refs.toggle).addClass("afx-tree-view-folder-close"); + $(this.refs.toggle).addClass( + "afx-tree-view-folder-close" + ); } - } /** - * + * Check whether the current node is expanded * * @type {boolean} * @memberof TreeViewItemPrototype @@ -184,7 +276,7 @@ namespace OS { return this.hasattr("open"); } /** - * + * Get the current indent level * * @type {number} * @memberof TreeViewItemPrototype @@ -194,7 +286,7 @@ namespace OS { } /** - * + * Set the current indent level of this node from the root node * * @memberof TreeViewItemPrototype */ @@ -213,7 +305,7 @@ namespace OS { } /** - * + * Check whether the current node is not a leaf node * * @private * @returns {boolean} @@ -228,7 +320,7 @@ namespace OS { } /** - * + * Get the child nodes data of the current node * * @type {TreeViewDataType[]} * @memberof TreeViewItemPrototype @@ -239,7 +331,7 @@ namespace OS { } /** - * + * Set the child nodes data of the current node * * @memberof TreeViewItemPrototype */ @@ -268,7 +360,13 @@ namespace OS { element.data = v; } } - + + /** + * Init the tag with default properties data + * + * @protected + * @memberof TreeViewItemPrototype + */ protected init(): void { this.treeroot = undefined; this.treepath = this.aid.toString(); @@ -279,7 +377,7 @@ namespace OS { this._indent = 0; } /** - * + * Mount the tag and bind basic events * * @protected * @memberof TreeViewItemPrototype @@ -310,7 +408,10 @@ namespace OS { } /** - * + * Layout definition of a node. This function + * returns the definition of the base outer layout + * of a node. Custom inner layout of the node should + * be defined in the [[itemlayout]] function * * @protected * @returns {TagLayoutType[]} @@ -346,7 +447,8 @@ namespace OS { } /** - * + * This function need to be implemented by all subclasses + * to define the inner layout of the node * * @protected * @abstract @@ -356,7 +458,9 @@ namespace OS { protected abstract itemlayout(): TagLayoutType[]; /** - * + * This function is called when the node data change. + * It needs to be implemented on all subclasses of this + * class * * @protected * @abstract @@ -365,9 +469,9 @@ namespace OS { protected abstract ondatachange(): void; } - /** - * + * SimpleTreeViewItem extends [[TreeViewItemPrototype]] and + * define it inner layout using a [[LabelTag]] * * @export * @class SimpleTreeViewItem @@ -383,7 +487,7 @@ namespace OS { } /** - * + * Refresh the label when data changed * * @protected * @returns {void} @@ -399,7 +503,7 @@ namespace OS { } /** - * + * Inner layout definition * * @protected * @returns @@ -410,29 +514,143 @@ namespace OS { } } - /** - * + * A tree view widget presents a hierarchical list of nodes. * * @export * @class TreeViewTag * @extends {AFXTag} */ export class TreeViewTag extends AFXTag { + /** + * Reference the the selected node + * + * @private + * @type {TreeViewItemPrototype} + * @memberof TreeViewTag + */ private _selectedItem: TreeViewItemPrototype; + + /** + * Placeholder for tree select event handle + * + * @private + * @type {TagEventCallback} + * @memberof TreeViewTag + */ private _ontreeselect: TagEventCallback; + + /** + * Place holder for tree double click event handle + * + * @private + * @type {TagEventCallback} + * @memberof TreeViewTag + */ private _ontreedbclick: TagEventCallback; - private _ondragndrop: TagEventCallback>; + + /** + * Placeholder for drag and drop event handle + * + * @private + * @type {TagEventCallback>} + * @memberof TreeViewTag + */ + private _ondragndrop: TagEventCallback< + DnDEventDataType + >; + + /** + * Tree data placeholder + * + * @private + * @type {TreeViewDataType} + * @memberof TreeViewTag + */ private _data: TreeViewDataType; + + /** + * Placeholder for private dragndrop mouse down event handle + * + * @private + * @memberof TreeViewTag + */ private _treemousedown: (e: JQuery.MouseEventBase) => void; + + /** + * Placeholder for private dragndrop mouse up event handle + * + * @private + * @memberof TreeViewTag + */ private _treemouseup: (e: JQuery.MouseEventBase) => void; + + /** + * Placeholder for private dragndrop mouse move event handle + * + * @private + * @memberof TreeViewTag + */ private _treemousemove: (e: JQuery.MouseEventBase) => void; + + /** + * Private data object passing between dragndrop mouse event + * + * @private + * @type {{ from: TreeViewTag; to: TreeViewTag }} + * @memberof TreeViewTag + */ private _dnd: { from: TreeViewTag; to: TreeViewTag }; + + /** + * Reference to parent tree of the current tree. + * This value is undefined if the current tree is the root + * + * @type {TreeViewTag} + * @memberof TreeViewTag + */ parent: TreeViewTag; + + /** + * Reference to the root tree, this value is undefined + * if the curent tree is root + * + * @type {TreeViewTag} + * @memberof TreeViewTag + */ treeroot: TreeViewTag; + + /** + * tree path of the current tree from the root + * + * @type {string} + * @memberof TreeViewTag + */ treepath: string; + + /** + * Indent level of the current tree + * + * @type {number} + * @memberof TreeViewTag + */ indent: number; + + /** + * Indicates whether the tree should be expanded + * + * @type {boolean} + * @memberof TreeViewTag + */ open: boolean; + /** + * Placeholder for the `fetch` function of the tree. + * This function is used to fetch the child nodes of the + * current tree. This function should a promise on + * a list of [[TreeViewDataType]] + * + * @memberof TreeViewItemPrototype + */ fetch: ( d: TreeViewItemPrototype ) => Promise; @@ -443,11 +661,10 @@ namespace OS { */ constructor() { super(); - } /** - * + * Init the tree view before mounting: * * @protected * @memberof TreeViewTag @@ -464,7 +681,7 @@ namespace OS { } /** - * + * Layout definition * * @protected * @returns {TagLayoutType[]} @@ -475,7 +692,7 @@ namespace OS { } /** - * + * Do nothing * * @protected * @param {*} [d] @@ -483,7 +700,7 @@ namespace OS { */ protected reload(d?: any): void {} /** - * + * Enable/disable drag and drop event on the tree * * @memberof TreeViewTag */ @@ -492,7 +709,7 @@ namespace OS { } /** - * + * Check whether the drag and drop event is enabled * * @type {boolean} * @memberof TreeViewTag @@ -502,7 +719,7 @@ namespace OS { } /** - * + * Set the tree select event handle * * @memberof TreeViewTag */ @@ -511,7 +728,7 @@ namespace OS { } /** - * + * Set the tree double click event handle * * @memberof TreeViewTag */ @@ -520,7 +737,11 @@ namespace OS { } /** + * Set the default tag name of the tree node. + * If there is no tag name in the node data, + * this value will be used when creating node. * + * Defaut to `afx-tree-view-item` * * @memberof TreeViewTag */ @@ -529,7 +750,7 @@ namespace OS { } /** - * + * Get the default node tag name * * @type {string} * @memberof TreeViewTag @@ -539,7 +760,7 @@ namespace OS { } /** - * + * Unselect the selected element in the tree * * @memberof TreeViewTag */ @@ -550,7 +771,7 @@ namespace OS { } /** - * + * Get the DOM element of the selected node * * @type {TreeViewItemPrototype} * @memberof TreeViewTag @@ -560,7 +781,7 @@ namespace OS { } /** - * + * Set the selected node using its DOM element * * @memberof TreeViewTag */ @@ -575,7 +796,7 @@ namespace OS { } /** - * + * Expand all nodes in the tree * * @returns {void} * @memberof TreeViewTag @@ -588,7 +809,7 @@ namespace OS { } /** - * + * Collapse all nodes in the tree * * @returns {void} * @memberof TreeViewTag @@ -601,7 +822,8 @@ namespace OS { } /** - * + * This function will trigger the tree select or tree double click + * event * * @param {TagEventType} e * @returns {void} @@ -626,7 +848,7 @@ namespace OS { } /** - * + * Check whether the current tree is a root tree * * @returns {boolean} * @memberof TreeViewTag @@ -636,7 +858,7 @@ namespace OS { } /** - * + * Check whether the current tree tag is a leaf * * @returns {boolean} * @memberof TreeViewTag @@ -654,21 +876,24 @@ namespace OS { } /** - * + * Set drag and drop event handle * * @memberof TreeViewTag */ - set ondragndrop(v: TagEventCallback>) { + set ondragndrop( + v: TagEventCallback> + ) { this._ondragndrop = v; } /** - * + * Set the tree data. This operation will create + * all tree node elements of the current tree * * @memberof TreeViewTag */ set data(v: TreeViewDataType) { - this._selectedItem = undefined + this._selectedItem = undefined; if (!v) { return; } @@ -700,7 +925,7 @@ namespace OS { } /** - * + * Get the tree data * * @type {TreeViewDataType} * @memberof TreeViewTag @@ -710,7 +935,7 @@ namespace OS { } /** - * + * Mount the tree view * * @protected * @memberof TreeViewTag diff --git a/src/core/tags/WindowTag.ts b/src/core/tags/WindowTag.ts index fc39991..705c5da 100644 --- a/src/core/tags/WindowTag.ts +++ b/src/core/tags/WindowTag.ts @@ -1,23 +1,96 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ namespace OS { export namespace GUI { export namespace tag { + /** + * A WindowTag represents a virtual window element + * used by AntOS applications and dialogs. + * + * @export + * @class WindowTag + * @extends {AFXTag} + */ export class WindowTag extends AFXTag { + /** + * The element ID of the virtual desktop element + * + * @type {string} + * @memberof WindowTag + */ desktop: string; + + /** + * Window width placeholder + * + * @private + * @type {number} + * @memberof WindowTag + */ private _width: number; + + /** + * Window height placeholder + * + * @private + * @type {number} + * @memberof WindowTag + */ private _height: number; + + /** + * Placeholder indicates whether the current window is shown + * + * @private + * @type {boolean} + * @memberof WindowTag + */ private _shown: boolean; + + /** + * Placeholder indicates whether the current window is maximized + * + * @private + * @type {boolean} + * @memberof WindowTag + */ private _isMaxi: boolean; + + /** + * This placeholder stores the latest offset of the current window. + * + * @private + * @type {GenericObject} + * @memberof WindowTag + */ private _history: GenericObject; + + /** + * This placeholder stores the offset of the virtual desktop element + * + * @private + * @type {GenericObject} + * @memberof WindowTag + */ private _desktop_pos: GenericObject; + + /** + * Creates an instance of WindowTag. + * @memberof WindowTag + */ constructor() { super(); } + /** + * Init window tag + * - `shown`: false + * - `isMaxi`: false + * - `minimizable`: false + * - `resizable`: true + * - `apptitle`: Untitled + * + * @protected + * @memberof WindowTag + */ protected init(): void { this._shown = false; this._isMaxi = false; @@ -27,11 +100,30 @@ namespace OS { this.minimizable = true; this.resizable = true; this.apptitle = "Untitled"; - } + + /** + * Do nothing + * + * @protected + * @memberof WindowTag + */ protected calibrate(): void {} + + /** + * Do nothing + * + * @protected + * @param {*} [d] + * @memberof WindowTag + */ protected reload(d?: any): void {} + /** + * Set the window width + * + * @memberof WindowTag + */ set width(v: number) { this._width = v; if (!v) { @@ -39,10 +131,22 @@ namespace OS { } this.setsize({ w: v, h: this.height }); } + + /** + * Get the window width + * + * @type {number} + * @memberof WindowTag + */ get width(): number { return this._width; } + /** + * Set the window height + * + * @memberof WindowTag + */ set height(v: number) { this._height = v; if (!v) { @@ -54,9 +158,21 @@ namespace OS { }); } + /** + * Get the window height + * + * @type {number} + * @memberof WindowTag + */ get height(): number { return this._height; } + + /** + * enable/disable window minimizable + * + * @memberof WindowTag + */ set minimizable(v: boolean) { this.attsw(v, "minimizable"); if (v) { @@ -65,9 +181,22 @@ namespace OS { $(this.refs["minbt"]).hide(); } } + + /** + * Check whether the window is minimizable + * + * @type {boolean} + * @memberof WindowTag + */ get minimizable(): boolean { return this.hasattr("minimizable"); } + + /** + * enable/disable widow resizable + * + * @memberof WindowTag + */ set resizable(v: boolean) { this.attsw(v, "resizable"); if (v) { @@ -78,19 +207,45 @@ namespace OS { $(this.refs["grip"]).hide(); } } + + /** + * Check whether the current window is resizable + * + * @type {boolean} + * @memberof WindowTag + */ get resizable(): boolean { return this.hasattr("resizable"); } - set apptitle(v: string| FormattedString) { + + /** + * Set the window title + * + * @memberof WindowTag + */ + set apptitle(v: string | FormattedString) { $(this).attr("apptitle", v.__()); if (v) { (this.refs["txtTitle"] as LabelTag).text = v; } } - get apptitle(): string| FormattedString { + + /** + * Get window title + * + * @type {(string| FormattedString)} + * @memberof WindowTag + */ + get apptitle(): string | FormattedString { return $(this).attr("apptitle"); } + /** + * Resize all the children of the window based on its width and height + * + * @private + * @memberof WindowTag + */ private resize(): void { const ch = $(this.refs["yield"]).height() / @@ -102,8 +257,14 @@ namespace OS { }); } + /** + * Mount the window tag and bind basic events + * + * @protected + * @returns {void} + * @memberof WindowTag + */ protected mount(): void { - this.contextmenuHandle = function (e) {}; $(this.refs["minbt"]).click((e) => { return this.observable.trigger("hide", { @@ -182,6 +343,14 @@ namespace OS { }); } + /** + * Set the window size + * + * @private + * @param {GenericObject} o format: `{ w: window_width, h: window_height }` + * @returns {void} + * @memberof WindowTag + */ private setsize(o: GenericObject): void { if (!o) { return; @@ -196,6 +365,12 @@ namespace OS { }); } + /** + * Enable to drag window on the virtual desktop + * + * @private + * @memberof WindowTag + */ private enable_dragging(): void { $(this.refs["dragger"]) .css("user-select", "none") @@ -237,6 +412,13 @@ namespace OS { }); } + /** + * Enable window resize, this only works if the window + * is resizable + * + * @private + * @memberof WindowTag + */ private enable_resize(): void { $(this.refs["grip"]) .css("user-select", "none") @@ -269,6 +451,14 @@ namespace OS { }); } + /** + * Maximize the window or restore its previous width, height, + * and position + * + * @private + * @returns {void} + * @memberof WindowTag + */ private toggle_window(): void { let h: number, w: number; if (!this.resizable) { @@ -298,6 +488,13 @@ namespace OS { } } + /** + * Layout definition of the window tag + * + * @protected + * @returns {TagLayoutType[]} + * @memberof WindowTag + */ protected layout(): TagLayoutType[] { return [ { diff --git a/src/core/tags/tag.ts b/src/core/tags/tag.ts index 995c8be..a42c569 100644 --- a/src/core/tags/tag.ts +++ b/src/core/tags/tag.ts @@ -629,14 +629,14 @@ namespace OS { }; /** * All the AFX tags are defined in this namespace, - * these tags are are defined as custom DOM elements and will be + * these tags are defined as custom DOM elements and will be * stored in the `customElements` registry of the browser */ export namespace tag { /** * Define an AFX tag as a custom element and add it to the * global `customElements` registry. If the tag is redefined, i.e. - * the tag already exist, its behavior will be updated with the + * the tag already exists, its behavior will be updated with the * new definition * * @export