From 85b5e0e92104d921f161bac22349db7f1f89790a Mon Sep 17 00:00:00 2001 From: Yusuke Sato Date: Fri, 26 Nov 2010 10:15:08 +0900 Subject: [PATCH] Add function comments to bus/panelproxy.[ch]. BUG=none TEST=none Review URL: http://codereview.appspot.com/3293042 --- bus/panelproxy.c | 51 +++++++++++++++++++++++++++++++++++------------- bus/panelproxy.h | 2 ++ 2 files changed, 39 insertions(+), 14 deletions(-) diff --git a/bus/panelproxy.c b/bus/panelproxy.c index d976aea5..3b525642 100644 --- a/bus/panelproxy.c +++ b/bus/panelproxy.c @@ -23,6 +23,21 @@ #include "types.h" #include "marshalers.h" +/* panelproxy.c is a very simple proxy class for the panel component that does only the following: + * + * 1. Handle D-Bus signals from the panel process. For the list of the D-Bus signals, you can check the bus_panel_proxy_g_signal function, or + * introspection_xml in src/ibuspanelservice.c. The bus_panel_proxy_g_signal function simply emits a corresponding glib signal for each + * D-Bus signal. + * 2. Handle glib signals for a BusPanelProxy object (which is usually emitted by bus_panel_proxy_g_signal.) The list of such glib signals is + * in the bus_panel_proxy_class_init function. The signal handler function, e.g. bus_panel_proxy_candidate_clicked, simply calls the + * corresponding function in inputcontext.c, e.g. bus_input_context_candidate_clicked, using the current focused context. + * 3. Provide a way to call D-Bus methods in the panel process. For the list of the D-Bus methods, you can check the header file (panelproxy.h) + * or introspection_xml in src/ibuspanelservice.c. Functions that calls g_dbus_proxy_call, e.g. bus_panel_proxy_set_cursor_location, would + * fall into this category. + * 4. Handle glib signals for a BusInputContext object. The list of such glib signals is in the input_context_signals[] array. The signal handler + * function, e.g. _context_set_cursor_location_cb, simply invokes a D-Bus method by calling a function like bus_panel_proxy_set_cursor_location. + */ + enum { PAGE_UP, PAGE_DOWN, @@ -61,7 +76,6 @@ struct _BusPanelProxyClass { }; static guint panel_signals[LAST_SIGNAL] = { 0 }; -// static guint engine_signals[LAST_SIGNAL] = { 0 }; /* functions prototype */ static void bus_panel_proxy_init (BusPanelProxy *panel); @@ -95,10 +109,10 @@ bus_panel_proxy_new (BusConnection *connection) obj = g_initable_new (BUS_TYPE_PANEL_PROXY, NULL, NULL, - "g-object-path", IBUS_PATH_PANEL, - "g-interface-name", IBUS_INTERFACE_PANEL, - "g-connection", bus_connection_get_dbus_connection (connection), - NULL); + "g-object-path", IBUS_PATH_PANEL, + "g-interface-name", IBUS_INTERFACE_PANEL, + "g-connection", bus_connection_get_dbus_connection (connection), + NULL); return BUS_PANEL_PROXY (obj); } @@ -201,7 +215,7 @@ bus_panel_proxy_class_init (BusPanelProxyClass *class) static void bus_panel_proxy_init (BusPanelProxy *panel) { - panel->focused_context = NULL; + /* member variables will automatically be zero-cleared. */ } static void @@ -217,6 +231,11 @@ bus_panel_proxy_real_destroy (IBusProxy *proxy) IBUS_PROXY_CLASS(bus_panel_proxy_parent_class)->destroy ((IBusProxy *)panel); } +/** + * bus_panel_proxy_g_signal: + * + * Handle all D-Bus signals from the panel process. This function emits a corresponding glib signal for each D-Bus signal. + */ static void bus_panel_proxy_g_signal (GDBusProxy *proxy, const gchar *sender_name, @@ -225,6 +244,7 @@ bus_panel_proxy_g_signal (GDBusProxy *proxy, { BusPanelProxy *panel = (BusPanelProxy *)proxy; + /* The list of nullary D-Bus signals. */ static const struct { const gchar *signal_name; const guint signal_id; @@ -243,6 +263,7 @@ bus_panel_proxy_g_signal (GDBusProxy *proxy, } } + /* Handle D-Bus signals with parameters. Deserialize them and emit a glib signal. */ if (g_strcmp0 ("CandidateClicked", signal_name) == 0) { guint index = 0; guint button = 0; @@ -578,10 +599,10 @@ DEFINE_FUNCTION (state_changed) #undef DEFINE_FUNCTION -static const struct _SignalCallbackTable { +static const struct { gchar *name; GCallback callback; -} __signals[] = { +} input_context_signals[] = { { "set-cursor-location", G_CALLBACK (_context_set_cursor_location_cb) }, { "update-preedit-text", G_CALLBACK (_context_update_preedit_text_cb) }, @@ -607,7 +628,9 @@ static const struct _SignalCallbackTable { { "disabled", G_CALLBACK (_context_state_changed_cb) }, { "engine-changed", G_CALLBACK (_context_state_changed_cb) }, - // { "destroy", G_CALLBACK (_context_destroy_cb) }, + /* FIXME re-enable this if needed. + { "destroy", G_CALLBACK (_context_destroy_cb) }, + */ }; void @@ -636,10 +659,10 @@ bus_panel_proxy_focus_in (BusPanelProxy *panel, /* install signal handlers */ gint i; - for (i = 0; i < G_N_ELEMENTS (__signals); i++) { + for (i = 0; i < G_N_ELEMENTS (input_context_signals); i++) { g_signal_connect (context, - __signals[i].name, - __signals[i].callback, + input_context_signals[i].name, + input_context_signals[i].callback, panel); } } @@ -655,9 +678,9 @@ bus_panel_proxy_focus_out (BusPanelProxy *panel, /* uninstall signal handlers */ gint i; - for (i = 0; i < G_N_ELEMENTS (__signals); i++) { + for (i = 0; i < G_N_ELEMENTS (input_context_signals); i++) { g_signal_handlers_disconnect_by_func (context, - __signals[i].callback, + input_context_signals[i].callback, panel); } diff --git a/bus/panelproxy.h b/bus/panelproxy.h index 83d6ff1a..427e409f 100644 --- a/bus/panelproxy.h +++ b/bus/panelproxy.h @@ -51,6 +51,8 @@ typedef struct _BusPanelProxyClass BusPanelProxyClass; GType bus_panel_proxy_get_type (void); BusPanelProxy *bus_panel_proxy_new (BusConnection *connection); + +/* functions that invoke D-Bus methods of the panel component. */ void bus_panel_proxy_focus_in (BusPanelProxy *panel, BusInputContext *context); void bus_panel_proxy_focus_out (BusPanelProxy *panel,