Plug tooltips.

Added a GafferUI.Metadata class which is used to register descriptions for the various node and plug types. Used it to implement tooltip help for plugs, with the tooltip coming from the "parameterName.help" annotation in the case of RenderManShader nodes. We still need to register appropriate metadata for all existing nodes and generate documentation from it.

Changes

@@ -1,5 +1,7 @@
 * RenderManShader node now supports the use of annotations within the shader to define the node UI. Annotations follow the OSL specification for shader metadata.
 
+* Added the GafferUI.Metadata class, which will be used to provide things such as node and plug descriptions for the generation of tooltips and reference documentation.
+
 0.55.0
 ======
 

python/GafferRenderManUI/RenderManShaderUI.py

@@ -243,3 +243,16 @@ def __plugValueWidgetCreator( plug ) :
 	return GafferUI.PlugValueWidget.create( plug, useTypeOnly=True )
 
 GafferUI.PlugValueWidget.registerCreator( GafferRenderMan.RenderManShader.staticTypeId(), "parameters.*", __plugValueWidgetCreator )
+
+##########################################################################
+# Metadata registrations
+##########################################################################
+
+def __plugDescription( plug ) :
+
+	annotations = __shaderAnnotations( plug.node() )
+	d = annotations.get( plug.getName() + ".help", None )	
+
+	return d.value if d is not None else ""
+
+GafferUI.Metadata.registerPlugDescription( GafferRenderMan.RenderManShader, "parameters.*", __plugDescription )

python/GafferUI/Metadata.py

@@ -0,0 +1,133 @@
+##########################################################################
+#  
+#  Copyright (c) 2013, Image Engine Design Inc. All rights reserved.
+#  
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are
+#  met:
+#  
+#      * Redistributions of source code must retain the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer.
+#  
+#      * Redistributions in binary form must reproduce the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer in the documentation and/or other materials provided with
+#        the distribution.
+#  
+#      * Neither the name of John Haddon nor the names of
+#        any other contributors to this software may be used to endorse or
+#        promote products derived from this software without specific prior
+#        written permission.
+#  
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+#  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+#  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+#  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+#  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+#  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+#  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+#  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+#  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+#  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+#  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#  
+##########################################################################
+
+import re
+import fnmatch
+
+import IECore
+
+import Gaffer
+
+## The Metadata class provides a registry of metadata for the different types
+# of Nodes and Plugs. This metadata assists in creating UIs and can be used to
+# generate documentation.
+class Metadata :
+
+	## Registers a textual description for nodes of the specified type.
+	# The description may either be a string or a callable which will compute
+	# a description when passed a node instance.
+	@classmethod
+	def registerNodeDescription( cls, nodeType, description ) :
+
+		if isinstance( nodeType, IECore.TypeId ) :
+			nodeTypeId = nodeType
+		else :
+			nodeTypeId = nodeType.staticTypeId()
+
+		cls.__nodeDescriptions[nodeTypeId] = description
+
+	## Returns a description for the specified node instance.
+	@classmethod
+	def nodeDescription( cls, node ) :
+
+		nodeTypeId = node.typeId()
+		while nodeTypeId != IECore.TypeId.Invalid :
+
+			description = cls.__nodeDescriptions.get( nodeTypeId, None )
+			if description is not None :
+				if callable( description ) :
+					return description( node )
+				else :
+					return description
+
+			nodeTypeId = IECore.RunTimeTyped.baseTypeId( nodeTypeId )
+
+		return ""
+
+	## Registers a textual description for the specified plug on nodes of the
+	# specified type. The plugPath may be a string optionally containing fnmatch
+	# wildcard characters or be a regex for performing more complex matches.
+	# The description may either be a string or a callable which will compute
+	# a description when passed a node instance.
+	@classmethod
+	def registerPlugDescription( cls, nodeType, plugPath, stringOrCallable ) :
+
+		if isinstance( nodeType, IECore.TypeId ) :
+			nodeTypeId = nodeType
+		else :
+			nodeTypeId = nodeType.staticTypeId()
+
+		if isinstance( plugPath, basestring ) :
+			plugPath = re.compile( fnmatch.translate( plugPath ) )
+		else :
+			assert( type( plugPath ) is type( re.compile( "" ) ) )
+
+		plugDescriptions = cls.__plugDescriptions.setdefault( nodeTypeId, [] )
+		plugDescriptions.insert(
+			0,
+			IECore.Struct(
+				plugPathMatcher = plugPath,
+				description = stringOrCallable
+			)
+		)
+
+	## Returns a description for the specified plug instance.
+	@classmethod
+	def plugDescription( cls, plug ) :
+
+		node = plug.node()
+		if node is None :
+			return ""
+
+		plugPath = plug.relativeName( node )
+
+		nodeTypeId = node.typeId()
+		while nodeTypeId != IECore.TypeId.Invalid :
+			plugDescriptions = cls.__plugDescriptions.get( nodeTypeId, None )
+			if plugDescriptions is not None :
+				for d in plugDescriptions :
+					if d.plugPathMatcher.match( plugPath ) :
+						if callable( d.description ) :
+							return d.description( plug )
+						else :
+							return d.description
+
+			nodeTypeId = IECore.RunTimeTyped.baseTypeId( nodeTypeId )
+
+		return ""
+
+	__nodeDescriptions = {}
+	__plugDescriptions = {}

python/GafferUI/PlugWidget.py

@@ -75,6 +75,8 @@ def __init__( self, plugOrWidget, label=None, description=None, **kw ) :
 		if label is not None :
 			self.__label.setText( label )
 
+		self.__label.setToolTip( GafferUI.Metadata.plugDescription( plug ) )
+
 		## \todo Decide how we allow this sort of tweak using the public
 		# interface. Perhaps we should have a SizeableContainer or something?
 		self.__label._qtWidget().setMinimumWidth( self.labelWidth() )

python/GafferUI/__init__.py

@@ -182,6 +182,7 @@ def _qtImport( name, lazy=False ) :
 from TransformPlugValueWidget import TransformPlugValueWidget
 from IncrementingPlugValueWidget import IncrementingPlugValueWidget
 from SectionedCompoundPlugValueWidget import SectionedCompoundPlugValueWidget
+from Metadata import Metadata
 
 # then stuff specific to parameterised objects
 

python/GafferUITest/MetadataTest.py

@@ -0,0 +1,99 @@
+##########################################################################
+#  
+#  Copyright (c) 2013, Image Engine Design Inc. All rights reserved.
+#  
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are
+#  met:
+#  
+#      * Redistributions of source code must retain the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer.
+#  
+#      * Redistributions in binary form must reproduce the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer in the documentation and/or other materials provided with
+#        the distribution.
+#  
+#      * Neither the name of John Haddon nor the names of
+#        any other contributors to this software may be used to endorse or
+#        promote products derived from this software without specific prior
+#        written permission.
+#  
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+#  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+#  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+#  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+#  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+#  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+#  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+#  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+#  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+#  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+#  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#  
+##########################################################################
+
+import unittest
+
+import IECore
+
+import Gaffer
+import GafferTest
+import GafferUI
+import GafferUITest
+
+class MetadataTest( GafferUITest.TestCase ) :
+
+	class DerivedAddNode( GafferTest.AddNode ) :
+
+		def __init__( self, name="DerivedAddNode" ) :
+
+			GafferTest.AddNode.__init__( self, name )
+
+	IECore.registerRunTimeTyped( DerivedAddNode )
+
+	def testNodeDescription( self ) :
+
+		add = GafferTest.AddNode()
+
+		self.assertEqual( GafferUI.Metadata.nodeDescription( add ), "" )
+
+		GafferUI.Metadata.registerNodeDescription( GafferTest.AddNode, "description" )
+		self.assertEqual( GafferUI.Metadata.nodeDescription( add ), "description" )
+
+		GafferUI.Metadata.registerNodeDescription( GafferTest.AddNode, lambda node : node.getName() )
+		self.assertEqual( GafferUI.Metadata.nodeDescription( add ), "AddNode" )
+
+		derivedAdd = self.DerivedAddNode()
+		self.assertEqual( GafferUI.Metadata.nodeDescription( derivedAdd ), "DerivedAddNode" )
+
+		GafferUI.Metadata.registerNodeDescription( self.DerivedAddNode.staticTypeId(), "a not very helpful description" )
+		self.assertEqual( GafferUI.Metadata.nodeDescription( derivedAdd ), "a not very helpful description" )
+		self.assertEqual( GafferUI.Metadata.nodeDescription( add ), "AddNode" )
+
+	def testPlugDescription( self ) :
+
+		add = GafferTest.AddNode()
+
+		self.assertEqual( GafferUI.Metadata.plugDescription( add["op1"] ), "" )
+
+		GafferUI.Metadata.registerPlugDescription( GafferTest.AddNode.staticTypeId(), "op1", "The first operand" )
+		self.assertEqual( GafferUI.Metadata.plugDescription( add["op1"] ), "The first operand" )
+
+		GafferUI.Metadata.registerPlugDescription( GafferTest.AddNode.staticTypeId(), "op1", lambda plug : plug.getName() + " description" )
+		self.assertEqual( GafferUI.Metadata.plugDescription( add["op1"] ), "op1 description" )
+
+		derivedAdd = self.DerivedAddNode()
+		self.assertEqual( GafferUI.Metadata.plugDescription( derivedAdd["op1"] ), "op1 description" )
+
+		GafferUI.Metadata.registerPlugDescription( self.DerivedAddNode, "op*", "derived class description" )
+		self.assertEqual( GafferUI.Metadata.plugDescription( derivedAdd["op1"] ), "derived class description" )
+		self.assertEqual( GafferUI.Metadata.plugDescription( derivedAdd["op2"] ), "derived class description" )
+
+		self.assertEqual( GafferUI.Metadata.plugDescription( add["op1"] ), "op1 description" )
+		self.assertEqual( GafferUI.Metadata.plugDescription( add["op2"] ), "" )
+
+if __name__ == "__main__":
+	unittest.main()
+

python/GafferUITest/__init__.py

@@ -81,6 +81,7 @@
 from ScriptWindowTest import ScriptWindowTest
 from CompoundPlugValueWidgetTest import CompoundPlugValueWidgetTest
 from CompoundEditorTest import CompoundEditorTest
+from MetadataTest import MetadataTest
 
 if __name__ == "__main__":
 	unittest.main()