From: Iñigo Martínez Date: Fri, 20 Apr 2007 07:08:14 +0000 (+0000) Subject: Developers documentation updated. X-Git-Tag: EVINCE_0_9_0~42 X-Git-Url: https://www.fi.muni.cz/~kas/git//home/kas/public_html/git/?a=commitdiff_plain;h=fb53dffc05b5bf6f767a6b33abf6eabb627e7644;p=evince.git Developers documentation updated. 2007-04-20 Iñigo Martínez * shell/ev-application.c: * shell/ev-job-queue.c: * shell/ev-metadata-manager.c: * shell/ev-stock-icons.c: * shell/ev-window.c: * shell/main.c: Developers documentation updated. svn path=/trunk/; revision=2410 --- diff --git a/ChangeLog b/ChangeLog index 9198d0dd..53390643 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2007-04-20 Iñigo Martínez + + * shell/ev-application.c: + * shell/ev-job-queue.c: + * shell/ev-metadata-manager.c: + * shell/ev-stock-icons.c: + * shell/ev-window.c: + * shell/main.c: + + Developers documentation updated. + 2007-04-19 Carlos Garcia Campos * shell/ev-window.c: (uri_is_valid), (launch_external_uri): diff --git a/shell/ev-application.c b/shell/ev-application.c index 53d284f1..2ce43c04 100644 --- a/shell/ev-application.c +++ b/shell/ev-application.c @@ -101,6 +101,13 @@ ev_application_register_service (EvApplication *application) } #endif /* ENABLE_DBUS */ +/** + * ev_application_get_instance: + * + * Checks for #EvApplication instance, if it doesn't exist it does create it. + * + * Returns: an instance of the #EvApplication data. + */ EvApplication * ev_application_get_instance (void) { @@ -161,6 +168,15 @@ init_session (EvApplication *application) G_CALLBACK (removed_from_session), application); } +/** + * ev_display_open_if_needed: + * @name: the name of the display to be open if it's needed. + * + * Search among all the open displays if any of them have the same name as the + * passed name. If the display isn't found it tries the open it. + * + * Returns: a #GdkDisplay of the display with the passed name. + */ static GdkDisplay * ev_display_open_if_needed (const gchar *name) { @@ -184,6 +200,17 @@ ev_display_open_if_needed (const gchar *name) return display != NULL ? display : gdk_display_open (name); } +/** + * get_screen_from_args: + * @args: a #GHashTable with data passed to the application. + * + * Looks for the screen in the display available in the hash table passed to the + * application. If the display isn't opened, it's opened and the #GdkScreen + * assigned to the screen in that display returned. + * + * Returns: the #GdkScreen assigned to the screen on the display indicated by + * the data on the #GHashTable. + */ static GdkScreen * get_screen_from_args (GHashTable *args) { @@ -212,6 +239,16 @@ get_screen_from_args (GHashTable *args) return screen; } +/** + * get_window_run_mode_from_args: + * @args: a #GHashTable with data passed to the application. + * + * It does look if the mode option has been passed from command line, using it + * as the window run mode, otherwise the run mode will be the normal mode. + * + * Returns: The window run mode passed from command line or + * EV_WINDOW_MODE_NORMAL in other case. + */ static EvWindowRunMode get_window_run_mode_from_args (GHashTable *args) { @@ -228,6 +265,16 @@ get_window_run_mode_from_args (GHashTable *args) return mode; } +/** + * get_destination_from_args: + * @args: a #GHashTable with data passed to the application. + * + * It does look for the page-label argument parsed from the command line and + * if it does exist, it returns an #EvLinkDest. + * + * Returns: An #EvLinkDest to page-label if it has been passed from the command + * line, NULL in other case. + */ static EvLinkDest * get_destination_from_args (GHashTable *args) { @@ -247,6 +294,16 @@ get_destination_from_args (GHashTable *args) return dest; } +/** + * get_unlink_temp_file_from_args: + * @args: a #GHashTable with data passed to the application. + * + * It does look if the unlink-temp-file option has been passed from the command + * line returning it's boolean representation, otherwise it does return %FALSE. + * + * Returns: the boolean representation of the unlink-temp-file value or %FALSE + * in other case. + */ static gboolean get_unlink_temp_file_from_args (GHashTable *args) { @@ -263,6 +320,19 @@ get_unlink_temp_file_from_args (GHashTable *args) return unlink_temp_file; } +/** + * ev_application_open_window: + * @application: The instance of the application. + * @args: A #GHashTable with the arguments data. + * @timestamp: Current time value. + * @error: The #GError facility. + * + * Creates a new window and if the args are available, it's not NULL, it gets + * the screen from them and assigns the just created window to it. At last it + * does show it. + * + * Returns: %TRUE. + */ gboolean ev_application_open_window (EvApplication *application, GHashTable *args, @@ -287,6 +357,16 @@ ev_application_open_window (EvApplication *application, return TRUE; } +/** + * ev_application_get_empty_window: + * @application: The instance of the application. + * @screen: The screen where the empty window will be search. + * + * It does look if there is any empty window in the indicated screen. + * + * Returns: The first empty #EvWindow in the passed #GdkScreen or NULL in other + * case. + */ static EvWindow * ev_application_get_empty_window (EvApplication *application, GdkScreen *screen) @@ -310,6 +390,18 @@ ev_application_get_empty_window (EvApplication *application, return empty_window; } +/** + * ev_application_get_uri_window: + * @application: The instance of the application. + * @uri: The uri to be opened. + * + * It looks in the list of the windows for the one with the document represented + * by the passed uri on it. If the window is empty or the document isn't present + * on any window, it will return NULL. + * + * Returns: The #EvWindow where the document represented by the passed uri is + * shown, NULL in other case. + */ static EvWindow * ev_application_get_uri_window (EvApplication *application, const char *uri) { @@ -336,6 +428,16 @@ ev_application_get_uri_window (EvApplication *application, const char *uri) return uri_window; } +/** + * ev_application_open_uri_at_dest: + * @application: The instance of the application. + * @uri: The uri to be opened. + * @screen: Thee screen where the link will be shown. + * @dest: The #EvLinkDest of the document. + * @mode: The run mode of the window. + * @unlink_temp_file: The unlink_temp_file option value. + * @timestamp: Current time value. + */ void ev_application_open_uri_at_dest (EvApplication *application, const char *uri, @@ -400,6 +502,14 @@ ev_application_open_uri_at_dest (EvApplication *application, timestamp); } +/** + * ev_application_open_uri: + * @application: The instance of the application. + * @uri: The uri to be opened + * @args: A #GHashTable with the arguments data. + * @timestamp: Current time value. + * @error: The #GError facility. + */ gboolean ev_application_open_uri (EvApplication *application, const char *uri, @@ -516,6 +626,14 @@ ev_application_init (EvApplication *ev_application) #endif /* HAVE_GTK_RECENT */ } +/** + * ev_application_get_windows: + * @application: The instance of the application. + * + * It creates a list of the top level windows. + * + * Returns: A #GList of the top level windows. + */ GList * ev_application_get_windows (EvApplication *application) { diff --git a/shell/ev-job-queue.c b/shell/ev-job-queue.c index d2733d6f..bd7b86c5 100644 --- a/shell/ev-job-queue.c +++ b/shell/ev-job-queue.c @@ -52,6 +52,14 @@ add_job_to_async_queue (GQueue *queue, EvJob *job) g_queue_push_tail (queue, job); } +/** + * add_job_to_queue_locked: + * @queue: a #GQueue where the #EvJob will be added. + * @job: an #EvJob to be added to the specified #GQueue. + * + * Add the #EvJob to the specified #GQueue and woke up the ev_render_thread who + * is waiting for render_cond. + */ static void add_job_to_queue_locked (GQueue *queue, EvJob *job) @@ -61,6 +69,14 @@ add_job_to_queue_locked (GQueue *queue, g_cond_broadcast (render_cond); } +/** + * notify_finished: + * @job: the object that signal will be reseted. + * + * It does emit the job finished signal and returns %FALSE. + * + * Returns: %FALSE. + */ static gboolean notify_finished (GObject *job) { @@ -69,6 +85,13 @@ notify_finished (GObject *job) return FALSE; } +/** + * job_finished_cb: + * @job: the #EvJob that has been handled. + * + * It does finish the job last work and look if there is any more job to be + * handled. + */ static void job_finished_cb (EvJob *job) { @@ -77,6 +100,14 @@ job_finished_cb (EvJob *job) ev_job_queue_run_next (); } +/** + * handle_job: + * @job: the #EvJob to be handled. + * + * First, it does check if the job is async and then it does attend it if + * possible giving a failed assertion otherwise. If the job isn't async it does + * attend it and notify that the job has been finished. + */ static void handle_job (EvJob *job) { @@ -114,6 +145,24 @@ handle_job (EvJob *job) } } +/** + * search_for_jobs_unlocked: + * + * Check if there is any job at the synchronized queues and return any existing + * job in them taking in account the next priority: + * + * render_queue_high > + * thumbnail_queue_high > + * render_queue_low > + * links_queue > + * load_queue > + * thumbnail_queue_low > + * fonts_queue > + * print_queue > + * + * Returns: an available #EvJob in the queues taking in account stablished queue + * priorities. + */ static EvJob * search_for_jobs_unlocked (void) { @@ -154,6 +203,15 @@ search_for_jobs_unlocked (void) return NULL; } +/** + * no_jobs_available_unlocked: + * + * Looks if there is any job at render, links, load, thumbnail. fonts and print + * queues. + * + * Returns: %TRUE if the render, links, load, thumbnail, fonts and print queues + * are empty, %FALSE in other case. + */ static gboolean no_jobs_available_unlocked (void) { @@ -168,6 +226,16 @@ no_jobs_available_unlocked (void) } /* the thread mainloop function */ +/** + * ev_render_thread: + * @data: data passed to the thread. + * + * The thread mainloop function. It does wait for any available job in synced + * queues to handle it. + * + * Returns: the return value of the thread, which will be returned by + * g_thread_join(). + */ static gpointer ev_render_thread (gpointer data) { @@ -192,6 +260,12 @@ ev_render_thread (gpointer data) } +/** + * ev_job_queue_run_next: + * + * It does look for any job on the render high priority queue first and after + * in the render low priority one, and then it does handle it. + */ static void ev_job_queue_run_next (void) { @@ -211,6 +285,12 @@ ev_job_queue_run_next (void) } /* Public Functions */ +/** + * ev_job_queue_init: + * + * Creates a new cond, new mutex, a thread for evince job handling and inits + * every queue. + */ void ev_job_queue_init (void) { diff --git a/shell/ev-metadata-manager.c b/shell/ev-metadata-manager.c index c3fc4226..0dba983e 100644 --- a/shell/ev-metadata-manager.c +++ b/shell/ev-metadata-manager.c @@ -72,6 +72,12 @@ static gboolean ev_metadata_manager_save (gpointer data); static EvMetadataManager *ev_metadata_manager = NULL; +/** + * item_free: + * @data: a pointer to a #Item data + * + * It does free the values on the #GHashTable where data points. + */ static void item_free (gpointer data) { @@ -87,6 +93,16 @@ item_free (gpointer data) g_free (item); } +/** + * ev_metadata_manager_init: + * + * Creates an EvMetadataManager with default values. + * + * values_loaded -> %FALSE. + * modified -> %FALSE. + * timeout_id -> the id of the event source. + * items -> a new full empty #GHashTable. + */ void ev_metadata_manager_init (void) { @@ -380,7 +396,7 @@ ev_metadata_manager_set_last (const gchar *key, } /** - * ev_metadata_manager_set: + * ev_metadata_manager_get: * @uri: Uri to set data for, if @NULL, we return default value * @key: Key to set uri * @value: GValue struct filled up with value diff --git a/shell/ev-stock-icons.c b/shell/ev-stock-icons.c index f2d059b9..799878dd 100644 --- a/shell/ev-stock-icons.c +++ b/shell/ev-stock-icons.c @@ -43,6 +43,11 @@ static const EvStockIcon stock_icons [] = { { EV_STOCK_ROTATE_RIGHT, "object-rotate-right"}, }; +/** + * ev_stock_icons_init: + * + * Creates a new icon factory, adding the base stock icons to it. + */ void ev_stock_icons_init (void) { diff --git a/shell/ev-window.c b/shell/ev-window.c index 4d76b6f2..532aa4e4 100644 --- a/shell/ev-window.c +++ b/shell/ev-window.c @@ -606,6 +606,16 @@ update_sizing_buttons (EvWindow *window) } } +/** + * ev_window_is_empty: + * @ev_window: The instance of the #EvWindow. + * + * It does look if there is any document loaded or if there is any job to load + * a document. + * + * Returns: %TRUE if there isn't any document loaded or any any documente to be + * loaded, %FALSE in other case. + */ gboolean ev_window_is_empty (const EvWindow *ev_window) { @@ -1340,12 +1350,27 @@ ev_window_load_job_cb (EvJobLoad *job, return; } +/** + * ev_window_get_uri: + * @ev_window: The instance of the #EvWindow. + * + * It returns the uri of the document showed in the #EvWindow. + * + * Returns: the uri of the document showed in the #EvWindow. + */ const char * ev_window_get_uri (EvWindow *ev_window) { return ev_window->priv->uri; } +/** + * ev_window_close_dialogs: + * @ev_window: The window where dialogs will be closed. + * + * It looks for password, print and properties dialogs and closes them and + * frees them from memory. If there is any print job it does free it too. + */ static void ev_window_close_dialogs (EvWindow *ev_window) { @@ -5187,6 +5212,13 @@ ev_window_init (EvWindow *ev_window) ev_window_setup_action_sensitivity (ev_window); } +/** + * ev_window_new: + * + * Creates a #GtkWidget that represents the window. + * + * Returns: the #GtkWidget that represents the window. + */ GtkWidget * ev_window_new (void) { diff --git a/shell/main.c b/shell/main.c index 3abe4cd2..932e3279 100644 --- a/shell/main.c +++ b/shell/main.c @@ -66,6 +66,24 @@ value_free (GValue *value) g_free (value); } +/** + * arguments_parse: + * + * Parses the arguments and creates a #GHashTable with this data. + * + * key -> value + * + * dislay -> display at the default screen. + * screen -> screen number. + * page-label -> only if the page label argument has been passed, + * the page of the document to display. + * mode -> only if the view mode is one of the availables, + * the view mode. + * unlink-temp-file -> only if the view mode is preview mode and + * unlink-temp-file has been passed, unlink-temp-file. + * + * Returns: a pointer into #GHashTable with data from the arguments. + */ static GHashTable * arguments_parse (void) {