-
Notifications
You must be signed in to change notification settings - Fork 2
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.
First import the service using one of the release binaries or via Servoy's Web Package Manager.
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 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 callback function is receiving the following parameters:
Params
Type | Name | Summary |
---|---|---|
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) |
Add new menu to existing menubar
Params
Type | Name | Summary | Required |
---|---|---|---|
string | text | Menu label | Required |
index | int | Insert position | Optional |
Remove specified menu
Params
Type | Name | Summary | Required |
---|---|---|---|
index | int | Menu index (zero based) | Required |
Return the index order of the menu (zero based index)
Params
Type | Name | Summary | Required |
---|---|---|---|
string | text | Menu label to query | Required |
Return the menu label
Params
Type | Name | Summary | Required |
---|---|---|---|
int | index | Index to query | Required |
Count menus from the menubar
Cleanup the menubar. For Mac OS this means to display a minimal menu.
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 |
Cleanup the specified menu
Params
Type | Name | Summary | Required |
---|---|---|---|
int | index | Menu index to cleanup | Required |
Add a separator line
Params
Type | Name | Summary | Required |
---|---|---|---|
int | index | Menu index | Required |
int | position | Insert position | Optional |
int | itemIndex | Submenu index | Optional |
Add an item to the specified menu
Params
Type | Name | Summary | Required |
---|---|---|---|
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 |
Delete an item
Params
Type | Name | Summary | Required |
---|---|---|---|
int | index | Menu index | Required |
int | position | Insert position | Required |
int | itemIndex Submenu index | Optional |
Count items
Params
Type | Name | Summary | Required |
---|---|---|---|
int | index | Menu index | Required |
int | itemIndex | Submenu index | Optional |
Add a checkbox to the specified menu
Params
Type | Name | Summary | Required |
---|---|---|---|
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 |
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
Type | Name | Summary | Required |
---|---|---|---|
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 |
Get menuitem index from the specified menu
Params
Type | Name | Summary | Required |
---|---|---|---|
int | index | Menu index | Required |
string | text | Item label to query for | Required |
Get menuitem label
Params
Type | Name | Summary | Required |
---|---|---|---|
int | index | Menu index | Required |
int | itemIndex | Menuitem index | Required |
Roles allow menu items to have predefined behaviors. Params
Type | Name | Summary | Required |
---|---|---|---|
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.