isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-11-26 18:11:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote branch 'elliot/cookbook-consistency'

Browse Source 
* elliot/cookbook-consistency:
  cookbook: Fixed typo
  cookbook: Fix build so CSS files get installed
  cookbook: Moved paragraph where it logically belongs
  cookbook: Added some judicious note elements
  cookbook: Added more information for contributors
  cookbook: Link out to docbook site
  cookbook: Made docbook element usage consistent
  cookbook: Additional selectors in CSS stylesheet
  cookbook: Copy the CSS file into the HTML build directory
This commit is contained in:
Emmanuele Bassi 2010-07-12 21:20:30 +01:00
commit 2de61da296
6 changed files with 204 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/common/style.css
View File

@ -1,6 +1,6 @@
/* /*
Generic XHTML / DocBook XHTML CSS Stylesheet. Generic XHTML / DocBook XHTML CSS Stylesheet.
Browser wrangling and typographic design by Browser wrangling and typographic design by
Oyvind Kolas / pippin@gimp.org Oyvind Kolas / pippin@gimp.org
@ -42,7 +42,7 @@
body { body {
font-family: Verdana, Sans, sans-serif; font-family: Verdana, Sans, sans-serif;
min-width: 640px; min-width: 640px;
width: 80%; width: 80%;
margin: 0em auto; margin: 0em auto;
@ -120,7 +120,7 @@ h6 {
padding-top: 256px; padding-top: 256px;
/* background-image: url("images/clutter-logo.png"); */ /* background-image: url("images/clutter-logo.png"); */
background-position: right top; background-position: right top;
float: right; float: right;
margin-top: -256px; margin-top: -256px;
padding-right: 50px; padding-right: 50px;
margin-left: 50px; margin-left: 50px;
@ -243,7 +243,7 @@ div.legalnotice p.legalnotice-title {
p { p {
line-height: 1.5em; line-height: 1.5em;
margin-top: 0em; margin-top: 0em;
} }
dl { dl {
@ -297,7 +297,7 @@ p a[id] {
padding: 0px; padding: 0px;
display: inline; display: inline;
background-image: none; background-image: none;
} }
a { a {
text-decoration: underline; text-decoration: underline;
@ -339,10 +339,10 @@ div.table p.title b{
font-weight: normal; font-weight: normal;
} }
.mediaobject .caption, .mediaobject .caption,
.mediaobject .caption p { .mediaobject .caption p {
text-align: center; text-align: center;
font-size: 80%; font-size: 80%;
padding-top: 0.5em; padding-top: 0.5em;
padding-bottom: 0.5em; padding-bottom: 0.5em;
} }
@ -370,6 +370,10 @@ span.application {
font-style: italic; font-style: italic;
} }
span.property, span.type {
font-family: monospace;
}
.programlisting { .programlisting {
font-family: monospace; font-family: monospace;
font-size: 80%; font-size: 80%;
@ -607,7 +611,7 @@ b.keycap,
.keycap { .keycap {
border: 1px solid; border: 1px solid;
} }
div.navheader, div.heading{ div.navheader, div.heading{
border-bottom: 1px solid; border-bottom: 1px solid;
@ -681,7 +685,7 @@ hr {
background-color: #8bd12e; background-color: #8bd12e;
} }
.glossary dl dt, .glossary dl dt,
.variablelist dl dt, .variablelist dl dt,
.variablelist dl dt span.term { .variablelist dl dt span.term {
color: #044; color: #044;
@ -770,8 +774,8 @@ h6,
h7{ h7{
} }
div.preface .titlepage .title, div.preface .titlepage .title,
div.colophon .title, div.colophon .title,
div.chapter .titlepage .title { div.chapter .titlepage .title {
background-image: url("images/title-bg.png"); background-image: url("images/title-bg.png");
background-position: bottom; background-position: bottom;
@ -938,7 +942,7 @@ table {
.tip, .tip,
.note { .note {
background: #91ae35; background: #91ae35;
color: #fff; color: #fff;
padding: 20px; padding: 20px;
margin: 20px; margin: 20px;
} }
@ -949,11 +953,11 @@ table {
margin: 0em; margin: 0em;
font-size: 2em; font-size: 2em;
font-weight: bold; font-weight: bold;
color: #fff; color: #fff;
} }
.tip a, .tip a,
.note a { .note a {
color: #fff; color: #fff;
text-decoration: underline; text-decoration: underline;
} }

5
doc/cookbook/Makefile.am
View File

@ -26,6 +26,7 @@ XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current
XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
HTML_FILES = html/*.html HTML_FILES = html/*.html
CSS_FILES = html/*.css
IMAGE_FILES = images/clutter-logo.png IMAGE_FILES = images/clutter-logo.png
EXTRA_DIST = clutter-cookbook.xml.in $(IMAGE_FILES) $(XML_FILES) EXTRA_DIST = clutter-cookbook.xml.in $(IMAGE_FILES) $(XML_FILES)
@ -43,6 +44,7 @@ pdf-build.stamp: clutter-cookbook.xml
html-build.stamp: clutter-cookbook.xml html-build.stamp: clutter-cookbook.xml
$(XSLTPROC) $(XSLTOPTS) -o clutter-cookbook.html $(XSL_XHTML_URI) $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \ $(XSLTPROC) $(XSLTOPTS) -o clutter-cookbook.html $(XSL_XHTML_URI) $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \
$(XSLTPROC) $(XSLTOPTS) -o html/ ref-html-style.xsl $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \ $(XSLTPROC) $(XSLTOPTS) -o html/ ref-html-style.xsl $(top_builddir)/doc/cookbook/clutter-cookbook.xml && \
cp $(top_srcdir)/doc/common/style.css html/ && \
echo timestamp > $(@F) echo timestamp > $(@F)
if ENABLE_PDFS if ENABLE_PDFS
@ -71,7 +73,7 @@ install-data-local:
then echo '-- Nothing to install' ; \ then echo '-- Nothing to install' ; \
else \ else \
$(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) ; \ $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR) ; \
for file in `ls $(HTML_FILES)`; do \ for file in `ls $(HTML_FILES) $(CSS_FILES)`; do \
if [ -f $$file ]; then \ if [ -f $$file ]; then \
basefile=`echo $$file | sed -e 's,^.*/,,'`; \ basefile=`echo $$file | sed -e 's,^.*/,,'`; \
$(INSTALL_DATA) $$file $(DESTDIR)$(TARGET_DIR)/$$basefile; \ $(INSTALL_DATA) $$file $(DESTDIR)$(TARGET_DIR)/$$basefile; \
@ -89,7 +91,6 @@ install-data-local:
fi \ fi \
done; \ done; \
fi; \ fi; \
$(INSTALL_DATA) $(top_srcdir)/doc/common/style.css $(DESTDIR)$(TARGET_DIR)/style.css; \
$(INSTALL_DATA) html/clutter-cookbook.devhelp $(DESTDIR)$(TARGET_DIR)/clutter-cookbook.devhelp $(INSTALL_DATA) html/clutter-cookbook.devhelp $(DESTDIR)$(TARGET_DIR)/clutter-cookbook.devhelp
.PHONY : doc .PHONY : doc

20
doc/cookbook/actors.xml
View File

@ -23,7 +23,7 @@
with the others: it can be the parent of another actor, or a child of with the others: it can be the parent of another actor, or a child of
another actor.</para> another actor.</para>
<note><para>The Stage is an actor that can have children but cannot have <note><para>The stage is an actor that can have children but cannot have
any parent.</para></note> any parent.</para></note>
<para>Actors have different attributes: a position, a size, a <para>Actors have different attributes: a position, a size, a
@ -38,7 +38,7 @@
</section> </section>
<section id="actors-allocation-notify"> <section id="actors-allocation-notify">
<title>Knowing when an actor position or size change</title> <title>Knowing when an actor's position or size changes</title>
<section> <section>
<title>Problem</title> <title>Problem</title>
@ -112,7 +112,9 @@ on_allocation_changed (ClutterActor *actor,
<para>Any change the position and size of an actor will cause a <para>Any change the position and size of an actor will cause a
change in the allocation of the actor itself. This will update the change in the allocation of the actor itself. This will update the
values of the :x, :y, :width and :height properties as well.</para> values of the <property>x</property>, <property>y</property>,
<property>width</property> and <property>height</property>
properties as well.</para>
<para>The first technique allows a greater deal of granularity, <para>The first technique allows a greater deal of granularity,
allowing you to know what exactly changed. Inside the callback allowing you to know what exactly changed. Inside the callback
@ -159,12 +161,13 @@ on_allocation_changed (ClutterActor *actor,
<para>All actors will update these properties when their size <para>All actors will update these properties when their size
or position change.</para> or position change.</para>
<para>Note that the Stage, on the other hand, will not notify on <para>Note that the stage, on the other hand, will not notify on
position changes, so it is not possible to use the :x and :y position changes, so it is not possible to use the
<property>x</property> and <property>y</property>
properties to know that the platform-specific window embedding the properties to know that the platform-specific window embedding the
stage has been moved &mdash; if the platform supports a windowing stage has been moved &mdash; if the platform supports a windowing
system. In order to achieve that you will have to use backend-specific system. In order to achieve that you will have to use backend-specific
API to extract the surface used by the Stage and then platform-specific API to extract the surface used by the stage and then platform-specific
API to retrieve its coordinates.</para> API to retrieve its coordinates.</para>
</section> </section>
@ -218,11 +221,11 @@ void on_paint (ClutterActor *actor, gpointer user_data);
<title>Discussion</title> <title>Discussion</title>
<para>The paint cycle in Clutter works its way recursively from the <para>The paint cycle in Clutter works its way recursively from the
Stage through every child.</para> stage through every child.</para>
<para>Whenever an Actor is going to be painted it will be positioned in <para>Whenever an Actor is going to be painted it will be positioned in
a new frame of reference according to the list of transformations a new frame of reference according to the list of transformations
(scaling, rotation and additional traslations). After that, the "paint" (scaling, rotation and additional translations). After that, the "paint"
signal will be emitted.</para> signal will be emitted.</para>
<para>The "paint" signal is defined as <emphasis>run-last</emphasis>, <para>The "paint" signal is defined as <emphasis>run-last</emphasis>,
@ -255,4 +258,3 @@ on_paint (ClutterActor *actor)
</section> </section>
</chapter> </chapter>

61
doc/cookbook/clutter-cookbook.xml.in
View File

@ -49,9 +49,64 @@
<appendix id="contributing"> <appendix id="contributing">
<title>Contributing to this document</title> <title>Contributing to this document</title>
<para>This document is written in Docbook XML. The source file for this <para>This document is written in
document is located in the subdirectory "doc/cookbook" of the source <ulink url="http://docbook.org/">Docbook XML</ulink>. The source files
directory of Clutter.</para> for this document are located in the subdirectory
<filename>doc/cookbook</filename> inside the Clutter source directory.</para>
<para>To maintain some degree of consistency, try to stick to the
following broad guidelines about how to write Docbook for this
cookbook:</para>
<itemizedlist>
<listitem>
<para>If adding a new recipe, use the
<filename>recipe-template.xml</filename> XML file as a basis.
You can find it in the <filename>&lt;clutter_source&gt;/doc/cookbook/</filename>
directory.</para>
</listitem>
<listitem>
<para>Try to indent your XML sensibly using 2 spaces per level
(we're not too strict, but some indentation helps reading
the source).</para>
</listitem>
<listitem>
<para>Stick to a column width of around 80 characters.</para>
</listitem>
<listitem>
<para>Use the &lt;filename&gt; element for file
and directory names.</para>
</listitem>
<listitem>
<para>Use the &lt;property&gt; element for property names
(e.g. GObject properties).</para>
</listitem>
<listitem>
<para>Use the &lt;type&gt; element for GObject class
names.</para>
</listitem>
<listitem>
<para>Use the &lt;constant&gt; element for C defines.</para>
</listitem>
<listitem>
<para>Use the &lt;keycap&gt; element for keys, where
you are referring to what's actually printed on the key, e.g.
<keycap>Shift</keycap>. If you're referring to the key some
other way (e.g. "the Control key"), don't use
&lt;keycap&gt;.</para>
</listitem>
<listitem>
<para>Use the &lt;function&gt; element for functions;
the style adopted is to give the function name followed by
empty brackets, e.g. <function>clutter_actor_set_size()</function>.
</para>
</listitem>
<listitem>
<para>Use the &lt;note&gt; element for asides which might
otherwise interrupt the flow of the recipe.</para>
</listitem>
</itemizedlist>
</appendix> </appendix>
</book> </book>

105
doc/cookbook/events.xml
View File

@ -70,8 +70,8 @@
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis>Solution 2:</emphasis> Use an actor's <para><emphasis>Solution 2:</emphasis> Use an actor's
ClutterBindingPool to declaratively assign actions to specific <type>ClutterBindingPool</type> to declaratively assign
key and modifier combinations.</para> actions to specific key and modifier combinations.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
@ -80,12 +80,13 @@
<section> <section>
<title>Solution 1</title> <title>Solution 1</title>
<para>Connect the key-press-event signal for an actor to a callback; <para>Connect the <emphasis>key-press-event</emphasis>
then examine the event in the callback to determine which key and signal for an actor to a callback; then examine the event
modifiers were pressed.</para> in the callback to determine which key and modifiers were
pressed.</para>
<para>First, connect an actor's key-press-event signal <para>First, connect an actor's
to a callback:</para> <emphasis>key-press-event</emphasis> signal to a callback:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -96,7 +97,8 @@ g_signal_connect (actor, "key-press-event", G_CALLBACK (_key_press_cb), NULL);
<para>Then, in the callback, check which key was pressed and which <para>Then, in the callback, check which key was pressed and which
modifiers were down at the same time. For example, this callback modifiers were down at the same time. For example, this callback
checks for a press on the up arrow key and whether checks for a press on the up arrow key and whether
the Shift and/or Control key were down:</para> the <keycap>Shift</keycap> and/or <keycap>Ctrl</keycap>
key were down:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -110,60 +112,67 @@ _key_press_cb (ClutterActor *actor,
if (CLUTTER_Up == keyval) if (CLUTTER_Up == keyval)
{ {
ClutterModifierType modifiers = clutter_event_get_state (event); ClutterModifierType modifiers = clutter_event_get_state (event);
switch (modifiers) switch (modifiers)
{ {
case CLUTTER_SHIFT_MASK: case CLUTTER_SHIFT_MASK:
g_debug ("Up and shift pressed"); g_debug ("Up and shift pressed");
break; break;
case CLUTTER_SHIFT_MASK + CLUTTER_CONTROL_MASK: case CLUTTER_SHIFT_MASK + CLUTTER_CONTROL_MASK:
g_debug ("Up and shift and control pressed"); g_debug ("Up and shift and control pressed");
break; break;
default: default:
g_debug ("Up pressed"); g_debug ("Up pressed");
break; break;
} }
/* The event was handled, and the emission should stop */ /* The event was handled, and the emission should stop */
return TRUE; return TRUE;
} }
/* The event was not handled, and the emission should continue */ /* The event was not handled, and the emission should continue */
return FALSE; return FALSE;
} }
</programlisting> </programlisting>
</informalexample> </informalexample>
<para>Note that Clutter provides a range of key value definitions <note>
(like CLUTTER_Up, used above). These are generated from the list in the <para>Clutter provides a range of key value definitions
<ulink url="http://cgit.freedesktop.org/xorg/proto/x11proto/plain/keysymdef.h">X.Org source code</ulink> (like <constant>CLUTTER_Up</constant>, used above). These are
(replace "XK" with "CLUTTER" in the definitions there to get the generated from the list in the
CLUTTER equivalents; alternatively, look at the clutter-keysyms.h <ulink url="http://cgit.freedesktop.org/xorg/proto/x11proto/plain/keysymdef.h">X.Org source code</ulink>
header file for the list).</para> (replace "XK" with "CLUTTER" in the definitions there to get the
CLUTTER equivalents; alternatively, look at the
<filename>clutter-keysyms.h</filename> header file for the
list).</para>
<para>CLUTTER_SHIFT_MASK, CLUTTER_CONTROL_MASK and other modifiers are <para><constant>CLUTTER_SHIFT_MASK</constant>,
defined in the ClutterModifierType enum.</para> <constant>CLUTTER_CONTROL_MASK</constant> and other modifiers are
defined in the <type>ClutterModifierType</type> enum.</para>
</note>
</section> </section>
<section> <section>
<title>Solution 2</title> <title>Solution 2</title>
<para>Assign actions to an actor's ClutterBindingPool. <para>Assign actions to an actor's <type>ClutterBindingPool</type>.
A binding pool stores mappings from a key press (either a single key A binding pool stores mappings from a key press (either a single key
or a key plus modifiers) to actions; an action is simply a callback or a key plus modifiers) to actions; an action is simply a callback
function with a specific signature.</para> function with a specific signature.</para>
<para>While this approach is trickier to implement, it is more <para>While this approach is trickier to implement, it is more
flexible and removes the drudgery of writing branching code to flexible and removes the drudgery of writing branching code to
handle different key presses. See the Discussion section for handle different key presses. See the
more details.</para> <link linkend="events-handling-key-events-discussion">Discussion</link>
section for more details.</para>
<para>To use this approach with an actor which will receive key press <para>To use this approach with an actor which will receive key press
events, first get that actor's binding pool. In the example below, events, first get that actor's binding pool. In the example below,
we're using the binding pool for the default ClutterStage:</para> we're using the binding pool for the default
<type>ClutterStage</type>:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -176,8 +185,9 @@ binding_pool = clutter_binding_pool_get_for_class (stage_class);
</informalexample> </informalexample>
<para>Next, install actions into the binding pool. For example, to <para>Next, install actions into the binding pool. For example, to
install an action bound to the up arrow key, which calls the _move_up install an action bound to the up arrow key, which calls the
function when that key is pressed, you would do:</para> <function>_move_up()</function> function when that key is pressed,
you would do:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -191,8 +201,10 @@ clutter_binding_pool_install_action (binding_pool,
</programlisting> </programlisting>
</informalexample> </informalexample>
<para>Another example, binding up + Shift + Control to an action which <para>Another example, binding up arrow +
calls _move_up_shift_control when activated:</para> <keycap>Shift</keycap> + <keycap>Ctrl</keycap> to an action
which calls <function>_move_up_shift_control()</function> when
activated:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -206,8 +218,8 @@ clutter_binding_pool_install_action (binding_pool,
</programlisting> </programlisting>
</informalexample> </informalexample>
<para>The function called when an action is activated looks like this <para>The function called when an action is activated looks
(for _move_up):</para> like this (for <function>_move_up()</function>):</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -223,8 +235,8 @@ _move_up (GObject *instance,
</programlisting> </programlisting>
</informalexample> </informalexample>
<para>Then bind the key-press-event for the actor (in our case, <para>Then bind the <emphasis>key-press-event</emphasis> signal
the stage) to a callback:</para> for the actor (in our case, the stage) to a callback:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -258,13 +270,13 @@ _key_press_cb (ClutterActor *actor,
</programlisting> </programlisting>
</informalexample> </informalexample>
<para>Now, when a key plus modifiers that has been bound to an action <para>Now, when a key + modifiers that have been bound to an action
is pressed on the actor, the appropriate action is activated.</para> are pressed on the actor, the appropriate action is activated.</para>
</section> </section>
</section> </section>
<section> <section id="events-handling-key-events-discussion">
<title>Discussion</title> <title>Discussion</title>
<section> <section>
@ -285,9 +297,10 @@ _key_press_cb (ClutterActor *actor,
<para>In addition, Solution 2 lets you write a single callback to <para>In addition, Solution 2 lets you write a single callback to
handle all key press events for all actors. This callback could then handle all key press events for all actors. This callback could then
use clutter_binding_pool_find (as in the example code) to determine use <function>clutter_binding_pool_find()</function>
which binding pool to activate (depending on which actor received the (as in the example code) to determine which binding pool to
key press event).</para> activate (depending on which actor received the key press
event).</para>
<para>Finally, a binding pool allows you to block and unblock actions. <para>Finally, a binding pool allows you to block and unblock actions.
This means you can make the response to a key press event conditional This means you can make the response to a key press event conditional
@ -305,17 +318,19 @@ _key_press_cb (ClutterActor *actor,
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>A ClutterKeyEvent contains only a <emphasis>single</emphasis> <para>A <type>ClutterKeyEvent</type> contains only a
key value, plus possibly one or more modifier keys (like Shift, <emphasis>single</emphasis> key value, plus possibly one
Control, Alt etc.). There are no functions in the or more modifier keys (like <keycap>Shift</keycap>,
Clutter API which return events for tracking near-simultaneous <keycap>Ctrl</keycap>, <keycap>Alt</keycap> etc.).
presses on multiple keys.</para> There are no functions in the Clutter API which return
events for tracking near-simultaneous presses on multiple
keys.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>By default, the stage receives all key events. <para>By default, the stage receives all key events.
To make another actor receive key events, use To make another actor receive key events, use
clutter_stage_set_key_focus:</para> <function>clutter_stage_set_key_focus()</function>:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>

97
doc/cookbook/textures.xml
View File

@ -27,8 +27,8 @@
<section> <section>
<title>Solution</title> <title>Solution</title>
<para>Create a ClutterCairoTexture, then draw onto the Cairo context <para>Create a <type>ClutterCairoTexture</type>, then draw onto
it wraps using the Cairo API:</para> the Cairo context it wraps using the Cairo API:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -64,9 +64,11 @@ cairo_destroy (cr);
<section> <section>
<title>Discussion</title> <title>Discussion</title>
<para>A ClutterCairoTexture is a standard ClutterActor, so it can be <para>A <type>ClutterCairoTexture</type> is a standard
added to ClutterContainers (e.g. a ClutterStage or ClutterGroup), <type>ClutterActor</type>, so it can be added to a
animated, resized etc. in the usual ways.</para> <type>ClutterContainer</type> (e.g. a <type>ClutterStage</type>
or <type>ClutterGroup</type>), animated, resized etc. in the
usual ways.</para>
<para>Other useful operations:</para> <para>Other useful operations:</para>
@ -74,24 +76,24 @@ cairo_destroy (cr);
<listitem> <listitem>
<para><emphasis>To draw on part of the texture:</emphasis> <para><emphasis>To draw on part of the texture:</emphasis>
use <function>clutter_cairo_texture_create_region</function> to use <function>clutter_cairo_texture_create_region()</function> to
retrieve a Cairo context for the region you want to draw on.</para> retrieve a Cairo context for the region you want to draw on.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis>To clear existing content from a texture:</emphasis> <para><emphasis>To clear existing content from a texture:</emphasis>
use <function>clutter_cairo_texture_clear</function>.</para> use <function>clutter_cairo_texture_clear()</function>.</para>
<para>You may need to do this as the texture reuses the same <para>You may need to do this as the texture reuses the same
Cairo context each time you call Cairo context each time you call
<function>clutter_cairo_texture_create</function> or <function>clutter_cairo_texture_create()</function> or
<function>clutter_cairo_texture_create_region</function>.</para> <function>clutter_cairo_texture_create_region()</function>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis>To resize the Cairo context wrapped <para><emphasis>To resize the Cairo context wrapped
by a texture</emphasis>, use by a texture</emphasis>, use
<function>clutter_cairo_texture_set_surface_size</function>.</para> <function>clutter_cairo_texture_set_surface_size()</function>.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -144,13 +146,14 @@ cairo_destroy (cr);
</programlisting> </programlisting>
</informalexample> </informalexample>
<para>Note that if the page is larger than the Cairo context, <note><para>If the page is larger than the Cairo context,
some of it might not be visible. Similarly, if the ClutterCairoTexture some of it might not be visible. Similarly, if the
is larger than the stage, some of that might not be visible. So you <type>ClutterCairoTexture</type> is larger than the stage,
may need to do some work to make the ClutterCairoTexture fit some of that might not be visible. So you
inside the stage properly (e.g. resize the stage), and/or some work may need to do some work to make the <type>ClutterCairoTexture</type>
fit inside the stage properly (e.g. resize the stage), and/or some work
to make the PDF page sit inside the Cairo context (e.g. scale the PDF to make the PDF page sit inside the Cairo context (e.g. scale the PDF
page or put it inside a scrollable actor).</para> page or put it inside a scrollable actor).</para></note>
</section> </section>
@ -174,8 +177,8 @@ cairo_destroy (cr);
<para>Set the texture to keep the aspect ratio of the <para>Set the texture to keep the aspect ratio of the
underlying image (so it doesn't distort when it's scaled); use underlying image (so it doesn't distort when it's scaled); use
the actor's request-mode property to set the correct the actor's <property>request-mode</property> property to set
geometry management (see the discussion section); then the correct geometry management (see the discussion section); then
resize the texture along one dimension (height or width). resize the texture along one dimension (height or width).
Now, when an image is loaded into the texture, the image is Now, when an image is loaded into the texture, the image is
scaled to fit the set height or width; the other dimension scaled to fit the set height or width; the other dimension
@ -210,20 +213,20 @@ clutter_texture_set_from_file (CLUTTER_TEXTURE (texture),
<section> <section>
<title>Discussion</title> <title>Discussion</title>
<para>The request mode for an actor determines how <para>The <property>request-mode</property> for an actor
geometry requisition is performed; in this case, this determines how geometry requisition is performed; in this case, this
includes how scaling is applied if you change the actor's includes how scaling is applied if you change the actor's
width or height. There are two possible values for width or height. There are two possible values for
request-mode:</para> request-mode:</para>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>If set to <emphasis>CLUTTER_REQUEST_HEIGHT_FOR_WIDTH</emphasis> <para>If set to <constant>CLUTTER_REQUEST_HEIGHT_FOR_WIDTH</constant>
(the default), changing the width causes the height (the default), changing the width causes the height
to be scaled by the same factor as the width.</para> to be scaled by the same factor as the width.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>If set to <emphasis>CLUTTER_REQUEST_WIDTH_FOR_HEIGHT</emphasis>, <para>If set to <constant>CLUTTER_REQUEST_WIDTH_FOR_HEIGHT</constant>,
changing the height causes the width to be scaled by the changing the height causes the width to be scaled by the
same factor as the height.</para> same factor as the height.</para>
</listitem> </listitem>
@ -231,21 +234,22 @@ clutter_texture_set_from_file (CLUTTER_TEXTURE (texture),
<para>In the example above, the texture is set to keep its <para>In the example above, the texture is set to keep its
aspect ratio then fixed to a width of 300 pixels; the aspect ratio then fixed to a width of 300 pixels; the
request-mode is set to CLUTTER_REQUEST_HEIGHT_FOR_WIDTH. If a request-mode is set to <constant>CLUTTER_REQUEST_HEIGHT_FOR_WIDTH</constant>.
standard, photo-sized image in landscape orientation were If a standard, photo-sized image in landscape orientation were
loaded into it (2848 pixels wide x 2136 high), it would be scaled loaded into it (2848 pixels wide x 2136 high), it would be scaled
down to 300 pixels wide; then, its height would be scaled by the down to 300 pixels wide; then, its height would be scaled by the
same factor as the width (i.e. scaled down to 225 pixels).</para> same factor as the width (i.e. scaled down to 225 pixels).</para>
<para>With request-mode set to CLUTTER_REQUEST_WIDTH_FOR_HEIGHT, <para>With request-mode set to
<constant>CLUTTER_REQUEST_WIDTH_FOR_HEIGHT</constant>,
you would get the same effect by setting the height first; you would get the same effect by setting the height first;
then, computation of the width for the scaled image would be then, computation of the width for the scaled image would be
based on the scaling factor applied to its height instead.</para> based on the scaling factor applied to its height instead.</para>
<para>You can work out which side of the source image is longest using <para>You can work out which side of the source image is longest using
clutter_texture_base_size() to get its width and height. This can <function>clutter_texture_base_size()</function> to get its
be useful when trying to scale images with different orientations width and height. This can be useful when trying to scale images
to fit into uniform rows or columns:</para> with different orientations to fit into uniform rows or columns:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -259,8 +263,9 @@ clutter_texture_get_base_size (CLUTTER_TEXTURE (texture), &width, &height);
</informalexample> </informalexample>
<note><para>If you explicitly set the size (both width and height) <note><para>If you explicitly set the size (both width and height)
of a texture with clutter_actor_set_size() (or of a texture with <function>clutter_actor_set_size()</function> (or
with clutter_actor_set_width() and clutter_actor_set_height()), any with <function>clutter_actor_set_width()</function> and
<function>clutter_actor_set_height()</function>), any
image loaded into the texture is automatically stretched/shrunk to image loaded into the texture is automatically stretched/shrunk to
fit the texture. This is the case regardless of any other settings fit the texture. This is the case regardless of any other settings
(like whether to keep aspect ratio).</para></note> (like whether to keep aspect ratio).</para></note>
@ -285,7 +290,8 @@ clutter_texture_get_base_size (CLUTTER_TEXTURE (texture), &width, &height);
<section> <section>
<title>Solution</title> <title>Solution</title>
<para>Create a ClutterTexture directly from an image file:</para> <para>Create a <type>ClutterTexture</type> directly from an
image file:</para>
<informalexample> <informalexample>
<programlisting> <programlisting>
@ -378,11 +384,12 @@ if (error != NULL)
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Call g_thread_init() (from the GLib library) prior <para>Call <function>g_thread_init()</function> (from the
to calling clutter_init(), so that a local thread is used GLib library) prior to calling <function>clutter_init()</function>,
to load the file, rather than the main loop. (Note that so that a local thread is used to load the file, rather
this is not necessary if you're using GLib version >= 2.24, than the main loop. (Note that this is not necessary if
since GObject initializes threading with the type system.)</para> you're using GLib version >= 2.24, since GObject
initializes threading with the type system.)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Set the texture to load data asynchronously.</para> <para>Set the texture to load data asynchronously.</para>
@ -462,16 +469,18 @@ main (int argc, char *argv[])
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Various GNOME libraries provide image data in GdkPixbuf <para>Various GNOME libraries provide image data in
structures; clutter-gtk has functions for <type>GdkPixbuf</type> structures; clutter-gtk has
creating or setting a texture from a GdkPixbuf: functions for creating or setting a texture from a
gtk_clutter_texture_new_from_pixbuf() <type>GdkPixbuf</type>:
and gtk_clutter_texture_set_from_pixbuf() respectively.</para> <function>gtk_clutter_texture_new_from_pixbuf()</function>
and <function>gtk_clutter_texture_set_from_pixbuf()</function>
respectively.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>If you have raw RGB pixel data, ClutterTexture also has <para>If you have raw RGB pixel data, <type>ClutterTexture</type>
the clutter_texture_set_from_rgb_data() method for loading also has a <function>clutter_texture_set_from_rgb_data()</function>
it.</para> function for loading it.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>