DomAPI Home
DomAPI

domapi.Listbox

See also: Elm
See also: Component

A standard listbox component with a whole slew of features that affect it's look-and-feel. Supports multiple selection, sorting, drag-n-drop and more.

The Listbox has a property named items which can be treated as a NodeArray. You can access each item in the list using array notation, such as Listbox1.items.[0].innerHTML="boo"
This would set the text of the first item in the list. Take care not to try to access an item that doesn't exist. You can use items.length to determine how many items are in the list. (remember that the array starts with zero, not one!)

The listbox has a method named addItem() which takes an an inline object as a parameter. This argument controls how an item is created. For example: 

listitem1.addItem({text:"Item One"});
listitem1.addItem({text:"Item Two", value:23});
listitem1.addItem({text:"Item Three", itemSelectionFunc});
listitem1.addItem({text:"Item Four", value:23, fn:"itemSelected(this.innerText)"});
listitem1.addItem({text:"Item Five" , fn:function(){alert(1)}});

Listbox Example: system, aqua

Listbox Constructor

var listbox1 = domapi.Listbox({
  doHLines        : true,
  doLedger        : false,
  minWidth        : 50,
  doAutoWidth     : false,
  doMultiSelect   : false,
  doAllowNoSelect : false,
  doShowSelection : true 
});
Also inherits the construtor arguments of Elm and Component.

Constructor Details
Parameter Type Default Description
doHLines boolean true    
doLedger boolean false    
minWidth integer 50    
doAutoWidth boolean false    
doMultiSelect boolean false    
doAllowNoSelect boolean false    
doShowSelection boolean true    

Events unique to domapi.Listbox

Also has the same events as Elm and Component.

Methods unique to domapi.Listbox

Also has the same methods as Elm and Component.

Properties unique to domapi.Listbox

Also has the same properties as Elm and Component.
Events
onbeforechange ()

Fires right before the onchange event. You can return false to stop the selection from taking place. If you do, the onchange event will not fire.
item is the item the user is selecting.
NOTE: You must return true from this event to allow the selection to take place.

back to top
onchange ()

Fires after users has selected an item. item is the item the user is selecting.

Example:
  listbox1.onchange=function(item){alert("you selected " + item.innerHTML)};
back to top
Methods
addItem( arg )

The "arg" parameter fed to this method is an inline Object. See below for accepted parameters.
Any parameters not listed here that you add may also be attached to any returned Object.

Adds an item to the list. Caption can be plain-text or HTML.
Can optionally fire a function when the item is selected.

Example:
  with(listbox1){
  addItem({text:"Item 1"});
  addItem({text:"Item 2", fn:"alert('item2')"});
}
Available "arg" Parameters:
Parameter Type Required Default Description
text String     The caption to display 
value variant   text  Optional value to store for the item 
fn variant     Can be either a string (to be evaled) or a function reference. This parameter is fired whenever the item is selected. 
back to top
clearItems ()

Deletes every item from the list.

Example:
  if(confirm("Are you sure?"))listbox1.clearItems();
back to top
deleteItem ( i )

Deletes the item at the given index. Zero is the first item's index.

Example:
  // removes last item in list
with(listbox1)
   if(items.length > 1)deleteItem(items.length-1);
Parameters:
Parameter Type Required Default Description
i integer Y   Ordinal position 
back to top
delimitedText ( s, delimiter )

This method takes in a character delimited string and creates an item for each entry. For example, passing in the string "red,white,blue" would cause the listbox to add three items of the cooresponding captions.
The default delimiter a comma, or you can specify another to use.

Example:
  listbox1.delimitedText("one,two,three");

listbox1.delimitedText("four|five|six","|");

directorylistbox1.delimitedText("root\program files\my dir\","\");
Parameters:
Parameter Type Required Default Description
s String Y     
delimiter String   ,    
back to top
findItem ( s, ignoreCase )

Attempts to locate an item in the list. Returns a pointer to the item or null if not found.
By default searches are case-sensitive. Pass true as the second parameter for case-insensitive searches.

Example:
  var myItem = listbox1.findItem("boat",true);  // search for mixed-case "boat"
if(myItem != null) alert("found a boat!");
Parameters:
Parameter Type Required Default Description
s String Y   value to find 
ignoreCase boolean   false    
back to top
loadFromJson ( json )

Loads the listbox from a JSON object.

Example:
  var json = {
  items : [
    {text:"item1", value:12},
    {text:"item2"}
  ]
};
listbox1.loadFromJson(json);
Parameters:
Parameter Type Required Default Description
json Object Y     
back to top
loadFromJsonUrl ( url )

Loads the Listbox from a JSON string, specified by a URL.

Parameters:
Parameter Type Required Default Description
url String Y     
See also:  loadFromJson
back to top
selectAll ()

 

back to top
selectItem ( i, select )

Causes the listbox to select the item located at the index provided in i. Mimics the user clicking the item.

Parameters:
Parameter Type Required Default Description
i integer Y   Ordinal position. 
select boolean   false  Indicates whether the item should be selected or not. 
back to top
selectNone ()

 

back to top
setItem ( i, arg )

This method will overwrite an existing item. Params are the same as addItem() with the exception of the first which is the index of the item to overwrite. The first item in the list is item number zero.

Example:
  listbox1.setItem(4,{value:"Item 5"});
listbox1.setItem(0,{value:"Item 1",onselect:"close()"});
Parameters:
Parameter Type Required Default Description
i integer Y   Ordinal position. 
arg Object     Inline object containing new values for text, value and onselect 
back to top
sortItems ( direction, type )

Sorts the items in the list alphanumerically.
dir is the sort direction. 0=acsending, 1=descending

Example:
  listbox1.sortItems(0);
Parameters:
Parameter Type Required Default Description
direction integer Y     
type integer       
back to top
Properties
doAllowNoSelection type : boolean default value : false

If set to false, the control will not allow there to ever be less than one selected node. The first node added to the list will be immediately selected.

Example:
  listbox1.allowNoSelect = true;  // user can deselect all items
back to top
doBGFill type : boolean default value : true

Controls whether the listbox background is transparent or not.

back to top
doBorder type : boolean default value : true

Displays a border around the Listbox

back to top
doDepress type : boolean default value : true

When true, the items will appear to be depressed when clicked.

back to top
doHLines type : boolean default value : true

Controls whether or not horizontal lines are drawn between items

Example:
  listbox1.hLines = false; // hide lines
back to top
doLedger type : boolean default value : false

When ledgerMode is true, the control automatically alternates background colors when drawing items.

back to top
doMultiSelect type : boolean default value : false

If true, user can select more than one item.

Example:
  listbox1.multiSelect = true;  // allow the user to select more than one item
back to top
doRollover type : boolean default value : true

When true, the items will highlight as you mouseover them.

back to top
doShowSelection type : boolean default value : true

Determines whether or not the control highlights the selected item.

Example:
  listbox1.showSelection = false; // do not highlight item
back to top
itemIndex type : integer

Stores the integer index of the selected item.

back to top
items type : Collection

Each item in the list is accessed via this object. (which can be treated like a standard Array)

Example:
  alert("there are " + this.items.length + " items");

alert("item 4 is " + this.items[3].innerHTML);
back to top
selected type : Array

Pointer to the currently selected item. Returns null if none are selected.

Example:
  listbox1.onchange=function(){alert("you selected " + this.selected.innerHTML)};
back to top
DHTML by www.domapi.com