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 GeanyData::documents_array so it can be used with C array syntax. More...
#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.

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...
GeanyDocument *	document_find_by_filename (const gchar *utf8_filename)
	Finds a document with the given filename. More...
GeanyDocument *	document_find_by_id (guint id)
	Lookup an old document by its ID. More...
GeanyDocument *	document_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...
GeanyDocument *	document_get_current (void)
	Finds the current document. More...
GeanyDocument *	document_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...
GeanyDocument *	document_index (gint idx)
	Accessor function for GeanyData::documents_array items. More...
GeanyDocument *	document_new_file (const gchar *filename, GeanyFiletype *ft, const gchar *text)
	Creates a new document. More...
GeanyDocument *	document_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_force (GeanyDocument *doc, const gchar *forced_enc)
	Reloads the document with the specified 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...

Detailed Description

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

Macro Definition Documentation

DOC_FILENAME

#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.

DOC_VALID

#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.

documents

#define documents   ((GeanyDocument **)GEANY(documents_array)->pdata)

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

Warning

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

Example:

GeanyDocument *doc = documents[i]; 

See also

documents_array().

foreach_document

#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' */

Iterates all valid document indexes.

Use like a for statement.

Parameters

i	guint index for GeanyData::documents_array.

Example:

guint i;
foreach_document(i)
{
    GeanyDocument *doc = documents[i];
    g_assert(doc->is_valid);
}

Function Documentation

document_close()

gboolean document_close

(

GeanyDocument *

doc

)

Closes the given document.

Parameters

doc	The document to remove.

Returns

TRUE if the document was actually removed or FALSE otherwise.

Since

0.15

document_compare_by_display_name()

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

a	GeanyDocument**.
b	GeanyDocument**.

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

document_compare_by_tab_order()

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

a	GeanyDocument**.
b	GeanyDocument**.

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)

document_compare_by_tab_order_reverse()

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

a	GeanyDocument**.
b	GeanyDocument**.

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)

document_find_by_filename()

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_filename

The filename to search (in UTF-8 encoding).

Returns

(transfer: none) The matching document, or NULL.

See also

document_find_by_real_path().

document_find_by_id()

GeanyDocument * document_find_by_id

(

guint

id

)

Lookup an old document by its ID.

Useful when the corresponding document may have been closed since the ID was retrieved.

Parameters

id	The ID of the document to find

Returns

(transfer: none) NULL if the document is no longer open.

Example:

static guint id;
GeanyDocument *doc = ...;
id = doc->id;   // store ID
...
// time passes - the document may have been closed by now
GeanyDocument *doc = document_find_by_id(id);
gboolean still_open = (doc != NULL);

Since

1.25.

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

realname

The filename to search, which should be identical to the string returned by utils_get_real_path().

Returns

(transfer: none) The matching document, or NULL.

Note

This is only really useful when passing a TMSourceFile::file_name.

See also

GeanyDocument::real_path.

document_find_by_filename().

Since

0.15

document_get_basename_for_display()

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

doc	The document to use.
length	The 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

document_get_current()

GeanyDocument * document_get_current

(

void

)

Finds the current document.

Returns

(transfer: none) A pointer to the current document or NULL if there are no opened documents.

document_get_from_page()

GeanyDocument * document_get_from_page

(

guint

page_num

)

Finds the document for the given notebook page page_num.

Parameters

page_num

The notebook page number to search.

Returns

(transfer: none) The corresponding document for the given notebook page, or NULL.

document_get_notebook_page()

gint document_get_notebook_page

(

GeanyDocument *

doc

)

Gets the notebook page index for a document.

Parameters

doc	The document.

Returns

The index.

Since

0.19

document_get_status_color()

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

doc	The 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

document_index()

GeanyDocument * document_index

(

gint

idx

)

Accessor function for GeanyData::documents_array items.

Warning

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

Parameters

idx	GeanyData::documents_array index.

Returns

(transfer: none) The document, or NULL if idx is out of range.

Since

0.16

document_new_file()

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_filename	The file name in UTF-8 encoding, or NULL to open a file as "untitled".
ft	The filetype to set or NULL to detect it from filename if not NULL.
text	The initial content of the file (in UTF-8 encoding), or NULL.

Returns

(transfer: none) The new document.

document_open_file()

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_filename	The filename of the document to load, in locale encoding.
readonly	Whether to open the document in read-only mode.
ft	The filetype for the document or NULL to auto-detect the filetype.
forced_enc	The file encoding to use or NULL to auto-detect the file encoding.

Returns

(transfer: none) The document opened or NULL.

document_open_files()

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

filenames	(element-type: filename) A list of filenames to load, in locale encoding.
readonly	Whether to open the document in read-only mode.
ft	The filetype for the document or NULL to auto-detect the filetype.
forced_enc	The file encoding to use or NULL to auto-detect the file encoding.

document_reload_force()

gboolean document_reload_force	(	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

doc	The document to reload.
forced_enc	The file encoding to use or NULL to auto-detect the file encoding.

Returns

TRUE if the document was actually reloaded or FALSE otherwise.

document_remove_page()

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_num

The notebook page number to remove.

Returns

TRUE if the document was actually removed or FALSE otherwise.

document_rename_file()

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

doc	The current document which should be renamed.
new_filename	The new filename in UTF-8 encoding.

Since

0.16

document_save_file()

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

doc	The document to save.
force	Whether 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.

document_save_file_as()

gboolean document_save_file_as	(	GeanyDocument *	doc,
		const gchar *	utf8_fname
	)

Saves the document, detecting the filetype.

Parameters

doc	The document for the file to save.
utf8_fname	The 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

document_set_encoding()

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

doc	The document to use.
new_encoding	The encoding to be set for the document.

document_set_filetype()

void document_set_filetype	(	GeanyDocument *	doc,
		GeanyFiletype *	type
	)

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

Parameters

doc	The document to use.
type	The filetype.

document_set_text_changed()

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

doc	The document to use.
changed	Whether the document state should indicate changes have been made.