Development/Tutorials/Plasma/Python/Using DataEngines - Revision history

Neverendingo: Text replace - "" to ""

2011-06-29T20:54:09Z

Text replace - "</code>" to "</syntaxhighlight>"

Neverendingo: Text replace - "`" to ""`


2011-06-29T20:39:37Z
Text replace - "<code bash>" to "<syntaxhighlight lang="bash">"

				
				
				
				
			
			← Older revision
			Revision as of 20:39, 29 June 2011
			
Line 10:
Line 10:
    
  Plasma comes with a handy tool called <tt>plasmaengineexplorer</tt> which lists all of the available DataEngines and can be used to examine them to see what kind of data and fields they send. <tt>plasmaengineexplorer</tt> can be started directly from the shell.   Plasma comes with a handy tool called <tt>plasmaengineexplorer</tt> which lists all of the available DataEngines and can be used to examine them to see what kind of data and fields they send. <tt>plasmaengineexplorer</tt> can be started directly from the shell.
− <code bash> + <syntaxhighlight lang="bash">
  plasmaengineexplorer   plasmaengineexplorer
  </code>   </code>



Neverendingo: Text replace - "" to ""

2011-06-29T20:29:54Z
Text replace - "<code python>" to "<syntaxhighlight lang="python">"

				
				
				
				
			
			← Older revision
			Revision as of 20:29, 29 June 2011
			
Line 27:
Line 27:
    
  The code to connect to the "time" DataEngine is in the clock's <tt>connectToEngine()</tt> method, shown below.   The code to connect to the "time" DataEngine is in the clock's <tt>connectToEngine()</tt> method, shown below.
− <code python> + <syntaxhighlight lang="python">
  def connectToEngine(self):   def connectToEngine(self):
       self.timeEngine = self.dataEngine("time")        self.timeEngine = self.dataEngine("time")
Line 44:
Line 44:
    
  Data is injected into the applet via the <tt>dataUpdate()</tt> method.   Data is injected into the applet via the <tt>dataUpdate()</tt> method.
− <code python> + <syntaxhighlight lang="python">
  @pyqtSignature("dataUpdated(const QString &, const Plasma::DataEngine::Data &)")   @pyqtSignature("dataUpdated(const QString &, const Plasma::DataEngine::Data &)")
  def dataUpdated(self, sourceName, data):   def dataUpdated(self, sourceName, data):



Tmske: fixed typo
2009-01-18T16:21:47Z
fixed typo

				
				
				
				
			
			← Older revision
			Revision as of 16:21, 18 January 2009
			
Line 57:
Line 57:
       self.update()        self.update()
  </code>   </code>
− The <tt>dataUpdated()</tt> method takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt>, and then the data itself. The big <tt>@pyqtSignature()</tt> line just before <tt>dataUpdated()</tt> is a Python decorator which marks this Python method as having <tt>const QString &, const Plasma::DataEngine::Data &</tt> as its C++ method signature. This is needed so that Qt and find the correct method on our applet when data is sent. + The <tt>dataUpdated()</tt> method takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt>, and then the data itself. The big <tt>@pyqtSignature()</tt> line just before <tt>dataUpdated()</tt> is a Python decorator which marks this Python method as having <tt>const QString &, const Plasma::DataEngine::Data &</tt> as its C++ method signature. This is needed so that Qt can find the correct method on our applet when data is sent.
    
  The code just ignores the <tt>sourceName</tt> parameter because it knows that the data must be from the "time" DataEngine, and just concentrates on the data. The <tt>sourceName</tt> parameter becomes important when you have multiple DataEngines attached to the same applet. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method.   The code just ignores the <tt>sourceName</tt> parameter because it knows that the data must be from the "time" DataEngine, and just concentrates on the data. The <tt>sourceName</tt> parameter becomes important when you have multiple DataEngines attached to the same applet. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method.



Sedwards: corrections
2009-01-18T15:16:10Z
corrections

				
				
				
				
			
			← Older revision
			Revision as of 15:16, 18 January 2009
			
Line 1:
Line 1:
  == Abstract ==   == Abstract ==
    
− One of the most important concepts in Plasma is that of the "DataEngine". DataEngines are used to deliver data from somewhere, often from an internet service for example, to your applet. In this tutorial we'll discuss DataEngines, what they are, and how to use them from your Plasma applet. + One of the most important concepts in Plasma is that of the "DataEngine". DataEngines are used to deliver data from somewhere, often from an internet service for example, to your applet. In this tutorial we will discuss DataEngines, what they are, and how to use them from your Plasma applet.
    
  == What are DataEngines? ==   == What are DataEngines? ==
    
− As already mentioned, DataEngines are objects which serve to deliver some kind of data to Plasma applets. Plasma supports many different DataEngines out of the box which deliver all sorts of varied information about the state of the machine, e.g. CPU usage, memory usage, position of the mouse pointer; to things such as the current weather report, current time or the latest comic from the internet. DataEngines are used to supply the raw data which an applet can display. Separating the part of the code which fetches data from the part which displays the data means that one DataEngine can be reused by many applets, regardless of which language the DataEngine is written in. It also makes it easy for people to display the same data using different applets which may tuned to different tasks of screen form factors. + As already mentioned, DataEngines are objects which serve to deliver some kind of data to one or more Plasma applets. Plasma supports many different DataEngines out of the box which deliver all kinds of varied information about things like the state of the machine, e.g. CPU usage, memory usage, position of the mouse pointer; to things such as the current weather report, current time or the latest comic from the internet. DataEngines are used to supply the raw data which an applet displays. Separating the part of the code that fetches data from the part which displays the data, means that one DataEngine can be reused by many applets, regardless of which language the DataEngine or applet is written in. It also makes it easy for people to display the same data using different applets which may tuned towards different uses or screen form factors.
    
  == Exploring DataEngines ==   == Exploring DataEngines ==
    
− Plasma comes with a handy tool called <tt>plasmaengineexplorer</tt> to list the running DataEngines and examine them to see what kind of data and fields them send. <tt>plasmaengineexplorer</tt> can be simply started from the shell as so. + Plasma comes with a handy tool called <tt>plasmaengineexplorer</tt> which lists all of the available DataEngines and can be used to examine them to see what kind of data and fields they send. <tt>plasmaengineexplorer</tt> can be started directly from the shell.
  <code bash>   <code bash>
  plasmaengineexplorer   plasmaengineexplorer
Line 17:
Line 17:
  [[Image:Dataengine_snapshot.png|center]]   [[Image:Dataengine_snapshot.png|center]]
    
− The "time" DataEngine periodically publishes the current time for many different timezones. The first timezone in the list ("/etc/localtime") is special and simply refers to the current local time on the computer without referring to a specific timezone. If you open the "/etc/localtime" node in the tree you can see which data fields the "time" DataEngine provides. The most important fields are the "Time" and "Date". The <tt>plasmaengineexplorer</tt> also lists what kind of data type the field is, e.g. a <tt>QString</tt>, <tt>QTime</tt> or <tt>QDate</tt>. This information is needed when hooking up a DataEngine to your applet. + The "time" DataEngine periodically publishes the current time for many different timezones. The first timezone in the list ("/etc/localtime") is special and simply refers to the current local time on the computer without referring to any specific timezone. If you open the "/etc/localtime" node in the tree you can see which data fields the "time" DataEngine provides. The most important fields are "Time" and "Date". The <tt>plasmaengineexplorer</tt> also lists what data type the field is, e.g. a <tt>QString</tt>, <tt>QTime</tt> or <tt>QDate</tt>. This information is needed when hooking up a DataEngine to your applet.
    
  Explore some of the other DataEngines in the list. Perhaps it will give you some good ideas for new and interesting applets.   Explore some of the other DataEngines in the list. Perhaps it will give you some good ideas for new and interesting applets.
Line 23:
Line 23:
  == Connecting to a DataEngine ==   == Connecting to a DataEngine ==
    
− The Python clock example code is a good example of how to connect to the "time" DateEngine. You can view the   + The Python clock code is a good example of how to connect to the "time" DateEngine. You can view the  
− [http://websvn.kde.org/branches/KDE/4.2/kdebase/workspace/plasma/scriptengines/python/examples/applets/pyclock/contents/code/main.py?revision=906699&view=markup main.py code online here online]. Let's look at how the Python clock does it. + [http://websvn.kde.org/branches/KDE/4.2/kdebase/workspace/plasma/scriptengines/python/examples/applets/pyclock/contents/code/main.py?revision=906699&view=markup main.py code here online]. Let's take a look at how the Python clock works.
    
− The code to connect to the "time" DataEngine is in the clock's <tt>connectToEngine()</tt> method. + The code to connect to the "time" DataEngine is in the clock's <tt>connectToEngine()</tt> method, shown below.
  <code python>   <code python>
  def connectToEngine(self):   def connectToEngine(self):
Line 41:
Line 41:
  The <tt>connectSource()</tt> method on the DataEngine binds it to this applet. The first parameter is the "DataSource" name. This corresponds to the "DataSouce" column in <tt>plasmaengineexplorer</tt>. For the "time" DataEngine, it selects which timezone you want the time for. The next parameter is where the data should be sent. In this case it is quite simple, just send the data to this applet. The number is the "polling interval" in milliseconds. This is how often the data should be updated. Depending on how often the clock needs to update its display, it calls the <tt>connectSource()</tt> method with either 500 or 6000 milliseconds as the polling interval.   The <tt>connectSource()</tt> method on the DataEngine binds it to this applet. The first parameter is the "DataSource" name. This corresponds to the "DataSouce" column in <tt>plasmaengineexplorer</tt>. For the "time" DataEngine, it selects which timezone you want the time for. The next parameter is where the data should be sent. In this case it is quite simple, just send the data to this applet. The number is the "polling interval" in milliseconds. This is how often the data should be updated. Depending on how often the clock needs to update its display, it calls the <tt>connectSource()</tt> method with either 500 or 6000 milliseconds as the polling interval.
    
− <tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. Many many applets syncronise to the same way, then Plasma can handle the updates in large batches instead of many small updates. This is important on mobile devices which throttle the CPU down to save battery power. It is more efficient for these devices if updates are done in big batches instead of many small batches. + <tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. When many applets syncronise the same way, then Plasma can handle the data updates for all of the applets in large batches instead of many small batches. This is important on mobile devices which throttle the CPU down to save battery power. It is more energy efficient for these devices if updates are done in big batches instead of many small batches.
    
− Data is injected in the applet via the <tt>dataUpdate()</tt> method. + Data is injected into the applet via the <tt>dataUpdate()</tt> method.
  <code python>   <code python>
  @pyqtSignature("dataUpdated(const QString &, const Plasma::DataEngine::Data &)")   @pyqtSignature("dataUpdated(const QString &, const Plasma::DataEngine::Data &)")
Line 57:
Line 57:
       self.update()        self.update()
  </code>   </code>
− The <tt>dataUpdated()</tt> takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt> and the data itself. The big <tt>@pyqtSignature()</tt> line just before <tt>dataUpdated()</tt> is a Python decorator which marks this Python method as having <tt>const QString &, const Plasma::DataEngine::Data &</tt> as its C++ method signature. This is needed so that Qt and find the correct method on our applet. + The <tt>dataUpdated()</tt> method takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt>, and then the data itself. The big <tt>@pyqtSignature()</tt> line just before <tt>dataUpdated()</tt> is a Python decorator which marks this Python method as having <tt>const QString &, const Plasma::DataEngine::Data &</tt> as its C++ method signature. This is needed so that Qt and find the correct method on our applet when data is sent.
    
− The code just ignores the <tt>sourceName</tt> parameter because it knows that the data must be from the "time" DataEngine, and just concentrates on the data. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method. + The code just ignores the <tt>sourceName</tt> parameter because it knows that the data must be from the "time" DataEngine, and just concentrates on the data. The <tt>sourceName</tt> parameter becomes important when you have multiple DataEngines attached to the same applet. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method.
    
− Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock's display is only updated if really necessary, followed by some code which actually updates the time and redraws the display. + Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock's display is only updated if really necessary, followed by the code to actually update the time and redraw the display.
    
  == Conclusion ==   == Conclusion ==
    
  As you can see DataEngines are a great way of delivering data to applets which can also be easily reused by different applets. Connecting a DataEngine to your applet is a simple matter of fetching the data engine itself, connecting up to the wanted data source and then accepting the processing the data in your own <tt>dataUpdated()</tt> method.   As you can see DataEngines are a great way of delivering data to applets which can also be easily reused by different applets. Connecting a DataEngine to your applet is a simple matter of fetching the data engine itself, connecting up to the wanted data source and then accepting the processing the data in your own <tt>dataUpdated()</tt> method.



Sedwards: content is now complete
2009-01-18T15:01:12Z
content is now complete

				
				
				
				
			
			← Older revision
			Revision as of 15:01, 18 January 2009
			
Line 63:
Line 63:
  Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock's display is only updated if really necessary, followed by some code which actually updates the time and redraws the display.   Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock's display is only updated if really necessary, followed by some code which actually updates the time and redraws the display.
    
  + == Conclusion ==
    
−   + As you can see DataEngines are a great way of delivering data to applets which can also be easily reused by different applets. Connecting a DataEngine to your applet is a simple matter of fetching the data engine itself, connecting up to the wanted data source and then accepting the processing the data in your own <tt>dataUpdated()</tt> method.
− TODO: finish tutorial. + 



Sedwards at 14:55, 18 January 2009
2009-01-18T14:55:33Z


				
				
				
				
			
			← Older revision
			Revision as of 14:55, 18 January 2009
			
Line 57:
Line 57:
       self.update()        self.update()
  </code>   </code>
− The <tt>dataUpdated()</tt> takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt> and the data itself. In this case we just ignore the source name because we know that it must be from the "time" DataEngine, and just concentrate on the data. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method. + The <tt>dataUpdated()</tt> takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt> and the data itself. The big <tt>@pyqtSignature()</tt> line just before <tt>dataUpdated()</tt> is a Python decorator which marks this Python method as having <tt>const QString &, const Plasma::DataEngine::Data &</tt> as its C++ method signature. This is needed so that Qt and find the correct method on our applet.
    
− Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock display is only updated if really necessary, followed by some code which actually updates the time and redraws the display. + The code just ignores the <tt>sourceName</tt> parameter because it knows that the data must be from the "time" DataEngine, and just concentrates on the data. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method.
  +  
  + Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock's display is only updated if really necessary, followed by some code which actually updates the time and redraws the display.
    
    
    
  TODO: finish tutorial.   TODO: finish tutorial.



Sedwards at 14:50, 18 January 2009
2009-01-18T14:50:33Z


				
				
				
				
			
			← Older revision
			Revision as of 14:50, 18 January 2009
			
Line 42:
Line 42:
    
  <tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. Many many applets syncronise to the same way, then Plasma can handle the updates in large batches instead of many small updates. This is important on mobile devices which throttle the CPU down to save battery power. It is more efficient for these devices if updates are done in big batches instead of many small batches.   <tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. Many many applets syncronise to the same way, then Plasma can handle the updates in large batches instead of many small updates. This is important on mobile devices which throttle the CPU down to save battery power. It is more efficient for these devices if updates are done in big batches instead of many small batches.
  + 
  + Data is injected in the applet via the <tt>dataUpdate()</tt> method.
  + <code python>
  + @pyqtSignature("dataUpdated(const QString &, const Plasma::DataEngine::Data &)")
  + def dataUpdated(self, sourceName, data):
  +     self.time = data[QString("Time")].toTime()
  + 
  +     if self.time.minute() == self.lastTimeSeen.minute() and \
  +            self.time.second() == self.lastTimeSeen.second():
  +         # avoid unnecessary repaints
  +         return
  + 
  +     self.lastTimeSeen = self.time
  +     self.update()
  + </code>
  + The <tt>dataUpdated()</tt> takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt> and the data itself. In this case we just ignore the source name because we know that it must be from the "time" DataEngine, and just concentrate on the data. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method.
  + 
  + Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock display is only updated if really necessary, followed by some code which actually updates the time and redraws the display.
  + 
    
    
  TODO: finish tutorial.   TODO: finish tutorial.



Sedwards at 14:30, 18 January 2009
2009-01-18T14:30:52Z


				
				
				
				
			
			← Older revision
			Revision as of 14:30, 18 January 2009
			
Line 23:
Line 23:
  == Connecting to a DataEngine ==   == Connecting to a DataEngine ==
    
  + The Python clock example code is a good example of how to connect to the "time" DateEngine. You can view the 
  + [http://websvn.kde.org/branches/KDE/4.2/kdebase/workspace/plasma/scriptengines/python/examples/applets/pyclock/contents/code/main.py?revision=906699&view=markup main.py code online here online]. Let's look at how the Python clock does it.
  + 
  + The code to connect to the "time" DataEngine is in the clock's <tt>connectToEngine()</tt> method.
  + <code python>
  + def connectToEngine(self):
  +     self.timeEngine = self.dataEngine("time")
  +     if self.showSecondHand:
  +         self.timeEngine.connectSource(self.currentTimezone,
  +             self, 500)
  +     else:
  +         self.timeEngine.connectSource(self.currentTimezone,
  +             self, 6000, Plasma.AlignToMinute)
  + </code>
  + This method is called from the clock's <tt>init()</tt> method. It first calls the <tt>dateEngine()</tt> method on the <tt>plasmascript.Applet</tt> class to get a reference to the "time" DataEngine.
  + 
  + The <tt>connectSource()</tt> method on the DataEngine binds it to this applet. The first parameter is the "DataSource" name. This corresponds to the "DataSouce" column in <tt>plasmaengineexplorer</tt>. For the "time" DataEngine, it selects which timezone you want the time for. The next parameter is where the data should be sent. In this case it is quite simple, just send the data to this applet. The number is the "polling interval" in milliseconds. This is how often the data should be updated. Depending on how often the clock needs to update its display, it calls the <tt>connectSource()</tt> method with either 500 or 6000 milliseconds as the polling interval.
  + 
  + <tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. Many many applets syncronise to the same way, then Plasma can handle the updates in large batches instead of many small updates. This is important on mobile devices which throttle the CPU down to save battery power. It is more efficient for these devices if updates are done in big batches instead of many small batches.
    
    
  TODO: finish tutorial.   TODO: finish tutorial.



Sedwards at 13:35, 18 January 2009
2009-01-18T13:35:19Z


				
				
				
				
			
			← Older revision
			Revision as of 13:35, 18 January 2009
			
Line 19:
Line 19:
  The "time" DataEngine periodically publishes the current time for many different timezones. The first timezone in the list ("/etc/localtime") is special and simply refers to the current local time on the computer without referring to a specific timezone. If you open the "/etc/localtime" node in the tree you can see which data fields the "time" DataEngine provides. The most important fields are the "Time" and "Date". The <tt>plasmaengineexplorer</tt> also lists what kind of data type the field is, e.g. a <tt>QString</tt>, <tt>QTime</tt> or <tt>QDate</tt>. This information is needed when hooking up a DataEngine to your applet.   The "time" DataEngine periodically publishes the current time for many different timezones. The first timezone in the list ("/etc/localtime") is special and simply refers to the current local time on the computer without referring to a specific timezone. If you open the "/etc/localtime" node in the tree you can see which data fields the "time" DataEngine provides. The most important fields are the "Time" and "Date". The <tt>plasmaengineexplorer</tt> also lists what kind of data type the field is, e.g. a <tt>QString</tt>, <tt>QTime</tt> or <tt>QDate</tt>. This information is needed when hooking up a DataEngine to your applet.
    
− Explore some of the other DataEngines in the list. Perhaps it will give yousome ideas for applets. + Explore some of the other DataEngines in the list. Perhaps it will give you some good ideas for new and interesting applets.
    
  == Connecting to a DataEngine ==   == Connecting to a DataEngine ==

← Older revision		Revision as of 14:50, 18 January 2009
Line 42:		Line 42:

	<tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. Many many applets syncronise to the same way, then Plasma can handle the updates in large batches instead of many small updates. This is important on mobile devices which throttle the CPU down to save battery power. It is more efficient for these devices if updates are done in big batches instead of many small batches.		<tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. Many many applets syncronise to the same way, then Plasma can handle the updates in large batches instead of many small updates. This is important on mobile devices which throttle the CPU down to save battery power. It is more efficient for these devices if updates are done in big batches instead of many small batches.
		+
		+	Data is injected in the applet via the <tt>dataUpdate()</tt> method.
		+	<code python>
		+	@pyqtSignature("dataUpdated(const QString &, const Plasma::DataEngine::Data &)")
		+	def dataUpdated(self, sourceName, data):
		+	self.time = data[QString("Time")].toTime()
		+
		+	if self.time.minute() == self.lastTimeSeen.minute() and \
		+	self.time.second() == self.lastTimeSeen.second():
		+	# avoid unnecessary repaints
		+	return
		+
		+	self.lastTimeSeen = self.time
		+	self.update()
		+	</code>
		+	The <tt>dataUpdated()</tt> takes the normal Python <tt>self</tt> parameter in first place, then the name of the data source (<tt>sourceName</tt>) which called <tt>dataUpdated()</tt> and the data itself. In this case we just ignore the source name because we know that it must be from the "time" DataEngine, and just concentrate on the data. The data is delivered as a Python <tt>dict</tt> mapping <tt>QString</tt> keys to <tt>QVariant</tt> object values. When looking up the "Time" key you need to be careful to use a <tt>QString</tt> as a key and not just a normal Python string. Notice how the code also extracts a <tt>QTime</tt> object from the <tt>QVariant</tt> using the <tt>toTime()</tt> method.
		+
		+	Next the <tt>dataUpdated()</tt> method has some code to make sure that the clock display is only updated if really necessary, followed by some code which actually updates the time and redraws the display.
		+


	TODO: finish tutorial.		TODO: finish tutorial.

← Older revision		Revision as of 14:30, 18 January 2009
Line 23:		Line 23:
	== Connecting to a DataEngine ==		== Connecting to a DataEngine ==

		+	The Python clock example code is a good example of how to connect to the "time" DateEngine. You can view the
		+	[http://websvn.kde.org/branches/KDE/4.2/kdebase/workspace/plasma/scriptengines/python/examples/applets/pyclock/contents/code/main.py?revision=906699&view=markup main.py code online here online]. Let's look at how the Python clock does it.
		+
		+	The code to connect to the "time" DataEngine is in the clock's <tt>connectToEngine()</tt> method.
		+	<code python>
		+	def connectToEngine(self):
		+	self.timeEngine = self.dataEngine("time")
		+	if self.showSecondHand:
		+	self.timeEngine.connectSource(self.currentTimezone,
		+	self, 500)
		+	else:
		+	self.timeEngine.connectSource(self.currentTimezone,
		+	self, 6000, Plasma.AlignToMinute)
		+	</code>
		+	This method is called from the clock's <tt>init()</tt> method. It first calls the <tt>dateEngine()</tt> method on the <tt>plasmascript.Applet</tt> class to get a reference to the "time" DataEngine.
		+
		+	The <tt>connectSource()</tt> method on the DataEngine binds it to this applet. The first parameter is the "DataSource" name. This corresponds to the "DataSouce" column in <tt>plasmaengineexplorer</tt>. For the "time" DataEngine, it selects which timezone you want the time for. The next parameter is where the data should be sent. In this case it is quite simple, just send the data to this applet. The number is the "polling interval" in milliseconds. This is how often the data should be updated. Depending on how often the clock needs to update its display, it calls the <tt>connectSource()</tt> method with either 500 or 6000 milliseconds as the polling interval.
		+
		+	<tt>Plasma.AlignToMinute</tt> indicates to Plasma whether the updates should be syncronised to the system clock. Many many applets syncronise to the same way, then Plasma can handle the updates in large batches instead of many small updates. This is important on mobile devices which throttle the CPU down to save battery power. It is more efficient for these devices if updates are done in big batches instead of many small batches.


	TODO: finish tutorial.		TODO: finish tutorial.