gstat -add status-message description

Author: c-morley

docs/src/gui/gstat.adoc

@@ -487,6 +487,62 @@ This depends on the widget/libraries used.
 intended to be sent when requesting LinuxCNC to shutdown. +
 This depends on the widget/libraries used.
 
+*status-message* :: 'returns python dict (message), python dict (options)'
+Intended for a screen/panel to get status/log messages from widgets, but can be used generally. +
+The listening object is expected to look for and handle at least these entries: +
+
+The message dict would include: +
+
+ * TITLE: (string)
+ * SHORTTEXT: (string)
+ * DETAILS: (string)
+
+The options dict would include: +
+
+ * LEVEL: (integer)
+ * LOG: (bool)
+
+The listening object could use this to display information on a text line or message dialog. +
+The LEVEL would indicate urgency 0 = DEFAULT 1 = WARNING 2 = CRITICAL +
+LOG indicates whether the message should be logged to a file/page if available. +
+LOG messages would be assumed to use the DETAILS entry. +
+
+An example of how to send a message:
+
+[source,python]
+----
+mess = {'SHORTTEXT':'File Copy Failed',
+        'TITLE':'FileManager',
+        'DETAILS':'There is not enough room on disk to copy the file'}
+opt = {'LOG':True,'LEVEL':2}
+STATUS.emit('status-message',mess,opt)
+----
+
+An example of the listening object:
+
+[source,python]
+----
+# tell STATUS we want to respond to any sent 'status-message' messages.
+STATUS.connect('status-message', lambda w, d, o: self.add_external_status(m,o))
+
+    def add_external_status(self, message, option):
+
+        # extract and trap errors for expected entries
+        level = option.get('LEVEL', STATUS.DEFAULT) 
+        log = option.get("LOG", True)
+        title = message.get('TITLE', '')
+        mess = message.get('SHORTTEXT', '')
+        logtext = message.get('DETAILS', '')
+
+        # call a function to print the message on a statusbar:
+        self.add_status(mess, level, noLog=True)
+
+        # request a log file update
+        if log:
+            STATUS.emit('update-machine-log', "{}\n{}".format(title, logtext), 'TIME')
+
+----
+
 *error* :: '(returns integer, string)' -
 intended to be sent when an error has been reported . +
 integer represents the kind of error. ERROR, TEXT or DISPLAY +
@@ -623,4 +679,4 @@ returns string representing the internal selected axis letter.
 Some status points are reported wrongly during a running program because the interpreter runs ahead of the current position of a running program.
 This will hopefully be resolved with the merge of state-tags branch.
 
-// vim: set syntax=asciidoc:
+// vim: set syntax=asciidoc: