Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Liferay Nativity is a cross-platform library for adding icon overlays and context menus to file browsers.
Objective-C C++ Java C# Batchfile C Other

Liferay Nativity

Table of Contents


Liferay Nativity is a cross-platform library for adding icon overlays and context menus to file browsers.

The following operating systems are currently supported:

  • Windows Vista or greater (tested up to Windows 8)
  • Mac OS X 10.7 or greater (tested up to OS X 10.8.4)
  • Linux GNOME Nautilus 3.x or greater (tested up to Nautilus 3.6)

Currently the client code is only available for Java. Contributions for other clients like Ruby, C++, etc are welcome.

Native Plugins

Mac OS X

As of OS X 10.10 Yosemite, overlay icons and context menus are officially supported through the new Finder Sync API. A sample Finder Sync plugin is included which continues to work within the existing Nativity architecture.

Liferay Nativity continues to work for OS X 10.9 and below. This code has been moved to the Injector folder.

Finder Sync

As of OS X 10.10 Yosemite, Apple has finally added an API for extending Finder with plugins. The benefits of using the new Finder Sync API are significant (future-proof supported API, separate process eliminates Finder crashes, performance, etc), so developers are strongly advised to make use of this new API.

Build and Deployment

After cloning the liferay-nativity project, open LiferayShellApp.xcodeproj. Configure the appropriate signing identities and build. The LiferayShellApp can be ignored as it is a sample parent app used for debugging the plugin.

The LiferayFinderSync.appex bundle should be placed under the /Contents/Plugins/ folder of your application.

Limitations and Issues

There are several known issues with the Finder Sync API that require a change in behavior from the existing Nativity API.

Conflicts With Multiple Finder Sync Plugins

If multiple Finder Sync plugins monitor the same folders, only the first Finder Sync process that launched will be able to request/set icon badges. This means if a Finder Sync extension "greedily" decides to monitor a parent folder like ~/Documents (like Dropbox currently does), then any Finder Sync extension monitoring files under the ~/Documents parent will not show badges if the greedy extension launched first.

Ideally, Apple needs to figure out an intelligent mechanism for deciding which Finder Sync gets to draw the icon badge. Until then, developers are advised to be "polite" and monitor only the folders that explicitly belong to your application. Context menus will work fine with multiple extensions.


Finder Sync plugins must be sandboxed. By default, sandboxed applications cannot read data outside its own containers. In order to allow icons to be registered from any path as well as the ability to refresh file badges (which requires reading an observed folder's children), the entitlement is included, but any app submitted to the Mac App Store using this entitlement will likely be rejected.

Flat Context Menus

Finder Sync plugins also do not support sub-menus. The context menus returned by the client must be a flat list. Attempting to generate a tree of context menu items will result in only the parent level appearing in the context menu.


For OS X 10.9 Mavericks and below, there is no official API for custom file overlays and context menus in Finder, so LiferayNativity uses a technique called "method swizzling" to swap Finder's code with our own custom code. The Finder Sync plugin only works on OS X 10.10 Yosemite and above.

The LiferayNativityFinder bundle is responsible for "method swizzling" the code for icon overlays and context menus as well as handling client requests. LiferayNativityInjector is a scripting addition responsible for injecting the LiferayNativityFinder bundle into the running instance of Finder.

Note: Since method swizzling into Finder is not supported by Apple, any upgrade to Finder can break LiferayNativity's injected code. LiferayNativityInjector has an optional version check that can throw a warning if a newer, untested version of Finder is detected. Also, buggy injected code can cause Finder to crash or hang, so proceed with caution!


After cloning the liferay-nativity project, open LiferayNativity.xcworkspace and build using the LiferayNativity.osax scheme. The LiferayNativity.osax binary will be under LiferayNativityInjector's Products folder. You can ignore LiferayNativityFinder.bundle as it's already copied into LiferayNativity.osax's Resources folder.


Copy LiferayNativity.osax (LiferayNativityInjector's target) into /Library/ScriptingAdditions (this will prompt for administrator privileges). Alternatively, LiferayNativity.osax can be copied into the user's ~/Library/ScriptingAdditions but is not recommended because each request to run a script will prompt for administrator privileges.

After the scripts have been copied, the following scripting commands will be available. Send the NVTYload event using the example below to inject the LiferayNativityFinder bundle into the running instance of Finder.

NVTYload event

Loads LiferayNativityFinder into the running

tell application "Finder"
        «event NVTYload»
    end try
end tell
NVTYunld event

Unloads LiferayNativityFinder from the running Note, this does not actually remove the injected bundle but rather reverses all method swizzling and frees memory used by LiferayNativityFinder.

tell application "Finder"
        «event NVTYunld»
    end try
end tell
NVTYlded event

Check if LiferayNativityFinder is installed in the running Returns 0 if enabled, the error number otherwise.

tell application "Finder"
        «event NVTYlded»
        set the result to 0
    on error msg number code
        set the result to code
    end try
end tell

Upon successful deployment, log messages will be written to the system log.

Code Architecture


The code for LiferayNativityInjector is modified from the scripting additions used by TotalFinder. The original source code is available here. This method proved much simpler than using SIMBL or mach_inject. You can see our previous injection method using a combination of mach_inject and a priviliged helper tool installed by SMJobBless by checking out a commit before c82910f1b3. Many thanks to BinaryAge for open sourcing their injection code!


Once injected, LiferayNativityFinder is responsible for method swizzling the overlay icons and context menus into Finder. The original source code for method swizzling (as well as the previously used injection method through mach_inject) was written by the talented developers at TeamDev. Kudos to TeamDev for tackling an extremely challenging programming task!

Below is a brief description of the classes inside LiferayNativityFinder.

  • GCDAsyncSocket - Used for interprocess communication with the client.
  • JSONKit - Used to encapsulate messages sent across sockets.
  • FinderHook - Responsible for method swizzling. Replaces the methods needed for icon overlays and context menus.
  • ContextMenuHandler - Swizzled methods for context menus.
  • IconOverlayHander - Swizzled methods for icon overlays.
  • RequestManager - Manager for receiving and sending commands to the client.
  • ContentManager - Provides functions for associating icon overlays with files.
  • IconCache - Manages registered icon overlays.
  • MenuManager - Provides functions for associating custom menu items to selected files.


For Windows Nativity makes use of both a JNI interface as well as Windows Shell Extensions. There are several DLL’s which must be built and configured to use Nativity on Windows.

  • 1 for context menus
  • 1 for each overlay you want to use
  • 1 for JNI Interface dll
  • 1 Utility DLL shared by the context menu shell extension and the icon overlay extension.

JNI Interface

The JNI interface allows the Java side of nativity to interact with the native side of nativity. It only provides the ability to set a folder to a system folder. In windows if you want to set a folder icon through an desktop.ini file you must set the folder to be a system folder. So Nativity provides this functionality even though it is available in java 1.7, however nativity also provides it do older versions of java can be supported.

public static native boolean setSystemFolder(String folder)

The JNI interface also allows interaction with Explorer. It notifies explorer to redraw an icon overlay. This provides the ability to refresh the when they have changed.

public static native boolean updateExplorer(String filePath);

To use the JNI interface, the Liferay Nativity Windows Util project must be build and the resulting DLL named


This dll must also be on the java.library. path.

Shell Extensions

The shell extensions must be built and registered to be used by explorer, explorer also must be restarted for the icon overlays to display.

Build Properties

In your ant properties file you need to add the following properties.

  • nativity.dir This is the location of the nativity code.
  • nativity.version This is the version for your build of nativity.
  • ms.sdk.7.1.dir This is the directory that that MS SDK 7.1 resides
  • framework.dir This is the directory where the .NET Framework resides

  • This is the GUID you have assigned to your context menu dll.

  • This is the name for your icon overlay DLL, remember you need one icon overlay dll for each icon overlay.

  • overlay.guid.? This is the GUID you have assigned to this icon overlay dll.
  • This is the int value that this icon overlay will display for. The dll will query the java side for the id value, if the id value received is equal to this value, the icon overlay will display.
  • overlay.path.? This is the path to the icon overlay, this icon will be placed in the DLL during the build process.
ms.sdk.7.1.dir=C:/Program Files/Microsoft SDKs/Windows/v7.1

Ant Scripts

Windows Util DLL

This dll is required for both the Context Menus and the Icon Overlays.

<ant dir="${nativity.dir}" target="build-windows-util" inheritAll="false">
  <property name="nativity.dir" value="${nativity.dir}" />
  <property name="target.os" value="windows" />
  <property name="ms.sdk.7.1.dir" value="${ms.sdk.7.1.dir}" />
  <property name="framework.dir" value="${framework.dir}" />

Context Menu DLL

<ant dir="${nativity.dir}" target="build-windows-menus" inheritAll="false">
  <property name="nativity.dir" value="${nativity.dir}" />
  <property name="target.os" value="windows" />
  <property name="ms.sdk.7.1.dir" value="${ms.sdk.7.1.dir}" />
  <property name="framework.dir" value="${framework.dir}" />

  <property name="" value="${}" />

Icon Overlay DLL

One Icon Overlay DLL must be built for each Icon Overlay.

<ant dir="${nativity.dir}" target="build-windows-overlays" inheritAll="false">
  <property name="nativity.dir" value="${nativity.dir}" />
  <property name="dist.dir" value="${project.dir}/dist" />
  <property name="target.os" value="windows" />
  <property name="ms.sdk.7.1.dir" value="${ms.sdk.7.1.dir}" />
  <property name="framework.dir" value="${framework.dir}" />

  <property name="" value="${}" />
  <property name="overlay.guid" value="${overlay.guid.?}" />
  <property name="" value="${}" />
  <property name="overlay.path" value="${overlay.path.?}" />
<ant dir="${nativity.dir}" target="build-windows-overlays" inheritAll="false">
  <property name="nativity.dir" value="${nativity.dir}" />
  <property name="dist.dir" value="${project.dir}/dist" />
  <property name="target.os" value="windows" />
  <property name="ms.sdk.7.1.dir" value="${ms.sdk.7.1.dir}" />
  <property name="framework.dir" value="${framework.dir}" />

  <property name="" value="${}" />
  <property name="overlay.guid" value="${overlay.guid.syncing}" />
  <property name="" value="${}" />
  <property name="overlay.path" value="${overlay.path.syncing}" />


Liferay Nativity currently only supports Nautilus file manager. Hooks for Nemo are available, but the overlay icons and context menus do not appear.


git clone

cd liferay-nativity/linux/nautilus/src

sudo apt-get install cmake build-essential libgtk2.0-dev libnautilus-extension-dev libboost-all-dev

cmake .




sudo ln -s pwd/ /usr/lib/nautilus/extensions-3.0/ killall -9 nautilus

Nemo (Nautilus fork)

sudo ln -s pwd/ /usr/lib/nemo/extensions-3.0/ killall -9 nemo

Upon successful deployment, log messages will be written to ~/.liferay-nativity/liferaynativity.log.

Further instructions coming soon

Java Client

The clients communicate with the Native Plugins via JSON messages over sockets.

The java client can be distributed as a jar file. Run the ant task "build-jar" to automate building the jar file. Build properties are configured in You can override with user-specific values by creating a build.<username>.properties file where <username> is your computer account name (e.g.:

The key classes for the java client are:

  • Package com.liferay.nativity.control
    • NativityControl - Controller for interacting with the native plugin. Required for all other modules. This class is documented in the source.
    • NativityControlUtil - Utility for returning a NativityControl instance.
  • Package com.liferay.nativity.modules.contextmenu
    • ContextMenuControl - Controller module for interacting with context menus. This class is documented in the source.
    • ContextMenuControlUtil - Utility for returning a ContextMenuControl instance.
    • ContextMenuControlCallback - Callback class that must be implemented to respond to context menu requests.
  • Package com.liferay.nativity.modules.fileicon
    • FileIconControl - Controller module for interacting with file icon overlays. This class is documented in the source.
    • FileIconControlUtil - Utility for returning a FileIconControl instance.
    • FileIconControlCallback - Callback class that must be implemented to respond to file icon requests. (Currently only needed for Windows)

Example Code

The following example Java code will overlay testFile.txt with testIcon.icns and create a context menu item titled "Nativity Test".

NativityControl nativityControl = NativityControlUtil.getNativityControl();


/* File Icons */

int testIconId;

// FileIconControlCallback used by Windows and Mac
FileIconControlCallback fileIconControlCallback = new FileIconControlCallback() {
  public int getIconForFile(String path) {
    return testIconId;

FileIconControl fileIconControl = FileIconControlUtil.getFileIconControl(
  nativityControl, fileIconControlCallback);


String testFilePath = "/Users/liferay/Desktop/testFile.txt";

if (OSDetector.isWindows()) {
  // This id is determined when building the DLL
  testIconId = 1;
else if (OSDetector.isMinimumAppleVersion(OSDetector.MAC_YOSEMITE_10_10)) {
  // Used by Mac Finder Sync. This unique id can be set at runtime.
  testIconId = 1;

  fileIconControl.registerIconWithId("/Users/liferay/Desktop/testIcon.icns", "test label", testIconId);
else if (OSDetector.isLinux() || OSDetector.isMinimumAppleVersion()) {
  // Used by Mac Injector and Linux
  testIconId = fileIconControl.registerIcon("/Users/liferay/Desktop/testIcon.icns");

// FileIconControl.setFileIcon() method only used by Linux
fileIconControl.setFileIcon(testFilePath, testIconId);

/* Context Menus */

ContextMenuControlCallback contextMenuControlCallback = new ContextMenuControlCallback() {
  public List<ContextMenuItem> getContextMenuItems(String[] paths) {
    ContextMenuItem contextMenuItem = new ContextMenuItem("Nativity Test");

    ContextMenuAction contextMenuAction = new ContextMenuAction() {
      public void onSelection(String[] paths) {
        for (String path : paths) {
          System.out.print(path + ", ");



    List<ContextMenuItem> contextMenuItems = new ArrayList<ContextMenuItem>() {};

    // Mac Finder Sync will only show the parent level of context menus
    return contextMenuItems;

ContextMenuControlUtil.getContextMenuControl(nativityControl, contextMenuControlCallback);

Issue Tracking and Contributions

LiferayNativity is an open source project and community members are encouraged to submit bug fixes and enhancements.

Please report all bugs and feature requests here: (you will need to create a free account).

To contribute code, create or find the issue on Nativity's ticket management page. From the ticket page, click on "Workflow" -> "Contribute Solution" and include the pull request link. You can choose "Automatic" for the Assignee.

Review the guidelines for contributions to Liferay projects here: link


LiferayNativity is licensed under the LGPL. Check license.txt for the latest licensing information.


Email with questions or comments.

Something went wrong with that request. Please try again.