# -*- coding: utf-8 -*-
"""
The cerebro.gui module provides access to simple graphic interfaces,
such as input dialogs, file selection, progress indicator, etc.
.. rubric:: Functions
* :py:func:`critical_box() <cerebro.gui.critical_box>`
* :py:func:`get_existing_directory() <cerebro.gui.get_existing_directory>`
* :py:func:`get_open_file_name() <cerebro.gui.get_open_file_name>`
* :py:func:`get_open_file_names() <cerebro.gui.get_open_file_names>`
* :py:func:`get_save_file_name() <cerebro.gui.get_save_file_name>`
* :py:func:`information_box() <cerebro.gui.information_box>`
* :py:func:`message_editor() <cerebro.gui.message_editor>`
* :py:func:`question_box() <cerebro.gui.question_box>`
* :py:func:`warning_box() <cerebro.gui.warning_box>`
.. rubric:: Classes
* :py:class:`AccountDialog <cerebro.gui.AccountDialog>`
* :py:class:`InputDialog <cerebro.gui.InputDialog>`
* :py:class:`ProgressBox <cerebro.gui.ProgressBox>`
"""
import py_cerebro_gui
[docs]def get_existing_directory(title):
"""
:param string title: selection dialog title.
:returns: path to the selected directory.
:rtype: string
Displays a directory selection dialog and returns the selected one.
If the user cancels selection, None returns.
::
dir = cerebro.gui.get_existing_directory('Select directory')
if dir != None:
print('Selected directory', dir)
"""
return py_cerebro_gui.get_existing_directory(title)
[docs]def get_open_file_name(title, filter = ''):
"""
:param string title: selection dialog title.
:param string filter: file filter by type, e.g., ``'*.txt'``.
If you are going to use several filters at once, separate them by ';;', e.g.::
'Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)'
:returns: path to the selected file.
:rtype: string
Displays a file selection dialog and returns the selected file.
If the user cancels selection, None returns.
::
file = cerebro.gui.get_open_file_name('Select file', '*.txt')
if file != None:
print('Selected file:', file)
.. seealso:: :py:func:`get_open_file_names() <cerebro.gui.get_open_file_names>`.
"""
return py_cerebro_gui.get_open_file_name(title, filter)
[docs]def get_open_file_names(title, filter = ''):
"""
:param string title: selection dialog title.
:param string filter: file filter by type, e.g., ``'*.txt'``
If you are going to use several filters at once, separate them by ';;', e.g.::
'Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)'
:returns: a list of paths to the selected files.
:rtype: list(string,)
Displays a file selection dialog - with an option to select more than one file - and returns the selected file(s).
If the user cancels selection, None returns.
::
files = cerebro.gui.get_open_file_names('Select files', '*.txt')
if files != None:
print('Selected files:', files)
.. seealso:: :py:func:`get_open_file_name() <cerebro.gui.get_open_file_name>`.
"""
return py_cerebro_gui.get_open_file_names(title, filter)
[docs]def get_save_file_name(title, suffix, filename = ''):
"""
:param string title: selection dialog title.
:param string suffix: file suffix (extension).
:param string filename: file default name.
:returns: path to the file.
:rtype: string
Displays a dialog to select a file for saving and returns the selected file.
If the user cancels selection, None returns.
::
file = cerebro.gui.get_save_file_name('Save file', 'txt')
if file != None:
print('File to be saved:', file)
"""
return py_cerebro_gui.get_save_file_name(title, suffix, filename)
[docs]def critical_box(title, text):
"""
:param string title: window title.
:param string text: message text.
Displays an error message.
.. image:: ../img/capi_gui_error.png
:align: center
"""
py_cerebro_gui.critical_box(title, text)
[docs]def question_box(title, text):
"""
:param string title: window title.
:param string text: question text.
:returns: True, if the user pressed "Yes" button.
:rtype: bool
Displays a dialog with the question.
.. image:: ../img/capi_gui_question.png
:align: center
"""
return py_cerebro_gui.question_box(title, text) != 0
[docs]def warning_box(title, text):
"""
:param string title: window title.
:param string text: message text.
Displays a warning window.
"""
py_cerebro_gui.warning_box(title, text)
[docs]def message_editor(type, task_id, parent_message_id = None, html_text = None, attachments = None, attachment_as_links = None, work_time = None, status_id = None, client_visible = None):
"""
:param int type: :py:const:`message type <cerebro.aclasses.AbstractMessage.TYPE_>`.
:param int task_id: the ID of the task the message will added to.
:param int parent_message_id: the ID of the parent message, i.e. the message to which this message is a response.
:param string html_text: the text of the message in html format. The text can also be unformatted.
:param list(string,) attachments: a list of files that will be attached to the message.
:param list(string,) attachment_as_links: a list of files that will be attached to the message as links.
:param float work_time: time in minutes.
:param int status_id: the task status ID to which the task will be switched once the message has been sent.
:param bool client_visible: If equal to True, the message is visible to clients.
Opens the standard unblocking message-editor window the next time a new message is sent to the task.
All arguments other than message type and task ID are optional. If it is not necessary to use certain message parameters, use the hex None instead.
Files or links to files in the lists 'attachments' and 'attachment_as_links' must have a full path.
To give a a task the 'No Status' status, set the argument 'status_id' to 0.
The 'work_time' argument should only be set for reports or reviews.
If the message type is :py:const:`"Отчет" <cerebro.aclasses.AbstractMessage.TYPE_REPORT>`
or :py:const:`"Отчет за ресурс" <cerebro.aclasses.AbstractMessage.TYPE_RESOURCE_REPORT>`,
it indicates the time signed off (declared by the current message author).
If the message type is :py:const:`"Рецензия" <cerebro.aclasses.AbstractMessage.TYPE_REVIEW>`,
it indicates the time signed off and approved for the previous Report.
::
current_task = cerebro.core.current_task()
cerebro.gui.message_editor(cerebro.aclasses.AbstractMessage.TYPE_NOTE, current_task.id(), None, 'Test')
"""
if html_text == None:
html_text = ''
if parent_message_id == None:
parent_message_id = -2
if attachments == None:
attachments = []
if attachment_as_links == None:
attachment_as_links = []
if work_time == None:
work_time = -1
if status_id == None:
status_id = -2
if client_visible == None:
client_visible = -1
py_cerebro_gui.message_editor(type, task_id, parent_message_id, html_text, attachments, attachment_as_links, work_time, status_id, int(client_visible))
[docs]class ProgressBox():
"""
:param string title: progress window title.
:param int min: progress minimal value.
:param int max: progress maximal value.
Progress window class.
.. rubric:: Methods
* :py:meth:`close() <cerebro.gui.ProgressBox.close>`
* :py:meth:`hide_cancel_button() <cerebro.gui.ProgressBox.hide_cancel_button>`
* :py:meth:`label() <cerebro.gui.ProgressBox.label>`
* :py:meth:`max() <cerebro.gui.ProgressBox.max>`
* :py:meth:`min() <cerebro.gui.ProgressBox.min>`
* :py:meth:`reset() <cerebro.gui.ProgressBox.reset>`
* :py:meth:`set_label() <cerebro.gui.ProgressBox.set_label>`
* :py:meth:`set_range() <cerebro.gui.ProgressBox.set_range>`
* :py:meth:`set_title() <cerebro.gui.ProgressBox.set_title>`
* :py:meth:`set_value() <cerebro.gui.ProgressBox.set_value>`
* :py:meth:`show() <cerebro.gui.ProgressBox.show>`
* :py:meth:`title() <cerebro.gui.ProgressBox.title>`
* :py:meth:`value() <cerebro.gui.ProgressBox.value>`
* :py:meth:`was_canceled() <cerebro.gui.ProgressBox.was_canceled>`
.. image:: ../img/capi_gui_progress.png
:align: center
::
prgbar = cerebro.gui.ProgressBox('Progress Window', 0, 100)
prgbar.set_label('Progress...')
prgbar.show()
for i in range(0,100):
if prgbar.was_canceled() == True: # checking if the operation hasn't been canceled by user
break
prgbar.set_value(i)
prgbar.close()
"""
def __init__(self, title, min = 0, max = 100):
self.__id = py_cerebro_gui.progress_bar(title, min, max)
[docs] def set_title(self, title):
"""
:param string title: window title.
Sets a progress window title.
.. seealso:: :py:meth:`title() <cerebro.gui.ProgressBox.title>`.
"""
py_cerebro_gui.progress_bar_set_title(self.__id, title)
[docs] def title(self):
"""
:returns: progress window title.
:rtype: string
.. seealso:: :py:meth:`set_title() <cerebro.gui.ProgressBox.set_title>`.
"""
return py_cerebro_gui.progress_bar_title(self.__id)
[docs] def set_label(self, label):
"""
:param string label: text label.
Sets a text label.
.. seealso:: :py:meth:`label() <cerebro.gui.ProgressBox.label>`.
"""
py_cerebro_gui.progress_bar_set_label(self.__id, label)
[docs] def label(self):
"""
:returns: text label.
:rtype: string
.. seealso:: :py:meth:`set_label() <cerebro.gui.ProgressBox.set_label>`.
"""
return py_cerebro_gui.progress_bar_label(self.__id)
[docs] def set_value(self, value):
"""
:param int value: progress value.
Sets progress value.
.. seealso:: :py:meth:`value() <cerebro.gui.ProgressBox.value>`.
"""
py_cerebro_gui.progress_bar_set_value(self.__id, value)
[docs] def value(self):
"""
:returns: progress value.
:rtype: int
.. seealso:: :py:meth:`set_value() <cerebro.gui.ProgressBox.set_value>`.
"""
return py_cerebro_gui.progress_bar_value(self.__id)
[docs] def set_range(self, min, max):
"""
:param int min: minimal progress value.
:param int max: maximal progress value.
Sets minimal and maximal progress values.
.. seealso:: :py:meth:`max() <cerebro.gui.ProgressBox.max>`, :py:meth:`min() <cerebro.gui.ProgressBox.min>`.
"""
py_cerebro_gui.progress_bar_set_range(self.__id, min, max)
[docs] def min(self):
"""
:returns: minimal progress value.
:rtype: int
.. seealso:: :py:meth:`set_range() <cerebro.gui.ProgressBox.set_range>`.
"""
return py_cerebro_gui.progress_bar_min(self.__id)
[docs] def max(self):
"""
:returns: maximal progress value.
:rtype: int
.. seealso:: :py:meth:`set_range() <cerebro.gui.ProgressBox.set_range>`.
"""
return py_cerebro_gui.progress_bar_max(self.__id)
[docs] def reset(self):
"""
Resets progress value the minimum.
"""
py_cerebro_gui.progress_bar_reset(self.__id)
[docs] def show(self):
"""
Displays a progress window.
.. seealso:: :py:meth:`close() <cerebro.gui.ProgressBox.close>`.
"""
py_cerebro_gui.progress_bar_show(self.__id)
[docs] def close(self):
"""
Closes a progress window.
.. seealso:: :py:meth:`show() <cerebro.gui.ProgressBox.show>`.
"""
py_cerebro_gui.progress_bar_close(self.__id)
[docs] def was_canceled(self):
"""
:returns: True, if the user pressed the "Cancel" button.
:rtype: bool
"""
return py_cerebro_gui.progress_bar_was_canceled(self.__id) != 0
[docs]class AccountDialog():
"""
:param string title: dialog title.
:param string label: text label.
:param string store_key: a key to restore previously saved login and password.
Credentials input dialogue class.
.. rubric:: Methods
* :py:meth:`execute() <cerebro.gui.AccountDialog.execute>`
* :py:meth:`login() <cerebro.gui.AccountDialog.login>`
* :py:meth:`password() <cerebro.gui.AccountDialog.password>`
* :py:meth:`set_login() <cerebro.gui.AccountDialog.set_login>`
* :py:meth:`store() <cerebro.gui.AccountDialog.store>`
.. image:: ../img/capi_gui_account.png
:align: center
::
daccount = cerebro.gui.account_dialog('Example', 'Enter your login and password', 'store_key')
res = daccount.execute()
if res == True:
print('Login and password entered by user:', daccount.login(), daccount.password())
daccount.store('store_key') # saving the password for future calls
"""
def __init__(self, title, label = '', store_key = ''):
self.__id = py_cerebro_gui.daccount(title, label, store_key)
[docs] def set_login(self, login):
"""
:param string login: login.
Sets login value.
.. seealso:: :py:meth:`login() <cerebro.gui.AccountDialog.login>`.
"""
py_cerebro_gui.daccount_set_login(self.__id, login)
[docs] def execute(self):
"""
:returns: True, if the user entered login and password and pressed "OK" button or if the login and password were saved earlier.
:rtype: bool
Displays a dialog window.
If the login and password were saved during a previous call, the dialog window is not displayed,
"True" returns, and then you can resolve the login and password by using the following methods:
:py:meth:`login() <cerebro.gui.AccountDialog.login>` and :py:meth:`password() <cerebro.gui.AccountDialog.password>`.
"""
return py_cerebro_gui.daccount_exec(self.__id) != 0
[docs] def login(self):
"""
:returns: login entered by user.
:rtype: string
.. seealso:: :py:meth:`set_login() <cerebro.gui.AccountDialog.set_login>`.
"""
return py_cerebro_gui.daccount_login(self.__id)
[docs] def password(self):
"""
:returns: password entered by user.
:rtype: string
"""
return py_cerebro_gui.daccount_pass(self.__id)
[docs] def store(self, store_key, expires = 7): # is saved according to the key for the current user, -1 means unlimited
"""
:param string store_key: key for saving login and password.
:param int expires: password storage period, days. Setting the argument to -1 means the storage period is unlimited.
The dialog saves login and password by a text key for the desired period of time.
To restore a previously saved password, pass the key used for saving to the dialog constructor.
.. note:: All passwords are stored in encrypted form.
"""
py_cerebro_gui.daccount_save(self.__id, store_key, expires)