Geany  dev
Data Structures | Macros | 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...
 

Macros

#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. More...
 
#define DOC_VALID(doc_ptr)   ((doc_ptr) != NULL && (doc_ptr)->is_valid)
 Null-safe way to check GeanyDocument::is_valid. More...
 
#define documents   ((GeanyDocument **)GEANY(documents_array)->pdata)
 Wraps documents_array so it can be used with C array syntax. More...
 
#define documents_foreach(i)   foreach_document(i)
 
#define foreach_document(i)
 Iterates all valid document indexes. More...
 

Typedefs

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

Functions

gboolean document_close (GeanyDocument *doc)
 Closes the given document. More...
 
gint document_compare_by_display_name (gconstpointer a, gconstpointer b)
 Compares documents by their display names. More...
 
gint document_compare_by_tab_order (gconstpointer a, gconstpointer b)
 Compares documents by their tab order. More...
 
gint document_compare_by_tab_order_reverse (gconstpointer a, gconstpointer b)
 Compares documents by their tab order, in reverse order. More...
 
GeanyDocumentdocument_find_by_filename (const gchar *utf8_filename)
 Finds a document with the given filename. More...
 
GeanyDocumentdocument_find_by_real_path (const gchar *realname)
 Finds a document whose real_path field matches the given filename. More...
 
gchar * document_get_basename_for_display (GeanyDocument *doc, gint length)
 Returns the last part of the filename of the given GeanyDocument. More...
 
GeanyDocumentdocument_get_current (void)
 Finds the current document. More...
 
GeanyDocumentdocument_get_from_page (guint page_num)
 Finds the document for the given notebook page page_num. More...
 
gint document_get_notebook_page (GeanyDocument *doc)
 Gets the notebook page index for a document. More...
 
const GdkColor * document_get_status_color (GeanyDocument *doc)
 Gets the status color of the document, or NULL if default widget coloring should be used. More...
 
GeanyDocumentdocument_index (gint idx)
 Accessor function for documents_array items. More...
 
GeanyDocumentdocument_new_file (const gchar *filename, GeanyFiletype *ft, const gchar *text)
 Creates a new document. More...
 
GeanyDocumentdocument_open_file (const gchar *locale_filename, gboolean readonly, GeanyFiletype *ft, const gchar *forced_enc)
 Opens a document specified by locale_filename. More...
 
void document_open_files (const GSList *filenames, gboolean readonly, GeanyFiletype *ft, const gchar *forced_enc)
 Opens each file in the list filenames. More...
 
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. More...
 
gboolean document_remove_page (guint page_num)
 Removes the given notebook tab at page_num and clears all related information in the document list. More...
 
void document_rename_file (GeanyDocument *doc, const gchar *new_filename)
 Renames the file in doc to new_filename. More...
 
gboolean document_save_file (GeanyDocument *doc, gboolean force)
 Saves the document. More...
 
gboolean document_save_file_as (GeanyDocument *doc, const gchar *utf8_fname)
 Saves the document, detecting the filetype. More...
 
void document_set_encoding (GeanyDocument *doc, const gchar *new_encoding)
 Sets the encoding of a document. More...
 
void document_set_filetype (GeanyDocument *doc, GeanyFiletype *type)
 Sets the filetype of the document (which controls syntax highlighting and tags) More...
 
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. More...
 

Variables

GPtrArray * documents_array
 Dynamic array of GeanyDocument pointers. More...
 

Detailed Description

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

Macro Definition 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)    ((doc_ptr) != NULL && (doc_ptr)->is_valid)

Null-safe way to check GeanyDocument::is_valid.

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.

Warning
Always check the returned document is valid (doc->is_valid).

Example:

See Also
documents_array().
#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 /* prevent outside 'else' matching our macro 'if' */
#define documents
Wraps documents_array so it can be used with C array syntax.
Definition: document.h:134
GPtrArray * documents_array
Dynamic array of GeanyDocument pointers.
Definition: document.c:100

Iterates all valid document indexes.

Use like a for statement.

Parameters
iguint index for documents_array.

Example:

guint i;
{
g_assert(doc->is_valid);
}

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
gint document_compare_by_display_name ( gconstpointer  a,
gconstpointer  b 
)

Compares documents by their display names.

This matches GCompareFunc for use with e.g. g_ptr_array_sort().

Note
'Display name' means the base name of the document's filename.
Parameters
aGeanyDocument**.
bGeanyDocument**.
Warning
The arguments take the address of each document pointer.
Returns
Negative value if a < b; zero if a = b; positive value if a > b.
Since
0.21
gint document_compare_by_tab_order ( gconstpointer  a,
gconstpointer  b 
)

Compares documents by their tab order.

This matches GCompareFunc for use with e.g. g_ptr_array_sort().

Parameters
aGeanyDocument**.
bGeanyDocument**.
Warning
The arguments take the address of each document pointer.
Returns
Negative value if a < b; zero if a = b; positive value if a > b.
Since
0.21 (GEANY_API_VERSION 209)
gint document_compare_by_tab_order_reverse ( gconstpointer  a,
gconstpointer  b 
)

Compares documents by their tab order, in reverse order.

This matches GCompareFunc for use with e.g. g_ptr_array_sort().

Parameters
aGeanyDocument**.
bGeanyDocument**.
Warning
The arguments take the address of each document pointer.
Returns
Negative value if a < b; zero if a = b; positive value if a > b.
Since
0.21 (GEANY_API_VERSION 209)
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 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.

Also shows the Save As dialog if necessary. If the file is not modified, this function may do nothing unless force is set to TRUE.

Saving may include replacing tabs with 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.

On successful saving:

  • GeanyDocument::real_path is set.
  • The filetype is set again or auto-detected if it wasn't set yet.
  • The "document-save" signal is emitted for plugins.
Warning
You should ensure doc->file_name has an absolute path unless you want the Save As dialog to be shown. A NULL value also shows the dialog. This behaviour was added in Geany 1.22.
Parameters
docThe document to save.
forceWhether to save the file even if it is not modified.
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.

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 may represent a different document later on, or may have been closed and become invalid.

Warning
You must check GeanyDocument::is_valid when iterating over this array. This is done automatically if you use the foreach_document() macro.
Note
Never assume that the order of document pointers is the same as the order of notebook tabs. One reason is that notebook tabs can be reordered. Use document_get_from_page() to lookup a document from a notebook tab number.
See Also
documents.