gparamspec.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

  G_PARAM_CONSTRUCT	      = 1 << 2,
  G_PARAM_CONSTRUCT_ONLY      = 1 << 3,
  G_PARAM_LAX_VALIDATION      = 1 << 4,
  G_PARAM_PRIVATE	      = 1 << 5
} GParamFlags;
</programlisting>
<para>
Through the <link linkend="GParamFlags">GParamFlags</link> flag values, certain aspects of parameters
can be configured.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_PARAM_READABLE</literal></entry>
<entry>      the parameter is readable
</entry>
</row>
<row>
<entry><literal>G_PARAM_WRITABLE</literal></entry>
<entry>      the parameter is writable
</entry>
</row>
<row>
<entry><literal>G_PARAM_CONSTRUCT</literal></entry>
<entry>     the parameter will be set upon object construction
</entry>
</row>
<row>
<entry><literal>G_PARAM_CONSTRUCT_ONLY</literal></entry>
<entry>the parameter will only be set upon object construction
</entry>
</row>
<row>
<entry><literal>G_PARAM_LAX_VALIDATION</literal></entry>
<entry>upon parameter conversion (see <link linkend="g-param-value-convert">g_param_value_convert</link>())
                         strict validation is not required
</entry>
</row>
<row>
<entry><literal>G_PARAM_PRIVATE</literal></entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-PARAM-READWRITE-CAPS">G_PARAM_READWRITE</title>
<programlisting>#define	G_PARAM_READWRITE	(G_PARAM_READABLE | G_PARAM_WRITABLE)
</programlisting>
<para>
<link linkend="GParamFlags">GParamFlags</link> value alias for <literal>G_PARAM_READABLE</literal> | <literal>G_PARAM_WRITABLE</literal>.
</para></refsect2>
<refsect2>
<title><anchor id="G-PARAM-MASK-CAPS">G_PARAM_MASK</title>
<programlisting>#define	G_PARAM_MASK		(0x000000ff)
</programlisting>
<para>
Mask containing the bits of <link linkend="GParamSpec">GParamSpec</link>.flags which are reserved for GLib.
</para></refsect2>
<refsect2>
<title><anchor id="G-PARAM-USER-SHIFT-CAPS">G_PARAM_USER_SHIFT</title>
<programlisting>#define	G_PARAM_USER_SHIFT	(8)
</programlisting>
<para>
Minimum shift count to be used for user defined flags, to be stored in
<link linkend="GParamSpec">GParamSpec</link>.flags.
</para></refsect2>
<refsect2>
<title><anchor id="g-param-spec-ref">g_param_spec_ref ()</title>
<programlisting><link linkend="GParamSpec">GParamSpec</link>* g_param_spec_ref                (<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>
Increment the reference count of <parameter>pspec</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>  a valid <link linkend="GParamSpec">GParamSpec</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the <link linkend="GParamSpec">GParamSpec</link> that was passed into this function


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-spec-unref">g_param_spec_unref ()</title>
<programlisting>void        g_param_spec_unref              (<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>
Decrement the reference count of a <parameter>pspec</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>a valid <link linkend="GParamSpec">GParamSpec</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-spec-sink">g_param_spec_sink ()</title>
<programlisting>void        g_param_spec_sink               (<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>
The initial reference count of a newly created <link linkend="GParamSpec">GParamSpec</link> is 1,
eventhough no one has explicitely called <link linkend="g-param-spec-ref">g_param_spec_ref</link>() on it yet.
So the einital reference count is flagged as "floating", untill someone
calls: g_param_spec_ref (<parameter>pspec</parameter>); g_param_spec_sink (<parameter>pspec</parameter>);
in sequence on it, taking over the initial reference count (thus
ending up with a <parameter>pspec</parameter> that has a reference count of 1 still, but is
not flagged "floating" anymore).
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>a valid <link linkend="GParamSpec">GParamSpec</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-value-set-default">g_param_value_set_default ()</title>
<programlisting>void        g_param_value_set_default       (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Set <parameter>value</parameter> to its default value as specified in <parameter>pspec</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>a valid <link linkend="GParamSpec">GParamSpec</link>
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>a <link linkend="GValue">GValue</link> of correct type for <parameter>pspec</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-value-defaults">g_param_value_defaults ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_param_value_defaults          (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Check whether <parameter>value</parameter> contains the default value as specified in <parameter>pspec</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>  a valid <link linkend="GParamSpec">GParamSpec</link>
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>  a <link linkend="GValue">GValue</link> of correct type for <parameter>pspec</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>whether <parameter>value</parameter> contains the canonical defualt for this <parameter>pspec</parameter>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-value-validate">g_param_value_validate ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_param_value_validate          (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GValue">GValue</link> *value);</programlisting>
<para>
Ensure that the contents of <parameter>value</parameter> comply with the specifications
set out by <parameter>pspec</parameter>. For example, a <link linkend="GParamSpecInt">GParamSpecInt</link> might require
that integers stored in <parameter>value</parameter> may not be smaller than -42 and not be
greater than +42. If <parameter>value</parameter> contains an integer outside of this range,
it is modified accordingly, so the resulting value will fit into the
range -42 .. +42.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>  a valid <link linkend="GParamSpec">GParamSpec</link>
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>  a <link linkend="GValue">GValue</link> of correct type for <parameter>pspec</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>whether modifying <parameter>value</parameter> was necessary to ensure validity


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-value-convert">g_param_value_convert ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_param_value_convert           (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             const <link linkend="GValue">GValue</link> *src_value,
                                             <link linkend="GValue">GValue</link> *dest_value,
                                             <link linkend="gboolean">gboolean</link> strict_validation);</programlisting>
<para>
This function transforms <parameter>src_value</parameter> into <parameter>dest_value</parameter> if possible,
and then validates <parameter>dest_value</parameter>, in order for it to conform to
<parameter>pspec</parameter>.
If <parameter>strict_validation</parameter> is <literal>TRUE</literal> this function will only suceed if
the transformed <parameter>dest_value</parameter> complied to <parameter>pspec</parameter> without modifications.

See also <link linkend="g-value-type-transformable">g_value_type_transformable</link>(), <link linkend="g-value-transform">g_value_transform</link>() and
<link linkend="g-param-value-validate">g_param_value_validate</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>            a valid <link linkend="GParamSpec">GParamSpec</link>
</entry></row>
<row><entry align="right"><parameter>src_value</parameter>&nbsp;:</entry>
<entry>        souce <link linkend="GValue">GValue</link>
</entry></row>
<row><entry align="right"><parameter>dest_value</parameter>&nbsp;:</entry>
<entry>       destination <link linkend="GValue">GValue</link> of correct type for <parameter>pspec</parameter>
</entry></row>
<row><entry align="right"><parameter>strict_validation</parameter>&nbsp;:</entry>
<entry>$TRUE requires <parameter>dest_value</parameter> to conform to <parameter>pspec</parameter> without modifications
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>          <literal>TRUE</literal> if transformation and validation were successfull,
                    <literal>FALSE</literal> otherwise and <parameter>dest_value</parameter> is left untouched.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-values-cmp">g_param_values_cmp ()</title>
<programlisting><link linkend="gint">gint</link>        g_param_values_cmp              (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             const <link linkend="GValue">GValue</link> *value1,
                                             const <link linkend="GValue">GValue</link> *value2);</programlisting>
<para>
Compare <parameter>value1</parameter> with <parameter>value2</parameter> according to <parameter>pspec</parameter>, and return -1, 0 or +1,
if <parameter>value1</parameter> is found to be less than, equal to or greater than <parameter>value2</parameter>, respectively.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>  a valid <link linkend="GParamSpec">GParamSpec</link>
</entry></row>
<row><entry align="right"><parameter>value1</parameter>&nbsp;:</entry>
<entry> a <link linkend="GValue">GValue</link> of correct type for <parameter>pspec</parameter>
</entry></row>
<row><entry align="right"><parameter>value2</parameter>&nbsp;:</entry>
<entry> a <link linkend="GValue">GValue</link> of correct type for <parameter>pspec</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>-1, 0 or +1, for a less than, equal to or greater than result


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-spec-get-name">g_param_spec_get_name ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_param_spec_get_name (<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-spec-get-nick">g_param_spec_get_nick ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_param_spec_get_nick (<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-spec-get-blurb">g_param_spec_get_blurb ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_param_spec_get_blurb
                                            (<link linkend="GParamSpec">GParamSpec</link> *pspec);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pspec</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-param-spec-get-qdata">g_param_spec_get_qdata ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_param_spec_get_qdata          (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GQuark">GQuark</link> quark);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>