IWindow

​

Interface IWindow

interface IWindow

Extends com.amazon.apmf.IStandard A window is a rectangle area where the client can render a scene on a display. This class represents a window and provides methods to create / destroy a window with desired properties such as format, size, role, and more. Once the window is created, its state can be managed through this class. By default, Window is assumed to show transparent pixels and ChildWindow Opaque content. Clients can override these settings to optimize rendering appropriately.

​

Methods

​

createChildWindow()

IWindow* createChildWindow(i32 posXRelativeToParent, i32 posYRelativeToParent, i32 requestedWidth, i32 requestedHeight, string title, IWindow* refWindow, ZorderPosition pos)

Construct a new opaque window which is a child of this window (parent). Child window position (top-left) is expected relative to parent window’s top-left position. If requested width and height are both zero, then a full-screen window based on ICanvasConfig size is created. If both are non-zero, then display-subsystem would try to respect the size but it may be overridden by the Window Manager. Use IResizeListener to check for actual size of the window. Position and size are expected in logical pixels as per ICanvasConfig. Window role is set as the same as parent one and window is by default created as opaque.

​

Parameters

posXRelativeToParent

i32 — Required The desired window position x coordinate (may be overridden by the Window Manager - use a IPositionListener to check)

posYRelativeToParent

i32 — Required The desired window position y coordinate (may be overridden by the Window Manager - use a IPositionListener to check)

requestedWidth

i32 — Required The desired window width (may be overridden by the Window Manager - use a IResizeListener to check)

requestedHeight

i32 — Required The desired window height (may be overridden by the Window Manager - use a ResizeListener to check)

title

string — Required Desired title

refWindow

IWindow* — Required The reference window has to be already a child of the parent window or the parent itself. “refWindow” is only used to indicate the relative z-order position of this child window relative to the reference window.

pos

ZorderPosition — Required Child window creation parameter “ABOVE_ZPOS” indicates position above reference window & “BELOW_ZPOS” indicates position below reference window.

​

Returns

IWindow* child window, and throw a runtime exception if creation failed.

​

Throws

• DeviceError — if IWindow is not in valid state
• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid
• OutOfMemoryError — if device is out of memory

---

​

setInputRegion()

void setInputRegion(RectI[] region)

Set active input region to this window. The active input region is the area of the window where input events will be received. By default, if no active input region is specified, the region is infinite and the entire window will receive input events. Calling this function will limit the active input region to the region specified.

​

Parameters

region

RectI[] — Required The active input region. The region is defined as a rect with top left corner at (x, y) and a width/height. Region(x, y, width, height)

​

Throws

• DeviceError — if IWindow is not in valid state
• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

subtractInputRegion()

void subtractInputRegion(RectI[] region)

Subtracts an active input region from this window. The active input region is the area of the window where input events will be received. An active input region must have been added prior to calling this function

​

Parameters

region

RectI[] — Required The input region to subtract. The region is defined as a rect with top left corner at (x, y) and a width/height. Region(x, y, width, height)

​

Throws

• DeviceError — if IWindow is not in valid state
• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

setOpaqueRegion()

void setOpaqueRegion(RectI[] region)

Adds an opaque region to this window. This allows display server to optimize rendering composition of layers below this region.

​

Parameters

region

RectI[] — Required The opaque region. The region is defined as a rect with top left corner at (x, y) and a width/height. Region(x, y, width, height). The region is specified in Window local co-ordinates.

​

Throws

• DeviceError — if IWindow is not in valid state
• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

subtractOpaqueRegion()

void subtractOpaqueRegion(RectI[] region)

Subtracts an opaque region from this window.

​

Parameters

region

RectI[] — Required The opaque region to subtract. The region is defined as a rect with top left corner at (x, y) and a width/height. Region(x, y, width, height). The region is specified in Window local co-ordinates.

​

Throws

• DeviceError — if IWindow is not in valid state
• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

getHandle()

i64 getHandle()

Query the window handle which can be used to initialize a Surface returnWindow handle, can be used to create surface and buffer consumers [IGpuDevice#createScreenSurface] [IGraphicsModule#createMediaSurface] The handle will remain valid until the window is destroyed.

​

Returns

i64 i64

​

Throws

• DeviceError — if IWindow is not in valid state

---

​

show()

void show()

Instruct the display server to show the window (if it was hidden)

​

Throws

• DeviceError — if IWindow is not in valid state

---

​

hide()

void hide()

Instruct the display server to hide the window, but don’t destroy it, and don’t de-allocate buffers.

​

Throws

• DeviceError — if IWindow is not in valid state

---

​

setSize()

void setSize(i32 width, i32 height)

Set the size of this Window based on the adjusted window position. This will set the size of the window, taking the adjusted position into account.

​

Parameters

width

i32 — Required “width” value of the new size in pixels

height

i32 — Required “height” value of the new size in pixels

​

Throws

• DeviceError — if IWindow is not in valid state
• NullPointerError — if any input argument is null pointer while a non-null one is expected

---

​

setPos()

void setPos(i32 x, i32 y)

Take the x and y position and internally adds the adjusted offset (Ex, for video letter box) to compute the final position. Compared to setPos() API which takes the absolute x and y position, this allows the client to change the position without knowing the adjusted offset, and it means the final position set by this API can be different than given values. For more details and descriptions, refer to setPos().

​

Parameters

x

i32 — Required value of the new position based on original one.

y

i32 — Required value of the new position based on original one.

​

Throws

• DeviceError — if IWindow is not in valid state

---

​

getWidth()

i32 getWidth()

​

Returns

i32 Window width in pixels

---

​

getHeight()

i32 getHeight()

​

Returns

i32 Window height in pixels

---

​

getTitle()

string getTitle()

​

Returns

string Window title

---

​

setViewportSource()

bool setViewportSource(i32 x, i32 y, i32 width, i32 height)

Set the source viewport of the window The viewport defines the subregion of window to be scanned out. In order to scale up/down the source viewport, the destination viewport size needs to be adjusted using setViewportDestination(), otherwise, the destination size is set to current window size. The x/y/width/height must be positive and within window geometry.

​

Parameters

x

i32 — Required Position of source viewport

y

i32 — Required Position of source viewport

width

i32 — Required Width of source viewport

height

i32 — Required Height of source viewport

​

Returns

bool True on success

​

Throws

• DeviceError — if IWindow is not in valid state
• InvalidArgumentError — if any input argument is invalid

---

​

setViewportDestination()

bool setViewportDestination(i32 width, i32 height)

Set the destination viewport size of the window Width/height must be positive and within boundary.

• it should be within window size for full-screen window
• it should be same as window size for maximized window

​

Parameters

width

i32 — Required Width of viewport destination size

height

i32 — Required Height of viewport destination size

​

Returns

bool true on success

​

Throws

• DeviceError — if IWindow is not in valid state
• InvalidArgumentError — if any input argument is invalid

---

​

addKeyboardListener()

com.amazon.apmf.ISubscription* addKeyboardListener(IKeyboardListener* listener)

This API is deprecated. Use [IWindow2#addKeyEventListener] Add window keyboard listener handler. The listener will continue to receive events until ISubscription#unsubscribe() is called or until the event source is destroyed.

​

Parameters

listener

IKeyboardListener* — Required IKeyboardListener Listener interface

​

Returns

com.amazon.apmf.ISubscription* ISubscription* related to this listener interface [IKeyboardListener]

​

Throws

• DeviceError — if IWindow is not in valid state
• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

addPointerListener()

com.amazon.apmf.ISubscription* addPointerListener(IPointerListener* listener)

This API is deprecated. Use [IWindow2#addPointerEventListener] Add window pointer device listener handler The listener will continue to receive events until ISubscription#unsubscribe() is called or until the event source is destroyed.

​

Parameters

listener

IPointerListener* — Required IPointerListener Listener interface

​

Returns

com.amazon.apmf.ISubscription* ISubscription* related to this listener interface [IPointerListener]

​

Throws

• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

addTouchListener()

com.amazon.apmf.ISubscription* addTouchListener(ITouchListener* listener)

This API is deprecated. Use [IWindow2#addTouchEventListener] Add window touch listener handler. The listener will continue to receive events until ISubscription#unsubscribe() is called or until the event source is destroyed.

​

Parameters

listener

ITouchListener* — Required ITouchListener listener interface

​

Returns

com.amazon.apmf.ISubscription* ISubscription* related to this listener interface [ITouchListener]

​

Throws

• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

addResizeListener()

com.amazon.apmf.ISubscription* addResizeListener(IResizeListener* listener)

Add window resize listener handler. The listener will continue to receive events until ISubscription#unsubscribe() is called or until the event source is destroyed.

​

Parameters

listener

IResizeListener* — Required IResizeListener listener interface

​

Returns

com.amazon.apmf.ISubscription* ISubscription* related to this listener interface [IResizeListener]

​

Throws

• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

addPositionListener()

com.amazon.apmf.ISubscription* addPositionListener(IPositionListener* listener)

Add window position change listener handler. The listener will continue to receive events until ISubscription#unsubscribe() is called or until the event source is destroyed.

​

Parameters

listener

IPositionListener* — Required IPositionListener listener interface

​

Returns

com.amazon.apmf.ISubscription* ISubscription* related to this listener interface [IPositionListener]

​

Throws

• NullPointerError — if any input argument is null pointer while a non-null one is expected
• InvalidArgumentError — if any input argument is invalid

---

​

acknowledgeInputEvents()

void acknowledgeInputEvents(i32 eventId, bool needToForwardEvent)

This API is deprecated. Use [IInputEvent#acknowledge] Acknowledges an input event and optionally requests framework to forward the input event to other clients in the system. Clients must call this API for each input events it receives via IKeyboardListener, IPointerListener & ITouchListener interfaces. Clients failing to acknowledge an input event will be treated as unresponsive and forced to terminate.

​

Parameters

eventId

i32 — Required valid event ID passed in callbacks of IKeyboardListener, IPointerListener & ITouchListener interfaces.

needToForwardEvent

bool — Required if true framework will forward this input event to other components in the system assuming clients couldn’t make any sense of this input event in it’s current state of things. [IKeyboardListener], [IPointerListener], [ITouchListener]

​

Throws

• DeviceError — if IWindow is not in valid state
• InvalidArgumentError — if any input argument is invalid

---