目录

@ohos.multimodalInput.pointer (Mouse Pointer)

The pointer module provides APIs related to pointer attribute management.

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { pointer } from '@kit.InputKit';

pointer.setPointerVisible

setPointerVisible(visible: boolean, callback: AsyncCallback<void>): void

Sets the visible status of the mouse pointer. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
visible boolean Yes Whether the mouse pointer is visible. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

try {
  pointer.setPointerVisible(true, (error: Error) => {
    if (error) {
      console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
      return;
    }
    console.log(`Set pointer visible success`);
  });
} catch (error) {
  console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

pointer.setPointerVisible

setPointerVisible(visible: boolean): Promise<void>

Sets the visible status of the mouse pointer. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
visible boolean Yes Whether the mouse pointer is visible. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.

Return value

Name Description
Promise<void> Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

try {
  pointer.setPointerVisible(false).then(() => {
    console.log(`Set pointer visible success`);
  });
} catch (error) {
  console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

pointer.setPointerVisibleSync10+

setPointerVisibleSync(visible: boolean): void

Sets the visible status of the mouse pointer. This API returns the result synchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
visible boolean Yes Whether the mouse pointer is visible. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

try {
  pointer.setPointerVisibleSync(false);
  console.log(`Set pointer visible success`);
} catch (error) {
  console.log(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

pointer.isPointerVisible

isPointerVisible(callback: AsyncCallback<boolean>): void

Checks the visible status of the mouse pointer. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result. The value true indicates that the mouse pointer is displayed, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

try {
  pointer.isPointerVisible((error: Error, visible: boolean) => {
    if (error) {
      console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
      return;
    }
    console.log(`Get pointer visible success, visible: ${JSON.stringify(visible)}`);
  });
} catch (error) {
  console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

pointer.isPointerVisible

isPointerVisible(): Promise<boolean>

Checks the visible status of the mouse pointer. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Return value

Name Description
Promise<boolean> Promise used to return the result.

Example

try {
  pointer.isPointerVisible().then((visible: boolean) => {
    console.log(`Get pointer visible success, visible: ${JSON.stringify(visible)}`);
  });
} catch (error) {
  console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

pointer.isPointerVisibleSync10+

isPointerVisibleSync(): boolean

Obtains the visible status of the mouse pointer. This API returns the result synchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Return value

Name Description
boolean Visible status of the mouse pointer. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.

Example

try {
  let visible: boolean = pointer.isPointerVisibleSync();
  console.log(`Get pointer visible success, visible: ${JSON.stringify(visible)}`);
} catch (error) {
  console.log(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

pointer.getPointerStyle

getPointerStyle(windowId: number, callback: AsyncCallback<PointerStyle>): void

Obtains the mouse pointer style. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID.
callback AsyncCallback<PointerStyle> Yes Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

let context = getContext(this);
window.getLastWindow(context, (error: BusinessError, win: window.Window) => {
  if (error.code) {
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
    return;
  }
  let windowId = win.getWindowProperties().id;
  if (windowId < 0) {
    console.log(`Invalid windowId`);
    return;
  }
  try {
    pointer.getPointerStyle(windowId, (error: Error, style: pointer.PointerStyle) => {
      console.log(`Get pointer style success, style: ${JSON.stringify(style)}`);
    });
  } catch (error) {
    console.log(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
  }
});

pointer.getPointerStyle

getPointerStyle(windowId: number): Promise<PointerStyle>

Obtains the mouse pointer style. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID.

Return value

Name Description
Promise<PointerStyle> Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

let context = getContext(this);
window.getLastWindow(context, (error: BusinessError, win: window.Window) => {
  if (error.code) {
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
    return;
  }
  let windowId = win.getWindowProperties().id;
  if (windowId < 0) {
    console.log(`Invalid windowId`);
    return;
  }
  try {
    pointer.getPointerStyle(windowId).then((style: pointer.PointerStyle) => {
      console.log(`Get pointer style success, style: ${JSON.stringify(style)}`);
    });
  } catch (error) {
    console.log(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
  }
});

pointer.getPointerStyleSync10+

getPointerStyleSync(windowId: number): PointerStyle

Obtains the mouse pointer style. This API returns the result synchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes

Window ID.

The default value is -1, indicating the global mouse pointer style.

Return value

Name Description
PointerStyle Mouse pointer style.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';

let windowId = -1;
try {
  let style: pointer.PointerStyle = pointer.getPointerStyleSync(windowId);
  console.log(`Get pointer style success, style: ${JSON.stringify(style)}`);
} catch (error) {
  console.log(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
}

pointer.setPointerStyle

setPointerStyle(windowId: number, pointerStyle: PointerStyle, callback: AsyncCallback<void>): void

Sets the mouse pointer style. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID.
pointerStyle PointerStyle Yes Pointer style.
callback AsyncCallback<void> Yes Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => {
  if (error.code) {
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
    return;
  }
  let windowId = win.getWindowProperties().id;
  if (windowId < 0) {
    console.log(`Invalid windowId`);
    return;
  }
  try {
    pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS, error => {
      console.log(`Set pointer style success`);
    });
  } catch (error) {
    console.log(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
  }
});

pointer.setPointerStyle

setPointerStyle(windowId: number, pointerStyle: PointerStyle): Promise<void>

Sets the mouse pointer style. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID.
pointerStyle PointerStyle Yes Pointer style.

Return value

Name Description
Promise<void> Promise used to return the result.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => {
  if (error.code) {
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
    return;
  }
  let windowId = win.getWindowProperties().id;
  if (windowId < 0) {
    console.log(`Invalid windowId`);
    return;
  }
  try {
    pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS).then(() => {
      console.log(`Set pointer style success`);
    });
  } catch (error) {
    console.log(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
  }
});

pointer.setPointerStyleSync10+

setPointerStyleSync(windowId: number, pointerStyle: PointerStyle): void

Sets the mouse pointer style. This API returns the result synchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID.
pointerStyle PointerStyle Yes Pointer style.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => {
  if (error.code) {
    console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
    return;
  }
  let windowId = win.getWindowProperties().id;
  if (windowId < 0) {
    console.log(`Invalid windowId`);
    return;
  }
  try {
    pointer.setPointerStyleSync(windowId, pointer.PointerStyle.CROSS);
    console.log(`Set pointer style success`);
  } catch (error) {
    console.log(`getPointerSize failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
  }
});

PrimaryButton10+

Type of the primary mouse button.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Value Description
LEFT 0 Left mouse button.
RIGHT 1 Right mouse button.

RightClickType10+

Enumerates shortcut menu triggering modes.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Value Description
TOUCHPAD_RIGHT_BUTTON 1 Tapping the right-button area of the touchpad.
TOUCHPAD_LEFT_BUTTON 2 Tapping the left-button area of the touchpad.
TOUCHPAD_TWO_FINGER_TAP 3 Tapping or pressing the touchpad with two fingers.

PointerStyle

Enumerates mouse pointer styles.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Value Description Legend
DEFAULT 0 Default
EAST 1 East arrow
WEST 2 West arrow
SOUTH 3 South arrow
NORTH 4 North arrow
WEST_EAST 5 West-east arrow
NORTH_SOUTH 6 North-south arrow
NORTH_EAST 7 North-east arrow
NORTH_WEST 8 North-west arrow
SOUTH_EAST 9 South-east arrow
SOUTH_WEST 10 South-west arrow
NORTH_EAST_SOUTH_WEST 11 North-east and south-west adjustment
NORTH_WEST_SOUTH_EAST 12 North-west and south-east adjustment
CROSS 13 Cross (accurate selection)
CURSOR_COPY 14 Copy
CURSOR_FORBID 15 Forbid
COLOR_SUCKER 16 Sucker
HAND_GRABBING 17 Grabbing hand
HAND_OPEN 18 Opening hand
HAND_POINTING 19 Hand-shaped pointer
HELP 20 Help
MOVE 21 Move
RESIZE_LEFT_RIGHT 22 Left and right resizing
RESIZE_UP_DOWN 23 Up and down resizing
SCREENSHOT_CHOOSE 24 Screenshot crosshair
SCREENSHOT_CURSOR 25 Screenshot
TEXT_CURSOR 26 Text selection
ZOOM_IN 27 Zoom in
ZOOM_OUT 28 Zoom out
MIDDLE_BTN_EAST 29 Scrolling east
MIDDLE_BTN_WEST 30 Scrolling west
MIDDLE_BTN_SOUTH 31 Scrolling south
MIDDLE_BTN_NORTH 32 Scrolling north
MIDDLE_BTN_NORTH_SOUTH 33 Scrolling north-south
MIDDLE_BTN_NORTH_EAST 34 Scrolling north-east
MIDDLE_BTN_NORTH_WEST 35 Scrolling north-west
MIDDLE_BTN_SOUTH_EAST 36 Scrolling south-east
MIDDLE_BTN_SOUTH_WEST 37 Scrolling south-west
MIDDLE_BTN_NORTH_SOUTH_WEST_EAST 38 Moving as a cone in four directions
HORIZONTAL_TEXT_CURSOR10+ 39 Horizontal text selection
CURSOR_CROSS10+ 40 Cross
CURSOR_CIRCLE10+ 41 Circle
LOADING10+ 42 Animation loading

Atomic service API: This API can be used in atomic services since API version 12.

RUNNING10+ 43 Animation running in the background

Atomic service API: This API can be used in atomic services since API version 12.

pointer.setCustomCursor11+

setCustomCursor(windowId: number, pixelMap: image.PixelMap, focusX?: number, focusY?: number): Promise<void>

Sets a custom cursor. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID.
pixelMap image.PixelMap Yes Pixel map resource.
focusX number No Focus x of the custom cursor. The value is greater than or equal to 0. The default value is 0.
focusY number No Focus y of the custom cursor. The value is greater than or equal to 0. The default value is 0.

Return value

Name Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
getContext().resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => {
  const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0);
  let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer);
  let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }};
  svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => {
    window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => {
      let windowId = win.getWindowProperties().id;
        try {
          pointer.setCustomCursor(windowId, pixelMap).then(() => {
            console.log(`setCustomCursor success`);
          });
        } catch (error) {
          console.log(`setCustomCursor failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
        }
      });
  });
});

pointer.setCustomCursorSync11+

setCustomCursorSync(windowId: number, pixelMap: image.PixelMap, focusX?: number, focusY?: number): void

Sets a custom cursor. This API returns the result synchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID.
pixelMap image.PixelMap Yes Pixel map resource.
focusX number No Focus x of the custom cursor. The value is greater than or equal to 0. The default value is 0.
focusY number No Focus y of the custom cursor. The value is greater than or equal to 0. The default value is 0.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';
const svgFileData = getContext().resourceManager.getMediaContent($r("app.media.app_icon")).then((svgFileData) => {
  const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0);
  let svgImagesource: image.ImageSource = image.createImageSource(svgBuffer);
  let svgDecodingOptions: image.DecodingOptions = {desiredSize: { width: 50, height:50 }};
  svgImagesource.createPixelMap(svgDecodingOptions).then((pixelMap) => {
    window.getLastWindow(getContext(), (error: BusinessError, win: window.Window) => {
      let windowId = win.getWindowProperties().id;
        try {
          pointer.setCustomCursorSync(windowId, pixelMap, 25, 25);
          console.log(`setCustomCursorSync success`);
        } catch (error) {
          console.log(`setCustomCursorSync failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
        }
    });
  });
});