BBjListButton

Description

The BBjListButton object provides methods for manipulating a GUI list button control.

Implemented Interfaces

DropTarget, Editable, Focusable, MouseWheelEnabled, RecordSetBindable,RecordSetFillable,SimpleRecordSetBindable,TabTraversable, TextAlignable,Validateable

Creation

BBjAPI > BBjSysGui > BBjWindow > BBjListButton

A BBjListButton object is created through the following BBjWindow methods:

Return Value

Method

BBjListButton

addListButton(int ID, number x, number y, number w, number h, string initialContents)

BBjListButton

addListButton(int ID, number x, number y, number w, number h, string initialContents, string flags)

BBjListButton addListButton(int ID, string initialContents)
BBjListButton addListButton(int ID, string initialContents, String flags)
BBjListButton addListButton(string initialContents)

BBjListButton

addListButton(string initialContents, String flags)

Methods of BBjListButton

Return Value

Method

void

addItem(string item)

void

closeList()

void

deselect()

BBjVector

getAllItems()

int

getFieldHeight()

string

getItemAt(int index)

int

getItemCount()

void

getOpenWidth()

int

getSelectedIndex()

void

insertItemAt(int index, string item)

void

insertItems(int index, BBjVector itemVector!)

void

insertItems(int index, string items$)

boolean

isEditable()

void

openList()

void

removeAllItems()

void

removeItemAt(int index)

void

setImageAt(int index, BBjImage image!)

void

selectIndex(int index)

void

setEditable(boolean edit)

void

setFieldHeight(int height)

void

setMaximumRowCount(int max)

void

setOpenWidth(int width)

void

setTextAt(int index, string text)

Methods of BBjListButton implemented for DropTarget

Return Value Method
int getDropActions()
void setDropActions(int actions)
BBjVector getDropTypes()
void setDropTypes(BBjVector types)

Methods of BBjListButton implemented for Editable

Return Value Method
boolean isEditable()
void setEditable(boolean edit)

Methods of BBjListButton implemented for Focusable

Return Value Method
boolean isFocusable()
void setFocusable(boolean focus)

Methods of BBjListButton implemented for MouseWheelEnabled

Return Value Method
int getScrollWheelBehavior()
void setScrollWheelBehavior(int trav)

Methods of BBjListButton implemented for RecordSetBindable

Return Value Method
void bindRecordSet(BBjRecordSet recordset!, string fieldname)
string getBoundFieldName()

Methods of BBjListButton implemented for RecordSetFillable

Return Value Method
void fillFromRecordSet(BBjRecordSet recordset, string fieldname)

Methods of BBjListButton implemented for SimpleRecordSetBindable

Return Value Method
BBjRecordSet getBoundRecordSet()
void unbindRecordSet()

Methods of BBjListButton implemented for TabTraversable

Return Value Method
boolean isTabTraversable()
void setTabTraversable(boolean trav)

Methods of BBjListButton implemented for TextAlignable

Return Value Method
int getAlignment()
void setAlignment(int align)

Methods of BBjListButton implemented for Validateable

Return Value Method
void accept(boolean valid)
string getValidationText()

Methods of BBjListButton inherited from BBjControl

Events

Callback Code

Object-oriented Event

Read Record Event

Code

ON_CONTROL_VALIDATION

BBjControlValidationEvent

Control Validation Event

v

ON_DROP_TARGET_DROP

BBjDropTargetDropEvent

Drop Target Drop Event

D

ON_GAINED_FOCUS

BBjGainedFocusEvent

Control Focus Gained/Lost Event

f

ON_LIST_CANCEL

BBjListCancelEvent

List Button and List Edit Notify Events

N (Notify code 4)

ON_LIST_CHANGE

BBjListChangeEvent

List Button and List Edit Notify Events

N (Notify code 5)

ON_LIST_CLICK

BBjListClickEvent

List Item Click Event

l (lower case L)

ON_LIST_CLOSE

BBjListCloseEvent

List Button and List Edit Notify Events

N (Notify code 3)

ON_LIST_OPEN

BBjListOpenEvent

List Button and List Edit Notify Events

N (Notify code 1)

ON_LIST_SELECT

BBjListSelectEvent

List Button and List Edit Notify Events

N (Notify code 2)

ON_LOST_FOCUS

BBjLostFocusEvent

Control Focus Gained/Lost Event

f

ON_MOUSE_ENTER

BBjMouseEnterEvent

Mouse Enter/Exit Event

E

ON_MOUSE_EXIT

BBjMouseExitEvent

Mouse Enter/Exit Event

E

ON_POPUP_REQUEST

BBjPopupRequestEvent

Popup Request Event

r

ON_RIGHT_MOUSE_DOWN

BBjRightMouseDownEvent

Right Mouse Button Down Event

R

BUI logoCSS

The visual appearance of BUI controls is defined using CSS (cascading style sheets) rules. Easily change the default colors, border, and other settings by customizing these rules, all without changing any application code. See CSS API for a high-level overview of BUI CSS.

In BBj 13 and higher, the default BUI BBjListButton is implemented as a custom control, to allow for CSS styling that isn't possible with native browser select elements. The native browser select elements can provide a better user experience on mobile phone and tablet browsers; the NATIVE_BROWSER_LIST !OPTIONS setting can be set to TRUE to specify that style.

The native version of the BUI BBjListButton is implemented as a <select> element with the .BBjListButton.bbj-native style name.

In BBj 10 and higher, native style BUI BBjListButton controls don't honor the deselect() method. Applications that depend on this method should set the LISTBUTTON_DESELECT method. Applications that depend on this method should set the LISTBUTTON_DESELECT setting to TRUE. This option has no effect in GUI.

By default, BBj immediately populates BUI list controls (BBjListBox, BBjListButton, BBjListEdit) with all items sent by the program. With very large lists containing many hundreds or thousands of items, this can take a bit of time. In BBj 13 and higher, the list controls can be configured to preload a smaller number of items. For example:

listpagesize$ = stbl("!LIST_PAGE_SIZE","16")

This example tells the BUI list controls to preload only 16 elements, then add more as the user scrolls. If this STBL isn't defined, or if it's set to "0", the BUI list controls preload the entire list.

!LIST_PAGE_SIZE doesn't apply to GUI, and it doesn't apply to the NATIVE_BROWSER_LIST versions of the BUI list controls.

The custom listbutton defines the following style names:

.BBjListButton (the top level control)

.BBjListButton-button (the button face)

.BBjListButton-buttonText (the left side of the button, which contains the text label)

.BBjListButton-imageWrapper (the right side of the button, which contains the dropdown arrow)

.BBjListButton-image (the dropdown arrow image)

.BBjListButton-listPanel (the dropdown container for the list)

.BBjListButton-listBox (the dropdown list)

.BBjListButton-item(an individual item in the dropdown list)

.BBjListButton-item.bbj-selected(the selected item)

.BBjListButton.bbj-disabled(the control is disabled)

.BBjListButton.bbj-focused(the control is focused)

.BBjListButton.bbj-readonly(the control is read only)

This section uses the list sample from the BBj BUI Showcase (code, demo).

With the default styles, the custom BBjListButton looks like this:

With the styles shown below, it looks like this:

 

.BBjListButton, .BBjListButton-button, .BBjListEdit-button

{

  color: white !important;

  box-shadow: 2px 2px 5px hsla(0,0%,0%,.7);

  text-shadow: 0px 0px 1px hsla(0,0%,0%,.8);

  border-radius: 5px;

  background: navy !important;

  background-image: -webkit-radial-gradient(160% 100% at 50% 0% ,hsla(0,0%,100%,.3) 50%,hsla(0,0%,100%,0) 52%) !important;

  background-image: radial-gradient(160% 100% at 50% 0% ,hsla(0,0%,100%,.3) 50%,hsla(0,0%,100%,0) 52%) !important;

  overflow: hidden;

}

.BBjListEdit

{

  border-radius: 5px;

}

.BBjListEdit-button

{

  border-width: 0px;

}

.BBjListButton-image, .BBjListEdit-image

{

  border-top-color: white;

}

.BBjListButton-listBox, .BBjListEdit-listBox

{

  overflow-x: hidden !important;

  box-shadow: 2px 2px 5px hsla(0,0%,0%,.7);

Remarks

In BBj 5 and higher, typing into a BBjListButton control accumulates keystrokes entered within a specified number of milliseconds into a typeahead buffer. This allows the user, for example, to jump directly to New York in a list of all 50 states by quickly typing "NY". Without this typeahead buffer, the user would have to press "N" eight times to skip past the other state codes beginning with "N." The default time window for this feature is 1000 milliseconds (1 second). The !LISTSEARCH global overrides that timeout value; a setting of zero effectively disables this buffer.

In BBj 13.00 and higher, the LISTBUTTON_AUTO_SELECT !OPTIONS setting can be set to TRUE to select the Visual PRO/5 default behavior of auto-selecting index 0 when items are added to a previously empty list. The default behavior in BBj is to not auto-select index 0.

In BBj 13.01 and higher, the LISTBUTTON_SELECT !OPTIONS setting can be set to TRUE to auto-select index 0 when creating a non-empty BBjListButton. The default behavior is to not auto-select index 0 on creation.

Constants inherited from BBjControl

Example

rem 'Add a list button control to a window

rem 'Obtain the instance of the BBjAPI object
let myAPI! = BBjAPI()

rem 'Open the SysGui device
SYSGUI = UNT
OPEN (SYSGUI) "X0"

rem 'Obtain the instance of the BBjSysGui object
let mySysGui! = myAPI!.getSysGui()

rem 'Set addWindow param values
X = 10
Y = 10
WIDTH = 200
HEIGHT = 200
TITLE$="BBj Window"

rem 'Set the current context
mySysGui!.setContext(0)

rem 'Create a window
myWindow! = mySysGui!.addWindow(X,Y,WIDTH,HEIGHT,TITLE$)

rem 'Add a list button control to the window
myListButton! = myWindow!.addListButton(101,50,100,90,60,"",$0000$)

rem 'Add items into the list button
FOR I = 1 TO 4
    ITEM$="ITEM " + STR(I)
    myListButton!.addItem(ITEM$)
NEXT I

rem 'Register the CALLBACK routines
CALLBACK(ON_LIST_SELECT,LIST_ITEM_SELECTED,mySysGui!.getContext(),myListButton!.getID())
CALLBACK(ON_CLOSE,APP_CLOSE,mySysGui!.getContext())

rem 'Process Events
process_events

rem 'Callback routine called when the user selects an item in the list button
LIST_ITEM_SELECTED:
    rem 'Display a message with the select list button item
    MESSAGE$="The item selected is: " + STR(myListButton!.getItemAt(myListButton!.getSelectedIndex()))
    let X = MSGBOX(MESSAGE$)
return

rem 'Callback routine called when the user closes the application window
APP_CLOSE:
release

See Also

BBjAPI

BBjSysGui

BBjWindow

LISTBUTTON Mnemonic - Create a List Button Control

CALLBACK Verb - Register BBj Subroutine

DWC Component: dwc-choicebox

See the BBj Object Diagram for an illustration of the relationship between BBj Objects.