Provides functionality to handle Window creation and management.
System-triggered OnScreenKeyboard events have ticket value kSbEventOnScreenKeyboardInvalidTicket.
Well-defined value for an invalid window handle.
A handle to a window.
typedef SbWindowPrivate* SbWindow
Options that can be requested at window creation time.
The requested size of the new window. The value of
video_pixel_ratiowill not be used or looked at.
Whether the new window should be windowed or not. If not, the requested size is really the requested resolution.
const char * name
The name of the window to create.
Defines a rectangle via a point
(x, y) and a size
(width, height). This
structure is used as output for SbWindowGetOnScreenKeyboardBoundingRect.
The size of a window in graphics rendering coordinates. The width and height of a window should correspond to the size of the graphics surface used for drawing that would be created to back that window.
The width of the window in graphics pixels.
The height of the window in graphics pixels.
The ratio of video pixels to graphics pixels. This ratio must be applied equally to width and height, meaning the aspect ratio is maintained.
A value of 1.0f means the video resolution is the same as the graphics resolution. This is the most common case.
Values greater than 1.0f mean that the video resolution is higher (denser, larger) than the graphics resolution. This is a common case as devices often have more video decoding capabilities than graphics rendering capabilities (or memory, etc...).
Values less than 1.0f mean that the maximum video resolution is smaller than the graphics resolution.
A value of 0.0f means the ratio could not be determined, it should be assumed to be the same as the graphics resolution (i.e. 1.0f).
Blur the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardBlurred.
kSbEventTypeOnScreenKeyboardBlurred has data
SbWindowBlurOnScreenKeyboard() when the keyboard is already blurred is
permitted. Calling SbWindowBlurOnScreenKeyboard while the on screen keyboard is
not showing does nothing and does not fire any event.
void SbWindowBlurOnScreenKeyboard(SbWindow window, int ticket)
Creates and returns a new system window with the given
options, which may be
NULL. The function returns
kSbWindowInvalid if it cannot create the
SbWindow due to policy, unsatisfiable options, or any other reason.
options are not specified, this function uses all defaults, which must work
on every platform. In general, it defaults to creating a fullscreen window at
the highest 16:9 resolution possible. If the platform does not support
fullscreen windows, then it creates a normal, windowed window.
Some devices are fullscreen-only, including many production targets for Starboard. In those cases, only one SbWindow may be created, and it must be fullscreen. Additionally, in those cases, the requested size will actually be the requested resolution.
An SbWindow must be created to receive window-based events, like input events, even on fullscreen-only devices. These events are dispatched to the Starboard entry point.
options: Options that specify parameters for the window being created.
SbWindow SbWindowCreate(const SbWindowOptions *options)
window, reclaiming associated resources.
SbWindow to destroy.
bool SbWindowDestroy(SbWindow window)
Focus the on screen keyboard. Fire kSbEventTypeOnScreenKeyboardFocused.
kSbEventTypeOnScreenKeyboardFocused has data
SbWindowFocusOnScreenKeyboard() when the keyboard is already focused is
permitted. Calling SbWindowFocusOnScreenKeyboard while the on screen keyboard is
not showing does nothing and does not fire any event.
void SbWindowFocusOnScreenKeyboard(SbWindow window, int ticket)
Gets the size of the diagonal between two opposing screen corners.
A return value of 0 means that starboard does not know what the screen diagonal is.
float SbWindowGetDiagonalSizeInInches(SbWindow window)
Get the rectangle of the on screen keyboard in screen pixel coordinates. Return
true if successful. Return
false if the on screen keyboard is not showing.
If the function returns
rect will not have been modified.
bool SbWindowGetOnScreenKeyboardBoundingRect(SbWindow window, SbWindowRect *bounding_rect)
Gets the platform-specific handle for
window, which can be passed as an
EGLNativeWindowType to initialize EGL/GLES. This return value is entirely
platform-specific, so there are no constraints about expected ranges.
window: The SbWindow to retrieve the platform handle for.
void* SbWindowGetPlatformHandle(SbWindow window)
Retrieves the dimensions of
window and sets
size accordingly. This function
true if it completes successfully. If the function returns
size will not have been modified.
window: The SbWindow to retrieve the size of.
size: The retrieved size.
bool SbWindowGetSize(SbWindow window, SbWindowSize *size)
Hide the on screen keyboard. Fire kSbEventTypeWindowSizeChange and
kSbEventTypeOnScreenKeyboardHidden if necessary.
kSbEventTypeOnScreenKeyboardHidden has data
SbWindowHideOnScreenKeyboard() when the keyboard is already hidden is permitted.
void SbWindowHideOnScreenKeyboard(SbWindow window, int ticket)
Determine if the on screen keyboard is shown.
bool SbWindowIsOnScreenKeyboardShown(SbWindow window)
Returns whether the given window handle is valid.
static bool SbWindowIsValid(SbWindow window)
Sets the default options for system windows.
options: The option values to use as default values. This object must not be
void SbWindowSetDefaultOptions(SbWindowOptions *options)
Notify the system that
keepFocus has been set for the OnScreenKeyboard.
keepFocus true indicates that the user may not navigate focus off of the
OnScreenKeyboard via input; focus may only be moved via events sent by the app.
keepFocus false indicates that the user may navigate focus off of the
OnScreenKeyboard via input.
keepFocus is initialized to false in the
void SbWindowSetOnScreenKeyboardKeepFocus(SbWindow window, bool keep_focus)
Show the on screen keyboard and populate the input with text
kSbEventTypeWindowSizeChange and kSbEventTypeOnScreenKeyboardShown if necessary.
kSbEventTypeOnScreenKeyboardShown has data
ticket. The passed in
will never be NULL, but may be an empty string. Calling
SbWindowShowOnScreenKeyboard() when the keyboard is already shown is permitted,
and the input will be replaced with
input_text. Showing the on screen keyboard
does not give it focus.
void SbWindowShowOnScreenKeyboard(SbWindow window, const char *input_text, int ticket)
Update the on-screen keyboard custom suggestions. Fire
kSbEventTypeOnScreenKeyboardSuggestionsUpdated has data
suggestions should remain up-to-date when the keyboard is shown after being
void SbWindowUpdateOnScreenKeyboardSuggestions(SbWindow window, const char *suggestions, int num_suggestions, int ticket)