gparamspec.sgml

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

<refentry id="gobject-GParamSpec">
<refmeta>
<refentrytitle>GParamSpec</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GParamSpec</refname><refpurpose>Meta data object for parameter specifications.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gobject.h&gt;


#define     <link linkend="G-TYPE-IS-PARAM-CAPS">G_TYPE_IS_PARAM</link>                 (type)
#define     <link linkend="G-PARAM-SPEC-CAPS">G_PARAM_SPEC</link>                    (pspec)
#define     <link linkend="G-IS-PARAM-SPEC-CAPS">G_IS_PARAM_SPEC</link>                 (pspec)
#define     <link linkend="G-PARAM-SPEC-CLASS-CAPS">G_PARAM_SPEC_CLASS</link>              (pclass)
#define     <link linkend="G-IS-PARAM-SPEC-CLASS-CAPS">G_IS_PARAM_SPEC_CLASS</link>           (pclass)
#define     <link linkend="G-PARAM-SPEC-GET-CLASS-CAPS">G_PARAM_SPEC_GET_CLASS</link>          (pspec)
#define     <link linkend="G-PARAM-SPEC-TYPE-CAPS">G_PARAM_SPEC_TYPE</link>               (pspec)
#define     <link linkend="G-PARAM-SPEC-TYPE-NAME-CAPS">G_PARAM_SPEC_TYPE_NAME</link>          (pspec)
#define     <link linkend="G-PARAM-SPEC-VALUE-TYPE-CAPS">G_PARAM_SPEC_VALUE_TYPE</link>         (pspec)
struct      <link linkend="GParamSpec">GParamSpec</link>;
struct      <link linkend="GParamSpecClass">GParamSpecClass</link>;
enum        <link linkend="GParamFlags">GParamFlags</link>;
#define     <link linkend="G-PARAM-READWRITE-CAPS">G_PARAM_READWRITE</link>
#define     <link linkend="G-PARAM-MASK-CAPS">G_PARAM_MASK</link>
#define     <link linkend="G-PARAM-USER-SHIFT-CAPS">G_PARAM_USER_SHIFT</link>
<link linkend="GParamSpec">GParamSpec</link>* <link linkend="g-param-spec-ref">g_param_spec_ref</link>                (<link linkend="GParamSpec">GParamSpec</link> *pspec);
void        <link linkend="g-param-spec-unref">g_param_spec_unref</link>              (<link linkend="GParamSpec">GParamSpec</link> *pspec);
void        <link linkend="g-param-spec-sink">g_param_spec_sink</link>               (<link linkend="GParamSpec">GParamSpec</link> *pspec);
void        <link linkend="g-param-value-set-default">g_param_value_set_default</link>       (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GValue">GValue</link> *value);
<link linkend="gboolean">gboolean</link>    <link linkend="g-param-value-defaults">g_param_value_defaults</link>          (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GValue">GValue</link> *value);
<link linkend="gboolean">gboolean</link>    <link linkend="g-param-value-validate">g_param_value_validate</link>          (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GValue">GValue</link> *value);
<link linkend="gboolean">gboolean</link>    <link linkend="g-param-value-convert">g_param_value_convert</link>           (<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);
<link linkend="gint">gint</link>        <link linkend="g-param-values-cmp">g_param_values_cmp</link>              (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             const <link linkend="GValue">GValue</link> *value1,
                                             const <link linkend="GValue">GValue</link> *value2);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-param-spec-get-name">g_param_spec_get_name</link> (<link linkend="GParamSpec">GParamSpec</link> *pspec);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-param-spec-get-nick">g_param_spec_get_nick</link> (<link linkend="GParamSpec">GParamSpec</link> *pspec);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-param-spec-get-blurb">g_param_spec_get_blurb</link>
                                            (<link linkend="GParamSpec">GParamSpec</link> *pspec);
<link linkend="gpointer">gpointer</link>    <link linkend="g-param-spec-get-qdata">g_param_spec_get_qdata</link>          (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GQuark">GQuark</link> quark);
void        <link linkend="g-param-spec-set-qdata">g_param_spec_set_qdata</link>          (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GQuark">GQuark</link> quark,
                                             <link linkend="gpointer">gpointer</link> data);
void        <link linkend="g-param-spec-set-qdata-full">g_param_spec_set_qdata_full</link>     (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GQuark">GQuark</link> quark,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy);
<link linkend="gpointer">gpointer</link>    <link linkend="g-param-spec-steal-qdata">g_param_spec_steal_qdata</link>        (<link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GQuark">GQuark</link> quark);
<link linkend="gpointer">gpointer</link>    <link linkend="g-param-spec-internal">g_param_spec_internal</link>           (<link linkend="GType">GType</link> param_type,
                                             const <link linkend="gchar">gchar</link> *name,
                                             const <link linkend="gchar">gchar</link> *nick,
                                             const <link linkend="gchar">gchar</link> *blurb,
                                             <link linkend="GParamFlags">GParamFlags</link> flags);
struct      <link linkend="GParamSpecTypeInfo">GParamSpecTypeInfo</link>;
<link linkend="GType">GType</link>       <link linkend="g-param-type-register-static">g_param_type_register_static</link>    (const <link linkend="gchar">gchar</link> *name,
                                             const <link linkend="GParamSpecTypeInfo">GParamSpecTypeInfo</link> *pspec_info);
struct      <link linkend="GParamSpecPool">GParamSpecPool</link>;
<link linkend="GParamSpecPool">GParamSpecPool</link>* <link linkend="g-param-spec-pool-new">g_param_spec_pool_new</link>       (<link linkend="gboolean">gboolean</link> type_prefixing);
void        <link linkend="g-param-spec-pool-insert">g_param_spec_pool_insert</link>        (<link linkend="GParamSpecPool">GParamSpecPool</link> *pool,
                                             <link linkend="GParamSpec">GParamSpec</link> *pspec,
                                             <link linkend="GType">GType</link> owner_type);
void        <link linkend="g-param-spec-pool-remove">g_param_spec_pool_remove</link>        (<link linkend="GParamSpecPool">GParamSpecPool</link> *pool,
                                             <link linkend="GParamSpec">GParamSpec</link> *pspec);
<link linkend="GParamSpec">GParamSpec</link>* <link linkend="g-param-spec-pool-lookup">g_param_spec_pool_lookup</link>        (<link linkend="GParamSpecPool">GParamSpecPool</link> *pool,
                                             const <link linkend="gchar">gchar</link> *param_name,
                                             <link linkend="GType">GType</link> owner_type,
                                             <link linkend="gboolean">gboolean</link> walk_ancestors);
<link linkend="GParamSpec">GParamSpec</link>** <link linkend="g-param-spec-pool-list">g_param_spec_pool_list</link>         (<link linkend="GParamSpecPool">GParamSpecPool</link> *pool,
                                             <link linkend="GType">GType</link> owner_type,
                                             <link linkend="guint">guint</link> *n_pspecs_p);
<link linkend="GList">GList</link>*      <link linkend="g-param-spec-pool-list-owned">g_param_spec_pool_list_owned</link>    (<link linkend="GParamSpecPool">GParamSpecPool</link> *pool,
                                             <link linkend="GType">GType</link> owner_type);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
<link linkend="GParamSpec">GParamSpec</link> is an object structure that encapsulates the meta data
required to specify parameters, such as e.g. <link linkend="GObject">GObject</link> properties.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-TYPE-IS-PARAM-CAPS">G_TYPE_IS_PARAM()</title>
<programlisting>#define G_TYPE_IS_PARAM(type)		(G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
</programlisting>
<para>
Returns whether <parameter>type</parameter> "is a" <literal>G_TYPE_PARAM</literal>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>type</parameter>&nbsp;:</entry>
<entry>a <link linkend="GType">GType</link> ID


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-PARAM-SPEC-CAPS">G_PARAM_SPEC()</title>
<programlisting>#define G_PARAM_SPEC(pspec)		(G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
</programlisting>
<para>
Cast a derived <link linkend="GParamSpec">GParamSpec</link> object (e.g. of type <link linkend="GParamSpecInt">GParamSpecInt</link>) into
a <link linkend="GParamSpec">GParamSpec</link> object.
</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-IS-PARAM-SPEC-CAPS">G_IS_PARAM_SPEC()</title>
<programlisting>#define G_IS_PARAM_SPEC(pspec)		(G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
</programlisting>
<para>
Check whether <parameter>pspec</parameter> "is a" valid <link linkend="GParamSpec">GParamSpec</link> structure of type <literal>G_TYPE_PARAM</literal>
or derived.
</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 <link linkend="GParamSpec">GParamSpec</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-PARAM-SPEC-CLASS-CAPS">G_PARAM_SPEC_CLASS()</title>
<programlisting>#define G_PARAM_SPEC_CLASS(pclass)      (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
</programlisting>
<para>
Cast a derived <link linkend="GParamSpecClass">GParamSpecClass</link> structure into a <link linkend="GParamSpecClass">GParamSpecClass</link> structure.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pclass</parameter>&nbsp;:</entry>
<entry>a valid <link linkend="GParamSpecClass">GParamSpecClass</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-IS-PARAM-SPEC-CLASS-CAPS">G_IS_PARAM_SPEC_CLASS()</title>
<programlisting>#define G_IS_PARAM_SPEC_CLASS(pclass)   (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
</programlisting>
<para>
Check whether <parameter>pclass</parameter> "is a" valid <link linkend="GParamSpecClass">GParamSpecClass</link> structure of type <literal>G_TYPE_PARAM</literal>
or derived.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>pclass</parameter>&nbsp;:</entry>
<entry>a <link linkend="GParamSpecClass">GParamSpecClass</link>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-PARAM-SPEC-GET-CLASS-CAPS">G_PARAM_SPEC_GET_CLASS()</title>
<programlisting>#define G_PARAM_SPEC_GET_CLASS(pspec)	(G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
</programlisting>
<para>
Retrieve the <link linkend="GParamSpecClass">GParamSpecClass</link> of a <link linkend="GParamSpec">GParamSpec</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>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-PARAM-SPEC-TYPE-CAPS">G_PARAM_SPEC_TYPE()</title>
<programlisting>#define G_PARAM_SPEC_TYPE(pspec)	(G_TYPE_FROM_INSTANCE (pspec))
</programlisting>
<para>
Retrive the <link linkend="GType">GType</link> of this <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-TYPE-NAME-CAPS">G_PARAM_SPEC_TYPE_NAME()</title>
<programlisting>#define G_PARAM_SPEC_TYPE_NAME(pspec)	(g_type_name (G_PARAM_SPEC_TYPE (pspec)))
</programlisting>
<para>
Retrive the <link linkend="GType">GType</link> name of this <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-VALUE-TYPE-CAPS">G_PARAM_SPEC_VALUE_TYPE()</title>
<programlisting>#define	G_PARAM_SPEC_VALUE_TYPE(pspec)	(G_PARAM_SPEC (pspec)-&gt;value_type)
</programlisting>
<para>
Retrive the <link linkend="GType">GType</link> to intiialize a <link linkend="GValue">GValue</link> for this 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="GParamSpec">struct GParamSpec</title>
<programlisting>struct GParamSpec
{
  GTypeInstance  g_type_instance;

  gchar         *name;
  GParamFlags    flags;
  GType		 value_type;
  GType		 owner_type;	/* class using this property */

  /*&lt; private &gt;*/
  gchar         *_nick;
  gchar         *_blurb;
  GData		*qdata;
  guint          ref_count;
  guint		 param_id;	/* sort-criteria */
};
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="GTypeInstance">GTypeInstance</link> <structfield>g_type_instance</structfield></entry>
<entry>private <link linkend="GTypeInstance">GTypeInstance</link> portion
</entry>
</row>
<row>
<entry><link linkend="gchar">gchar</link> *<structfield>name</structfield></entry>
<entry>           name of this parameter
</entry>
</row>
<row>
<entry><link linkend="GParamFlags">GParamFlags</link> <structfield>flags</structfield></entry>
<entry>          <link linkend="GParamFlags">GParamFlags</link> flags for this parameter
</entry>
</row>
<row>
<entry><link linkend="GType">GType</link> <structfield>value_type</structfield></entry>
<entry>     the <link linkend="GValue">GValue</link> type for this parameter
</entry>
</row>
<row>
<entry><link linkend="GType">GType</link> <structfield>owner_type</structfield></entry>
<entry>     <link linkend="GType">GType</link> type that uses (introduces) this paremeter

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GParamSpecClass">struct GParamSpecClass</title>
<programlisting>struct GParamSpecClass;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GParamFlags">enum GParamFlags</title>
<programlisting>typedef enum
{
  G_PARAM_READABLE            = 1 &lt;&lt; 0,
  G_PARAM_WRITABLE            = 1 &lt;&lt; 1,