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)[source]¶ Bases:
evennia.commands.command.Command
Manipulate the text paging. Catch no-input with aliases.
-
key
= '__noinput_command'¶
-
aliases
= ['previous', 'q', 't', 'end', 'abort', 'quit', 'top', 'e', 'next', 'p', 'a', 'n']¶
-
auto_help
= False¶
-
help_category
= 'general'¶
-
lock_storage
= 'cmd:all();'¶
-
search_index_entry
= {'aliases': 'previous q t end abort quit top e next p a n', 'category': 'general', 'key': '__noinput_command', 'no_prefix': ' previous q t end abort quit top e next p a n', 'tags': '', 'text': '\n Manipulate the text paging. Catch no-input with aliases.\n '}¶
-
-
class
evennia.utils.evmore.
CmdMoreExit
(**kwargs)[source]¶ Bases:
evennia.commands.command.Command
Any non-more command will exit the pager.
-
key
= '__nomatch_command'¶
-
aliases
= []¶
-
help_category
= 'general'¶
-
lock_storage
= 'cmd:all();'¶
-
search_index_entry
= {'aliases': '', 'category': 'general', 'key': '__nomatch_command', 'no_prefix': ' ', 'tags': '', 'text': '\n Any non-more command will exit the pager.\n\n '}¶
-
-
class
evennia.utils.evmore.
CmdSetMore
(cmdsetobj=None, key=None)[source]¶ Bases:
evennia.commands.cmdset.CmdSet
Stores the more command
-
key
= 'more_commands'¶
-
priority
= 110¶
-
mergetype
= 'Replace'¶
-
at_cmdset_creation
()[source]¶ 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'¶
-
-
class
evennia.utils.evmore.
EvMore
(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)[source]¶ Bases:
object
The main pager object
-
__init__
(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)[source]¶ Initialization of the EvMore pager.
- Parameters
caller (Object or Account) – Entity reading the text.
inp (str, EvTable, Paginator or iterator) –
The text or data to put under paging.
If a string, paginage normally. If this text contains one or more \f format symbol, 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 inp 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 inp 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 inp is an EvTable.
justify_kwargs (dict, optional) – Keywords for the justify 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).
kwargs (any, optional) – These will be passed on to the caller.msg method. Notably, one can pass additional outputfuncs this way. There is one special kwarg: - text_kwargs - extra kwargs to pass with the text outputfunc, e.g. text_kwargs={“type”: “help”} would result to each page being sent to msg as text=(pagetxt, {“type”: “help”}).
Examples
super_long_text = " ... " EvMore(caller, super_long_text)
Paginator
from django.core.paginator import Paginator query = ObjectDB.objects.all() pages = Paginator(query, 10) # 10 objs per page EvMore(caller, pages)
Every page an EvTable
from evennia import EvTable def _to_evtable(page): table = ... # convert page to a table return EvTable(*headers, table=table, ...) EvMore(caller, pages, page_formatter=_to_evtable)
-
paginator_slice
(pageno)[source]¶ Paginate by slice. This is done with an eye on memory efficiency (usually for querysets); to avoid fetching all objects at the same time.
-
paginator_django
(pageno)[source]¶ Paginate using the django queryset Paginator API. Note that his is indexed from 1.
-
init_iterable
(inp)[source]¶ The input is something other than a string - convert to iterable of strings
-
init_f_str
(text)[source]¶ 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_pages
(inp)[source]¶ Initialize the pagination. By default, will analyze input type to determine how pagination automatically.
- Parameters
inp (any) – Incoming data to be paginated. By default, handles pagination of strings, querysets, django.Paginator, EvTables and any iterables with strings.
Notes
If overridden, this method must perform the following actions:
read and re-store self._data (the incoming data set) if needed for pagination to work.
set self._npages to the total number of pages. Default is 1.
set self._paginator to a callable that will take a page number 1…N and return the data to display on that page (not any decorations or next/prev buttons). If only wanting to change the paginator, override self.paginator instead.
set self._page_formatter to a callable that will receive the page from self._paginator and format it with one element per line. Default is str. Or override self.page_formatter directly instead.
By default, helper methods are called that perform these actions depending on supported inputs.
-
paginator
(pageno)[source]¶ Paginator. The data operated upon is in self._data.
- Parameters
pageno (int) – The page number to view, from 0…N-1
- Returns
str –
- The page to display (without any decorations, those are added
by EvMore).
-
page_formatter
(page)[source]¶ Page formatter. Every page passes through this method. Override it to customize behavior per-page. A common use is to generate a new EvTable for every page (this is more efficient than to generate one huge EvTable across many pages and feed it into EvMore all at once).
- Parameters
page (any) – A piece of data representing one page to display. This must
- Returns
str –
- A ready-formatted page to display. Extra footer with help about
switching to the next/prev page will be added automatically
-
-
evennia.utils.evmore.
msg
(caller, text='', always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=True, **kwargs)[source]¶ EvMore-supported version of msg, mimicking the normal msg method.
Initialization of the EvMore pager.
- Parameters
caller (Object or Account) – Entity reading the text.
inp (str, EvTable, Paginator or iterator) –
The text or data to put under paging.
If a string, paginage normally. If this text contains one or more \f format symbol, 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 inp 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 inp 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 inp is an EvTable.
justify_kwargs (dict, optional) – Keywords for the justify 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).
kwargs (any, optional) – These will be passed on to the caller.msg method. Notably, one can pass additional outputfuncs this way. There is one special kwarg: - text_kwargs - extra kwargs to pass with the text outputfunc, e.g. text_kwargs={“type”: “help”} would result to each page being sent to msg as text=(pagetxt, {“type”: “help”}).
Examples
super_long_text = " ... " EvMore(caller, super_long_text)
Paginator
from django.core.paginator import Paginator query = ObjectDB.objects.all() pages = Paginator(query, 10) # 10 objs per page EvMore(caller, pages)
Every page an EvTable
from evennia import EvTable def _to_evtable(page): table = ... # convert page to a table return EvTable(*headers, table=table, ...) EvMore(caller, pages, page_formatter=_to_evtable)