WindowsUIFunctions

Windows UI interaction functions

wbc.bringToFront

• Description: Brings the UI to the front of the display, topmost in the z-order.
• Threading: Foreground/immediate
• Function: wbc.bringToFront()
• Arguments: none
• Returns:
  • OK
• Notes: None

wbc.showWindow

• Description: Shows or hides the entire application window
• Threading: Foreground/immediate
• Function: wbc.showWindow(doShow)
• Arguments:
  • doShow. If true, the window appears. If false, the window is hidden. If already in the desired state, no error is generated
• Returns:
  • OK/INVALID
• Notes: None

wbc.setskin

• Description: Uses an image to "Skin" the application window, allowing uneven window shapes with varying alpha levels.
• Threading:Foreground/immediate.
• Function: wbc.setSkin: function(fileSpec, leftMargin, topMargin, rightMargin, bottomMargin)
• Arguments:
  • fileSpec: File spec to jpg, bmp, or png (png recommended)
  • leftMargin, topMargin, rightMargin, bottomMargin. Optional arguments. Allow the html content window margins to be set at the same time as the skin is applied.
• Returns:
  • OK/ERROR/INVALID
• Notes:
  • The html content area must remain rectangular and within the smaller bounds of the skin.
  • If the html content area rectangle overlaps a transparent area, it will not be trimmed by this skin and cause undesired effects.
  • For optimum performance and memory usage, it is recommended that the window size is set to the image height and width before applying the skin.

wbc.setContentArea

• Description: Sets the size and position of the HTML content pane within the application window.
• Threading: Foreground/immediate
• Function: wbc.setContentArea: function(left, top, width, height, isAnchored)
• Arguments:
  • left: position from the left edge of the client area, in pixels.
  • top: position from the top edge of the client area, in pixels.
  • width: width of the content window
  • height: height of the content window
• isAnchored. If true, the four 'margins' will be remembered whenever the application window is resized, and the content window will resize so that the margins remain the same size.
• Returns:
  • OK: successful.
  • INVALID: invalid arguments.
• Notes: None

wbc.setCornerRadii

• Description: Allows each individual corner of the application window to be rounded by specifying the radius.
• Threading: Foreground/immedate.
• Function: wbc.setCornerRadii(topLeft, topRight, bottomLeft, bottomRight)
• Arguments:
  • topLeft: Radius of the top left corner.
  • topRight: Radius of the top right corner.
  • bottomLeft: Radius of the bottom left corner.
  • bottomRight: Radius of the bottom right corner.
• Returns:
  • OK/Invalid.
• Notes: None

wbc.resizeWindow

• Description: Changes the application's window height and width.
• Threading: Foreground/immediate.
• Function: wbc.resizeWindow(width, height)
• Arguments:
  • width: the required width in pixels
  • height: the required height in pixels.
• Returns:
  • OK -- valid parameters
  • INVALID -- invalid parameters
  • ERROR -- unable to resize
• Notes: None

wbc.animateWindow

• Description: Animates an unskinned Window's size, position, and transparency.
• Threading: Background threaded, with optional completion callback.
• Function: wbc.animateWindow(leftPos, topPos, width, height, transparency, duration, callback)
• Arguments:
  • leftPos: the desired x position of the window rectangle. Optional. If null, the x position will not change.
  • topPos: the desired y position of the window rectangle. Optional. If nulls, the y position will not change.
  • width: the desired width of the window rectangle. Optional. If null, the width will not change.
  • height: the desired height of the window rectangle. Optional. If null, the width will not change.
  • transparency: the desired transparency (float). 0 = opaque, 1 = fully transparent. Required.
  • duration: The number of milliseconds over which the animation will take place. Required.
  • callback: optional. This function will be called back when the animation finishes. The single callback function argument can be ignored.
• Returns:
  • OK -- parameters acceptable.
  • ERROR -- invalid parameters.
• Notes:
  • This function should not be used if setSkin/animateSkin has been used to first set a Window skin. It is designed only for a clean/unskinned window.

wbc.animateSkin

• Description: Smoothly transitions between one skin and another. Suitable for "slide out" effects associated with emulating a smartphone keyboard pull-out or similar.
• Threading: Background threaded.
• Function: wbc.animateSkin(newSkinFile, duration, isRightOrBottom, leftMargin, topMargin, rightMargin, bottomMargin, callback)
• Arguments:
  • newSkinFile: local path to new skin file. Use forward slashes or double/escaped backslashes.
  • duration: number of milliseconds desired for the duration of the animation.
  • isRightOrBottom: If true, the top/left position of the current skin will remain fixed. If false, the bottom/right position will remain anchored.
  • leftMargin, topMargin, rightMargin, bottomMargin: New margins (in pixels) for the innner content window.
  • callback: Optinoal. callback fired when skin animation complete.
• Returns:
  • OK.
  • ERROR. Invalid arguments or unable to locate newSkinFile.
    Notes:
  • The function transforms the currently selected skin into the new skin.
  • Before calling this function, the UI should be already skinned - by calling the setSkin function.
  • The function implements the 'sliding' effect. The new skin slides from behind the old skin (and back).
  • If optional margin parameters defined the content area is transformed also, otherwise - the content area remains static during the transformation.

wbc.getWindowRect

• Description: Returns size and position of application window, relative to desktop.
• Threading: Foreground/immediate return.
• Function: wbc.getWindowRect();
• Arguments: None
• Returns:
  • A rectangle object, with the following properties:
    • left - the X coordinate of the upper-left corner
  • top - the Y coordinate of the upper-left corner
  • right - the X coordinate of the lower-right corner
  • bottom - the Y coordinate of the lower-right corner
  • width - the Width of the rectangle
    • height - the Height of the rectangle
• Notes: None

wbc.getContentRect

• Description: Returns the size/postion of the HTML content window within the application window's client area.
• Threading: Foreground. Immediate.
• Function: wbc.getContentRect();
• Arguments: None
• Returns: A rectangle object, with the following properties:
  • left
  • top
  • right
  • bottom
  • width
  • height
• Notes: None

wbc.createMenu

• Description: Creates a pop-up menu outside of the DOM that can extend past the window bounds.
• Threading: Function returns immediately. Background threaded wait, with timeout and callbacks.
• Function: wbc.createMenu(xPos, yPos, menuArray, callback, callbackTimeout, timeoutSec, horizAlign, vertAlign)
• Arguments:
  • xPos: x-position, relative to the left-margin of the content area.
  • yPos: y-position, relative to the top-margin of the content area.
  • menuArray: An array of menu items. See notes below for full description.
  • callback: The function to call back if a menu item is clicked.
  • callbackTimeout: A bound function that is called back after the timeout has elapsed if no menu item is chosen.
  • timeout: Number of seconds to display the menu before it times out and automatically disappears.
  • horizAlign. Controls how the menu is positioned relative to xPos: "center" = centered. "left" = left aligned. "right" = right aligned. Default is "center"
  • vertAlign. Controls how the menu is positioned relative to yPos: "center" = centered. "top" = top aligned. "bottom" = bottom aligned. Default is "center"
• Returns:
  • OK if menu is displayed correctly
  • ERROR if arguments are invalid.
• Notes:
  • See the format for a menu array, below
• Menu Array
  • This should be an array (var menuItems = []) of menu Item objects.
  • Each menu item object can have the following properties.
    • menuItem.Text: The text to display
    • menuItem.Icon: Path to an icon (png, jpg, bmp, etc) image. Optional. If specified, icon will display to the left of the text.
    • menuItem.isSeparator . Boolean. Optional. If present and true, a horizontal line separator is drawn.
  • menuItem.isenabled. Boolean. Optional. If present and false, the menu item is shown in gray(disabled) text and will not trigger a menu click callback. If not present or true, the menu item will display normally and respond to clicks.

wbc.showDialog

• Description: Displays a standard windows dialog.
• Threading: Foreground or background wait for user interaction.
• Function: wbc.showDialog(text, title, options, callback)
• Arguments:
  • text: Text to display in the dialog. New lines can be included with the '\r\n' combination.
  • title: Text displayed in the dialog title.
  • options: Dialog options, as follows:
  • options.buttons. Optional. Can be one of 'OK' (default), 'OKCANCEL', 'ABORTRETRYIGNORE', 'YESNOCANCEL', 'YESNO', 'RETRYCANCEL', or 'CANCELTRYCONTINUE'. Button combination to be displayed.
  • options.icon. Optional (Default is none). Can be one of 'QUESTION', 'EXCLAMATION', 'ASTERISK', 'HAND', 'WARNING', 'ERROR', 'INFORMATION', or 'STOP'. Icon to be displayed.
  • options.defaultButton. Optional (Default is the first button). Can be 1,2,3, or 4. Indicates which button will have the focus when the window is first shown.
  • callback. The function to be called when the user responds to the dialog. Optional. If specified the function returns immediately and calls back later. If omitted, code execution is blocked until the user responds.
• Returns:
  • OK if dialog showable (valid arguments)
  • ERROR if arguments invalid.
• Notes:
  • When a button is clicked the callback is called with an evt object. This evt.result will contain one of the following responses, matching the button that was clicked:
  • "OK"
  • "YES"
  • "NO"
  • "CANCEL"
  • "ABORT"
  • "RETRY"
  • "IGNORE"
  • "CONTINUE"

wbc.browseForFile

• Description: Prompts the user to select one or more files or save a file, using the Windows 'browse for file' dialog.
• Threading: Foreground/Blocking
• Function: browseForFile(isSaveDialog, filters, title, initialDir, isMultiSelect)
• Arguments:
  • isSaveDialog: If true, the Open File dialog is shown. If false, the Save File dialog is shown.
  • title: The title of the dialog. Optional. If omitted, the default title is shown.
  • initialDir: The folder in which the dialog will initially browse.
  • isMultiSelect: If true, allows multiple selection of files. Ignored if isSaveDialog==true.
  • filters: An array of objects controlling the contents of the "files of type" filter combo. Each object should expose the following properties:
  • text: Description of the filter (eg "MS Word Documents")
  • filter: The Extension of the filter (eg. "docx")
  • isDefault: Optional. If set to true, this will be the filter selected by default.
• Returns:
  • If multi-select is true, and isSaveDialog is false, the return value is an array of strings, each containing a fileSpec of a selected file.
  • If saveDialog is true, the return value is a single string.
  • If the user cancels the action, the return value is null.
  • If an error occurs, the return value is "ERROR".
• Notes: None

wbc.browseForFolder

• Description: Prompts the user to select a folder, using the standard Windows "browse for folder" dialog.
• Threading: Foreground/blocking.
• Function: browseForFolder(title, initialFolder)
• Arguments:
  • title: The title of the browse dialog.
  • initialFolder: The location selected when the dialog first opens. If null, "c:\" will be used.
• Returns:
  • null if the user cancels the operation.
  • "ERROR" if invalid parameters are passed.
  • A string containing the folder spec if a folder is selected.
• Notes: None

wbc.trackMouse

• Description: Allows mouse tracking events to be logged to a file
• Threading: Immediate/Foreground
• Function: wbc.trackMouse(fileSpec, bufferLength)
• Arguments:
  • fileSpec: The log file location in which to save mouse events. Specify null or '' to turn off mouse tracking.
  • bufferLength: Number of events stored in memory before events are flushed to disk.
• Returns:
  • OK/ERROR/INVALID
    Notes:
  • Mouse tracking takes place when the application window when it is in the foreground, but not if the mouse moves outside the bounds,
  • Mouse tracking does not take place when the application is minimized or otherwise invisible.
  • When the number of tracked mouse events reaches the bufferLength value all accumulated events are flushed to disk (written to the file)
  • The format of the log file is the following:
  • Each line of the file represents a separate mouse event. The lines have the following format:
    • time:message;button-state;xPos,yPos
  • The log tokens have the following meaning:
  • time: the timestamp of the event (the number of milliseconds passed since 1970)
  • message: move message (event type). Can be one of the following:
    * "MOVE": mouse moved
    • "L_CLICK": mouse left-click event
    • "R_CLICK": mouse right-click event
    • "M_CLICK": mouse middle-click event
  • button-state: the state of mouse buttons at the moment of the event.
    • Can be any combination of the following flags: "L", "R" or "M" (left, right and middle buttons).
    • For example the value could be "LR" which means, that both left and right mouse buttons were pressed.
  • xPos - the X position of the mouse (position is relative to the upper-left corner of the WBC window)
  • yPos - the Y position of the mouse (position is relative to the upper-left corner of the WBC window)

wbc.followMouse

• Description: Allows the UI to be dragged around the desktop in response to a left-mouse-down event.
• Threading: Background thread controlled.
• Function: wbc.followMouse(doFollow, callback)
• Arguments:
  • doFollow. Boolean. true turns on mouse following, false turns it off.
  • callback. Optional. If specified, this function will be called back when following is automatically turned off (left mouse up).
• Returns:
  • OK -- valid arguments.
  • ERROR -- invalid arguments.
• Notes:
  • When the left-mouse-up event is dispatched, mouse following will automatically turned off.
  • If alternative behavior is required, an alternative to the followMouse function in wbc.js can be created.
  • The callback evt object will contain the following properties:
  • func: set to the internal function name 'uisdk_RegisterMouseClickCallback'
  • event: the mouse-click event description. Can be one of the following: "down", "up" or "doubleClick"
  • button: the mouse button. Can be one of the following values: "left", "right" or "middle"

wbc.setInputState

• Description: Freezes/unfreezes input on the current window so that a dialog can act modally.
• Threading: Foreground/immediate.
• Function: wbc.setInputState(isEnabled, transparency)
• Arguments:
  • isEnabled: if true, input becomes enabled. if false, input becomes disabled.
  • transparency: allows the window transparency to be set at the same time.
• Returns:
  • OK/Invalid
• Notes:
  • None

wbc.enableFrame

• Description: Enables or disables the window 'frame' around the client area.
• Threading: Foreground/immediate
• Function: wbc.enableFrame(doEnable)
• Arguments:
  • doEnable: true enables the frame (if not currently enabled) and false disables the frame.
• Returns:
  • OK/INVALID/ERROR
• Notes:
  • Has no effect on a skinned window.

wbc.listenForDesktopSizechange

• Description: Invokes a callback if the desktop size (screen width or height, or taskbar position) is changed.
• Threading: Background threaded
• Function: wbc.listenForDesktopSizechange(callback);
• Arguments:
  • callback: bound function to be called when the event is triggered.
• Returns:
  • OK/INVALID
• Notes:
  • The callback receive a single evt object, with the following properties:
    • func: the internal function name ('uisdk_RegisterDesktopChange')
  • width: the new width of the desktop window area
  • height: the new height of the desktop window area
  • bitsPerPixel: the new bit depth of the desktop window

wbc.watchSession

• Description: Invokes a callback if WTS_ session message events occur, such as logon, logoff, and fast user switching.
• Threading: Background threaded listener.
• Function: wbc.watchSession(callback)
• Arguments:
  • callback: a bound JavaScript function that receives a single object (evt)
• Returns:
  • OK.
• Notes:
  • The callback function receives a single evt object, with the following properties:
    • func: internal function name ('uisdk_RegisterSessionChange')
  • status: status code describing the reason the session state change notification was sent. This parameter can be one of the following values:
    • WTS_CONSOLE_CONNECT: A session was connected to the console session
    • WTS_CONSOLE_DISCONNECT: A session was disconnected from the console session
    • WTS_REMOTE_CONNECT: A session was connected to the remote session
    • WTS_REMOTE_DISCONNECT: A session was disconnected from the remote session
    • WTS_SESSION_LOGON: A user has logged on to the session
    • WTS_SESSION_LOGOFF: A user has logged off the session
    • WTS_SESSION_LOCK: A session has been locked
    • WTS_SESSION_UNLOCK: A session has been unlocked
  • sessionId: the ID of the current session

wbc.sendMessage

• Description: Sends a windows message to another window.
• Threading: Foreground/blocking.
• Function: wbc.sendMessage(hWnd, message, wParam, lParam)
• Arguments:
  • hWnd: Window handle of destination window
  • message: integer. Message to send.
  • wParam: integer or string. Message specific information.
  • lParam: integer or string. Message specific information.
• Returns:
  • OK: successful.
  • INVALID: invalid arguments.
• Notes:
  • This blocks foreground code execution, so this function should be carefully used.
  • The receiving message return value is not available, so there are few reasons to use this.
  • Unless the return value is absolutely needed, use wbc.postMesssage instead.

wbc.postMessage

• Description: Sends a windows message to another window without waiting for it to be processed.
• Threading: Foreground/non-blocking.
• Function: wbc.postMessage(hWnd, message, wParam, lParam)
• Arguments:
  • hWnd: Window handle of destination window
  • message: integer. Message to send.
  • wParam: integer or string. Message specific information.
  • lParam: integer or string. Message specific information.
• Returns:
  • OK: successful.
  • INVALID: invalid arguments.
• Notes:
  • Use this method instead of wbc.sendMessage wherever possible.