zim.gui.pageview.PageView

class documentation

class PageView(GSignalEmitterMixin, Gtk.VBox): (source)

Known subclasses: zim.gui.notebookview.NotebookView

Widget to display a single page, consists of a TextView and a FindBar. Also adds menu items and in general integrates the TextView with the rest of the application.

Unknown Field: signal
`modified-changed ()`: emitted when the page is edited
`textstyle-changed (style)`: Emitted when textstyle at the cursor changes, gets the list of text styles or None.
`activate-link (link, hints)`: emitted when a link is opened, stops emission after the first handler returns `True`
Unknown Field: todo
document preferences supported by PageView
document extra keybindings implemented in this widget
document style properties supported by this widget

Method	`__init__`	Constructor @param notebook: the `Notebook` object @param navigation: `NavigationModel` object
Method	`activate_link`	Undocumented
Method	`apply_format_bullet_list`	Menu action to format selection as bullet list
Method	`apply_format_checkbox_list`	Menu action to format selection as checkbox list
Method	`apply_format_numbered_list`	Menu action to format selection as numbered list
Method	`attach_file`	Menu action to show the `AttachFileDialog` @param file: optional file to suggest in the dialog
Method	`autoselect`	Auto select either a word or a line.
Method	`clear_formatting`	Menu item to remove formatting from current (auto-)selection
Method	`clear_heading_format`	Menu item to remove heading
Method	`clear_list_format`	Menu action to remove list formatting
Method	`copy`	Menu action for copy to clipboard
Method	`copy_current_line`	Menu action to copy the current line to the clipboard
Method	`cut`	Menu action for cut to clipboard
Method	`delete`	Menu action for delete
Method	`do_activate_link`	Undocumented
Method	`do_mark_set`	@emits link-caret-enter @emits link-caret-leave
Method	`do_populate_popup`	Undocumented
Method	`do_textstyle_changed`	Undocumented
Method	`do_toggle_format_action`	Handler that catches all actions to apply and/or toggle formats
Method	`do_toggle_format_action_alt`	Undocumented
Method	`edit_object`	Menu action to trigger proper edit dialog for the current object at the cursor
Method	`find`	Find some string in the text, scroll there and select it
Method	`find_next`	Menu action to skip to next match
Method	`find_previous`	Menu action to go back to previous match
Method	`get_cursor_pos`	Get the cursor position in the buffer
Method	`get_scroll_pos`	Undocumented
Method	`get_selection`	Convenience method to get the text of the current selection.
Method	`get_word`	Convenience method to get the word that is under the cursor
Method	`grab_focus`	Undocumented
Method	`hide_find`	Hide the `FindBar` widget
Method	`insert_bullet_list`	Menu action insert a bullet item at the cursor
Method	`insert_checkbox_list`	Menu action insert an open checkbox at the cursor
Method	`insert_date`	Menu action to insert a date, shows the `InsertDateDialog`
Method	`insert_image`	Insert a image @param file: the image file to insert. If `file` does not exist or isn't an image, a "broken image" icon will be shown
Method	`insert_line`	Menu action to insert a line at the cursor position
Method	`insert_link`	Menu item to show the `InsertLinkDialog`
Method	`insert_links`	Non-interactive method to insert one or more links
Method	`insert_new_file`	Undocumented
Method	`insert_numbered_list`	Menu action insert a numbered list item at the cursor
Method	`insert_object`	Undocumented
Method	`insert_object_model`	Undocumented
Method	`insert_text_from_file`	Menu action to show a `InsertTextFromFileDialog`
Method	`migrate_checkbox`	Menu action to toggle checkbox at the cursor or in current selected text
Method	`navigate_to_anchor`	Navigate to an anchor on the current page. @param name: The name of the anchor to navigate to @param select_line: Select the whole line after
Method	`on_insertedobjecttypemap_changed`	Undocumented
Method	`on_link_enter`	Undocumented
Method	`on_link_leave`	Undocumented
Method	`on_modified_changed`	Undocumented
Method	`on_preferences_changed`	Undocumented
Method	`on_text_style_changed`	(Re-)intializes properties for TextView, TextBuffer and TextTags based on the properties in the style config.
Method	`open_file_templates_folder`	Menu action to open the templates folder
Method	`paste`	Menu action for paste from clipboard
Method	`redo`	Menu action to redo a single step
Method	`reload_page`	Menu action to reload the current page. Will first try to save any unsaved changes, then reload the page from disk.
Method	`remove_link`	Menu action to remove link object at the current cursor position
Method	`replace_selection`	Undocumented
Method	`save_changes`	Save contents of the widget back to the page object and synchronize it with the notebook.
Method	`save_page`	Menu action to save the current page.
Method	`scroll_cursor_on_screen`	Undocumented
Method	`set_cursor_pos`	Set the cursor position in the buffer and scroll the TextView to show it
Method	`set_edit_bar_visible`	Undocumented
Method	`set_page`	Set the current page to be displayed in the pageview
Method	`set_readonly`	Set the widget read-only or not
Method	`set_scroll_pos`	Undocumented
Method	`show_find`	Show the `FindBar` widget
Method	`show_find_and_replace`	Menu action to show the `FindAndReplaceDialog`
Method	`show_insert_image`	Menu action to insert an image, shows the `InsertImageDialog` @param file: optional file to suggest in the dialog
Method	`show_word_count`	Menu action to show the `WordCountDialog`
Method	`toggle_checkbox`	Menu action to toggle checkbox at the cursor or in current selected text
Method	`toggle_format`	Toggle the format for the current (auto-)selection or new insertions at the current cursor position
Method	`transmigrate_checkbox`	Menu action to toggle checkbox at the cursor or in current selected text
Method	`uncheck_checkbox`	Undocumented
Method	`undo`	Menu action to undo a single step
Method	`xtoggle_checkbox`	Menu action to toggle checkbox at the cursor or in current selected text
Method	`zoom_in`	Menu action to increase the font size
Method	`zoom_out`	Menu action to decrease the font size
Method	`zoom_reset`	Menu action to reset the font size
Class Variable	`__gsignals__`	Undocumented
Class Variable	`__signals__`	Undocumented
Instance Variable	`edit_bar`	Undocumented
Instance Variable	`find_bar`	the `FindBar` child widget
Instance Variable	`navigation`	Undocumented
Instance Variable	`notebook`	Undocumented
Instance Variable	`overlay`	Undocumented
Instance Variable	`page`	`Page` object for the current page displayed in the widget
Instance Variable	`preferences`	a `ConfigDict` with preferences
Instance Variable	`readonly`	`True` when the widget is read-only, see `set_readonly()` for details
Instance Variable	`swindow`	Undocumented
Instance Variable	`text_style`	a `ConfigSectionsDict` with style properties. Although this is a class attribute loading the data from the config file is delayed till the first object is constructed
Instance Variable	`textview`	Undocumented
Instance Variable	`ui_is_initialized`	Undocumented
Instance Variable	`view`	the `TextView` child object
Method	`_apply_bullet`	Undocumented
Method	`_checkbox_do_populate_popup`	Undocumented
Method	`_connect_focus_event`	Undocumented
Method	`_create_textbuffer`	Undocumented
Method	`_default_do_populate_popup`	Undocumented
Method	`_do_activate_link`	Undocumented
Method	`_hack_on_inserted_tree`	Undocumented
Method	`_set_edit_bar_visible`	Undocumented
Method	`_set_menuitems_sensitive`	Batch update global menu sensitivity while respecting sensitivities set due to cursor position, readonly state etc.
Method	`_start_bullet`	Undocumented
Method	`_update_new_file_submenu`	Undocumented
Method	`_update_readonly`	Undocumented
Method	`_zoom_increase_decrease_font_size`	Undocumented
Instance Variable	`_buffer_signals`	Undocumented
Instance Variable	`_caret_link`	Undocumented
Instance Variable	`_edit_bar_visible`	Undocumented
Instance Variable	`_hack_hbox`	Undocumented
Instance Variable	`_hack_label`	Undocumented
Instance Variable	`_insertedobject_manager`	Undocumented
Instance Variable	`_overlay_label`	Undocumented
Instance Variable	`_readonly_set`	Undocumented
Instance Variable	`_readonly_set_error`	Undocumented
Instance Variable	`_save_page_handler`	Undocumented
Instance Variable	`_undo_history_queue`	Undocumented

Inherited from GSignalEmitterMixin:

Method	`connect`	Undocumented
Method	`connect_after`	Undocumented
Method	`disconnect`	Undocumented
Method	`emit_return_first`	Undocumented
Method	`emit_return_iter`	Undocumented
Instance Variable	`_signal_hooks`	Undocumented
Instance Variable	`_signals_inner`	Undocumented

def __init__(self, notebook, navigation): (source)

overrides zim.signals.GSignalEmitterMixin.__init__

Constructor

Parameters
notebook	the `Notebook` object
navigation	`NavigationModel` object

def activate_link(self, link, new_window=False): (source)

Undocumented

@action(_('Bulle_t List'), menuhints='edit')
def apply_format_bullet_list(self): (source)

Menu action to format selection as bullet list

@action(_('Checkbo_x List'), menuhints='edit')
def apply_format_checkbox_list(self): (source)

Menu action to format selection as checkbox list

@action(_('_Numbered List'), menuhints='edit')
def apply_format_numbered_list(self): (source)

Menu action to format selection as numbered list

@action(_('_Attachment...'), verb_icon='zim-attachment', menuhints='insert')
def attach_file(self, file=None): (source)

Menu action to show the AttachFileDialog

Parameters
file	optional file to suggest in the dialog

def autoselect(self, selectline=False): (source)

Auto select either a word or a line.

Does not do anything if a selection is present already or when the preference for auto-select is set to False.

Parameters
selectline	if `True` auto-select a whole line, only auto-select a single word otherwise
Returns
`True` when this function changed the selection.

@action(_('_Clear Formatting'), accelerator='<Primary>9', menuhints='edit', verb_icon='edit-clear-all-symbolic')
def clear_formatting(self): (source)

Menu item to remove formatting from current (auto-)selection

@action(_('_Remove Heading'), menuhints='edit')
def clear_heading_format(self): (source)

Menu item to remove heading

@action(_('_Remove List'), menuhints='edit')
def clear_list_format(self): (source)

Menu action to remove list formatting

@action(_('_Copy'), '<Primary>C', menuhints='edit')
def copy(self): (source)

Menu action for copy to clipboard

@action(_('Copy Line'), accelerator='<Primary><Shift>C', menuhints='edit')
def copy_current_line(self): (source)

Menu action to copy the current line to the clipboard

@action(_('Cu_t'), '<Primary>X', menuhints='edit')
def cut(self): (source)

Menu action for cut to clipboard

@action(_('_Delete'), menuhints='edit')
def delete(self): (source)

Menu action for delete

def do_activate_link(self, link, hints): (source)

Undocumented

def do_mark_set(self, buffer, iter, mark): (source)

@emits link-caret-enter @emits link-caret-leave

def do_populate_popup(self, menu): (source)

Undocumented

def do_textstyle_changed(self, styles): (source)

Undocumented

def do_toggle_format_action(self, action): (source)

Handler that catches all actions to apply and/or toggle formats

def do_toggle_format_action_alt(self, active, action): (source)

Undocumented

@action(_('_Edit Link or Object...'), '<Primary>E', menuhints='edit')
def edit_object(self, iter=None): (source)

Menu action to trigger proper edit dialog for the current object at the cursor

Can show e.g. InsertLinkDialog for a link, EditImageDialog for the a image, or a plugin dialog for e.g. an equation.

Parameters
iter	`TextIter` for an alternative cursor position

def find(self, string, flags=0): (source)

Find some string in the text, scroll there and select it

Parameters
string	the text to find
flags	options for find behavior, see `TextFinder.find()`

@action(_('Find Ne_xt'), accelerator='<Primary>G', alt_accelerator='F3')
def find_next(self): (source)

Menu action to skip to next match

@action(_('Find Pre_vious'), accelerator='<Primary><shift>G', alt_accelerator='<shift>F3')
def find_previous(self): (source)

Menu action to go back to previous match

def get_cursor_pos(self): (source)

Get the cursor position in the buffer

Returns
the cursor position as an integer offset from the start of the buffer

def get_scroll_pos(self): (source)

Undocumented

def get_selection(self, format=None): (source)

Convenience method to get the text of the current selection.

Parameters
format	format to use for the formatting of the returned text (e.g. 'wiki' or 'html'). If the format is `None` only the text will be returned without any formatting.
Returns
text selection or `None`

def get_word(self, format=None): (source)

Convenience method to get the word that is under the cursor

Parameters
format	format to use for the formatting of the returned text (e.g. 'wiki' or 'html'). If the format is `None` only the text will be returned without any formatting.
Returns
current word or `None`

def grab_focus(self): (source)

Undocumented

def hide_find(self): (source)

Hide the FindBar widget

@action(_('Bulle_t List'), menuhints='insert')
def insert_bullet_list(self): (source)

Menu action insert a bullet item at the cursor

@action(_('Checkbo_x List'), menuhints='insert')
def insert_checkbox_list(self): (source)

Menu action insert an open checkbox at the cursor

@action(_('Date and Time...'), accelerator='<Primary>D', menuhints='insert')
def insert_date(self): (source)

Menu action to insert a date, shows the InsertDateDialog

def insert_image(self, file): (source)

Insert a image

Parameters
file	the image file to insert. If `file` does not exist or isn't an image, a "broken image" icon will be shown

@action(_('Horizontal _Line'), menuhints='insert')
def insert_line(self): (source)

Menu action to insert a line at the cursor position

@action(_('_Link...'), '<Primary>L', verb_icon='zim-link', menuhints='insert')
def insert_link(self): (source)

Menu item to show the InsertLinkDialog

def insert_links(self, links): (source)

Non-interactive method to insert one or more links

Inserts the links separated by newlines. Intended e.g. for drag-and-drop or copy-paste actions of e.g. files from a file browser.

Parameters
links	list of links, either as string, `Path` objects, or `File` objects

def insert_new_file(self, template, basename=None): (source)

Undocumented

@action(_('_Numbered List'), menuhints='insert')
def insert_numbered_list(self): (source)

Menu action insert a numbered list item at the cursor

def insert_object(self, attrib, data): (source)

Undocumented

def insert_object_model(self, otype, model): (source)

Undocumented

@action(_('Text From _File...'), menuhints='insert')
def insert_text_from_file(self): (source)

Menu action to show a InsertTextFromFileDialog

@action(_('Toggle Checkbox \'>\''), verb_icon=STOCK_MIGRATED_BOX, menuhints='edit')
def migrate_checkbox(self): (source)

Menu action to toggle checkbox at the cursor or in current selected text

def navigate_to_anchor(self, name, select_line=False, fail_silent=False): (source)

Navigate to an anchor on the current page.

Parameters
name	The name of the anchor to navigate to
select_line	Select the whole line after
fail_silent	Undocumented

def on_insertedobjecttypemap_changed(self, *a): (source)

Undocumented

def on_link_enter(self, view, link): (source)

Undocumented

def on_link_leave(self, view, link): (source)

Undocumented

def on_modified_changed(self, buffer): (source)

Undocumented

def on_preferences_changed(self, *a): (source)

Undocumented

def on_text_style_changed(self, *a): (source)

(Re-)intializes properties for TextView, TextBuffer and TextTags based on the properties in the style config.

@action(_('File _Templates...'))
def open_file_templates_folder(self): (source)

Menu action to open the templates folder

@action(_('_Paste'), '<Primary>V', menuhints='edit')
def paste(self): (source)

Menu action for paste from clipboard

@action(_('_Redo'), '<Primary><shift>Z', alt_accelerator='<Primary>Y', menuhints='edit')
def redo(self): (source)

Menu action to redo a single step

@action(_('_Reload'), '<Primary>R')
def reload_page(self): (source)

Menu action to reload the current page. Will first try to save any unsaved changes, then reload the page from disk.

@action(_('_Remove Link'), menuhints='edit')
def remove_link(self, iter=None): (source)

Menu action to remove link object at the current cursor position

Parameters
iter	`TextIter` for an alternative cursor position

def replace_selection(self, text, autoselect=None): (source)

Undocumented

def save_changes(self, write_if_not_modified=False): (source)

Save contents of the widget back to the page object and synchronize it with the notebook.

Parameters
write_if_not_modified	If `True` page will be written even if it is not changed. (This allows e.g. to force saving template content to disk without editing.)

@action(_('_Save'), '<Primary>S', menuhints='edit')
def save_page(self): (source)

Menu action to save the current page.

Can result in a SavePageErrorDialog when there is an error while saving a page. If that dialog is cancelled by the user, the page may not be saved after all.

def scroll_cursor_on_screen(self): (source)

Undocumented

def set_cursor_pos(self, pos): (source)

Set the cursor position in the buffer and scroll the TextView to show it

Parameters

pos

the cursor position as an integer offset from the start of the buffer

As a special case when the cursor position is -1 the cursor is set at the end of the buffer.

def set_edit_bar_visible(self, visible): (source)

Undocumented

def set_page(self, page, cursor=None): (source)

Set the current page to be displayed in the pageview

When the page does not yet exist a template is loaded for a new page which is obtained from Notebook.get_template().

Exceptions while loading the page are handled gracefully with an error dialog and will result in the widget to be read-only and insensitive until the next page is loaded.

Parameters

page a Page object

cursor

optional cursor position (integer)

When the cursor is set to -1 the cursor will be placed at the end of the buffer.

If cursor is None the cursor is set at the start of the page for existing pages or to the end of the template when the page does not yet exist.

def set_readonly(self, readonly): (source)

Set the widget read-only or not

Sets the read-only state but also update menu items etc. to reflect the new state.

Parameters

readonly

True or False to set the read-only state

Effective read-only state seen in the self.readonly attribute is in fact True (so read-only) when either the widget itself OR the current page is read-only. So setting read-only to False here may not immediately change self.readonly if a read-only page is loaded.

def set_scroll_pos(self, pos): (source)

Undocumented

@action(_('_Find...'), '<Primary>F', alt_accelerator='<Primary>F3')
def show_find(self, string=None, flags=0, highlight=False): (source)

Show the FindBar widget

Parameters
string	the text to find
flags	options for find behavior, see `TextFinder.find()`
highlight	if `True` highlight the results

@action(_('_Replace...'), '<Primary>H', menuhints='edit')
def show_find_and_replace(self): (source)

Menu action to show the FindAndReplaceDialog

@action(_('_Image...'), menuhints='insert')
def show_insert_image(self, file=None): (source)

Menu action to insert an image, shows the InsertImageDialog

Parameters
file	optional file to suggest in the dialog

@action(_('Word Count...'))
def show_word_count(self): (source)

Menu action to show the WordCountDialog

@action(_('Toggle Checkbox \'V\''), 'F12', verb_icon=STOCK_CHECKED_BOX, menuhints='edit')
def toggle_checkbox(self): (source)

Menu action to toggle checkbox at the cursor or in current selected text

def toggle_format(self, format): (source)

Toggle the format for the current (auto-)selection or new insertions at the current cursor position

When the cursor is at the begin or in the middle of a word and there is not selection, the word is selected automatically to toggle the format. For headings and other line based formats auto-selects the whole line.

This is the handler for all the format actions.

Parameters
format	the format style name (e.g. "h1", "strong" etc.)

@action(_('Toggle Checkbox \'<\''), verb_icon=STOCK_TRANSMIGRATED_BOX, menuhints='edit')
def transmigrate_checkbox(self): (source)

Menu action to toggle checkbox at the cursor or in current selected text

@action(_('Un-check Checkbox'), verb_icon=STOCK_UNCHECKED_BOX, menuhints='edit')
def uncheck_checkbox(self): (source)

Undocumented

@action(_('_Undo'), '<Primary>Z', menuhints='edit')
def undo(self): (source)

Menu action to undo a single step

@action(_('Toggle Checkbox \'X\''), '<shift>F12', verb_icon=STOCK_XCHECKED_BOX, menuhints='edit')
def xtoggle_checkbox(self): (source)

Menu action to toggle checkbox at the cursor or in current selected text

@action(_('_Zoom In'), '<Primary>plus', alt_accelerator='<Primary>equal')
def zoom_in(self): (source)

Menu action to increase the font size

@action(_('Zoom _Out'), '<Primary>minus')
def zoom_out(self): (source)

Menu action to decrease the font size

@action(_('_Normal Size'), '<Primary>0')
def zoom_reset(self): (source)

Menu action to reset the font size

__gsignals__ = (source)

Undocumented

__signals__ = (source)

Undocumented

edit_bar = (source)

Undocumented

find_bar = (source)

the FindBar child widget

navigation = (source)

Undocumented

notebook = (source)

Undocumented

overlay = (source)

Undocumented

page = (source)

Page object for the current page displayed in the widget

preferences = (source)

a ConfigDict with preferences

readonly = (source)

True when the widget is read-only, see set_readonly() for details

swindow = (source)

Undocumented

text_style = (source)

a ConfigSectionsDict with style properties. Although this is a class attribute loading the data from the config file is delayed till the first object is constructed

textview = (source)

Undocumented

ui_is_initialized: bool = (source)

Undocumented

view = (source)

the TextView child object

def _apply_bullet(self, bullet_type): (source)

Undocumented

def _checkbox_do_populate_popup(self, menu, buffer, iter): (source)

Undocumented

def _connect_focus_event(self): (source)

Undocumented

def _create_textbuffer(self, parsetree=None): (source)

Undocumented

def _default_do_populate_popup(self, menu): (source)

Undocumented

def _do_activate_link(self, link, hints): (source)

Undocumented

def _hack_on_inserted_tree(self, *a): (source)

Undocumented

def _set_edit_bar_visible(self, visible): (source)

Undocumented

def _set_menuitems_sensitive(self, sensitive, force_sensitive=()): (source)

Batch update global menu sensitivity while respecting sensitivities set due to cursor position, readonly state etc.

def _start_bullet(self, bullet_type): (source)

Undocumented

def _update_new_file_submenu(self, action): (source)

Undocumented

def _update_readonly(self): (source)

Undocumented

def _zoom_increase_decrease_font_size(self, plus_or_minus): (source)

Undocumented

_buffer_signals = (source)

Undocumented

_caret_link = (source)

Undocumented

_edit_bar_visible = (source)

Undocumented

_hack_hbox = (source)

Undocumented

_hack_label = (source)

Undocumented

_insertedobject_manager = (source)

Undocumented

_overlay_label = (source)

Undocumented

_readonly_set = (source)

Undocumented

_readonly_set_error: bool = (source)

Undocumented

_save_page_handler = (source)

Undocumented

_undo_history_queue: list = (source)

Undocumented