Add support to load images from files which can be used as custom ico…

…ns in modals (#226)

CHANGELOG.md

@@ -6,6 +6,10 @@ Changelog
 
 Release: dd.mm.yyyy
 
+### New
+
+- Add support to load images from files which can be used as custom icons in modals ([#226](https://github.com/kasper/phoenix/issues/226)).
+
 ### Changes
 
 - Upgrade Lodash to 4.17.11 (from 4.17.5).
@@ -23,6 +27,10 @@ Release: dd.mm.yyyy
 
 - Change: Add key modifiers to mouse events ([#216](https://github.com/kasper/phoenix/issues/216), [#217](https://github.com/kasper/phoenix/pull/217)).
 
+#### Image
+
+- New: Function `fromFile(String path)` loads an image from the given path, the path is resolved before attempting to load the image, returns `undefined` if unsuccessful ([#226](https://github.com/kasper/phoenix/issues/226)).
+
 2.6.2
 -----
 

Phoenix.xcodeproj/project.pbxproj

@@ -16,6 +16,7 @@
 		A72ED7B61B6E25940064E35B /* PHPhoenix.m in Sources */ = {isa = PBXBuildFile; fileRef = A72ED7B51B6E25940064E35B /* PHPhoenix.m */; };
 		A731A7261C2C76B800EB9FD5 /* PHSpace.m in Sources */ = {isa = PBXBuildFile; fileRef = A731A7251C2C76B800EB9FD5 /* PHSpace.m */; };
 		A73C2CAB1B9088040004C663 /* PHNotificationHelper.m in Sources */ = {isa = PBXBuildFile; fileRef = A73C2CAA1B9088040004C663 /* PHNotificationHelper.m */; };
+		A73F956021D65763002FCB22 /* NSImage+PHExtension.m in Sources */ = {isa = PBXBuildFile; fileRef = A73F955F21D65763002FCB22 /* NSImage+PHExtension.m */; };
 		A741336C1BB7EEAC008DAF39 /* PHHandler.m in Sources */ = {isa = PBXBuildFile; fileRef = A741336B1BB7EEAC008DAF39 /* PHHandler.m */; };
 		A741336F1BB7F228008DAF39 /* PHEventHandler.m in Sources */ = {isa = PBXBuildFile; fileRef = A741336E1BB7F228008DAF39 /* PHEventHandler.m */; };
 		A74133721BB7F556008DAF39 /* PHEventTranslator.m in Sources */ = {isa = PBXBuildFile; fileRef = A74133711BB7F556008DAF39 /* PHEventTranslator.m */; };
@@ -80,6 +81,8 @@
 		A731A7251C2C76B800EB9FD5 /* PHSpace.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = PHSpace.m; sourceTree = "<group>"; };
 		A73C2CA91B9088040004C663 /* PHNotificationHelper.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = PHNotificationHelper.h; sourceTree = "<group>"; };
 		A73C2CAA1B9088040004C663 /* PHNotificationHelper.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = PHNotificationHelper.m; sourceTree = "<group>"; };
+		A73F955E21D6573D002FCB22 /* NSImage+PHExtension.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "NSImage+PHExtension.h"; sourceTree = "<group>"; };
+		A73F955F21D65763002FCB22 /* NSImage+PHExtension.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "NSImage+PHExtension.m"; sourceTree = "<group>"; };
 		A73FF10E1BBD982A0024CF97 /* PHEventConstants.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = PHEventConstants.h; sourceTree = "<group>"; };
 		A741336A1BB7EEAC008DAF39 /* PHHandler.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = PHHandler.h; sourceTree = "<group>"; };
 		A741336B1BB7EEAC008DAF39 /* PHHandler.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = PHHandler.m; sourceTree = "<group>"; };
@@ -262,6 +265,8 @@
 			children = (
 				A79452401C2F35E3007AF8C5 /* NSArray+PHExtension.h */,
 				A79452411C2F35E3007AF8C5 /* NSArray+PHExtension.m */,
+				A73F955E21D6573D002FCB22 /* NSImage+PHExtension.h */,
+				A73F955F21D65763002FCB22 /* NSImage+PHExtension.m */,
 				A78749621CA2BB440042DA4C /* NSProcessInfo+PHExtension.h */,
 				A78749631CA2BB440042DA4C /* NSProcessInfo+PHExtension.m */,
 				A79C467A1B5BF3C100C460CF /* NSScreen+PHExtension.h */,
@@ -572,6 +577,7 @@
 				A79C46981B5BF3C100C460CF /* PHAppDelegate.m in Sources */,
 				A7288A3B1CC14DF800EC032B /* PHWeakTimerTarget.m in Sources */,
 				A72ED7B61B6E25940064E35B /* PHPhoenix.m in Sources */,
+				A73F956021D65763002FCB22 /* NSImage+PHExtension.m in Sources */,
 				A73C2CAB1B9088040004C663 /* PHNotificationHelper.m in Sources */,
 				A74133721BB7F556008DAF39 /* PHEventTranslator.m in Sources */,
 				A7E6DF6F1BBAC1F3001920B4 /* PHAccessibilityObserver.m in Sources */,

Phoenix/ModalWindow.xib

@@ -30,7 +30,7 @@
                     <customView translatesAutoresizingMaskIntoConstraints="NO" id="O5f-kD-6s1">
                         <rect key="frame" x="0.0" y="0.0" width="152" height="59"/>
                         <subviews>
-                            <imageView horizontalHuggingPriority="251" verticalHuggingPriority="251" translatesAutoresizingMaskIntoConstraints="NO" id="peX-kY-Jau">
+                            <imageView horizontalHuggingPriority="251" verticalHuggingPriority="251" horizontalCompressionResistancePriority="250" verticalCompressionResistancePriority="250" translatesAutoresizingMaskIntoConstraints="NO" id="peX-kY-Jau">
                                 <rect key="frame" x="17" y="5" width="48" height="48"/>
                                 <constraints>
                                     <constraint firstAttribute="width" secondItem="peX-kY-Jau" secondAttribute="height" multiplier="1:1" priority="750" id="hpt-4C-KRY"/>

Phoenix/NSImage+PHExtension.h

@@ -0,0 +1,24 @@
+/*
+ * Phoenix is released under the MIT License. Refer to https://github.com/kasper/phoenix/blob/master/LICENSE.md
+ */
+
+@import Cocoa;
+@import JavaScriptCore;
+
+#import "PHIdentifiableJSExport.h"
+
+@protocol NSImageJSExport <JSExport, PHIdentifiableJSExport>
+
+#pragma mark - Constructing
+
++ (instancetype) fromFile:(NSString *)path;
+
+@end
+
+@interface NSImage (PHExtension) <NSImageJSExport>
+
+#pragma mark - Initialising
+
++ (instancetype) fromFile:(NSString *)path;
+
+@end

Phoenix/NSImage+PHExtension.m

@@ -0,0 +1,22 @@
+/*
+ * Phoenix is released under the MIT License. Refer to https://github.com/kasper/phoenix/blob/master/LICENSE.md
+ */
+
+#import "NSImage+PHExtension.h"
+
+@implementation NSImage (PHExtension)
+
+#pragma mark - Initialising
+
++ (instancetype) fromFile:(NSString *)path {
+
+    NSString *resolvedPath = path.stringByResolvingSymlinksInPath;
+
+    if (![[NSFileManager defaultManager] fileExistsAtPath:resolvedPath]) {
+        NSLog(@"Warning: Trying to initialise an image from a non-existent path “%@”.", resolvedPath);
+    }
+
+    return [[self alloc] initWithContentsOfFile:resolvedPath];
+}
+
+@end

Phoenix/PHContext.m

@@ -4,6 +4,7 @@
 
 @import JavaScriptCore;
 
+#import "NSImage+PHExtension.h"
 #import "NSScreen+PHExtension.h"
 #import "PHAccessibilityObserver.h"
 #import "PHApp.h"
@@ -185,6 +186,7 @@ - (void) setupAPI {
     self.context[@"Event"] = [PHEventHandler class];
     self.context[@"Timer"] = [PHTimerHandler class];
     self.context[@"Task"] = [PHTaskHandler class];
+    self.context[@"Image"] = [NSImage class];
     self.context[@"Modal"] = [PHModalWindowController class];
     self.context[@"Screen"] = [NSScreen class];
     self.context[@"Space"] = [PHSpace class];

docs/API.md

@@ -29,12 +29,13 @@ This documentation is an overview of the JavaScript API provided by Phoenix. Cur
 13. [Event](#13-event)
 14. [Timer](#14-timer)
 15. [Task](#15-task)
-16. [Modal](#16-modal)
-17. [Screen](#17-screen)
-18. [Space](#18-space)
-19. [Mouse](#19-mouse)
-20. [App](#20-app)
-21. [Window](#21-window)
+16. [Image](#16-image)
+17. [Modal](#17-modal)
+18. [Screen](#18-screen)
+19. [Space](#19-space)
+20. [Mouse](#20-mouse)
+21. [App](#21-app)
+22. [Window](#22-window)
 
 ## Getting Started
 
@@ -434,7 +435,21 @@ end
 - `new Task(String path, Array arguments, Function callback)` constructs a task that asynchronously executes an absolute path with the given arguments and returns the handler, you must keep a reference to the handler in order for your callback to get called, the callback function receives its handler as the only argument
 - `terminate()` terminates the task immediately
 
-## 16. Modal
+## 16. Image
+
+Use the `Image`-object to construct images.
+
+```java
+class Image implements Identifiable
+
+  static Image fromFile(String path)
+
+end
+```
+
+- `fromFile(String path)` loads an image from the given path, the path is resolved before attempting to load the image, returns `undefined` if unsuccessful
+
+## 17. Modal
 
 Use the `Modal`-object to display content as modal windows (in front of all other windows). Modals can be used to display icons and/or text for visual cues. Properties defined as dynamic can be altered while the modal is displayed.
 
@@ -472,7 +487,7 @@ end
 - `show()` shows the modal, you must set at least an icon or text for the modal to be displayed
 - `close()` closes the modal
 
-## 17. Screen
+## 18. Screen
 
 Use the `Screen`-object to access frame sizes and other screens on a multi-screen setup. Beware that a screen can get stale if you keep a reference to it and it is for instance disconnected while you do so.
 
@@ -509,7 +524,7 @@ end
 
 - `visible` (boolean): if set `true` returns all visible windows for the screen, if set `false` returns all hidden windows for the screen
 
-## 18. Space
+## 19. Space
 
 Use the `Space`-object to control spaces. *These features are only supported on El Capitan (10.11) and upwards.* A single window can be in multiple spaces at the same time. To move a window to a different space, remove it from any existing spaces and add it to a new one. You can switch to a space by focusing on a window in that space. Beware that a space can get stale if you keep a reference to it and it is for instance closed while you do so.
 
@@ -542,7 +557,7 @@ end
 
 - `visible` (boolean): if set `true` returns all visible windows for the space, if set `false` returns all hidden windows for the space
 
-## 19. Mouse
+## 20. Mouse
 
 Use the `Mouse`-object to control the cursor.
 
@@ -558,7 +573,7 @@ end
 - `location()` returns the cursor position
 - `move(Point point)` moves the cursor to a given position, returns `true` if successful
 
-## 20. App
+## 21. App
 
 Use the `App`-object to control apps. Beware that an app can get stale if you keep a reference to it and it is for instance terminated while you do so, refer to `isTerminated()`.
 
@@ -619,7 +634,7 @@ end
 
 - `force` (boolean): if set `true` force terminates the app
 
-## 21. Window
+## 22. Window
 
 Use the `Window`-object to control windows. Every screen (i.e. display) combines to form a large rectangle. Every window lives within this rectangle and their position can be altered by giving coordinates inside this rectangle. To position a window to a specific display, you need to calculate its position within the large rectangle. To figure out the coordinates for a given screen, use the functions in `Screen`. Beware that a window can get stale if you keep a reference to it and it is for instance closed while you do so.