CommonCtrl.dropdownlistbox

a dropdown listbox control using a textbox, a button and a listbox

Description

Sample Code

NPL.load("(gl)script/ide/dropdownlistbox.lua");
local ctl = CommonCtrl.dropdownlistbox:new{
   name = "dropdownlistbox1",
   alignment = "_lt",
   left=0, top=0,
   width = 300,
   height = 26,
   parent = nil,
   items = {"line1", "line2", "line3", "line4", values=nil,},
};
ctl:Show();

Member Functions

dropdownlistbox:new

 common control library
NPL.load("(gl)script/ide/common_control.lua");

 define a new control in the common control libary

 default member attributes
local dropdownlistbox = {
   -- the top level control name
   name = "dropdownlistbox1",
   -- normal window size
   alignment = "_lt",
   left = 0,
   top = 0,
   width = 300,
   height = 26, 
   buttonwidth = 20, -- the drop down button width
   dropdownheight = 150, -- the drop down list box height.
   parent = nil,
   -- appearance
   container_bg = nil, -- the background of container that contains the editbox and the dropdown button.
   editbox_bg = nil, -- edit box background texture
   dropdownbutton_bg = "Texture/DropDownBox.png:4 5 4 5",-- drop down button background texture
   listbox_bg = nil, -- list box background texture
   -- data
   -- an array of text, one needs to call RefreshListBox() manually, if one changes the items after the list box is displayed for the first time.
   -- items.values can be nil or a table mapping items name to item value. if items.values is nil, the GetValue() method will default to GetText().
   items = {values=nil,}, 
   text = "", -- current text
   -- onchange event, it can be nil, a string to be executed or a function of type void ()(sCtrlName, item)
   -- it will be called when the user select an item or pressed Enter in the editbox. One may call GetText() to retrieve text in the handler
   onselect= nil,
   -- it is a function to format the a selected item text to be displayed in the editbox. It takes a string and returns a string, such as fucntion(text) return text.." Seconds" end
   -- if this is nil, the original item text is displayed at the editbox.
   FuncTextFormat=nil,
   -- whether we allow user to enter text into the editbox
   AllowUserEdit = true,
   -- if true the drop down list box button is disabled. 
   IsReadonly = nil,
   listbox_cont_id = -1,
   listbox_id = -1,
   button_id = -1,
   editbox_id = -1,
}

constructor

syntax

function dropdownlistbox:new (o)

parameters

dropdownlistbox:Destroy

Destroy the UI control

syntax

function dropdownlistbox:Destroy ()

dropdownlistbox:Show

• param bShow : boolean to show or hide. if nil, it will toggle current setting.

syntax

function dropdownlistbox:Show(bShow)

parameters

dropdownlistbox:GetText

returns the text of the selected item, return "" if nothing is selected.

syntax

function dropdownlistbox:GetText()

dropdownlistbox:SetText

set text

syntax

function dropdownlistbox:SetText(text)

parameters

dropdownlistbox:GetValue

get the value if items.values is a table.

syntax

function dropdownlistbox:GetValue()

dropdownlistbox:SetValue

set the value if items.values is a table.

syntax

function dropdownlistbox:SetValue(value)

parameters

dropdownlistbox:GetEnabled

return whether the listbox is enabled

syntax

function dropdownlistbox:GetEnabled()

dropdownlistbox:SetEnabled

set whether the listbox is enabled

syntax

function dropdownlistbox:SetEnabled(bEnable)

parameters

dropdownlistbox:RefreshListBox

OBSOLETED: this function is not needed any more. It does nothing.

syntax

function dropdownlistbox:RefreshListBox()

dropdownlistbox:RefillListBox

refill the listbox content using the items.

syntax

function dropdownlistbox:RefillListBox()

dropdownlistbox.OnClickDropDownButton

called when the drop down button is clicked.

syntax

function dropdownlistbox.OnClickDropDownButton(sCtrlName)

parameters

dropdownlistbox.OnMouseUpListBoxCont

called when the user select a list box item

syntax

function dropdownlistbox.OnMouseUpListBoxCont(sCtrlName)

parameters

dropdownlistbox.OnTextChange

called when the text has changed

syntax

function dropdownlistbox.OnTextChange(sCtrlName)

parameters

dropdownlistbox.OnSelectListBox

called when the user select a list box item

syntax

function dropdownlistbox.OnSelectListBox(sCtrlName)

parameters

dropdownlistbox:InsertItem

insert item to back: if already exist, it does nothing.

• param item : string item
• param bNoUpdate : if true, the list box is not refreshed even a new item is added.
• return the : index of the inserted item.

syntax

function dropdownlistbox:InsertItem(item, bNoUpdate)

parameters