Restructure code, improve doxygen documentation

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
+ * @brief Main window close event
- *
+ * @param window GtkWindow which is closed
- * Closes the main window. This leads to the termination of the whole application
+ * @param event unused event
- * @param window main window
+ * @param user GdsRenderGui instance
- * @param user not used
+ * @return Status of the event handling. Always true.
- * @return TRUE. This indicates that the event has been fully handled
  */
 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
+ * @brief cell_tree_view_activated Callback for 'double click' on cell selector element
- * @param tree_view Not used
+ * @param tree_view The tree view the event occured in
- * @param user convert button data
+ * @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)

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);
 

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
+ * @brief Check if a specific layer element with the given layer number is present in the layer selector
- * @param layer Layer nu,ber
+ * @param self LayerSelector instance
- * @return TRUE if present
+ * @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,
+	struct layer_element_dnd_data dnd_data;
-					sel_layer_element_drag_begin,
+
-					sel_layer_element_drag_data_get,
+	if (!self || !element)
-					sel_layer_element_drag_end);
+		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
+ * @brief Analyze \p cell layers and append detected layers to layer selector \p self
- * @param listbox listbox to add layer
+ * @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
+ * @brief Load the layer mapping from a CSV formatted file
- * @param file_name CSV Layer Mapping 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
+ * @brief Save layer mapping of selector \p self to a file
- * @param file_name layer mapping file
+ * @param self LayerSelector instance
- * @param list_box listbox
+ * @param file_name File name to save to
  */
 static void layer_selector_save_layer_mapping_data(LayerSelector *self, const gchar *file_name)
 {

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 selector LayerSelector instance
- * @param main_window Parent window for dialogs
+ * @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 selector LayerSelector instance
- * @param main_window Parent window for dialogs
+ * @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
+ * @brief Get a list of all layers that shall be exported when rendering the cells
- * @return List with layer_info elements
+ * @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
+ * @brief Force the layer selector list to be sorted according to \p sort_function
- *
+ * @param selector LayerSelector instance
- * If the layer selector is not yet set up, this function has no effect.
+ * @param sort_function The sorting method (up or down sorting)
- *
- * @param sort_function Sorting direction
  */
 void layer_selector_force_sort(LayerSelector *selector, enum layer_selector_sort_algo sort_function);
 

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 layer_element_set_dnd_callbacks(LayerElement *elem, struct layer_element_dnd_data *data)
-				     void (*drag_begin)(GtkWidget *, GdkDragContext *, gpointer),
-				     void (*drag_data_get)(GtkWidget *, GdkDragContext *,
-							   GtkSelectionData *, guint , guint, gpointer),
-				     void (*drag_end)(GtkWidget *, GdkDragContext *, gpointer))
 {
+	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);
+	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(drag_begin), NULL);
+	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(drag_data_get), 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(drag_end), NULL);
+	g_signal_connect(elem->priv.event_handle, "drag-end", G_CALLBACK(data->drag_end), NULL);
 
 }
 

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
+ * @brief Setup drag and drop of \p elem for use in the LayerSelector
- * @param elem
+ * @param elem Layer element to set up
- * @param entries
+ * @param data Data array containing the necessary callbacks etc. for drag and drop.
- * @param entry_count
  */
-void layer_element_set_dnd_callbacks(LayerElement *elem, GtkTargetEntry *entries, int entry_count,
+void layer_element_set_dnd_callbacks(LayerElement *elem, struct layer_element_dnd_data *data);
-				     void (*drag_begin)(GtkWidget *, GdkDragContext *, gpointer),
-				     void (*drag_data_get)(GtkWidget *, GdkDragContext *,
-							   GtkSelectionData *, guint , guint, gpointer),
-				     void (*drag_end)(GtkWidget *, GdkDragContext *, gpointer));
 
 G_END_DECLS