Rename keyboard.hold and release to up and down (#95)

References #89
2017-07-19 14:27:01 -07:00 · 2017-07-19 14:27:01 -07:00 · 71f8c76f04
commit 71f8c76f04
parent 21af495b65
4 changed files with 46 additions and 47 deletions
--- a/docs/api.md
+++ b/docs/api.md
@ -61,12 +61,12 @@
  * [page.waitFor(selector)](#pagewaitforselector)
  * [page.waitForNavigation(options)](#pagewaitfornavigationoptions)
 - [class: Keyboard](#class-keyboard)
-  * [keyboard.hold(key[, options])](#keyboardholdkey-options)
+  * [keyboard.down(key[, options])](#keyboarddownkey-options)
  * [keyboard.modifiers()](#keyboardmodifiers)
  * [keyboard.press(key[, options])](#keyboardpresskey-options)
-  * [keyboard.release(key)](#keyboardreleasekey)
  * [keyboard.sendCharacter(char)](#keyboardsendcharacterchar)
  * [keyboard.type(text)](#keyboardtypetext)
+  * [keyboard.up(key)](#keyboardupkey)
 - [class: Dialog](#class-dialog)
  * [dialog.accept([promptText])](#dialogacceptprompttext)
  * [dialog.dismiss()](#dialogdismiss)
@ -561,23 +561,23 @@ Shortcut for [page.mainFrame().waitFor(selector)](#framewaitforselector).

 Keyboard provides an api for managing a virtual keyboard. The high level api is [`keyboard.type`](#keyboardtypetext), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.

-For finer control, you can use press, release, and sendCharacter to manually fire events as if they were generated from a real keyboard.
+For finer control, you can use [`keyboard.down`](#keyboarddownkey-options), [`keyboard.up`](#keyboardupkey), and [`keyboard.sendCharacter`](#keyboardsendcharacterchar) to manually fire events as if they were generated from a real keyboard.

 An example of holding down `Shift` in order to select and delete some text:
 ```js
 page.keyboard.type('Hello World!');
 page.keyboard.press('ArrowLeft');

-page.keyboard.hold('Shift');
+page.keyboard.down('Shift');
 for (let i = 0; i = 0; i < ' World'.length; i++)
  page.keyboard.press('ArrowLeft');
-page.keyboard.release('Shift');
+page.keyboard.up('Shift');

 page.keyboard.press('Backspace');
 // Result text will end up saying 'Hello!'
 ```

-#### keyboard.hold(key[, options])
+#### keyboard.down(key[, options])
 - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [KeyboardEvent.key](https://www.w3.org/TR/uievents-key/)
 - `options` <[Object]>
  - `text` <[string]> If specified, generates an input event with this text.
@ -587,7 +587,7 @@ Dispatches a `keydown` event.

 This will not send input events unless `text` is specified.

-If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use [`keyboard.release`](#keyboardreleasekey).
+If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use [`keyboard.up`](#keyboardupkey).

 #### keyboard.modifiers()
 - returns: <[Object]>
@ -596,7 +596,7 @@ If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key
  - `Control` <[boolean]>
  - `Alt` <[boolean]>

- Returns which modifier keys are currently active. Use [`keyboard.hold`](#keyboardholdkey) to activate a modifier key.
+ Returns which modifier keys are currently active. Use [`keyboard.down`](#keyboarddownkey) to activate a modifier key.

 #### keyboard.press(key[, options])
 - `key` <[string]> Name of key to press, such as `ArrowLeft`. See [KeyboardEvent.key](https://www.w3.org/TR/uievents-key/)
@ -604,13 +604,7 @@ If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key
  - `text` <[string]> If specified, generates an input event with this text.
 - returns: <[Promise]>

-Shortcut for [`keyboard.hold`](#keyboardholdkey) and [`keyboard.release`](#keyboardreleasekey).
-
-#### keyboard.release(key)
- `key` <[string]> Name of key to release, such as `ArrowLeft`. See [KeyboardEvent.key](https://www.w3.org/TR/uievents-key/)
- returns: <[Promise]>
-
-Dispatches a `keyup` event.
+Shortcut for [`keyboard.down`](#keyboarddownkey) and [`keyboard.up`](#keyboardupkey).

 #### keyboard.sendCharacter(char)
 - `char` <[string]> Character to send into the page.
@ -633,6 +627,12 @@ This is the suggested way to type printable characters.
 page.keyboard.type('Hello World!');
 ```

+#### keyboard.up(key)
+- `key` <[string]> Name of key to release, such as `ArrowLeft`. See [KeyboardEvent.key](https://www.w3.org/TR/uievents-key/)
+- returns: <[Promise]>
+
+Dispatches a `keyup` event.
+
 ### class: Dialog

 [Dialog] objects are dispatched by page via the ['dialog'](#event-dialog) event.
--- a/lib/Keyboard.js
+++ b/lib/Keyboard.js
@ -31,7 +31,7 @@ class Keyboard {
   * @param {{text: (string|undefined)}} options
   * @return {!Promise}
   */
-  async hold(key, options) {
+  async down(key, options) {
    let {text} = options || {};
    this._keys.add(key);
    await this._client.send('Input.dispatchKeyEvent', {
@ -60,7 +60,7 @@ class Keyboard {
   * @param {string} key
   * @return {!Promise}
   */
-  async release(key) {
+  async up(key) {
    this._keys.delete(key);
    await this._client.send('Input.dispatchKeyEvent', {
      type: 'keyUp',
@ -76,8 +76,8 @@ class Keyboard {
   * @return {!Promise}
   */
  async press(key, options) {
-    this.hold(key, options);
-    await this.release(key);
+    this.down(key, options);
+    await this.up(key);
  }

  /**
--- a/phantom_shim/WebPage.js
+++ b/phantom_shim/WebPage.js
@ -414,37 +414,37 @@ class WebPage {
    switch (eventType) {
      case 'keyup':
        if (typeof keyOrKeys === 'number') {
-          await(this._page.keyboard.release(String.fromCharCode(keyOrKeys)));
+          await(this._page.keyboard.up(String.fromCharCode(keyOrKeys)));
          break;
        }
        for (let key of keyOrKeys)
-          await(this._page.keyboard.release(key));
+          await(this._page.keyboard.up(key));
        break;
      case 'keypress':
        if (modifier & 0x04000000)
-          this._page.keyboard.hold('Control');
+          this._page.keyboard.down('Control');
        if (modifier & 0x02000000)
-          this._page.keyboard.hold('Shift');
+          this._page.keyboard.down('Shift');
        if (keyOrKeys instanceof Array) {
-          this._page.keyboard.hold(keyOrKeys[0]);
-          await(this._page.keyboard.release(keyOrKeys[0]));
+          this._page.keyboard.down(keyOrKeys[0]);
+          await(this._page.keyboard.up(keyOrKeys[0]));
        } else if (typeof keyOrKeys === 'number') {
          await(this._page.type(String.fromCharCode(keyOrKeys)));
        } else {
          await(this._page.type(keyOrKeys));
        }
        if (modifier & 0x02000000)
-          this._page.keyboard.release('Shift');
+          this._page.keyboard.up('Shift');
        if (modifier & 0x04000000)
-          this._page.keyboard.release('Control');
+          this._page.keyboard.up('Control');
        break;
      case 'keydown':
        if (typeof keyOrKeys === 'number') {
-          await(this._page.keyboard.hold(String.fromCharCode(keyOrKeys)));
+          await(this._page.keyboard.down(String.fromCharCode(keyOrKeys)));
          break;
        }
        for (let key of keyOrKeys)
-          await(this._page.keyboard.hold(key));
+          await(this._page.keyboard.down(key));
        break;
    }
  }
--- a/test/test.js
+++ b/test/test.js
@ -698,12 +698,11 @@ describe('Puppeteer', function() {
        keyboard.press('ArrowLeft');
      await keyboard.type('inserted ');
      expect(await page.evaluate(() => document.querySelector('textarea').value)).toBe('Hello inserted World!');
-      keyboard.hold('Shift');
+      keyboard.down('Shift');
      for (let i = 0; i < 'inserted '.length; i++)
        keyboard.press('ArrowLeft');
-      keyboard.release('Shift');
-      keyboard.hold('Backspace');
-      await keyboard.release('Backspace');
+      keyboard.up('Shift');
+      await keyboard.press('Backspace');
      expect(await page.evaluate(() => document.querySelector('textarea').value)).toBe('Hello World!');
    }));
    it('should report shiftKey', SX(async function(){
@ -711,30 +710,30 @@ describe('Puppeteer', function() {
      let keyboard = page.keyboard;
      let codeForKey = {'Shift': 16, 'Alt': 18, 'Meta': 91, 'Control': 17};
      for (let modifierKey in codeForKey) {
-        await keyboard.hold(modifierKey);
+        await keyboard.down(modifierKey);
        expect(await page.evaluate(() => getResult())).toBe('Keydown: ' + modifierKey + ' ' + codeForKey[modifierKey] + ' [' + modifierKey + ']');
-        await keyboard.hold('!');
+        await keyboard.down('!');
        expect(await page.evaluate(() => getResult())).toBe('Keydown: ! 49 [' + modifierKey + ']');
-        await keyboard.release('!');
+        await keyboard.up('!');
        expect(await page.evaluate(() => getResult())).toBe('Keyup: ! 49 [' + modifierKey + ']');
-        await keyboard.release(modifierKey);
+        await keyboard.up(modifierKey);
        expect(await page.evaluate(() => getResult())).toBe('Keyup: ' + modifierKey + ' ' + codeForKey[modifierKey] + ' []');
      }
    }));
    it('should report multiple modifiers', SX(async function(){
      await page.navigate(PREFIX + '/input/keyboard.html');
      let keyboard = page.keyboard;
-      await keyboard.hold('Control');
+      await keyboard.down('Control');
      expect(await page.evaluate(() => getResult())).toBe('Keydown: Control 17 [Control]');
-      await keyboard.hold('Meta');
+      await keyboard.down('Meta');
      expect(await page.evaluate(() => getResult())).toBe('Keydown: Meta 91 [Control Meta]');
-      await keyboard.hold(';');
+      await keyboard.down(';');
      expect(await page.evaluate(() => getResult())).toBe('Keydown: ; 186 [Control Meta]');
-      await keyboard.release(';');
+      await keyboard.up(';');
      expect(await page.evaluate(() => getResult())).toBe('Keyup: ; 186 [Control Meta]');
-      await keyboard.release('Control');
+      await keyboard.up('Control');
      expect(await page.evaluate(() => getResult())).toBe('Keyup: Control 17 [Meta]');
-      await keyboard.release('Meta');
+      await keyboard.up('Meta');
      expect(await page.evaluate(() => getResult())).toBe('Keyup: Meta 91 []');
    }));
    it('should send proper codes while typing', SX(async function(){
@ -754,14 +753,14 @@ describe('Puppeteer', function() {
    it('should send propery codes while typing with shift', SX(async function(){
      await page.navigate(PREFIX + '/input/keyboard.html');
      let keyboard = page.keyboard;
-      await keyboard.hold('Shift');
+      await keyboard.down('Shift');
      await keyboard.type('~');
      expect(await page.evaluate(() => getResult())).toBe(
          [ 'Keydown: Shift 16 [Shift]',
            'Keydown: ~ 192 [Shift]', // 192 is ` keyCode
            'Keypress: ~ 126 126 126 [Shift]', // 126 is ~ charCode
            'Keyup: ~ 192 [Shift]'].join('\n'));
-      await keyboard.release('Shift');
+      await keyboard.up('Shift');
    }));
    it('should not type canceled events', SX(async function(){
      await page.navigate(PREFIX + '/input/textarea.html');
@ -786,10 +785,10 @@ describe('Puppeteer', function() {
      expect(keyboard.modifiers().Meta).toBe(false);
      expect(keyboard.modifiers().Alt).toBe(false);
      expect(keyboard.modifiers().Control).toBe(false);
-      keyboard.hold('Shift');
+      keyboard.down('Shift');
      expect(keyboard.modifiers().Shift).toBe(true);
      expect(keyboard.modifiers().Alt).toBe(false);
-      keyboard.release('Shift');
+      keyboard.up('Shift');
      expect(keyboard.modifiers().Shift).toBe(false);
      expect(keyboard.modifiers().Alt).toBe(false);
    }));