Skip to content

Commit

Permalink
better docs
Browse files Browse the repository at this point in the history
  • Loading branch information
nate-parrott committed Nov 4, 2014
1 parent 9797d75 commit 72218cd
Show file tree
Hide file tree
Showing 6 changed files with 34 additions and 22 deletions.
4 changes: 1 addition & 3 deletions FlashlightApp/EasySIMBL/Flashlight-Info.plist
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>0.9</string>
<string>0.1</string>
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
Expand All @@ -41,8 +41,6 @@
<string>public.app-category.utilities</string>
<key>LSMinimumSystemVersion</key>
<string>${MACOSX_DEPLOYMENT_TARGET}</string>
<key>NSHumanReadableCopyright</key>
<string>${EXECUTABLE_NAME} ${PRODUCT_VERSION}, ©2012 Norio Nomura</string>
<key>NSMainNibFile</key>
<string>MainMenu</string>
<key>NSPrincipalClass</key>
Expand Down
5 changes: 5 additions & 0 deletions FlashlightApp/EasySIMBL/PluginListController.m
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ - (void)tableView:(NSTableView *)tableView didAddRowView:(NSTableRowView *)rowVi
((PluginCellView *)[rowView viewAtColumn:0]).listController = self;
}

- (NSIndexSet *)tableView:(NSTableView *)tableView
selectionIndexesForProposedSelection:(NSIndexSet *)proposedSelectionIndexes {
return nil;
}

#pragma mark Data
- (IBAction)reloadPluginsFromWeb:(id)sender {
[self.failedToLoadDirectoryBanner setHidden:YES];
Expand Down
6 changes: 3 additions & 3 deletions FlashlightApp/EasySIMBL/en.lproj/MainMenu.xib
Original file line number Diff line number Diff line change
Expand Up @@ -674,7 +674,7 @@
<rect key="frame" x="1" y="0.0" width="238" height="134"/>
<autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
<subviews>
<tableView verticalHuggingPriority="750" allowsExpansionToolTips="YES" columnAutoresizingStyle="firstColumnOnly" alternatingRowBackgroundColors="YES" columnSelection="YES" multipleSelection="NO" autosaveColumns="NO" rowHeight="65" rowSizeStyle="automatic" viewBased="YES" id="2Bw-eW-td2">
<tableView verticalHuggingPriority="750" allowsExpansionToolTips="YES" columnAutoresizingStyle="firstColumnOnly" alternatingRowBackgroundColors="YES" multipleSelection="NO" autosaveColumns="NO" typeSelect="NO" rowHeight="65" rowSizeStyle="automatic" viewBased="YES" id="2Bw-eW-td2">
<autoresizingMask key="autoresizingMask"/>
<size key="intercellSpacing" width="3" height="2"/>
<color key="backgroundColor" white="1" alpha="1" colorSpace="calibratedWhite"/>
Expand Down Expand Up @@ -793,7 +793,7 @@
</textFieldCell>
</textField>
<textField horizontalHuggingPriority="251" verticalHuggingPriority="750" id="4I6-zG-9ut">
<rect key="frame" x="33" y="30" width="238" height="17"/>
<rect key="frame" x="33" y="29.999999779112191" width="238" height="17"/>
<autoresizingMask key="autoresizingMask" widthSizable="YES" flexibleMinY="YES" heightSizable="YES"/>
<textFieldCell key="cell" scrollable="YES" lineBreakMode="clipping" sendsActionOnEndEditing="YES" title="Couldn't load online plugins directory." id="6Rm-1o-2sX">
<font key="font" metaFont="system"/>
Expand Down Expand Up @@ -873,6 +873,6 @@ Gw
<outlet property="failedToLoadDirectoryBanner" destination="eIK-Jf-OGb" id="BJ2-yH-ZoO"/>
</connections>
</customObject>
<arrayController id="714"/>
<arrayController selectsInsertedObjects="NO" avoidsEmptySelection="NO" id="714"/>
</objects>
</document>
2 changes: 2 additions & 0 deletions FlashlightApp/Flashlight.xcodeproj/project.pbxproj
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,7 @@
GCC_PRECOMPILE_PREFIX_HEADER = YES;
GCC_PREFIX_HEADER = "EasySIMBL/Flashlight-Prefix.pch";
INFOPLIST_FILE = "EasySIMBL/Flashlight-Info.plist";
MACOSX_DEPLOYMENT_TARGET = 10.10;
PRODUCT_NAME = "$(TARGET_NAME)";
WRAPPER_EXTENSION = app;
};
Expand All @@ -558,6 +559,7 @@
GCC_PRECOMPILE_PREFIX_HEADER = YES;
GCC_PREFIX_HEADER = "EasySIMBL/Flashlight-Prefix.pch";
INFOPLIST_FILE = "EasySIMBL/Flashlight-Info.plist";
MACOSX_DEPLOYMENT_TARGET = 10.10;
PRODUCT_NAME = "$(TARGET_NAME)";
WRAPPER_EXTENSION = app;
};
Expand Down
39 changes: 23 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,44 @@
Flashlight
==========

_The missing Spotlight plugin system_

![Image of a Spotlight window showing 'ellohay orldway' as the Pig Latin translation of 'hello world'](https://raw.github.com/nate-parrott/flashlight/master/PigLatinExampleImage.png) ![Image of a a UI for selecting Spotlight plugins](https://raw.github.com/nate-parrott/flashlight/master/UIExampleImage.png)

Flashlight is an **unofficial Spotlight API** that allows you to programmatically process queries and add additional results. It's *very rough right now,* and a *horrendous hack*, but a fun proof of concept.

**Installation**

Flashlight depends on [EasySIMBL](https://github.com/norio-nomura/EasySIMBL), a runtime code-injection framework. (like MobileSubstrate, but for OS X).

When you build and run the Xcode project, it generates a bundle called `SpotlightSIMBL.bundle`, automatically copies it to `~/Library/Application Support/SIMBL/Plugins`, then restarts Spotlight.
Clone and build using Xcode, or [download Flashlight.app from _releases_](https://github.com/nate-parrott/Flashlight/releases).

**API**

After installation, Flashlight reads plugins from `~/Library/FlashlightPlugins`. Each plugin must be a directory containing an executable named `executable`.

Every time you type a character into Spotlight, each plugin's executable will be invoked with your query as the first argument (`argv[1]`). If the plugin decides to respond to the query, it should print a json document to `stdout` in this format:
Flashlight plugins are `.bundle` files in `~/Library/FlashlightPlugins`. They have a simple directory structure:

```
{
"title": "'Hello world' in Pig Latin",
"html": "<h1>ellohay, orldway</h1>",
"execute": "(shell string to execute when enter is pressed)"
}
- MyPlugin.bundle
- executable
(probably a script in your favorite language, starting with #!/usr/bin/python|ruby|php|bash)
- Info.plist
(create these with Xcode. Must contain 'CFBundleDisplayName' and 'Description' keys)
```

(if the plugin doesn't want to provide a response, just don't print anything.)
When you enter text into Spotlight, Flashlight will invoke all the `*.bundle/executable` files. (in order for the system to know what interpreter to use, you've got to include the [shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix)).)

This HTML will then be presented to the user:
Flashlight will pass the Spotlight query as the first argument (`argv[1]`).

![Image of a Spotlight window showing 'ellohay orldway' as the Pig Latin translation of 'hello world'](https://raw.github.com/nate-parrott/flashlight/master/PigLatinExampleImage.png)
If you want to show a search result, just print a JSON structure to stdout:

```
{
"title": "Search result title",
"html": "<h1>HTML to show inline <em>inside Spotlight</em></h1>",
"execute": "bash shell script to run if the user hits enter"
}
```

(this HTML will be loaded with the plugin's directory as its base URL, so you can reference images, javascript and CSS from it.)
For examples, look at the ['say' example](https://github.com/nate-parrott/Flashlight/tree/master/PluginDirectory/say.bundle) or the [Pig Latin example](https://github.com/nate-parrott/Flashlight/tree/master/PluginDirectory/piglatin.bundle).

This is currently all the API does. More capabilities, like more customization of the search result, are on my to-do list.

**How it works**

Expand Down
Binary file added UIExampleImage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 72218cd

Please sign in to comment.