Changes

* In general theory Options class should derive from [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.ReportOptions ReportOptions] class. But usually in pratice for a common report the <tt>[https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.MenuReportOptions</tt> MenuReportOptions] class is used instead, which will abstract most of the lower-level widget handling below. In this tutorial we'll assume that Options class is derived from [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.MenuReportOptions MenuReportOptions].

====Using ReportOptions====<pre>class OptionsClassName(ReportOptions): def __init__(self,name,person_id=None): ReportOptions.__init__(self,name,person_id)</pre>* It should set new options that are specific for this report, by overriding Defining parameters of the <tt>set_new_options()</tt> method which defines <tt>options_dict</tt> and <tt>options_help</tt> dictionaries:<pre>def set_new_options(self): # Options specific for this report self.options_dict = { 'my_first_option' : 0, 'my_second_option' : '', } self.options_help = { 'my_first_option' : ("=num","Number of something", [ "First value", "Second value" ], True), 'my_second_option' : ("=str","Some necessary string for the report", "Whatever String You Wish"), }</pre>* It should also enable the "semi-common" options that are used in this report, by overriding the <tt>enable_options</tt> method which defines <tt>enable_dict</tt> dictionary. The semi-commons are the options which Gramps knows about, but which are not necessarily present in all reports:<pre>def enable_options(self): # Semi-common options that should be enabled for this report self.enable_dict = { 'filter' : 0, }</pre>All the common options are already taken care of by the core of Gramps.* For any new options set up in the options class, there must be defined UI widgets to provide means of changing these options through the dialogs. Also, there must be defined method <tt>parse_user_options</tt> to extract values of these options from the widgets and to set them into the class-variable dictionary <tt>options_dict</tt>:<pre>def add_user_options(self,dialog): option_menu = gtk.OptionMenu() self.the_menu = gtk.Menu()

To define options for item_index in rangeyour report, you need to override <code>MenuReportOptions.add_menu_options(10)</code> method. Then [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.MenuReportOptions MenuReportOptions] class will present the user with a standard menu interface for running the report. You may generate a menu using one or more of the classes available in [https://www.gramps-project.org/docs/gen/gen_plug.html#module-gramps.gen.plug.menu._menu <code>gramps.gen.plug.menu</code>] package such as [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._booleanlist.BooleanListOption BooleanListOption] class. Also you may use standard Gramps options from [https: item = _("Item numer %d") % item_index menuitem = gtk//github.com/gramps-project/gramps/blob/dba1e4e5555694194836d2934542e30c0f75d1b6/gramps/gen/plug/report/stdoptions.py <code>gramps.gen.MenuItem(item) menuitemplug.show() selfreport.the_menustdoptions</code>] module.append(menuitem)For example:

option_menu.set_menu<pre>def add_menu_options(self.the_menu, menu): option_menu """ Add options to the menu for this report.set_history """ category_name = _(self.options_dict['my_first_option']"Report Options")  dialog.add_option what_types = BooleanListOption(_('My first optionReport for'),option_menu)  self what_types.the_string_entry = gtk.Entryadd_button(_() if self.options_dict['my_second_optionMales']:), True) selfwhat_types.the_string_entry.set_textadd_button(_(self.options_dict['my_second_optionFemales']) else:, True) selfwhat_types.the_string_entry.set_textadd_button(_("Empty string"'Unknown gender'), True) self.the_string_entry what_types.show() dialog.add_optionadd_button(_('My second optionOther'),selfTrue) menu.the_string_entryadd_option(category_name, "what_types", what_types)

def parse_user_options stdoptions.add_localization_option(selfmenu,dialog): self.options_dict['my_second_option'] = unicode(self.the_string_entry.get_text()) self.options_dict['my_first_option'] = self.the_menu.get_history(category_name)

====Using MenuReportOptions==== The [https://www.gramps-project.org/docsIn this example <code>category name</gen/gen_plug.html#gramps.gen.plug.report._options.MenuReportOptions MenuReportOptions] can be code> is used in place of [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.ReportOptions ReportOptions] to present the user with a standard interface for running the report. Instead of parsing options, you generate a menu using one or more of tab "Report Options" on the classes available in [https://www.gramps-project.org/docs/gen/gen_plug.html#module-gramps.gen.plug.menu._menu Menu]. All these are initialized in the [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug._options.MenuOptions.add_menu_options add_menu_options()] method which must be overridden when inheriting from [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.reportparameter entry dialog._options.MenuReportOptions MenuReportOptions]). For example:

Object <precode>def add_menu_options(selfwhat_types</code> of class [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._booleanlist.BooleanListOption BooleanListOption] is created that presents the user with a group of check boxes, menu)one is created for each call to [https: """ Add options to the //gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu for this report. """ category_name = _("Report Options") what_types = _booleanlist.BooleanListOption(_('Select From:')) what_types.add_button(_('People'), True) what_types.add_button(_('Families'), False) what_types]. Finally the object is added to the menu with [https://gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._menu.add_button(_('Places'), False) what_typesMenu.add_button(_('Events'), False) add_option menu.add_option(category_name, "what_types", what_types)</pre>].

In this example a [https://wwwFunction <code>stdoptions.gramps-project.orgadd_localization_option()</docs/gen/gen_plug.html#gramps.gen.plug.menu._booleanlist.BooleanListOption BooleanListOption] object code> adds to the same <ttcode>what_typesmenu</ttcode> is created that presents the user with a group of check boxes, one is created standard Gramps option for each call to [https://gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._booleanlist.BooleanListOption.add_button what_types.add_button()]. Finally localizing the object is added to the menu with [https://gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._menu.Menu.add_option menu.add_option()]. The category name is used to generate tabs on report into a different locale from the report dialogUI locale.

Then to access the selected values once the user runs the report, you make a call the menu object from within the report's <ttcode>__init__()</ttcode> functionmethod. For example, to access the "what_types" that are selected from the menu above you would add the following code:

class ExampleReport def __init__(Reportself, database, options_class, user):

def Report.__init__(self, database, options_class, user):

Reportwhat_types_option = options_class.__init__menu.get_option_by_name('what_types') self, database, options_class.what_types = what_types_option.get_selected()

menu_option = self.set_locale( options_class.menu.get_option_by_name('what_types'"trans") self.what_types = menu_option.get_selectedget_value())

In the example, the option <code>what_types_option</code> instance is retrieved by the [https://gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._menu.Menu.get_option_by_name options_class.menu.get_option_by_name()] method. The string passed to the method must match the name you passed as the second argument to [https://gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._menu.Menu.add_option menu.add_option()] when you created the menu. Then a list of the selected item titles is retrieved with [https://gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._booleanlist.BooleanListOption.get_selected menu_optionwhat_types_option.get_selected()] and stored as a instance variable <ttcode>self.what_types</ttcode> for later use. The standard Gramps option for localizing the report has name "trans". Its value is passed to [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._reportbase.Report.set_locale <code>Report.set_locale()</code>] method that creates <code>self._()</code> method for the locale chosen by the report's user. It is then used by <code>write_report()</code> (see below).

If the report uses the user-adjustable paragraph styles the default definitions for the styles must be defined here by overriding method [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.ReportOptions.make_default_style make_default_style()], to form a 'default' stylesheetstyle sheet: