add more docs, fix minor bug on dialog registration

This commit is contained in:
lxsang 2020-06-15 18:10:13 +02:00
parent 218f6142c6
commit 977bf0c62f
7 changed files with 400 additions and 76 deletions

View File

@ -24,7 +24,7 @@ namespace OS {
*/ */
export namespace application { export namespace application {
/** /**
* Abstract prototype of all AntOS application. * Abstract prototype of all AntOS applications.
* Any new application definition should extend * Any new application definition should extend
* this prototype * this prototype
* *
@ -97,7 +97,7 @@ namespace OS {
/** /**
* Init the application, this function is called when the * Init the application, this function is called when the
* application process is called and docked the the application * application process is created and docked in the application
* dock. * dock.
* *
* The application UI will be rendered after the execution * The application UI will be rendered after the execution
@ -380,7 +380,7 @@ namespace OS {
/** /**
* Base menu definition. This function * Base menu definition. This function
* return the based menu definition of all applications. * returns the based menu definition of all applications.
* Other application specific menu entries * Other application specific menu entries
* should be defined in [[menu]] function * should be defined in [[menu]] function
* *

View File

@ -203,7 +203,7 @@ namespace OS {
private markup: string | OS.API.VFS.BaseFileHandle; private markup: string | OS.API.VFS.BaseFileHandle;
/** /**
* If the `markup` variable is not provided, the * If the `markup` variable is not provided, then
* the [[init]] function will find the scheme definition * the [[init]] function will find the scheme definition
* in this class variable * in this class variable
* *
@ -277,7 +277,7 @@ namespace OS {
* Simple prompt dialog to get user input text. * Simple prompt dialog to get user input text.
* The input date of the dialog: * The input date of the dialog:
* *
* ``` * ```typescript
* { * {
* title: string, // window title * title: string, // window title
* label: string, // label text * label: string, // label text
@ -458,7 +458,7 @@ namespace OS {
* *
* Input data: * Input data:
* *
* ``` * ```typescript
* { * {
* title: string // window title * title: string // window title
* } * }
@ -531,7 +531,7 @@ namespace OS {
* *
* Input data: * Input data:
* *
* ``` * ```typescript
* { * {
* title: string // window title * title: string // window title
* } * }
@ -610,7 +610,7 @@ namespace OS {
* *
* Input data: * Input data:
* *
* ``` * ```typescript
* { * {
* title: string, // window title * title: string, // window title
* [propName:string]: any * [propName:string]: any
@ -689,7 +689,7 @@ namespace OS {
* *
* Input data: * Input data:
* *
* ``` * ```typescript
* { * {
* title: string, // window title * title: string, // window title
* icon?: string, // label icon * icon?: string, // label icon
@ -771,7 +771,7 @@ namespace OS {
* *
* Input data: * Input data:
* *
* ``` * ```typescript
* { * {
* title: string, // window title * title: string, // window title
* data: * data:
@ -941,7 +941,7 @@ namespace OS {
* *
* Input data: * Input data:
* *
* ``` * ```typescript
* { * {
* title: string, // window title * title: string, // window title
* root?: string, // the root path folder of the file view * root?: string, // the root path folder of the file view
@ -953,6 +953,15 @@ namespace OS {
* } * }
* ``` * ```
* *
* Callback data:
*
* ```typescript
* {
* file: string, // selected file path
* name: string // user input file name
* }
* ```
*
* @export * @export
* @class FileDialog * @class FileDialog
* @extends {BasicDialog} * @extends {BasicDialog}

View File

@ -18,7 +18,14 @@
namespace OS { namespace OS {
export namespace application { export namespace application {
/** /**
* Services are processes that run in the background and
* are waken up in certain circumstances such as global
* events or user interactions.
* *
* Each service takes an entry in the system tray menu
* located on the system panel. This menu entry is used
* to access to service visual contents such as: options,
* task performing based on user interaction, etc.
* *
* @export * @export
* @abstract * @abstract
@ -26,18 +33,70 @@ namespace OS {
* @extends {BaseModel} * @extends {BaseModel}
*/ */
export abstract class BaseService extends BaseModel { export abstract class BaseService extends BaseModel {
/**
* The service icon shown in the system tray
*
* @type {string}
* @memberof BaseService
*/
icon: string; icon: string;
/**
* CSS class of the service icon shown in the system tray
*
* @type {string}
* @memberof BaseService
*/
iconclass: string; iconclass: string;
/**
* Text of the service shown in the system tray
*
* @type {string}
* @memberof BaseService
*/
text: string; text: string;
/**
* Reference to the menu entry DOM element attached
* to the service
*
* @type {HTMLElement}
* @memberof BaseService
*/
domel: HTMLElement; domel: HTMLElement;
/**
* Reference to the timer that periodically execute the callback
* defined in [[watch]].
*
* @private
* @type {number}
* @memberof BaseService
*/
private timer: number; private timer: number;
/**
* Reference to th system tray menu
*
* @type {HTMLElement}
* @memberof BaseService
*/
holder: HTMLElement; holder: HTMLElement;
onmenuselect: (d: OS.GUI.TagEventType<GUI.tag.MenuEventData>) => void;
/**
* Place holder for service select callback
*
* @memberof BaseService
*/
onmenuselect: (
d: OS.GUI.TagEventType<GUI.tag.MenuEventData>
) => void;
/** /**
*Creates an instance of BaseService. *Creates an instance of BaseService.
* @param {string} name * @param {string} name service class name
* @param {AppArgumentsType[]} args * @param {AppArgumentsType[]} args service arguments
* @memberof BaseService * @memberof BaseService
*/ */
constructor(name: string, args: AppArgumentsType[]) { constructor(name: string, args: AppArgumentsType[]) {
@ -53,25 +112,27 @@ namespace OS {
} }
/** /**
* * Do nothing
* *
* @memberof BaseService * @memberof BaseService
*/ */
hide(): void {} hide(): void {}
/** /**
* Init the service before attaching it to
* the system tray: event subscribe, scheme
* loading.
* *
* Should be implemented by all subclasses
* *
* @abstract * @abstract
* @memberof BaseService * @memberof BaseService
*/ */
abstract init(): void; abstract init(): void;
//implement by user
// event registe, etc
// scheme loader
/** /**
* * Refresh the service menu entry in the
* system tray
* *
* @memberof BaseService * @memberof BaseService
*/ */
@ -80,7 +141,7 @@ namespace OS {
} }
/** /**
* * Get the service meta-data
* *
* @returns {API.PackageMetaType} * @returns {API.PackageMetaType}
* @memberof BaseService * @memberof BaseService
@ -90,7 +151,8 @@ namespace OS {
} }
/** /**
* * Attach the service to a menu element
* such as the system tray menu
* *
* @param {HTMLElement} h * @param {HTMLElement} h
* @memberof BaseService * @memberof BaseService
@ -99,30 +161,35 @@ namespace OS {
this.holder = h; this.holder = h;
} }
/** /**
* Set the callback that will be called periodically
* after a period of time.
* *
* Each service should only have at most one watcher
* *
* @protected * @protected
* @param {number} t * @param {number} t period time in seconds
* @param {() => void} f * @param {() => void} f callback function
* @returns {number} * @returns {number}
* @memberof BaseService * @memberof BaseService
*/ */
protected watch(t: number, f: () => void): number { protected watch(t: number, f: () => void): number {
var func = () => { var func = () => {
f(); f();
if (this.timer) {
clearTimeout(this.timer);
}
return (this.timer = setTimeout(() => func(), t)); return (this.timer = setTimeout(() => func(), t));
}; };
return func(); return func();
} }
/** /**
* * This function is called when the service
* is exited
* *
* @protected * @protected
* @param {BaseEvent} evt * @param {BaseEvent} evt exit event
* @returns * @returns
* @memberof BaseService * @memberof BaseService
*/ */
@ -140,32 +207,34 @@ namespace OS {
} }
/** /**
* * Do nothing
* *
* @memberof BaseService * @memberof BaseService
*/ */
main(): void {} main(): void {}
/** /**
* * Do nothing
* *
* @memberof BaseService * @memberof BaseService
*/ */
show(): void {} show(): void {}
/** /**
* Awake the service, this function is usually called when
* the system tray menu entry attached to the service is
* selected.
* *
* This function should be implemented by all subclasses
* *
* @abstract * @abstract
* @param {GUI.TagEventType} e * @param {GUI.TagEventType} e
* @memberof BaseService * @memberof BaseService
*/ */
abstract awake(e: GUI.TagEventType<GUI.tag.MenuEventData>): void; abstract awake(e: GUI.TagEventType<GUI.tag.MenuEventData>): void;
//implement by user to tart the service
/** /**
* * Do nothing
* *
* @protected * @protected
* @param {BaseEvent} evt * @param {BaseEvent} evt
@ -173,7 +242,7 @@ namespace OS {
*/ */
protected cleanup(evt: BaseEvent) {} protected cleanup(evt: BaseEvent) {}
} }
//implemeted by user
BaseService.type = ModelType.Service; BaseService.type = ModelType.Service;
BaseService.singleton = true; BaseService.singleton = true;
} }

View File

@ -17,39 +17,156 @@
//along with this program. If not, see https://www.gnu.org/licenses/. //along with this program. If not, see https://www.gnu.org/licenses/.
"use strict"; "use strict";
/**
* Reference to the global this
*/
const Ant = this; const Ant = this;
/** /**
* * Extend the String prototype with some API
* functions used by AntOS API
* *
* @interface String * @interface String
*/ */
interface String { interface String {
/**
* Simple string hash function
*
* @returns {number}
* @memberof String
*/
hash(): number; hash(): number;
/**
* Parse the current string and convert it
* to an object of type [[Version]] if the string
* is in the format recognized by [[Version]],
* e.g.: `1.0.1-a`
*
* @returns {OS.Version}
* @memberof String
*/
__v(): OS.Version; __v(): OS.Version;
/**
* Convert the current string to base 64 string
*
* @returns {string}
* @memberof String
*/
asBase64(): string; asBase64(): string;
/**
* Unescape all escaped characters on the
* string using `\`
*
* @returns {string}
* @memberof String
*/
unescape(): string; unescape(): string;
/**
* Convert the current string to uint8 array
*
* @returns {Uint8Array}
* @memberof String
*/
asUint8Array(): Uint8Array; asUint8Array(): Uint8Array;
/**
* Format the current using input parameters.
* The current string should be a formatted string
* in the following form:
*
* ```typescript
* "example string: {0} and {1}".format("hello", "world")
* // return "example string: hello and world"
* ```
*
* @param {...any[]} args
* @returns {string}
* @memberof String
*/
format(...args: any[]): string; format(...args: any[]): string;
/**
* Create a [[FormattedString]] object using the current
* string and the input parameters
*
* @param {...any[]} args
* @returns {OS.FormattedString}
* @memberof String
*/
f(...args: any[]): OS.FormattedString; f(...args: any[]): OS.FormattedString;
/**
* Check if the current string is translatable, if it
* is the case, translate the string to the language specified
* in the current system locale setting.
*
* A translatable string is a string in the following
* form: `"__(example string)"`
*
* @returns {string}
* @memberof String
*/
__(): string; __(): string;
/**
* Translate current string to the language specified
* by the system locale setting
*
* @returns {string}
* @memberof String
*/
l(): string; l(): string;
/**
* Trim left of a string by a mask string
*
* @param {string} arg specifies a sub-string to be removed
* @returns {string}
* @memberof String
*/
trimLeft(arg: string): string; trimLeft(arg: string): string;
/**
* Trim right of a string by a mask string
*
* @param {string} arg specifies a sub-string to be removed
* @returns {string}
* @memberof String
*/
trimRight(arg: string): string; trimRight(arg: string): string;
/**
* Trim both left and right of a string by a mask string
*
* @param {string} arg specifies a sub-string to be removed
* @returns {string}
* @memberof String
*/
trimBy(arg: string): string; trimBy(arg: string): string;
} }
/** /**
* * Extend the Data prototype with the
* [[timestamp]] function
* *
* @interface Date * @interface Date
*/ */
interface Date { interface Date {
/**
* Return the timestamp of the current Date object
*
* @returns {number}
* @memberof Date
*/
timestamp(): number; timestamp(): number;
} }
/** /**
* * Generic key-value pair object interface
* *
* @interface GenericObject * @interface GenericObject
* @template T * @template T
@ -59,7 +176,12 @@ interface GenericObject<T> {
} }
/** /**
* Global function to create a [[FormattedString]] from
* a formatted string and a list of parameters. Example
* *
* ```typescript
* __("hello {0}", world) // return a FormattedString object
* ```
* *
* @param {...any[]} args * @param {...any[]} args
* @returns {(OS.FormattedString | string)} * @returns {(OS.FormattedString | string)}
@ -67,21 +189,28 @@ interface GenericObject<T> {
declare function __(...args: any[]): OS.FormattedString | string; declare function __(...args: any[]): OS.FormattedString | string;
/** /**
* * This global function allow chaining stack trace from one error to
* another. It is particular helping when tracking the source of
* the error in promises chain which results in some obfuscated stack
* traces as the stack resets on every new promise.
* *
* @param {Error} e * @param {Error} e
* @returns {Error} * @returns {Error}
*/ */
declare function __e(e: Error): Error; declare function __e(e: Error): Error;
//define the OS object /**
* This namespace is the main entry point of AntOS
* API
*/
namespace OS { namespace OS {
/** /**
* Return an range of numbers
* *
* * @param {number} left start of the range
* @param {number} left * @param {number} right end of the range
* @param {number} right * @param {boolean} inclusive specifies whether the
* @param {boolean} inclusive * `right` of the range is included in the returned array
* @returns {number[]} * @returns {number[]}
*/ */
function __range__( function __range__(
@ -114,7 +243,6 @@ namespace OS {
); );
}; };
// chaning error
Ant.__e = function (e: Error): Error { Ant.__e = function (e: Error): Error {
const reason = new Error(e.toString()); const reason = new Error(e.toString());
reason.stack += "\nCaused By:\n" + e.stack; reason.stack += "\nCaused By:\n" + e.stack;
@ -122,14 +250,40 @@ namespace OS {
}; };
/** /**
* * Represent a translatable formatted string
* *
* @export * @export
* @class FormattedString * @class FormattedString
*/ */
export class FormattedString { export class FormattedString {
/**
* Format string in the following form
*
* ```typescript
* "format string with {0} and {1}"
* // {[0-9]} is the format pattern
* ```
*
* @type {string}
* @memberof FormattedString
*/
fs: string; fs: string;
/**
* The value of the format pattern represented
* in [[fs]]
*
* @type {any[]}
* @memberof FormattedString
*/
values: any[]; values: any[];
/**
* Creates an instance of FormattedString.
* @param {string} fs format string
* @param {any[]} args input values of the format patterns
* @memberof FormattedString
*/
constructor(fs: string, args: any[]) { constructor(fs: string, args: any[]) {
this.fs = fs; this.fs = fs;
this.values = []; this.values = [];
@ -146,7 +300,7 @@ namespace OS {
} }
/** /**
* * Convert FormattedString to String
* *
* @returns {string} * @returns {string}
* @memberof FormattedString * @memberof FormattedString
@ -156,7 +310,9 @@ namespace OS {
} }
/** /**
* * Translate the format string to the current system
* locale language, format the string with values and
* then converted it to normal `string`
* *
* @returns {string} * @returns {string}
* @memberof FormattedString * @memberof FormattedString
@ -174,7 +330,7 @@ namespace OS {
} }
/** /**
* * Return the hash number of the formatted string
* *
* @returns {number} * @returns {number}
* @memberof FormattedString * @memberof FormattedString
@ -184,9 +340,10 @@ namespace OS {
} }
/** /**
* Match the formatted string against a regular expression
* a string pattern
* *
* * @param {(string | RegExp)} t string or regular expression
* @param {(string | RegExp)} t
* @returns {RegExpMatchArray} * @returns {RegExpMatchArray}
* @memberof FormattedString * @memberof FormattedString
*/ */
@ -195,7 +352,7 @@ namespace OS {
} }
/** /**
* * Convert the formatted string to Base^$
* *
* @returns {string} * @returns {string}
* @memberof FormattedString * @memberof FormattedString
@ -205,7 +362,7 @@ namespace OS {
} }
/** /**
* * Un escape the formatted string
* *
* @returns {string} * @returns {string}
* @memberof FormattedString * @memberof FormattedString
@ -215,7 +372,7 @@ namespace OS {
} }
/** /**
* * Convert the formatted string to uint8 array
* *
* @returns {Uint8Array} * @returns {Uint8Array}
* @memberof FormattedString * @memberof FormattedString
@ -225,7 +382,7 @@ namespace OS {
} }
/** /**
* * Input values for the format string
* *
* @param {...any[]} args * @param {...any[]} args
* @memberof FormattedString * @memberof FormattedString
@ -238,21 +395,70 @@ namespace OS {
} }
/** /**
* This class represents the Version number format used by AntOS. A typical
* AntOS version number is in the following format:
* *
* ```
* [major_number].[minor_number].[patch]-[branch]
*
* e.g.: 1.2.3-r means that:
* - version major number is 1
* - version minor number is 2
* - patch version is 3
* - the current branch is release `r`
* ```
* *
* @export * @export
* @class Version * @class Version
*/ */
export class Version { export class Version {
/**
* The version string
*
* @type {string}
* @memberof Version
*/
string: string; string: string;
/**
* The current branch
* - 1: `a` - alpha branch
* - 2: `b` - beta branch
* - 3: `r` - release branch
*
* @private
* @type {number}
* @memberof Version
*/
private branch: number; private branch: number;
/**
* Version major number
*
* @type {number}
* @memberof Version
*/
major: number; major: number;
/**
* Version minor number
*
* @type {number}
* @memberof Version
*/
minor: number; minor: number;
/**
* Version patch number
*
* @type {number}
* @memberof Version
*/
patch: number; patch: number;
/** /**
*Creates an instance of Version. *Creates an instance of Version.
* @param {string} string * @param {string} string string represents the version
* @memberof Version * @memberof Version
*/ */
constructor(string: string) { constructor(string: string) {
@ -288,10 +494,17 @@ namespace OS {
} }
/** /**
* Compare the current version with another version.
* *
* The comparison priority is `branch>major>minor>patch`.
* *
* @param {(string | Version)} o * For the branch, the priority is `r>b>a`
*
* @param {(string | Version)} o version string or object
* @returns {(0 | 1 | -1)} * @returns {(0 | 1 | -1)}
* Return 0 if the two versions are the same, 1 if
* the current version is newer than the input version,
* otherwise return -1
* @memberof Version * @memberof Version
*/ */
compare(o: string | Version): 0 | 1 | -1 { compare(o: string | Version): 0 | 1 | -1 {
@ -328,9 +541,10 @@ namespace OS {
} }
/** /**
* Check if the current version is newer than
* the input version
* *
* * @param {(string | Version)} o version string or object
* @param {(string | Version)} o
* @returns {boolean} * @returns {boolean}
* @memberof Version * @memberof Version
*/ */
@ -339,9 +553,10 @@ namespace OS {
} }
/** /**
* Check if the current version is older than
* the input version
* *
* * @param {(string | Version)} o version string or object
* @param {(string | Version)} o
* @returns {boolean} * @returns {boolean}
* @memberof Version * @memberof Version
*/ */
@ -350,7 +565,7 @@ namespace OS {
} }
/** /**
* * Return itself
* *
* @returns {Version} * @returns {Version}
* @memberof Version * @memberof Version
@ -360,7 +575,7 @@ namespace OS {
} }
/** /**
* * Convert Version object to string
* *
* @returns {string} * @returns {string}
* @memberof Version * @memberof Version
@ -496,25 +711,45 @@ namespace OS {
return (this.getTime() / 1000) | 0; return (this.getTime() / 1000) | 0;
}; };
/**
* Variable represents the current AntOS version, it
* is an instance of [[Version]]
*/
export const VERSION: Version = "1.0.0-a".__v(); export const VERSION: Version = "1.0.0-a".__v();
/** /**
* Register a model prototype to the system namespace.
* There are two types of model to be registered, if the model
* is of type [[SubWindow]], its prototype will be registered
* in the [[dialogs]] namespace, otherwise, if the model type
* is [[Application]] or [[Service]], its prototype will be
* registered in the [[application]] namespace.
* *
* When a model is loaded in the system, its prototype is registered
* for later uses
* *
* @export * @export
* @param {string} name * @param {string} name class name
* @param {*} x * @param {*} x the corresponding class
* @returns {*} * @returns {*}
*/ */
export function register(name: string, x: PM.ProcessTypeClass): void { export function register(name: string, x: PM.ModelTypeClass): void {
if (((x as any) as typeof BaseModel).type === ModelType.SubWindow) { if (((x as any) as typeof BaseModel).type === ModelType.SubWindow) {
GUI.dialog[name] = x; GUI.dialogs[name] = x;
} else { } else {
application[name] = x; application[name] = x;
} }
} }
/** /**
* This function cleans up the entire system and
* makes sure the system is in a new and clean session.
* It performs the following operations:
* *
* - Kill all running processes
* - Unregister all global events and reset the global
* announcement system
* - Clear the current theme
* - Reset process manager and all system settings
* *
* @export * @export
*/ */
@ -540,13 +775,15 @@ namespace OS {
} }
/** /**
* * Booting up AntOS. This function checks whether the user
* is successfully logged in, then call [[startAntOS]], otherwise
* it shows the login screen
* *
* @export * @export
*/ */
export function boot(): void { export function boot(): void {
//first login //first login
console.log("Booting sytem"); console.log("Booting system");
API.handle API.handle
.auth() .auth()
.then(function (d: API.RequestResult) { .then(function (d: API.RequestResult) {
@ -562,10 +799,17 @@ namespace OS {
.catch((e: Error) => console.error(e)); .catch((e: Error) => console.error(e));
} }
/**
* Placeholder for all the callbacks that are called when the system
* exits. These callbacks are useful when an application or service wants
* to perform a particular task before shuting down the system
*/
export const cleanupHandles: { [index: string]: () => void } = {}; export const cleanupHandles: { [index: string]: () => void } = {};
/** /**
* * Perform the system shutdown operation. This function calls all
* clean up handles in [[cleanupHandles]], then save the system setting
* before exiting
* *
* @export * @export
*/ */
@ -585,11 +829,11 @@ namespace OS {
} }
/** /**
* * Register a callback to the system [[cleanupHandles]]
* *
* @export * @export
* @param {string} n * @param {string} n callback string name
* @param {() => void} f * @param {() => void} f the callback handle
* @returns * @returns
*/ */
export function onexit(n: string, f: () => void) { export function onexit(n: string, f: () => void) {
@ -597,7 +841,9 @@ namespace OS {
return (cleanupHandles[n] = f); return (cleanupHandles[n] = f);
} }
} }
/**
*
*/
export namespace API { export namespace API {
/** /**
* *

View File

@ -85,7 +85,7 @@ namespace OS {
*/ */
export interface RequestResult { export interface RequestResult {
/** /**
* Indicate whether an the response is error * Indicate whether the response is error
* *
* @type {(boolean | string)} * @type {(boolean | string)}
* @memberof RequestResult * @memberof RequestResult

View File

@ -1,7 +1,7 @@
namespace OS { namespace OS {
export namespace PM { export namespace PM {
export type ProcessType = application.BaseApplication | application.BaseService; export type ProcessType = application.BaseApplication | application.BaseService;
export type ProcessTypeClass = { export type ModelTypeClass = {
new <T extends BaseModel>(args: AppArgumentsType[]): T; new <T extends BaseModel>(args: AppArgumentsType[]): T;
}; };
export var pidalloc: number = 0; export var pidalloc: number = 0;
@ -17,7 +17,7 @@ namespace OS {
*/ */
export function createProcess( export function createProcess(
app: string, app: string,
cls: ProcessTypeClass, cls: ModelTypeClass,
args?: AppArgumentsType[] args?: AppArgumentsType[]
): Promise<ProcessType> { ): Promise<ProcessType> {
return new Promise(function (resolve, reject) { return new Promise(function (resolve, reject) {