From 829c9a2386a19eaddbde814009f2e603e44cc635 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Mon, 25 Mar 2019 18:47:12 +0100 Subject: [PATCH] Restructure code, improve doxygen documentation --- gds-render-gui.c | 21 +++++++++--------- gds-render-gui.h | 4 ++-- layer/layer-selector.c | 49 +++++++++++++++++++++++++++++------------ layer/layer-selector.h | 27 ++++++++++++----------- widgets/layer-element.c | 21 ++++++++++-------- widgets/layer-element.h | 29 ++++++++++++++++-------- 6 files changed, 94 insertions(+), 57 deletions(-) diff --git a/gds-render-gui.c b/gds-render-gui.c index 5a7785a..6f68fc0 100644 --- a/gds-render-gui.c +++ b/gds-render-gui.c @@ -63,12 +63,11 @@ struct _GdsRenderGui { G_DEFINE_TYPE(GdsRenderGui, gds_render_gui, G_TYPE_OBJECT) /** - * @brief Window close event of main window - * - * Closes the main window. This leads to the termination of the whole application - * @param window main window - * @param user not used - * @return TRUE. This indicates that the event has been fully handled + * @brief Main window close event + * @param window GtkWindow which is closed + * @param event unused event + * @param user GdsRenderGui instance + * @return Status of the event handling. Always true. */ static gboolean on_window_close(gpointer window, GdkEvent *event, gpointer user) { @@ -113,7 +112,7 @@ static GString *generate_string_from_date(struct gds_time_field *date) /** * @brief Callback function of Load GDS button * @param button - * @param user Necessary Data + * @param user GdsRenderGui instance */ static void on_load_gds(gpointer button, gpointer user) { @@ -367,9 +366,11 @@ ret_layer_destroy: } /** - * @brief cell_tree_view_activated - * @param tree_view Not used - * @param user convert button data + * @brief cell_tree_view_activated Callback for 'double click' on cell selector element + * @param tree_view The tree view the event occured in + * @param path path to the selected row + * @param column The clicked column + * @param user pointer to GdsRenderGui object */ static void cell_tree_view_activated(gpointer tree_view, GtkTreePath *path, GtkTreeViewColumn *column, gpointer user) diff --git a/gds-render-gui.h b/gds-render-gui.h index 9e2941b..46dd3a2 100644 --- a/gds-render-gui.h +++ b/gds-render-gui.h @@ -41,7 +41,7 @@ G_DECLARE_FINAL_TYPE(GdsRenderGui, gds_render_gui, RENDERER, GUI, GObject); /** * @brief Create new GdsRenderGui Object - * @return + * @return New object */ GdsRenderGui *gds_render_gui_new(); @@ -50,7 +50,7 @@ GdsRenderGui *gds_render_gui_new(); * * This function returns the main window of the GUI, which can later be displayed. * All handling of hte GUI is taken care of inside the GdsRenderGui Object - * @return + * @return The generated main window */ GtkWindow *gds_render_gui_get_main_window(GdsRenderGui *gui); diff --git a/layer/layer-selector.c b/layer/layer-selector.c index 7b99156..b23dc2f 100644 --- a/layer/layer-selector.c +++ b/layer/layer-selector.c @@ -424,9 +424,10 @@ static void layer_selector_clear_widgets(LayerSelector *self) } /** - * @brief Check if specific layer number is present in list box - * @param layer Layer nu,ber - * @return TRUE if present + * @brief Check if a specific layer element with the given layer number is present in the layer selector + * @param self LayerSelector instance + * @param layer Layer number to check for + * @return TRUE if layer is present, else FALSE */ static gboolean layer_selector_check_if_layer_widget_exists(LayerSelector *self, int layer) { GList *list; @@ -449,17 +450,30 @@ static gboolean layer_selector_check_if_layer_widget_exists(LayerSelector *self, return ret; } +/** + * @brief Setup the necessary drag and drop callbacks of layer elements. + * @param self LayerSelector instance. Used to get the DnD target entry. + * @param element LayerElement instance to set the callbacks + */ static void sel_layer_element_setup_dnd_callbacks(LayerSelector *self, LayerElement *element) { - layer_element_set_dnd_callbacks(element, &self->dnd_target, 1, - sel_layer_element_drag_begin, - sel_layer_element_drag_data_get, - sel_layer_element_drag_end); + struct layer_element_dnd_data dnd_data; + + if (!self || !element) + return; + + dnd_data.entries = &self->dnd_target; + dnd_data.entry_count = 1; + dnd_data.drag_end = sel_layer_element_drag_end; + dnd_data.drag_begin = sel_layer_element_drag_begin; + dnd_data.drag_data_get = sel_layer_element_drag_data_get; + + layer_element_set_dnd_callbacks(element, &dnd_data); } /** - * @brief Analyze \p cell and append used layers to list box - * @param listbox listbox to add layer + * @brief Analyze \p cell layers and append detected layers to layer selector \p self + * @param self LayerSelector instance * @param cell Cell to analyze */ static void layer_selector_analyze_cell_layers(LayerSelector *self, struct gds_cell *cell) @@ -557,8 +571,15 @@ static LayerElement *layer_selector_find_layer_element_in_list(GList *el_list, i } /** - * @brief Load file and apply layer definitions to listbox - * @param file_name CSV Layer Mapping File + * @brief Load the layer mapping from a CSV formatted file + * + * This function imports the layer specification from a file (see @ref lmf-spec). + * The layer ordering defined in the file is kept. All layers present in the + * current loaded library, which are not present in the layer mapping file + * are appended at the end of the layer selector list. + * + * @param self LayerSelector instance + * @param file_name File name to load from */ static void layer_selector_load_layer_mapping_from_file(LayerSelector *self, gchar *file_name) { @@ -658,9 +679,9 @@ static void layer_selector_load_mapping_clicked(GtkWidget *button, gpointer user /** - * @brief Save layer mapping of whole list box into file - * @param file_name layer mapping file - * @param list_box listbox + * @brief Save layer mapping of selector \p self to a file + * @param self LayerSelector instance + * @param file_name File name to save to */ static void layer_selector_save_layer_mapping_data(LayerSelector *self, const gchar *file_name) { diff --git a/layer/layer-selector.h b/layer/layer-selector.h index 10e87e0..2719434 100644 --- a/layer/layer-selector.h +++ b/layer/layer-selector.h @@ -48,39 +48,40 @@ enum layer_selector_sort_algo {LAYER_SELECTOR_SORT_DOWN = 0, LAYER_SELECTOR_SORT LayerSelector *layer_selector_new(GtkListBox *list_box); /** - * @brief Generate layer widgets in \p listbox + * @brief Generate layer widgets in in the LayerSelector instance * @note This clears all previously inserted elements - * @param listbox + * @param selector LayerSelector instance * @param libs The libraries to add */ void layer_selector_generate_layer_widgets(LayerSelector *selector, GList *libs); /** * @brief Supply button for loading the layer mapping - * @param button - * @param main_window Parent window for dialogs + * @param selector LayerSelector instance + * @param button Load button. Will be referenced + * @param main_window Parent window for dialogs. Will be referenced */ void layer_selector_set_load_mapping_button(LayerSelector *selector, GtkWidget *button, GtkWindow *main_window); /** * @brief Supply button for saving the layer mapping - * @param button - * @param main_window Parent window for dialogs + * @param selector LayerSelector instance + * @param button Save button. Will be refeneced + * @param main_window Parent window for dialogs. Will be referenced */ void layer_selector_set_save_mapping_button(LayerSelector *selector, GtkWidget *button, GtkWindow *main_window); /** - * @brief get the layer information present in the listbox of the selector - * @return List with layer_info elements + * @brief Get a list of all layers that shall be exported when rendering the cells + * @param selector Layer selector instance + * @return List of layer_info structures containing the layer information */ GList *layer_selector_export_rendered_layer_info(LayerSelector *selector); /** - * @brief Force sorting of the layer selector in a specified way - * - * If the layer selector is not yet set up, this function has no effect. - * - * @param sort_function Sorting direction + * @brief Force the layer selector list to be sorted according to \p sort_function + * @param selector LayerSelector instance + * @param sort_function The sorting method (up or down sorting) */ void layer_selector_force_sort(LayerSelector *selector, enum layer_selector_sort_algo sort_function); diff --git a/widgets/layer-element.c b/widgets/layer-element.c index f1d3efd..d9257b2 100644 --- a/widgets/layer-element.c +++ b/widgets/layer-element.c @@ -120,26 +120,29 @@ void layer_element_get_color(LayerElement *elem, GdkRGBA *rgba) { if (!rgba) return; + gtk_color_chooser_get_rgba(GTK_COLOR_CHOOSER(elem->priv.color), rgba); } void layer_element_set_color(LayerElement *elem, GdkRGBA *rgba) { + if (!elem || !rgba) + return; + gtk_color_chooser_set_rgba(GTK_COLOR_CHOOSER(elem->priv.color), rgba); } -void layer_element_set_dnd_callbacks(LayerElement *elem, GtkTargetEntry *entries, int entry_count, - void (*drag_begin)(GtkWidget *, GdkDragContext *, gpointer), - void (*drag_data_get)(GtkWidget *, GdkDragContext *, - GtkSelectionData *, guint , guint, gpointer), - void (*drag_end)(GtkWidget *, GdkDragContext *, gpointer)) +void layer_element_set_dnd_callbacks(LayerElement *elem, struct layer_element_dnd_data *data) { + if (!elem || !data) + return; + /* Setup drag and drop */ gtk_style_context_add_class (gtk_widget_get_style_context(GTK_WIDGET(elem)), "row"); - gtk_drag_source_set(GTK_WIDGET(elem->priv.event_handle), GDK_BUTTON1_MASK, entries, entry_count, GDK_ACTION_MOVE); - g_signal_connect(elem->priv.event_handle, "drag-begin", G_CALLBACK(drag_begin), NULL); - g_signal_connect(elem->priv.event_handle, "drag-data-get", G_CALLBACK(drag_data_get), NULL); - g_signal_connect(elem->priv.event_handle, "drag-end", G_CALLBACK(drag_end), NULL); + gtk_drag_source_set(GTK_WIDGET(elem->priv.event_handle), GDK_BUTTON1_MASK, data->entries, data->entry_count, GDK_ACTION_MOVE); + g_signal_connect(elem->priv.event_handle, "drag-begin", G_CALLBACK(data->drag_begin), NULL); + g_signal_connect(elem->priv.event_handle, "drag-data-get", G_CALLBACK(data->drag_data_get), NULL); + g_signal_connect(elem->priv.event_handle, "drag-end", G_CALLBACK(data->drag_end), NULL); } diff --git a/widgets/layer-element.h b/widgets/layer-element.h index 8d30c09..a514363 100644 --- a/widgets/layer-element.h +++ b/widgets/layer-element.h @@ -56,6 +56,22 @@ struct _LayerElement { LayerElementPriv priv; }; +/** + * @brief This structure holds the necessary data to set up a LayerElement for Drag'n'Drop + */ +struct layer_element_dnd_data { + /** @brief Array of target entries for the DnD operation */ + GtkTargetEntry *entries; + /** @brief Count of elements in layer_element_dnd_data::entries array */ + int entry_count; + /** @brief Callback function for drag_begin event */ + void (*drag_begin)(GtkWidget *, GdkDragContext *, gpointer); + /** @brief Callback fucktion for data_get event */ + void (*drag_data_get)(GtkWidget *, GdkDragContext *, GtkSelectionData *, guint, guint, gpointer); + /** @brief Callback function for drag_end event */ + void (*drag_end)(GtkWidget *, GdkDragContext *, gpointer); +}; + /** * @brief Create new layer element object * @return new object @@ -119,16 +135,11 @@ void layer_element_get_color(LayerElement *elem, GdkRGBA *rgba); void layer_element_set_color(LayerElement *elem, GdkRGBA *rgba); /** - * @brief layer_element_set_dnd_callbacks - * @param elem - * @param entries - * @param entry_count + * @brief Setup drag and drop of \p elem for use in the LayerSelector + * @param elem Layer element to set up + * @param data Data array containing the necessary callbacks etc. for drag and drop. */ -void layer_element_set_dnd_callbacks(LayerElement *elem, GtkTargetEntry *entries, int entry_count, - void (*drag_begin)(GtkWidget *, GdkDragContext *, gpointer), - void (*drag_data_get)(GtkWidget *, GdkDragContext *, - GtkSelectionData *, guint , guint, gpointer), - void (*drag_end)(GtkWidget *, GdkDragContext *, gpointer)); +void layer_element_set_dnd_callbacks(LayerElement *elem, struct layer_element_dnd_data *data); G_END_DECLS