Restructure code, improve doxygen documentation

This commit is contained in:
Mario Hüttel 2019-03-25 18:47:12 +01:00
parent a99a469cf0
commit 829c9a2386
6 changed files with 94 additions and 57 deletions

View File

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

View File

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

View File

@ -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)
{

View File

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

View File

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

View File

@ -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