BBjMenuButton

Description

In BBj 7.00 and higher, the BBjMenuButton object provides methods for manipulating a rollover-style button control with an optional dropdown menu.

Implemented Interfaces

In BBj 7.00 and higher: DropTarget, Injectable, TextAlignable

In BBj 15.00 and higher: DragSource, Focusable, TabTraversable

Creation

BBjAPI > BBjSysGui > BBjWindow > BBjMenuButton

A BBjMenuButton object is created through the following BBjWindow methods:

Return Value	Method
BBjMenuButton	addMenuButton(int ID, number x, number y, number w, number h, string title)
BBjMenuButton	addMenuButton(int ID, number x, number y, number w, number h, string title, string flags)
BBjMenuButton	addMenuButton(int ID, String title)
BBjMenuButton	addMenuButton(int ID, String title), String flags)
BBjMenuButton	addMenuButton(String title)
BBjMenuButton	addMenuButton(String title), String flags)

Methods of BBjMenuButton

Return Value	Method
BBjPopupMenu	addDropdownMenu()
void	clearImageSize()
boolean	getBeep()
boolean	getDisableOnClick()
int	getDropdownButtonWidth()
BBjPopupMenu	getDropdownMenu()
string	getImageFile()
int	getImageHeight()
int	getImageWidth()
boolean	isBorderPainted()
boolean	isDropdownMenuVisible()
void	removeDropdownMenu()
void	setBeep(boolean `beep`)
void	setBorderPainted(boolean `paint`)
void	setDisableOnClick(boolean `disable`)
void	setDropdownMenu(BBjPopupMenu `dropdownMenu`)
void	setDropdownMenuVisible(boolean `visible`)
void	setDropdownButtonWidth(number `width`)
void	setImage(BBjImage `image`)
void	setImageFile(string `file`)
void	setImageSize(number `height`, int `width`)

Methods of BBjMenuButton implemented for DragSource

Return Value	Method
int	getDragActions()
sting	getDragType()
void	setDragActions(int `actions`)
void	setDragType(string `type`)

Methods of BBjMenuButton implemented for DropTarget

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

Methods of BBjMenuButton implemented for Focusable

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

Methods of BBjButton implemented for Injectable

Return Value	Method
string	getInjectString()
void	setInjectString(string `injectString`)

Methods of BBjMenuButton implemented for TabTraversable

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

Methods of BBjMenuButton implemented for TextAlignable

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

Methods of BBjMenuButton inherited from BBjControl

Return Value	Method
void	addClass(string `className`)
BBjPopupMenu	addPopupMenu()
boolean	addStyle(string `styleName`)
void	clearCallback(int `eventType`)
void	clearStyles()
void	destroy()
void	focus()
string	getAttribute(string `attribute`)
BBjColor	getBackColor()
boolean	getBeepOnValidationFailure()
boolean	getCausesControlValidation()
boolean	getClientEdge()
BBjVector	getClassList()
Object	getClientProperty(Object `key`)
string	getComputedStyle(string `property`)
int	getContextID()
int	getControlType()
BBjFont	getFont()
BBjColor	getForeColor()
int	getHeight()
int	getID()
string	getLongCue()
string	getName()
boolean	getNoEdge()
BBjWindow	getParentWindow()
BBjPopupMenu	getPopupMenu()
Object	getProperty(String `key`)
Object	getProperty(String `key`, Type `type`)
boolean	getRaisedEdge()
int	getScreenX()
int	getScreenY()
string	getShortCue()
string	getStyle(string `property`)
bBjVector	getStyles()
string	getText()
string	getToolTipText()
Object	getUserData()
int	getWidth()
int	getX()
int	getY()
boolean	isDestroyed()
boolean	isEnabled()
boolean	isGrouped()
boolean	isOpaque()
boolean	isVisible()
void	putClientProperty(Object `key`, Object `value`)
void	removeAttribute(string `attribute`)
void	removeClass(string `className`)
void	removePopupMenu()
boolean	removeStyle(string `styleName`)
void	setAttribute(string `attribute`, string `value`)
void	setBackColor(BBjColor `color!`)
void	setBeepOnValidationFailure(boolean `shouldBeep`)
void	setCallback(int `eventType`, CustomObject `customObj`, string `methodName`)
void	setCallback(int `eventType`, string `subRoutineName`)
void	setCausesControlValidation(boolean `valid`)
void	setClientEdge(boolean `client`)
void	setCursor(int `cursor`)
void	setEnabled(boolean `enabled`)
void	setFont(BBjFont`font!`)
void	setForeColor(BBjColor `color!`)
void	setGrouped(boolean `grouped`)
void	setLocation(int `x`, int `y`)
void	setLongCue(string `cue`)
void	setName(string `name`)
void	setNoEdge(boolean `noEdge`)
void	setOpaque(boolean `opaque`)
void	setPopupMenu(BBjPopupMenu `popupMenu!`)
void	setProperty(String `key`, Object `value`)
void	setProperty(String `key`, Object `value`, Type `type`)
void	setRaisedEdge(boolean `raised`)
void	setShortCue(string `cue`)
void	setSize(int `width`, int `height`)
void	setSlot(BBjControl `control`)
void	setSlot(String `slot`, BBjControl `control`)
void	setStyle(string `property`, string `value`)
void	setText(string `text`)
void	setToolTipText(string `text`)
void	setUserData(Object `userData`)
void	setVisible(boolean `visible`)
void	showToolTipText() showToolTipText(int `x`, int `y`)
boolean	toggleClass(string `className`)
void	unsetStyle(string `property`)

Events

Callback Code	Object-oriented Event	Read Record Event	Code
ON_BUTTON_PUSH	BBjButtonPushEvent	Push Button Event	B
ON_DROP_TARGET_DROP	BBjDropTargetDropEvent	Drop Target Drop Event	D
ON_FORM_VALIDATION	BBjFormValidationEvent	Form Validation Event	V
ON_GAINED_FOCUS	BBjGainedFocusEvent	Control Focus Gained/Lost Event	f
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

CSS

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.

The BBjMenuButton can be used in several different ways. With a dropdown menu, it combines a button and menu in a single control. If no menu is defined, it acts as a rollover button that has a more noticeable appearance as the user hovers over it. Here's a very basic sample program, showing just a few of these variations:

sysgui = unt

open (sysgui)"X0"

sysgui! = bbjapi().getSysGui()

image$ = "com/basis/bbj/images/basis-b.gif"

image! = sysgui!.getImageManager().loadImageFromServerJar(image$)

window! = sysgui!.addWindow(50,50,200,200,"BBjMenuButton",$00090003$)

window!.setCallback(window!.ON_CLOSE,"eoj")

menubutton1! = window!.addMenuButton(101,25,25,150,50,"MenuButton",$$)

menubutton1!.setImage(image!)

menubutton2! = window!.addMenuButton(102,25,100,150,50,"MenuButton",$4000$)

menubutton2!.setImage(image!)

dropdownMenu! = sysgui!.addPopupMenu()

dropdownItem1! = dropdownMenu!.addMenuItem(-201,"Dropdown Item 1")

dropdownItem2! = dropdownMenu!.addMenuItem(-202,"Dropdown Item 2")

menuButton2!.setDropdownMenu(dropdownMenu!)

process_events

eoj:

release

With the default CSS styles, it looks like this:

The BBjMenuButton defines the following style names:

Style Name	Description
.BBjMenuButton	The top level control.
.BBjMenuButton-button	The main button area.
.BBjMenuButton-button-down-hovering	The main button area when pressed by the user.
.BBjMenuButton-button-up-hovering	The main button area when the user is hovering over it.
.BBjMenuButton-dropdown	The dropdown button on the right edge -- if the button has a dropdown.
.BBjMenuButton-dropdown-down-hovering	The dropdown button area when pressed by the user.
.BBjMenuButton-dropdown-up-hovering	The dropdown button area when the user is hovering over it.
.BBjMenuButton-dropdown-image	The dropdown button image.
.BBjMenuButton-menu	The dropdown menu.
.BBjMenuButton.bbj-bordered	The BBjMenuButton was created with a permanent border.
.BBjMenuButton.bbj-disabled	The BBjMenuButton disabled.
.BBjMenuButton.bbj-focused	The BBjMenuButton is focused.
.BBjMenuButton.bbj-dropdown	The BBjMenuButton has a dropdown menu.

Remarks

By default, menu buttons are not focusable or tab traversable. In BBj 15 and higher, applications that require all menu buttons to be focusable can set the MENUBUTTON_FOCUSABLE !COMPAT setting to TRUE. Applications that require all menu buttons to be tab traversable can set the MENUBUTTON_TAB_TRAVERSABLE !COMPAT setting to TRUE.

Mobile touch-oriented browsers (e.g. Mobile Safari in iOS, Chrome in Android) wait for 300 milliseconds after the user taps an element before generating a click event. This delay makes applications feel sluggish when the user tries to click on multiple buttons in rapid sequence, a process that can be common in applications like phone dialers. When the FAST_TOUCH_CLICK !OPTIONS setting is set to TRUE, BUI menu buttons on iOS and Android report ON_BUTTON_PUSH immediately when the user touches and releases their finger from a button. This improves the responsiveness for those events, but introduces some side effects that the developer should be aware of. Because BUI is handling touch events on these buttons, normal double-tap and pinch-zoom gestures don't work. And because BUI is reporting the ON_BUTTON_PUSH event immediately, it appears in the event stream before the button reports gaining focus. Some applications are sensitive to precise sequence of events.

Constants inherited from BBjControl

Value	Control Constant
-1	UNKNOWN_CONTROL
0	WINDOW
1	MAIN_WINDOW
2	CHILD_WINDOW
3	MENU
4	SPECIAL_CONTROL
5	NATIVE_CONTROL
11	PUSHBUTTON_CONTROL
12	RADIOBUTTON_CONTROL
13	CHECKBOX_CONTROL
14	HSCROLL_CONTROL
15	VSCROLL_CONTROL
16	EDIT_CONTROL
17	TEXT_CONTROL
18	LISTBOX_CONTROL
19	LISTBUTTON_CONTROL
20	LISTEDIT_CONTROL
21	GROUPBOX_CONTROL
22	CEDIT_CONTROL
24	LINECHART_CONTROL
25	BARCHART_CONTROL
26	PIECHART_CONTROL
27	HTMLVIEW_CONTROL
28	MENUBUTTON_CONTROL
29	PRINTPREVIEW_CONTROL
30	GENERICCHART_CONTROL
31	WRAPPED_JCOMPONENT_CONTROL
32	WEB_COMPONENT_CONTROL
91	INPUTT_CONTROL
92	INPUTT_SPINNER_CONTROL
99	SPLITTER_CONTROL
100	MENUITEM_CONTROL
101	CHECKABLE_MENUITEM_CONTROL
102	STATUSBAR_CONTROL
103	TOOLBUTTON_CONTROL
104	INPUTE_CONTROL
105	INPUTN_CONTROL
106	TAB_CONTROL
107	GRID_CONTROL
108	IMAGE_CONTROL
109	TREE_CONTROL
110	DATAAWARE_GRID_CONTROL
112	PROGRESS_CONTROL
113	NAVIGATOR_CONTROL
114	INPUTD_CONTROL
115	NAMESPACE_CONTROL
116	GRID_HEADER_CONTROL
117	HSLIDER_CONTROL
118	VSLIDER_CONTROL
119	FILECHOOSER_CONTROL
120	COLORCHOOSER_CONTROL
121	FONTCHOOSER_CONTROL
122	DATABOUND_GRID_CONTROL
123	INPUTD_SPINNER_CONTROL
124	INPUTE_SPINNER_CONTROL
125	INPUTN_SPINNER_CONTROL
126	EDIT_SPINNER_CONTROL
127	HTMLEDIT_CONTROL

Example

rem 'Create a BBjMenuButton

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

rem 'Open the SysGui device
SYSGUI = UNT
OPEN (SYSGUI)"X0"
DIM EVENT$:TMPL(SYSGUI)

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

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

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

rem 'Create a window with a title in the current context
myWindow! = mySysGui!.addWindow(X,Y,WIDTH,HEIGHT,TITLE$)

rem 'Create BBjMenuButtons
menuButton1! = myWindow!.addMenuButton(101,0,0,100,22,"MenuButton1")
menuButton2! = myWindow!.addMenuButton(102,100,0,100,22,"MenuButton2")

rem 'Create a dropdown menu
myDropdownMenu! = mySysGui!.addPopupMenu()
myDropdownItem1! = myDropdownMenu!.addMenuItem(-201,"Dropdown Item 1")
myDropdownItem2! = myDropdownMenu!.addMenuItem(-202,"Dropdown Item 2")

rem 'Associate dropdown menu with the buttons
menuButton1!.setDropdownMenu(myDropdownMenu!)
menuButton2!.setDropdownMenu(myDropdownMenu!)

rem 'Create a popup menu
myPopupMenu! = mySysGui!.addPopupMenu()
myPopupItem1! = myPopupMenu!.addMenuItem(-301,"Popup Item 1")
myPopupItem2! = myPopupMenu!.addMenuItem(-302,"Popup Item 2")

rem 'Associate popup menu with the buttons
menuButton1!.setPopupMenu(myPopupMenu!)
menuButton2!.setPopupMenu(myPopupMenu!)

rem 'Register the CALLBACK routines
CALLBACK(ON_BUTTON_PUSH,MenuButton1,mySysGui!.getContext(),MenuButton1!.getID())
CALLBACK(ON_BUTTON_PUSH,MenuButton2,mySysGui!.getContext(),MenuButton2!.getID())
CALLBACK(ON_POPUP_ITEM_SELECT,DropdownItem1,myDropdownMenu!.getID(),myDropdownItem1!.getID())
CALLBACK(ON_POPUP_ITEM_SELECT,DropdownItem2,myDropdownMenu!.getID(),myDropdownItem2!.getID())
CALLBACK(ON_POPUP_ITEM_SELECT,PopupItem1,myPopupMenu!.getID(),myPopupItem1!.getID())
CALLBACK(ON_POPUP_ITEM_SELECT,PopupItem2,myPopupMenu!.getID(),myPopupItem2!.getID())
CALLBACK(ON_CLOSE,APP_CLOSE,mySysGui!.getContext())

rem 'Process Events
process_events

rem 'Callback routine invoked when the user clicks the button
MenuButton1:
    event! = mySysGui!.getLastEvent()
    event$ = mySysGui!.getLastEventString()
    i = msgbox("MenuButton1 was clicked")
return

rem 'Callback routine invoked when the user clicks the button
MenuButton2:
    event! = mySysGui!.getLastEvent()
    event$ = mySysGui!.getLastEventString()
    i = msgbox("MenuButton2 was clicked")
return

rem 'Callback routine invoked when the user selects the first dropdown item
DropdownItem1:
    event! = mySysGui!.getLastEvent()
    event$ = mySysGui!.getLastEventString()
    i = msgbox("Dropdown Item 1 was selected on "+event!.getControl().getText())
return

rem 'Callback routine invoked when the user selects the second dropdown item
DropdownItem2:
    event! = mySysGui!.getLastEvent()
    event$ = mySysGui!.getLastEventString()
    i = msgbox("Dropdown Item 2 was selected on "+event!.getControl().getText())
return

rem 'Callback routine invoked when the user selects the first popup item
PopupItem1:
    event! = mySysGui!.getLastEvent()
    event$ = mySysGui!.getLastEventString()
    i = msgbox("Popup Item 1 was selected on "+event!.getControl().getText())
return

rem 'Callback routine invoked when the user selects the second popup item
PopupItem2:
    event! = mySysGui!.getLastEvent()
    event$ = mySysGui!.getLastEventString()
    i = msgbox("Popup Item 2 was selected on "+event!.getControl().getText())
return

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