GODoc: GOffice Reference Manual

## GODoc GODoc |

## Functions

GOImage * | go_doc_add_image ()
void | go_doc_bump_state ()
void | go_doc_end_read ()
gint64 | go_doc_get_dirty_time ()
GOImage * | go_doc_get_image ()
GHashTable * | go_doc_get_images ()
GsfDocMetaData * | go_doc_get_meta_data ()
GDateTime * | go_doc_get_modtime ()
guint64 | go_doc_get_saved_state ()
guint64 | go_doc_get_state ()
char const * | go_doc_get_uri ()
GOImage * | go_doc_image_fetch ()
void | go_doc_init_read ()
void | go_doc_init_write ()
gboolean | go_doc_is_dirty ()
gboolean | go_doc_is_pristine ()
void | go_doc_read ()
void | go_doc_save_image ()
void | go_doc_save_resource ()
void | go_doc_set_dirty ()
void | go_doc_set_dirty_time ()
void | go_doc_set_meta_data ()
void | go_doc_set_modtime ()
void | go_doc_set_pristine ()
void | go_doc_set_saved_state ()
void | go_doc_set_state ()
gboolean | go_doc_set_uri ()
void | go_doc_update_meta_data ()
void | go_doc_write ()

## Properties

gboolean | dirty | Read / Write
gint64 | dirty-time | Read / Write
GDateTime * | modtime | Read / Write
gboolean | pristine | Read / Write
guint64 | saved-state | Read / Write
guint64 | state | Read / Write
char * | uri | Read / Write

## Signals

void | metadata-changed | Run Last
void | metadata-update | Run Last

## Types and Values

| GODoc

## Object Hierarchy

        GObject
        ╰── GODoc

## Description

## Functions

### go_doc_add_image ()

    GOImage *
    go_doc_add_image (GODoc *doc,
                      char const *id,
                      GOImage *image);

Adds `image` to the document if no such image already exists. The name of the returned image might be different from `id` , even if given.

#### Parameters

doc | a GODoc |
id | the image name or `NULL` |
image | a GOImage |

#### Returns

either `image` , in which case the document adds a reference on it, or an identical image for which the owner does not own a reference.

[transfer none]

### go_doc_bump_state ()

    void
    go_doc_bump_state (GODoc *doc);

Sets the current state of the document to a fresh id.

#### Parameters

doc | GODoc |

### go_doc_end_read ()

    void
    go_doc_end_read (GODoc *doc);

### go_doc_get_dirty_time ()

    gint64
    go_doc_get_dirty_time (GODoc const *doc);

#### Parameters

doc | GODoc |

#### Returns

the time (as in `g_get_real_time()`) the document was first marked dirty.

### go_doc_get_image ()

    GOImage *
    go_doc_get_image (GODoc *doc,
                      char const *id);

#### Parameters

doc | a GODoc |
id | the image name |

#### Returns

the GOImage is one exist with name `id` . The caller does not own a reference.

[transfer none]

### go_doc_get_images ()

    GHashTable *
    go_doc_get_images (GODoc *doc);

#### Parameters

doc | GODoc |

#### Returns

the images registered inside the document.

[transfer none]

### go_doc_get_meta_data ()

    GsfDocMetaData *
    go_doc_get_meta_data (GODoc const *doc);

#### Parameters

doc | GODoc |

#### Returns

`doc` 's metadata.

[transfer none]

### go_doc_get_modtime ()

    GDateTime *
    go_doc_get_modtime (GODoc const *doc);

#### Parameters

doc | GODoc |

#### Returns

the last known file system time stamp for the document, or `NULL` if unknown.

[transfer none]

### go_doc_get_saved_state ()

    guint64
    go_doc_get_saved_state (GODoc *doc);

#### Parameters

doc | GODoc |

#### Returns

the state at the last time the document was saved.

### go_doc_get_state ()

    guint64
    go_doc_get_state (GODoc *doc);

#### Parameters

doc | GODoc |

#### Returns

the current state of the document.

### go_doc_get_uri ()

    char const	*
    go_doc_get_uri (GODoc const *doc);

### go_doc_image_fetch ()

    GOImage *
    go_doc_image_fetch (GODoc *doc,
                        char const *id,
                        GType type);

Searches for a GOImage with name `id` in the document image buffer and creates one if needed. The caller does not own a reference on the returned GOImage. This function must be called after a call to `go_doc_init_read()`, otherwise it will emit a critical and return NULL.

#### Parameters

doc | a GODoc |
id | the name for the new image. |
type | the type of the GOImage to create if needed. |

#### Returns

the found or created GOImage.

[transfer none]

### go_doc_init_read ()

    void
    go_doc_init_read (GODoc *doc,
                      GsfInput *input);

### go_doc_init_write ()

    void
    go_doc_init_write (GODoc *doc,
                       GsfXMLOut *output);

### go_doc_is_dirty ()

    gboolean
    go_doc_is_dirty (GODoc const *doc);

#### Parameters

doc | GODoc |

#### Returns

TRUE if `doc` has been modified.

### go_doc_is_pristine ()

    gboolean
    go_doc_is_pristine (GODoc const *doc);

This checks to see if the doc has ever been used ( approximately )

#### Parameters

doc | GODoc |

#### Returns

`TRUE` if we can discard this doc.

### go_doc_read ()

    void
    go_doc_read (GODoc *doc,
                 GsfXMLIn *xin,
                 xmlChar const **attrs);

### go_doc_save_image ()

    void
    go_doc_save_image (GODoc *doc,
                       char const *id);

Saves the image with the document. Each image will be saved only once.

#### Parameters

doc | a GODoc |
id | the Id of the GOImage to save |

### go_doc_save_resource ()

    void
    go_doc_save_resource (GODoc *doc,
                          GOPersist const *gp);

Saves the resource with the document. Each resource will be saved only once.

#### Parameters

doc | a GODoc |
gp | the GOPersist to save |

### go_doc_set_dirty ()

    void
    go_doc_set_dirty (GODoc *doc,
                      gboolean is_dirty);

Changes the dirty state of `doc` to `is_dirty` and clears the pristine state no matter what.

#### Parameters

doc | GODoc |
is_dirty | bool |

### go_doc_set_dirty_time ()

    void
    go_doc_set_dirty_time (GODoc *doc,
                           gint64 t);

Changes the dirty time, i.e., the time the document was first marked dirty.

#### Parameters

doc | GODoc |
t | a timestamp from g_get_real_time |

### go_doc_set_meta_data ()

    void
    go_doc_set_meta_data (GODoc *doc,
                          GsfDocMetaData *data);

Adds a ref to `data` .

#### Parameters

doc | GODoc |
data | GsfDocMetaData |

### go_doc_set_modtime ()

    void
    go_doc_set_modtime (GODoc *doc,
                        GDateTime *modtime);

Sets the last known file system time stamp for the document, `NULL` if unknown.

#### Parameters

doc | GODoc |
modtime | new file system time stamp. | [allow-none]

### go_doc_set_pristine ()

    void
    go_doc_set_pristine (GODoc *doc,
                         gboolean pristine);

Sets the indication of whether this document is unchanged since it was created. Note: if both "dirty" and "pristine" are being set, set "pristine" last.

#### Parameters

doc | GODoc |
pristine | a gboolean. |

### go_doc_set_saved_state ()

    void
    go_doc_set_saved_state (GODoc *doc,
                            guint64 state);

Sets the state at the last time the document was saved.

#### Parameters

doc | GODoc |
state | state at the time of last save |

### go_doc_set_state ()

    void
    go_doc_set_state (GODoc *doc,
                      guint64 state);

Sets the current state of the document as a serial number that is intended to be incremented for each document change.

Setting the state will set the document's dirty status also, assuming both the state and the saved state are known.

#### Parameters

doc | GODoc |
state | state of document |

### go_doc_set_uri ()

    gboolean
    go_doc_set_uri (GODoc *doc,
                    char const *uri);

#### Parameters

doc | the document to modify |
uri | the uri for this worksheet. |

#### Returns

TRUE if the name was set succesfully.

### go_doc_update_meta_data ()

    void
    go_doc_update_meta_data (GODoc *doc);

Signal that `doc` 's metadata should be updated - statistics (sheet count, word count) - content (sheet names, bookmarks) - reloading linked items

#### Parameters

doc | GODoc |

### go_doc_write ()

    void
    go_doc_write (GODoc *doc,
                  GsfXMLOut *output);

## Types and Values

### GODoc

    typedef struct _GODoc GODoc;

## Property Details

### The `“dirty”` property

      “dirty”                    gboolean

Whether the document has been changed.

Owner: GODoc

Flags: Read / Write

Default value: FALSE

### The `“dirty-time”` property

      “dirty-time”               gint64

When the document was first changed.

Owner: GODoc

Flags: Read / Write

Default value: 0

### The `“modtime”` property

      “modtime”                  GDateTime *

The known file system modification time.

Owner: GODoc

Flags: Read / Write

### The `“pristine”` property

      “pristine”                 gboolean

Whether the document is unchanged since it was created.

Owner: GODoc

Flags: Read / Write

Default value: FALSE

### The `“saved-state”` property

      “saved-state”              guint64

State of document when last saved.

Owner: GODoc

Flags: Read / Write

Default value: 0

### The `“state”` property

      “state”                    guint64

Current state of document.

Owner: GODoc

Flags: Read / Write

Default value: 0

### The `“uri”` property

      “uri”                      char *

The URI associated with this document.

Owner: GODoc

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“metadata-changed”` signal

    void
    user_function (GODoc   *godoc,
                   gpointer user_data)

Flags: Run Last

### The `“metadata-update”` signal

    void
    user_function (GODoc   *godoc,
                   gpointer user_data)

Flags: Run Last