Merge documentation into the master branch to add lots of documentation

svn path=/trunk/; revision=3595
parent 7da14090
2008-07-29 Ignacio Casal Quinteiro <nacho.resa@gmail.com>
* src/application.c:
* src/message-table.c:
* src/msg.c:
* src/notebook.c:
* src/po.c:
* src/statusbar.c:
* src/statusbar.h:
* src/tab.c:
* src/utils.c:
* src/view.c:
* src/window.c:
Added documentation and updated the old one.
2008-07-29 Ignacio Casal Quinteiro <nacho.resa@gmail.com>
* plugins/insert-tags/insert-tags-plugin.c:
......
2008-07-29 Ignacio Casal Quinteiro <nacho.resa@gmail.com>
<<<<<<< HEAD:src/ChangeLog
=======
* statusbar.c:
Fixed access to statusbar object.
2008-07-29 Ignacio Casal Quinteiro <nacho.resa@gmail.com>
>>>>>>> documentation:src/ChangeLog
* draw-spaces.c:
Improved \n symbol and added RTL support.
......
......@@ -231,6 +231,13 @@ app_weak_notify (gpointer data,
gtk_main_quit ();
}
/**
* gtranslator_application_get_default:
*
* Returns the default instance of the application.
*
* Returns: the default instance of the application.
*/
GtranslatorApplication *
gtranslator_application_get_default (void)
{
......@@ -247,6 +254,14 @@ gtranslator_application_get_default (void)
return instance;
}
/**
* gtranslator_application_open_window:
* @app: a #GtranslatorApplication
*
* Creates a new #GtranslatorWindow and shows it.
*
* Returns: the #GtranslatorWindow to be opened
*/
GtranslatorWindow *
gtranslator_application_open_window (GtranslatorApplication *app)
{
......@@ -282,13 +297,26 @@ gtranslator_application_open_window (GtranslatorApplication *app)
return window;
}
/**
* _gtranslator_application_get_toolbars_model:
* @application: a #GtranslatorApplication
*
* Returns the toolbar model.
*
* Retuns: the toolbar model.
*/
GObject *
_gtranslator_application_get_toolbars_model (GtranslatorApplication *application)
{
return G_OBJECT (application->priv->toolbars_model);
}
/**
* _gtranslator_application_save_toolbars_model:
* @application: a #GtranslatorApplication
*
* Saves the toolbar model.
*/
void
_gtranslator_application_save_toolbars_model (GtranslatorApplication *application)
{
......@@ -296,6 +324,12 @@ _gtranslator_application_save_toolbars_model (GtranslatorApplication *applicatio
application->priv->toolbars_file, "1.0");
}
/**
* gtranslator_application_shutdown:
* @app: a #GtranslatorApplication
*
* Shutdowns the application.
*/
void
gtranslator_application_shutdown(GtranslatorApplication *app)
{
......@@ -366,6 +400,14 @@ gtranslator_application_get_windows (GtranslatorApplication *app)
return app->priv->windows;
}
/**
* gtranslator_application_register_icon:
* @app: a #GtranslatorApplication
* @icon: the name of the icon
* @stock_id: the stock id for the new icon
*
* Registers a new @icon with the @stock_id.
*/
void
gtranslator_application_register_icon (GtranslatorApplication *app,
const gchar *icon,
......
......@@ -384,6 +384,14 @@ gtranslator_message_table_class_init (GtranslatorMessageTableClass *klass)
object_class->finalize = gtranslator_message_table_finalize;
}
/**
* gtranslator_message_table_new:
* @tab: a #GtranslatorTab
*
* Creates a new #GtranslatorMessageTable object.
*
* Returns: the newly created #GtranslatorMessageTable
*/
GtkWidget *
gtranslator_message_table_new (GtkWidget *tab)
{
......@@ -401,6 +409,14 @@ gtranslator_message_table_new (GtkWidget *tab)
return GTK_WIDGET(obj);
}
/**
* gtranslator_message_table_populate:
* @table: a #GtranslatorMessageTable
* @messages: a list of #GtranslatorMsg
*
* Populates the #GtranslatorMessageTable with the list of #GtranslatorMsg and
* sort them.
*/
void
gtranslator_message_table_populate(GtranslatorMessageTable *table,
GList *messages)
......
......@@ -78,6 +78,8 @@ gtranslator_msg_class_init (GtranslatorMsgClass *klass)
/**
* gtranslator_msg_new:
*
* Creates a new #GtranslatorMsg.
*
* Return value: a new #GtranslatorMsg object
**/
GtranslatorMsg *
......@@ -121,8 +123,9 @@ gtranslator_msg_set_message(GtranslatorMsg *msg,
* gtranslator_msg_get_row_reference:
* @msg: a #GtranslatorMsg
*
* Return value: the GtkTreeRowReference corresponding to the message's place in the message table
**/
* Returns: the #GtkTreeRowReference corresponding to the message's place
* in the message table
*/
GtkTreeRowReference *
gtranslator_msg_get_row_reference(GtranslatorMsg *msg)
{
......
......@@ -195,6 +195,11 @@ gtranslator_notebook_init (GtranslatorNotebook *notebook)
static void
gtranslator_notebook_finalize (GObject *object)
{
GtranslatorNotebook *notebook = GTR_NOTEBOOK (object);
if (notebook->priv->pages)
g_list_free (notebook->priv->pages);
G_OBJECT_CLASS (gtranslator_notebook_parent_class)->finalize (object);
}
......@@ -221,12 +226,26 @@ gtranslator_notebook_class_init (GtranslatorNotebookClass *klass)
/***************************** Public funcs ***********************************/
/**
* gtranslator_notebook_new:
*
* Creates a new #GtranslatorNotebook.
*
* Returns: a new #GtranslatorNotebook object
*/
GtkWidget *
gtranslator_notebook_new()
{
return GTK_WIDGET(g_object_new(GTR_TYPE_NOTEBOOK, NULL));
}
/**
* gtranslator_notebook_add_page:
* @notebook: a #GtranslatorNotebook
* @tab: a #GtranslatorTab
*
* Adds a new #GtranslatorTab to @notebook.
*/
void
gtranslator_notebook_add_page (GtranslatorNotebook *notebook,
GtranslatorTab *tab)
......@@ -255,6 +274,14 @@ gtranslator_notebook_add_page (GtranslatorNotebook *notebook,
priv->pages = g_list_append (priv->pages, tab);
}
/**
* gtranslator_notebook_get_page:
* @notebook: a #GtranslatorNotebook
*
* Gets the selected page in the #GtranslatorNotebook.
*
* Returns: the selected page in the @notebook
*/
GtranslatorTab *
gtranslator_notebook_get_page(GtranslatorNotebook *notebook)
{
......
......@@ -259,7 +259,9 @@ on_gettext_po_xerror2(gint severity,
/**
* gtranslator_po_new:
*
* Return value: a new #GtranslatorPo object
* Creates a new #GtranslatorPo.
*
* Returns: a new #GtranslatorPo object
**/
GtranslatorPo *
gtranslator_po_new(void)
......@@ -277,7 +279,8 @@ gtranslator_po_new(void)
* @filename: the filename path to open
* @error: a variable to store the errors
*
*
* Parses all things related to the #GtranslatorPo and initilizes all neccessary
* variables.
**/
void
gtranslator_po_parse(GtranslatorPo *po,
......@@ -692,7 +695,9 @@ gtranslator_po_save_file(GtranslatorPo *po,
* gtranslator_po_get_filename:
* @po: a #GtranslatorPo
*
* Return value: the file name string
* Gets the path of the po file.
*
* Returns: the file name string
**/
const gchar *
gtranslator_po_get_filename(GtranslatorPo *po)
......
......@@ -39,6 +39,9 @@ struct _GtranslatorStatusbarPrivate
GtkWidget *overwrite_mode_label;
/* default context data */
guint default_context_id;
/* tmp flash timeout data */
guint flash_timeout;
guint flash_context_id;
......@@ -83,6 +86,8 @@ gtranslator_statusbar_init (GtranslatorStatusbar *statusbar)
gtk_widget_show (statusbar->priv->statusbar);
gtk_box_pack_end (GTK_BOX (statusbar), statusbar->priv->statusbar,
TRUE, TRUE, 0);
statusbar->priv->default_context_id = gtk_statusbar_get_context_id (GTK_STATUSBAR (statusbar->priv->statusbar),
"default-context-id");
/*
* Progress bar
......@@ -129,6 +134,48 @@ gtranslator_statusbar_new (void)
return GTK_WIDGET (g_object_new (GTR_TYPE_STATUSBAR, NULL));
}
/**
* gtranslator_statusbar_push_default:
* @statusbar: a #GtranslatorStatusbar
* @text: the text to push in the statusbar
*
* Pushes a text onto the statusbar in the default context id.
*/
void
gtranslator_statusbar_push_default (GtranslatorStatusbar *statusbar,
const gchar *text)
{
g_return_if_fail (GTR_IS_STATUSBAR (statusbar));
gtk_statusbar_push (GTK_STATUSBAR (statusbar->priv->statusbar),
statusbar->priv->default_context_id, text);
}
/**
* gtranslator_statusbar_pop_default:
* @statusbar: a #GtranslatorStatusbar
*
* Pops the text in the statusbar of the default context id.
*/
void
gtranslator_statusbar_pop_default (GtranslatorStatusbar *statusbar)
{
g_return_if_fail (GTR_IS_STATUSBAR (statusbar));
gtk_statusbar_pop (GTK_STATUSBAR (statusbar->priv->statusbar),
statusbar->priv->default_context_id);
}
/**
* gtranslator_statusbar_push:
* @statusbar: a #GtranslatorStatusbar
* @context_id: the message's context id, as returned by gtk_statusbar_get_context_id()
* @text: the text to push in the statusbar
*
* Pushes a new message onto a statusbar's stack.
*
* Returns: a message id that can be used with gtk_statusbar_remove()
*/
guint
gtranslator_statusbar_push (GtranslatorStatusbar *statusbar,
guint context_id,
......@@ -140,6 +187,13 @@ gtranslator_statusbar_push (GtranslatorStatusbar *statusbar,
context_id, text);
}
/**
* gtranslator_statusbar_pop:
* @statusbar: a #GtranslatorStatusbar
* @context_id: a context identifier
*
* Removes the first message in the GtkStatusBar's stack with the given context id.
*/
void
gtranslator_statusbar_pop (GtranslatorStatusbar *statusbar,
guint context_id)
......@@ -168,6 +222,12 @@ gtranslator_statusbar_set_overwrite (GtranslatorStatusbar *statusbar,
else gtk_label_set_text(GTK_LABEL(statusbar->priv->overwrite_mode_label), _("INS"));
}
/**
* gtranslator_statusbar_clear_overwrite:
* @statusbar: a #GtranslatorStatusbar
*
* Clears the statusbar overwrite label.
*/
void
gtranslator_statusbar_clear_overwrite (GtranslatorStatusbar *statusbar)
{
......@@ -218,7 +278,7 @@ gtranslator_statusbar_flash_message (GtranslatorStatusbar *statusbar,
g_source_remove (statusbar->priv->flash_timeout);
statusbar->priv->flash_timeout = 0;
gtk_statusbar_remove (GTK_STATUSBAR (statusbar),
gtk_statusbar_remove (GTK_STATUSBAR (statusbar->priv->statusbar),
statusbar->priv->flash_context_id,
statusbar->priv->flash_message_id);
}
......@@ -235,8 +295,13 @@ gtranslator_statusbar_flash_message (GtranslatorStatusbar *statusbar,
g_free (msg);
}
/*
* Update the progress bar
/**
* gtranslator_statusbar_update_progress_bar:
* @statusbar: a #GtranslatorStatusbar
* @translated_count: the number of translated messages
* @messages_count: the number of messages
*
* Updates the state of the progress bar with the given values.
*/
void
gtranslator_statusbar_update_progress_bar (GtranslatorStatusbar *statusbar,
......
......@@ -53,6 +53,11 @@ GType gtranslator_statusbar_get_type (void) G_GNUC_CONST;
GtkWidget *gtranslator_statusbar_new (void);
void gtranslator_statusbar_push_default (GtranslatorStatusbar *statusbar,
const gchar *text);
void gtranslator_statusbar_pop_default (GtranslatorStatusbar *statusbar);
guint gtranslator_statusbar_push (GtranslatorStatusbar *statusbar,
guint context_id,
const gchar *text);
......
......@@ -584,6 +584,8 @@ gtranslator_tab_class_init (GtranslatorTabClass *klass)
* gtranslator_tab_new:
* @po: a #GtranslatorPo
*
* Creates a new #GtranslatorTab.
*
* Return value: a new #GtranslatorTab object
**/
GtranslatorTab *
......@@ -806,12 +808,28 @@ gtranslator_tab_message_go_to(GtranslatorTab *tab,
}
/**
* _gtranslator_tab_can_close:
* @tab: a #GtranslatorTab
*
* Whether a #GtranslatorTab can be closed.
*
* Returns: TRUE if the #GtranslatorPo of the @tab is already saved
*/
gboolean
_gtranslator_tab_can_close (GtranslatorTab *tab)
{
return gtranslator_po_get_state (tab->priv->po) == GTR_PO_STATE_SAVED;
}
/**
* gtranslator_tab_get_from_document:
* @po: a #GtranslatorPo
*
* Returns the #GtranslatorTab for a specific #GtranslatorPo.
*
* Returns: the #GtranslatorTab for a specific #GtranslatorPo
*/
GtranslatorTab *
gtranslator_tab_get_from_document (GtranslatorPo *po)
{
......
......@@ -174,6 +174,15 @@ gtranslator_xml_open_file (const gchar *filename)
return doc;
}
/**
* gtranslator_gtk_button_new_with_stock_icon:
* @label: the label of the button
* @stock_id: the id of the stock image
*
* Convenience function to create a #GtkButton with a stock image.
*
* Returns: a new #GtkButton
*/
GtkWidget *
gtranslator_gtk_button_new_with_stock_icon (const gchar *label,
const gchar *stock_id)
......@@ -188,12 +197,22 @@ gtranslator_gtk_button_new_with_stock_icon (const gchar *label,
return button;
}
/**
* gtranslator_utils_menu_position_under_widget:
* @menu: a #GtkMenu
* @x: the x position of the widget
* @y: the y position of the widget
* @push_in:
* @user_data: the widget to get the position
*
* It returns the position to popup a menu in a specific widget.
*/
void
gtranslator_utils_menu_position_under_widget (GtkMenu *menu,
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data)
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data)
{
GtkWidget *w = GTK_WIDGET (user_data);
GtkRequisition requisition;
......@@ -215,12 +234,22 @@ gtranslator_utils_menu_position_under_widget (GtkMenu *menu,
*push_in = TRUE;
}
/**
* gtranslator_utils_menu_position_under_widget:
* @menu: a #GtkMenu
* @x: the x position of the widget
* @y: the y position of the widget
* @push_in:
* @user_data: the widget to get the position
*
* It returns the position to popup a menu in a TreeView.
*/
void
gtranslator_utils_menu_position_under_tree_view (GtkMenu *menu,
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data)
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data)
{
GtkTreeView *tree = GTK_TREE_VIEW (user_data);
GtkTreeModel *model;
......@@ -279,7 +308,7 @@ gtranslator_utils_menu_position_under_tree_view (GtkMenu *menu,
* of error it returns FALSE and sets error_widget to a GtkLabel containing
* the error message to display.
*
* Returns FALSE if an error occurs, TRUE on success.
* Returns: FALSE if an error occurs, TRUE on success.
*/
gboolean
gtranslator_utils_get_glade_widgets (const gchar *filename,
......@@ -433,7 +462,6 @@ gtranslator_utils_is_valid_uri (const gchar *uri)
/**
* gtranslator_utils_drop_get_uris:
* @selection_data: the #GtkSelectionData from drag_data_received
* @info: the info from drag_data_received
*
* Create a list of valid uri's from a uri-list drop.
*
......@@ -640,11 +668,20 @@ finally_2:
return ret;
}
/**
* gtranslator_utils_activate_url:
* @dialog: a #GtkAboutDialog
* @url: the url to show
* @data: useless data variable
*
* Shows the corresponding @url in the default browser.
*/
void
gtranslator_utils_activate_url (GtkAboutDialog *dialog,
const gchar *url,
gpointer data)
{
//FIXME: gtk_url_show deprecates this func.
gchar *open[3];
if (g_find_program_in_path ("xdg-open"))
......@@ -665,6 +702,14 @@ gtranslator_utils_activate_url (GtkAboutDialog *dialog,
NULL, NULL, NULL);
}
/**
* gtranslator_utils_help_display:
* @parent: a #GtkWindow
* @doc_id: the name of the type of doc
* @file_name: the name of the doc
*
* Shows the help for an specific document in the default help browser.
*/
void
gtranslator_utils_help_display (GtkWindow *parent,
const gchar *doc_id,
......@@ -730,6 +775,13 @@ gtranslator_utils_help_display (GtkWindow *parent,
g_free (command);
}
/**
* gtranslator_utils_get_user_config_dir:
*
* Returns the default config dir for gtranslator.
*
* Returns: the config dir for gtranslator.
*/
gchar *
gtranslator_utils_get_user_config_dir (void)
{
......
......@@ -194,17 +194,32 @@ gtranslator_view_class_init (GtranslatorViewClass *klass)
object_class->finalize = gtranslator_view_finalize;
}
/**
* gtranslator_view_new:
*
* Creates a new #GtranslatorView. An empty default buffer will be created for you.
*
* Returns: a new #GtranslatorView
*/
GtkWidget *
gtranslator_view_new (void)
{
GtkWidget *view;
view = GTK_WIDGET (g_object_new (GTR_TYPE_VIEW, NULL));
gtk_widget_show_all(view);
return view;
}
/**
* gtranslator_view_get_selected_text:
* @view: a #GtranslatorView
* @selected_text: it stores the text selected in the #GtranslatorView
* @len: it stores the length of the @selected_text
*
* Gets the selected text region of the #GtranslatorView
*
* Returns: TRUE if the @selected_text was got correctly.
*/
gboolean
gtranslator_view_get_selected_text (GtranslatorView *view,
gchar **selected_text,
......@@ -300,6 +315,13 @@ gtranslator_view_enable_visible_whitespace(GtranslatorView *view,
gtk_widget_queue_draw (GTK_WIDGET (view));
}
/**
* gtranslator_view_cut_clipboard:
* @view: a #GtranslatorView
*
* Copies the currently-selected text to a clipboard,
* then deletes said text if it's editable.
*/
void
gtranslator_view_cut_clipboard (GtranslatorView *view)
{
......@@ -328,6 +350,12 @@ gtranslator_view_cut_clipboard (GtranslatorView *view)
0.0);
}
/**
* gtranslator_view_copy_clipboard:
* @view: a #GtranslatorView
*
* Copies the currently-selected text to a clipboard.
*/
void
gtranslator_view_copy_clipboard (GtranslatorView *view)
{
......@@ -347,6 +375,13 @@ gtranslator_view_copy_clipboard (GtranslatorView *view)
/* on copy do not scroll, we are already on screen */
}
/**
* gtranslator_view_cut_clipboard:
* @view: a #GtranslatorView
*
* Pastes the contents of a clipboard at the insertion point,
* or at override_location.
*/
void
gtranslator_view_paste_clipboard (GtranslatorView *view)
{
......@@ -407,8 +442,13 @@ gtranslator_view_set_font (GtranslatorView *view,
}
/*
* Search funcs
/**
* gtranslator_view_set_search_text:
* @view: a #GtranslatorView
* @text: the text to set for searching
* @flags: a #GtranslatorSearchFlags
*
* Stores the text to search for in the @view with some specific @flags.
*/
void
gtranslator_view_set_search_text (GtranslatorView *view,
......@@ -474,9 +514,19 @@ gtranslator_view_set_search_text (GtranslatorView *view,
g_object_notify (G_OBJECT (doc), "can-search-again");
}
/**
* gtranslator_view_get_search_text:
* @view: a #GtranslatorView
* @flags: the #GtranslatorSearchFlags of the stored text.
*
* Returns the text to search for it and the #GtranslatorSearchFlags of that
* text.
*
* Returns: the text to search for it.
*/
gchar *
gtranslator_view_get_search_text (GtranslatorView *view,
guint *flags)
guint *flags)
{
g_return_val_if_fail (GTR_IS_VIEW (view), NULL);
......@@ -486,6 +536,12 @@ gtranslator_view_get_search_text (GtranslatorView *view,
return gtranslator_utils_escape_search_text (view->priv->search_text);
}
/**
* gtranslator_view_get_can_search_again:
* @view: a #GtranslatorView
*
* Returns: TRUE if it can search again
*/
gboolean
gtranslator_view_get_can_search_again (GtranslatorView *view)
{
......@@ -495,8 +551,24 @@ gtranslator_view_get_can_search_again (GtranslatorView *view)
(*view->priv->search_text != '\0'));
}
/**
* gtranslator_view_search_forward:
* @view: a #GtranslatorView
* @start: start of search
* @end: bound for the search, or %NULL for the end of the buffer
* @match_start: return location for start of match, or %NULL
* @match_end: return location for end of match, or %NULL
*
* Searches forward for str. Any match is returned by setting match_start to the
* first character of the match and match_end to the first character after the match.
* The search will not continue past limit.
* Note that a search is a linear or O(n) operation, so you may wish to use limit
* to avoid locking up your UI on large buffers.
*
* Returns: whether a match was found
*/
gboolean
gtranslator_view_search_forward (GtranslatorView *view,
gtranslator_view_search_forward (GtranslatorView *view,
const GtkTextIter *start,
const GtkTextIter *end,
GtkTextIter *match_start,
......@@ -567,9 +639,25 @@ gtranslator_view_search_forward (GtranslatorView *view,
return found;
}
/**
* gtranslator_view_search_backward:
* @view: a #GtranslatorView
* @start: start of search
* @end: bound for the search, or %NULL for the end of the buffer
* @match_start: return location for start of match, or %NULL
* @match_end: return location for end of match, or %NULL
*
* Searches backward for str. Any match is returned by setting match_start to the
* first character of the match and match_end to the first character after the match.
* The search will not continue past limit.
* Note that a search is a linear or O(n) operation, so you may wish to use limit
* to avoid locking up your UI on large buffers.
*
* Returns: whether a match was found
*/
gboolean
gtranslator_view_search_backward (GtranslatorView *view,
gtranslator_view_search_backward (GtranslatorView *view,
const GtkTextIter *start,
const GtkTextIter *end,
GtkTextIter *match_start,
......@@ -641,6 +729,18 @@ gtranslator_view_search_backward (GtranslatorView *view,
return found;
}
/**
* gtranslator_view_replace_all:
* @view: a #GtranslatorView
* @find: the text to find
* @replace: the text to replace @find
* @flags: a #GtranslatorSearchFlags
*
* Replaces all matches of @find with @replace and returns the number of
* replacements.
*
* Returns: the number of replacements made it.
*/
gint
gtranslator_view_replace_all (GtranslatorView *view,
const gchar *find,
......
......@@ -1516,6 +1516,16 @@ gtranslator_window_class_init (GtranslatorWindowClass *klass)
/***************************** Public funcs ***********************************/
/**
* gtranslator_window_create_tab:
* @window: a #GtranslatorWindow
* @po: a #GtranslatorPo
*
* Adds a new #GtranslatorTab to the #GtranslatorNotebook and returns the
* #GtranslatorTab.
*
* Returns: a new #GtranslatorTab object
*/
GtranslatorTab *
gtranslator_window_create_tab(GtranslatorWindow *window,
GtranslatorPo *po)
......@@ -1530,12 +1540,28 @@ gtranslator_window_create_tab(GtranslatorWindow *window,
return tab;
}
/**
* gtranslator_window_get_active_tab:
* @window: a #GtranslatorWindow
*
* Gets the active #GtranslatorTab of the @window.
*
* Returns: the active #GtranslatorTab of the @window.
*/
GtranslatorTab *
gtranslator_window_get_active_tab(GtranslatorWindow *window)
{
return gtranslator_notebook_get_page(GTR_NOTEBOOK(window->priv->notebook));
}