NGDesktop UI plugin

Welcome to the ngdesktopui wiki! This wiki provides comprehensive documentation to using the ngdesktopui web service. This service works with the NGDesktop Client as a bridge to execute client side calls dealing with UI from Servoy.

Getting Started

First import the service using one of the release binaries or via Servoy's Web Package Manager.

Example Usage

The following code snippet is create a sample menu for NGDesktop:

function createTestMenu(event) { var isMac = application.getOSName().toUpperCase().indexOf('MAC')>=0; var menu = plugins.ngdesktopui; menu.removeAllMenus(); var ngdesktopIndex = menu.addMenu("Servoy NGDesktop"); //on MacOS this name is hidden menu.addMenuItem(ngdesktopIndex,"About Servoy NGDesktop...",callback); menu.addSeparator(ngdesktopIndex); menu.addRoleItem(ngdesktopIndex,"services"); menu.addSeparator(ngdesktopIndex); if (isMac) { menu.addRoleItem(ngdesktopIndex,"hide", "Hide this application"); menu.addRoleItem(ngdesktopIndex,"hideOthers"); menu.addSeparator(ngdesktopIndex); } menu.addRoleItem(ngdesktopIndex,"quit");

//add file menu
var fileIndex = menu.addMenu("File");
menu.addMenuItem(fileIndex,"New",callback);
menu.addMenuItem(fileIndex,"Open...",callback);

//insert menuitem example
//since this will be a submenu the callback is set to null
recentIndex = menu.addMenuItem(fileIndex,"Open recent", null, 1);
addRecentFiles(fileIndex, recentIndex);

//add edit menu
var editIndex = menu.addMenu("Edit");
menu.addRoleItem(editIndex,"undo");
menu.addRoleItem(editIndex,"redo");
menu.addSeparator(editIndex);
menu.addRoleItem(editIndex,"cut");
menu.addRoleItem(editIndex,"copy");
menu.addRoleItem(editIndex,"paste");

//add help menu
var helpIndex = menu.addMenu("Help");
menu.addMenuItem(helpIndex,"Search...",callback);
menu.addMenuItem(helpIndex,"Servoy NGDesktop help",callback)

}

function addRecentFiles(menuIndex, submenuIndex) { var menu = plugins.ngdesktopui; var position = menu.addMenuItem(menuIndex,"Bureau.pdf",callback, 0, submenuIndex); position = menu.addMenuItem(menuIndex,"Advertising.pdf",callback, position + 1, submenuIndex); position = menu.addSeparator(menuIndex,position + 1, submenuIndex); position = menu.addRoleItem(menuIndex,"clearRecentDocuments", null, position + 1,submenuIndex); }

The callbackFunction is receiving the following parameters:

• {string} itemName - the text of the clicked item
• {string} type - "normal", "checkbox", "radio"
• {boolean} checked - true or false for checkbox, true for radio buttons and undefined for the other types.

The following issues has been discovered so far:

• setMenuBarVisibility has no effect on MacOS. You can't hide a MacOS menu
• removeAllMenus - for MacOS is display a minimal menu having the app name as Menu name and Quit option as menuItem
• on macOS - the first menuName is always the app name: first addMenu(menuName) will not display the "menuName" but the app name. The name behind (which you will work with), still remain "menuName"
• on MacOS - the checkboxes and radio buttons in menus are not correctly rendered. This seems to be a Chromium issue. Further investigation needed for this
• When clicking on a radio button - it will be selected, and the previous radio buttons (from the adiacent radio items) will be deselected. However, calling multiple times addRadioButton(menuName, menuitemName, true) will add multiple selected radio buttons (they will unselect automatically when one radio button is selected). It is your responsability to call addRadioButton() with "selected" parameter set to true - only once. The same issue is true also for insertRadioButton

API Documentation

Method Summary

addMenu

Add new menu to existing menubar

Params

Type	Name	Summary	Required
string	menuName	Menu name to add	Required

insertMenu

Add new menu at the specified position

Params

Type	Name	Summary	Required
string	menuName	Menu name to insert	Required

removeMenu

Remove specified menu

getMenuIndexByName

Return the index order of the menu (zero based index)

Params

Type	Name	Summary	Required
string	menuName	Menu name to query	Required

getMenuNameByIndex

Return the menu name ar the specified (zero based) index. This is usefull on MacOS where the first menu name is hidden by the app name by default. using `plugins.ngdesktopui.getMenuNameByIndex(0) will return the menu name behind

Params

Type	Name	Summary	Required
int	index	Index to query for the name	Required

getMenuCount

Count menus from the menubar

addMenuItem

Add an item to the specified menu

Params

Type	Name	Summary	Required
string	menuName	Menu where to add the item	Required
string	menuitemName	Item name	Required
function	callback	callback function	Optional

insertMenuItem

Insert an item to the specified menu at the requested position Params

Type	Name	Summary	Required
int	index	Position to insert the index	Required
string	menuName	Menu where to insert the item	Required
string	menuitemName	Item name	Required
function	callback	callback function	Optional

removeMenuItem

Delete an item base on item name

Params

Type	Name	Summary	Required
string	menuName	Menu where to remove the item	Required
string	menuitemName	Item name to be removed	Required

removeMenuItemByIndex

Delete an item based on index. It is usefull to remove separator items (which have no name)

Params

Type	Name	Summary	Required
int	index	Item index to be removed	Required
string	menuName	Menu where to remove the item	Required

getMenuItemsCount

Count items Params

Type	Name	Summary	Required
string	menuName	Menu where to count the items	Required

removeAllMenuItems

Cleanup the specified menu Params

Type	Name	Summary	Required
string	menuName	Menu to cleanup	Required

removeAllMenus

Cleanup the menu bar. On MacOS that means a minimal menu is displayed

setMenuBarVisibility

Show/Hide menu bar. On MacOS this method has no effect Params

Type	Name	Summary	Required
boolean	visibility	true - show menubar, false - hide menubar	Required

addCheckBox

Add a checkbox Params

Type	Name	Summary	Required
string	menuName	Menu where to add the item	Required
string	checkboxLabel	Item name	Required
boolean	checked	whether check box is checked	required
function	callback	callback function	Optional

addRadioButton

Add a radio button Params

Type	Name	Summary	Required
string	menuName	Menu where to add the item	Required
string	radioButtonLabel	Item name	Required
boolean	select	whether radio button is selected	required
function	callback	callback function	Optional

insertCheckBox

Insert checkbox at the specified position. Params

Type	Name	Summary	Required
int	index	Index where to insert the checkbox	required
string	menuName	Menu where to add the item	Required
string	checkboxLabel	Item name	Required
boolean	checked	whether check box is checked	required
function	callback	callback function	Optional

insertRadioButton

Insert a radio button at the specified position

Params

Type	Name	Summary	Required
int	index	Index where to insert the radio button	required
string	menuName	Menu where to add the item	Required
string	radioButtonLabel	Item name	Required
boolean	select	whether radio button is selected	required
function	callback	callback function	Optional

addSeparator

Add a separator line

insertSeparator

insert a separator line