dany/antos-frontend
1
0
Fork 0
mirror of https://github.com/lxsang/antos-frontend.git synced 2025-07-18 06:49:47 +02:00
Code Issues 1 Actions Projects Releases Wiki Activity

add more doc

Browse Source
This commit is contained in:
lxsang
2020-06-12 20:24:39 +02:00
parent d5df803c2c
commit 218f6142c6
24 changed files with 1006 additions and 793 deletions
Download Patch File Download Diff File Expand all files Collapse all files

369
src/core/BaseModel.ts
View File

@ -1,9 +1,3 @@
/*
* decaffeinate suggestions:
* DS102: Remove unnecessary code created because of implicit returns
* DS208: Avoid top-level this
* Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md
*/
// Copyright 2017-2018 Xuan Sang LE <xsang.le AT gmail DOT com>
// AnTOS Web desktop is is licensed under the GNU General Public
@ -23,42 +17,92 @@
//along with this program. If not, see https://www.gnu.org/licenses/.
namespace OS {
/**
*
* Application argument type definition
*
* @export
* @interface AppArgumentsType
*/
export interface AppArgumentsType {
/**
* File type to be open by the app
*
* @type {string}
* @memberof AppArgumentsType
*/
type?: string;
/**
* File path to be opened
*
* @type {string}
* @memberof AppArgumentsType
*/
path: string;
/**
* Any other object
*/
[propName: string]: any;
}
/**
*
* Enum definition of different model types
*
* @export
* @enum {number}
*/
export enum ModelType {
/**
* Applications
*/
Application,
/**
* Services
*/
Service,
/**
* Sub-window such as dialogs
*/
SubWindow,
}
/**
*
* Base AntOS event definition
*
* @export
* @class BaseEvent
*/
export class BaseEvent {
/**
* The event name placeholder
*
* @type {string}
* @memberof BaseEvent
*/
name: string;
/**
* Placeholder indicates whether the event is forced to
* be happen
*
* @private
* @type {boolean}
* @memberof BaseEvent
*/
private force: boolean;
/**
* Placeholder indicates whether the event is prevented.
* This value has not effect if `force` is set to `true`
*
* @type {boolean}
* @memberof BaseEvent
*/
prevent: boolean;
/**
*Creates an instance of BaseEvent.
* @param {string} name
* @param {boolean} force
* @param {string} name event name
* @param {boolean} force indicates whether the event is forced
* @memberof BaseEvent
*/
constructor(name: string, force: boolean) {
@ -68,7 +112,8 @@ namespace OS {
}
/**
*
* Prevent the current event. This function
* has no effect if `force` is set to true
*
* @memberof BaseEvent
*/
@ -80,34 +125,164 @@ namespace OS {
}
/**
*
* The root model of all applications, dialogs or services
* in the system
*
* @export
* @abstract
* @class BaseModel
*/
export abstract class BaseModel {
/**
* The class name
*
* @type {string}
* @memberof BaseModel
*/
name: string;
/**
* The argument of the model
*
* @type {AppArgumentsType[]}
* @memberof BaseModel
*/
args: AppArgumentsType[];
/**
* Each model has its own local announcement system
* to handle all local events inside that model.
*
* This observable object is propagate to all the
* UI elements ([[AFXTag]]) inside the model
*
* @protected
* @type {API.Announcer}
* @memberof BaseModel
*/
protected _observable: API.Announcer;
/**
* Reference to the core API namespace
*
* @protected
* @type {typeof API}
* @memberof BaseModel
*/
protected _api: typeof API;
/**
* Reference to the core GUI namespace
*
* @protected
* @type {typeof GUI}
* @memberof BaseModel
*/
protected _gui: typeof GUI;
/**
* Reference to the model's dialog
*
* @type {GUI.BaseDialog}
* @memberof BaseModel
*/
dialog: GUI.BaseDialog;
/**
* The HTML element ID of the virtual desktop
*
* @protected
* @type {string}
* @memberof BaseModel
*/
protected host: string;
/**
* The process number of the current model.
* For sub-window this number is the number
* of the parent window
*
* @type {number}
* @memberof BaseModel
*/
pid: number;
/**
* Reference the DOM element of the UI scheme belong to
* this model
*
* @type {HTMLElement}
* @memberof BaseModel
*/
scheme: HTMLElement;
/**
* Reference to the system setting
*
* @protected
* @type {typeof setting}
* @memberof BaseModel
*/
protected systemsetting: typeof setting;
/**
* Placeholder for the process creation timestamp
*
* @type {number}
* @memberof BaseModel
*/
birth: number;
/**
* Different model type
*
* @static
* @type {ModelType}
* @memberof BaseModel
*/
static type: ModelType;
/**
* Allow singleton on this model
*
* @static
* @type {boolean}
* @memberof BaseModel
*/
static singleton: boolean;
/**
* The javacript of css dependencies of the model. All dependencies
* will be loaded before the model is rendered
*
* @static
* @type {string[]} list of VFS paths of dependencies
* @memberof BaseModel
*/
static dependencies: string[];
/**
* Reference to the CSS Element of the model
*
* @static
* @type {(HTMLElement | string)}
* @memberof BaseModel
*/
static style: HTMLElement | string;
/**
* Place holder for model meta-data
*
* @static
* @type {API.PackageMetaType}
* @memberof BaseModel
*/
static meta: API.PackageMetaType;
/**
*Creates an instance of BaseModel.
* @param {string} name
* @param {AppArgumentsType[]} args
* @param {string} name class name
* @param {AppArgumentsType[]} args arguments
* @memberof BaseModel
*/
constructor(name: string, args: AppArgumentsType[]) {
@ -126,12 +301,18 @@ namespace OS {
});
}
get observable(): API.Announcer
{
/**
* Getter: get the local announcer object
*
* @readonly
* @type {API.Announcer}
* @memberof BaseModel
*/
get observable(): API.Announcer {
return this._observable;
}
/**
*
* Update the model locale
*
* @protected
* @param {string} name
@ -139,10 +320,10 @@ namespace OS {
*/
protected updateLocale(name: string) {}
/**
*
* Render the model's UI
*
* @protected
* @param {string} p
* @param {string} p VFS path to the UI scheme definition
* @returns {void}
* @memberof BaseModel
*/
@ -151,9 +332,9 @@ namespace OS {
}
/**
* Exit the model
*
*
* @param {boolean} force
* @param {boolean} force set this value to `true` will bypass the prevented exit event by user
* @returns {void}
* @memberof BaseModel
*/
@ -171,7 +352,8 @@ namespace OS {
}
/**
*
* Model meta data, need to be implemented by
* subclasses
*
* @abstract
* @returns {API.PackageMetaType}
@ -180,7 +362,7 @@ namespace OS {
abstract meta(): API.PackageMetaType;
/**
*
* VFS path to the model asset
*
* @returns {string}
* @memberof BaseModel
@ -193,13 +375,20 @@ namespace OS {
return null;
}
// call a server side script
/**
*
* Execute a server side script and get back the result
*
* @protected
* @param {GenericObject<any>} cmd
* @param {GenericObject<any>} cmd execution indication, should be:
*
* ```
* {
* path?: string, // VFS path to the server side script
* code: string, // or server side code to be executed
* parameters: any // the parameters of the server side execution
* }
* ```
*
* @returns {Promise<any>}
* @memberof BaseModel
*/
@ -208,7 +397,18 @@ namespace OS {
}
/**
* Connect to the server side api using a websocket connection
*
* Server side script can be execute inside the stream by writing
* data in JSON format with the following interface
*
* ```
* {
* path?: string, // VFS path to the server side script
* code: string, // or server side code to be executed
* parameters: any // the parameters of the server side execution
* }
* ```
*
* @protected
* @returns {Promise<WebSocket>}
@ -219,7 +419,7 @@ namespace OS {
}
/**
*
* Init the model before UI rendering
*
* @abstract
* @memberof BaseModel
@ -227,7 +427,7 @@ namespace OS {
abstract init(): void;
/**
*
* Main entry point after UI rendering
*
* @abstract
* @memberof BaseModel
@ -235,7 +435,7 @@ namespace OS {
abstract main(): void;
/**
*
* Show the model
*
* @abstract
* @memberof BaseModel
@ -243,33 +443,29 @@ namespace OS {
abstract show(): void;
/**
*
* Hide the model
*
* @abstract
* @memberof BaseModel
*/
abstract hide(): void;
//implement by sub class
/**
*
* Function called when the model exits
*
* @protected
* @abstract
* @param {BaseEvent} e
* @param {BaseEvent} e exit event
* @memberof BaseModel
*/
protected abstract onexit(e: BaseEvent): void;
//implement by subclass
/**
*
* subscribe once to a local event
*
* @protected
* @param {string} e
* @param {(d: any) => void} f
* @param {string} e name of the event
* @param {(d: any) => void} f event callback
* @returns {void}
* @memberof BaseModel
*/
@ -277,13 +473,12 @@ namespace OS {
return this.observable.one(e, f);
}
/**
*
* Subscribe to a local event
*
* @protected
* @param {string} e
* @param {(d: any) => void} f
* @param {string} e event name
* @param {(d: any) => void} f event callback
* @returns {void}
* @memberof BaseModel
*/
@ -291,13 +486,12 @@ namespace OS {
return this.observable.on(e, f);
}
/**
*
* Unsubscribe an event
*
* @protected
* @param {string} e
* @param {(d: any) => void} [f]
* @param {string} e event name or `*` (all events)
* @param {(d: any) => void} [f] callback to be unsubscribed, can be `undefined`
* @returns {void}
* @memberof BaseModel
*/
@ -308,28 +502,26 @@ namespace OS {
return this.observable.off(e, f);
}
/**
*
* trigger a local event
*
* @protected
* @param {string} e
* @param {*} [d]
* @param {string} e event name
* @param {*} [d] event data
* @returns {void}
* @memberof BaseModel
*/
trigger(e: string, d?: any): void {
if(!this.observable) return;
if (!this.observable) return;
this.observable.trigger(e, d);
}
/**
*
* subscribe to an event on the global announcement system
*
* @protected
* @param {string} e
* @param {(d: any) => void} f
* @param {string} e event name
* @param {(d: any) => void} f event callback
* @returns {void}
* @memberof BaseModel
*/
@ -337,13 +529,14 @@ namespace OS {
return announcer.on(e, f, this);
}
/**
* Open a dialog
*
*
* @param {(GUI.BaseDialog | string)} d
* @param {GenericObject<any>} [data]
* @returns {Promise<any>}
* @param {(GUI.BaseDialog | string)} d a dialog object or a dialog class name
* @param {GenericObject<any>} [data] input data of the dialog, refer to each
* dialog definition for the format of the input data
* @returns {Promise<any>} A promise on the callback data of the dialog, refer
* to each dialog definition for the format of the callback data
* @memberof BaseModel
*/
openDialog(
@ -369,32 +562,30 @@ namespace OS {
this.dialog.handle = resolve;
this.dialog.pid = this.pid;
this.dialog.data = data;
if (data && data.title) {
this.dialog.title = data.title;
}
return this.dialog.init();
});
}
/**
*
* Open a [[YesNoDialog]] to confirm a task
*
* @protected
* @param {GenericObject<any>} data
* @returns {Promise<any>}
* @param {GenericObject<any>} data [[YesNoDialog]] input data
* @returns {Promise<boolean>}
* @memberof BaseModel
*/
protected ask(data: GenericObject<any>): Promise<any> {
protected ask(data: GenericObject<any>): Promise<boolean> {
return this._gui.openDialog("YesNoDialog", data);
}
/**
*
* Trigger a global event
*
* @protected
* @param {string} t
* @param {(string | FormattedString)} m
* @param {Error} [e]
* @param {string} t event name
* @param {(string | FormattedString)} m event message
* @param {Error} [e] error object if any
* @returns {void}
* @memberof BaseModel
*/
@ -421,9 +612,9 @@ namespace OS {
}
/**
* Publish a global notification
*
*
* @param {(string | FormattedString)} m
* @param {(string | FormattedString)} m notification string
* @returns {void}
* @memberof BaseModel
*/
@ -432,9 +623,9 @@ namespace OS {
}
/**
* Publish a global warning
*
*
* @param {(string | FormattedString)} m
* @param {(string | FormattedString)} m warning string
* @returns {void}
* @memberof BaseModel
*/
@ -443,10 +634,10 @@ namespace OS {
}
/**
* Report a global error
*
*
* @param {(string | FormattedString)} m
* @param {Error} [e]
* @param {(string | FormattedString)} m error message
* @param {Error} [e] error object if any
* @returns
* @memberof BaseModel
*/
@ -455,10 +646,10 @@ namespace OS {
}
/**
* Report a global fail event
*
*
* @param {string} m
* @param {Error} [e]
* @param {string} m fail message
* @param {Error} [e] error object if any
* @returns
* @memberof BaseModel
*/
@ -467,7 +658,7 @@ namespace OS {
}
/**
*
* Throw an error inside the model
*
* @returns {Error}
* @memberof BaseModel
@ -477,7 +668,7 @@ namespace OS {
}
/**
*
* Update the model, this will update all its UI elements
*
* @returns {void}
* @memberof BaseModel
@ -489,7 +680,8 @@ namespace OS {
}
/**
*
* Find a HTMLElement in the UI of the model
* using the `data-id` attribute of the element
*
* @protected
* @param {string} id
@ -503,7 +695,8 @@ namespace OS {
}
/**
*
* Select all DOM Element inside the UI of the model
* using JQuery selector
*
* @protected
* @param {string} sel