From d280bf1ca676581593ddd0ad5e912e7a15a8733d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Mo=C5=84?= Date: Tue, 10 Mar 2009 19:45:16 +0100 Subject: [PATCH] add some comments --- gui.c | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- preset.c | 26 ++++++-- 2 files changed, 216 insertions(+), 6 deletions(-) diff --git a/gui.c b/gui.c index 5f2120b..6f188d4 100644 --- a/gui.c +++ b/gui.c @@ -35,10 +35,17 @@ typedef struct { gint x; /* combo box item number */ } WidgetListElem; -static GtkKnobAnim *knob_anim = NULL; +static GtkKnobAnim *knob_anim = NULL; /* animation used by knobs */ static GList *widget_list = NULL; /* this list contains WidgetListElem data elements */ -static gboolean allow_send = FALSE; +static gboolean allow_send = FALSE; /* if FALSE GUI parameter changes won't be sent to device */ +/** + * show_error_message: + * @parent: transient parent, or NULL for none + * @message: error description + * + * Shows error message dialog. + **/ void show_error_message(GtkWidget *parent, gchar *message) { g_return_if_fail(message != NULL); @@ -53,6 +60,13 @@ void show_error_message(GtkWidget *parent, gchar *message) gtk_widget_destroy(msg); } +/** + * value_changed_option_cb: + * @adj: the object which emitted the signal + * @setting: setting controlled by adj + * + * Sets effect value. + **/ void value_changed_option_cb(GtkAdjustment *adj, EffectSettings *setting) { g_return_if_fail(setting != NULL); @@ -78,6 +92,13 @@ void value_changed_option_cb(GtkAdjustment *adj, EffectSettings *setting) } } +/** + * toggled_cb: + * @button: the object which emitted the signal + * @effect: effect controlled by button + * + * Turns effect on/off basing on state of button. + **/ void toggled_cb(GtkToggleButton *button, Effect *effect) { g_return_if_fail(effect != NULL); @@ -88,6 +109,16 @@ void toggled_cb(GtkToggleButton *button, Effect *effect) } } +/** + * widget_list_add: + * @widget: GtkObject to add to widget list + * @id: object controlled ID + * @position: object controlled position + * @value: effect value type (if widget is GtkComboBox, otherwise -1) + * @x: combo box item number (if widget is GtkComboBox, otherwise -1) + * + * Adds widget to widget list. + **/ static void widget_list_add(GtkObject *widget, gint id, gint position, gint value, gint x) { WidgetListElem *el; @@ -102,6 +133,13 @@ static void widget_list_add(GtkObject *widget, gint id, gint position, gint valu widget_list = g_list_prepend(widget_list, el); } +/** + * apply_widget_setting: + * @el: widget list element + * @param: parameter to set + * + * Sets widget list element value to param value. + **/ static void apply_widget_setting(WidgetListElem *el, SettingParam *param) { if ((el->id == param->id) && (el->position == param->position)) { @@ -117,6 +155,12 @@ static void apply_widget_setting(WidgetListElem *el, SettingParam *param) } } +/** + * apply_preset_to_gui: + * @preset: preset to sync + * + * Synces GUI with preset. + **/ static void apply_preset_to_gui(Preset *preset) { g_return_if_fail(preset != NULL); @@ -136,6 +180,11 @@ static void apply_preset_to_gui(Preset *preset) allow_send = TRUE; } +/** + * apply_current_preset: + * + * Synces GUI with device current edit buffer. + **/ static void apply_current_preset() { GString *msg = get_current_preset(); @@ -145,6 +194,15 @@ static void apply_current_preset() preset_free(preset); } +/** + * create_table: + * @settings: effect parameters + * @amt: amount of effect parameters + * + * Creates knobs that allow user to set effect parameters. + * + * Return value: GtkTable containing necessary widgets to set effect parameters. + **/ GtkWidget *create_table(EffectSettings *settings, gint amt) { GtkWidget *table, *label, *widget, *knob; @@ -181,6 +239,14 @@ GtkWidget *create_table(EffectSettings *settings, gint amt) return table; } +/** + * create_on_off_button: + * @effect: Effect that can be turned on/off + * + * Creates toggle button that allow user to turn effect on/off. + * + * Return value: GtkToggleButton + **/ GtkWidget *create_on_off_button(Effect *effect) { GtkWidget *button = gtk_toggle_button_new_with_label(effect->label); @@ -197,6 +263,12 @@ typedef struct { GtkWidget *child; /* child widget */ } EffectSettingsGroup; +/** + * effect_settings_group_free: + * @group: group to be freed + * + * Frees all memory used by group + **/ void effect_settings_group_free(EffectSettingsGroup *group) { /* destroy widget without parent */ @@ -207,6 +279,13 @@ void effect_settings_group_free(EffectSettingsGroup *group) g_free(group); } +/** + * combo_box_changed_cb: + * @widget: the object which emitted the signal + * @data: user data (unused, can be anything) + * + * Switches effect type and shows widgets allowing to set selected effect type parameters. + **/ void combo_box_changed_cb(GtkComboBox *widget, gpointer data) { GtkWidget *child; @@ -236,6 +315,15 @@ void combo_box_changed_cb(GtkComboBox *widget, gpointer data) } } +/** + * create_widget_container: + * @group: Effect type groups + * @amt: amount of effect groups + * + * Creates widget allowing user to choose effect type. + * + * Return value: widget that allow user to set effect type. + **/ GtkWidget *create_widget_container(EffectGroup *group, gint amt) { GtkWidget *vbox; @@ -281,6 +369,15 @@ GtkWidget *create_widget_container(EffectGroup *group, gint amt) return vbox; } +/** + * create_vbox: + * @widgets: Effect descriptions + * @amt: amount of effect descriptions + * + * Creates vbox containing widgets allowing user to set effect options. + * + * Return value: widget that allow user to set effect options. + **/ GtkWidget *create_vbox(Effect *widgets, gint amt) { GtkWidget *vbox; @@ -313,6 +410,15 @@ enum { NUM_COLUMNS }; +/** + * row_activate_cb: + * @treeview: the object which emitted the signal + * @path: the GtkTreePath for the activated row + * @column: the GtkTreeViewColumn in which the activation occurred + * @model: model holding preset names + * + * Sets active device preset to preset selected by user. + **/ void row_activate_cb(GtkTreeView *treeview, GtkTreePath *path, GtkTreeViewColumn *column, GtkTreeModel *model) { GtkTreeIter iter; gint id; @@ -327,6 +433,14 @@ void row_activate_cb(GtkTreeView *treeview, GtkTreePath *path, GtkTreeViewColumn } } +/** + * fill_store_with_presets: + * @model: model to fill + * @bank: preset bank + * @name: preset bank description visible to user + * + * Appends to model preset names found in device preset bank. + **/ static void fill_store_with_presets(GtkTreeStore *model, guint bank, gchar *name) { GtkTreeIter iter; @@ -354,12 +468,25 @@ static void fill_store_with_presets(GtkTreeStore *model, guint bank, gchar *name g_strfreev(presets); } +/** + * fill_store: + * @model: model to fill + * + * Fills model with preset names found on device. + **/ static void fill_store(GtkTreeStore *model) { fill_store_with_presets(model, PRESETS_USER, "User Presets"); fill_store_with_presets(model, PRESETS_SYSTEM, "System Presets"); } +/** + * create_preset_tree: + * + * Creates treeview showing list of presets available on device. + * + * Return value: treeview containing all preset names found on device. + **/ GtkWidget *create_preset_tree() { GtkWidget *treeview; @@ -385,6 +512,13 @@ GtkWidget *create_preset_tree() return treeview; } +/** + * show_store_preset_window: + * @window: application toplevel window + * @default_name: default preset name + * + * Shows window allowing user to store current edit buffer. + **/ static void show_store_preset_window(GtkWidget *window, gchar *default_name) { GtkWidget *dialog, *cmbox, *entry, *table, *label; @@ -433,12 +567,24 @@ static void show_store_preset_window(GtkWidget *window, gchar *default_name) gtk_widget_destroy(dialog); } +/** + * action_store_cb: + * @action: the object which emitted the signal + * + * Shows store preset window. + **/ static void action_store_cb(GtkAction *action) { GtkWidget *window = g_object_get_data(G_OBJECT(action), "window"); show_store_preset_window(window, NULL); } +/** + * action_show_about_dialog_cb: + * @action: the object which emitted the signal + * + * Shows about dialog. + **/ static void action_show_about_dialog_cb(GtkAction *action) { static const gchar * const authors[] = { @@ -467,6 +613,13 @@ static SupportedFileTypes file_types[] = { }; static guint n_file_types = G_N_ELEMENTS(file_types); +/** + * action_open_preset_cb: + * @action: the object which emitted the signal + * + * Shows file chooser dialog. + * If user opens valid preset file, the preset gets applied to edit buffer and store preset window is shown. + **/ static void action_open_preset_cb(GtkAction *action) { static GtkWidget *dialog = NULL; @@ -552,6 +705,12 @@ static void action_open_preset_cb(GtkAction *action) dialog = NULL; } +/** + * widget_list_free: + * @list: widget list to be freed + * + * Frees all memory used by widget list. + */ static void widget_list_free(GList *list) { GList *iter; @@ -561,6 +720,12 @@ static void widget_list_free(GList *list) g_list_free(list); } +/** + * action_quit_cb: + * @action: the object which emitted the signal + * + * Destroys action object "window" data, then stops gtk main loop. + **/ static void action_quit_cb(GtkAction *action) { GtkWidget *window = g_object_get_data(G_OBJECT(action), "window"); @@ -597,14 +762,31 @@ static const gchar *menu_info = " " ""; +/** + * add_action_data: + * @ui: GtkUIManager to lookup actions + * @path: path to action + * @window: toplevel window + * + * Sets action object "window" data to toplevel window. + **/ static void add_action_data(GtkUIManager *ui, const gchar *path, GtkWidget *window) { GtkAction *action; action = gtk_ui_manager_get_action(ui, path); + g_return_if_fail(action != NULL); + g_object_set_data(G_OBJECT(action), "window", window); } +/** + * add_menubar: + * @window: toplevel window + * @vbox: vbox to hold menubar + * + * Creates menubar (adds accel group to toplevel window as well) and packs it into vbox. + **/ static void add_menubar(GtkWidget *window, GtkWidget *vbox) { GtkUIManager *ui; @@ -636,6 +818,11 @@ static void add_menubar(GtkWidget *window, GtkWidget *vbox) g_object_unref(ui); } +/** + * gui_create: + * + * Creates main window. + **/ void gui_create() { GtkWidget *window; @@ -683,6 +870,11 @@ void gui_create() g_signal_connect(G_OBJECT(window), "delete_event", G_CALLBACK(gtk_main_quit), NULL); } +/** + * gui_free: + * + * Frees memory allocated by gui_create which is not explicitly freed when main window is destroyed. + **/ void gui_free() { widget_list_free(widget_list); diff --git a/preset.c b/preset.c index bbf6242..c9cb8d8 100644 --- a/preset.c +++ b/preset.c @@ -112,10 +112,14 @@ static void XMLCALL text_cb(void *data, const char* text, int len) g_free(value); } -/* - Parses preset file - On success returns Preset which must be freed using preset_free, or NULL on error -*/ +/** + * create_preset_from_xml_file: + * @filename: valid path to file + * + * Tries to open file pointed by path, then parses it. + * + * Return value: Preset which must be freed using preset_free, or NULL on error. + **/ Preset *create_preset_from_xml_file(gchar *filename) { GFile *file; @@ -165,6 +169,14 @@ Preset *create_preset_from_xml_file(gchar *filename) return preset; } +/** + * create_preset_from_data: + * @data: unpacked RECEIVE_PRESET_PARAMETERS message + * + * Parses message + * + * Return value: Preset which must be freed using preset_free, or NULL on error. + **/ Preset *create_preset_from_data(GString *data) { gint total; @@ -213,6 +225,12 @@ Preset *create_preset_from_data(GString *data) return preset; } +/** + * preset_free: + * @preset: preset to be freed + * + * Frees all memory used by preset + **/ void preset_free(Preset *preset) { g_return_if_fail(preset != NULL);