Skip to content

Commit

Permalink
Doxygen documentation for new options classes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@jralls
jralls committed Nov 12, 2021
1 parent 00a982d commit 96b09de
Show file tree
Hide file tree
Showing 9 changed files with 292 additions and 55 deletions.
44 changes: 44 additions & 0 deletions gnucash/gnome-utils/dialog-options.hpp
View file
Expand Up @@ -3,6 +3,7 @@
* Copyright (C) 1998-2000 Linas Vepstas *
* Copyright (c) 2006 David Hampton <hampton@employees.org> *
* Copyright (c) 2011 Robert Fewell *
* Copyright 2019-2021 John Ralls <jralls@ceridwen.us> *
* *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
Expand All @@ -21,6 +22,10 @@
* 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
* Boston, MA 02110-1301, USA gnu@gnu.org *
\********************************************************************/
/** @addtogroup GUI
@{ */
/** @addtogroup GuiOptions Options Dialog
@{ */

#ifndef GNC_DIALOG_OPTIONS_HPP_
#define GNC_DIALOG_OPTIONS_HPP_
Expand All @@ -31,26 +36,59 @@
#include <gnc-option-ui.hpp>
#include "dialog-options.h"

/** @fn WidgetCreateFunc
* Function pointer for per-option-type GtkWidget constructors.
* @param option The option to create an element for.
* @param page_box The option dialog page's layout grid
* @param name_label A GtkLabel to attach to the widget
* @param documentation The string to use for the tooltip.
* @param enclosing The parent widget
* @param packed Whether the widget will be packed into an eventbox.
* @return pointer to the widget.
*/

typedef GtkWidget* (*WidgetCreateFunc)(GncOption&, GtkGrid*, GtkLabel*, char*,
GtkWidget**, bool*);
/** @class GncOptionUIFactory
* Factory class that keeps track of which GncOptionValueType needs which
* WidgetCreateFunc and calls the appropriate one when required.
*/
class GncOptionUIFactory
{
public:
/** Register a WidgetCreateFunc
* @param type The UI type
* @param func The function to register
*/
static void set_func(GncOptionUIType type, WidgetCreateFunc func);
/** Create a widget
* @param option The option for which to create the widget
* @param page The Option dialog page in which to insert the widget
* @param name The label to attach to the widget
* @param description The text for the widget's tooltip
* @param enclosing The widget's parent
* @param packed Whether the widget will be packed into an eventbox.
* @return pointer to the created widget.
*/
static GtkWidget* create(GncOption&, GtkGrid*, GtkLabel*, char*,
GtkWidget**, bool*);
private:
static std::vector<WidgetCreateFunc> s_registry;
};

/** class GncOptionGtkUIItem
* Gtk-specific Interface class for Option Widget
*/
class GncOptionGtkUIItem : public GncOptionUIItem
{
public:
GncOptionGtkUIItem(GtkWidget* widget, GncOptionUIType type);
GncOptionGtkUIItem(const GncOptionGtkUIItem& item);
GncOptionGtkUIItem(GncOptionGtkUIItem&&) = default;
virtual ~GncOptionGtkUIItem() override;
/** Control wether the widget is sensitive */
virtual void set_selectable(bool) const noexcept override;
/** Clear the data from the widget. */
void clear_ui_item() override;
void set_widget(GtkWidget* widget);
virtual GtkWidget* const get_widget() const { return m_widget; }
Expand All @@ -68,6 +106,10 @@ template<GncOptionUIType type> GtkWidget*
create_option_widget(GncOption& option, GtkGrid*, GtkLabel*, char*, GtkWidget**,
bool*);

/** Templated cast to convert various QofInstance subtype ptrs into QofInstance*
* to placate the C++ type system. QofInstance is a GObject hierarchy so the
* usual C++ type substitution doesn't work.
*/
template <typename Instance> inline const QofInstance*
qof_instance_cast(Instance inst)
{
Expand All @@ -76,3 +118,5 @@ qof_instance_cast(Instance inst)
}

#endif // GNC_DIALOG_OPTIONS_HPP_
/** @}
@} */
9 changes: 9 additions & 0 deletions gnucash/gnome/business-options-gnome.h
View file
Expand Up @@ -21,10 +21,19 @@
* 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652
* Boston, MA 02110-1301, USA gnu@gnu.org
*/
/** @addtogroup GUI
@{ */
/** @addtogroup GuiOptions Options Dialog
@{ */

#ifndef GNC_BUSINESS_OPTIONS_H_
#define GNC_BUSINESS_OPTIONS_H_

/**
* Set up the business and counters pages in the File Preferences dialog.
*/
void gnc_business_options_gnome_initialize (void);

#endif /* GNC_BUSINESS_OPTIONS_H_ */
/** @}
@} */
91 changes: 90 additions & 1 deletion libgnucash/app-utils/gnc-option-date.hpp
View file
Expand Up @@ -20,7 +20,14 @@
* Boston, MA 02110-1301, USA gnu@gnu.org *
* *
\********************************************************************/

/** @addtogroup Engine
@{ */
/** @addtogroup Options
@{ */
/** @file gnc-option-date.hpp
@brief Relative date enumeration and manipulation functions.
@author Copyright 2019-2021 John Ralls <jralls@ceridwen.us>
*/
#ifndef GNC_OPTION_DATE_HPP_
#define GNC_OPTION_DATE_HPP_

Expand Down Expand Up @@ -78,14 +85,96 @@ constexpr unsigned relative_date_periods =

using RelativeDatePeriodVec = std::vector<RelativeDatePeriod>;

/**
* Report whether the relative date represents a period offset to today's date
* rather than the beginning or end of a date range. For example ONE_MONTH_AGO
* will be made concrete as the same day as today in the previous month.
*
* @param period The Relative Date Period to check.
* @return true if the date is stand-alone.
*/
bool gnc_relative_date_is_single(RelativeDatePeriod);

/**
* Report whether the relative date represents the beginning of a date
* range. For example START_LAST_MONTH is the beginning of a range.
*
* @param period The Relative Date Period to check.
* @return true if the date is the beginning of a date range
*/
bool gnc_relative_date_is_starting(RelativeDatePeriod);

/**
* Report whether the relative date represents the end of a date range. For
* example END_LAST_MONTH is the end of a range.
*
* @param period The Relative Date Period to check.
* @return true if the date is the end of a date range.
*/
bool gnc_relative_date_is_ending(RelativeDatePeriod);

/**
* Provide the string representation of a relative date for persisting the
* value. This string is not localizable.
*
* @param period The relative date period.
* @return A constant string or nullptr if the period is ABSOLUTE. The string's
* lifetime will be that of the Relative Date Period. It must not be freed and
* should be copied if the period might be destroyed before the using code is
* finished.
*/
const char* gnc_relative_date_storage_string(RelativeDatePeriod);

/**
* Provide the string representation of a relative date for displaying
* value to a user. This string is not localizable.
*
* @param period The relative date period.
* @return A constant string or nullptr if the period is ABSOLUTE. The string's
* lifetime will be that of the Relative Date Period. It must not be freed and
* should be copied if the period might be destroyed before the using code is
* finished.
*/
const char* gnc_relative_date_display_string(RelativeDatePeriod);

/**
* Provide the description of a relative date. This string is localizable.
*
* @param period The relative date period.
* @return A constant string or nullptr if the period is ABSOLUTE. The string's
* lifetime will be that of the Relative Date Period. It must not be freed and
* should be copied if the period might be destroyed before the using code is
* finished.
*/
const char* gnc_relative_date_description(RelativeDatePeriod);

/**
* Convert a relative date storage string back to a RelativeDatePeriod value.
*
* @param A string representation obtained from
* gnc_relative_date_storage_string.
* @return A RelativeDatePeriod value.
*/
RelativeDatePeriod gnc_relative_date_from_storage_string(const char*);

/**
* Convert a RelativeDatePeriod value to a concrete time64 by applying the value to the current time. For example if it is now 3:15:42 PM local time 3 June, calling this with a period RelativeDatePeriod::ONE_WEEK_AHEAD will return a time64 representing 3:15:42 PM local time 10 June of this year.
*
* @param period The relative date period to use to calculate the concrete date.
* @return a time64.
*/
time64 gnc_relative_date_to_time64(RelativeDatePeriod);

/**
* Add the display string to the provided std::ostream.
*
* @param stream the std::ostream to which to write the period value
* @param period the period value to write
* @return A reference to stream so that the operator can be chained.
*/
std::ostream& operator<<(std::ostream&, const RelativeDatePeriod);

#endif //GNC_OPTION_DATE_HPP_

/** @}
@} */
88 changes: 36 additions & 52 deletions libgnucash/app-utils/gnc-option-impl.hpp
View file
Expand Up @@ -21,6 +21,15 @@
* *
\********************************************************************/

/** @addtogroup Engine
@{ */
/** @addtogroup Options
@{ */
/** @file gnc-option-impl.hpp
@brief Implementation templates and specializtions for GncOption values.
Objecte created by these templates are wrapped by the GncOption variant.
@author Copyright 2019-2021 John Ralls <jralls@ceridwen.us>
*/
#ifndef GNC_OPTION_IMPL_HPP_
#define GNC_OPTION_IMPL_HPP_

Expand All @@ -46,58 +55,19 @@ extern "C"

#include "gnc-option-uitype.hpp"

/*
* Unused base class to document the structure of the current Scheme option
* vector, re-expressed in C++. The comment-numbers on the right indicate which
* item in the Scheme vector each item implements.
*
* Not everything here needs to be implemented, nor will it necessarily be
* implemented the same way. For example, part of the purpose of this redesign
* is to convert from saving options as strings of Scheme code to some form of
* key-value pair in the book options, so generate_restore_form() will likely be
* supplanted with save_to_book().
template <typename ValueType>
class GncOptionBase
{
public:
virtual ~GncOption = default;
virtual ValueType get_value() const = 0; //5
virtual ValueType get_default_value() = 0;
virtual SCM get_SCM_value() = 0;
virtual SCM get_SCM_default_value() const = 0; //7
virtual void set_value(ValueType) = 0; //6
// generate_restore_form outputs a Scheme expression (a "form") that finds an
// option and sets it to the current value. e.g.:
//(let ((option (gnc:lookup-option options
// "Display"
// "Amount")))
// ((lambda (option) (if option ((gnc:option-setter option) 'none))) option))
// it uses gnc:value->string to generate the "'none" (or whatever the option's
// value would be as input to the scheme interpreter).
virtual std::string generate_restore_form(); //8
virtual void save_to_book(QofBook*) const noexcept; //9
virtual void read_from_book(QofBook*); //10
virtual std::vector<std::string> get_option_strings(); //15
virtual set_changed_callback(std::function<void(void*)>); //14
protected:
const std::string m_section; //0
const std::string m_name; //1
const std::string m_sort_tag; //2
const std::type_info m_kvp_type; //3
const std::string m_doc_string; //4
std::function<void(void*)> m_changed_callback; //Part of the make-option closure
std::function<void(void*)>m_option_widget_changed_callback; //16
};
*/

static const char* commodity_scm_intro{"'(commodity-scm "};
#ifndef SWIG
size_t constexpr classifier_size_max{50};
size_t constexpr sort_tag_size_max{10};
#endif

/** @struct OptionClassifier
* This class is the parent of all option implmentations. It contains the
* elements that the optiondb uses to retrieve option values and that the
* options dialog determines on which tab to place the option, in what order,
* and what string to display as a tooltip.
*/
struct OptionClassifier
{
std::string m_section;
Expand All @@ -112,6 +82,9 @@ struct OptionClassifier
auto constexpr size_t_max = std::numeric_limits<std::size_t>::max();
#endif

/** @class GncOptionValue
* The generic option-value class. Most option types can use this template.
*/
template <typename ValueType>
class GncOptionValue : public OptionClassifier
{
Expand Down Expand Up @@ -167,6 +140,12 @@ class GncOptionValue : public OptionClassifier
ValueType m_default_value;
};

/** class GncOptionValidatedValue
* Validated values have an additional member function, provided as a
* constructor argument, that checks value parameters for some property before
* setting the object's value member. If the function returns false a
* std::invalid_argument exception is thrown.
*/
template <typename ValueType>
class GncOptionValidatedValue : public OptionClassifier
{
Expand Down Expand Up @@ -353,7 +332,7 @@ operator>> <GncOptionValue<bool>>(std::istream& iss,
}
#endif // SWIG

/**
/** @class GncOptionRangeValue
* Used for numeric ranges and plot sizes.
*/

Expand Down Expand Up @@ -461,7 +440,8 @@ using GncMultichoiceOptionEntry = std::tuple<const std::string,
using GncMultichoiceOptionIndexVec = std::vector<std::size_t>;
using GncMultichoiceOptionChoices = std::vector<GncMultichoiceOptionEntry>;

/** Multichoice options have a vector of valid options
/** @class GncOptionMultichoiceValue
* Multichoice options have a vector of valid options
* (GncMultichoiceOptionChoices) and validate the selection as being one of
* those values. The value is the index of the selected item in the vector. The
* tuple contains three strings, a key, and a display
Expand Down Expand Up @@ -731,7 +711,7 @@ using GncOptionAccountList = std::vector<const Account*>;

using GncOptionAccountTypeList = std::vector<GNCAccountType>;

/** Account options
/** @class GncOptionAccountListValue
*
* Set one or more accounts on which to report, optionally restricted to certain
* account types. Many calls to make-account-list-option will pass a get-default
Expand Down Expand Up @@ -853,6 +833,10 @@ operator>> <GncOptionAccountListValue>(std::istream& iss,
return iss;
}

/* @class GncOptionAccountSelValue
* Like GncOptionAccountListValue but contains only a single account.
*/

class GncOptionAccountSelValue : public OptionClassifier
{
public:
Expand Down Expand Up @@ -936,8 +920,8 @@ operator>> <GncOptionAccountSelValue>(std::istream& iss,
return iss;
}

/** Date options
* A legal date value is a pair of either and a RelativeDatePeriod, the absolute
/** @class GncOptionDateValue
* A legal date value is a pair of either a RelativeDatePeriod, the absolute
* flag and a time64, or for legacy purposes the absolute flag and a timespec.
*/
/*
Expand Down Expand Up @@ -1076,7 +1060,7 @@ operator>> <GncOptionDateValue>(std::istream& iss,
return opt.in_stream(iss);
}

/** QofQuery Options
*/

#endif //GNC_OPTION_IMPL_HPP_
/**@}
@} */

0 comments on commit 96b09de

Please sign in to comment.