Screen property types

Since:

BlackBerry 10.0.0

Data:

SCREEN_PROPERTY_ALPHA_MODE

A single integer that defines how alpha should be interpreted.

The alpha mode must be of type Screen alpha mode types. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property and share this same definition:

• pixmap
• window
  • In the configuration file, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following are valid settings that can be used for this property in graphics.conf:
    • alpha-mode = pre-multipled
    • alpha-mode = non-pre-multipled

SCREEN_PROPERTY_GAMMA

A single integer that indicates the gamma value of the current display; a property of a display object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer.

SCREEN_PROPERTY_BRIGHTNESS

A single integer between [-255..255] that is used to adjust the brightness of a window; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• brightness = [brightness -255..255]

SCREEN_PROPERTY_BUFFER_COUNT

A single integer that indicates the number of buffers that were created or attached to the window; a property of a window object.

When retrieving this property type, ensure that you have sufficient storage for one integer. Also note that this property is local to the window object. This means that a query for this property will not trigger a flush of the command buffer despite that screen_get_window_property_iv() is of type flushing execution. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value (beyond initialization, this property can only queried and not set. The following is the usage for setting this property in graphics.conf:

• buffer-count = [number of buffers]

SCREEN_PROPERTY_BUFFER_SIZE

A pair of integers containing the width and height, in pixels, of the buffer.

When retrieving or setting this property type, ensure that you provide sufficient storage for two integers. The following API objects have this property and share this same definition:

• buffer
• pixmap
• window
  • In the configuration file, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
    • surface-size [width] x [height]

SCREEN_PROPERTY_BUTTONS

A single integer which is a bitmask indicating which buttons are pressed; a property of an event object or device object.

Note that D-pad, A, B, X, Y, Start, Select, Left, and Right are all considered buttons on gamepads. Currently, there is no button-map on gamepads equivalent to keymaps for keyboards. When retrieving this property type, ensure that you provide sufficient storage for one integer. The SCREEN_PROPERTY_BUTTONS property is applicable to the following events and device types:

• SCREEN_EVENT_GAMEPAD
• SCREEN_EVENT_JOG
• SCREEN_EVENT_JOYSTICK
• SCREEN_EVENT_MTOUCH_PRETOUCH
• SCREEN_EVENT_MTOUCH_TOUCH
• SCREEN_EVENT_MTOUCH_MOVE
• SCREEN_EVENT_MTOUCH_RELEASE
• SCREEN_EVENT_POINTER: In the case of a pointer, SCREEN_PROPERTY_BUTTONS must be a combination of type Screen mouse button types.

SCREEN_PROPERTY_COLOR_SPACE

A single integer that indicates the color space of a buffer.

The color space must be of type Screen color space types. The default value is SCREEN_COLOR_SPACE_UNCORRECTED. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property and share this same definition:

• pixmap
• window

SCREEN_PROPERTY_CONTRAST

A single integer between [-128..127] that is used to adjust the contrast of a window; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• contrast = [window contrast -128..127]

SCREEN_PROPERTY_DEVICE

A single integer representing the object handle for the input device that the event came from; a property of an event object.

When retrieving this property type, ensure that you provide sufficient storage for one integer. The SCREEN_PROPERTY_DEVICE property is applicable to the following events:

• SCREEN_EVENT_GAMEPAD
• SCREEN_EVENT_INPUT
• SCREEN_EVENT_JOG
• SCREEN_EVENT_JOYSTICK
• SCREEN_EVENT_KEYBOARD
• SCREEN_EVENT_MTOUCH_PRETOUCH
• SCREEN_EVENT_MTOUCH_TOUCH
• SCREEN_EVENT_MTOUCH_MOVE
• SCREEN_EVENT_MTOUCH_RELEASE
• SCREEN_EVENT_POINTER
• SCREEN_EVENT_DEVICE

SCREEN_PROPERTY_DEVICE_INDEX

Deprecated:

This property has been deprecated.

Use SCREEN_PROPERTY_DEVICE instead.

SCREEN_PROPERTY_DISPLAY

A display handle.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer. The following API objects have this property, each with its own variant of the definition:

• device: The display that is the focus for the specified input device. A value of NULL indicates that the input device is focused on the default display.
• event:
  • In the case of the SCREEN_EVENT_PROPERTY event, SCREEN_PROPERTY_DISPLAY is the property of either a device or a window, depending on the recipient object of the event.
  • In the case of the SCREEN_EVENT_DISPLAY event, SCREEN_PROPERTY_DISPLAY is the handle of the new external display that has been detected.
  • In the case of the SCREEN_EVENT_IDLE event, SCREEN_PROPERTY_DISPLAY is the handle of the display in which a window entered an idle state.
• session: The display associated with the specified input session if the session is active. When a session is linked to a window, the session and the window have the same display.
• window: The display on which the specified window will be shown if the window is visible. A value of NULL indicates that the window will be shown on the default display. Note that setting SCREEN_PROPERTY_DISPLAY invalidates the pipeline. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have its property initialized to this value. The following are valid settings that can be used for this property in graphics.conf:
  • display = internal
  • display = composite
  • display = svideo
  • display = YPbPr
  • display = rgb
  • display = rgbhv
  • display = dvi
  • display = hdmi
  • display = [display id]

SCREEN_PROPERTY_FLIP

A single integer that indicates whether or not the window contents are flipped; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_FORMAT

A single integer that indicates the pixel format of the buffer.

The format must be of type Screen pixel format types. When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. The following API objects have this property and share this same definition:

• buffer
• pixmap
• window
  • In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have its property initialized to this value. The following are valid settings that can be used for this property in graphics.conf:
    • format = byte
    • format = rgba4444
    • format = rgbx4444
    • format = rgba5551
    • format = rgbx5551
    • format = rgb565
    • format = rgb888
    • format = rgba8888
    • format = rgbx8888
    • format = yvu9
    • format = nv12
    • format = yv12
    • format = uyvy
    • format = yuy2
    • format = yvyu
    • format = v422
    • format = ayuv
    • format = [pixel format type 0..16]

SCREEN_PROPERTY_FRONT_BUFFER

A handle to the last buffer of the window to have been posted; a property of a window object.

When retrieving this property type, ensure that you have sufficient storage for one void pointer.

SCREEN_PROPERTY_GLOBAL_ALPHA

A single integer that indicates the global alpha value to be applied to the window; a property of a window object.

This value must be between 0 and 255. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• global-alpha = [global alpha 0..255]

SCREEN_PROPERTY_GROUP

The group that the API object is associated with.

When retrieving or setting this property type, ensure that you have sufficient storage according to the definition of the property for the specific API object. The following API objects have this property, each with its own variant of this definition(s):

• event: The window group that is associated with the event. SCREEN_PROPERTY_GROUP is applicable for the following events:
  • SCREEN_EVENT_IDLE The pointer to a group of type screen_group_t that has changed to idle state.
  • SCREEN_EVENT_PROPERTY The pointer to a group of type screen_group_t that has had a property changed.
  • SCREEN_EVENT_CREATE The name of the group that the window has joined. Typically this property would be relevant only to a SCREEN_EVENT_CREATE event for a child or embedded window. For an application window, the SCREEN_EVENT_CREATE is forwarded to the windowing system immediately and will have no group associated with it. However, a SCREEN_EVENT_CREATE event for a child or embedded window does not really exist unless it is associated with a parent (window group). Therefore, the SCREEN_EVENT_CREATE event for a child or embedded window has a group association.
• pixmap:
  • The name of the group that the pixmap is associated with when SCREEN_PROPERTY_GROUP is used with screen_get_pixmap_property_cv(). When retrieving this property type, ensure that you have sufficient storage for a character buffer.
  • The pointer to a group of type screen_group_t, that the pixmap is associated with when SCREEN_PROPERTY_GROUP is used with screen_get_pixmap_property_pv(). When retrieving this property type, ensure that you have sufficient storage for a structure of type screen_group_t.
• window
  • The name of the group that the window has created or parented when SCREEN_PROPERTY_GROUP is used with screen_get_window_property_cv(). When retrieving this property type, ensure that you have sufficient storage for a character buffer. If the window has not created or parented a group, then this property refers to the group that the window has joined.
  • The pointer to a group of type screen_group_t, that the window has created or parented when SCREEN_PROPERTY_GROUP is used with screen_get_window_property_pv(). When retrieving this property type, ensure that you have sufficient storage for a for a structure of type screen_group_t. If the window has not created or parented a group, then this property refers to the group that the window has joined.

SCREEN_PROPERTY_HUE

A single integer between [-128..127] that is used to adjust the hue of a window; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• hue = [global alpha -128..127]

SCREEN_PROPERTY_ID_STRING

A string that can be used by window manager or parent to identify the contents of the specified API object.

When retrieving or setting this property type, ensure that you provide a character buffer. The following API objects have this property and share this same definition:

• device
• display (SCREEN_PROPERTY_ID_STRING can only be retrieved and not set for a display object)
• pixmap
• session
• window
  • In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
    • id_string = [string]

SCREEN_PROPERTY_INTERLACED

A single integer that indicates whether or not the buffer contains interlaced fields instead of progressive data; a property of a buffer object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer.

SCREEN_PROPERTY_KEY_CAP

A single integer that indicates the keyboard cap associated with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. SCREEN_PROPERTY_KEY_CAP is applicable only to a SCREEN_EVENT_KEYBOARD event.

SCREEN_PROPERTY_FLAGS

A single integer that indicates the flags associated with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. SCREEN_PROPERTY_FLAGS is applicable for the following events:

• SCREEN_EVENT_GESTURE
• SCREEN_EVENT_KEYBOARD
• SCREEN_EVENT_POINTER

SCREEN_PROPERTY_KEY_FLAGS

See SCREEN_PROPERTY_FLAGS.

SCREEN_PROPERTY_MODIFIERS

A single integer that indicates the modifiers associated with the specific API object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. The following API objects have this property and share this same definition:

• display(SCREEN_PROPERTY_MODIFIERS can only be retrieved and not set for a display object)
• device
• event: This is only applicable for the following events:
  • SCREEN_EVENT_GAMEPAD
  • SCREEN_EVENT_GESTURE
  • SCREEN_EVENT_JOG
  • SCREEN_EVENT_JOYSTICK
  • SCREEN_EVENT_KEYBOARD
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_RELEASE
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_POINTER

SCREEN_PROPERTY_KEY_MODIFIERS

See SCREEN_PROPERTY_MODIFIERS.

SCREEN_PROPERTY_SCAN

A single integer that indicates the scan code associated with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. SCREEN_PROPERTY_SCAN is applicable only to SCREEN_EVENT_KEYBOARD and SCREEN_EVENT_GESTURE events.

SCREEN_PROPERTY_KEY_SCAN

See SCREEN_PROPERTY_SCAN.

SCREEN_PROPERTY_SYM

A single integer that indicates the symbols associated with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. SCREEN_PROPERTY_SYM is applicable only to SCREEN_EVENT_GESTURE and SCREEN_EVENT_KEYBOARD events.

SCREEN_PROPERTY_KEY_SYM

See SCREEN_PROPERTY_SYM.

SCREEN_PROPERTY_MIRROR

A single integer (0 or 1) that indicates whether or not contents of the API object are mirrored (flipped horizontally); a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_NAME

A single integer containing the name of the window group.

When retrieving or setting this property type, ensure you provide sufficient storage a character buffer. The following API objects have this property, and share this same definition:

• event (Applicable only to a SCREEN_EVENT_PROPERTY event)
• group

SCREEN_PROPERTY_OWNER_PID

A single integer that indicates the process id of the process responsible for creating the API object.

When retrieving this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, and share this same definition:

• window
• session

SCREEN_PROPERTY_PHYSICALLY_CONTIGUOUS

A single integer that indicates whether or not the buffer is physically contiguous; a property of a buffer object.

When retrieving or setting this property type, ensure you provide sufficient storage for one integer.

SCREEN_PROPERTY_PLANAR_OFFSETS

Three integers that provide the offset from the base address for each of the Y, U and V components of planar YUV formats; a property of a buffer object.

When retrieving or setting this property type, ensure that you have sufficient storage for three integers.

SCREEN_PROPERTY_POINTER

A pointer that can be used by software renderers to read from and/or write to the buffer; a property of a buffer object.

When this property is used, ensure that you provide sufficient storage space for one void pointer. The buffer must have been realized with a usage containing SCREEN_USAGE_READ and/or SCREEN_USAGE_WRITE for this property to be a valid pointer.

SCREEN_PROPERTY_POSITION

Integers that define position of the screen coordinates of the related API object.

The following API objects have this property, each with its own variant of this definition:

• event: The x and y values for the contact point of the mtouch or pointer. When retrieving or setting this property type, ensure that you have sufficient storage for two integers. This is only applicable for the following events:
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_RELEASE
  • SCREEN_EVENT_POINTER
• session: The x and y positions of the input region. The position is expressed relative to the top corner of the window buffer if the session is associated with a window. Otherwise, the position is in display coordinates. When retrieving or setting this property type, ensure that you have sufficient storage for two integers.
• window: The x and y positions of the window screen coordinates. Remember that the position of child and embedded windows are relative to the parent window. For example, if the position of the application window is {10, 10} and the position of the child window is {10, 10}, then the position of the child window on the screen is actually {20, 20}. When retrieving or setting this property type, ensure that you have sufficient storage for two integers. In the configuration file, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
  • window-position = [x-position] , [y-position]

SCREEN_PROPERTY_PROTECTED

A single integer that specifies whether or not there is protection for the buffer; a property of a buffer object.

The content of the buffer will not be displayed unless there is a secure link present. Operations on the buffer such as reading from, writing to, or mapping a region of the buffer to a different address space will be prohibited. Note that setting protection on a buffer does not invoke a request for authentication. Typically, the window that owns the buffer will have its window property, SCREEN_PROPERTY_PROTECTION_ENABLE, set. The request for authentication will be made when the window is posted and its SCREEN_PROPERTY_VISIBLE property indicates that the window is visible. When retrieving or setting this property type, ensure that you provide sufficient storage for one integer.

SCREEN_PROPERTY_RENDER_BUFFERS

A handle to the buffer or buffers available for rendering.

When retrieving this property type, ensure that you provide sufficient storage according to the API object type. The following API objects have this property, each with its own variant of this definition:

• pixmap: Only one buffer is allowed for a pixmap object. When retrieving SCREEN_PROPERTY_RENDER_BUFFERS for a pixmap object, ensure that you have sufficient storage for one void pointer.
• window: Multiple buffers may be available for rendering for a window object. When retrieving SCREEN_PROPERTY_RENDER_BUFFERS for a window, ensure that you have sufficient storage for one void pointer for each available buffer. Use the window property SCREEN_PROPERTY_RENDER_BUFFER_COUNT to determine the number of buffers you have for the window object.

SCREEN_PROPERTY_ROTATION

A single integer that defines the current rotation of the API object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• display: The current rotation of the display. The rotation value is one of: 0, 90, 180, 270 degrees clockwise. It's used for the positioning and sizing of the display. Changing the display rotation, does not implicitly change any window properties.
• window: The current rotation of the window. Window rotation is absolute. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
  • rotation = [rotation 0, 90, 180, 270]

SCREEN_PROPERTY_SATURATION

A single integer between [-128..127] that is used to adjust the saturation of a window; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have its property initialized to this value. The following is the usage for setting this property in graphics.conf:

• saturation = [saturation -128..127]

SCREEN_PROPERTY_SIZE

The size of the associated API object.

When retrieving or setting this property type, ensure that you provide sufficient storage according to the API object. The following API objects have this property, each with its own variant of this definition:

• buffer: A single integer that indicates the size, in bytes, of the buffer. When retrieving or setting this property type, ensure that you have sufficient storage for one integer.
• display: A pair of integers that define the width and height, in pixels, of the current video resolution. When retrieving this property type, ensure that you have sufficient storage for two integers. Note that the display size changes with the display rotation. For example, if the video mode is 1024x768 and the rotation is 0 degrees, the display size will indicate 1024x768. When the display rotation is set to 90 degrees, the display size will become 768x1024. (SCREEN_PROPERTY_SIZE can only be retrieved and not set for a display object)
• event: A pair of integers that define the width and height, in pixels, of the touch or contact area. This is only applicable for the following events:
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_RELEASE
• session: A pair of integers that define the width and height, in pixels, of the input region. The dimensions are expressed in buffer coordinates if the session is associated with a window. Otherwise, the size is in display coordinates. When retrieving or setting this property type, esnure that you have sufficient storage for two integers.
• window: A pair of integers that define the width and height, in pixels, of the window. When retrieving this property type, ensure that you have sufficient storage for two integers. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
  • window-size = [width] x [height]

SCREEN_PROPERTY_SOURCE_POSITION

A pair of integers that define the x-and y- position of a source viewport within the window buffers.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers. The following API objects have this property, each with its own variant of this defnition:

• event: This is only applicable for the following events:
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_RELEASE
  • SCREEN_EVENT_POINTER
• window: The x and y coordinates of the top left corner of a rectangular region within the window buffer representing the source viewport of the window. This is the portion of the window buffer that is to be displayed. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
  • source-position = [x-position], [y-position]

SCREEN_PROPERTY_SOURCE_SIZE

A pair of integers that define the width and height, pixels, of a source viewport within the window buffers.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers. The following API objects have this property, each with its own variant of this definition:

• event: This is only applicable for the following events:
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_RELEASE
• window: The width and height of a rectangular region within the window buffer representing the source viewport of the window. This is the portion of the window buffer that is to be displayed. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
  • source-size = [width] x [height]

SCREEN_PROPERTY_STRIDE

A single integer that indicates the number of bytes between the same pixels on adjacent rows; a property of a buffer object.

When retrieving or setting this property type, ensure that you provide sufficient storage for one integer.

SCREEN_PROPERTY_SWAP_INTERVAL

A single integer that specifies the minimum number of vsync periods between posts; a property of a window object, When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• interval = [swap interval]

SCREEN_PROPERTY_TRANSPARENCY

A single integer that defines the transparency type of an API object.

The following API objects have this property, each with its own variant of this definition:

• display: How multiple layers are combined. The transparencies that are applicable to a display object are:
  • SCREEN_TRANSPARENCY_SOURCE_COLOR
  • SCREEN_TRANSPARENCY_SOURCE_OVER
  When retrieving this property type for a display object, ensure that you have sufficient storage for one integer.
• window How the alpha channel of the window is used to combine a window with other windows or the background color underneath it. Although the window transparency property can be set, the actual transparency applied is dependent on hardware. If the hardware supports it, the transparency specified by this property will be applied, otherwise a best effort algorithm will be used to apply the window transparency. Transparency must be of the type Screen transparency types. When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_TYPE

A single integer that indicates the type of the specified buffer object.

When retrieving this property type, ensure that you provide sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• device: The type of input device. Valid input device types are:
  • SCREEN_EVENT_GAMEPAD
  • SCREEN_EVENT_JOG
  • SCREEN_EVENT_JOYSTICK
  • SCREEN_EVENT_KEYBOARD
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_POINTER
• display: The type of display port. Valid display ports must be of type Screen display types.
• event: The type of event. Valid event types must be of type Screen event types.
• session: The type of input session. Valid session types must be of type
  • SCREEN_EVENT_POINTER
  • SCREEN_EVENT_KEYBOARD
  • SCREEN_EVENT_GAMEPAD
  • SCREEN_EVENT_JOYSTICK
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_JOG
• window: The type of window. Valid window types must be of type Screen window types.

SCREEN_PROPERTY_USAGE

A single integer that is a bitmask indicating the intended usage for the buffers associated with the API object.

The default usage for a buffer is SCREEN_USAGE_READ|SCREEN_USAGE_WRITE. SCREEN_PROPERTY_USAGE must be a combination of type Screen usage flag types. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. Note that changing SCREEN_PROPERTY_USAGE affects the pipeline when the overlay usage bit (SCREEN_USAGE_OVERLAY) is added or removed. The following API objects have this property, and share the same definition:

• pixmap
• window
  • In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to this value. The following are valid usage flags and their implications that you can use to set this property in graphics.conf:
    • sw (read or write)
    • gles1 (OpenGL 1.X)
    • gles2 (OpenGL 2.X)
    • gles3 (OpenGL 3.X)
    • vg (OpenVG)
    • native (native API operations such as blits or fills)
    • rotation (re-configure orientation without re-allocation)
  • The following is the usage for setting this property in graphics.conf:
    • usage = [usage flag1, usage flag2, ... ]
    • e.g., usage = sw, gles1

SCREEN_PROPERTY_USER_DATA

Four integers containing data associated with the user; a property of an event object.

SCREEN_PROPERTY_USER_DATA can be queried or set in association with an event of type SCREEN_EVENT_USER. When retrieving or setting this property type, ensure that you have sufficient storage for four integers.

SCREEN_PROPERTY_USER_HANDLE

A handle that is passed to the application window when events are associated with the window; a handle to an object to associate the API object with user data.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer. The following API objects have this property, and share this same definition:

• device
• group
• window

SCREEN_PROPERTY_VISIBLE

A single integer that specifies whether an API object is visible or active.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property and share this same definition:

• session
• window: In the configuration file, , the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following are valid settings that can be used for this property in graphics.conf:
  • visible = true
  • visible = false

SCREEN_PROPERTY_WINDOW

A pointer to a window.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer. The following API objects have this property, each with its own variant of this definition:

• device The window on which the input device is focused. All input from the device will be directed to this particular window.
• event (SCREEN_PROPERTY_WINDOW can only be retrieved and not set for an event object)For the following events, SCREEN_PROPERTY_WINDOW refers to the window associated with the event:
  • SCREEN_EVENT_CREATE
  • SCREEN_EVENT_POST
  • SCREEN_EVENT_CLOSE
  • SCREEN_EVENT_UNREALIZE
  For the following events, SCREEN_PROPERTY_WINDOW refers to the window associated with the input device for which the event is intended:
  • SCREEN_EVENT_GAMEPAD
  • SCREEN_EVENT_JOYSTICK
  • SCREEN_EVENT_KEYBOARD
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_RELEASE
  • SCREEN_EVENT_POINTER
  For the following event, SCREEN_PROPERTY_WINDOW refers to the window whose property is being set:
  • SCREEN_EVENT_PROPERTY
• session: The window on which the input session is focused.

SCREEN_PROPERTY_RENDER_BUFFER_COUNT

A single integer that indicates he number of render buffers associated with the window; a property of a window object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_ZORDER

A single integer that indicates the distance from the bottom that is used when ordering API objects amongst each other.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property and share this same definition:

• session A window can have multiple input sessions. When regions of these multiple sessions overlap, this property is used to determine which session is on top. The session whose SCREEN_PROPERTY_ZORDER is the highest will be the the session that receives the input event.
• window: Indicates the distance from the bottom that is used when ordering window groups amongst each other. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:
  • order = [zorder]

SCREEN_PROPERTY_PHYSICAL_ADDRESS

A single long long integer that corresponds to the physical address of the buffer; a property of a buffer object.

This property is only valid when the buffer is physically contiguous. When retrieving or setting this property type, ensure that you provide sufficient storage for one long integer.

SCREEN_PROPERTY_SCALE_QUALITY

A single integer that indicates the amount of filtering performed by the windowing system when scaling is required to draw the window; a property of a window object.

The scale quality must be of type Screen scale quality types. When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_SENSITIVITY

A single integer that indicates the API object input behavior.

The sensitivity must be of type Screen sensitivity types or an integer that is a bitmask combination of Screen sensitivity masks. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property and share this same definition:

• session
• window

SCREEN_PROPERTY_MIRROR_MODE

A single integer that defines whether or not the display is currently in mirror mode.

Mirror mode indicates that the internal and external displays display the same signal. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, and share this same definition:

• display
• event (Applicable only to a SCREEN_EVENT_DISPLAY event)

SCREEN_PROPERTY_DISPLAY_COUNT

A single integer containing the number of displays associated with this context; a property of a context object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_DISPLAYS

An array of display pointers; a property of a context object.

When retrieving this property type, ensure that you have sufficient storage for one void pointer for each display. Retrieve the SCREEN_PROPERTY_DISPLAY_COUNT property to find out how many displays are associated with this context; Once you know the number of displays, you can allocate sufficient storage to retrieve SCREEN_PROPERTY_DISPLAYS.

SCREEN_PROPERTY_CBABC_MODE

A single integer that indicates what the window content is; a property of a window object.

The content mode must be of type Screen content mode types. When getting or setting this property type, ensure that you have sufficient storage for one integer. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following are valid settings that can be used for this property in graphics.conf:

• cbabc = none
• cbabc = video
• cbabc = ui
• cbabc = photo

SCREEN_PROPERTY_FLOATING

A single integer that indicates whether or not the window is a floating window; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_ATTACHED

A single integer that indicates whether or not the display is currently attached.

When retrieving or setting this property type, ensure you have sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• display: Indicates whether or not the display is connected. Display objects may exist in a context, but are not considered connected until they are attached.
• event:
  • In the case of the SCREEN_EVENT_DISPLAY event, this indicates that a display has changed its state; the display has either connected or disconnected.
  • In the case of the SCREEN_EVENT_DEVICE event, this indicates that either a new device has been created and is now conntected, or that a device has disconnected and been deleted. Unlike displays, device objects only exist in a context if they are attached. (SCREEN_PROPERTY_ATTACHED can only be retrieved and not set for device event.)

SCREEN_PROPERTY_DETACHABLE

A single integer that indicates whether or not the display can be detached; a property of a display object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_NATIVE_RESOLUTION

A pair of integers that define the width and height of the native video resolution; a property of a display object.

When retrieving this property type, ensure that you have sufficient storage for two integers.

SCREEN_PROPERTY_PROTECTION_ENABLE

A single integer that indicates whether or not content protection is enabled for the API object.

You require a secure link in order to have protection enabled. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• display: Indicates whether or not content protection is needed for the window(s) on the display. Content protection is considered enabled as long as one window on the display has its content protection enabled and its SCREEN_PROPERTY_VISIBLE property indicates that the window is visible. The SCREEN_PROPERTY_PROTECTION_ENABLE property of a display is dynamic; its value depends on the SCREEN_PROPERTY_PROTECTION_ENABLE property of the window(s) that are on the display. SCREEN_PROPERTY_PROTECTION_ENABLE can only be retrieved and not set for a display object.
• window: Indicates whether or not authentication is to be requested before the content of the window can be displayed. Authentication is requested when the window is posted and its SCREEN_PROPERTY_VISIBLE property indicates that the window is visible.
• event: (Applicable only to a SCREEN_EVENT_DISPLAY event) Indicates that a disabling of content protection is detected. This is likely due to the loss of a secure link to the display.

SCREEN_PROPERTY_SOURCE_CLIP_POSITION

A pair of integers that define the x- and y- position of a clipped source rectangular viewport within the window buffers; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers.

SCREEN_PROPERTY_PHYSICAL_SIZE

A pair of integers that define the width and height, in millimeters, of the display; a property of a display object.

When retrieving this property type, ensure that you have sufficient storage for two integers.

SCREEN_PROPERTY_FORMAT_COUNT

A single integer that indicates the number of formats that the display supports; a property of a display object.

When retrieving this property type, ensure that you have sufficient storage for at least one integer.

SCREEN_PROPERTY_FORMATS

An array of integers of size SCREEN_PROPERTY_FORMAT_COUNT that defines the formats supported by the display; a property of a display object.

If the display has many layers, the list is the union of all the formats supported on all layers. Formats are of type Screen pixel format types. When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_SOURCE_CLIP_SIZE

A pair of integers that define the width and height, in pixels, of a clipped source rectangular viewport within he window buffers; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers.

SCREEN_PROPERTY_TOUCH_ID

A single integer that indicates the multi-touch contact id associated with the specific event; a property of an event object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_VIEWPORT_POSITION

A pair of integers that define the x and y position of a rectangular region within the API object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers. The following API objects have this property, each with its own variant of this definition:

• display: The x and y coordinates of the top left corner of a rectangular region within the display that is intended to be mapped to and redrawn to the display. In order for you to access this display property, you need to be working within a privileged context.
• window: The x and y coordinates of the top left corner of a virtual viewport. The virtual viewport is typically used to achieve the effect of scrolling or panning a source whose size is larger than the size of your window buffer.

SCREEN_PROPERTY_VIEWPORT_SIZE

A pair of integers that define the width and height of a rectangular region within the API object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers. The following API objects have this property, each with its own variant of this definition:

• display: The width and height, in pixels, of a rectangular region within the display that is intended to be mapped to and redrawn to the display. In order for you to access this display property, you need to be working within a privileged context.
• window: The width and height, in pixels, of a virtual viewport. The virtual viewport is typically used to achieve the effect of scrolling or panning a source whose size is larger than the size of your window buffer.

SCREEN_PROPERTY_TOUCH_ORIENTATION

A single integer that indicates the multi-touch orientation associated with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. This property is only applicable for the following events:

• SCREEN_EVENT_MTOUCH_PRETOUCH
• SCREEN_EVENT_MTOUCH_TOUCH
• SCREEN_EVENT_MTOUCH_MOVE
• SCREEN_EVENT_MTOUCH_RELEASE

SCREEN_PROPERTY_TOUCH_PRESSURE

A single integer that indicates the multi-touch pressure associated with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you have sufficient storage or one integer. This property is only applicable for the following events: events:

• SCREEN_EVENT_MTOUCH_PRETOUCH
• SCREEN_EVENT_MTOUCH_TOUCH
• SCREEN_EVENT_MTOUCH_MOVE
• SCREEN_EVENT_MTOUCH_RELEASE

SCREEN_PROPERTY_TIMESTAMP

A single long long integer that indicates a timestamp associated with the API object.

When retrieving or setting this property type, ensure that you have sufficient storage for one long long integer. It is important to note that screen uses the realtime clock and not the monotonic clock when calculating the timestamp. The following API objects have this property, each with its own variant of this definition:

• event: The timestamp at which the event was received by Screen (SCREEN_PROPERTY_TIMESTAMP can only be retrieved and not set for an event object).
• window: The timestamp to indicate the start of a frame. This timestamp can be used by the application to measure the elapsed time taken to perform functions of interest. For example, the application can measure the time between when the timestamap is set and when the window is posted (e.g., when OpenGL swap buffers). This timestamp allows for the application to track CPU time. The application can set the timestamp to any specific time. Then, the application uses the screen_get_window_property_llv() function to retrieve the SCREEN_PROPERTY_METRICS property of the window to look at the timestamp for comparison to the set timestamp.

SCREEN_PROPERTY_SEQUENCE_ID

A single integer that is associated with the specific API object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• event: The multi-touch sequence ID associated with the event. This property is only applicable for the following events:
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_RELEASE
  • SCREEN_EVENT_KEYBOARD
• session The unique identifier used by Screen to track, in sequence, when a session of a specific type was created. This identifier is not to be confused with SCREEN_PROPERTY_ID which is an identifier that can be used by applications to identify specific API objects.
• window The unique identifier used by Screen to track, in sequence, when a session of a specific type was created. This identifier is not to be confused with SCREEN_PROPERTY_ID which is an identifier that can be used by applications to identify specific API objects.

SCREEN_PROPERTY_IDLE_MODE

A single integer indicating the idle mode of the window; a property of a window object.

The idle mode must be of type Screen idle mode types. When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_IDLE_STATE

A single integer that indicates the idle state of the API object.

The idle state will be 1 if the system is idle, indicating that no input was received after the idle timeout period (SCREEN_PROPERTY_IDLE_TIMEOUT). The idle state will be 0, if an input event was received prior to the idle timeout period expiring. When retrieving this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, each sharing a similiar definition:

• device: The idle state that is applicable to the entire device.
• display: The idle state that is applicable to the entire display.
• event (Applicable only to a SCREEN_EVENT_IDLE event): Indicates that an idle state change has taken place for either a display or group object. Query the SCREEN_PROPERTY_OBJECT_TYPE property of the event to determine the object type of this event.
• group : The idle state that is applicable to only the group. A group is considered in idle state if none of the windows that are part of the group have received input after the idle timeout period for the group.

SCREEN_PROPERTY_KEEP_AWAKES

A single integer that indicates the number of windows with an idle mode of type SCREEN_IDLE_MODE_KEEP_AWAKE that are visible on a display; a property of a display object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_IDLE_TIMEOUT

A single long long integer that indicates the amount of time, in seconds, after which the system will enter an idle state.

When retrieving or setting this property type, ensure that you have sufficient storage for one long long integer. The following API objects have this property, each sharing a similar definition:

• context: The amount of time after which the display of the context will enter an idle state.
• device: The amount of time after which the device will enter an idle state.
• display: The amount of time after which the display will enter an idle state.
• group: The amount of time after which the group will enter in an idle state.

SCREEN_PROPERTY_FOCUS

A handle which corresponds to the object that currently has keyboard focus.

When retrieving or setting this property type, ensure that you have sufficient storage according to the definition of the property for the specific API object. The following API objects have this property, each with its own variant of this definition:

• context: A handle to the top-level window (application window) on the display that currently has the keyboard focus.
• display: A handle to the top-level window (application window) on the display that currently has the keyboard focus.
• group: A handle to the immediate window in the group that currently has the keyboard focus. You must be the owner of the group, screen_group_t, to be able to set this property.
• session: A handle to the input session that currently has keyboard focus.
• window: A single integer that indicates whether or not the window currently has the keyboard focus. (SCREEN_PROPERTY_KEYBOARD_FOCUS can only be retrieved and not set for a window object)

SCREEN_PROPERTY_KEYBOARD_FOCUS

Deprecated:

This property has been deprecated.

Use SCREEN_PROPERTY_FOCUS instead.

SCREEN_PROPERTY_MTOUCH_FOCUS

A handle or an indicator which corresponds to the API object that currently has mtouch focus.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer. The following API objects have this property, each with its own variant of this definition:

• context: A handle to the top-level window (application window) on the display that currently has the mtouch focus.
• display: A handle to the top-level window (application window) on the display that currently has the mtouch focus.
• group: A handle to the immediate window in the group that currently has the mtouch focus. You must be the owner of the group, screen_group_t, to be able to set this property.
• session: An integer (0 or 1) to indicate whether the input session currently has the mtouch focus (e.g., 0 = does not have focus and 1 = has focus)

SCREEN_PROPERTY_POINTER_FOCUS

A handle which corresponds to the API object that currently has pointer focus.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer. The following API objects have this property, each with its own variant of this definition:

• context: A handle to the top-level window (application window) on the display that currently has the pointer focus.
• display: A handle to the top-level window (application window) on the display that currently has the pointer focus.
• group: A handle to the immediate window in the group that currently has the pointer focus. You must be the owner of the group, screen_group_t, to be able to set this property.
• session: A handle to the input session that currently has the mtouch focus.

SCREEN_PROPERTY_ID

A single integer that indicates the identification of the API object.

When retrieving this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, and share this same definition:

• device
• display
• group
• pixmap
• session
• window

SCREEN_PROPERTY_POWER_MODE

A single integer that defines the power mode.

Power modes must be of type Screen power mode types. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, and share this same definition:

• device
• display

SCREEN_PROPERTY_MODE_COUNT

A single integer that indicates the number of modes supported by the display; a property of display object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_MODE

A pointer to a structure of type screen_display_mode_t whose content is based on the current video mode.

When retrieving or setting this property type, ensure that you have sufficient storage for screen_display_mode_t for each mode. Retrieve the SCREEN_PROPERTY_MODE_COUNT property to find out how many modes are supported by this display; Once you know the number of displays, you can allocate sufficient storage to retrieve SCREEN_PROPERTY_MODE. When setting this property type, you can pass SCREEN_MODE_PREFERRED_INDEX to fall back to the default video mode without having to first query all the modes supported by the display to find the one with SCREEN_MODE_PREFERRED set in flags of screen_display_mode_t. The following API objects have this property, and share this same definition:

• display
• event (Applicable only to a SCREEN_EVENT_DISPLAY event)
• session

SCREEN_PROPERTY_CLIP_POSITION

A pair of integers that define the x- and y- position of a clipped rectangular viewport within the window buffers; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• clip-position = [x-position], [y-position]

SCREEN_PROPERTY_CLIP_SIZE

A pair of integers that define the width and height , in pixels, of a clipped rectangular viewport within the window buffers; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• clip-size = [width] x [height]

SCREEN_PROPERTY_COLOR

A single integer that indicates the background color of the window; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. In the configuration file, graphics.conf, the value of this property can be set so that windows of a specified class will have this property initialized to the value. The following is the usage for setting this property in graphics.conf:

• color = [window background color]

SCREEN_PROPERTY_MOUSE_WHEEL

A single integer that indicates the pointer wheel associated with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. This property is only applicable for a SCREEN_EVENT_POINTER event.

SCREEN_PROPERTY_CONTEXT

A pointer to the context associated with the API object.

When retrieving this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, and share this same definition:

• device
• display
• event
• group
• pixmap
• session
• window

SCREEN_PROPERTY_DEBUG

A single integer that enables an on-screen plot or a list of window statistics as a debugging aid; a property of a window object.

The debug type must be a bitmask that represents a combination of the types Screen debug graph types. When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_ALTERNATE

A handle to an alternate screen object.

When retrieving or setting this property type, ensure that you have sufficient storage for a void pointer. The following API objects have this property, each with its own variant of this definition:

• window
• session

SCREEN_PROPERTY_ALTERNATE_WINDOW

See SCREEN_PROPERTY_ALTERNATE.

SCREEN_PROPERTY_DEVICE_COUNT

A single integer containing the number of devices associated with this object.

When retrieving this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• context: The number of display devices associated with this context.
• session: The number of input devices associated with this session.

SCREEN_PROPERTY_BUFFER_POOL

Deprecated:

This property has been deprecated.

Do not use.

SCREEN_PROPERTY_OBJECT_TYPE

A single integer that indicates the object type associated the with the specific event; a property of an event object.

When retrieving this property type, ensure that you have sufficient storage for one integer. Object types must be of type Screen object types. This property is only applicable for a SCREEN_EVENT_PROPERTY event.

SCREEN_PROPERTY_DEVICES

An array of device pointers.

When retrieving this property type, ensure that you have sufficient storage for one void pointer for each device. Retrieve the SCREEN_PROPERTY_DEVICE_COUNT property to find out how many devices are associated with this API object. Once you know the number of devices, you can allocate sufficient storage to retrieve SCREEN_PROPERTY_DEVICES. The following API objects have this property and share this same definition:

• context
• session

SCREEN_PROPERTY_GROUP_COUNT

A single integer containing the number of groups associated with this context a property of a context object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_GROUPS

An array of group pointers; a property of a context object.

When retrieving this property type, ensure that you have sufficient storage for one void pointer for each group. Retrieve the SCREEN_PROPERTY_GROUP_COUNT property to get the number of groups that are associated with this context; once you know the number of groups, you can allocate sufficient storage to retrieve SCREEN_PROPERTY_GROUPS.

SCREEN_PROPERTY_PIXMAP_COUNT

A single integer containing the number of pixmaps associated with this context; a property of a context object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_PIXMAPS

An array of pixmap pointers; a property of a context object.

When retrieving this property type, ensure that you have sufficient storage for one void pointer for each pixmap. Retrieve the SCREEN_PROPERTY_PIXMAP_COUNT property to find out how many pixmaps are associated with this context; Once you know the number of pixmaps, you can allocate sufficient storage to retrieve SCREEN_PROPERTY_PIXMAPS.

SCREEN_PROPERTY_WINDOW_COUNT

A single integer containing the number of windows associated with this context; a property of a context object.

When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_WINDOWS

An array of window pointers; a property of a context object.

When retrieving this property type, ensure that you have sufficient storage for one void pointer for each window. Retrieve the SCREEN_PROPERTY_WINDOW_COUNT property to find out how many windows are associated with this context; Once you know the number of windows, you can allocate sufficient storage to retrieve SCREEN_PROPERTY_WINDOWS.

SCREEN_PROPERTY_KEYMAP

A character string specifying a keymap.

When retrieving or setting this property type, ensure that you provide a character buffer. The following API objects have this property, each with its own variant of the definition:

• context: The default keymap. Unless specifically assigned, this keymap is applied to all input devices.
• device: The keymap that is assigned to the specified input device. The keymap is only applicable to that device and is not persistent. For example, if the input device is removed and then replaced, the default keymap will be applied to it until a keymap is specifically set for the input device again.

SCREEN_PROPERTY_MOUSE_HORIZONTAL_WHEEL

A single integer that indicates the mouse horizontal wheel associated the with the specific event.

a property of an event object. When retrieving or setting this property type, ensure that you have sufficient storage for one integer. This property is only applicable for a SCREEN_EVENT_POINTER event.

SCREEN_PROPERTY_TOUCH_TYPE

A single integer that indicates the touch associated the with the specific event; a property of an event object.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. Touch types must be of type Screen touch types. This property is only applicable for the following events:

• SCREEN_EVENT_MTOUCH_PRETOUCH
• SCREEN_EVENT_MTOUCH_TOUCH
• SCREEN_EVENT_MTOUCH_MOVE
• SCREEN_EVENT_MTOUCH_RELEASE

SCREEN_PROPERTY_NATIVE_IMAGE

A pointer to the image; a property of a buffer object.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer.

SCREEN_PROPERTY_SCALE_FACTOR

A single integer that indicates the number of bits of the desired sub-pixel precision.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property:

• event: The default value is 0.
• window: The default value is 16. Note that setting this property, SCREEN_PROPERTY_SCALE_FACTOR, prior to retrieving SCREEN_PROPERTY_TRANSFORM will affect the values for the transformation matrix.

SCREEN_PROPERTY_DPI

A pair of integers which represent the dpi measurement; a property of a display object.

The dpi is calculated from the physical dimensions and resolution of the display. When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_METRIC_COUNT

A single integer that indicates the number of metrics associated with an API object.

Note that the actual value of the number of metrics may vary between API objects. When retrieving this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, and share this same definition:

• device
• display
• pixmap
• window

SCREEN_PROPERTY_METRICS

A array of metrics associated with an API object.

Note that the size of the array of metrics may vary between API objects. When retrieving this property type, ensure that you have sufficient storage for one void pointer for each metric. Retrieve the SCREEN_PROPERTY_METRIC_COUNT property to find out how many metrics are associated with the API object; once you know the number of metrics, you can allocate sufficient storage to retrieve SCREEN_PROPERTY_METRICS. The following API objects have this property, and share this same definition:

• device
• display
• pixmap
• session
• window

SCREEN_PROPERTY_BUTTON_COUNT

A single integer that indicates the number of buttons on the input device; a property of a device object.

You can set this property on input devices you create. In the case of mtouch, this property refers to the number of buttons on the stylus, not necessarily the touch points. All users can query the value on the created device. When retrieving or setting this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_VENDOR

A string that can be used to identify the vendor of the specified API object.

When retrieving or setting this property type, ensure that you provide a character buffer. The following API objects have his property, and share this same definition:

• device
• display

SCREEN_PROPERTY_PRODUCT

A string that can be used to identify the product name of the specified API object.

When retrieving or setting this property type, ensure that you provide a character buffer. The following API objects have his property, and share this same definition:

• device
• display

SCREEN_PROPERTY_BRUSH_CLIP_POSITION

A pair of integers that define the x- and y- position of a clipped rectangular area within the window buffers where brush strokes are allowed to be drawn; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers.

SCREEN_PROPERTY_BRUSH_CLIP_SIZE

A pair of integers that define the width and height, in pixels, of a clipped rectangular area within the window buffers where brush strokes are allowed to be drawn; a property of a window object.

When retrieving or setting this property type, ensure that you have sufficient storage for two integers.

SCREEN_PROPERTY_ANALOG0

The x, y and z values for one analog controller; a property of an event object.

For analog controllers that do not have three degrees of freedom, only x and y values are valid; z will have a value of 0. Regardless of two or three degress of freedom of your analog controller(s), when retrieving or setting this property type, ensure that you have sufficient storage for three integers. This property is only applicable for the following events:

• SCREEN_EVENT_GAMEPAD:
• SCREEN_EVENT_JOYSTICK:

SCREEN_PROPERTY_ANALOG1

The rx, ry, and rz values for a second analog controller for the SCREEN_EVENT_GAMEPAD event.

For analog controllers that do not have three degrees of freedom, only x and y values are valid; z will have a value of 0. Regardless of two or three degress of freedom of your analog controller(s), when retrieving or setting this property type, ensure that you have sufficient storage for three integers.

SCREEN_PROPERTY_BRUSH

The pixmap that contains the brush to be used when the window property, SCREEN_PROPERTY_SENSITIVITY, has a brush bit set and the corresponding type of input event is delivered to the API object.

The sensitivity values that can be set to enable brush drawing in your sensitivity mask are:

• SCREEN_SENSITIVITY_MASK_POINTER_BRUSH for a mouse
• SCREEN_SENSITIVITY_MASK_FINGER_BRUSH for touch
• SCREEN_SENSITIVITY_MASK_STYLUS_BRUSH for a stylus

The pixmap can use an RGB color format for color information. The alpha channel can be used to define the brush shape. The pixmap buffer size will determine the size of the brush. No drawing will occur if the window has a brush sensitivity bit set and no brush pixmap.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer. The following API objects have this property and share this same definition:

• session
• window

SCREEN_PROPERTY_MAXIMUM_TOUCH_ID

A single integer that indicates the index of the highest possible touch ID; a property of a device object.

This property can be queried only from an input device that supports mtouch, i.e., a device of type SCREEN_EVENT_MTOUCH_TOUCH. When retrieving this property type, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_TRANSFORM

A set of integers that represent the 3x3 transformation matrix used to convert buffer or device coordinates to display coordinates.

The transformation matrix is stored in row-major order. This property is typically used when you have a known coordinate and need to know where it would be located on the display screen. Screen creates a vector V=(X, Y, 1.0) from the raw coordinates, (X, Y). Then, Screen multiplies the transformation matrix T with this vector (T x V) to achieve a resultant vector of (Xa, Ya, Wa). This resultant vector is then divided by Wa to result in (Xab, Yab, 1.0), which provides (Xab, Yab) as the transformed display coordinates. When retrieving this property, ensure that you have sufficient storage for 9 integers. When you set the SCREEN_PROPERTY_SCALE_FACTOR property of a window or device prior to retrieving this property, you affect the values of this transformation matrix. The following API objects have this property, and share this same definition:

• device (input devices of type SCREEN_EVENT_MTOUCH_TOUCH) When setting this property, the last row of the transformation matrix must be [0, 0, non-zero].
• window (SCREEN_PROPERTY_TRANSFORM can only be retrieved and not set for a window object)

SCREEN_PROPERTY_KEY_ALTERNATE_SYM

A single integer that provides an alternate key symbol associated to the event; a property of an event object.

On reduced keyboards with a limited number of keys, the alternate key symbol may correspond to a non-printable shortcut or command symbol while the main key symbol would be suitable for text entry. The alternate key symbol may be identical to the primary key symbol. When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. SCREEN_PROPERTY_KEY_ALTERNATE_SYM is applicable only to a SCREEN_EVENT_KEYBOARD event.

SCREEN_PROPERTY_TECHNOLOGY

An integer that is used to identify the technology used by a particular object handle; a property of a display object.

When retrieving this property type, ensure that you provide enough storage for one integer.

SCREEN_PROPERTY_PERMISSIONS

A single integer bitmask indicating the permissions associated with an API object.

SCREEN_PROPERTY_PERMISSIONS must be a combination of type Screen permission masks. In order to set SCREEN_PROPERTY_PERMISSIONS, you must be the owner of the API object. You can set this property at any time. Similar to setting file permissions with chmod (Change file modes in POSIX), if you want someone to have special access to the API object, you need to set the appropriate permissions on that API object. Screen permissions give you control over who has access to what. When retrieving or setting this property type, ensure that you provide sufficient storage for one integer. The following API objects have this property and share this same definition:

• window
• session

SCREEN_PROPERTY_STICKY_MODIFIERS

A single integer bitmask indicating which modifiers associated with a device should have a sticky behavior; a property of a device object.

A sticky modifier turns on its corresponding locked modifier automatically, which then gets cleared on the key press, key release sequence immediately following. When multiple modifiers are set to be sticky, they can be compounded, allowing <Shift Down>, <Shift Up>, <Alt Down>, <Alt Up>, <A> to produce the same results as <Shift Down>, <Alt Down>, <A>, <Shift Up>, <Alt Up>. When retrieving or setting this property type, ensure that you provide sufficient storage for one integer.

SCREEN_PROPERTY_INTENSITY

A single integer between [-1..100000] that controls the brightness of a display on those displays that allow its brightness to be controlled; a property of a display object.

The default value of -1 implies that Screen will automatically set the display intensity based on ambient lighting. When retrieving or setting this property type, ensure that you provide sufficient storage for one integer.

SCREEN_PROPERTY_DRIVER_CONTROL

A pair of integers that can be communicated to the driver owning a particular resource.

When retrieving or setting this property type, ensure that you provide sufficient storage for two integers. The following API objects may support driver controls:

• display
• device Consult your driver documentation to see what driver controls are available and the specific usage semantics.

SCREEN_PROPERTY_DELAY

A single long long integer that controls the device delay in nanoseconds; a property of a device object.

A value of zero will cancel the current delay if one is set and flush any delayed events. A value greater than zero will set the delay or reset an active delay to the specified value. The delay is relative to the actual time of the from when the property was set in Screen. Ensure that SCREEN_PROPERTY_BUFFER_COUNT is set before using this property. When retrieving or setting this property type, ensure that you provide sufficient storage for one integer.

SCREEN_PROPERTY_SESSION

A pointer to a session.

When retrieving or setting this property type, ensure that you have sufficient storage for one void pointer. The following API objects have this property, each with its own variant of this definition:

• device The session on which the input device is focused. All input from the device will be directed to this particular session.
• event For the following events, SCREEN_PROPERTY_SESSION refers to the session associated with the event:
  • SCREEN_EVENT_CREATE
  • SCREEN_EVENT_CLOSE
  For the following events, SCREEN_PROPERTY_SESSION refers to the session associated with the input for which the event is intended:
  • SCREEN_EVENT_GESTURE
  • SCREEN_EVENT_INPUT
  • SCREEN_EVENT_JOG
  • SCREEN_EVENT_POINTER
  • SCREEN_EVENT_KEYBOARD
  • SCREEN_EVENT_GAMEPAD
  • SCREEN_EVENT_JOYSTICK
  • SCREEN_EVENT_MTOUCH_PRETOUCH
  • SCREEN_EVENT_MTOUCH_TOUCH
  • SCREEN_EVENT_MTOUCH_MOVE
  • SCREEN_EVENT_MTOUCH_RELEASE
  For the following event, SCREEN_PROPERTY_SESSION refers to the session whose property is being set or retrieved:
  • SCREEN_EVENT_PROPERTY

SCREEN_PROPERTY_REFERENCE_COLOR

An integer that is a color to be used with the SCREEN_TRANSPARENCY_TEST, SCREEN_TRANSPARENCY_REVERSED_TEST and SCREEN_TRANSPARENCY_SOURCE_COLOR modes.

The following API objects have this property:

• window
• display

When the transparency mode is SCREEN_TRANSPARENCY_TEST or SCREEN_TRANSPARENCY_REVERSED_TEST, transparency is applied to each pixel based on a comparison with the reference color.

When the transparency mode is SCREEN_TRANSPARENCY_SOURCE_COLOR, transparency is applied to each pixel matching the reference color.

When retrieving or setting this property, ensure that you have sufficient storage for one integer. If this attribute is not specified, then a default of 0 will be used.

SCREEN_PROPERTY_GESTURE_RECOGNITION

An integer that determines whether gesture recognition is enabled on a given object.

The following types of objects support gesture recognition:

• device
• session When retrieving or setting this property, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_DURATION

A single long long integer that indicates a time duration, in nanoseconds; a property of an event object.

When retrieving or setting this property type, ensure that you have sufficient storage for one long long integer. This property is only applicable for the SCREEN_EVENT_GESTURE event.

SCREEN_PROPERTY_DISPLACEMENT

A pair of integers that define the x- and y- coordinates of events with relative displacement.

When retrieving or setting this property, ensure that you have sufficient storage for two integers. This property is only applicable for the following events:

• SCREEN_EVENT_GAMEPAD
• SCREEN_EVENT_GESTURE
• SCREEN_EVENT_JOG
• SCREEN_EVENT_JOYSTICK
• SCREEN_EVENT_POINTER

SCREEN_PROPERTY_SPEED

An integer that represents the speed of an input device; a property of a device object.

When retrieving or setting this property, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_ACCELERATION

Four integers that define the acceleration of an input device; a property of a device object.

The speed model is the following: displacement' = displacement * (1 + acceleration) * speed; where the acceleration is: acceleration = velocity * (constant0 + velocity * constant1). The first value corresponds to constant0, the linear factor. The second value corresponds to constant1, or the quadratic factor. The third and fourth values are minimum and maximum thresholds for the velocity. Any displacement with a velocity less than the minimum threshold will not be accelerated. Any displacement with a velocity greater than the maximum threshold will have its acceleration clamped to the acceleration corresponding to the maximum velocity threshold. When retrieving or setting this property, ensure that you have sufficient storage for one integer.

SCREEN_PROPERTY_BALLISTIC_COEFFICIENTS

A set of 16 integers that represent coefficients to configure ballistic filtering; a property of a device object.

Touch events pass through ballistic filtering to reduce jitter. The first 6 integers configure a digital filter while the remaining 10 integers are currently unused and are reserved for future filter configurations. When retrieving or setting this property, ensure that you have sufficient storage for 16 integers.

SCREEN_PROPERTY_TAB_POSITION

An integer specifying the tab position.

When retrieving or setting this property, ensure that you have sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• session
• window

SCREEN_PROPERTY_CURSOR

An integer specifying which cursor shape to display when the pointer is over a session.

When retrieving or setting this property type, ensure that you have sufficient storage for one integer. The following API objects have this property, each with its own variant of this definition:

• session

Library:

Description:

Full read/write access to Screen API object properties is product dependent.