Module Utilities

Index

Variables

Modules

Enumerations

Interfaces

Functions

Variables

QueryCollection: QueryCollection

Represents the result of a query selector, and provides various operations that perform actions over the elements of the collection.

(n: number): T in Array<T>

Parameters

  • n: number

Returns

T in Array<T>

public length: number

Gets or sets the length of the array. This is a number one higher than the highest element defined in an array.

public addClass(name: string): QueryCollection

Adds the specified class to all the elements in the collection.

Parameters

  • name: string

    The name of the class to add.

Returns

QueryCollection

This QueryCollection object.

public children(element: HTMLElement): QueryCollection

Creates a QueryCollection that contains the children of the specified parent element.

Parameters

  • element: HTMLElement

    The parent element.

Returns

QueryCollection

The QueryCollection that contains the children of the element.

public clearStyle(name: string): QueryCollection

Clears the specified style property for all the elements in the collection.

Parameters

  • name: string

    The name of the style property to be cleared.

Returns

QueryCollection

This QueryCollection object.

public concat(items?: Array<U extends T[]>): Array<T>

Combines two or more arrays.

Parameters

  • items?: Array<U extends T[]> optional

    Additional items to add to the end of array1.

Returns

Array<T>

public concat(items?: Array<T>): Array<T>

Combines two or more arrays.

Parameters

  • items?: Array<T> optional

    Additional items to add to the end of array1.

Returns

Array<T>

public control(ctor: any, options?: any): QueryCollection

Creates controls that are attached to the elements in this QueryCollection, if the ctor parameter is a function, or configures the controls that are attached to the elements in this QueryCollection, if the ctor parameter is an object.

Parameters

  • ctor: any

    If this parameter is a function, it is a constructor function that is used to create controls to attach to the elements. If it is an object, it is the set of options passed to the controls.

  • options?: any optional

    The options passed to the newly-created controls.

Returns

QueryCollection

This QueryCollection object.

public every(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any): boolean

Determines whether all the members of an array satisfy the specified test.

Parameters

  • callbackfn: (value: T, index: number, array: T[]) => boolean

    A function that accepts up to three arguments. The every method calls the callbackfn function for each element in array1 until the callbackfn returns false, or until the end of the array.

  • thisArg?: any optional

    An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

Returns

boolean

public filter(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any): Array<T>

Returns the elements of an array that meet the condition specified in a callback function.

Parameters

  • callbackfn: (value: T, index: number, array: T[]) => boolean

    A function that accepts up to three arguments. The filter method calls the callbackfn function one time for each element in the array.

  • thisArg?: any optional

    An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

Returns

Array<T>

public forEach(callbackFn: (value: T, index: number, array: T[]) => void, thisArg?: any): QueryCollection

Performs an action on each item in the QueryCollection.

Parameters

  • callbackFn: (value: T, index: number, array: T[]) => void

    The action to perform on each item.

  • thisArg?: any optional

    The argument to bind to callbackFn.

Returns

QueryCollection

The QueryCollection.

public get(index: number): T in WinJS.Utilities.QueryCollection<T>

Gets an item from the QueryCollection.

Parameters

  • index: number

    The index of the item to return.

Returns

T in WinJS.Utilities.QueryCollection<T>

A single item from the collection.

public getAttribute(name: string): any

Gets an attribute value from the first element in the collection.

Parameters

  • name: string

    The name of the attribute.

Returns

any

The value of the attribute.

public hasClass(name: string): boolean

Determines whether the specified class exists on the first element of the collection.

Parameters

  • name: string

    The name of the class.

Returns

boolean

true if the element has the specified class; otherwise, false.

public id(id: string): QueryCollection

Looks up an element by ID and wraps the result in a QueryCollection.

Parameters

  • id: string

    The ID of the element.

Returns

QueryCollection

A QueryCollection that contains the element, if it is found.

public include(items: T in WinJS.Utilities.QueryCollection<T>)

Adds a set of items to this QueryCollection.

Parameters

  • items: T in WinJS.Utilities.QueryCollection<T>

    The items to add to the QueryCollection. This may be an array-like object, a document fragment, or a single item.

public include(items: Array<T>)

Adds a set of items to this QueryCollection.

Parameters

  • items: Array<T>

    The items to add to the QueryCollection. This may be an array-like object, a document fragment, or a single item.

public indexOf(searchElement: T in Array<T>, fromIndex?: number): number

Returns the index of the first occurrence of a value in an array.

Parameters

  • searchElement: T in Array<T>

    The value to locate in the array.

  • fromIndex?: number optional

    The array index at which to begin the search. If fromIndex is omitted, the search starts at index 0.

Returns

number

public join(separator?: string): string

Adds all the elements of an array separated by the specified separator string.

Parameters

  • separator?: string optional

    A string used to separate one element of an array from the next in the resulting String. If omitted, the array elements are separated with a comma.

Returns

string

public lastIndexOf(searchElement: T in Array<T>, fromIndex?: number): number

Returns the index of the last occurrence of a specified value in an array.

Parameters

  • searchElement: T in Array<T>

    The value to locate in the array.

  • fromIndex?: number optional

    The array index at which to begin the search. If fromIndex is omitted, the search starts at the last index in the array.

Returns

number

public listen(eventType: string, listener: Function, capture?: boolean)

Registers the listener for the specified event on all the elements in the collection.

Parameters

  • eventType: string

    The name of the event.

  • listener: Function

    The event handler function to be called when the event occurs.

  • capture?: boolean optional

    true if capture == true is to be passed to addEventListener; otherwise, false.

public map(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): Array<U>

Calls a defined callback function on each element of an array, and returns an array that contains the results.

Parameters

  • callbackfn: (value: T, index: number, array: T[]) => U

    A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.

  • thisArg?: any optional

    An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

Returns

Array<U>

public pop(): T in Array<T>

Removes the last element from an array and returns it.

Returns

T in Array<T>

public push(items?: Array<T>): number

Appends new elements to an array, and returns the new length of the array.

Parameters

  • items?: Array<T> optional

    New elements of the Array.

Returns

number

public query(query: any): QueryCollection

Executes a query selector on all the elements in the collection and aggregates the result into a QueryCollection.

Parameters

  • query: any

    The query selector string.

Returns

QueryCollection

A QueryCollection object containing the aggregate results of executing the query on all the elements in the collection.

public reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue?: T in Array<T>): T in Array<T>

Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

Parameters

  • callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T

    A function that accepts up to four arguments. The reduce method calls the callbackfn function one time for each element in the array.

  • initialValue?: T in Array<T> optional

    If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.

Returns

T in Array<T>

public reduce(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U

Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

Parameters

  • callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U

    A function that accepts up to four arguments. The reduce method calls the callbackfn function one time for each element in the array.

  • initialValue: U

    If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.

Returns

U

public reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue?: T in Array<T>): T in Array<T>

Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

Parameters

  • callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T

    A function that accepts up to four arguments. The reduceRight method calls the callbackfn function one time for each element in the array.

  • initialValue?: T in Array<T> optional

    If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.

Returns

T in Array<T>

public reduceRight(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U

Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

Parameters

  • callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U

    A function that accepts up to four arguments. The reduceRight method calls the callbackfn function one time for each element in the array.

  • initialValue: U

    If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.

Returns

U

public removeClass(name: string): QueryCollection

Removes the specified class from all the elements in the collection.

Parameters

  • name: string

    The name of the class to be removed.

Returns

QueryCollection

his QueryCollection object.

public removeEventListener(eventType: string, listener: Function, capture?: boolean): QueryCollection

Unregisters the listener for the specified event on all the elements in the collection.

Parameters

  • eventType: string

    The name of the event.

  • listener: Function

    The event handler function.

  • capture?: boolean optional

    true if capture == true; otherwise, false.

Returns

QueryCollection

This QueryCollection object.

public reverse(): Array<T>

Reverses the elements in an Array.

Returns

Array<T>

public setAttribute(name: string, value: any): QueryCollection

Sets an attribute value on all the items in the collection.

Parameters

  • name: string

    The name of the attribute to be set.

  • value: any

    The value of the attribute to be set.

Returns

QueryCollection

This QueryCollection object.

public setStyle(name: string, value: any): QueryCollection

Sets the specified style property for all the elements in the collection.

Parameters

  • name: string

    The name of the style property.

  • value: any

    The value for the property.

Returns

QueryCollection

This QueryCollection object.

public shift(): T in Array<T>

Removes the first element from an array and returns it.

Returns

T in Array<T>

public slice(start?: number, end?: number): Array<T>

Returns a section of an array.

Parameters

  • start?: number optional

    The beginning of the specified portion of the array.

  • end?: number optional

    The end of the specified portion of the array.

Returns

Array<T>

public some(callbackfn: (value: T, index: number, array: T[]) => boolean, thisArg?: any): boolean

Determines whether the specified callback function returns true for any element of an array.

Parameters

  • callbackfn: (value: T, index: number, array: T[]) => boolean

    A function that accepts up to three arguments. The some method calls the callbackfn function for each element in array1 until the callbackfn returns true, or until the end of the array.

  • thisArg?: any optional

    An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.

Returns

boolean

public sort(compareFn?: (a: T, b: T) => number): Array<T>

Sorts an array.

Parameters

  • compareFn?: (a: T, b: T) => number optional

    The name of the function used to determine the order of the elements. If omitted, the elements are sorted in ascending, ASCII character order.

Returns

Array<T>

public splice(start: number): Array<T>

Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.

Parameters

  • start: number

    The zero-based location in the array from which to start removing elements.

Returns

Array<T>

public splice(start: number, deleteCount: number, items?: Array<T>): Array<T>

Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.

Parameters

  • start: number

    The zero-based location in the array from which to start removing elements.

  • deleteCount: number

    The number of elements to remove.

  • items?: Array<T> optional

    Elements to insert into the array in place of the deleted elements.

Returns

Array<T>

public template(templateElement: HTMLElement, data: any, renderDonePromiseCallback: Function): QueryCollection

Renders a template that is bound to the given data and parented to the elements included in the QueryCollection. If the QueryCollection contains multiple elements, the template is rendered multiple times, once at each element in the QueryCollection per item of data passed.

Parameters

  • templateElement: HTMLElement

    The DOM element to which the template control is attached.

  • data: any

    The data to render. If the data is an array (or any other object that has a forEach method) then the template is rendered multiple times, once for each item in the collection.

  • renderDonePromiseCallback: Function

    If supplied, this function is called each time the template gets rendered, and is passed a promise that is fulfilled when the template rendering is complete.

Returns

QueryCollection

The QueryCollection.

public toLocaleString(): string

Returns

string

public toString(): string

Returns a string representation of an array.

Returns

string

public toggleClass(name: string): QueryCollection

Toggles (adds or removes) the specified class on all the elements in the collection. If the class is present, it is removed; if it is absent, it is added.

Parameters

  • name: string

    The name of the class to be toggled.

Returns

QueryCollection

This QueryCollection object.

public unshift(items?: Array<T>): number

Inserts new elements at the start of an array.

Parameters

  • items?: Array<T> optional

    Elements to insert at the start of the Array.

Returns

number

eventMixin: { addEventListener(type: string, listener: Function, useCapture?: boolean): void; dispatchEvent(type: string, eventProperties: any): boolean; removeEventListener(type: string, listener: Function, useCapture?: boolean): void; }

A mixin that contains event-related functions.

public addEventListener()

Adds an event listener to the control.

.listener.listener: Function

.type.type: string

optional .useCapture.useCapture?: boolean

public dispatchEvent(): boolean

Raises an event of the specified type and with the specified additional properties.

Returns

boolean

true if preventDefault was called on the event.

.eventProperties.eventProperties: any

.type.type: string

public removeEventListener()

Removes an event listener from the control.

.listener.listener: Function

.type.type: string

optional .useCapture.useCapture?: boolean

hasWinRT: boolean

Gets whether the current script context has access to WinRT APIs.

isPhone: boolean

Indicates whether the app is running on Windows Phone.

Functions

addClass(e: T, name: string): T

Adds the specified class to the specified element.

Parameters

  • e: T

    The element to which to add the class.

  • name: string

    The name of the class to add.

Returns

T

The element.

children(element: HTMLElement): QueryCollection

Gets a collection of elements that are the direct children of the specified element.

Parameters

  • element: HTMLElement

    The parent element.

Returns

QueryCollection

The collection of children of the element.

convertToPixels(element: HTMLElement, value: string): number

Converts a CSS positioning string for the specified element to pixels.

Parameters

  • element: HTMLElement

    The element.

  • value: string

    The CSS positioning string.

Returns

number

The number of pixels.

createEventProperties(events?: Array<string>): any

Creates an object that has one event for each name passed to the function.

Parameters

  • events?: Array<string> optional

    A variable list of property names.

Returns

any

The object with the specified properties. The names of the properties are prefixed with 'on'.

data(element: HTMLElement): any

Gets the data value associated with the specified element.

Parameters

  • element: HTMLElement

    The element.

Returns

any

The value associated with the element.

disposeSubTree(element: HTMLElement)

Disposes all first-generation disposable elements that are descendents of the specified element. The specified element itself is not disposed.

Parameters

  • element: HTMLElement

    The root element whose sub-tree is to be disposed.

empty(element: T): T

Removes all the child nodes from the specified element.

Parameters

  • element: T

    The element.

Returns

T

The element.

eventWithinElement(element: HTMLElement, event: Event): boolean

Determines whether the specified event occurred within the specified element.

Parameters

  • element: HTMLElement

    The element.

  • event: Event

    The event.

Returns

boolean

true if the event occurred within the element; otherwise, false.

formatLog(message: string, tag: string, type: string): string

Adds tags and type to a logging message.

Parameters

  • message: string

    The message to be formatted.

  • tag: string

    The tag(s) to be applied to the message. Multiple tags should be separated by spaces.

  • type: string

    The type of the message.

Returns

string

The formatted message.

getContentHeight(element: HTMLElement): number

Gets the height of the content of the specified element. The content height does not include borders or padding.

Parameters

  • element: HTMLElement

    The element.

Returns

number

The content height of the element.

getContentWidth(element: HTMLElement): number

Gets the width of the content of the specified element. The content width does not include borders or padding.

Parameters

  • element: HTMLElement

    The element.

Returns

number

The content width of the element.

getMember(name: string, root?: any): any

Gets the leaf-level type or namespace specified by the name parameter.

Parameters

  • name: string

    The name of the member.

  • root?: any optional

    The root to start in. Defaults to the global object.

Returns

any

The leaf-level type or namespace in the specified parent namespace.

getPosition(element: HTMLElement): IPosition

Gets the position of the specified element.

Parameters

  • element: HTMLElement

    The element.

Returns

IPosition

An object that contains the left, top, width and height properties of the element.

getRelativeLeft(element: HTMLElement, parent: HTMLElement): number

Gets the left coordinate of the specified element relative to the specified parent.

Parameters

  • element: HTMLElement

    The element.

  • parent: HTMLElement

    The parent element.

Returns

number

The relative left coordinate.

getRelativeTop(element: HTMLElement, parent: HTMLElement): number

Gets the top coordinate of the element relative to the specified parent.

Parameters

  • element: HTMLElement

    The element.

  • parent: HTMLElement

    The parent element.

Returns

number

The relative top coordinate.

getTotalHeight(element: HTMLElement): number

Gets the height of the element, including its margins.

Parameters

  • element: HTMLElement

    The element.

Returns

number

The height of the element including margins.

getTotalWidth(element: HTMLElement): number

Gets the width of the element, including margins.

Parameters

  • element: HTMLElement

    The element.

Returns

number

The width of the element including margins.

hasClass(e: HTMLElement, name: string): boolean

Determines whether the specified element has the specified class.

Parameters

  • e: HTMLElement

    The element.

  • name: string

    The name of the class.

Returns

boolean

true if the element has the class, otherwise false.

id(id: string): QueryCollection

Returns a collection with zero or one elements matching the specified id.

Parameters

  • id: string

    The ID of the element (or elements).

Returns

QueryCollection

A collection of elements whose id matches the id parameter.

insertAdjacentHTML(element: HTMLElement, position: string, text: string)

Calls insertAdjacentHTML on the specified element.

Parameters

  • element: HTMLElement

    The element on which insertAdjacentHTML is to be called.

  • position: string

    The position relative to the element at which to insert the HTML. Possible values are: beforebegin, afterbegin, beforeend, afterend.

  • text: string

    The text to insert.

insertAdjacentHTMLUnsafe(element: HTMLElement, position: string, text: string)

Calls insertAdjacentHTML on the specified element in the context of MSApp.execUnsafeLocalFunction.

Parameters

  • element: HTMLElement

    The element on which insertAdjacentHTML is to be called.

  • position: string

    The position relative to the element at which to insert the HTML. Possible values are: beforebegin, afterbegin, beforeend, afterend.

  • text: string

    Value to be provided to insertAdjacentHTML.

markDisposable(element: HTMLElement, disposeImpl: Function)

Attaches the default dispose API wrapping the dispose implementation to the specified element.

Parameters

  • element: HTMLElement

    The element to mark as disposable.

  • disposeImpl: Function

    The function containing the element-specific dispose logic, called by the dispose function that markDisposable attaches.

markSupportedForProcessing(func: U): U

Marks a function as being compatible with declarative processing. Declarative processing is performed by WinJS.UI.processAll or WinJS.Binding.processAll.

Parameters

  • func: U

    The function to be marked as compatible with declarative processing.

Returns

U

The input function, marked as compatible with declarative processing.

query(query: any, element?: HTMLElement): QueryCollection

Returns a QueryCollection with zero or one elements matching the specified selector query.

Parameters

  • query: any

    The CSS selector to use. See Selectors for more information.

  • element?: HTMLElement optional

    Optional. The root element at which to start the query. If this parameter is omitted, the scope of the query is the entire document.

Returns

QueryCollection

A QueryCollection with zero or one elements matching the specified selector query.

ready(callback?: Function, async?: boolean): Promise

Ensures that the specified function executes only after the DOMContentLoaded event has fired for the current page. The DOMContentLoaded event occurs after the page has been parsed but before all the resources are loaded.

Parameters

  • callback?: Function optional

    A function that executes after the DOMContentLoaded event has occurred.

  • async?: boolean optional

    If true, the callback should be executed asynchronously.

Returns

Promise

A promise that completes after the DOMContentLoaded event has occurred.

removeClass(e: T, name: string): T

Removes the specified class from the specified element.

Parameters

  • e: T

    The element from which to remove the class.

  • name: string

    The name of the class to remove.

Returns

T

The element.

requireSupportedForProcessing(value: T): T

Asserts that the value is compatible with declarative processing. Declarative processing is performed by WinJS.UI.processAll or WinJS.Binding.processAll. If the value is not compatible, and strictProcessing is on, an exception is thrown. All functions that have been declared using WinJS.Class.define, WinJS.Class.derive, WinJS.UI.Pages.define, or WinJS.Binding.converter are automatically marked as supported for declarative processing. Any other function that you use from a declarative context (that is, a context in which an HTML element has a data-win-control or data-win-options attribute) must be marked manually by calling this function. When you mark a function as supported for declarative processing, you are guaranteeing that the code in the function is secure from injection of third-party content.

Parameters

  • value: T

    The value to be tested for compatibility with declarative processing. If the value is a function it must be marked with a property supportedForProcessing with a value of true when strictProcessing is on. For more information, see WinJS.Utilities.markSupportedForProcessing.

Returns

T

The input value.

setInnerHTML(element: HTMLElement, text: string)

Sets the innerHTML property of the specified element to the specified text.

Parameters

  • element: HTMLElement

    The element on which the innerHTML property is to be set.

  • text: string

    The value to be set to the innerHTML property.

setInnerHTMLUnsafe(element: HTMLElement, text: string)

Sets the innerHTML property of the specified element to the specified text.

Parameters

  • element: HTMLElement

    The element on which the innerHTML property is to be set.

  • text: string

    The value to be set to the innerHTML property.

setOuterHTML(element: HTMLElement, text: string)

Sets the outerHTML property of the specified element to the specified text.

Parameters

  • element: HTMLElement

    The element on which the outerHTML property is to be set.

  • text: string

    The value to be set to the outerHTML property.

setOuterHTMLUnsafe(element: HTMLElement, text: string)

Sets the outerHTML property of the specified element to the specified text in the context of MSApp.execUnsafeLocalFunction.

Parameters

  • element: HTMLElement

    The element on which the outerHTML property is to be set.

  • text: string

    The value to be set to the outerHTML property.

startLog(options?: ILogOptions)

Configures a logger that writes messages containing the specified tags to the JavaScript console.

Parameters

  • options?: ILogOptions optional

    The tags for messages to log. Multiple tags should be separated by spaces. May contain type, tags, excludeTags and action properties.

stopLog()

Removes the WinJS logger that had previously been set up.

toggleClass(e: T, name: string): T

Toggles (adds or removes) the specified class on the specified element. If the class is present, it is removed; if it is absent, it is added.

Parameters

  • e: T

    The element on which to toggle the class.

  • name: string

    The name of the class to toggle.

Returns

T

The element.