Auto-merge pull request #3044 from montegoulding/feature/represented_…

…filename

[[ DocumentFilename ]] Add documentFilename property

As discussed on the engine forums I have implemented a documentFilename property which sets the represented filename of the window on mac. I'm happy to look at other platforms if they support anything like this but I haven't found anything thus far.

docs/dictionary/property/documentFilename.lcdoc

@@ -0,0 +1,56 @@
+Name: documentFilename
+
+Type: property
+
+Syntax: set the documentFilename of <stack> to <filename>
+
+Summary: Specifies the file path to the file that the stack represents.
+
+Associations: stack
+
+Introduced: 8.0.0
+
+OS: mac,windows,linux,ios,android
+
+Platforms: desktop
+
+Example:
+answer file "Open document"
+if it is not empty then
+  put it into theFilename
+  set the documentFilename of stack "Template Document Editor" to theFilename
+  clone stack "Template Document Editor"
+end if
+
+Example:
+put the documentFilename of this stack into theFilename
+if theFilename is not empty then
+  # load data from file
+  try
+    put arrayDecode(url ("binfile:" & theFilename)) into theDataA
+    # load the data into the UI
+    UpdateWithData theDataA
+  catch error
+    # file corrupted
+  end try
+end if
+
+Parameters:
+Stack: The name or ID of the stack.
+Filename: The full or relative path to the document.
+
+Description:
+Use the <documentFilename> property to associate a stack being presented to the
+user with a document on disk.
+
+On mac setting the <documentFilename> property will set the represented filename
+of the window. The window will show an icon for the file next to the window
+title.
+
+On other platforms there is no visual representation of the association between
+the stack and the document filename but the property may still be used to manage
+the association.
+
+>*Note:* The <documentFilename> property is not persistent (not saved into the stackfile).
+
+Tags: windowing

docs/notes/feature-documentFilename.md

@@ -0,0 +1,12 @@
+# documentFilename property
+
+A new property has been added to specify the file path to the file that a stack
+represents.
+
+On mac setting the documentFilename property will set the represented filename
+of the window. The window will show an icon for the file next to the window
+title.
+
+On other platforms there is no visual representation of the association between
+the stack and the document file but the property may still be used to manage
+the association.

engine/src/desktop-stack.cpp

@@ -215,6 +215,9 @@ void MCStack::realize(void)
 
         // MW-2014-06-11: [[ Bug 12467 ]] Make sure we reset the cursor property of the window.
         resetcursor(True);
+
+        // MERG-2015-10-11: [[ DocumentFilename ]] update the window with the document filename property
+        MCPlatformSetWindowProperty(t_window, kMCPlatformWindowPropertyDocumentFilename, kMCPlatformPropertyTypeMCString, &m_document_filename);
 	}
 
 	start_externals();
@@ -333,6 +336,13 @@ void MCStack::view_platform_updatewindowwithcallback(MCRegionRef p_region, MCSta
 	s_update_context = nil;
 }
 
+// MERG-2015-10-12: [[ DocumentFilename ]] Stub for documentFilename.
+void MCStack::updatedocumentfilename(void)
+{
+    if (window != nil)
+        MCPlatformSetWindowProperty(window, kMCPlatformWindowPropertyDocumentFilename, kMCPlatformPropertyTypeMCString, &m_document_filename);
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 
 // MW-2014-06-11: [[ Bug 12495 ]] Update windowshape by setting window property.

engine/src/exec-interface-stack.cpp

@@ -46,6 +46,7 @@ along with LiveCode.  If not see <http://www.gnu.org/licenses/>.  */
 #include "external.h"
 
 #include "exec-interface.h"
+#include "osspec.h"
 
 //////////
 
@@ -2182,3 +2183,30 @@ void MCStack::SetScriptOnly(MCExecContext& ctxt, bool p_script_only)
 {
     m_is_script_only = p_script_only;
 }
+
+// MERG-2015-10-11: [[ DocumentFilename ]] Add stack documentFilename property
+void MCStack::GetDocumentFilename(MCExecContext &ctxt, MCStringRef& r_document_filename)
+{
+    r_document_filename = MCValueRetain(m_document_filename);
+}
+
+void MCStack::SetDocumentFilename(MCExecContext &ctxt, MCStringRef p_document_filename)
+{
+    MCStringRef t_resolved_filename;
+
+    if (MCStringIsEmpty(p_document_filename))
+    {
+        t_resolved_filename = p_document_filename;
+    }
+    else if (!MCS_resolvepath(p_document_filename, t_resolved_filename))
+    {
+        ctxt . LegacyThrow(EE_DOCUMENTFILENAME_BADFILENAME);
+        return;
+    }
+
+    MCValueAssign(m_document_filename, t_resolved_filename);
+
+    updatedocumentfilename();
+
+}
+

engine/src/executionerrors.h

@@ -2665,6 +2665,9 @@ enum Exec_errors
 
     // {EE-0869} Import: not an object array
     EE_IMPORT_NOTANOBJECTARRAY,
+
+    // {EE-0870} documentFilename: bad filename
+    EE_DOCUMENTFILENAME_BADFILENAME,
 };
 
 extern const char *MCexecutionerrors;

engine/src/lextable.cpp

@@ -823,7 +823,9 @@ LT factor_table[] =
         {"div", TT_BINOP, O_DIV},
         {"dnsservers", TT_FUNCTION, F_DNS_SERVERS},
 		{"document", TT_CHUNK, CT_DOCUMENT},
-		// MW-2011-11-24: [[ Nice Folders ]] The adjective for 'the documents folder'.
+        // MERG-2015-10-11: [[ DocumentFilename ]] Property tag for documentFilename
+        {"documentfilename", TT_PROPERTY, P_DOCUMENT_FILENAME},
+        // MW-2011-11-24: [[ Nice Folders ]] The adjective for 'the documents folder'.
 		{"documents", TT_PROPERTY, P_DOCUMENTS_FOLDER},
         {"dontdither", TT_PROPERTY, P_DONT_DITHER},
         {"dontrefresh", TT_PROPERTY, P_DONT_REFRESH},

engine/src/lnxstack.cpp

@@ -670,6 +670,11 @@ void MCStack::clearscroll(void)
 {
 }
 
+// MERG-2015-10-12: [[ DocumentFilename ]] Stub for documentFilename.
+void MCStack::updatedocumentfilename(void)
+{
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 
 void MCBitmapClearRegion(MCBitmap *p_image, int32_t p_x, int32_t p_y, uint32_t p_width, uint32_t p_height)

engine/src/mac-internal.h

@@ -521,7 +521,9 @@ class MCMacPlatformWindow: public MCPlatformWindow
 private:
 	// Compute the Cocoa window style from the window's current properties.
 	void ComputeCocoaStyle(NSUInteger& r_window_style);
-
+    // MERG-2015-10-11: [[ DocumentFilename ]] Set documentFilename.
+    void UpdateDocumentFilename(void);
+
 	// The window delegate object.
 	MCWindowDelegate *m_delegate;
 

engine/src/mac-window.mm

@@ -32,6 +32,8 @@
 
 #include "graphics_util.h"
 
+#include "osspec.h"
+
 ///////////////////////////////////////////////////////////////////////////
 
 static NSDragOperation s_drag_operation_result = NSDragOperationNone;
@@ -1894,6 +1896,9 @@ - (void)setFrameSize: (NSSize)size
     // MW-2014-04-08: [[ Bug 12080 ]] Make sure we turn off automatic 'hiding on deactivate'.
     //   The engine handles this itself.
     [m_window_handle setHidesOnDeactivate: m_hides_on_suspend];
+
+    // MERG-2015-10-11: [[ DocumentFilename ]] Set documentFilename.
+    UpdateDocumentFilename();
 }
 
 void MCMacPlatformWindow::DoSynchronize(void)
@@ -1964,7 +1969,12 @@ - (void)setFrameSize: (NSSize)size
     if (m_changes . ignore_mouse_events_changed)
         [m_window_handle setIgnoresMouseEvents: m_ignore_mouse_events];
 
-	m_synchronizing = false;
+    if (m_changes . document_filename_changed)
+    {
+        UpdateDocumentFilename();
+    }
+
+    m_synchronizing = false;
 }
 
 bool MCMacPlatformWindow::DoSetProperty(MCPlatformWindowProperty p_property, MCPlatformPropertyType p_type, const void *value)
@@ -2191,6 +2201,25 @@ bool MCMacDoUpdateRegionCallback(void *p_context, const MCRectangle &p_rect)
 	r_cocoa_style = t_window_style;
 }
 
+// MERG-2015-10-11: [[ DocumentFilename ]] Set documentFilename.
+void MCMacPlatformWindow::UpdateDocumentFilename(void)
+{
+    MCStringRef t_native_filename;
+
+    NSString * t_represented_filename;
+    t_represented_filename = nil;
+
+    if (!MCStringIsEmpty(m_document_filename) && MCS_pathtonative(m_document_filename, t_native_filename))
+    {
+        t_represented_filename = [NSString stringWithMCStringRef: t_native_filename];
+    }
+    else
+        t_represented_filename = @"";
+
+    // It appears setRepresentedFilename can't be set to nil
+    [m_window_handle setRepresentedFilename: t_represented_filename];
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 
 static bool MCAlphaToCGImageNoCopy(const MCGRaster &p_alpha, CGImageRef &r_image)

engine/src/mblstack.cpp

@@ -158,6 +158,11 @@ void MCStack::clearscroll(void)
 {
 }
 
+// MERG-2015-10-12: [[ DocumentFilename ]] Stub for documentFilename.
+void MCStack::updatedocumentfilename(void)
+{
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 
 MCRectangle MCStack::view_platform_getwindowrect() const

engine/src/parsedef.h

@@ -1604,7 +1604,10 @@ enum Properties {
     // MW-2014-08-12: [[ EditionType ]] Returns whether the engine is commercial or community
     P_EDITION_TYPE,
 
-	// ARRAY STYLE PROPERTIES
+    // MERG-2015-10-11: [[ DocumentFilename ]] Property tag for documentFilename
+    P_DOCUMENT_FILENAME,
+
+    // ARRAY STYLE PROPERTIES
 	P_FIRST_ARRAY_PROP,
     P_CUSTOM_KEYS = P_FIRST_ARRAY_PROP,
     P_CUSTOM_PROPERTIES,

engine/src/platform-internal.h

@@ -188,13 +188,18 @@ class MCPlatformWindow
 
         // MERG-2014-06-02: [[ IgnoreMouseEvents ]] Changed flag for ignore mouse events.
         bool ignore_mouse_events_changed : 1;
+
+        // MERG-2015-10-11: [[ DocumentFilename ]] Changed flag for docuent filename
+        bool document_filename_changed : 1;
 	} m_changes;
 	MCPlatformWindowStyle m_style;
 	MCStringRef m_title;
 	MCPlatformWindowMaskRef m_mask;
 	float m_opacity;
 	MCRectangle m_content;
 	MCCursorRef m_cursor;
+    // MERG-2015-10-11: [[ DocumentFilename ]] documentFilename property
+    MCStringRef m_document_filename;
 	struct
 	{
 		bool m_has_title_widget : 1;

engine/src/platform-window.cpp

@@ -65,6 +65,9 @@ MCPlatformWindow::MCPlatformWindow(void)
     m_is_realized = false;
 
 	m_is_opaque = true;
+
+    // MERG-2015-10-11: [[ DocumentFilename ]] documentFilename property
+    m_document_filename = MCValueRetain(kMCEmptyString);
 }
 
 MCPlatformWindow::~MCPlatformWindow(void)
@@ -77,6 +80,9 @@ MCPlatformWindow::~MCPlatformWindow(void)
     // SN-2014-06-23: Title updated to StringRef
 	MCValueRelease(m_title);
 
+    // MERG-2015-10-11: [[ DocumentFilename ]] documentFilename property
+    MCValueRelease(m_document_filename);
+
 	free(m_attachments);
 }
 
@@ -383,6 +389,12 @@ void MCPlatformWindow::SetProperty(MCPlatformWindowProperty p_property, MCPlatfo
 			m_ignore_mouse_events = *(bool *)p_value;
 			m_changes . ignore_mouse_events_changed = true;
 			break;
+        // MERG-2015-10-11: [[ DocumentFilename ]] Handle document filename
+        case kMCPlatformWindowPropertyDocumentFilename:
+            assert(p_type == kMCPlatformPropertyTypeMCString);
+            MCValueAssign(m_document_filename, *(MCStringRef*)p_value);
+            m_changes . document_filename_changed = true;
+            break;
 		default:
 			assert(false);
 			break;
@@ -454,6 +466,11 @@ void MCPlatformWindow::GetProperty(MCPlatformWindowProperty p_property, MCPlatfo
 		case kMCPlatformWindowPropertyCursor:
 			*(MCPlatformCursorRef *)r_value = m_cursor;
 			break;
+        // MERG-2015-10-11: [[ DocumentFilename ]] Handle document filename
+        case kMCPlatformWindowPropertyDocumentFilename:
+            assert(p_type == kMCPlatformPropertyTypeMCString);
+            *(MCStringRef*)r_value = MCValueRetain(m_document_filename);
+            break;
 		default:
 			assert(false);
 			break;

engine/src/platform.h

@@ -795,6 +795,8 @@ enum MCPlatformWindowProperty
     kMCPlatformWindowPropertyHideOnSuspend,
 
     kMCPlatformWindowPropertyIgnoreMouseEvents,
+
+    kMCPlatformWindowPropertyDocumentFilename,
 };
 
 void MCPlatformSetWindowProperty(MCPlatformWindowRef window, MCPlatformWindowProperty property, MCPlatformPropertyType type, const void *value);

engine/src/srvstack.cpp

@@ -200,6 +200,11 @@ void MCStack::enablewindow(bool enable)
 {
 }
 
+// MERG-2015-10-12: [[ DocumentFilename ]] Stub for documentFilename.
+void MCStack::updatedocumentfilename(void)
+{
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 
 bool MCStack::configure_window_buffer()

engine/src/stack.cpp

@@ -198,6 +198,9 @@ MCPropertyInfo MCStack::kProperties[] =
 
     // MERG-2015-08-31: [[ ScriptOnly ]] Add stack scriptOnly property
     DEFINE_RW_OBJ_PROPERTY(P_SCRIPT_ONLY, Bool, MCStack, ScriptOnly)
+
+    // MERG-2015-10-11: [[ DocumentFilename ]] Add stack documentFilename property
+    DEFINE_RW_OBJ_PROPERTY(P_DOCUMENT_FILENAME, String, MCStack, DocumentFilename)
 };
 
 MCObjectPropertyTable MCStack::kPropertyTable =
@@ -291,6 +294,9 @@ MCStack::MCStack()
 
 	// IM-2014-05-27: [[ Bug 12321 ]] No fonts to purge yet
 	m_purge_fonts = false;
+
+    // MERG-2015-10-11: [[ DocumentFilename ]] The filename the stack represnts
+    m_document_filename = MCValueRetain(kMCEmptyString);
 
 	m_view_need_redraw = false;
 	m_view_need_resize = false;
@@ -500,6 +506,9 @@ MCStack::MCStack(const MCStack &sref) : MCObject(sref)
 
     m_attachments = nil;
 
+    // MERG-2015-10-12: [[ DocumentFilename ]] No document filename to begin with
+    m_document_filename = MCValueRetain(kMCEmptyString);
+
 	view_copy(sref);
 }