phosphor-command - npm Package Compare versions

Comparing version 0.7.0 to 0.8.0

lib/index.d.ts

@@ -16,13 +16,7 @@ import { ISignal } from 'phosphor-signaling';
      *
-     * This abstract method must be implemented by a subclass.
+     * This abstract method must be implemented by a subclass, and the
+     * implementation **must not** throw an exception.
      */
     abstract execute(args: any): void;
     /**
-     * A signal emitted when the command's state changes.
-     *
-     * #### Notes
-     * A subclass should emit this signal when the command state changes.
-     */
-    changed: ISignal<Command, void>;
-    /**
      * Get the display text for the command.
@@ -140,2 +134,20 @@ *
     /**
+     * Test whether the command is visible for its current state.
+     *
+     * @param args - The arguments for the command. If the command does
+     *   not require arguments, this may be `null`.
+     *
+     * @returns `true` if the command is visible, `false` otherwise.
+     *
+     * #### Notes
+     * A subclass may reimplement this method as needed. If the state
+     * changes at runtime, the [[changed]] signal should be emitted.
+     *
+     * UI elements which have a visual representation of a command will
+     * typically not display a non-visible command.
+     *
+     * The default implementation of this method returns `true`.
+     */
+    isVisible(args: any): boolean;
+    /**
      * Test whether the command is checked for its current state.
@@ -160,13 +172,17 @@ *
 /**
- * Safely execute a command.
- *
- * @param command - The command to execute.
- *
- * @param args - The arguments for the command. If the command does
- *   not require arguments, this may be `null`.
- *
- * #### Notes
- * If the commmand throws an exception, it will be caught and logged.
+ * The namespace for the `Command` class statics.
  */
-export declare function safeExecute(command: Command, args: any): void;
+export declare namespace Command {
+    /**
+     * A signal emitted when a command's state changes.
+     *
+     * #### Notes
+     * A command should emit this signal when its state changes.
+     *
+     * This is a static signal which passes the changed command as the
+     * argument for the signal. This reduces the number of connections
+     * in an application from potentially hundreds, to just a few.
+     */
+    const changed: ISignal<typeof Command, Command>;
+}
 /**
@@ -205,2 +221,6 @@ * An options object for initializing a [[SimpleCommand]].
     /**
+     * The initial visible state of the command.
+     */
+    visible?: boolean;
+    /**
      * The initial checked state of the command.
@@ -312,2 +332,16 @@ */
     /**
+     * Test whether the command is visible for its current state.
+     *
+     * @param args - The arguments for the command. If the command does
+     *   not require arguments, this may be `null`.
+     *
+     * @returns `true` if the command is visible, `false` otherwise.
+     *
+     * #### Notes
+     * This method ignores the command arguments.
+     *
+     * **See also** [[setVisible]]
+     */
+    isVisible(args: any): boolean;
+    /**
      * Test whether the command is checked for its current state.
@@ -381,2 +415,11 @@ *
     /**
+     * Set the visible state for the command.
+     *
+     * @param value - The visible state for the command.
+     *
+     * #### Notes
+     * If the state changes, the [[changed]] signal will be emitted.
+     */
+    setVisible(value: boolean): void;
+    /**
      * Set the checked state for the command.
@@ -407,4 +450,135 @@ *
     private _enabled;
+    private _visible;
     private _checked;
     private _handler;
 }
+/**
+ * An options object for initializing a command item.
+ */
+export interface ICommandItemOptions {
+    /**
+     * The command for the command item.
+     */
+    command: Command;
+    /**
+     * The arguments for the command.
+     */
+    args?: any;
+    /**
+     * The keyboard shortcut decoration.
+     */
+    shortcut?: string;
+}
+/**
+ * A read-only object which combines a command and arguments.
+ *
+ * #### Notes
+ * This class is useful for UI controls which render commands for
+ * a given set of arguments, such as a menu or a command palette.
+ *
+ * Even though a command item is read-only, a command may still mutate
+ * its own state in-place which may change the computed item data. The
+ * consumer of a command item should connect to the `Command.changed`
+ * signal if it needs to be notified of command state changes.
+ */
+export declare class CommandItem {
+    /**
+     * Construct a new command item.
+     *
+     * @param options - The options for initializing the command item.
+     */
+    constructor(options: ICommandItemOptions);
+    /**
+     * Get the command for the command item.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    command: Command;
+    /**
+     * Get the arguments for the command.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    args: any;
+    /**
+     * Get the keyboard shortcut decoration.
+     *
+     * #### Notes
+     * The keyboard shortcut decoration is data which is explicitly *not*
+     * derived from or intrinsic to the command. This allows the keyboard
+     * shortcut to be defined externally as a user preference instead of
+     * in advance by the author of the command.
+     *
+     * This is a read-only property.
+     */
+    shortcut: string;
+    /**
+     * Get the display text for the command item.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    text: string;
+    /**
+     * Get the class name(s) for the command item icon.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    icon: string;
+    /**
+     * Get the short caption for the command item.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    caption: string;
+    /**
+     * Get the category for the command item.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    category: string;
+    /**
+     * Get the extra class name(s) for the command item.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    className: string;
+    /**
+     * Test whether the command item is enabled.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    isEnabled: boolean;
+    /**
+     * Test whether the command item is visible.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    isVisible: boolean;
+    /**
+     * Test whether the command item is checked.
+     *
+     * #### Notes
+     * This is a read-only property.
+     */
+    isChecked: boolean;
+    /**
+     * Execute the command items.
+     *
+     * #### Notes
+     * Calling `execute` when `isEnabled` is `false` may result in
+     * undefined behavior.
+     */
+    execute(): void;
+    private _command;
+    private _args;
+    private _shortcut;
+}

lib/index.js

@@ -21,15 +21,2 @@ /*-----------------------------------------------------------------------------
     }
-    Object.defineProperty(Command.prototype, "changed", {
-        /**
-         * A signal emitted when the command's state changes.
-         *
-         * #### Notes
-         * A subclass should emit this signal when the command state changes.
-         */
-        get: function () {
-            return CommandPrivate.changedSignal.bind(this);
-        },
-        enumerable: true,
-        configurable: true
-    });
     /**
@@ -160,2 +147,22 @@ * Get the display text for the command.
     /**
+     * Test whether the command is visible for its current state.
+     *
+     * @param args - The arguments for the command. If the command does
+     *   not require arguments, this may be `null`.
+     *
+     * @returns `true` if the command is visible, `false` otherwise.
+     *
+     * #### Notes
+     * A subclass may reimplement this method as needed. If the state
+     * changes at runtime, the [[changed]] signal should be emitted.
+     *
+     * UI elements which have a visual representation of a command will
+     * typically not display a non-visible command.
+     *
+     * The default implementation of this method returns `true`.
+     */
+    Command.prototype.isVisible = function (args) {
+        return true;
+    };
+    /**
      * Test whether the command is checked for its current state.
@@ -184,21 +191,18 @@ *
 /**
- * Safely execute a command.
- *
- * @param command - The command to execute.
- *
- * @param args - The arguments for the command. If the command does
- *   not require arguments, this may be `null`.
- *
- * #### Notes
- * If the commmand throws an exception, it will be caught and logged.
+ * The namespace for the `Command` class statics.
  */
-function safeExecute(command, args) {
-    try {
-        command.execute(args);
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-exports.safeExecute = safeExecute;
+var Command;
+(function (Command) {
+    /**
+     * A signal emitted when a command's state changes.
+     *
+     * #### Notes
+     * A command should emit this signal when its state changes.
+     *
+     * This is a static signal which passes the changed command as the
+     * argument for the signal. This reduces the number of connections
+     * in an application from potentially hundreds, to just a few.
+     */
+    Command.changed = (new phosphor_signaling_1.Signal()).bind(Command);
+})(Command = exports.Command || (exports.Command = {}));
 /**
@@ -229,2 +233,3 @@ * A concrete implementation of [[Command]].
         this._enabled = true;
+        this._visible = true;
         this._checked = false;
@@ -250,2 +255,5 @@ this._handler = options.handler;
         }
+        if (options.visible !== void 0) {
+            this._visible = options.visible;
+        }
         if (options.checked !== void 0) {
@@ -352,2 +360,18 @@ this._checked = options.checked;
     /**
+     * Test whether the command is visible for its current state.
+     *
+     * @param args - The arguments for the command. If the command does
+     *   not require arguments, this may be `null`.
+     *
+     * @returns `true` if the command is visible, `false` otherwise.
+     *
+     * #### Notes
+     * This method ignores the command arguments.
+     *
+     * **See also** [[setVisible]]
+     */
+    SimpleCommand.prototype.isVisible = function (args) {
+        return this._visible;
+    };
+    /**
      * Test whether the command is checked for its current state.
@@ -381,3 +405,3 @@ *
         this._text = value;
-        this.changed.emit(void 0);
+        Command.changed.emit(this);
     };
@@ -397,3 +421,3 @@ /**
         this._icon = value;
-        this.changed.emit(void 0);
+        Command.changed.emit(this);
     };
@@ -413,3 +437,3 @@ /**
         this._caption = value;
-        this.changed.emit(void 0);
+        Command.changed.emit(this);
     };
@@ -429,3 +453,3 @@ /**
         this._category = value;
-        this.changed.emit(void 0);
+        Command.changed.emit(this);
     };
@@ -445,3 +469,3 @@ /**
         this._className = value;
-        this.changed.emit(void 0);
+        Command.changed.emit(this);
     };
@@ -461,5 +485,20 @@ /**
         this._enabled = value;
-        this.changed.emit(void 0);
+        Command.changed.emit(this);
     };
     /**
+     * Set the visible state for the command.
+     *
+     * @param value - The visible state for the command.
+     *
+     * #### Notes
+     * If the state changes, the [[changed]] signal will be emitted.
+     */
+    SimpleCommand.prototype.setVisible = function (value) {
+        if (this._visible === value) {
+            return;
+        }
+        this._visible = value;
+        Command.changed.emit(this);
+    };
+    /**
      * Set the checked state for the command.
@@ -477,3 +516,3 @@ *
         this._checked = value;
-        this.changed.emit(void 0);
+        Command.changed.emit(this);
     };
@@ -491,3 +530,8 @@ /**
     SimpleCommand.prototype.execute = function (args) {
-        this._handler.call(void 0, args);
+        try {
+            this._handler.call(void 0, args);
+        }
+        catch (err) {
+            console.error(err);
+        }
     };
@@ -498,10 +542,184 @@ return SimpleCommand;
 /**
- * The namespace for the `Command` class private data.
+ * A read-only object which combines a command and arguments.
+ *
+ * #### Notes
+ * This class is useful for UI controls which render commands for
+ * a given set of arguments, such as a menu or a command palette.
+ *
+ * Even though a command item is read-only, a command may still mutate
+ * its own state in-place which may change the computed item data. The
+ * consumer of a command item should connect to the `Command.changed`
+ * signal if it needs to be notified of command state changes.
  */
-var CommandPrivate;
-(function (CommandPrivate) {
+var CommandItem = (function () {
     /**
-     * A signal emitted when a command's state changes.
+     * Construct a new command item.
+     *
+     * @param options - The options for initializing the command item.
      */
-    CommandPrivate.changedSignal = new phosphor_signaling_1.Signal();
-})(CommandPrivate || (CommandPrivate = {}));
+    function CommandItem(options) {
+        this._command = options.command;
+        this._args = options.args || null;
+        this._shortcut = options.shortcut || '';
+    }
+    Object.defineProperty(CommandItem.prototype, "command", {
+        /**
+         * Get the command for the command item.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "args", {
+        /**
+         * Get the arguments for the command.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._args;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "shortcut", {
+        /**
+         * Get the keyboard shortcut decoration.
+         *
+         * #### Notes
+         * The keyboard shortcut decoration is data which is explicitly *not*
+         * derived from or intrinsic to the command. This allows the keyboard
+         * shortcut to be defined externally as a user preference instead of
+         * in advance by the author of the command.
+         *
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._shortcut;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "text", {
+        /**
+         * Get the display text for the command item.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.text(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "icon", {
+        /**
+         * Get the class name(s) for the command item icon.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.icon(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "caption", {
+        /**
+         * Get the short caption for the command item.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.caption(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "category", {
+        /**
+         * Get the category for the command item.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.category(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "className", {
+        /**
+         * Get the extra class name(s) for the command item.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.className(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "isEnabled", {
+        /**
+         * Test whether the command item is enabled.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.isEnabled(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "isVisible", {
+        /**
+         * Test whether the command item is visible.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.isVisible(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(CommandItem.prototype, "isChecked", {
+        /**
+         * Test whether the command item is checked.
+         *
+         * #### Notes
+         * This is a read-only property.
+         */
+        get: function () {
+            return this._command.isChecked(this._args);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Execute the command items.
+     *
+     * #### Notes
+     * Calling `execute` when `isEnabled` is `false` may result in
+     * undefined behavior.
+     */
+    CommandItem.prototype.execute = function () {
+        this._command.execute(this._args);
+    };
+    return CommandItem;
+})();
+exports.CommandItem = CommandItem;

package.json

 {
   "name": "phosphor-command",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A module for expressing the command pattern.",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

No alert changes

Improved metrics

Total package byte prevSize

45777

increased by34.96%

Lines of code

1287

increased by43.8%

No dependency changes