swing-ui 0.1.25 → 1.0.1

package/types/enums.d.ts

@@ -0,0 +1,437 @@
+/**
+ * *
+ */
+export type ShortcutScope = number;
+/**
+ * A keyboard shortcut binding scope. Used to set when a keyboard shortcut should emit a KeyEvent for onShortcutAction() event handler using a {@link UIComponent#shortcuts|shortcuts()} method.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Focused - When the component has focus (default for non-container components).
+ * @property {number} Ancestor - When any child or their children have a focus (default for container components, other than Window).
+ * @property {number} Window - When component is in focused window (default for Window component).
+ * @see UIComponent#shortcuts
+ * @see UIComponent#onShortcut
+ */
+export const ShortcutScope: Readonly<{
+    Focused: 0;
+    Ancestor: 1;
+    Window: 2;
+}>;
+/**
+ * *
+ */
+export type DragDropAction = string;
+/**
+ * Enum for drag and drop actions.
+ * Used with `dragAction()` and `dropAction()`.
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} None - No action.
+ * @property {string} Copy - Copy action.
+ * @property {string} Move - Move action.
+ * @property {string} CopyOrMove - Copy or move action.
+ * @property {string} Link - Link action.
+ * @see UIComponent#dragAction
+ * @see UIComponent#dropAction
+ * @example
+ * list.dragAction(DragDropAction.CopyOrMove);
+ * list.dropAction(DragDropAction.CopyOrMove);
+ */
+export const DragDropAction: Readonly<{
+    None: "None";
+    Copy: "Copy";
+    Move: "Move";
+    CopyOrMove: "CopyOrMove";
+    Link: "Link";
+}>;
+/**
+ * *
+ */
+export type DropMode = string;
+/**
+ * Used with dropMode() in Table, List, and Tree
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} On - Drop on items.
+ * @property {string} Insert - Insert between items
+ * @property {string} OnOrInsert - Drop on items and between items
+ * @see {@link List#dropMode|List.dropMode()}
+ * @see {@link Table#dropMode|Table.dropMode()}
+ * @see {@link Tree#dropMode|Tree.dropMode()}
+ * @example
+ * table.dropMode(DropMode.OnOrInsert);
+ */
+export const DropMode: Readonly<{
+    On: "On";
+    Insert: "Insert";
+    OnOrInsert: "OnOrInsert";
+}>;
+/**
+ * *
+ */
+export type MouseAction = number;
+/**
+ * Enum for mouse actions.
+ * Used with `ui.mouseAction(action, button)`.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Press - Mouse button press.
+ * @property {number} Release - Mouse button release.
+ * @property {number} Click - Single click.
+ * @property {number} DoubleClick - Double click.
+ * @property {number} VerticalScroll - Vertical wheel scroll.
+ * @property {number} HorizontalScroll - Horizontal wheel scroll.
+ * @see SwingUI#mouseAction
+ * @example <h2>Performing a mouse click:</h2>
+ * ui.mouseAction(MouseAction.Click, MouseButton.Left);
+ */
+export const MouseAction: Readonly<{
+    Press: 0;
+    Release: 1;
+    Click: 2;
+    DoubleClick: 3;
+    VerticalScroll: 4;
+    HorizontalScroll: 5;
+}>;
+/**
+ * *
+ */
+export type MouseButton = number;
+/**
+ * Enum for mouse buttons.
+ * Compare to `mouseEvent.button` on mouse events or use with `ui.mouseAction(action, button)`.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Left - Left mouse button.
+ * @property {number} Right - Right mouse button.
+ * @property {number} Middle - Middle mouse button.
+ * @see SwingUI#mouseAction
+ * @see UIComponent#onMouseEvents
+ * @example <h2>Checking if right mouse button was clicked:</h2>
+ * if(mouseEvent.button === MouseButton.Right)
+ * {
+ *     console.log("Right click);
+ * }
+ * @example <h2>Performing a mouse click:</h2>
+ * ui.mouseAction(MouseAction.Click, MouseButton.Left);
+ */
+export const MouseButton: Readonly<{
+    Left: 1;
+    Right: 3;
+    Middle: 2;
+}>;
+/**
+ * *
+ */
+export type KeyAction = number;
+/**
+ * Keyboard key actions to be performed on the computer. Use it only with `ui.keyboardAction(action, value)` to perform key actions.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Press - Key press.
+ * @property {number} Release - Key release.
+ * @property {number} Type - Key typed (typed character input).
+ * @see SwingUI#keyboardAction
+ * @example <h2>Performing a key type action:</h2>
+ * ui.keyboardAction(KeyAction.Type, "A");
+ */
+export const KeyAction: Readonly<{
+    Press: 0;
+    Release: 1;
+    Type: 2;
+}>;
+/**
+ * *
+ */
+export type MessageIcon = number;
+/**
+ * Enum for standard message dialog icons. Used in `alert()`, `dialog()` and `TrayIcon.showNotification()`.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Error - Error icon.
+ * @property {number} Info - Information icon.
+ * @property {number} Warning - Warning icon.
+ * @property {number} Question - Question icon.
+ * @see alert
+ * @see dialog
+ * @see TrayIcon#showNotification
+ * @example
+ * alert("This file doesn't exist!", "File Absent", MessageIcon.Warning);
+ */
+export const MessageIcon: Readonly<{
+    Error: 0;
+    Info: 1;
+    Warning: 2;
+    Question: 3;
+}>;
+/**
+ * *
+ */
+export type SelectionMode = number;
+/**
+ * Enum for selection modes in UI components like Table, List, Tree. Used with `selectionMode()` to set of get a selection mode of a list of items or rows.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Single - Single item selection.
+ * @property {number} Range - Range selection (shift-click).
+ * @property {number} Multiple - Multiple selection (ctrl/cmd-click).
+ * @see Table#selectionMode
+ * @see List#selectionMode
+ * @see Tree#selectionMode
+ * @example
+ * table.selectionMode(SelectionMode.Single);
+ */
+export const SelectionMode: Readonly<{
+    Single: 0;
+    Range: 1;
+    Multiple: 2;
+}>;
+/**
+ * *
+ */
+export type FontFamily = string;
+/**
+ * An enum for generic font family names to use instead of a font name that may not be installed on target operating systems.
+ * Use with `component.font()`, `Text()` shape, `font` property of a List item, Tree item, ComboBox item, Table column, and everywhere else where font can be set.
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} Serif - Proportional font with small decorative strokes at the ends of letters (e.g., Times New Roman, Georgia, Garamond, Cambria.).
+ * @property {string} SansSerif - Proportional font without decorative strokes; clean and modern (e.g., Arial, Helvetica, Verdana, Calibri, Open Sans).
+ * @property {string} Monospaced - Fixed-width font where every character has the same width (e.g., Courier New, Consolas, Lucida Console, Menlo).
+ * @property {string} Cursive - Flowing, handwritten-style font (e.g., Brush Script, Comic Sans MS, Pacifico, Lobster).
+ * @property {string} System - The system UI font provided by the operating system. (e.g., Segoe UI (Windows), San Francisco (macOS/iOS), Roboto (Android/Linux)).
+ * @property {string} Fantasy - Decorative or themed font (e.g., Impact, Papyrus, Jokerman, Copperplate).
+ * @see UIComponent#font
+ * @see Text
+ * @example <h2>Setting component font:</h2>
+ * textarea.font({name: FontFamily.SansSerif});
+ *
+ * @example <h2>Setting Text shape font:</h2>
+ * let text = new Text("Hello World", {name: FontFamily.Fantasy, size: 30});
+ */
+export const FontFamily: Readonly<{
+    Serif: "serif";
+    SansSerif: "sans-serif";
+    Monospaced: "monospace";
+    Cursive: "cursive";
+    System: "system-ui";
+    Fantasy: "fantasy";
+}>;
+/**
+ * *
+ */
+export type DataType = string;
+/**
+ * Enum for data types used with drag and drop.
+ * Used with `dragDataType()`, `dropDataType()`, and to check if certain data type was dragged onto component.
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} None - No data.
+ * @property {string} All - Accept any type. Used only for dropDataType().
+ * @property {string} Text - Plain text.
+ * @property {string} HTML - HTML content.
+ * @property {string} Image - Image data.
+ * @property {string} Files - Files copied to system clipboard or dragged/dropped.
+ * @property {string} URIList - List of URIs.
+ * @property {string} URL - A single URL string.
+ * @property {string} JSON - JSON-encoded data.
+ * @property {string} TextEncoding - Text encoding used to encode the Text and/or HTML values.
+ * @property {string} Components - UI components (`component/*`).
+ * @example <h2>Sets the type of data list items represent when dragged:</h2>
+ * list.dragDataType(DataType.Files);
+ * @example <h2>Sets the type of data Table component accepts:</h2>
+ * table.dropDataType([DataType.Files, DataType.URIList, DataType.URL]);
+ * @example <h2>Check if expected data type was dragged onto Label:</h2>
+ * label.dropAction(DragDropAction.CopyOrMove).dropDataType(DataType.Files).onDropEvents(e => {
+ *  if(e.type === "drop" && Array.isArray(e.data[DataType.Filest]))
+ *  {
+ *      // set first file as label's icon image
+ *      e.target.icon(e.data[DataType.Files][0]);
+ *  }
+ * });
+ */
+export const DataType: Readonly<{
+    None: "None";
+    All: "All";
+    Text: "Text";
+    HTML: "HTML";
+    Image: "Image";
+    Files: "Files";
+    URIList: "URIList";
+    URL: "URL";
+    JSON: "JSON";
+    Components: "component/*";
+}>;
+/**
+ * *
+ */
+export type TextAction = number;
+/**
+ * Enum for actions on text components (TextField, TextArea, etc.). To be used in text() method.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Set - Replace all text.
+ * @property {number} Prepend - Add text at the beginning.
+ * @property {number} Append - Add text at the end.
+ * @property {number} Insert - Insert at current caret position.
+ * @property {number} ReplaceSelection - Replace selected text.
+ * @see UIComponent#text
+ * @example <h2>Appending text to TextArea component:</h2>
+ * let textarea = new TextArea("Hello").text(" World!", TextAction.Append);
+ * // text area will contain text "Hello World!"
+ */
+export const TextAction: Readonly<{
+    Set: 0;
+    Prepend: 1;
+    Append: 2;
+    Insert: 3;
+    ReplaceSelection: 4;
+}>;
+/**
+ * *
+ */
+export type Cursor = number;
+/**
+ * Enum for available mouse cursors.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Default - Default cursor.
+ * @property {number} Crosshair - Crosshair.
+ * @property {number} Text - Text input cursor.
+ * @property {number} Wait - Wait/busy cursor.
+ * @property {number} ResizeSW - Resize south-west.
+ * @property {number} ResizeSE - Resize south-east.
+ * @property {number} ResizeNW - Resize north-west.
+ * @property {number} ResizeNE - Resize north-east.
+ * @property {number} ResizeN - Resize north.
+ * @property {number} ResizeS - Resize south.
+ * @property {number} ResizeW - Resize west.
+ * @property {number} ResizeE - Resize east.
+ * @property {number} Hand - Pointing hand.
+ * @property {number} Move - Move cursor.
+ * @see UIComponent#cursor
+ * @example <h2>Sets "Wait" cursor to Panel component:</h2>
+ * panel.cursor(Cursor.Wait);
+ */
+export const Cursor: Readonly<{
+    Default: 0;
+    Crosshair: 1;
+    Text: 2;
+    Wait: 3;
+    ResizeSW: 4;
+    ResizeSE: 5;
+    ResizeNW: 6;
+    ResizeNE: 7;
+    ResizeN: 8;
+    ResizeS: 9;
+    ResizeW: 10;
+    ResizeE: 11;
+    Hand: 12;
+    Move: 13;
+}>;
+/**
+ * *
+ */
+export type Orientation = number;
+/**
+ * Enum for component orientation, such as Slider or Toolbar.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Horizontal - Horizontal orientation.
+ * @property {number} Vertical - Vertical orientation.
+ * @see SplitView#orientation
+ * @see ToolBar#orientation
+ * @example <h2>Setting orientation to a component:</h2>
+ * toolbar.orientation(Orientation.Vertical);
+ */
+export const Orientation: Readonly<{
+    Horizontal: 0;
+    Vertical: 1;
+}>;
+/**
+ * *
+ */
+export type BorderStyle = string;
+/**
+ * Border style enum. Use in a border object..
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} None - No border.
+ * @property {string} Line - Solid line.
+ * @property {string} Dashed - Dashed border.
+ * @property {string} Metal - Metallic style.
+ * @property {string} EtchedRaised - Etched raised border.
+ * @property {string} EtchedLowered - Etched lowered border.
+ * @property {string} BevelRaised - Bevel raised border.
+ * @property {string} BevelLowered - Bevel lowered border.
+ * @property {string} SoftRaised - Soft raised border.
+ * @property {string} SoftLowered - Soft lowered border.
+ * @see UIComponent#border
+ * @example <h2>Setting a new border:</h2>
+ * let border = {style: BorderStyle.Dashed, size: 2, color: "#002288"}
+ * panel.border(border);
+ */
+export const BorderStyle: Readonly<{
+    None: "none";
+    Line: "line";
+    Dashed: "dashed";
+    Metal: "metal";
+    EtchedRaised: "etched_raised";
+    EtchedLowered: "etched_lowered";
+    BevelRaised: "bevel_raised";
+    BevelLowered: "bevel_lowered";
+    SoftRaised: "soft_raised";
+    SoftLowered: "soft_lowered";
+}>;
+/**
+ * *
+ */
+export type LineWrap = number;
+/**
+ * Enum for word wrapping styles.
+ * Used with `lineWrap()` method in TextArea and DocumentEditor to control how text is wrapped.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} None - Disable line wrapping.
+ * @property {number} Word - Wrap line when a full word doesn't fit.
+ * @property {number} Character - Wrap line when a character doesn't fit.
+ * @see TextArea#lineWrapping
+ * @see DocumentEditor#lineWrapping
+ * @example <h2>Setting line wrapping style:</h2>
+ * textarea.lineWrap(LineWrap.Word);
+ */
+export const LineWrap: Readonly<{
+    None: 0;
+    Word: 1;
+    Character: 2;
+}>;

package/types/functions.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Displays a dialog windows with error message and error icon.
+ *
+ * @param {string|Error} message - Error message to display or Error object to display stack trace.
+ * @param {boolean|Error} [show_stack_trace=true] - Whether to show stack trace to be able to trace the error (applies only when first parameter is not an Error object).
+ * @return {void} Does not return a value
+ * @global
+ * @example <h2>Showing an error message only:</h2>
+ * error("Invalid parameters passed.", false);
+ *
+ * @example <h2>Showing an error message with a stack trace:</h2>
+ * error("Invalid parameters passed.");
+ *
+ * @example <h2>Showing an error message by passing an Error object:</h2>
+ * try
+ * {
+ *     // some code that may throw an error
+ * }
+ * catch(ex)
+ * {
+ *     error(ex);
+ * }
+ *
+ */
+export function error(message: string | Error, show_stack_trace?: boolean | Error): void;
+/**
+ * Returns a text representation of passed variable. Similar to JSON.stringify().
+ *
+ * @internal
+ * @ignore
+ * @global
+ * @param {any} variable - Any variable to be converted to a string representation
+ * @return {string} Serialized object as a String
+ */
+export function stringify(variable: any): string;
+/**
+ * Displays a dialog window with a specified error message and an error icon.
+ *
+ * @param {string} message - A message to be displayed in the dialog window
+ * @param {string} [title="Message"] - Dialog window title bar text
+ * @param {MessageIcon} [icon=MessageIcon.Info] - Icon to show in the dialog window.
+ *
+ * Valid value are:
+ *  - MessageIcon.Error
+ *  - MessageIcon.Info
+ *  - MessageIcon.Warning
+ *  - MessageIcon.Question
+ *
+ * @param {Window} [ownerWindow=null] - If set, the message dialog window will attempts to be centered at specified window
+ * @return {void} Does not return a value
+ * @global
+ *
+ * @example <h2>Simple usage with only one parameter:</h2>
+ * alert("File name is invalid. Please try again");
+ *
+ * @example <h2>Usage example when passing all parameters:</h2>
+ * alert("File name is invalid. Please try again","Invalid File", MessageIcon.Warning, this);
+ */
+export function alert(message: string, title?: string, icon?: MessageIcon, ownerWindow?: Window): void;
+/**
+ * Requests user for text input in a dialog window. Returns a string as user's input or undefined when user declined to input.
+ *
+ * @param {string} message - Message to user about this text input.
+ * @param {string} [default_value=""] - Default string that will be already present in the dialog window.
+ * @param {Window} [ownerWindow=null] - Window that will be overlaid by the dialog window.
+ * @returns {string|undefined} Returns user provided string, or `undefined` if user canceled input.
+ * @global
+ * @example
+ * let response = prompt("Please enter your name:", "John Doe", this);
+ * console.log("You entered: " + response);
+ */
+export function prompt(message: string, default_value?: string, ownerWindow?: Window): string | undefined;
+/**
+ * Displays a confirmation dialog to user and returns user's response as boolean.
+ *
+ * @param {string} message - Message to display to user
+ * @param {Window} [window=null] - Window which dialog window will overlay. If omitted, last created visible Window that's not PopUp will be used.
+ * @return {boolean} Returns `true` if user confirms the message, or `false` otherwise.
+ * @global
+ * @example
+ * if(confirm("Delete this file?", this))
+ * {
+ *     // delete code
+ * }
+ */
+export function confirm(message: string, window?: Window): boolean;
+/**
+ * Shows a custom dialog window that allows the user to respond by clicking one of provided buttons.
+ *
+ * @param {string} message - String message to user. It can be plain text or HTML.
+ * @param {string} [title=""] - Dialog window title shown in the title bar of the window
+ * @param {string[]} [buttons=["OK","Cancel"]] - An Array of button names. Indicate a default button by surrounding the text with square brackets like so: "[Cancel]"
+ * @param {MessageIcon|string} [icon=null] - One of MessageIcon icons, or an absolute path to an image from a file system.
+ * @param {Window} [window=null] - Owner window that will be overlaid by this dialog window. If omitted, last created visible Window that's not PopUp will be used.
+ * @return {number|undefined} Returns a zero-based number of a clicked button, or `null` if the dialog window was closed without clicking provided buttons.
+ * @global
+ * @example <h2>Usage example</h2>
+ * let response = dialog("Are you ready?", "Confirm readiness", ["Yes", "No", "[Maybe]"], MessageIcon.Question, window);
+ * switch(response)
+ * {
+ *     case 0: return "Yes";
+ *     case 1: return "No";
+ *     case 2: return "Maybe";
+ * }
+ *
+ * @example <h2>Using custom image</h2>
+ * let response = dialog("Is this you?", "Question #5", ["Yes","[No]"], "C://User/John/profile_icon.jpg", window);
+ */
+export function dialog(message: string, title?: string, buttons?: string[], icon?: MessageIcon | string, window?: Window): number | undefined;