See CreateNewCustomColumn in calibre.gui2.preferences.create_custom_column.py
Spoiler:
Code:
class CreateNewCustomColumn:
"""
Provide an API to create new custom columns.
Usage:
from calibre.gui2.preferences.create_custom_column import CreateNewCustomColumn
creator = CreateNewCustomColumn(gui)
if creator.must_restart():
...
else:
result = creator.create_column(....)
if result[0] == creator.Result.COLUMN_ADDED:
The parameter 'gui' passed when creating a class instance is the main
calibre gui (calibre.gui2.ui.get_gui())
Use the create_column(...) method to open a dialog to create a new custom
column with given lookup_name, column_heading, datatype, and is_multiple.
You can create as many columns as you wish with a single instance of the
CreateNewCustomColumn class. Subsequent class instances will refuse to
create columns until calibre is restarted, as will calibre Preferences.
The lookup name must begin with a '#'. All remaining characters must be
lower case letters, digits or underscores. The character after the '#' must
be a letter. The lookup name must not end with the suffix '_index'.
The datatype must be one of calibre's custom column types: 'bool',
'comments', 'composite', 'datetime', 'enumeration', 'float', 'int',
'rating', 'series', or 'text'. The datatype can't be changed in the dialog.
is_multiple tells calibre that the column contains multiple values -- is
tags-like. The value True is allowed only for 'composite' and 'text' types.
If generate_unused_lookup_name is False then the provided lookup_name and
column_heading must not already exist. If generate_unused_lookup_name is
True then if necessary the method will add the suffix '_n' to the provided
lookup_name to allocate an unused lookup_name, where 'n' is an integer.
The same processing is applied to column_heading to make it is unique, using
the same suffix used for the lookup name if possible. In either case the
user can change the column heading in the dialog.
Set freeze_lookup_name to False if you want to allow the user choose a
different lookup name. The user will not be allowed to choose the lookup
name of an existing column. The provided lookup_name and column_heading
either must not exist or generate_unused_lookup_name must be True,
regardless of the value of freeze_lookup_name.
The 'display' parameter is used to pass item- and type-specific information
for the column. It is a dict. The easiest way to see the current values for
'display' for a particular column is to create a column like you want then
look for the lookup name in the file metadata_db_prefs_backup.json. You must
restart calibre twice after creating a new column before its information
will appear in that file.
The key:value pairs for each type are as follows. Note that this
list might be incorrect. As said above, the best way to get current values
is to create a similar column and look at the values in 'display'.
all types:
'default_value': a string representation of the default value for the
column. Permitted values are type specific
'description': a string containing the column's description
comments columns:
'heading_position': a string specifying where a comment heading goes:
hide, above, side
'interpret_as': a string specifying the comment's purpose:
html, short-text, long-text, markdown
composite columns:
'composite_template': a string containing the template for the composite column
'composite_sort': a string specifying how the composite is to be sorted
'make_category': True or False -- whether the column is shown in the tag browser
'contains_html': True or False -- whether the column is interpreted as HTML
'use_decorations': True or False -- should check marks be displayed
datetime columns:
'date_format': a string specifying the display format
enumerated columns
'enum_values': a string containing comma-separated valid values for an enumeration
'enum_colors': a string containing comma-separated colors for an enumeration
'use_decorations': True or False -- should check marks be displayed
float columns:
'decimals': the number of decimal digits to allow when editing (int). Range: 1 - 9
float and int columns:
'number_format': the format to apply when displaying the column
rating columns:
'allow_half_stars': True or False -- are half-stars allowed
text columns:
'is_names': True or False -- whether the items are comma or ampersand separated
'use_decorations': True or False -- should check marks be displayed
This method returns a tuple (Result.enum_value, message). If tuple[0] is
Result.COLUMN_ADDED then the message is the lookup name including the '#'.
Otherwise it is a potentially localized error message.
You or the user must restart calibre for the column(s) to be actually added.
Result.EXCEPTION_RAISED is returned if the create dialog raises an exception.
This can happen if the display contains illegal values, for example a string
where a boolean is required. The string is the exception text. Run calibre
in debug mode to see the entire traceback.
The method returns Result.MUST_RESTART if further calibre configuration has
been blocked. You can check for this situation in advance by calling
must_restart().