44
calibre User Manual, Release 2.57.1
• loc_or_xpath –Should be an XPath expression such as //h:div[@id=”split_here”]. Can
also be a loc which is used internally to implement splitting in the preview panel.
• before – If True the split occurs before the identified element otherwise after it.
• totals – Used internally
calibre.ebooks.oeb.polish.split.multisplit(container,name, xpath, before=True)
Split the specified file at multiple locations (all tags that match the specified XPath expression. See also:
split()(page289).Splittingautomaticallymigratesalllinksandreferencestotheaffectedfiles.
Parameters before – If True the splits occur before the identified element otherwise after it.
calibre.ebooks.oeb.polish.split.merge(container,category, names, master)
Merge the specified files into a single file, automatically migrating all links and references to the affected files.
The file must all either be HTML or CSS files.
Parameters
• category – Must be either ’text’ for HTML files or ’styles’ for CSS files
• names – The list of files to be merged
• master – Which ofthe merged files is the master file,that is, the file that willremainafter
merging.
Managing covers
calibre.ebooks.oeb.polish.cover.set_cover(container, cover_path, report=None, op-
tions=None)
Set the coverof the book to the image pointedto by cover_path.
Parameters
• cover_path –Either the absolute path toan image file orthe canonical name of animage
in the book. When using an image in the book,you must also set options,see below.
• report – An optional callable that takes a single argument. It will be called with informa-
tion about the tasks being processed.
• options – None or a dictionary that controls how the cover is set. The dictionary can
haveentries: keep_aspect: True orFalse (Preserve aspectratio of covers in EPUB)no_svg:
True or False (Use an SVG cover wrapper in the EPUB titlepage) existing: True or False
(cover_path refers to an existing image in the book)
calibre.ebooks.oeb.polish.cover.mark_as_cover(container,name)
Mark the specified image as the cover image.
calibre.ebooks.oeb.polish.cover.mark_as_titlepage(container,
name,
move_to_start=True)
Mark the specified HTML file as the titlepage of the EPUB.
Parameters move_to_start –If True the HTML file is moved to the start ofthe spine
Workingwith CSS
calibre.ebooks.oeb.polish.fonts.change_font(container,old_name,new_name=None)
Change a font family from old_name to new_name. Changes all occurrences of the font family in stylesheets,
style tags and style attributes. If the old_name refers to an embeddedfont,it is removed. Youcan set new_name
to None to remove the font family insteadof changing it.
290
Chapter 1. Sections
How to C#: Basic SDK Concept of XDoc.PDF for .NET You may add PDF document protection functionality into your C# program. To be specific, you can edit PDF password and digital signature, and set PDF file
add fillable fields to pdf online; changing font size in pdf form VB.NET PDF: Basic SDK Concept of XDoc.PDF You may add PDF document protection functionality into your VB.NET program. To be specific, you can edit PDF password and digital signature, and set PDF file
add text field pdf; pdf form creation
44
calibre User Manual, Release 2.57.1
calibre.ebooks.oeb.polish.css.remove_unused_css(container,
report=None,
re-
move_unused_classes=False)
Remove allunused CSS rules fromthe book. An unused CSSrule is one that does notmatch any actual content.
Parameters
• report – An optional callable that takes a single argument. It is called with information
about the operations being performed.
• remove_unused_classes – If True, class attributes in the HTML that do not match
any CSS rules are also removed.
calibre.ebooks.oeb.polish.css.filter_css(container,properties, names=())
Remove the specified CSSproperties from all CSS rules in the book.
Parameters
• properties – Set of properties to remove. For example: {’font-family’,
’color’}.
• names – The files from which to remove the properties. Defaults to all HTML and CSS
files in the book.
Workingwith the Table of Contents
calibre.ebooks.oeb.polish.toc.from_xpaths(container,xpaths)
Generate a Table of Contents froma list of XPath expressions. Each expression in the list corresponds to a level
ofthe generate ToC. For example: [’//h:h1’, ’//h:h2’, ’//h:h3’] will generate a three level table
of contents fromthe <h1>,<h2> and <h3> tags.
calibre.ebooks.oeb.polish.toc.from_links(container)
Generate a Table of Contents fromlinks in the book.
calibre.ebooks.oeb.polish.toc.from_files(container)
Generate a Table of Contents fromfiles in the book.
calibre.ebooks.oeb.polish.toc.create_inline_toc(container, title=None)
Create an inline (HTML)Table ofContents from an existing NCXtable of contents.
Parameters title – The title forthis table of contents.
Edit Book Tool
class calibre.gui2.tweak_book.plugin.Tool
Bases: object The base class forindividual tools in an Edit Book plugin. Useful members include:
•self.plugin: A reference to thecalibre.customize.Plugin (page 192) object to which this
tool belongs.
•self.boss (page 292)
•self.gui (page 292)
Methods that must be overridden in sub classes:
•create_action() (page 292)
•register_shortcut() (page 292)
name = None
Set this to a unique name it will be used as a key
1.12. Setting up a calibre development environment
291
50
calibre User Manual, Release 2.57.1
allowed_in_toolbar = True
If True the user can choose to place this tool in the plugins toolbar
allowed_in_menu = True
If True the user can choose to place this tool in the plugins menu
toolbar_button_popup_mode = u’delayed’
The popup mode for the menu (if any) of the toolbar button. Possible values are ‘delayed’, ‘instant’,
‘button’
boss
Thecalibre.gui2.tweak_book.boss.Boss (page 293) object. Used to control the user inter-
face.
gui
The main window ofthe userinterface
current_container
Return the currentcalibre.ebooks.oeb.polish.container.Container (page 285) object
that represents the book being edited.
register_shortcut(qaction, unique_name, default_keys=(), short_text=None, description=None,
**extra_data)
Register a keyboard shortcutthatwill trigger the specified qaction. This keyboard shortcut will become
automatically customizable by the user in the Keyboardsection of the editor preferences.
Parameters
• qaction – A QAction object, it will be triggered when the configured key combination
is pressedby the user.
• unique_name – A unique name for this shortcut/action. It will be used internally, it
must not be shared by any other actions in this plugin.
• default_keys – A list of the default keyboard shortcuts. If not specified no default
shortcuts will be set. If the shortcuts specified here conflict with either builtin short-
cuts or shortcuts from user configuration/other plugins, they will be ignored. In that
case, users will have to configure the shortcuts manually via Preferences. For example:
default_keys=(’Ctrl+J’, ’F9’).
• short_text – An optionalshort description ofthis action. Ifnot specifiedthe textfrom
the QAction will be used.
• description – An optional longer description of this action, it will be used in the
preferences entry for this shortcut.
create_action(for_toolbar=True)
Create a QAction that will be added to either the plugins toolbar or the plugins menu depending on
for_toolbar. For example:
def create_action(self, for_toolbar=True):
ac = QAction(get_icons('myicon.png'), , 'Do something')
if for_toolbar:
# We want the toolbar button to have a popup menu
menu = QMenu()
ac.setMenu(menu)
menu.addAction('Do something g else')
subaction = menu.addAction('And another')
# Register a keyboard shortcut for this toolbar action be
# careful to do this for only one of the toolbar action or
# the menu action, not both.
292
Chapter 1. Sections
42
calibre User Manual, Release 2.57.1
self.register_shortcut(ac, 'some-unique-name', default_keys=('Ctrl+K',))
return ac
See also:
Methodregister_shortcut() (page 292).
Controlling the editor’s user interface
The ebook editor’s user interface is controlled by a single global Boss object. This has many useful methods that can
be used in plugin code to perform common tasks.
class calibre.gui2.tweak_book.boss.Boss(parent, notify=None)
add_savepoint(msg)
Create a restore checkpoint with the name specified as msg
apply_container_update_to_gui(mark_as_modified=True)
Update all the components of the user interface toreflect the latest data in the current book container.
Parameters mark_as_modified – If True,the book will be marked as modified, so the user
will be prompted to save it when quitting.
close_editor(name)
Close the editor that is editing the file specified by name
commit_all_editors_to_container()
Commit any changes that the user has made to files open in editors to the container. You should call this
method before performing any actions on the current container
currently_editing
Return the name of the file being edited currently or None if no file is being edited
edit_file(name,syntax=None, use_template=None)
Open the file specified by name in an editor
Parameters
• syntax – The media type of the file, for example, ’text/html’. If not specified it is
guessed from the file extension.
• use_template – A template to initialize the opened editor with
open_book(path=None,edit_file=None, clear_notify_data=True, open_folder=False)
Open the ebook at path for editing. Will show an error if the ebook is not in a supported format or the
current book has unsaved changes.
Parameters edit_file – The name of a file inside the newly opened book to start editing.
Can also be a list ofnames.
rewind_savepoint()
Undo the previous creation of a restore checkpoint, useful if you create a checkpoint,then abort the oper-
ation with no changes
save_book()
Save the book. Saving is performed in the background
set_modified()
Mark the book as having been modified
1.12. Setting up a calibre development environment
293
43
calibre User Manual, Release 2.57.1
show_current_diff(allow_revert=True, to_container=None)
Show the changes to the book from its last checkpointed state
Parameters
• allow_revert – If True the diffdialog will have a button to allow the user to revert all
changes
• to_container – A container object to compare the current container to. If None, the
previously checkpointed container is used
show_editor(name)
Show the editor that is editing the file specified by name
sync_preview_to_editor()
Sync the position ofthe preview panel to the current cursor position in the current editor
1.13 Glossary
RSS RSS (Really Simple Syndication) is a web feed format that is used to publish frequently updated content, like
news articles, blogposts, etc. Itis a formatthat is particularly suitedto being read by computers,andis therefore
the preferred way of getting content from the web into an ebook. There are many other feed formats in use on
the Internet, and calibre understands most of them. In particular, it has good support for the ATOM format,
which is commonly used for blogs.
recipe A recipe is a set of instructions that teach calibre how to convert an online news source, such as a magazine
or a blog, into an ebook. A recipe is essentiallyPython
115
code. As such, it is capable of converting arbitrarily
complex news sources into ebooks. At the simplest level, it is just a set of variables, such as URLs, that give
calibre enough information to go out onto the Internet and download the news.
HTML HTML (Hyper Text Mark-UpLanguage),a subsetofStandard Generalized Mark-UpLanguage (SGML) for
electronic publishing, is the specific standard used for the World Wide Web.
CSS CSS(Cascading StyleSheets)is alanguage usedtodescribe howanHTMLdocumentshould be rendered(visual
styling).
API API (Application Programming Interface) is a source code interface that a library provides to support requests
for services to be made of it by computer programs.
LRF LRF The ebook format that is read by the SONY ebook readers.
URL URL (Uniform Resource Locator) for example: http://example.com
regexp Regular expressions provide a concise and flexible means for identifying strings of text of interest, such as
particularcharacters,words,or patterns of characters. Seeregexpsyntax
116
forthesyntax ofregularexpressions
used in Python.
115
https://www.python.org
116
https://docs.python.org/2.7/library/re.html
294
Chapter 1. Sections
22
Python Module Index
c
calibre.customize,192
calibre.customize.conversion,199
calibre.db.cache,279
calibre.devices.interface,201
calibre.ebooks.metadata.book.base,153
calibre.ebooks.metadata.sources.base,
196
calibre.ebooks.oeb.polish.container,285
calibre.ebooks.oeb.polish.cover,290
calibre.ebooks.oeb.polish.css,290
calibre.ebooks.oeb.polish.jacket,289
calibre.ebooks.oeb.polish.pretty,289
calibre.ebooks.oeb.polish.replace,288
calibre.ebooks.oeb.polish.split,289
calibre.ebooks.oeb.polish.toc,291
calibre.gui2.tweak_book.boss,293
calibre.gui2.tweak_book.plugin.Tool,291
calibre.utils.formatter_functions,144
calibre.web.feeds.news,42
295
3
calibre User Manual, Release 2.57.1
296
Python Module Index
Documents you may be interested
Documents you may be interested