tester Reference Manual: GtkdocObject

## GtkdocObject GtkdocObject — class for gtk-doc unit test |

## Synopsis

    struct              GtkdocObject;
    struct              GtkdocObjectClass;
    GtkdocObject *      gtkdoc_object_new                   (void);
    void                gtkdoc_object_set_otest             (GObject *self,
                                                             const gchar *value);
    void                gtkdoc_object_frobnicate            (GObject *self,
                                                             gint n);
    gboolean            gtkdoc_object_fooify                (GObject *self,
                                                             ...);
    void                gtkdoc_object_do_not_use            (GObject *self);
    #define             GTKDOC_OBJECT_MACRO_DUMMY           (parameter_1,
                                                             parameter_2)
    #define             GTKDOC_OBJECT_MACRO_SUM             (parameter_1,
                                                             parameter_2)

## Object Hierarchy

      GObject
       +----GtkdocObject

## Properties

      "dep-otest"                gchar*                : Read / Write
      "otest"                    gchar*                : Read / Write

## Signals

      "dep-otest"                                      : No Hooks
      "otest"                                          : No Hooks
      "strings-changed"                                : No Hooks
      "variant-changed"                                : No Hooks

## Description

> Two line quote

Offsets are time values to be added to local time to get Coordinated Universal Time (UTC) and should be `"[±]hh[[:]mm[:ss]]"`. Dates are either `"Jn"` (Julian day with n between 1 and 365, leap years not counted), `"n"` (zero-based Julian day with n between 0 and 365) or `"Mm.w.d"` (day d (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day 0 is a Sunday). Times are in local wall clock time, the default is 02:00:00.

`lang_COUNTRY`MODIFIER``

This file contains non-sense code for the sole purpose of testing the docs. We can link to the "otest" property and the "otest" signal.

When subclassing it is useful to override the `GtkdocObjectClass.test()` method. The `GtkdocObjectClass.foo_bar()` vmethod lets you refine your frobnicator.

A new instance can be created using the `gtkdoc_object_new()` function. The whole lifecycle usualy looks like shown in this example:

    1
    2
    3
    4
    5
    GObject *myobj;

    myobj = gtkdoc_object_new();
    // do something
    g_object_unref (myobj);

### Examples

Here are a few examples.

#### Example 1

You can also change parameters:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    /* example for gobject usage
     * checkout the article at http://en.wikipedia.org/wiki/GObject
     *
     * This example is part of the release, that can be downloaded
     * from ftp://ftp.gnome.org/pub/gnome/sources/gtk-doc/ or any mirror.
     */

    #include <glib.h>
    #include <glib-object.h>

    gint
    main(gint argc, gchar **argv)
    {
      GObject *myobj;

      myobj = gtkdoc_object_new();
      g_object_set (myobj, "parameter", 5, NULL);
      g_object_unref (myobj);

      return 0;
    }

This example serves two main purposes:

- `test`ing conversion (`long description follows here`)

- catching bugs

  GTK

- having an example

### Discussion

This is a section with a heading without a trailing hash mark.

> Do not confuse the GtkUIManager UI Definitions described here with the similarly named GtkBuilder UI Definitions.

> Single line quote

1. This list is here to ensure the parsing of the above list

2. Doesn't change it.

This example serves two main purposes:

- testing alternate list syntax

  With section text in each.

- not sure if we want this one

  It has more stuff.

#### An embedded docbook section

Some stuff

- A list - Inside markup

### Coda

1. This is a ordered list

2. This is a code block in a list:

       1
       2
       3
       4
       5
       GObject *myobj;

       myobj = gtkdoc_object_new();
       // do something
       g_object_unref (myobj);

   And another:

       1
       2
       3
       4
       5
       GObject *myobj;

       myobj = gtkdoc_object_new();
       /* do something */
       g_object_unref (myobj);

3. Really

   Has a paragraph.

4. Is

Nothing more to say.

## Details

### struct GtkdocObject

    struct GtkdocObject;

instance data of gtk-doc unit test class

### struct GtkdocObjectClass

    struct GtkdocObjectClass {
      GObjectClass parent;

      /* class methods */
      void (*test)(const GtkdocObject * const self, gconstpointer const user_data);
      gboolean (*ping)(const GtkdocObject * const self);
      gboolean (*foo_bar)(const GtkdocObject * const self);
    };

class data of gtk-doc unit test class

GObjectClass `parent`; | this is a bug :/
`test` () | overideable method
`ping` () | can be used before calling the ``test()`` function
`foo_bar` () | lets you refine your frobnicator

### gtkdoc_object_new ()

    GtkdocObject *      gtkdoc_object_new                   (void);

Create a new instance

### Note

This will only work if you have called `g_type_init()` before.

Returns : | the instance or `NULL` in case of an error

Since 0.1

### gtkdoc_object_set_otest ()

    void                gtkdoc_object_set_otest             (GObject *self,
                                                             const gchar *value);

### Warning

`gtkdoc_object_set_otest` is deprecated and should not be used in newly-written code.

Use g_object_set(obj,"otest",value,NULL); instead.

Set the "otest" property. This is a long paragraph.

Oh, btw. setting the property directly saves us one method.

`self` : | the object
`value` : | the new otest value, whose description extends further than one line will allow

Since 0.5

### gtkdoc_object_frobnicate ()

    void                gtkdoc_object_frobnicate            (GObject *self,
                                                             gint n);

Frobnicate the content of `self` `n` times. This implements a complex algorithm (http://en.wikipedia.org/wiki/Algorithm).

[1]

`self` : | the object
`n` : | number of iterations

Since 0.5

### gtkdoc_object_fooify ()

    gboolean            gtkdoc_object_fooify                (GObject *self,
                                                             ...);

Fooify the content of `self` .

`self` : | the object
`...` : | a NULL terminated list of arguments
Returns : | `TRUE` for success

### gtkdoc_object_do_not_use ()

    void                gtkdoc_object_do_not_use            (GObject *self);

### Warning

`gtkdoc_object_do_not_use` has been deprecated since version 3.10 and should not be used in newly-written code.

3.10

Test a deprecation without additional message.

`self` : | the object

### GTKDOC_OBJECT_MACRO_DUMMY()

    #define GTKDOC_OBJECT_MACRO_DUMMY(parameter_1,parameter_2) /* do nothing */

This macro does nothing.

`parameter_1` : | first arg
`parameter_2` : | second arg

Since 0.1

### GTKDOC_OBJECT_MACRO_SUM()

    #define             GTKDOC_OBJECT_MACRO_SUM(parameter_1,parameter_2)

This macro adds its args.

`parameter_1` : | first arg
`parameter_2` : | second arg
Returns : | the sum of `parameter_1` and `parameter_2`

## Property Details

### The `"dep-otest"` property

      "dep-otest"                gchar*                : Read / Write

### Warning

`GtkdocObject:dep-otest` is deprecated and should not be used in newly-written code.

use "otest" property

dummy deprecated property for object.

Default value: "dummy"

### The `"otest"` property

      "otest"                    gchar*                : Read / Write

dummy property for object.

Default value: "dummy"

Since 0.1

## Signal Details

### The `"dep-otest"` signal

    void                user_function                      (GtkdocObject *self,
                                                            gpointer      user_data)      : No Hooks

### Warning

`GtkdocObject::dep-otest` is deprecated and should not be used in newly-written code.

Use the "otest" signal instead.

Here's an example signal handler.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    static gchar*
    otest_callback (GObject  *o,
                    gpointer  user_data)
    {
      gdouble      value;

      value = abs (o->value);

      return value;
    }

`self` : | myself
`user_data` : | user data set when the signal handler was connected.

### The `"otest"` signal

    void                user_function                      (GtkdocObject *self,
                                                            gpointer      user_data)      : No Hooks

The event has been triggered.

`self` : | myself
`user_data` : | user data set when the signal handler was connected.

### The `"strings-changed"` signal

    void                user_function                      (GtkdocObject *arg0,
                                                            GStrv         arg1,
                                                            gpointer      user_data)      : No Hooks

Something has happened.

`user_data` : | user data set when the signal handler was connected.

### The `"variant-changed"` signal

    void                user_function                      (GtkdocObject *arg0,
                                                            GVariant     *arg1,
                                                            gpointer      user_data)      : No Hooks

Something has happened.

`user_data` : | user data set when the signal handler was connected.

## See Also

GtkdocIface

[1] Negative frobnication can lead to unexpected behaviour.