swing-ui 0.1.25 → 1.0.3

package/types/classes/TrayIcon.d.ts

@@ -0,0 +1,43 @@
+/**
+ * TrayIcon is a system icon usually displayed in a tray of icons for applications running or capable of running in the background.
+ *
+ * TrayIcon component is able to show system notification messages, have context menu and show tooltip text on mouse hover.
+ *
+ * @class
+ * @global
+ * @example <h2>Create new TrayIcon:</h2>
+ * const icon = new TrayIcon("/path/to/icon.png").tooltip("New App Icon").contextMenu(existing_context_menu).show();
+ *
+ * @example <h2>Set an event handler:</h2>
+ * icon.onMouseEvents(e => {
+ *     console.log(`${e.clicks} ${e.type}`);
+ * })
+ * .onAction(e => {
+ *     console.log("System tray icon action was performed.");
+ * });
+ *
+ * @example <h2>Show system message:</h2>
+ * icon.showNotification(`Warning Sample`, `This is a sample message`, MessageIcon.Warning);
+ *
+ * @example <h2>hide and show the icon:</h2>
+ * icon.hide(); // or icon.visible(false);
+ *
+ * icons.show(); // or icon.visible(true);
+ */
+export class TrayIcon extends UIComponent {
+    /**
+     * Slider TrayIcon. Creates an instance of TrayIcon UI component.
+     * @param {string} icon - Icon image (relative/absolute path or base64 encoded image string).
+     */
+    constructor(icon: string);
+    /**
+     * Displays system notification.
+     *
+     * @param {string} title - Title of the notification message
+     * @param {string} message - The message body
+     * @param {MessageIcon} [icon=MessageIcon.Info] - One of the values: MessageIcon.Info, MessageIcon.Warning, MessageIcon.Info, or `null` to not show any icon.
+     * @return {TrayIcon} Returns `this` TrayIcon component for method chaining.
+     */
+    showNotification(title: string, message: string, icon?: MessageIcon): TrayIcon;
+}
+import { UIComponent } from "./UIComponent.js";

package/types/classes/Tree.d.ts

@@ -0,0 +1,354 @@
+/**
+ * A Tree component shows a list items but in a child/parent structure.
+ *
+ * Like in a {@link List} component the items can hold custom `id` and `value` data in addition to `text`, `icon`, `tooltip`, `font` object, `background`, and `color`.
+ *
+ * The Tree component can be customized the way  it's displayed by methods {@link Tree#showRoot}, {@link Tree#showRootHandle}, {@link Tree#showIcons}, and {@link Tree#expanded}.
+ *
+ * Items are identified by their unique index path, which is an array of each index, starting from root element [0]. Example index of an item can be [0, 3, 2] where first element is an index of root element (always [0]), and child's index, and then its child.
+ *
+ * Items can be easily added using {@link Tree#add}, removed using {@link Tree#remove}, updated and retrieved using {@link Tree#item}, and moved from one parent to another using {@link Tree#moveItem}.
+ *
+ * All other Tree methods not on this page are inherited from {@link ScrollableComponent} and {@link UIComponent}.
+ *
+ * @class
+ * @global
+ * @see ListItem
+ * @see ScrollableComponent
+ * @example
+ * // Format of tree item object (Only "text" is requited, other fields are optional)
+ * {
+ *     text: string,           // Item text (Required)
+ *     [id]: string|number,    // Value that can be used by software logic to identify this item
+ *     [value]: string|number, // Additional value to be stored in the item for later use.
+ *     [icon]: string,         // Absolute or relative path to icon image, base64 encoded image string, or `null` to remove icon.
+ *     [color]: string,        // Item text color as a 6 character hex encoded color string (e.g. #665500)
+ *     [background]: string,   // Item background color as a 6 character hex encoded color string (e.g. #665500)
+ *     [tooltip]: string,      // Tooltip text to show when pointer hover the item. (in List and Tree components only)
+ *     [font]: Font object     // Object{name: string, size: number, bold: boolean, ...}. See complete list of font properties in example of font() method.
+ *     [editable]: boolean     // Specifies if the node item text can be edited by the user.
+ *     [children]:object[]     // An array of children (when adding or recursively retrieving).
+ * }
+ */
+export class Tree extends ScrollableComponent {
+    /**
+     * Sets or gets visibility of a root node of the tree.
+     *
+     * @param {boolean} [show] - `true` to show, `false` to hide.
+     * @return {boolean|Tree} If no arguments are passed, current value is returned; otherwise `this` Tree component is returned for method chaining.
+     */
+    showRoot(...args: any[]): boolean | Tree;
+    /**
+     * Sets or gets visibility of a root node handle (the one that's used to expand/collapse the node to show/hide child nodes).
+     *
+     * @param {boolean} [show] - `true` to show, `false` to hide.
+     * @return {boolean|Tree} If no arguments are passed, current value is returned; otherwise `this` Tree component is returned for method chaining.
+     */
+    showRootHandle(...args: any[]): boolean | Tree;
+    /**
+     * Shows or hides all icons in the tree.
+     *
+     * @param {boolean} [show] - `true` to show, `false` to hide.
+     * @return {boolean|Tree} If no arguments are passed, current value is returned; otherwise `this` Tree component is returned for method chaining.
+     */
+    showIcons(...args: any[]): boolean | Tree;
+    /**
+     * Add an item or array of items to a tree node. To add item to root node use [0] for `index` argument.
+     *
+     * @param {object|object[]} items - One item object or an array of item objects.
+     * @param {number[]} index - Index of the item to insert the passed items to. To add to the root use [0].
+     * @param {number|undefined} [insertAt=undefined] - Indicates at what position to inserted the items. Value -1 means the end of list.
+     * @return {number} Returns an integer at which first passed item was inserted, or -1 if specified parent item index is invalid or no items were inserted.
+     */
+    add(items: object | object[], index: number[], insertAt?: number | undefined): number;
+    /**
+     * Removes item at specified index argument or removes this Tree component from its parent if no argument is passed.
+     *
+     * @param {number[]} [index] - Index if the item to remove. Omit this argument to remove this Tree from its parent.
+     * @return {Tree} Returns `this` Tree component for method chaining.
+     */
+    remove(...args: any[]): Tree;
+    /**
+     * Updates or gets an item at specified index.
+     *
+     * @param {number[]} index - Index of the item to get or update.
+     * @param {object} [item] - Item object. Omit this argument to get the item instead of updating it.
+     * @param {boolean} [update=false] - `true` to update specified item properties with provided item properties, `false` to replace the item with new one. Default is `false`.
+     * @return [object|undefined|Tree] If `item` argument is passed, `this` Tree component is returned; otherwise an item at specified index is returned, or `null` if passed `index` is invalid.
+     * @example
+     * // update an item at index [0,3,5]
+     * tree.item([0,3,5], {text:"New item text"});
+     *
+     * // get an item at index [0,3,5]
+     * let item = tree.item([0,3,5]);
+     * console.log(item?.text); // checks if item is not undefined
+     */
+    item(index: number[], ...args: any[]): any;
+    /**
+     * Sets or gets a list of items for a node at specified index. Setting the list of items will replace current items at specified index before adding new ones. To simply remove existing items pass an empty array as a second parameter.
+     *
+     * @param {number[]} [index=[0]] - Index of target item. Default is [0] tree root node
+     * @param {boolean|object[]} [items_or_recursive=false] - To set items, pass an array of items, or empty array to simply remove all items. When getting items you can specify a `boolean` whether to get all children items recursively or not. Default is `false`.
+     * @return {object[]|undefined|Tree} If setting items then `this` Tree component is returned. If getting items then Array of items is returned, or `undefined` if index doesn't point to an item in the Tree.
+     * @example <h2> Set items at the root node:</h2>
+     * tree.items([0], [
+     *   { text: "Videos", id: 1, icon: "icons/folder-videos.png" },
+     *   { text: "Photos", id: 2, icon: "icons/folder-images.png" }
+     * ]);
+     *
+     * @example <h2>Set items at a child node:</h2>
+     * tree.items([0,0], [
+     *   { text: "Video 1", id: "a1", value: "video1.mp4" },
+     *   { text: "Video 2", id: "a2", value: "video2.mp4", tooltip: "Second video" }
+     * ]);
+     *
+     * @example <h2>Get direct children of a node:</h2>
+     * const rootItems = tree.items([0]);
+     * console.log(rootItems); // → [ {text: "Videos", id: 1, ...}, {text: "Photos", id: 2, ...} ]
+     *
+     * @example <h2>Get items recursively from a node:</h2>
+     * const deepItems = tree.items([0,0], true);
+     * console.log(deepItems); // → [ {text: "Video 1", id: "a1", ...}, {text: "Video 2", id: "a2", ...} ]
+     *
+     * @example <h2>Get from a non-existing index:</h2>
+     * const nothing = tree.items([9]);
+     * console.log(nothing); // → undefined
+     */
+    items(index?: number[], items_or_recursive?: boolean | object[]): object[] | undefined | Tree;
+    /**
+     * Sets or gets the expand state of a specified item that has children. Items without children cannot be expanded. When setting `expanded` argument and `index` doesn't point to an item then just nothing will happen.
+     *
+     * @param {number[]} index - Index path of the item in question
+     * @param {boolean} [expanded] - Pass `true` or `false` to set the expand state, or omit to get current state.
+     * @param {boolean} [recursive=false] - Whether the specified `expand` state should be applied to all children items recursively. Default is `false`.
+     * @return {boolean|undefined|Tree} If `expanded` argument is passed, then `this` Tree component is returned; otherwise current expand state is returned, or `undefined` if specified index in not valid.
+     * @example <h2>Expand root node:</h2>
+     * tree.expended([0], true);
+     *
+     * @example <h2>Collapse item at specified index:</h2>
+     * tree.expended([0, 2], false);
+     *
+     * @example <h2>Check if item at specified index is expanded:</h2>
+     * let expanded = tree.expended([0, 2]);
+     */
+    expanded(...args: any[]): boolean | undefined | Tree;
+    /**
+     * Expands all items or a specified item and all if its children. If argument is not supplied, root default.
+     *
+     * @param {number[]} [index=[0]] - Index of an item to expand with all children items. If omitted, all items will be expended.
+     * @return {Tree} Returns `this` Tree component for method chaining.
+     */
+    expandAll(index?: number[]): Tree;
+    /**
+     * Collapses all items or a specified item and all if its children. If argument is not supplied, root is default.
+     *
+     * @param {number[]} [index=[0]] - Index of an item to collapse with all children items. If omitted, all items will be collapsed.
+     * @return {Tree} Returns `this` Tree component for method chaining.
+     */
+    collapseAll(index?: number[]): Tree;
+    /**
+     * Sets or gets a selection mode of the tree items, which defines how items can be selected (only one item, a multiple items as a range, or any combination of items).
+     *
+     * @param {SelectionMode} [mode] - One of: SelectionMode.Single, SelectionMode.Multiple, SelectionMode.Range. See {@link SelectionMode}
+     * @return {SelectionMode|Tree} If no arguments are supplied, current selection mode is returned; otherwise `this` Tree component is returned.
+     * @see SelectionMode
+     * @example <h2>Setting a selection mode:</h2>
+     * tree.selectionMode(SelectionMode.Single);
+     */
+    selectionMode(...args: any[]): SelectionMode | Tree;
+    /**
+     * Gets or sets the selected items in the tree. When setting selection, items that were previously selected but are not in the `indexes` argument will get deselected.
+     *
+     * - To **get** the current selection, call without arguments.
+     * - To **set** the selection, pass an array of index paths (array of arrays of index integers).
+     *
+     * @param {number[][]} [indexes] - An array of index paths to select. (array of arrays)
+     * @return {number[][]|Tree} Returns the current selection when called without arguments, or `this` Tree instance when setting.
+     */
+    selection(...args: any[]): number[][] | Tree;
+    /**
+     * Sets or get a whether item or items at specified index or array o indexes are selected. This adds or removes items to/from current selection instead of replacing current selection like selection() method does. If "selected" argument is supplied, it will select or deselect specified items.
+     *
+     * @param {number[]|number[][]} index - Index path of one item as array, or multiple items as array of arrays. When getting selection status, only first item is used.
+     * @param {boolean} [selected] - If supplied, it will indicate if specified items should be selected or not.
+     * @return {boolean|Tree} If `selected` arguments is passed, `this` Tree component is returned; otherwise a selection status of first specified item is returned, or `undefined` if index doesn't point to an item.
+     * @example <h2>Add one item to current selection:</h2>
+     * tree.selected([0,2], true);
+     *
+     * @example <h2>Add two items to current selection:</h2>
+     * tree.selected([[0,3], [0,4]], true);
+     *
+     * @example <h2>Deselect one item:</h2>
+     * tree.selected([0,3], false);
+     *
+     * @example <h2>Check if one item is selected:</h2>
+     * let selected = tree.selected([0,4]); // -> true
+     */
+    selected(index: number[] | number[][], ...args: any[]): boolean | Tree;
+    /**
+     * Selects/Deselects all items in the Tree
+     *
+     * @param {boolean} [selected=true] - `true` to select all items, `false` to deselect all items.
+     * @return {Tree} Returns an instance of `this` Tree for method chaining.
+     */
+    selectAll(selected?: boolean): Tree;
+    /**
+     * Starts editing a specified item, stops editing all items when `null` is passed, or returns an item currently being edited with its `index` property.
+     *
+     * If no parameters are passed, it returns currently editing item's index or `null` if no item is being edited at the moment.
+     *
+     * Editing state is when a user can type a new text into the item. Only one item can be editing at a time.
+     *
+     * @param {number[]|null} [index] - Index of the item to start editing. Pass `null` to stop editing currently editing item (if any).
+     * @return {ListItem|null|Tree} If `index` argument is passed, `this` Tree component is returned. When no arguments are provided, returns an item being edited at the moment (if any), or `null` if no item is being edited.
+     * @example <h2>Starting to edit a specified item:</h2>
+     * tree.editing([0, 2]);
+     *
+     * @example <h2>Stop editing all items:</h2>
+     * tree.editing(null);
+     *
+     * @example <h2>Check which item is editing now:</h2>
+     * let editedItem = tree.editing(); // -> ListItem or false.
+     * console.log(editedItem.index); // prints the index of the item
+     */
+    editing(...args: any[]): ListItem | null | Tree;
+    /**
+     * Gets or sets currently focused item in the Tree. Focus is different from selection. Focus can be controlled by focus traversing keys, such as Tab keyboard key, and focused item is not always an item being selected. Multiple items may be selected at a time, but only one item can retain focus at a time.
+     *
+     * @param {number[]} [index] - Index of one item (array of numbers).
+     * @return {ListItem|null|Tree} When no parameters are passed, returns currently focused item with index property, or `null` when no item is focused. When `index` is provided, `this` Tree component is returned.
+     */
+    focusedItem(...args: any[]): ListItem | null | Tree;
+    /**
+     * Sets custom icons to be used for open node, closed node, and leaf node.
+     *
+     * Example of icons object: {closed:"icons/closed.png", open:"icons/open.png", leaf:"icons/leaf.png"}. Each element is optional.
+     *
+     * Note: all properties of this object are optional.
+     *
+     * @param {{closed:string, open:string, leaf: string}} [icons] - An object of icons to set. Each icon is optional. When some icons are omitted, default ones will be used.
+     * @return {Tree|object} If setting icons, Returns `this` Tree component for method chaining; otherwise returns currently set icons.
+     * @example
+     * tree.icons({
+     *      closed:"icons/closed.png",
+     *      open:"icons/open.png",
+     *      leaf:"icons/leaf.png"
+     * });
+     */
+    icons(icons?: {
+        closed: string;
+        open: string;
+        leaf: string;
+    }): Tree | object;
+    /**
+     * Returns the amount of child nodes under the node specified by index argument.
+     *
+     * @param {number[]} [index] - Index path of an item in question. Default is the root item.
+     * @return {number|undefined} Returns a number of child items the specified item has, or `undefined` if the index doesn't point to an item.
+     */
+    childCount(index?: number[]): number | undefined;
+    /**
+     * Finds items whose `text` property matches the argument. Returns an array of found items.
+     *
+     * @param {string} text - Text to match when finding items.
+     * @return {ListItem[]} Returns an array of found items.  Each found item will have an `index` property fo convenience.
+     */
+    findByText(text: string): ListItem[];
+    /**
+     * Finds items whose `id` property matches the argument. Returns an array of found items.
+     *
+     * @param {string|number} id - Value of item's `id` property to match when finding items.
+     * @return {ListItem[]} Returns an array of found items. Each found item will have an `index` property fo convenience.
+     */
+    findByID(id: string | number): ListItem[];
+    /**
+     * Finds items whose `value` property matches the argument. Returns an array of found items.
+     *
+     * @param {string|number} value - Value of item's `value` property to match when finding items.
+     * @return {ListItem[]} Returns an array of found items. Each found item will have an `index` property fo convenience.
+     */
+    findByValue(value: string | number): ListItem[];
+    /**
+     * Moves one or more items from one location (index path) to another within the same Tree component. Items will be inserted in the order they are in the provided `indexes` array.
+     *
+     * @param {number[][]} indexes - Array of index arrays of items you want to move.
+     * @param {number[]} toIndex - Index of a new parent for specified items.
+     * @param {number} [insertAt] - Index position at which to insert the item(s) into parent (apply applies only if the parent item already has some items).
+     * @return {Tree} Returns `this` Tree component for method chaining.
+     */
+    moveItems(indexes: number[][], toIndex: number[], ...args: any[]): Tree;
+    /**
+     * Moves one item from one location (index path) to another within the same Tree component.
+     *
+     * @param {number[]} index -Index path of the item you want to move.
+     * @param {number[]} toIndex - Index of a new parent for specified item.
+     * @param {number} [insertAt] - Index position at which to insert the item into parent (apply applies only if the parent item already has some items).
+     * @return {Tree} Returns `this` Tree component for method chaining.
+     */
+    moveItem(itemIndexArray: any, toIndexArray: any, insertAt?: number): Tree;
+    /**
+     * Gets or sets how many consecutive clicks are required to start editing an item's text. The `Tree` component is not editable by default, therefore editing should be enabled by {@link UIComponent#editable} method for these clicks have effect. See example below.
+     *
+     * @param {number} [clicks] - Amount of rapid clicks required (1 or 2). Default is 2. If omitted, the current value is returned.
+     * @return {number|Tree} When called without parameters, current value is returned; otherwise returns `this` Tree component for method chaining.
+     * @example <h2>Enables editing, then sets 1 click to start editing:</h2>
+     * tree.editable(true).clicksToEdit(1);
+     * @see Tree#editable
+     */
+    clicksToEdit(...args: any[]): number | Tree;
+    /**
+     * Sets or gets whether Tree nodes' text can be edited by user.
+     *
+     * @param {boolean} [editable] - enables or disables editing
+     * @return {Object|boolean} If arguments is passed, returns `this` component instance, otherwise returns `boolean` value.
+     * @see Tree#clicksToEdit
+     */
+    editable(...args: any[]): Object | boolean;
+    /**
+     * Removes all children items of item at specified index. If no index path is specified, [0] root is cleared.
+     *
+     * @param {number[]} [index] - Index path of the item to clear. If omitted, the root node will be cleared.
+     * @return {Tree} Returns `this` Tree component for method chaining.
+     */
+    clear(...args: any[]): Tree;
+    /**
+     * Scrolls the scroll bars to make sure the item at specified index is visible. If position is specified, the item will be placed at the specified position between the top and bottom of the Tree component.
+     *
+     * @param {number[]} index - Index of a tree item to make visible.
+     * @param {number} [position] - A decimal number between 0 and 1 indicating vertical position in percentages (0% - 100% of the height of the component). If omitted, the item will only become visible, but not at a specific location.
+     * @returns {Tree} Returns `this` Tree object for chaining.
+     */
+    scrollToIndex(index?: number[], position?: number): Tree;
+    /**
+     * Sets or gets a height of each row. If returned value is 0 or less, then height is determined automatically.
+     *
+     * @param {number} [height] - New row height
+     * @returns {number|Tree} If called without arguments, a current row height is returned, otherwise `this` Tree object is returned for chaining.
+     */
+    rowHeight(...args: any[]): number | Tree;
+    /**
+     * Gets, registers or unregisters an event handler function for events triggered by adding, removing, updating items and when the Tree structure is changed.
+     *
+     * @param {function(Object): any} [callback] - The event handler function. Receives an event object.
+     * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+     * @returns {function[]|Tree} When called without parameters, an array of handler functions is returned, otherwise `this` Tree component is returned for method chaining.
+     *
+     * @example <h2>Event object format:</h2>
+     * Object {
+     *     target: Tree,        // The component that triggered the event
+     *     type: string,        // "add", "update", "remove", or "restructure".
+     *     items: object[],     // Items effected by the action that triggered the event
+     *     interactive: boolean // Only when type is "update". Indicates if the update was made by the user interacting with the item in GUI. `false` when updated programmatically.
+     * }
+     *
+     * @example <h2>Registering an event handler:</h2>
+     * tree.onItemsEvents(e=>{alert(e.type);}); // shows the event type in a new message dialog window
+     *
+     * @example <h2>Unregistering all registered event handlers:</h2>
+     * let _handlers = tree.onItemsEvents(); // gets all handlers
+     *
+     * for(let handler of _handlers) tree.onItemsEvents(handler, false); // unregisters each handler
+     */
+    onItemsEvents(callback?: (arg0: Object) => any, ...args: any[]): Function[] | Tree;
+}
+import { ScrollableComponent } from "./ScrollableComponent.js";