Geany  0.20
Data Structures | Defines | Typedefs | Functions | Variables
document.h File Reference

Document related actions: new, save, open, etc. More...

Data Structures

struct  GeanyDocument
 Structure for representing an open tab with all its properties. More...
struct  GeanyFilePrefs
 File Prefs. More...

Defines

#define DOC_FILENAME(doc)   (G_LIKELY(doc->file_name != NULL) ? (doc->file_name) : GEANY_STRING_UNTITLED)
 Returns the filename of the document passed or GEANY_STRING_UNTITLED (e.g.
#define DOC_VALID(doc_ptr)   (G_LIKELY((doc_ptr) != NULL) && G_LIKELY((doc_ptr)->is_valid))
 NULL-safe way to check doc_ptr->is_valid.
#define documents   ((GeanyDocument **)GEANY(documents_array)->pdata)
 Wraps documents_array so it can be used with C array syntax.
#define documents_foreach(i)   foreach_document(i)
#define foreach_document(i)
 Iterates all valid documents.

Typedefs

typedef struct GeanyFilePrefs GeanyFilePrefs
 File Prefs.

Functions

gboolean document_close (GeanyDocument *doc)
 Closes the given document.
GeanyDocumentdocument_find_by_filename (const gchar *utf8_filename)
 Finds a document with the given filename.
GeanyDocumentdocument_find_by_real_path (const gchar *realname)
 Finds a document whose real_path field matches the given filename.
gchar * document_get_basename_for_display (GeanyDocument *doc, gint length)
 Returns the last part of the filename of the given GeanyDocument.
GeanyDocumentdocument_get_current (void)
 Finds the current document.
GeanyDocumentdocument_get_from_page (guint page_num)
 Finds the document for the given notebook page page_num.
gint document_get_notebook_page (GeanyDocument *doc)
 Gets the notebook page index for a document.
const GdkColor * document_get_status_color (GeanyDocument *doc)
 Gets the status color of the document, or NULL if default widget coloring should be used.
GeanyDocumentdocument_index (gint idx)
 Accessor function for GeanyData::documents_array items.
GeanyDocumentdocument_new_file (const gchar *filename, GeanyFiletype *ft, const gchar *text)
 Creates a new document.
GeanyDocumentdocument_open_file (const gchar *locale_filename, gboolean readonly, GeanyFiletype *ft, const gchar *forced_enc)
 Opens a document specified by locale_filename.
void document_open_files (const GSList *filenames, gboolean readonly, GeanyFiletype *ft, const gchar *forced_enc)
 Opens each file in the list filenames.
gboolean document_reload_file (GeanyDocument *doc, const gchar *forced_enc)
 Reloads the document with the specified file encoding forced_enc or NULL to auto-detect the file encoding.
gboolean document_remove_page (guint page_num)
 Removes the given notebook tab at page_num and clears all related information in the document list.
void document_rename_file (GeanyDocument *doc, const gchar *new_filename)
 Renames the file in doc to new_filename.
gboolean document_save_file (GeanyDocument *doc, gboolean force)
 Saves the document.
gboolean document_save_file_as (GeanyDocument *doc, const gchar *utf8_fname)
 Saves the document, detecting the filetype.
void document_set_encoding (GeanyDocument *doc, const gchar *new_encoding)
 Sets the encoding of a document.
void document_set_filetype (GeanyDocument *doc, GeanyFiletype *type)
 Sets the filetype of the document (which controls syntax highlighting and tags)
void document_set_text_changed (GeanyDocument *doc, gboolean changed)
 Updates the tab labels, the status bar, the window title and some save-sensitive buttons according to the document's save state.

Variables

GPtrArray * documents_array
 Dynamic array of GeanyDocument pointers holding information about the notebook tabs.

Detailed Description

Document related actions: new, save, open, etc.


Define Documentation

#define DOC_FILENAME (   doc)    (G_LIKELY(doc->file_name != NULL) ? (doc->file_name) : GEANY_STRING_UNTITLED)

Returns the filename of the document passed or GEANY_STRING_UNTITLED (e.g.

_("untitled")) if the document's filename was not yet set. This macro never returns NULL.

#define DOC_VALID (   doc_ptr)    (G_LIKELY((doc_ptr) != NULL) && G_LIKELY((doc_ptr)->is_valid))

NULL-safe way to check doc_ptr->is_valid.

This is useful when doc_ptr was stored some time earlier and documents may have been closed since then.

Note:
This should not be used to check the result of the main API functions, these only need a NULL-pointer check - document_get_current() != NULL.
#define documents   ((GeanyDocument **)GEANY(documents_array)->pdata)

Wraps documents_array so it can be used with C array syntax.

Example: documents[0]->sci = NULL;

See also:
document_index().
#define documents_foreach (   i)    foreach_document(i)
Deprecated:
Use foreach_document() instead.

Iterates all valid documents. Use like a for statement.

Parameters:
iguint index for document_index().
#define foreach_document (   i)
Value:
for (i = 0; i < GEANY(documents_array)->len; i++)\
        if (!documents[i]->is_valid)\
            {}\
        else

Iterates all valid documents.

Use like a for statement.

Parameters:
iguint index for document_index().

Typedef Documentation

File Prefs.


Function Documentation

gboolean document_close ( GeanyDocument doc)

Closes the given document.

Parameters:
docThe document to remove.
Returns:
TRUE if the document was actually removed or FALSE otherwise.
Since:
0.15
GeanyDocument* document_find_by_filename ( const gchar *  utf8_filename)

Finds a document with the given filename.

This matches either an exact GeanyDocument::file_name string, or variant filenames with relative elements in the path (e.g. "/dir/..//name" will match "/name").

Parameters:
utf8_filenameThe filename to search (in UTF-8 encoding).
Returns:
The matching document, or NULL.
See also:
document_find_by_real_path().
GeanyDocument* document_find_by_real_path ( const gchar *  realname)

Finds a document whose real_path field matches the given filename.

Parameters:
realnameThe filename to search, which should be identical to the string returned by tm_get_real_path().
Returns:
The matching document, or NULL.
Note:
This is only really useful when passing a TMWorkObject::file_name.
See also:
GeanyDocument::real_path.
document_find_by_filename().
Since:
0.15
gchar* document_get_basename_for_display ( GeanyDocument doc,
gint  length 
)

Returns the last part of the filename of the given GeanyDocument.

The result is also truncated to a maximum of length characters in case the filename is very long.

Parameters:
docThe document to use.
lengthThe length of the resulting string or -1 to use a default value.
Returns:
The ellipsized last part of the filename of doc, should be freed when no longer needed.
Since:
0.17
GeanyDocument* document_get_current ( void  )

Finds the current document.

Returns:
A pointer to the current document or NULL if there are no opened documents.
GeanyDocument* document_get_from_page ( guint  page_num)

Finds the document for the given notebook page page_num.

Parameters:
page_numThe notebook page number to search.
Returns:
The corresponding document for the given notebook page, or NULL.
gint document_get_notebook_page ( GeanyDocument doc)

Gets the notebook page index for a document.

Parameters:
docThe document.
Returns:
The index.
Since:
0.19
const GdkColor* document_get_status_color ( GeanyDocument doc)

Gets the status color of the document, or NULL if default widget coloring should be used.

Returned colors are red if the document has changes, green if the document is read-only or simply NULL if the document is unmodified but writable.

Parameters:
docThe document to use.
Returns:
The color for the document or NULL if the default color should be used. The color object is owned by Geany and should not be modified or freed.
Since:
0.16
GeanyDocument* document_index ( gint  idx)

Accessor function for GeanyData::documents_array items.

Warning:
Always check the returned document is valid (doc->is_valid).
Parameters:
idxdocuments_array index.
Returns:
The document, or NULL if idx is out of range.
Since:
0.16
GeanyDocument* document_new_file ( const gchar *  utf8_filename,
GeanyFiletype ft,
const gchar *  text 
)

Creates a new document.

Line endings in text will be converted to the default setting. Afterwards, the "document-new" signal is emitted for plugins.

Parameters:
utf8_filenameThe file name in UTF-8 encoding, or NULL to open a file as "untitled".
ftThe filetype to set or NULL to detect it from filename if not NULL.
textThe initial content of the file (in UTF-8 encoding), or NULL.
Returns:
The new document.
GeanyDocument* document_open_file ( const gchar *  locale_filename,
gboolean  readonly,
GeanyFiletype ft,
const gchar *  forced_enc 
)

Opens a document specified by locale_filename.

Afterwards, the "document-open" signal is emitted for plugins.

Parameters:
locale_filenameThe filename of the document to load, in locale encoding.
readonlyWhether to open the document in read-only mode.
ftThe filetype for the document or NULL to auto-detect the filetype.
forced_encThe file encoding to use or NULL to auto-detect the file encoding.
Returns:
The document opened or NULL.
void document_open_files ( const GSList *  filenames,
gboolean  readonly,
GeanyFiletype ft,
const gchar *  forced_enc 
)

Opens each file in the list filenames.

Internally, document_open_file() is called for every list item.

Parameters:
filenamesA list of filenames to load, in locale encoding.
readonlyWhether to open the document in read-only mode.
ftThe filetype for the document or NULL to auto-detect the filetype.
forced_encThe file encoding to use or NULL to auto-detect the file encoding.
gboolean document_reload_file ( GeanyDocument doc,
const gchar *  forced_enc 
)

Reloads the document with the specified file encoding forced_enc or NULL to auto-detect the file encoding.

Parameters:
docThe document to reload.
forced_encThe file encoding to use or NULL to auto-detect the file encoding.
Returns:
TRUE if the document was actually reloaded or FALSE otherwise.
gboolean document_remove_page ( guint  page_num)

Removes the given notebook tab at page_num and clears all related information in the document list.

Parameters:
page_numThe notebook page number to remove.
Returns:
TRUE if the document was actually removed or FALSE otherwise.
void document_rename_file ( GeanyDocument doc,
const gchar *  new_filename 
)

Renames the file in doc to new_filename.

Only the file on disk is actually renamed, you still have to call document_save_file_as() to change the doc object. It also stops monitoring for file changes to prevent receiving too many file change events while renaming. File monitoring is setup again in document_save_file_as().

Parameters:
docThe current document which should be renamed.
new_filenameThe new filename in UTF-8 encoding.
Since:
0.16
gboolean document_save_file ( GeanyDocument doc,
gboolean  force 
)

Saves the document.

Saving may include replacing tabs by spaces, stripping trailing spaces and adding a final new line at the end of the file, depending on user preferences. Then the "document-before-save" signal is emitted, allowing plugins to modify the document before it is saved, and data is actually written to disk. The filetype is set again or auto-detected if it wasn't set yet. Afterwards, the "document-save" signal is emitted for plugins.

If the file is not modified, this functions does nothing unless force is set to TRUE.

Note:
You should ensure doc->file_name is not NULL before calling this; otherwise call dialogs_show_save_as().
Parameters:
docThe document to save.
forceWhether to save the file even if it is not modified (e.g. for Save As).
Returns:
TRUE if the file was saved or FALSE if the file could not or should not be saved.
gboolean document_save_file_as ( GeanyDocument doc,
const gchar *  utf8_fname 
)

Saves the document, detecting the filetype.

Parameters:
docThe document for the file to save.
utf8_fnameThe new name for the document, in UTF-8, or NULL.
Returns:
TRUE if the file was saved or FALSE if the file could not be saved.
See also:
document_save_file().
Since:
0.16
void document_set_encoding ( GeanyDocument doc,
const gchar *  new_encoding 
)

Sets the encoding of a document.

This function only set the encoding of the document, it does not any conversions. The new encoding is used when e.g. saving the file.

Parameters:
docThe document to use.
new_encodingThe encoding to be set for the document.
void document_set_filetype ( GeanyDocument doc,
GeanyFiletype type 
)

Sets the filetype of the document (which controls syntax highlighting and tags)

Parameters:
docThe document to use.
typeThe filetype.
void document_set_text_changed ( GeanyDocument doc,
gboolean  changed 
)

Updates the tab labels, the status bar, the window title and some save-sensitive buttons according to the document's save state.

This is called by Geany mostly when opening or saving files.

Parameters:
docThe document to use.
changedWhether the document state should indicate changes have been made.

Variable Documentation

GPtrArray* documents_array

Dynamic array of GeanyDocument pointers holding information about the notebook tabs.

Once a pointer is added to this, it is never freed. This means you can keep a pointer to a document over time, but it might no longer represent a notebook tab. To check this, check doc_ptr->is_valid. Of course, the pointer may represent a different file by then.

You also need to check GeanyDocument::is_valid when iterating over this array, although usually you would just use the foreach_document() macro.

Never assume that the order of document pointers is the same as the order of notebook tabs. Notebook tabs can be reordered. Use document_get_from_page().