64
edits
Changes
→Options class: Clarifications
===Options class===
* In general Options class should derive from [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.ReportOptions ReportOptions] class. Usually But usually for a common report the <tt>MenuReportOptions</tt> class should be derived from. <tt>MenuReportOptions</tt> is used instead, which will abstract most of the lower-level widget handling below.
====Using ReportOptions====
</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 methods 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):
self.options_dict['my_second_option'] = unicode(self.the_string_entry.get_text())
self.options_dict['my_first_option'] = self.the_menu.get_history()
</pre>
====Using MenuReportOptions====
The [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.MenuReportOptions MenuReportOptions] can be 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 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()] function (method which is a required function must be overridden when you inherit inheriting from [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.report._options.MenuReportOptions MenuReportOptions]). For example:
<pre>
</pre>
In this example a [https://www.gramps-project.org/docs/gen/gen_plug.html#gramps.gen.plug.menu._booleanlist.BooleanListOption BooleanListOption] object <tt>what_types</tt> is created that presents the user with a group of check boxes, one is created 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 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 the report dialog.
Then to access the selected values once the user runs the report, you make a call the menu object from within the report's <tt>__init__</tt> function. For example, to access the "what_types" that are selected from the menu above you would add the following code:
</pre>
In the example, the option class 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()] functionmethod. 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_option.get_selected()] and stored as a class member instance variable <tt>self.what_types</tt> for later use. ====Defining user-adjustable paragraph styles ==== 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' stylesheet: <pre>def make_default_style(self, default_style): f = docgen.FontStyle() f.set_size(10) f.set_type_face(docgen.FONT_SANS_SERIF) p = docgen.ParagraphStyle() p.set_font(f) p.set_description(_("The style used for the person's name.")) default_style.add_style("ABC-Name",p)</pre>
==Implementation==