Note: The term 'item' here refers to an entry in the ListControl, not an item in the Klip.

Use myTab.addListControl() to add a ListControl to a tab, where myTab is a Tab object.

Example

 function onLoad() {
 
     // Create a new tab
     var tab = Setup.addTab( "New Tab" );
 
     // Add a listcontrol using the following parameters
     //
     //    true -- give each item in the list a checkbox
     //    true -- allow the user to select multiple items
     //
     listControl = tab.addListControl( true, true );
   
     // Add three entries
     listControl.addItem( "First Item" );
     listControl.addItem( "Second Item" );
     listControl.addItem( "Third Item" );
 }
 

Each Tab object in the Setup array corresponds to a tab in a Klip's Customize window. This window is visible when a user right-clicks on a Klip and chooses the command 'Customize Klip...'

Each Tab object can have multiple UI components, and each Klip can have multiple tabs. Use the Button, Checkbox, ComboBox, ListControl, Spacer, Text, TextArea, and TextField objects in a tab to enable users to configure the Klip to their preferences.

Example

<?xml version='1.0' ?>
  <klip>
     <identity>
        <title>
           API: ListControl
        </title>
     </identity>
     <locations>
        <contentsource>
           http://support.klipfolio.com/files/demo/demo.xml
        </contentsource>
      <icon>
         http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
      </icon>
      <banner>
         http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png   
      </banner>
     </locations>
     <setup>
        <refresh>
          1
        </refresh>
     </setup>
     <style>
        alert { 
           type: item;
        } 
        sender {
           itemcol: 2;
           noterow: 1;
           label: 'Sender';
           emphasis: strong;
        } 
        summary {
           itemcol: 3;
           noterow: 4;
           wrap: false;
           notelabel: false;
        } 
        date {
           itemcol: 4;
           noterow: 2;
           label: 'Date';
        } 
        category {
           noterow: 3;
           label: 'Category';
        } 
        level {
           itemcol: 1;
           noterow: 5;
           notelabel: false;
           type: image;
        } 
        url {
           type: link;
        } 
        id {
           key: override;
        } 
  </style>
  <klipscript>
  <![CDATA[

// Globals
var LC_category;            // List Control Object
var LC_category_choices = [];    // Array to hold choices for List Control
var B_category_clear;        // Button event handler for clear
var B_category_all;            // Button event handler for show all

var hidden_count;

function onLoad()
{
    var tab,p;    

    // Create Filters Tab
    tab = Setup.addTab ("Filters");    

    tab.addText ("Filter category:");
    LC_category = tab.addListControl (true, false);
    LC_category.onStateChange = LC_category_onStateChange;        
    B_category_clear = tab.addButton( "Clear All" );
    B_category_clear.onClick = B_category_clear_onClick;
    B_category_all = tab.addButton( "Select All" );
    B_category_all.onClick = B_category_all_onClick;
    
    tab.addSpacer (false);
    button = tab.addButton ("Show State");
    button.onClick = show_state;


    // Load preferences
    // Retrieve Preferences for category
    var re_cat_category = new RegExp ("cat_category_(.*)", "i");
    var match;
   
    for (var i = 0; i < Prefs.length; i++) 
    { 
        match = re_cat_category.exec (Prefs[i].name);
        if (match) 
        {
            insert (LC_category, match[1], Prefs[i].value != "false");
        }
    }


    Setup.onOpen = Setup_onOpen;
    Setup.onClose = Setup_onClose;
}


function onRefresh()
{
    _t( "onRefresh () -- " + Prefs.contentsource );
    var result = Engines.Data.process ( Prefs.contentsource );
        
    // Apply Filters
    filter_items();

    return result;
}


//
// Support functions -----------------------------------------------
//

// Called when the user clicks a check box in the List Control for category
//
function LC_category_onStateChange (index)
{
    _t( "  LC_category_onStateChange(" + index + ") -- \"" + LC_category[index] + "\" set to " + this.getState(index) );
    
    var s = "cat_category_" + this[index];
    Prefs.setPref (s, this.getState(index));
    
    filter_items ();
}

// Called when the clicks the "Clear" button
//
function B_category_clear_onClick () 
{
    _t( "  B_category_clear_onClick" );
    
    for( var i = 0; i<LC_category.length; i++ ) 
    {
        var s = "cat_category_" + LC_category[i];
        LC_category.setState ( i, false);
        Prefs.setPref (s, "false");
    }
    
    filter_items ();
}

// Called when the user clicks the "Select All" button
//
function B_category_all_onClick () 
{
    _t( "  B_category_all_onClick" );
    
    for( var i = 0; i<LC_category.length; i++ ) 
    {
        var s = "cat_category_" + LC_category[i];
        LC_category.setState (i, true);
        Prefs.setPref (s, "true");
    }
    
    filter_items ();
}

// Inserts items a list control in alphabetical order
//
function insert (obj, entry, state) 
{
    var index = obj.length;
    obj.addItem( entry );
    obj.setState( index, state );
    if( index > 0 ) 
    {
        while( --index >= 0 ) 
        {
            if( obj[index + 1] < obj[index] ) 
            {
                var s = obj[index + 1];
                var state = obj.getState( index + 1 );
                var selected = obj.getSelected( index + 1 );

                obj[index + 1] = obj[index];
                obj.setState( index + 1, obj.getState( index ) ); 
                obj.setSelected( index + 1, obj.getSelected( index ) ); 

                obj[index] = s;
                obj.setState( index, state );
                obj.setSelected( index, selected );
            }
        }
    }
}


function Setup_onClose()
{
    _t( "Setup_onClose()" );
    set_status ();
}

function Setup_onOpen()
{
    _t( "Setup_onOpen()" );
    set_status ();
}

function filter_items()
{
    hidden_count = 0;
    var hidden;


    for (var i=0; i < Items.length; i++ ) 
    {
        hidden = false;

        // Dynamically build prefs for category if no prefs exist
        var category = Items[i].getData ("category");

        if (Prefs.getPref( "cat_category_" + category ) == "") 
        {
            Prefs.setPref ("cat_category_" + category, "true");
            insert( LC_category, category, true );
        }

        if ( Prefs.getPref ("cat_category_" + category) == "false" ) {
            hidden = true;
        }                        ;        


        Items[i].hidden = hidden;
        if ( Items[i].hidden == true ) {
            hidden_count++;
        }
        
    }
    set_status ();
}

function set_status() 
{
    var s = "";

    if (hidden_count > 0) 
    {
        Klip.progressmessage = "[ Hidden = " + hidden_count + "]";
    } 
}


//
// Useful Debug Code -----------------------------------------------
//
var button;
function show_state() 
{
       show_items ();
      show_itemsDeleted ();
    show_all_prefs ();
        
    // Dump state of ListControl
    for (i = 0; i < LC_category.length; i++) 
    {
        _t( "LC_category[" + i + "]=\""
            + LC_category[i] + "\" ("
            + LC_category.getState(i) + ")");
    }
}

function show_items() 
{
    if (Items.length == 0) 
    {
        trace ("There are no items in the Items[] array\r\n");
        return;
    }

    for( i = 0; i < Items.length; i++ ) 
    {
        trace ("Items[" + i + "]: \r\n");        
        queryItem (Items[i]);
    }
}

function show_itemsDeleted() 
{
    if (Items.Deleted.length == 0) 
    {
        trace ("There are no items in the Items.Deleted[] array\r\n");
        return;
    }
    
    for (i = 0; i < Items.Deleted.length; i++) 
    {
        trace ("Items.Deleted[" + i + "]: \r\n");        
        queryItem ( Items.Deleted[i]);
    }
}

function queryItem( item ) 
{
    trace( "-----------------\r\n" );
    trace( "    .hidden       = " + item.hidden + " (boolean)\r\n" );
    trace( "    .visited      = " + item.visited + " (boolean)\r\n" );
    trace( "    .canpurge     = " + item.canpurge + "  (boolean)\r\n" );
    trace( "    .alerting     = " + item.alerting + " (boolean)\r\n" );
    trace( "    .creation     = " + item.creation + " (double)\r\n" );
    trace( "    .pubdate      = " + item.pubdate + "  (double)\r\n" );
    trace( "    .lastmodified = " + item.lastmodified + "  (double)\r\n" );

    // Output the current value of each defined element in an item

        trace( "      .getData (\"level\") = \"" + item.getData( "level" ) + "\" (string)\r\n" );
        trace( "      .getData (\"sender\") = \"" + item.getData( "sender" ) + "\" (string)\r\n" );
        trace( "      .getData (\"summary\") = \"" + item.getData( "summary" ) + "\" (string)\r\n" );
        trace( "      .getData (\"date\") = \"" + item.getData( "date" ) + "\" (string)\r\n" );
        trace( "      .getData (\"category\") = \"" + item.getData( "category" ) + "\" (string)\r\n" );
        trace( "      .getData (\"url\") = \"" + item.getData( "url" ) + "\" (string)\r\n" );
        trace( "      .getData (\"id\") = \"" + item.getData( "id" ) + "\" (string)\r\n" );
    
    trace( "\r\n" );
}

function show_all_prefs() 
{
   if (Prefs.length == 0) 
   {
      trace ("There are no Prefs defined\r\n");
      return;
   }
   
   trace( "------------------------\r\n" );

   for (var i = 0; i < Prefs.length; i++) 
   { 
      trace("Prefs.getPref( \""+Prefs[i].name+"\" ) == \""+Prefs[i].value+"\"\r\n"); 
   }
   
   trace( "------------------------\r\n" );
}

function _t( s ) 
{
   trace( s + "\r\n" );
}
    ]]>
    </klipscript>
</klip>
     	

 onRefresh () -- http://support.klipfolio.com/files/demo/demo.xml
 Setup_onOpen()
   LC_category_onStateChange(0) -- "Category 1" set to false
   LC_category_onStateChange(1) -- "Category 2" set to false
   LC_category_onStateChange(1) -- "Category 2" set to true
 Setup_onClose()
 

Accessing ListControl as an Array

     // Change the second item
     listControl[1] = "This is a new second item";   
 

Properties Detail

disabled

boolean disabled

The enabled (true) or disabled (false) state of this component.

editable

boolean editable

The editable (true) or static (false) state of this listcontrol.

By default this property is false. It may be changed at any time. See onEndEdit() for more information.

length

integer length

The number of items in the list (read-only).

value

String value

The text of the currently selected item.

addItem

function addItem( <String> name, [<boolean> checked, [<boolean> selected]] )

Appends a new item to the list of items in this component.

Optionally, you can specify whether the new item is checked (for checked lists) and/or selected.

Parameters:
name - the text of the item to append
checked - item is checked (applies only to checked lists) [optional]
selected - item is selected [optional]

clear

function clear()

Clears all items from the listcontrol.

clearSelection

function clearSelection()

Deselects all selected in the ListControl.

getSelected

boolan getSelected( <integer> index )

Returns the selected (true) or unselected (false) state of a specific item.

Note: If the listcontrol was created with checkboxes, use getState() to get the checked/unchecked state of the item.

Parameters:
index - the index of the item

Returns:
true if the item is selected by the user; otherwise, returns false

getState

boolan getState( <integer> index )

Returns the checked (true) or unchecked (false) state of an item at a specific index.

Note: Use getSelected() to get the selected/unselected status of the item.

Parameters:
index - the index of the item

Returns:
the checked (true) or unchecked (false) state of an item at the given index. If the listcontrol was created without checkboxes, this function returns false.

onClick

function onClick( [<integer> index] )

Specifies a Handler Function for Klipfolio Dashboard to call when the user clicks an item in the list.

Example:
The following Klip creates a new tab called 'New Tab', then creates a list box and assigns it the handler functions onClick(), onStateChange(), and onDblClick().



<klip>
   <identity>
      <title>
         API: ListControl
      </title>
   </identity>
   <locations>
      <contentsource>
         http://support.klipfolio.com/files/demo/demo.xml
      </contentsource>
      <icon>
         http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
      </icon>
      <banner>
         http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png   
      </banner>
   </locations>
   <style>
      alert {
         type: item;
      }

      sender {
         itemcol: 2;
         noterow: 1;

         label: 'Sender';

         emphasis: strong;
      }


      summary {
         itemcol: 3;
         noterow: 4;

         wrap: false;

         notelabel: false;
      }

      date {
         itemcol: 4;
         noterow: 2;

         label: 'Date';
      }

      category {
         noterow: 3;

         label: 'Category';
      }


      level {
         itemcol: 1;
         noterow: 5;
         notelabel: false;
         
         type: image;
      }

      url {
         type: link;
      }
            
      id {
         key: override;
      }
   </style>
   <klipscript>
   <![CDATA[

var listControl;

function onLoad() {
 
     // Create a new tab
     var tab = Setup.addTab( "New Tab" );
 
     // Add a listcontrol usint the following parameters
     //
     //    true -- give each item in the list a checkbox
     //    true -- allow the user to select multiple items
     //
     listControl = tab.addListControl( true, true );
   
     // Add three entries
     listControl.addItem( "First Item" );
     listControl.addItem( "Second Item" );
     listControl.addItem( "Third Item" );
     
     listControl.onClick       = listControl_onClick;
     listControl.onStateChange = listControl_onStateChange;
     listControl.onDblClick    = listControl_onDblClick;
}

function listControl_onClick( index ) {
      trace( "You selected item " + index + " which is '" + this[index] + "'.\r\n" );
}

function listControl_onStateChange( index ) {
      trace( "You changed item " + index + " which is now set to '" + this.getState(index) + "'.\r\n" );
}

function listControl_onDblClick( index ) {
      trace( "You double-clicked item " + index + " which is '" + this[index] + "'.\r\n" );
}


function onRefresh()
{
	return Engines.Data.process( Prefs.contentsource );
}
  
   ]]>
   </klipscript>
</klip>

     	

Open the Klip's Customize window and interact with the comboboxes. For example, click on text of an entry to select it, or click the checkbox next to an entry to change its state. You'll see a similar output to Klip's Debug Window.


 You selected item 0 which is 'First Item'.
 You double-clicked item 0 which is 'First Item'.
 You changed item 1 which is now set to 'true'.
 You changed item 1 which is now set to 'false'.
 You changed item 0 which is now set to 'true'.
 

Klipfolio Dashboard passes a reference to the ListControl object via the instance variable this.

Note: Notice that the assignment to the handler function is checkBoxOnClick, not checkBoxOnClick(). The former is a function, while the latter is the return value from a function call.

Parameters:
index - the index of the item the user clicked. [optional]

onDblClick

function onDblClick( [<integer> index] )

Specifies a Handler Function for Klipfolio Dashboard to call when the user double-clicks an item in the ListControl.

See onClick() for an example.

Parameters:
index - the index of the item the user double-clicked [optional]

onEndEdit

function onEndEdit( [<integer> index [, <String> text]] )

Specifies a Handler Function for Klipfolio Dashboard to call when the user finishes editing the text of an item in the ListControl object.

Note that the items are only editable (and therefore this handler will only be called) if editable() is true.

Note also that your script can refer to the original text of the item specified by index using this[index]. If your script does not modify the edited item's text explicitly, it will revert back to its original value (prior to the user's edit) when this handler function returns.

Example:
The following Klip creates a new tab called 'New Tab', then creates a list box, sets it as editable, and assigns it the handler function onEndEdit().



<klip>
   <identity>
      <title>
         API: ListControl.onEndEdit()
      </title>
   </identity>
   <locations>
      <contentsource>
         http://support.klipfolio.com/files/demo/demo.xml
      </contentsource>
      <icon>
         http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
      </icon>
      <banner>
         http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png   
      </banner>
   </locations>
   <style>
      alert {
         type: item;
      }

      sender {
         itemcol: 2;
         noterow: 1;

         label: 'Sender';

         emphasis: strong;
      }


      summary {
         itemcol: 3;
         noterow: 4;

         wrap: false;

         notelabel: false;
      }

      date {
         itemcol: 4;
         noterow: 2;

         label: 'Date';
      }

      category {
         noterow: 3;

         label: 'Category';
      }


      level {
         itemcol: 1;
         noterow: 5;
         notelabel: false;
         
         type: image;
      }

      url {
         type: link;
      }
            
      id {
         key: override;
      }
   </style>
   <klipscript>
   <![CDATA[


var listControl;

function onLoad() {
 
     // Create a new tab
     var tab = Setup.addTab( "New Tab" );
 
     // Add a listcontrol usint the following parameters
     //
     //    true -- give each item in the list a checkbox
     //    true -- allow the user to select multiple items
     //
     listControl = tab.addListControl( true, true );
   
     // Set the list as editable
     listControl.editable = true;

     // Add three entries
     listControl.addItem( "First Item" );
     listControl.addItem( "Second Item" );
     listControl.addItem( "Third Item" );
     
     listControl.onEndEdit = listControl_onEndEdit;
}

function listControl_onEndEdit( index, text ) {
    trace( "You have edited item " + index + " from '" + this[index] + "' to '" + text + "'\r\n" );
    
    // Because we have defined an onEndEdit handler, the handler is responsible for
    // updating the text; otherwise, Klipfolio Dashboard will revert to original text.  
    
    this[index] = text;
}

function onRefresh()
{
	return Engines.Data.process( Prefs.contentsource );
}
  
   ]]>
   </klipscript>
</klip>

     	

If you open the Klip's Customize window and change the text for the first entry to 'Changed first item' and the second to 'Next Item', you'll see the following output in Klip's Debug Window.


 You have edited item 1 from 'First Item' to 'Changed first item'
 You have edited item 1 from 'Second Item' to 'Next Item'
 

Note: Notice the assignment to the handler function is listControl_onEndEdit, not listControl_onEndEdit(). The former is a function, while the latter is the return value from a function call.

Parameters:
index - the index of the item whose text has been edited [optional]
text - the text the user has input into the editable region of the item [optional]

onStateChange

function onStateChange( [<integer> index] )

Specifies a Handler Function for Klipfolio Dashboard to call when the user clicks the checkbox of an item in the ListControl.

See onClick() for an example.

Parameters:
index - the index of the item whose checkbox the user clicked [optional]

remove

boolean remove( <String> name | <integer> index )

Removes the specified item.

Note: remove accepts either a string parameter, for which Klipfolio Dashboard will search and remove the first instance of, or an integer parameter, the index at which the item you want to remove resides.

Example:
For example, the following Klip creates a new tab called 'New Tab', then adds a ListControl with four entries, then deletes the first by index and second entry by name, and renames the second item.



<klip>
   <identity>
      <title>
         API: ListControl.remove
      </title>
   </identity>
   <locations>
      <contentsource>
         http://support.klipfolio.com/files/demo/demo.xml
      </contentsource>
      <icon>
         http://www.klipfolio.com/static/klips/klipfolio/sample_icon.png
      </icon>
      <banner>
         http://www.klipfolio.com/static/klips/klipfolio/sample_banner.png   
      </banner>
   </locations>
   <style>
      alert {
         type: item;
      }

      sender {
         itemcol: 2;
         noterow: 1;

         label: 'Sender';

         emphasis: strong;
      }


      summary {
         itemcol: 3;
         noterow: 4;

         wrap: false;

         notelabel: false;
      }

      date {
         itemcol: 4;
         noterow: 2;

         label: 'Date';
      }

      category {
         noterow: 3;

         label: 'Category';
      }


      level {
         itemcol: 1;
         noterow: 5;
         notelabel: false;
         
         type: image;
      }

      url {
         type: link;
      }
            
      id {
         key: override;
      }
   </style>
   <klipscript>
   <![CDATA[

var listControl;

function onLoad() {
 
     // Create a new tab
     var tab = Setup.addTab( "New Tab" );
 
     // Add a listcontrol usint the following parameters
     //
     //    true -- give each item in the list a checkbox
     //    true -- allow the user to select multiple items
     //
     listControl = tab.addListControl( true, true );
   
     // Set the list as editable
     listControl.editable = true;

     // Add three entries
     listControl.addItem( "1st Item" );
     listControl.addItem( "2nd Item" );
     listControl.addItem( "3rd Item" );
     listControl.addItem( "4th Item" );
     
    // listControl.onEndEdit = listControl_onEndEdit;

     // Remove item by index
     listControl.remove( 0 );

     // Remove item by name
     listControl.remove( "2nd Item" );
     
     listControl[1] = "Renamed 4th Item";

}

function onRefresh()
{
	return Engines.Data.process( Prefs.contentsource );
}
  
   ]]>
   </klipscript>
</klip>

     	

Parameters:
name - the name of the item to remove
index - the index of the item to remove

Returns:
true if the specified item could be found and removed, otherwise returns false

setSelected

boolan setSelected( <integer> index, <boolean> state )

Sets the selected (true) or unselected (false) state of a specific item.

Note: If the listcontrol was created with checkboxes, use setState() to set the checked/unchecked state of the item.

Parameters:
index - the index of the item
state - selected (true) or unchecked (false)

setState

function setState( <integer> index, <boolean> state )

Sets the checked (true) or unchecked (false) state of an item at a specific index.

Note: If the listcontrol was created without checkboxes, this function has no effect.

Parameters:
index - the index of the item
state - checked (true) or unchecked (false)