Merge pull request livecode#7048 from livecodeian/feature-widget_reference

montegoulding · web-flow · commit a6445205f8eb · 2019-06-04T10:14:18.000+10:00
[[ Widget ]] Add `this widget` and `trigger all in &lt;widget&gt;` syntax
diff --git a/docs/lcb/notes/feature-widget_reference.md b/docs/lcb/notes/feature-widget_reference.md
@@ -0,0 +1,10 @@
+# LiveCode Builder Host Library
+## Widget Library
+New syntax has been added to obtain a reference to the widget, and to use that
+reference when notifying the engine of property changes via the `trigger all`
+command.
+
+This is most useful when LCB handlers within a widget module are used as
+asynchronous callback functions passed to foreign functions, as these may be
+called at a time when the widget is not the currently active widget. Using the
+reference prevents updates being seen as coming from the wrong widget.
diff --git a/engine/src/widget-syntax.cpp b/engine/src/widget-syntax.cpp
@@ -143,6 +143,11 @@ extern "C" MC_DLLEXPORT_DEF void MCWidgetExecTriggerAll(void)
     MCWidgetTriggerAll(MCcurrentwidget);
 }
 
+extern "C" MC_DLLEXPORT_DEF void MCWidgetExecTriggerAllInWidget(MCWidgetRef p_widget)
+{
+	MCWidgetTriggerAll(p_widget);
+}
+
 ////////////////////////////////////////////////////////////////////////////////
 
 extern "C" MC_DLLEXPORT_DEF void MCWidgetGetMyScriptObject(MCScriptObjectRef& r_script_object)
@@ -475,6 +480,14 @@ extern "C" MC_DLLEXPORT_DEF void MCWidgetGetMouseButtonState(uinteger_t p_index,
 
 ////////////////////////////////////////////////////////////////////////////////
 
+extern "C" MC_DLLEXPORT_DEF void MCWidgetEvalThisWidget(MCWidgetRef& r_widget)
+{
+	if (!MCWidgetEnsureCurrentWidget())
+		return;
+	
+	r_widget = MCValueRetain(MCcurrentwidget);
+}
+
 extern "C" MC_DLLEXPORT_DEF void MCWidgetEvalTheTarget(MCWidgetRef& r_widget)
 {
     if (!MCWidgetEnsureCurrentWidget())
diff --git a/engine/src/widget.lcb b/engine/src/widget.lcb
@@ -394,13 +394,18 @@ use com.livecode.foreign
 use com.livecode.canvas
 use com.livecode.engine
 
+// ---------- Widget type definition ---------- //
+
+public foreign type Widget binds to "MCWidgetTypeInfo"
+
 // ---------- Widget commands ---------- //
 
 public foreign handler MCWidgetExecRedrawAll() returns nothing binds to "<builtin>"
 public foreign handler MCWidgetExecScheduleTimerIn(in pTime as CDouble) returns nothing binds to "<builtin>"
 public foreign handler MCWidgetExecCancelTimer() returns nothing binds to "<builtin>"
 public foreign handler MCWidgetEvalInEditMode(out rInEditMode as CBool) returns nothing binds to "<builtin>"
 public foreign handler MCWidgetExecTriggerAll() returns nothing binds to "<builtin>"
+public foreign handler MCWidgetExecTriggerAllInWidget(in pWidget as Widget) returns nothing binds to "<builtin>"
 
 /**
 Summary:	Redraws the widget.
@@ -488,23 +493,32 @@ end syntax
 
 /**
 Summary:	Causes all of a widget's property triggers to be fired.
+mWidget:	An expression that evaluates to a widget.
 
 Example:
 	handler TextChangedCallback()
         UpdateTextProperty()
         trigger all
 	end handler
 
+Example:
+	private variable mSelf as Widget
+	handler TextChangedCallback()
+		UpdateTextProperty()
+		trigger all in mSelf
+	end handler
+
 Description:
 Use trigger all to cause all triggers for all a widget's properties to 
 be fired, for example when user action causes a native widget's 
 properties to change, to signal the property change to the IDE.
 */
 
 syntax TriggerAll is statement
-  "trigger" "all"
+  "trigger" "all" [ "in" <mWidget: Expression> ]
 begin
   MCWidgetExecTriggerAll()
+  MCWidgetExecTriggerAllInWidget(mWidget)
 end syntax
 
 
@@ -1164,8 +1178,7 @@ end syntax
 
 // annotation <name> of <widget>
 
-public foreign type Widget binds to "MCWidgetTypeInfo"
-
+public foreign handler MCWidgetEvalThisWidget(out rMe as optional Widget) returns nothing binds to "<builtin>"
 public foreign handler MCWidgetEvalTheTarget(out rTarget as optional Widget) returns nothing binds to "<builtin>"
 
 public foreign handler MCWidgetEvalMyChildren(out rChildWidgets as List) returns nothing binds to "<builtin>"
@@ -1260,6 +1273,49 @@ end syntax
 
 //
 
+/**
+Summary: Returns the current widget.
+Returns: A widget object.
+
+Example:
+
+-- In a widget
+private variable mSelf as Widget
+public handler OnCreate() returns nothing
+	-- Keep a reference to this widget
+	put this widget into mSelf
+
+	-- defined in separate module library
+	SetEventCallback(EventCallback)
+end handler
+
+-- may be called from another module library
+private handler EventCallback() returns nothing
+	-- update internal variables
+
+	-- notify ide of changes
+	trigger all in mSelf
+end handler
+
+Description:
+This widget evaluates to the current widget. This can be used to retain a
+reference for occasions where widget handlers may be called from another module,
+where the current widget may not be valid.
+
+This is useful when LCB handlers within a widget module are used as
+asynchronous callback functions passed to foreign functions, as these may be
+called at a time when the widget is not the currently active widget. Using the
+reference prevents updates being seen as coming from the wrong widget.
+*/
+
+syntax ThisWidget is expression
+	"this" "widget"
+begin
+	MCWidgetEvalThisWidget(output)
+end syntax
+
+//
+
 /**
 Summary: The currently placed child widgets of this widget.
 Returns: A list of the child widgets of this widget.
