diff options
Diffstat (limited to 'doc/properties.sgml')
| -rw-r--r-- | doc/properties.sgml | 165 |
1 files changed, 74 insertions, 91 deletions
diff --git a/doc/properties.sgml b/doc/properties.sgml index 3a27aadd..7db9e737 100644 --- a/doc/properties.sgml +++ b/doc/properties.sgml @@ -11,30 +11,50 @@ How to augment or define a #GladePropertyClass </refnamediv> <refsect1> - <title>Property Class Parameters</title> + <title>Property Class Configuration</title> <para> -There are alot of things that can be done with properties in glade; properties -can be added and removed from widget classes, lets list all the different -things you can do with properties. +Properties are introspected at load time and loaded into #GladePropertyClass structures. +The behaviour of properties can be modified by the catalog and fake properties can be added +for editing purposes. Here is an example of the xml form: + <programlisting><![CDATA[... + +<property id="frobnicate-mode" default="FOO_FROBNICATE_RED"> + + ... spec, tooltip etc + + <displayable-values> + + <value id="FOO_FROBNICATE_RED" name="Red"/> + <value id="FOO_FROBNICATE_BLUE" name="Blue"/> + + ... values here + + </displayable-values> + +</property> + +...]]></programlisting> + + </para> <para> Properties of the 'property' tag: <variablelist> <varlistentry> - <term>name</term> + <term>id</term> <listitem> <para> -The name to be used in the interface, this string is translated. -(if name is not specified; it defaults to the nickname of the #GParamSpec) +This is manditory and specifies the property that we are modifying (or adding) </para> </listitem> </varlistentry> <varlistentry> - <term>id</term> + <term>name</term> <listitem> <para> -This is manditory and specifies the property that we are modifying (or adding) +The name to be used in the interface. +(if name is not specified; it defaults to the nickname of the #GParamSpec) </para> </listitem> </varlistentry> @@ -140,140 +160,103 @@ is the value saved). <term>resource</term> <listitem> <para> -This is for string properties that represent filenames that are packaged with +Depicts string properties that represent filenames that are packaged with the glade file (like pixbufs); you can set this to "True" and the string property will be treated like a resource. </para> </listitem> </varlistentry> - </variablelist> - </para> - - <para> -Child tags of the 'property' tag: - <variablelist> <varlistentry> - <term>spec</term> + <term>themed-icon</term> <listitem> <para> -Specifies a function to be used to return a #GParamSpec for this property; -this is used to add virtual properties to an object (like the "size" property -on #GtkBox). +Depicts a string property that is used for an icon from the theme. These will +the appropriate editor. </para> </listitem> </varlistentry> <varlistentry> - <term>tooltip</term> + <term>weight</term> <listitem> <para> -The tooltip to be displayed in the property editor for this property, this -is also translated. The tooltip defaults to the blurb of the associated -#GParamSpec. +A numerical value to specify this properties position in the property editor. </para> </listitem> </varlistentry> <varlistentry> - <term>visible-lines</term> + <term>transfer-on-paste</term> <listitem> <para> -An integer value to specify how many lines will be shown for text properties -in the editor (this doesnt really work because of the complexity of calculating -size of rendered text; instead, just set this to 2 if you want the text property -to be edited in a textview with a scrolled window as opposed to a simple text entry). +Used for packing properties; depicts packing properties that should follow +the widget when pasted to a new container that supports the same properties. </para> </listitem> </varlistentry> <varlistentry> - <term>set-function</term> + <term>save-always</term> <listitem> <para> -A #GladeSetPropertyFunc used to set the property instead of g_object_set() +Specifies that the property should be saved regardless of its value (properties at thier +default values are normally not saved). </para> </listitem> </varlistentry> + </variablelist> + </para> + + <para> +Child tags of the 'property' tag: + <variablelist> <varlistentry> - <term>get-function</term> + <term>spec</term> <listitem> <para> -A #GladeSetPropertyFunc function used to set the property instead of g_object_get() +Specifies a function to be used to return a #GParamSpec for this property; +this is used to add virtual properties to an object (like the "size" property +on #GtkBox). </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tooltip</term> + <listitem> <para> -Technical note: that the get-function is hardly ever used, the only -time glade-3 will actually ask the object what a property's value should be; -is when adding a widget to a container and introspecting the values that -the container assigned the child as packing properties. +The tooltip to be displayed in the property editor for this property. +The tooltip defaults to the blurb of the associated #GParamSpec. </para> </listitem> </varlistentry> <varlistentry> - <term>verify-function</term> + <term>visible-lines</term> <listitem> <para> -A #GladeVerifyPropertyFunc function to verify whether the requested value is valid. -If specified; the editor will not allow the user to commit a value that this -function returns False for. +An integer value to specify how many lines will be shown for text properties +in the editor (this doesnt really work because of the complexity of calculating +size of rendered text; instead, just set this to 2 if you want the text property +to be edited in a textview with a scrolled window as opposed to a simple text entry). </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>displayable-values</term> + <listitem> <para> -Technical note: verify functions are nescisary in glade-3 because of -the abstraction between the value maintained in the glade-3 core and -the value that is actually on the said GObject's property. In other words, -if verify-function returns false; glade's value won't change and set-function -won't be called, if set-function decides not commit the said value, thats -its own rotten business (hehe) and if the property is set to ignore="True", -verify functions will still function properly even if set-functions are not -called for that property. +Allows you to specify user friendly strings for enum and flag values as shown in the +example above, use the `id' property in the value tag to depict the real value name +and the `name' property for the human readable one. </para> </listitem> </varlistentry> + </variablelist> </para> </refsect1> - <refsect2> - <title>Displayable Values, Packing defaults and such</title> - <para> -Enum and Flag type properties tend to have long complicated names unsuited for the glade -environment, glade will allow you to substitute these names using the displayable-values -child tag; the form looks like this: - <programlisting> -<![CDATA[<property id="pack-type"> - <displayable-values> - <value id="GTK_PACK_START" name="Start"></value> - <value id="GTK_PACK_END" name="End"></value> - </displayable-values> -</property>]]></programlisting> -Note that the "name" (which will be the resulting name for each `id') is a translated -string. - </para> - - <para> -A widget class may have default packing properties for each type of container that -it can be added to; a short example should suffice as a description of how this works: - <programlisting> -<![CDATA[<packing-defaults> - <parent-class name="GtkVBox"> - <child-property id="expand" default="false"/> - </parent-class> -</packing-defaults>]]></programlisting> -Note that you can list any number of 'packing-defaults' in a row. - </para> - - <para> -Properties can have additional parameters; these are completely unused by glade -but may be usefull for a plugin writer who may want to use the GladeParameter -api to find parameters on property classes; the form looks like this: - <programlisting> -<![CDATA[<property id="foo"> - <parameters> - <parameter key="Min" value="1"/> - <parameter key="Max" value="10000"/> - </parameters> -</property>]]></programlisting> - </para> - </refsect2> </refentry> |