evennia.utils.evmore

EvMore - pager mechanism

This is a pager for displaying long texts and allows stepping up and down in the text (the name comes from the traditional ‘more’ unix command).

To use, simply pass the text through the EvMore object:

from evennia.utils.evmore import EvMore

text = some_long_text_output()
EvMore(caller, text, always_page=False, session=None, justify_kwargs=None, **kwargs)

One can also use the convenience function msg from this module to avoid having to set up the EvMenu object manually:

from evennia.utils import evmore

text = some_long_text_output()
evmore.msg(caller, text, always_page=False, session=None, justify_kwargs=None, **kwargs)

The always_page argument decides if the pager is used also if the text is not long enough to need to scroll, session is used to determine which session to relay to and justify_kwargs are kwargs to pass to utils.utils.justify in order to change the formatting of the text. The remaining **kwargs will be passed on to the caller.msg() construct every time the page is updated.

---

class evennia.utils.evmore.CmdMore(**kwargs)

Bases: evennia.commands.command.Command

Manipulate the text paging

key = '__noinput_command'

aliases = ['b', 'next', 'q', 'abort', 'end', 'quit', 'back', 'e', 't', 'top', 'n', 'a']

auto_help = False

func()

Implement the command

help_category = 'general'

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': 'b next q abort end quit back e t top n a', 'category': 'general', 'key': '__noinput_command', 'tags': '', 'text': '\n Manipulate the text paging\n '}

class evennia.utils.evmore.CmdMoreLook(**kwargs)

Bases: evennia.commands.command.Command

Override look to display window and prevent OOCLook from firing

key = 'look'

aliases = ['l']

auto_help = False

func()

Implement the command

help_category = 'general'

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': 'l', 'category': 'general', 'key': 'look', 'tags': '', 'text': '\n Override look to display window and prevent OOCLook from firing\n '}

class evennia.utils.evmore.CmdSetMore(cmdsetobj=None, key=None)

Bases: evennia.commands.cmdset.CmdSet

Stores the more command

key = 'more_commands'

priority = 110

at_cmdset_creation()

Hook method - this should be overloaded in the inheriting class, and should take care of populating the cmdset by use of self.add().

path = 'evennia.utils.evmore.CmdSetMore'

evennia.utils.evmore.queryset_maxsize(qs)

class evennia.utils.evmore.EvMore(caller, text, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

Bases: object

The main pager object

__init__(caller, text, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

EvMore pager

Parameters

• caller (Object or Account) – Entity reading the text.

• text (str, EvTable or iterator) –

  The text or data to put under paging.

  • If a string, paginate normally. If this text contains one or more \f format symbols, automatic pagination and justification are force-disabled and page-breaks will only happen after each \f.

  • If EvTable, the EvTable will be paginated with the same setting on each page if it is too long. The table decorations will be considered in the size of the page.

  • Otherwise text is converted to an iterator, where each step is expected to be a line in the final display. Each line will be run through iter_callable.

• always_page (bool, optional) – If False, the pager will only kick in if text is too big to fit the screen.

• session (Session, optional) – If given, this session will be used to determine the screen width and will receive all output.

• justify (bool, optional) – If set, auto-justify long lines. This must be turned off for fixed-width or formatted output, like tables. It’s force-disabled if text is an EvTable.

• justify_kwargs (dict, optional) – Keywords for the justifiy function. Used only if justify is True. If this is not set, default arguments will be used.

• exit_on_lastpage (bool, optional) – If reaching the last page without the page being completely filled, exit pager immediately. If unset, another move forward is required to exit. If set, the pager exit message will not be shown.

• exit_cmd (str, optional) – If given, this command-string will be executed on the caller when the more page exits. Note that this will be using whatever cmdset the user had before the evmore pager was activated (so none of the evmore commands will be available when this is run).

• page_formatter (callable, optional) – If given, this function will be passed the contents of each extracted page. This is useful when paginating data consisting something other than a string or a list of strings. Especially queryset data is likely to always need this argument specified. Note however, that all size calculations assume this function to return one single line per element on the page!

• kwargs (any, optional) – These will be passed on to the caller.msg method.

Examples

super_long_text = " ... "
EvMore(caller, super_long_text)

from django.core.paginator import Paginator
query = ObjectDB.objects.all()
pages = Paginator(query, 10)  # 10 objs per page
EvMore(caller, pages)   # will repr() each object per line, 10 to a page

multi_page_table = [ [[..],[..]], ...]
EvMore(caller, multi_page_table, use_evtable=True,
       evtable_args=("Header1", "Header2"),
       evtable_kwargs={"align": "r", "border": "tablecols"})

format_page(page)

Page formatter. Uses the page_formatter callable by default. This allows to easier override the class if needed.

paginator_index(pageno)

Paginate to specific, known index

paginator_slice(pageno)

Paginate by slice. This is done with an eye on memory efficiency (usually for querysets); to avoid fetching all objects at the same time.

init_evtable(table)

The input is an EvTable.

init_queryset(qs)

The input is a queryset

init_iterable(inp)

The input is something other than a string - convert to iterable of strings

init_f_str(text)

The input contains f markers. We use f to indicate the user wants to enforce their line breaks on their own. If so, we do no automatic line-breaking/justification at all.

Parameters

text (str) – The string to format with f-markers.

init_str(text)

The input is a string

display(show_footer=True)

Pretty-print the page.

page_top()

Display the top page

page_end()

Display the bottom page.

page_next()

Scroll the text to the next page. Quit if already at the end of the page.

page_back()

Scroll the text back up, at the most to the top.

page_quit(quiet=False)

Quit the pager

start()

Starts the pagination

evennia.utils.evmore.msg(caller, text='', always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=True, **kwargs)

EvMore-supported version of msg, mimicking the normal msg method.

EvMore pager

Parameters

• caller (Object or Account) – Entity reading the text.

• text (str, EvTable or iterator) –

  The text or data to put under paging.

  • If a string, paginate normally. If this text contains one or more \f format symbols, automatic pagination and justification are force-disabled and page-breaks will only happen after each \f.

  • If EvTable, the EvTable will be paginated with the same setting on each page if it is too long. The table decorations will be considered in the size of the page.

  • Otherwise text is converted to an iterator, where each step is expected to be a line in the final display. Each line will be run through iter_callable.

• always_page (bool, optional) – If False, the pager will only kick in if text is too big to fit the screen.

• session (Session, optional) – If given, this session will be used to determine the screen width and will receive all output.

• justify (bool, optional) – If set, auto-justify long lines. This must be turned off for fixed-width or formatted output, like tables. It’s force-disabled if text is an EvTable.

• justify_kwargs (dict, optional) – Keywords for the justifiy function. Used only if justify is True. If this is not set, default arguments will be used.

• exit_on_lastpage (bool, optional) – If reaching the last page without the page being completely filled, exit pager immediately. If unset, another move forward is required to exit. If set, the pager exit message will not be shown.

• exit_cmd (str, optional) – If given, this command-string will be executed on the caller when the more page exits. Note that this will be using whatever cmdset the user had before the evmore pager was activated (so none of the evmore commands will be available when this is run).

• page_formatter (callable, optional) – If given, this function will be passed the contents of each extracted page. This is useful when paginating data consisting something other than a string or a list of strings. Especially queryset data is likely to always need this argument specified. Note however, that all size calculations assume this function to return one single line per element on the page!

• kwargs (any, optional) – These will be passed on to the caller.msg method.

Examples

super_long_text = " ... "
EvMore(caller, super_long_text)

from django.core.paginator import Paginator
query = ObjectDB.objects.all()
pages = Paginator(query, 10)  # 10 objs per page
EvMore(caller, pages)   # will repr() each object per line, 10 to a page

multi_page_table = [ [[..],[..]], ...]
EvMore(caller, multi_page_table, use_evtable=True,
       evtable_args=("Header1", "Header2"),
       evtable_kwargs={"align": "r", "border": "tablecols"})