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 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) {
}
function addRecentFiles(menuIndex, submenuIndex) {
}
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
The following sample will create a custom tray menu for NG Desktop:
function createTrayMenu(event) {
}
function trayCallback(itemName, itemType, itemStatus) {
}
API Documentation
Callback function
The callback function is receiving the following parameters:
Params
string
text
clicked item name
string
type
clicked item type ("normal", "checkbox", "radio")
boolean
checked
check state (true or false for checkboxes, true for radio buttons and undefined for the other types)
Method Summary
addMenu
Add new menu to existing menubar
Params
string
text
Menu label
Required
index
int
Insert position
Optional
removeMenu
Remove specified menu
Params
index
int
Menu index (zero based)
Required
addDevToolsMenu
Add Developer Tools menu to the menu bar. Use it just for debugging. Remove any call to this function once you're done.
getMenuIndexByText
Return the index order of the menu (zero based index)
Params
string
text
Menu label to query
Required
getMenuText
Return the menu label
Params
int
index
Index to query
Required
getMenuCount
Count menus from the menubar
removeAllMenus
Cleanup the menubar. For Mac OS this means to display a minimal menu.
setMenuBarVisibility
Show/Hide menu bar. On MacOS this method has no effect
Params
boolean
visibility
true - show menubar, false - hide menubar
Required
removeAllMenuItems
Cleanup the specified menu
Params
int
index
Menu index to cleanup
Required
addSeparator
Add a separator line
Params
int
index
Menu index
Required
int
position
Insert position
Optional
int
itemIndex
Submenu index
Optional
addMenuItem
Add an item to the specified menu
Params
int
index
Menu index
Required
string
text
Menu label
Required
function
callback
Callback function
Required (may be null)
int
position
Insert position
Optional
int
itemIndex Submenu index
Optional
removeMenuItem
Delete an item
Params
int
index
Menu index
Required
int
position
Insert position
Required
int
itemIndex Submenu index
Optional
getMenuItemsCount
Count items
Params
int
index
Menu index
Required
int
itemIndex
Submenu index
Optional
addCheckBox
Add a checkbox to the specified menu
Params
int
index
Menu index
Required
string
text
Menu label
Required
function
callback
Callback function
Required (may be null)
boolean
checked
initial checkbox status (default is false)
Optional
int
position
Insert position
Optional
int
itemIndex Submenu index
Optional
addRadioButton
Add a radio button to the specified menu. Note that the first added radio button in the group is alwasy selected regardless the 'selected' value There are no group creation method. A group consist from all adiacent radio buttons in a menu
Params
int
index
Menu index
Required
string
text
Menu label
Required
function
callback
Callback function
Required (may be null)
boolean
selected
select radio button (default is false)
Optional
int
position
Insert position
Optional
int
itemIndex Submenu index
Optional
getMenuItemIndexByText
Get menuitem index from the specified menu
Params
int
index
Menu index
Required
string
text
Item label to query for
Required
getMenuItemText
Get menuitem label
Params
int
index
Menu index
Required
int
itemIndex
Menuitem index
Required
addRoleItem
Roles allow menu items to have predefined behaviors.
Params
int
index
Menu index
Required
string
role
The item role (see below)
Required
string
text
The item label
Optional
int
position
Insert position
Optional
int
itemIndex
Submenu index
Optional
It is best to specify role for any menu item that matches a standard role, rather than trying to manually implement the behavior using a callback function. The built-in role behavior will give the best native experience.
The role property can have following values:
undo
about - Trigger a native about panel (custom message box on Window, which does not provide its own).
redo
cut
copy
paste
pasteAndMatchStyle
selectAll
delete
minimize - Minimize current window.
close - Close current window.
quit - Quit the application.
reload - Reload the current window.
forceReload - Reload the current window ignoring the cache.
toggleDevTools - Toggle developer tools in the current window.
togglefullscreen - Toggle full screen mode on the current window.
resetZoom - Reset the focused page's zoom level to the original size.
zoomIn - Zoom in the focused page by 10%.
zoomOut - Zoom out the focused page by 10%.
fileMenu - Whole default "File" menu (Close / Quit)
editMenu - Whole default "Edit" menu (Undo, Copy, etc.).
viewMenu - Whole default "View" menu (Reload, Toggle Developer Tools, etc.)
windowMenu - Whole default "Window" menu (Minimize, Zoom, etc.).
The following additional roles are available on macOS:
appMenu - Whole default "App" menu (About, Services, etc.)
hide - Map to the hide action.
hideOthers - Map to the hideOtherApplications action.
unhide - Map to the unhideAllApplications action.
startSpeaking - Map to the startSpeaking action.
stopSpeaking - Map to the stopSpeaking action.
front - Map to the arrangeInFront action.
zoom - Map to the performZoom action.
toggleTabBar - Map to the toggleTabBar action.
selectNextTab - Map to the selectNextTab action.
selectPreviousTab - Map to the selectPreviousTab action.
mergeAllWindows - Map to the mergeAllWindows action.
moveTabToNewWindow - Map to the moveTabToNewWindow action.
window - The submenu is a "Window" menu.
help - The submenu is a "Help" menu.
services - The submenu is a "Services" menu. This is only intended for use in the Application Menu and is not the same as the "Services" submenu used in context menus in macOS apps, which is not implemented in Electron.
recentDocuments - The submenu is an "Open Recent" menu.
clearRecentDocuments - Map to the clearRecentDocuments action.
createBrowserView
Creates a BrowserView (looks like an iframe) and adds this to the current window at the given coordinates with the given width and height. It returns and id that can be used to close/clean up this view later on, or to target that view to inject some javascript.
Params
int
x
The X coordinate to position this view
Required
int
y
The Y coordinate to position this view
Required
int
width
The width of this view
Required
int
height
The height of this view
Required
string
url
The url to load into this view
Required
closeBrowserView
Closes a and destroys a previously created BrowserView by the given id.
Params
int
id
The id of the view to close
Required
injectJSIntoBrowserView
Injects the given javascript into the content of the BrowserView of the given id. The javascript can be a function declaration that is then called later on. The last statement return value is given back to the callback as a first argument. If something goes wrong then the callback is called where the first argument is null and a second argument has the message of the exception.
Params
int
id
The id of the view to execute javascript in
Required
string
js
The piece of javascript that is injected into this view
Required
function
callback
the callback function that is used to get the results or exception if the call fails
Required
createTrayMenu
Return a TrayMenu object type.
TrayMenu properties
Type | Name | Summary | Required string | title | tray menu title displayed next to the tray icon | Optional string | tooltip | just a tooptip | Optional byte[] | icon | icon to be displayed in the tray | Optional byte[] | pressedIcon | icon to be displayed when opening the tray (MacOS only) | Optional
TrayMenu api
This methods are available only through the TrayMenu object - trayMenu.method(params). The autocompletion is not yet available
Callback function
The callback function is receiving the following parameters:
string
text
clicked item name
Required
string
type
clicked item type ("normal", "checkbox")
Required
boolean
checked
check state (true or false for checkboxes, false otherwise)
Required
addMenuItem
Add item to the tray menu
int
index
zero based index where to add / insert items in tray menu
Required
string
text
menu item text
Required
function
callback
Callback function
Required
removeMenuItem
int
index
zero based index of the item to be removed
Required
addCheckBox
int
index
zero based index where to add / insert items in tray menu
Required
string
text
menu item text
Required
function
callback
Callback function
Required
boolean
checked
Initial status of the checkbox
Required
addSeparator
Params
int
index
zero based index of the position where to add / insert the separator
Required
addRoleItem
Add a tray menu item with predefined (system) behavior. For details, check the documentation for the addRoleItem method above (for NG Desktop menu)
Params
int
index
zero based index of the position where to add / insert role
Required
string
role
The item role (see above ethod with the same name)
Required
string
text
Role label
Optional
done
When all desired changes to the tray menu are finalized, call this method for the changes to takes effect.
Example Usage
// open google.com var id = plugins.ngdesktopui.createBrowserView(100,200,700,500,"https://www.google.com/"); // get the value of the search field and return this. plugins.ngdesktopui.injectJSIntoBrowserView(id, "function test() { return document.getElementsByName('q')[0].value};test();", callback);
Last updated