Sugar Labs

Changes

Development Team/Almanac/Pango (view source)

Revision as of 21:32, 23 February 2010

5,672 bytes added ,  21:32, 23 February 2010
m
moved Walter is a wanker 12/Almanac/Pango to Development Team/Almanac/Pango over redirect: revert
Line 1: Line 1:  +
{{Almanac}}
 +
 
Pango is "the core text and font handling library used in GNOME applications. It has extensive support for the different writing systems used throughout the world."<ref>[http://library.gnome.org/devel/pango/ Pango Reference Manual]</ref>. The end of this section points to some standard documentation of Pango that should help you walk through most of what you want to do. We will simply discuss a few representative examples to help you get started in using Pango to display text in your activity.  
 
Pango is "the core text and font handling library used in GNOME applications. It has extensive support for the different writing systems used throughout the world."<ref>[http://library.gnome.org/devel/pango/ Pango Reference Manual]</ref>. The end of this section points to some standard documentation of Pango that should help you walk through most of what you want to do. We will simply discuss a few representative examples to help you get started in using Pango to display text in your activity.  
   Line 77: Line 79:  
=== How do I dynamically set the text in a pango layout? ===
 
=== How do I dynamically set the text in a pango layout? ===
   −
You will often want to change or reset the text in a pango layout during the life of your activity. To create such dynamic layouts, the main thing you need to do is reset the text or markup for your pango layout (usually using set_markup()) and to then call the queue_draw()<ref>[[http://www.pygtk.org/docs/pygtk/class-gtkwidget.html#method-gtkwidget--queue-draw]]</ref> method which schedules a redraw (effectively forcing an expose_event signal to be thrown).  
+
You will often want to change or reset the text in a pango layout during the life of your activity. To create such dynamic layouts, the main thing you need to do is reset the text or markup for your pango layout (usually using set_markup()) and to then call the queue_draw()<ref>[http://www.pygtk.org/docs/pygtk/class-gtkwidget.html#method-gtkwidget--queue-draw PyGtk Documentation: gtk.Widget.queue_draw]</ref> method which schedules a redraw (effectively forcing an expose_event signal to be thrown).  
   −
The code below uses a standard timeout code pattern<ref>[http://wiki.laptop.org/go/PyGTK/Smooth_Animation_with_PyGTK#Timer_Events]</ref> to call a method every 1 second. So the text in the Pango is updated to give the current time roughly every 1 second.
+
The code below uses a standard timeout code pattern<ref>[http://wiki.laptop.org/go/PyGTK/Smooth_Animation_with_PyGTK#Timer_Events PyGtk/Smooth Animation: Timer Objects]</ref> to call a method every 1 second. So the text in the Pango is updated to give the current time roughly every 1 second.
    
<pre>
 
<pre>
Line 132: Line 134:  
</pre>
 
</pre>
   −
=== How do I set the different font properties for my pango layout? ===
+
=== How do I set the width of the layout on which my pango text will be rendered? ===
 +
As the two images below show, you can set the width of your pango layout so that text is output within a narrow or wide space. To do this, you simply call the set_width method in [http://olympus.het.brown.edu/cgi-bin/dwww?type=file&location=/usr/share/doc/python-gtk2-doc/html/class-pangolayout.html pango.Layout].
 +
 
 +
 
 +
[[Image: pango-screenshot-narrow.jpg]]  [[Image: pango-screenshot-wide.jpg]]
 +
 
 +
The sample code below shows how this is done. Note how the width argument itself is in relatively large units (at least for sugar-jhbuild).
 +
 
 +
<pre>
 +
import pango
 +
...
 +
class TextWidget(gtk.DrawingArea):
 +
def __init__(self):
 +
                ...
 +
#create a pango layout. Leave text argument to be empty string since we want to use markup
 +
self.pango_context = self.create_pango_context()
 +
self.pango_layout = self.create_pango_layout('')
 +
 
 +
#Make the width of the pango layout to be relatively narrow
 +
self.pango_layout.set_width(200000)
 +
 
 +
#Make the width of the pango layout to be relatively wide.
 +
self.pango_layout.set_width(800000)
 +
                ...
 +
</pre>
 +
 
 +
=== How do I control the appearance of fonts on a Pango layout? ===
 +
 
 +
There are two ways in which you can customize how fonts are displayed in your activity.
 +
 
 +
# You set th default font properties throughout your layout.
 +
# Using [http://www.pygtk.org/docs/pygtk/pango-markup-language.html Pango markup], you customize specific blocks of text in your Pango layout.
 +
 
 +
To customize the default font throughout your layout, you call the [http://olympus.het.brown.edu/cgi-bin/dwww?type=file&location=/usr/share/doc/python-gtk2-doc/html/class-pangolayout.html#method-pangolayout--set-font-description pango.Layout.set_font_description()] method when you create and initialize your Pango layout.
 +
 
 +
<pre>
 +
import pango
 +
...
 +
#create a pango layout. Leave text argument to be empty string since we want to use markup
 +
self.pango_context = self.create_pango_context()
 +
self.pango_layout = self.create_pango_layout('')
 +
 
 +
#Set the default font style for this pango layout
 +
self.pango_layout.set_font_description(pango.FontDescription('serif Ultra-bold italic 14'))
 +
</pre>
 +
 
 +
Once you have set the default font, you can change around the appearance of specific blocks of text using [http://www.pygtk.org/docs/pygtk/pango-markup-language.html Pango markup]. This is done by calling the [http://olympus.het.brown.edu/cgi-bin/dwww?type=file&location=/usr/share/doc/python-gtk2-doc/html/class-pangolayout.html#method-pangolayout--set-markup pango.Layout.set_markup()] method. The markup below shows how text is customized in Pango. The block of text in the <span> tag specifically overrides some of the default settings made earlier through set_font_description().
 +
 
 +
<pre>
 +
                #Set the markup for our pango layout.
 +
self.pango_layout.set_markup('<span foreground=\"blue\">This is some sample markup</span>
 +
<sup>text</sup> that <span style=\"normal\" size=\"small\">is displayed with pango</span>\n\n <u>Current time:</u> ')
 +
</pre>
 +
 
 +
The screenshot below shows how the text above shows up after setting the default font earlier and then customizing with the markup.
 +
 
 +
[[Image: pango-font-control-appearance.jpg]]
 +
 
 +
=== Are there widgets other than drawing areas where you can render fonts using pango? ===
 +
 
 +
Yes, in fact some widgets like gtk.Label already have built in methods to set pango markup. This makes the process of creating custom Pango text extremely easy. In fact, if you just want some small or simple area of text in your activity UI, you might be better served creating a gtk.Label and using the set_markup() method that comes built in for use with Pango. Of course, if labels, tooltips or other widgets are not sufficient for what you are trying to do with your UI, you will have to revert to using more broad-purpose widgets like the gtk.DrawingArea.
 +
 
 +
Below is some code that creates a label, sets its text to be Pango markup and then adds it to some existing UI widget (called first_page).
 +
 
 +
<pre>
 +
import Pango
 +
...
 +
        #Create a new label whose text is rendered by Pango
 +
        mylabel = gtk.Label()
 +
        mylabel.set_markup("<u>This is pango markup</u> <span foreground=\"orange\">inside a label</span>")
 +
        first_page.pack_start(mylabel)
 +
 
 +
</pre>
 +
 
 +
Here's how this label shows up in the UI.
 +
 
 +
[[Image: suagar_almanac_pango_label.jpg]]
 +
 
 +
=== How do I load file data in to a Pango layout? ===
 +
 
 +
More often than not, you will probably want larger Pango layout areas to display data contained inside of a file rather than data that is conceived within the code of your program. The following code shows a utility method used to read from a file that can then be used to load data in to a Pango layout.
 +
 
 +
<pre>
 +
#### Method getFileData, which takes a file_path and returns the data within that file
 +
def getFileData(file_path):
 +
    fd = open(file_path, 'r')
 +
    try:
 +
        data = fd.read()
 +
    finally:
 +
        fd.close()
 +
    return data
 +
</pre>
 +
 
 +
With this utility method in place, updating a Pango layout with file data is pretty straightforward:
   −
=== In addition to drawing areas, are there other types of widgets in which I can embed pango layouts? ===
+
<pre>
 +
import pango
 +
...
 +
class TextWidget(gtk.DrawingArea):
 +
def __init__(self):
    +
self.repeat_period_msec = 1000
 +
 +
gtk.DrawingArea.__init__(self)
 +
self.context = None
 +
 +
#create a pango layout. Leave text argument to be empty string since we want to use markup
 +
self.pango_context = self.create_pango_context()
 +
self.pango_layout = self.create_pango_layout('')
 +
                ...
 +
 +
 +
#### Method update_file, reloads data from filepath and then updates the Pango layout that
 +
# displays the data in the file.
 +
def update_file(self, filepath):
 +
self.pango_layout.set_markup(annotateutils.getFileData(filepath))
 +
self.queue_draw()
 +
</pre>
    
= Notes =
 
= Notes =
 
<references />
 
<references />
Retrieved from "https://wiki.sugarlabs.org/go/Special:MobileDiff/18684...46676"