Hemi JavaScript Framework
Hemi.ui.wideselect
Description
The WideSelect control is a list control which supports buffered and paginated presentation.
Class Index
static Hemi.ui.wideselect.WideSelect
version 3.1.0
Control for buffering and paging large sets of data for display.
Index
Method Index
- public newInstance: Creates a new WideSelectInstance object.
Methods
newInstance
Creates a new WideSelectInstance object.
Syntax
u = newInstance(
o, cf, pf
)
Parameters
- o as HTMLNode : Parent HTML Node in which the control will be created.
- cf as function (optional): Click event handler.
- pf as function (optional): Paginate event handler.
Returns
u as WideSelectInstance: Instance of a WideSelect control.
Hemi.ui.wideselect.WideSelectItem
version 3.1.0
Object representing an item in the WideSelect control.
Index
Property Index
- public data: The data referenced or held by the item.
- public id: Unique identifier.
- public index: Index of this item in the items array.
- public name: Visible name of the item.
- private object (internal): The HTML object used to display the item.
Properties
data
The data referenced or held by the item.
Syntax
variant = object.data
object.data = variant
id
Unique identifier.
Syntax
String = object.id
index
Index of this item in the items array.
Syntax
integer = object.index
name
Visible name of the item.
Syntax
String = object.name
object.name = String
object
The HTML object used to display the item. Property is private and should not be directly referenced.
Syntax
HTMLNode = object.object
Hemi.ui.wideselect.ImportPageItem
version 3.1.0
Object construct used to bulk load paginated items.
Index
Property Index
- public id: Unique identifier
- public index: Index of this item in the items array.
- public label: Name of the item.
- private value (internal): Value of the item.
Properties
id
Unique identifier
Syntax
String = object.id
object.id = String
index
Index of this item in the items array.
Syntax
integer = object.index
label
Name of the item.
Syntax
String = object.label
object.label = String
value
Value of the item. Property is private and should not be directly referenced.
Syntax
variant = object.value
Hemi.ui.wideselect.WideSelectInstance
version 3.1.0
A buffering and pagination control for displaying large and incremental sets of data.
Index
Property Index
- public object_config (internal): Object API structure for storing sub structures: object_config.pointers and object_config.status.
- public object_id (internal): Unique instance identifier.
- public object_type (internal): The type of this object.
- public object_version (internal): Version of the object class.
- public ready_state (internal): Object load and execution state. Follows: 0 unitialized, 1 through 3 variant, 4 ready, 5 destroyed.
Method Index
- private _addItem (internal): Creates and renders a WideSelectItem object.
- private _handle_buffer_check (internal): Internal operation for testing the state of the buffer.
- private _handle_click (internal): Internal handler for mouseout event.
- private _handle_commit_buffer (internal): Internal operation for committing the buffer into the WideSelectItem array.
- private _handle_mouseout (internal): Internal handler for mouseout event.
- private _handle_mouseover (internal): Internal handler for mouseover event.
- private _handle_window_destroy (internal): Message subscription handler invoked when the host window is unloading.
- public addItem: Adds an item to the WideSelect control. The item is displayed based on buffering, and maximum display settings and restrictions. Use pageItem to add items for pagination. Specify a value of "_avoid" to create non-selectable labels.
- public alignControl: Aligns the WideSelectInstance to the bottom border of the specified HTML Node.
- public clearItem: Removes the specified WideSelectItem.
- public clearItems: Removes all WideSelectItem objects.
- public clearPagingValues: Removes all paged WideSelectItem objects.
- public commitBuffer: Commits the buffer up to the next buffer offset. Invoked automatically when AutoCommit is enabled.
- public deselectAllItems: Deselects all selected items in the WideSelect control.
- public destroy: Cleans up internal pointers, empties buffers, and removes HTML artifacts. Invoked when the window is unloaded.
- public endRequest: Hides the WideSelectInstance control if requested.
- public getActiveItem: Returns the selected WideSelectItem object.
- public getBufferMark: Returns the current position in the buffer, after which additional items will be rendered.
- public getBufferSize: Returns the current size of the buffer.
- public getCanMoveNext: Checks whether there is an additional page beyond the current.
- public getCanMovePrevious: Checks whether there is a previous page prior to the current.
- public getContainer: Returns the the HTML Node in which the control is created.
- public getCurrentPageItemCount: Returns the number of items in the current page.
- public getIsPaging: Returns whether the WideSelect control is in paging mode.
- public getIsRequested: Returns a bit indicating whether or not the control is requested for display.
- public getItem: Returns the WideSelectItem object at the specified index.
- public getItems: Returns an array of WideSelectItem objects.
- public getItemSize: Returns the current size of all items in the control.
- public getMaximumItems: Returns the maximum number of items supported by the control.
- public getMaximumPageItems: Returns the maximum number of items to display per page, if paging is enabled.
- public getMultiple: Returns whether multiple selection is enabled.
- public getObjectId: Returns the unique id of the object.
- public getObjectType: Returns the type of the object.
- public getObjectVersion: Returns the version of the object.
- public getPageStop: Returns whether the WideSelect control is no longer expecting data.
- public getPointers: Returns the object_config.pointers sub structure.
- public getReadyState: Returns the state of the object.
- virtual handle_pagenavigate: Handler is specified in the WideSelectInstance constructor; newInstance.
- public importPageItems: Imports a variant-length array of data into the paginated set of WideSelectItem objects.
- private init (internal): Initializes the WideSelect control.
- public moveFirst: Moves the paginated result set to the first page. Invokes any specified handle_pagenavigate handler.
- public moveLast: Moves the paginated result set to the last page. Invokes any specified handle_pagenavigate handler.
- public moveNext: Moves the paginated result set to the next page. Invokes any specified handle_pagenavigate handler.
- public movePrevious: Moves the paginated result set to the previous page. Invokes any specified handle_pagenavigate handler.
- public pageItem: Adds an item for pagination within the WideSelect control. The item is displayed based on pagination settings.
- public request: If requesting is enabled, displays and positions the WideSelectInstance control.
- public reset: Clears both paged and non-paged WideSelectItem objects, and ends any active request.
- public scrollToItem: Scrolls to control to the specified WideSelectItem.
- public selectItem: Selects the specified WideSelectItem.
- public setActiveItem: Selects the specified WideSelectItem . Blocks publication of the onresultclick message.
- public setAutoCommit: Specifies whether the WideSelect control should render items as they are added. If buffering is enabled, items will automatically begin rendering.
- public setAutoScroll: Specifies whether the WideSelect control will automatically scroll to the last rendered item.
- public setAutoSelect: Specifies whether the WideSelect control will automatically select the last rendered item.
- public setBufferDelay: Specifies the number of milliseconds to pause between rendering the buffer offset.
- public setBufferOffset: Specifies the number of items to be rendered at a time.
- public setCanRequest: Specifies whether the WideSelect control can be requested. The request featureset is used when the control is a pop-up or conditionally visible.
- public setIsBuffered: Specifies whether the control should buffer new items. Buffered items are incrementally rendered.
- public setIsPaging: Specifies whether the WideSelect control is in paging mode. Changing this value will clear paged items, and the control will need to be repopulated.
- public setMaximumItems: Sets the maximum number of items supported by the control. Specify zero to indicate no limit. Any items over the maximum when rollover is enabled will cause the top-most item to be removed. When rollover is disabled, the addItem method will fail on the last item.
- public setMaximumPageItems: Sets the maximum number of items displayed per page, if paging is enabled.
- public setMaximumRollover: Specifies whether the WideSelect control will rollover when the maximum number of items is reached; deleting the first item and adding the new item to the end. If disabled and a maximum limit is stipulated, then new items won't be added.
- public setMultiple: Sets whether multiple selection is enabled.
- public setPageStop: Specifies whether the WideSelect control should stop expecting more data, when in paging mode.
- public setResultHandler: Specifies the handler to invoke when a result item is activated.
- public updatePage: Renders the current page of WideSelectItem objects.
Message Index
- public onbuffercommitted: Message published to all subscribers when a buffered resultset was committed; being completely rendered and/or paginated.
- public onresultclick: Message published to all subscribers when the state changes for a WideSelectItem object.
Properties
object_config
Object API structure for storing sub structures: object_config.pointers and object_config.status.
Syntax
object = object.object_config
object_id
Unique instance identifier.
Syntax
String = object.object_id
object_type
The type of this object.
Syntax
String = object.object_type
object_version
Version of the object class.
Syntax
String = object.object_version
ready_state
Object load and execution state. Follows: 0 unitialized, 1 through 3 variant, 4 ready, 5 destroyed.
Syntax
int = object.ready_state
Methods
_addItem
Creates and renders a WideSelectItem object. Method is private and should not be directly referenced.
Syntax
void _addItem(
n, d
)
Parameters
- n as String : Name of the item. The name is used for the label.
- d as variant (optional): The value of the item.
_handle_buffer_check
Internal operation for testing the state of the buffer. Method is private and should not be directly referenced.
Syntax
void _handle_buffer_check(
)
_handle_click
Internal handler for mouseout event. Method is private and should not be directly referenced.
Syntax
void _handle_click(
v, b
)
Parameters
- v as variant : Overloaded variant which may be an event or index.
- b as boolean (optional): Bit indicating whether the "onresultclick" message should be suppressed.
_handle_commit_buffer
Internal operation for committing the buffer into the WideSelectItem array. Method is private and should not be directly referenced.
Syntax
void _handle_commit_buffer(
)
_handle_mouseout
Internal handler for mouseout event. Method is private and should not be directly referenced.
Syntax
void _handle_mouseout(
e
)
Parameters
- e as event : Event object
_handle_mouseover
Internal handler for mouseover event. Method is private and should not be directly referenced.
Syntax
void _handle_mouseover(
e
)
Parameters
- e as event : Event object
_handle_window_destroy
Message subscription handler invoked when the host window is unloading. Method is private and should not be directly referenced.
Syntax
void _handle_window_destroy(
)
addItem
Adds an item to the WideSelect control. The item is displayed based on buffering, and maximum display settings and restrictions. Use pageItem to add items for pagination. Specify a value of "_avoid" to create non-selectable labels.
Syntax
void addItem(
n, d
)
Parameters
- n as String : Name of the item. The name is used for the label.
- d as variant (optional): The value of the item.
alignControl
Aligns the WideSelectInstance to the bottom border of the specified HTML Node.
Syntax
void alignControl(
o
)
Parameters
- o as HTMLNode : HTML Node to which the control should be aligned.
clearItem
Removes the specified WideSelectItem.
Syntax
void clearItem(
i
)
Parameters
- i as integer : Index of WideSelectItem to remove.
clearItems
Removes all WideSelectItem objects.
Syntax
void clearItems(
)
clearPagingValues
Removes all paged WideSelectItem objects.
Syntax
void clearPagingValues(
)
commitBuffer
Commits the buffer up to the next buffer offset. Invoked automatically when AutoCommit is enabled.
Syntax
void commitBuffer(
)
deselectAllItems
Deselects all selected items in the WideSelect control.
Syntax
void deselectAllItems(
)
destroy
Cleans up internal pointers, empties buffers, and removes HTML artifacts. Invoked when the window is unloaded.
Syntax
void destroy(
)
endRequest
Hides the WideSelectInstance control if requested.
Syntax
void endRequest(
)
getActiveItem
Returns the selected WideSelectItem object.
Syntax
o = getActiveItem(
)
Returns
o as WideSelectItem: WideSelectItem object.
getBufferMark
Returns the current position in the buffer, after which additional items will be rendered.
Syntax
i = getBufferMark(
)
Returns
i as integer: Current insert position in the buffer.
getBufferSize
Returns the current size of the buffer.
Syntax
i = getBufferSize(
)
Returns
i as integer: Current size of the buffer.
getCanMoveNext
Checks whether there is an additional page beyond the current.
Syntax
b = getCanMoveNext(
)
Returns
b as boolean: Bit indicating whether there is an additional page.
getCanMovePrevious
Checks whether there is a previous page prior to the current.
Syntax
b = getCanMovePrevious(
)
Returns
b as boolean: Bit indicating whether there is a previous page.
getContainer
Returns the the HTML Node in which the control is created.
Syntax
o = getContainer(
)
Returns
o as HTMLNode: HTML Node in which the control is created.
getCurrentPageItemCount
Returns the number of items in the current page.
Syntax
i = getCurrentPageItemCount(
)
Returns
i as integer: Number of items in the current page.
getIsPaging
Returns whether the WideSelect control is in paging mode.
Syntax
b = getIsPaging(
)
Returns
b as boolean: Bit indicating whether the control is in paging mode.
getIsRequested
Returns a bit indicating whether or not the control is requested for display.
Syntax
b = getIsRequested(
)
Returns
b as boolean: Bit indicating whether the control is currently requested for display.
getItem
Returns the WideSelectItem object at the specified index.
Syntax
o = getItem(
i
)
Parameters
- i as integer : Index of WideSelectItem in items array.
Returns
o as WideSelectItem: WideSelectItem object.
getItems
Returns an array of WideSelectItem objects.
Syntax
a = getItems(
)
Returns
a as Array: Array of WideSelectItem objects.
getItemSize
Returns the current size of all items in the control.
Syntax
i = getItemSize(
)
Returns
i as integer: Count of all rendered and paginated items.
getMaximumItems
Returns the maximum number of items supported by the control.
Syntax
i = getMaximumItems(
)
Returns
i as integer: Maximum number of items supported by the control. Zero indicates no limit.
getMaximumPageItems
Returns the maximum number of items to display per page, if paging is enabled.
Syntax
i = getMaximumPageItems(
)
Returns
i as integer: Maximum number of items displayed per page.
getMultiple
Returns whether multiple selection is enabled.
Syntax
b = getMultiple(
)
Returns
b as boolean: Bit indicating whether multiple selection is enabled.
getObjectId
Returns the unique id of the object.
Syntax
i = getObjectId(
)
Returns
i as String: The unique object instance id.
getObjectType
Returns the type of the object.
Syntax
t = getObjectType(
)
Returns
t as String: The type of the object instance.
getObjectVersion
Returns the version of the object.
Syntax
v = getObjectVersion(
)
Returns
v as String: The version of the object instance.
getPageStop
Returns whether the WideSelect control is no longer expecting data.
Syntax
b = getPageStop(
)
Returns
b as boolean: Bit indicating whether the control is no longer expecting additional data.
getPointers
Returns the object_config.pointers sub structure.
Syntax
o = getPointers(
)
Returns
o as object: The object_config.pointers substructure.
getReadyState
Returns the state of the object.
Syntax
s = getReadyState(
)
Returns
s as int: The object ready state.
handle_pagenavigate
Handler is specified in the WideSelectInstance constructor; newInstance. Method is virtual and can be overridden.
Syntax
void handle_pagenavigate(
s, i
)
Parameters
- s as String : Static parameter:
- i as integer : Current page index.
importPageItems
Imports a variant-length array of data into the paginated set of WideSelectItem objects.
Syntax
void importPageItems(
a, b
)
Parameters
- a as Array : Array of ImportPageItem objects.
- b as boolean : Bit indicating whether this is the last page.
init
Initializes the WideSelect control. Method is private and should not be directly referenced.
Syntax
void init(
)
moveFirst
Moves the paginated result set to the first page. Invokes any specified handle_pagenavigate handler.
Syntax
void moveFirst(
)
moveLast
Moves the paginated result set to the last page. Invokes any specified handle_pagenavigate handler.
Syntax
void moveLast(
)
moveNext
Moves the paginated result set to the next page. Invokes any specified handle_pagenavigate handler.
Syntax
void moveNext(
b
)
Parameters
- b as boolean : Bit indicating whether the operation is a test.
movePrevious
Moves the paginated result set to the previous page. Invokes any specified handle_pagenavigate handler.
Syntax
void movePrevious(
b
)
Parameters
- b as boolean : Bit indicating whether the operation is a test.
pageItem
Adds an item for pagination within the WideSelect control. The item is displayed based on pagination settings.
Syntax
void pageItem(
n, d
)
Parameters
- n as String : Name of the item. The name is used for the label.
- d as variant (optional): The value of the item.
request
If requesting is enabled, displays and positions the WideSelectInstance control.
Syntax
void request(
)
reset
Clears both paged and non-paged WideSelectItem objects, and ends any active request.
Syntax
void reset(
)
scrollToItem
Scrolls to control to the specified WideSelectItem.
Syntax
void scrollToItem(
i
)
Parameters
- i as integer : Index of WideSelectItem to activate.
selectItem
Selects the specified WideSelectItem.
Syntax
void selectItem(
i, b
)
Parameters
- i as integer : Index of WideSelectItem to activate.
- b as boolean (optional): Bit indicating whether to block the
setActiveItem
Selects the specified WideSelectItem . Blocks publication of the onresultclick message.
Syntax
void setActiveItem(
i
)
Parameters
- i as integer : Index of WideSelectItem to activate.
setAutoCommit
Specifies whether the WideSelect control should render items as they are added. If buffering is enabled, items will automatically begin rendering.
Syntax
void setAutoCommit(
b
)
Parameters
- b as boolean : Bit indicating whether the control will automatically render items as they are added.
setAutoScroll
Specifies whether the WideSelect control will automatically scroll to the last rendered item.
Syntax
void setAutoScroll(
b
)
Parameters
- b as boolean : Bit indicating whether the control will automatically scroll to the last rendered item.
setAutoSelect
Specifies whether the WideSelect control will automatically select the last rendered item.
Syntax
void setAutoSelect(
b
)
Parameters
- b as boolean : Bit indicating whether the control will automatically select the last rendered item.
setBufferDelay
Specifies the number of milliseconds to pause between rendering the buffer offset.
Syntax
void setBufferDelay(
i
)
Parameters
- i as integer : Number of milleseconds.
setBufferOffset
Specifies the number of items to be rendered at a time.
Syntax
void setBufferOffset(
i
)
Parameters
- i as integer : Number of items to render at a time.
setCanRequest
Specifies whether the WideSelect control can be requested. The request featureset is used when the control is a pop-up or conditionally visible.
Syntax
void setCanRequest(
b
)
Parameters
- b as boolean : Bit indicating whether the control can be requested.
setIsBuffered
Specifies whether the control should buffer new items. Buffered items are incrementally rendered.
Syntax
void setIsBuffered(
b
)
Parameters
- b as boolean : Bit indicating whether the control should buffer new items.
setIsPaging
Specifies whether the WideSelect control is in paging mode. Changing this value will clear paged items, and the control will need to be repopulated.
Syntax
void setIsPaging(
b
)
Parameters
- b as boolean : Bit indicating whether the control is in paging mode.
setMaximumItems
Sets the maximum number of items supported by the control. Specify zero to indicate no limit. Any items over the maximum when rollover is enabled will cause the top-most item to be removed. When rollover is disabled, the addItem method will fail on the last item.
Syntax
void setMaximumItems(
i
)
Parameters
- i as integer : Maximum number of items supported by the control.
setMaximumPageItems
Sets the maximum number of items displayed per page, if paging is enabled.
Syntax
void setMaximumPageItems(
i
)
Parameters
- i as integer : Maximum number of items to be displayed per page.
setMaximumRollover
Specifies whether the WideSelect control will rollover when the maximum number of items is reached; deleting the first item and adding the new item to the end. If disabled and a maximum limit is stipulated, then new items won't be added.
Syntax
void setMaximumRollover(
b
)
Parameters
- b as boolean : Bit indicating whether the control will rollover when the maximum number of items is reached.
setMultiple
Sets whether multiple selection is enabled.
Syntax
void setMultiple(
b
)
Parameters
- b as boolean : Bit indicating whether multiple selection is enabled.
setPageStop
Specifies whether the WideSelect control should stop expecting more data, when in paging mode.
Syntax
void setPageStop(
b
)
Parameters
- b as boolean : Bit indicating whether the control should stop expecting more data.
setResultHandler
Specifies the handler to invoke when a result item is activated.
Syntax
void setResultHandler(
f
)
Parameters
- f as function : Function pointer to click handler.
updatePage
Renders the current page of WideSelectItem objects.
Syntax
void updatePage(
)
Messages
onbuffercommitted
Message published to all subscribers when a buffered resultset was committed; being completely rendered and/or paginated.
Syntax
// User-specified script to subscribe to message
org.cote.js.message.MessageService.subscribe("onbuffercommitted",_handle_message);
// Internal: how the message is published to subscribers
org.cote.js.message.MessageService.publish("onbuffercommitted"
, o
);
// User-specified script to handle the message subscription
function _handle_message("onbuffercommitted"
, o
){
// message handler code
}
Parameters
- o as WideSelectInstance : The WideSelect control for which the buffer was committed.
onresultclick
Message published to all subscribers when the state changes for a WideSelectItem object.
Syntax
// User-specified script to subscribe to message
org.cote.js.message.MessageService.subscribe("onresultclick",_handle_message);
// Internal: how the message is published to subscribers
org.cote.js.message.MessageService.publish("onresultclick"
, o
);
// User-specified script to handle the message subscription
function _handle_message("onresultclick"
, o
){
// message handler code
}
Parameters
- o as WideSelectInstance : The WideSelect control for which the item state was changed.
[ Hemi JavaScript Framework - Stephen W. Cote, 2002 - 2009. ]