Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add gui.widgets section to the documentation

Browse Source
This commit is contained in:
Nick Hall 2013-11-15 19:11:25 +00:00
parent a90139cb9a
commit 13438a74d6
14 changed files with 890 additions and 425 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/api.rst
View File

@ -32,6 +32,7 @@ Contents:
corecli/cli
coregui/gui
coregui/gui_widgets
date
relationship
simple

17
docs/coregui/gui.rst
View File

@ -153,23 +153,6 @@ Filter Editor
:undoc-members:
:show-inheritance:
*****************************
Gramplet Bar
*****************************
.. automodule:: gramps.gui.widgets.grampletbar
.. autoclass:: DetachedWindow
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GrampletBar
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: TabGramplet
:members:
:undoc-members:
:show-inheritance:
*****************************
Navigator
*****************************

433
docs/coregui/gui_widgets.rst Normal file
View File

@ -0,0 +1,433 @@
####################################
The :mod:`gramps.gui.widgets` Module
####################################
.. automodule:: gramps.gui.widgets
*****************************
Basic Entry
*****************************
.. automodule:: gramps.gui.widgets.basicentry
.. autoclass:: BasicEntry
:members:
:undoc-members:
:show-inheritance:
*****************************
Buttons
*****************************
.. automodule:: gramps.gui.widgets.buttons
.. autoclass:: IconButton
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: WarnButton
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: SimpleButton
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: PrivacyButton
:members:
:undoc-members:
:show-inheritance:
*****************************
Date Entry
*****************************
.. automodule:: gramps.gui.widgets.dateentry
.. autoclass:: DateEntry
:members:
:undoc-members:
:show-inheritance:
*****************************
Expand Collapse Arrow
*****************************
.. automodule:: gramps.gui.widgets.expandcollapsearrow
.. autoclass:: ExpandCollapseArrow
:members:
:undoc-members:
:show-inheritance:
*****************************
Fanchart
*****************************
.. automodule:: gramps.gui.widgets.fanchart
.. autoclass:: FanChartBaseWidget
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: FanChartWidget
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: FanChartGrampsGUI
:members:
:undoc-members:
:show-inheritance:
*****************************
Fanchart Descendant
*****************************
.. automodule:: gramps.gui.widgets.fanchartdesc
.. autoclass:: FanChartDescWidget
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: FanChartDescGrampsGUI
:members:
:undoc-members:
:show-inheritance:
*****************************
Gramplet Bar
*****************************
.. automodule:: gramps.gui.widgets.grampletbar
.. autoclass:: DetachedWindow
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GrampletBar
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: TabGramplet
:members:
:undoc-members:
:show-inheritance:
*****************************
Gramplet Pane
*****************************
.. automodule:: gramps.gui.widgets.grampletpane
.. autoclass:: LinkTag
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GrampletWindow
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GuiGramplet
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GridGramplet
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GrampletPane
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: Configuration
:members:
:undoc-members:
:show-inheritance:
*****************************
Labels
*****************************
.. automodule:: gramps.gui.widgets.labels
.. autoclass:: LinkLabel
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: EditLabel
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: BasicLabel
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GenderLabel
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MarkupLabel
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: DualMarkupLabel
:members:
:undoc-members:
:show-inheritance:
*****************************
Link Box
*****************************
.. automodule:: gramps.gui.widgets.linkbox
.. autoclass:: LinkBox
:members:
:undoc-members:
:show-inheritance:
*****************************
Menu Item
*****************************
.. automodule:: gramps.gui.widgets.menuitem
.. autoclass:: MenuItemWithData
:members:
:undoc-members:
:show-inheritance:
*****************************
Monitored Widgets
*****************************
.. automodule:: gramps.gui.widgets.monitoredwidgets
.. autoclass:: MonitoredCheckbox
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredEntry
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredEntryIndicator
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredSpinButton
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredText
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredType
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredDataType
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredMenu
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredStrMenu
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredDate
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredComboSelectedEntry
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MonitoredTagList
:members:
:undoc-members:
:show-inheritance:
*****************************
Multi Tree View
*****************************
.. automodule:: gramps.gui.widgets.multitreeview
.. autoclass:: MultiTreeView
:members:
:undoc-members:
:show-inheritance:
*****************************
Photo
*****************************
.. automodule:: gramps.gui.widgets.photo
.. autoclass:: Photo
:members:
:undoc-members:
:show-inheritance:
*****************************
Progress Dialog
*****************************
.. automodule:: gramps.gui.widgets.progressdialog
.. autoclass:: LongOpStatus
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: ProgressMonitor
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GtkProgressDialog
:members:
:undoc-members:
:show-inheritance:
*****************************
Shortlist ComboEntry
*****************************
.. automodule:: gramps.gui.widgets.shortlistcomboentry
.. autoclass:: ShortlistComboEntry
:members:
:undoc-members:
:show-inheritance:
*****************************
Spring Separator
*****************************
.. automodule:: gramps.gui.widgets.springseparator
.. autoclass:: SpringSeparatorToolItem
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: SpringSeparatorAction
:members:
:undoc-members:
:show-inheritance:
*****************************
Statusbar
*****************************
.. automodule:: gramps.gui.widgets.statusbar
.. autoclass:: Statusbar
:members:
:undoc-members:
:show-inheritance:
*****************************
Styled Text Buffer
*****************************
.. automodule:: gramps.gui.widgets.styledtextbuffer
.. autoclass:: LinkTag
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: GtkSpellState
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: StyledTextBuffer
:members:
:undoc-members:
:show-inheritance:
*****************************
Styled Text Editor
*****************************
.. automodule:: gramps.gui.widgets.styledtexteditor
.. autoclass:: StyledTextEditor
:members:
:undoc-members:
:show-inheritance:
*****************************
Tool ComboEntry
*****************************
.. automodule:: gramps.gui.widgets.toolcomboentry
.. autoclass:: ToolComboEntry
:members:
:undoc-members:
:show-inheritance:
*****************************
Undoable Buffer
*****************************
.. automodule:: gramps.gui.widgets.undoablebuffer
.. autoclass:: Stack
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableInsert
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableDelete
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableBuffer
:members:
:undoc-members:
:show-inheritance:
*****************************
Undoable Entry
*****************************
.. automodule:: gramps.gui.widgets.undoableentry
.. autoclass:: UndoableInsertEntry
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableDeleteEntry
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableEntry
:members:
:undoc-members:
:show-inheritance:
*****************************
Undoable Styled Buffer
*****************************
.. automodule:: gramps.gui.widgets.undoablestyledbuffer
.. autoclass:: UndoableInsertStyled
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableDeleteStyled
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableApplyStyle
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: UndoableStyledBuffer
:members:
:undoc-members:
:show-inheritance:
*****************************
Validated Combo Entry
*****************************
.. automodule:: gramps.gui.widgets.validatedcomboentry
.. autoclass:: ValidatedComboEntry
:members:
:undoc-members:
:show-inheritance:
*****************************
Validated Masked Entry
*****************************
.. automodule:: gramps.gui.widgets.validatedmaskedentry
.. autoclass:: FadeOut
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: MaskedEntry
:members:
:undoc-members:
:show-inheritance:
.. autoclass:: ValidatableMaskedEntry
:members:
:undoc-members:
:show-inheritance:
*****************************
Value Action
*****************************
.. automodule:: gramps.gui.widgets.valueaction
.. autoclass:: ValueAction
:members:
:undoc-members:
:show-inheritance:
*****************************
Value Tool Item
*****************************
.. automodule:: gramps.gui.widgets.valuetoolitem
.. autoclass:: ValueToolItem
:members:
:undoc-members:
:show-inheritance:

13
gramps/gui/widgets/expandcollapsearrow.py
View File

@ -67,18 +67,19 @@ def realize_cb(widget):
class ExpandCollapseArrow(Gtk.EventBox):
"""
Arrow to be used for expand/collapse of sections.
Note: shadow does not work, we indicate action with realize_cb
.. note:: shadow does not work, we indicate action with realize_cb
"""
def __init__(self, collapsed, onbuttonpress, pair):
"""
Constructor for the ExpandCollapseArrow class.
@param collapsed: True if arrow must be shown collapsed,
:param collapsed: True if arrow must be shown collapsed,
False otherwise
@type collapsed: bool
@param onbuttonpress: The callback function for button press
@type onbuttonpress: callback
@param pair: user param for onbuttonpress function
:type collapsed: bool
:param onbuttonpress: The callback function for button press
:type onbuttonpress: callback
:param pair: user param for onbuttonpress function
"""
GObject.GObject.__init__(self)
if collapsed :

43
gramps/gui/widgets/fanchart.py
View File

@ -676,16 +676,17 @@ class FanChartBaseWidget(Gtk.DrawingArea):
@staticmethod
def create_map_rect_to_sector(radius, rect, arc_used_ratio, start_rad, stop_rad):
"""Create a 2D-transform, mapping a rectangle onto a circle sector.
"""
Create a 2D-transform, mapping a rectangle onto a circle sector.
radius -- average radius of the target sector
rect -- (x1, y1, x2, y2)
arc_used_ratio -- From 0.0 to 1.0. Rather than stretching onto the
whole sector, only the middle arc_used_ratio part will be mapped onto.
start_rad -- start radial angle of the sector, in radians
stop_rad -- stop radial angle of the sector, in radians
Returns a lambda (x,y)|->(xNew,yNew) to feed to warpPath.
:param radius: average radius of the target sector
:param rect: (x1, y1, x2, y2)
:param arc_used_ratio: From 0.0 to 1.0. Rather than stretching onto the
whole sector, only the middle arc_used_ratio part
will be mapped onto.
:param start_rad: start radial angle of the sector, in radians
:param stop_rad: stop radial angle of the sector, in radians
:returns: a lambda (x,y)|->(xNew,yNew) to feed to warpPath.
"""
x0, y0, w, h = rect[0], rect[1], rect[2]-rect[0], rect[3]-rect[1]
@ -1042,16 +1043,20 @@ class FanChartWidget(FanChartBaseWidget):
filter, alpha_filter, form):
"""
Reset the values to be used:
root_person_handle = person to show
maxgen = maximum generations to show
background = config setting of which background procedure to use (int)
childring = to show the center ring with children or not
radialtext = try to use radial text or not
fontdescr = string describing the font to use
grad_start, grad_end: colors to use for background procedure
filter = the person filter to apply to the people in the chart
alpha = the alpha transparency value (0-1) to apply to filtered out data
form = the FORM_ constant for the fanchart
:param root_person_handle: person to show
:param maxgen: maximum generations to show
:param background: config setting of which background procedure to use
:type background: int
:param childring: to show the center ring with children or not
:param radialtext: try to use radial text or not
:param fontdescr: string describing the font to use
:param grad_start: colors to use for background procedure
:param grad_end: colors to use for background procedure
:param filter: the person filter to apply to the people in the chart
:param alpha: the alpha transparency value (0-1) to apply to filtered
out data
:param form: the ``FORM_`` constant for the fanchart
"""
self.rootpersonh = root_person_handle
self.generations = maxgen

25
gramps/gui/widgets/fanchartdesc.py
View File

@ -111,16 +111,21 @@ class FanChartDescWidget(FanChartBaseWidget):
filter, alpha_filter, form, angle_algo, dupcolor):
"""
Reset the values to be used:
root_person_handle = person to show
maxgen = maximum generations to show
background = config setting of which background procedure to use (int)
fontdescr = string describing the font to use
grad_start, grad_end: colors to use for background procedure
filter = the person filter to apply to the people in the chart
alpha_filter = the alpha transparency value (0-1) to apply to filtered out data
form = the FORM_ constant for the fanchart
angle_algo = alorithm to use to calculate the sizes of the boxes
dupcolor = color to use for people or families that occur a second or more time
:param root_person_handle: person to show
:param maxgen: maximum generations to show
:param background: config setting of which background procedure to use
:type background: int
:param fontdescr: string describing the font to use
:param grad_start: colors to use for background procedure
:param grad_end: colors to use for background procedure
:param filter: the person filter to apply to the people in the chart
:param alpha_filter: the alpha transparency value (0-1) to apply to
filtered out data
:param form: the ``FORM_`` constant for the fanchart
:param angle_algo: alorithm to use to calculate the sizes of the boxes
:param dupcolor: color to use for people or families that occur a second
or more time
"""
self.rootpersonh = root_person_handle
self.generations = maxgen

3
gramps/gui/widgets/grampletpane.py
View File

@ -1480,7 +1480,8 @@ class GrampletPane(Gtk.ScrolledWindow):
def can_configure(self):
"""
See :class:`~gui.views.pageview.PageView
See :class:`.PageView`
:return: bool
"""
return True

68
gramps/gui/widgets/monitoredwidgets.py
View File

@ -219,17 +219,17 @@ class MonitoredEntryIndicator(MonitoredEntry):
class MonitoredSpinButton(object):
"""
Class for signal handling of spinbuttons.
(Code is a modified copy of MonitoredEntry)
(Code is a modified copy of :class:`MonitoredEntry`)
"""
def __init__(self, obj, set_val, get_val, read_only=False,
autolist=None, changed=None):
"""
@param obj: widget to be monitored
@type obj: Gtk.SpinButton
@param set_val: callback to be called when obj is changed
@param get_val: callback to be called to retrieve value for obj
@param read_only: If SpinButton is read only.
:param obj: widget to be monitored
:type obj: Gtk.SpinButton
:param set_val: callback to be called when obj is changed
:param get_val: callback to be called to retrieve value for obj
:param read_only: If SpinButton is read only.
"""
self.obj = obj
@ -257,8 +257,8 @@ class MonitoredSpinButton(object):
"""
Reinitialize class with the specified callback functions.
@param set_val: callback to be called when SpinButton is changed
@param get_val: callback to be called to retrieve value for SpinButton
:param set_val: callback to be called when SpinButton is changed
:param get_val: callback to be called to retrieve value for SpinButton
"""
self.set_val = set_val
@ -269,7 +269,7 @@ class MonitoredSpinButton(object):
"""
Set the value of the monitored widget to the specified value.
@param value: Value to be set.
:param value: Value to be set.
"""
self.obj.set_value(value)
@ -278,8 +278,8 @@ class MonitoredSpinButton(object):
"""
Connect the signal of monitored widget to the specified callback.
@param signal: Signal prototype for which a connection should be set up.
@param callback: Callback function to be called when signal is emitted.
:param signal: Signal prototype for which a connection should be set up.
:param callback: Callback function to be called when signal is emitted.
"""
self.obj.connect(signal, callback)
@ -288,8 +288,8 @@ class MonitoredSpinButton(object):
"""
Event handler to be called when the monitored widget is changed.
@param obj: Widget that has been changed.
@type obj: Gtk.SpinButton
:param obj: Widget that has been changed.
:type obj: Gtk.SpinButton
"""
self.set_val(obj.get_value())
@ -300,7 +300,7 @@ class MonitoredSpinButton(object):
"""
Set the value of the monitored widget to the specified value.
@param value: Value to be set.
:param value: Value to be set.
"""
self.obj.set_value(value)
@ -309,17 +309,18 @@ class MonitoredSpinButton(object):
"""
Get the current value of the monitored widget.
@returns: Current value of monitored widget.
:returns: Current value of monitored widget.
"""
return self.obj.get_value()
def enable(self, value):
"""
Change the property editable and sensitive of the monitored widget to value.
Change the property editable and sensitive of the monitored widget to
value.
@param value: If widget should be editable or deactivated.
@type value: bool
:param value: If widget should be editable or deactivated.
:type value: bool
"""
self.obj.set_sensitive(value)
@ -334,7 +335,8 @@ class MonitoredSpinButton(object):
def update(self):
"""
Updates value of monitored SpinButton with the value returned by the get_val callback.
Updates value of monitored SpinButton with the value returned by the
get_val callback.
"""
if self.get_val():
@ -429,19 +431,21 @@ class MonitoredDataType(object):
"""
Constructor for the MonitoredDataType class.
@param obj: Existing ComboBox widget to use with has_entry=True.
@type obj: Gtk.ComboBox
@param set_val: The function that sets value of the type in the object
@type set_val: method
@param get_val: The function that gets value of the type in the object.
This returns a GrampsType, of which get_map returns all possible types
@type get_val: method
@param custom_values: Extra values to show in the combobox. These can be
text of custom type, tuple with type info or GrampsType class
@type : list of str, tuple or GrampsType
@ignore_values: list of values not to show in the combobox. If the result
of get_val is in these, it is not ignored
@type : list of int
:param obj: Existing ComboBox widget to use with has_entry=True.
:type obj: Gtk.ComboBox
:param set_val: The function that sets value of the type in the object
:type set_val: method
:param get_val: The function that gets value of the type in the object.
This returns a GrampsType, of which get_map returns all
possible types
:type get_val: method
:param custom_values: Extra values to show in the combobox. These can be
text of custom type, tuple with type info or
GrampsType class
:type custom_values: list of str, tuple or GrampsType
:param ignore_values: list of values not to show in the combobox. If the
result of get_val is in these, it is not ignored
:type ignore_values: list of int
"""
self.set_val = set_val
self.get_val = get_val

199
gramps/gui/widgets/progressdialog.py
View File

@ -56,21 +56,20 @@ from gramps.gen.utils.callback import Callback
#
#-------------------------------------------------------------------------
class LongOpStatus(Callback):
"""LongOpStatus provides a way of communicating the status of a long
"""
LongOpStatus provides a way of communicating the status of a long
running operations. The intended use is that when a long running operation
is about to start it should create an instance of this class and emit
it so that any listeners can pick it up and use it to record the status
of the operation.
Signals
=======
**Signals**
op-heartbeat - emitted every 'interval' calls to heartbeat.
op-end - emitted once when the operation completes.
* op-heartbeat - emitted every 'interval' calls to heartbeat.
* op-end - emitted once when the operation completes.
Example usage:
Example usage::
class MyClass(Callback):
@ -87,7 +86,6 @@ class LongOpStatus(Callback):
status.end()
class MyListener(object):
def __init__(self):
@ -117,21 +115,18 @@ class LongOpStatus(Callback):
interval=1,
can_cancel=False):
"""
@param msg: A Message to indicated the purpose of the operation.
@type msg: string
@param total_steps: The total number of steps that the operation
:param msg: A Message to indicated the purpose of the operation.
:type msg: string
:param total_steps: The total number of steps that the operation
will perform.
@type total_steps:
@param interval: The number of iterations between emissions.
@type interval:
@param can_cancel: Set to True if the operation can be cancelled.
If this is set the operation that creates the status object should
check the 'should_cancel' method regularly so that it can cancel
the operation.
@type can_cancel:
:type total_steps:
:param interval: The number of iterations between emissions.
:type interval:
:param can_cancel: Set to True if the operation can be cancelled.
If this is set the operation that creates the status
object should check the 'should_cancel' method
regularly so that it can cancel the operation.
:type can_cancel:
"""
Callback.__init__(self)
self._msg = msg
@ -169,16 +164,19 @@ class LongOpStatus(Callback):
self.emit('op-heartbeat')
def step(self):
"""Convenience function so LongOpStatus can be used as a ProgressBar
if set up correctly"""
"""
Convenience function so LongOpStatus can be used as a ProgressBar
if set up correctly
"""
self.heartbeat()
def estimated_secs_to_complete(self):
"""Return the number of seconds estimated left before operation
"""
Return the number of seconds estimated left before operation
completes. This will change as 'hearbeat' is called.
@return: estimated seconds to complete.
@rtype: int
:returns: estimated seconds to complete.
:rtype: int
"""
return self._secs_left
@ -189,61 +187,69 @@ class LongOpStatus(Callback):
return self._cancel
def cancel(self):
"""Inform the operation that it should complete.
"""
Inform the operation that it should complete.
"""
self._cancel = True
self.end()
def end(self):
"""End the operation. Causes the 'op-end' signal to be emitted.
"""
End the operation. Causes the 'op-end' signal to be emitted.
"""
self.emit('op-end')
self._running = False
def should_cancel(self):
"""Return true of the user has asked for the operation to be cancelled.
"""
Return true of the user has asked for the operation to be cancelled.
@return: True of the operation should be cancelled.
@rtype: bool
:returns: True of the operation should be cancelled.
:rtype: bool
"""
return self._cancel
def can_cancel(self):
"""@return: True if the operation can be cancelled.
@rtype: bool
"""
:returns: True if the operation can be cancelled.
:rtype: bool
"""
return self._can_cancel
def get_msg(self):
"""@return: The current status description messages.
@rtype: string
"""
:returns: The current status description messages.
:rtype: string
"""
return self._msg
def set_msg(self, msg):
"""Set the current description message.
"""
Set the current description message.
@param msg: The description message.
@type msg: string
:param msg: The description message.
:type msg: string
"""
self._msg = msg
def get_total_steps(self):
"""Get to total number of steps. NOTE: this is not the
"""
Get to total number of steps. NOTE: this is not the
number of times that the 'op-heartbeat' message will be
emited. 'op-heartbeat' is emited get_total_steps/interval
times.
@return: total number of steps.
@rtype: int
:returns: total number of steps.
:rtype: int
"""
return self._total_steps
def get_interval(self):
"""Get the interval between 'op-hearbeat' signals.
"""
Get the interval between 'op-hearbeat' signals.
@return: the interval between 'op-hearbeat' signals.
@rtype: int
:returns: the interval between 'op-hearbeat' signals.
:rtype: int
"""
return self._interval
@ -253,19 +259,19 @@ class LongOpStatus(Callback):
#
#-------------------------------------------------------------------------
class _StatusObjectFacade(object):
"""This provides a simple structure for recording the information
needs about a status object."""
"""
This provides a simple structure for recording the information
needs about a status object.
"""
def __init__(self, status_obj, heartbeat_cb_id=None, end_cb_id=None):
"""
@param status_obj:
@type status_obj: L{LongOpStatus}
@param heartbeat_cb_id: (default: None)
@type heartbeat_cb_id: int
@param end_cb_id: (default: None)
@type end_cb_id: int
:param status_obj:
:type status_obj: :class:`.LongOpStatus`
:param heartbeat_cb_id: (default: None)
:type heartbeat_cb_id: int
:param end_cb_id: (default: None)
:type end_cb_id: int
"""
self.status_obj = status_obj
self.heartbeat_cb_id = heartbeat_cb_id
@ -279,11 +285,12 @@ class _StatusObjectFacade(object):
#
#-------------------------------------------------------------------------
class ProgressMonitor(object):
"""A dialog for displaying the status of long running operations.
"""
A dialog for displaying the status of long running operations.
It will work with L{LongOpStatus} objects to track the
It will work with :class:`.LongOpStatus` objects to track the
progress of long running operations. If the operations is going to
take longer than I{popup_time} it will pop up a dialog with a
take longer than *popup_time* it will pop up a dialog with a
progress bar so that the user gets some feedback about what is
happening.
"""
@ -294,19 +301,17 @@ class ProgressMonitor(object):
title=_("Progress Information"),
popup_time = None):
"""
@param dialog_class: A class used to display the progress dialog.
@type dialog_class: GtkProgressDialog or the same interface.
@param dialog_class_params: A tuple that will be used as the initial
arguments to the dialog_class, this might be used for passing in
a parent window handle.
@type dialog_class_params: tuple
@param title: The title of the progress dialog
@type title: string
@param popup_time: number of seconds to wait before popup.
@type popup_time: int
:param dialog_class: A class used to display the progress dialog.
:type dialog_class: GtkProgressDialog or the same interface.
:param dialog_class_params: A tuple that will be used as the initial
arguments to the dialog_class, this might
be used for passing in a parent window
handle.
:type dialog_class_params: tuple
:param title: The title of the progress dialog
:type title: string
:param popup_time: number of seconds to wait before popup.
:type popup_time: int
"""
self._dialog_class = dialog_class
self._dialog_class_params = dialog_class_params
@ -329,10 +334,11 @@ class ProgressMonitor(object):
return self._dlg
def add_op(self, op_status):
"""Add a new status object to the progress dialog.
"""
Add a new status object to the progress dialog.
@param op_status: the status object.
@type op_status: L{LongOpStatus}
:param op_status: the status object.
:type op_status: :class:`.LongOpStatus`
"""
log.debug("adding op to Progress Monitor")
@ -407,13 +413,15 @@ class ProgressMonitor(object):
#
#-------------------------------------------------------------------------
class _GtkProgressBar(Gtk.VBox):
"""This widget displays the progress bar and labels for a progress
"""
This widget displays the progress bar and labels for a progress
indicator. It provides an interface to updating the progress bar.
"""
def __init__(self, long_op_status):
""":param long_op_status: the status of the operation.
:type long_op_status: L{gen.utils.LongOpStatus}
"""
:param long_op_status: the status of the operation.
:type long_op_status: :class:`.LongOpStatus`
"""
GObject.GObject.__init__(self)
@ -454,7 +462,8 @@ class _GtkProgressBar(Gtk.VBox):
self._hbox.show()
def step(self):
"""Move the progress bar on a step.
"""
Move the progress bar on a step.
"""
self._pbar_index = self._pbar_index + 1.0
@ -477,11 +486,14 @@ class _GtkProgressBar(Gtk.VBox):
#
#-------------------------------------------------------------------------
class GtkProgressDialog(Gtk.Dialog):
"""A gtk window to display the status of a long running
process."""
"""
A gtk window to display the status of a long running
process.
"""
def __init__(self, window_params, title):
""":param title: The title to display on the top of the window.
"""
:param title: The title to display on the top of the window.
:type title: string
"""
#GObject.GObject.__init__(self, *window_params)
@ -504,12 +516,13 @@ class GtkProgressDialog(Gtk.Dialog):
self._progress_bars = []
def add(self, long_op_status):
"""Add a new status object to the progress dialog.
"""
Add a new status object to the progress dialog.
:param long_op_status: the status object.
:type long_op_status: L{gen.utils.LongOpStatus}
:returns: a key that can be used as the L{pbar_idx}
to the other methods.
:type long_op_status: :class:`.LongOpStatus`
:returns: a key that can be used as the ``pbar_idx`` to the other
methods.
:rtype: int
"""
pbar = _GtkProgressBar(long_op_status)
@ -526,9 +539,10 @@ class GtkProgressDialog(Gtk.Dialog):
return len(self._progress_bars)-1
def remove(self, pbar_idx):
"""Remove the specified status object from the progress dialog.
"""
Remove the specified status object from the progress dialog.
:param pbar_idx: the index as returned from L{add}
:param pbar_idx: the index as returned from :meth:`add`
:type pbar_idx: int
"""
if pbar_idx is not None:
@ -537,10 +551,11 @@ class GtkProgressDialog(Gtk.Dialog):
del self._progress_bars[pbar_idx]
def step(self, pbar_idx):
"""Click the progress bar over to the next value. Be paranoid
"""
Click the progress bar over to the next value. Be paranoid
and insure that it doesn't go over 100%.
:param pbar_idx: the index as returned from L{add}
:param pbar_idx: the index as returned from :meth:`add`
:type pbar_idx: int
"""
if pbar_idx < len(self._progress_bars):
@ -552,13 +567,15 @@ class GtkProgressDialog(Gtk.Dialog):
Gtk.main_iteration()
def show(self):
"""Show the dialog and process any events.
"""
Show the dialog and process any events.
"""
Gtk.Dialog.show(self)
self._process_events()
def hide(self):
"""Hide the dialog and process any events.
"""
Hide the dialog and process any events.
"""
Gtk.Dialog.hide(self)
self._process_events()

109
gramps/gui/widgets/styledtextbuffer.py
View File

@ -20,7 +20,7 @@
# $Id$
"""Text buffer subclassed from Gtk.TextBuffer handling L{StyledText}."""
"""Text buffer subclassed from Gtk.TextBuffer handling :class:`.StyledText`."""
__all__ = ["ALLOWED_STYLES", "MATCH_START", "MATCH_END", "MATCH_FLAVOR",
"MATCH_STRING", "StyledTextBuffer"]
@ -115,11 +115,11 @@ class LinkTag(Gtk.TextTag):
#
#-------------------------------------------------------------------------
class GtkSpellState(object):
"""A simple state machine kinda thingy.
"""
A simple state machine kinda thingy.
Trying to track Gtk.Spell activities on a buffer and re-apply formatting
after Gtk.Spell replaces a misspelled word.
"""
(STATE_NONE,
STATE_CLICKED,
@ -174,12 +174,12 @@ class GtkSpellState(object):
self.reset_state()
def get_word_extents_from_mark(self, textbuffer, mark):
"""Get the word extents as Gtk.Spell does.
"""
Get the word extents as Gtk.Spell does.
Used to get the beginning of the word, in which user right clicked.
Formatting found at that position used after Gtk.Spell replaces
misspelled words.
"""
start = textbuffer.get_iter_at_mark(mark)
if not start.starts_word():
@ -192,10 +192,10 @@ class GtkSpellState(object):
return start.get_offset(), end.get_offset()
def forward_word_end(self, iter):
"""Gtk.Spell style Gtk.TextIter.forward_word_end.
"""
Gtk.Spell style Gtk.TextIter.forward_word_end.
The parameter 'iter' is changing as side effect.
"""
if not iter.forward_word_end():
return False
@ -211,10 +211,10 @@ class GtkSpellState(object):
return True
def backward_word_start(self, iter):
"""Gtk.Spell style Gtk.TextIter.backward_word_start.
"""
Gtk.Spell style Gtk.TextIter.backward_word_start.
The parameter 'iter' is changing as side effect.
"""
if not iter.backward_word_start():
return False
@ -234,26 +234,27 @@ class GtkSpellState(object):
#
#-------------------------------------------------------------------------
class StyledTextBuffer(UndoableBuffer):
"""An extended TextBuffer for handling StyledText strings.
"""
An extended TextBuffer for handling :class:`.StyledText` strings.
StyledTextBuffer is an interface between GRAMPS' L{StyledText} format
and Gtk.TextBuffer. To set and get the text use the L{set_text} and
L{get_text} methods.
StyledTextBuffer is an interface between GRAMPS' :class:`.StyledText` format
and Gtk.TextBuffer. To set and get the text use the :meth:`set_text` and
:meth:`get_text` methods.
To set a style to (a portion of) the text (e.g. from GUI) use the
L{apply_style} and L{remove_style} methods.
:meth:`apply_style` and :meth:`remove_style` methods.
To receive information about the style of the text at the cursor position
StyledTextBuffer provides two mechanism: message driven and polling.
To receive notification of style change as cursor moves connect to the
C{style-changed} signal. To get the value of a certain style at the cursor
use the L{get_style_at_cursor) method.
``style-changed`` signal. To get the value of a certain style at the cursor
use the :meth:`get_style_at_cursor` method.
StyledTextBuffer has a regexp pattern matching mechanism too. To add a
regexp pattern to match in the text use the L{match_add} method. To check
if there's a match at a certain position in the text use the L{match_check}
method. For an example how to use the matching see L{EditNote}.
regexp pattern to match in the text use the :meth:`match_add` method. To
check if there's a match at a certain position in the text use the
:meth:`match_check`nmethod. For an example how to use the matching see
:class:`.EditNote`.
"""
__gtype_name__ = 'StyledTextBuffer'
@ -486,20 +487,20 @@ class StyledTextBuffer(UndoableBuffer):
return removed_something
def _get_tag_from_range(self, start=None, end=None):
"""Extract Gtk.TextTags from buffer.
"""
Extract Gtk.TextTags from buffer.
Return only the name of the TextTag from the specified range.
If range is not given, tags extracted from the whole buffer.
@note: TextTag names are always composed like: (%s %s) % (style, value)
@param start: an offset pointing to the start of the range of text
@param type: int
@param end: an offset pointing to the end of the range of text
@param type: int
@return: tagdict
@rtype: {TextTag_Name: [(start, end),]}
:note: TextTag names are always composed like: (%s %s) % (style, value)
:param start: an offset pointing to the start of the range of text
:param type: int
:param end: an offset pointing to the end of the range of text
:param type: int
:returns: tagdict
:rtype: {TextTag_Name: [(start, end),]}
"""
if start is None:
start = 0
@ -521,10 +522,10 @@ class StyledTextBuffer(UndoableBuffer):
return tagdict
def _find_tag_by_name(self, style, value):
"""Fetch TextTag from buffer's tag table by it's name.
"""
Fetch TextTag from buffer's tag table by it's name.
If TextTag does not exist yet, it is created.
"""
if style not in StyledTextTagType.STYLE_TYPE:
return None
@ -552,10 +553,11 @@ class StyledTextBuffer(UndoableBuffer):
# Public API
def set_text(self, s_text):
"""Set the content of the buffer with markup tags.
@note: 's_' prefix means StyledText*, while 'g_' prefix means Gtk.*.
"""
Set the content of the buffer with markup tags.
.. note:: ``s_`` prefix means StyledText*, while ``g_`` prefix means
Gtk.*.
"""
super(StyledTextBuffer, self).set_text(str(s_text))
#self.remove_all_tags(self.get_start_iter(), self.get_end_iter())
@ -575,10 +577,11 @@ class StyledTextBuffer(UndoableBuffer):
self.apply_tag(g_tag, start_iter, end_iter)
def get_text(self, start=None, end=None, include_hidden_chars=True):
"""Return the buffer text.
@note: 's_' prefix means StyledText*, while 'g_' prefix means Gtk.*.
"""
Return the buffer text.
.. note:: ``s_`` prefix means StyledText*, while ``g_`` prefix means
Gtk.*.
"""
if start is None:
start = self.get_start_iter()
@ -622,13 +625,13 @@ class StyledTextBuffer(UndoableBuffer):
return StyledText(txt, s_tags)
def apply_style(self, style, value):
"""Apply a style with the given value to the selection.
@param style: style type to apply
@type style: L{StyledTextTagStyle} int value
@param value: value of the style type
@type value: depends on the I{style} type
"""
Apply a style with the given value to the selection.
:param style: style type to apply
:type style: :class:`.StyledTextTagStyle` int value
:param value: value of the style type
:type value: depends on the ``style`` type
"""
if not isinstance(value, StyledTextTagType.STYLE_TYPE[style]):
raise TypeError("Style (%d) value must be %s and not %s" %
@ -638,22 +641,22 @@ class StyledTextBuffer(UndoableBuffer):
self._apply_style_to_selection(style, value)
def remove_style(self, style):
"""Delete all occurences with any value of the given style.
@param style: style type to apply
@type style: L{StyledTextTagStyle} int value
"""
Delete all occurences with any value of the given style.
:param style: style type to apply
:type style: :class:`.StyledTextTagStyle` int value
"""
self._remove_style_from_selection(style)
def get_style_at_cursor(self, style):
"""Get the actual value of the given style at the cursor position.
@param style: style type to apply
@type style: L{StyledTextTagStyle} int value
@returns: value of the style type
@returntype: depends on the C{style} type
"""
Get the actual value of the given style at the cursor position.
:param style: style type to apply
:type style: :class:`.StyledTextTagStyle` int value
:returns: value of the style type
:rtype: depends on the ``style`` type
"""
return self.style_state[style]

109
gramps/gui/widgets/styledtexteditor.py
View File

@ -21,7 +21,7 @@
# $Id$
"Text editor subclassed from Gtk.TextView handling L{StyledText}."
"Text editor subclassed from Gtk.TextView handling :class:`.StyledText`."
__all__ = ["StyledTextEditor"]
@ -133,37 +133,38 @@ def find_parent_with_attr(self, attr="dbstate"):
#
#-------------------------------------------------------------------------
class StyledTextEditor(Gtk.TextView):
"""StyledTextEditor is an enhanced Gtk.TextView to edit L{StyledText}.
"""
StyledTextEditor is an enhanced Gtk.TextView to edit :class:`.StyledText`.
StyledTextEditor is a gui object for L{StyledTextBuffer}. It offers
L{set_text} and L{get_text} convenience methods to set and get the
StyledTextEditor is a gui object for :class:`.StyledTextBuffer`. It offers
:meth:`set_text` and :meth:`get_text` convenience methods to set and get the
buffer's text.
StyledTextEditor provides a formatting toolbar, which can be retrieved
by the L{get_toolbar} method.
by the :meth:`get_toolbar` method.
StyledTextEdit defines a new signal: 'match-changed', which is raised
whenever the mouse cursor reaches or leaves a matched string in the text.
The feature uses the regexp pattern mathing mechanism of
L{StyledTextBuffer}.
:class:`.StyledTextBuffer`.
The signal's default handler highlights the URL strings. URL's can be
followed from the editor's popup menu or by pressing the <CTRL>Left
mouse button.
@ivar last_match: previously matched string, used for generating the
:ivar last_match: previously matched string, used for generating the
'match-changed' signal.
@type last_match: tuple or None
@ivar match: currently matched string, used for generating the
:type last_match: tuple or None
:ivar match: currently matched string, used for generating the
'match-changed' signal.
@type match: tuple or None
@ivar spellcheck: spell checker object created for the editor instance.
@type spellcheck: L{Spell}
@ivar textbuffer: text buffer assigned to the edit instance.
@type textbuffer: L{StyledTextBuffer}
@ivar toolbar: toolbar to be used for text formatting.
@type toolbar: Gtk.Toolbar
@ivar url_match: stores the matched URL and other mathing parameters.
@type url_match: tuple or None
:type match: tuple or None
:ivar spellcheck: spell checker object created for the editor instance.
:type spellcheck: :class:`.Spell`
:ivar textbuffer: text buffer assigned to the edit instance.
:type textbuffer: :class:`.StyledTextBuffer`
:ivar toolbar: toolbar to be used for text formatting.
:type toolbar: Gtk.Toolbar
:ivar url_match: stores the matched URL and other mathing parameters.
:type url_match: tuple or None
"""
__gtype_name__ = 'StyledTextEditor'
@ -215,15 +216,15 @@ class StyledTextEditor(Gtk.TextView):
# virtual methods
def do_match_changed(self, match):
"""Default signal handler.
"""
Default signal handler.
URL highlighting.
@param match: the new match parameters
@type match: tuple or None
@attention: Do not override the handler, but connect to the signal.
:param match: the new match parameters
:type match: tuple or None
.. warning:: Do not override the handler, but connect to the signal.
"""
window = self.get_window(Gtk.TextWindowType.TEXT)
start, end = self.textbuffer.get_bounds()
@ -246,10 +247,10 @@ class StyledTextEditor(Gtk.TextView):
self.url_match = None
def on_unrealize(self, widget):
"""Signal handler.
"""
Signal handler.
Set the default Gtk settings back before leaving.
"""
try:
settings = Gtk.Settings.get_default()
@ -296,12 +297,12 @@ class StyledTextEditor(Gtk.TextView):
_LOG.debug("Textview paste clipboard")
def on_motion_notify_event(self, widget, event):
"""Signal handler.
"""
Signal handler.
As the mouse cursor moves the handler checks if there's a new
regexp match at the new location. If match changes the
'match-changed' signal is raised.
"""
x, y = self.window_to_buffer_coords(Gtk.TextWindowType.WIDGET,
int(event.x), int(event.y))
@ -354,10 +355,10 @@ class StyledTextEditor(Gtk.TextView):
return False
def on_button_press_event(self, widget, event):
"""Signal handler.
"""
Signal handler.
Handles the <CTRL> + Left click over a URL match.
"""
self.selclick=False
if ((event.type == Gdk.EventType.BUTTON_PRESS) and
@ -375,12 +376,13 @@ class StyledTextEditor(Gtk.TextView):
return False
def on_populate_popup(self, widget, menu):
"""Signal handler.
"""
Signal handler.
Insert extra menuitems:
1. Insert spellcheck selector submenu for spell checking.
2. Insert extra menus depending on ULR match result.
"""
# spell checker submenu
spell_menu = Gtk.MenuItem(label=_('Spellcheck'))
@ -456,11 +458,11 @@ class StyledTextEditor(Gtk.TextView):
self.connect('unrealize', self.on_unrealize)
def _create_toolbar(self):
"""Create a formatting toolbar.
@returns: toolbar containing text formatting toolitems.
@returntype: Gtk.Toolbar
"""
Create a formatting toolbar.
:returns: toolbar containing text formatting toolitems.
:rtype: Gtk.Toolbar
"""
# define the actions...
# ...first the toggle actions, which have a ToggleToolButton as proxy
@ -566,14 +568,14 @@ class StyledTextEditor(Gtk.TextView):
"[a-z0-9-]*(\\.[a-z0-9][a-z0-9-]*)+", MAIL)
def _create_spell_menu(self):
"""Create a menu with all the installed spellchecks.
"""
Create a menu with all the installed spellchecks.
It is called each time the popup menu is opened. Each spellcheck
forms a radio menu item, and the selected spellcheck is set as active.
@returns: menu containing all the installed spellchecks.
@returntype: Gtk.Menu
:returns: menu containing all the installed spellchecks.
:rtype: Gtk.Menu
"""
active_spellcheck = self.spellcheck.get_active_spellcheck()
@ -593,10 +595,10 @@ class StyledTextEditor(Gtk.TextView):
# Callback functions
def _on_toggle_action_activate(self, action):
"""Toggle a style.
"""
Toggle a style.
Toggle styles are e.g. 'bold', 'italic', 'underline'.
"""
if self._internal_style_change:
return
@ -695,7 +697,6 @@ class StyledTextEditor(Gtk.TextView):
Remove only our own tags without touching other ones (e.g. Gtk.Spell),
thus remove_all_tags() can not be used.
"""
clear_anything = self.textbuffer.clear_selection()
if not clear_anything:
@ -801,31 +802,31 @@ class StyledTextEditor(Gtk.TextView):
# public methods
def set_text(self, text):
"""Set the text of the text buffer of the editor.
@param text: formatted text to edit in the view.
@type text: L{StyledText}
"""
Set the text of the text buffer of the editor.
:param text: formatted text to edit in the view.
:type text: :class:`.StyledText`
"""
self.textbuffer.set_text(text)
self.textbuffer.place_cursor(self.textbuffer.get_start_iter())
def get_text(self):
"""Get the text of the text buffer of the editor.
@returns: the formatted text from the editor.
@returntype: L{StyledText}
"""
Get the text of the text buffer of the editor.
:returns: the formatted text from the editor.
:rtype: :class:`.StyledText`
"""
start, end = self.textbuffer.get_bounds()
return self.textbuffer.get_text(start, end, True)
def get_toolbar(self):
"""Get the formatting toolbar of the editor.
@returns: toolbar widget to use as formatting GUI.
@returntype: Gtk.Toolbar
"""
Get the formatting toolbar of the editor.
:returns: toolbar widget to use as formatting GUI.
:rtype: Gtk.Toolbar
"""
return self.toolbar

44
gramps/gui/widgets/validatedcomboentry.py
View File

@ -47,10 +47,11 @@ from gi.repository import Gtk
#
#-------------------------------------------------------------------------
class ValidatedComboEntry(Gtk.ComboBox):
"""A ComboBoxEntry widget with validation.
"""
A ComboBoxEntry widget with validation.
ValidatedComboEntry may have data type other then string, and is set
with the C{datatype} contructor parameter.
with the ``datatype`` contructor parameter.
Its behaviour is different from Gtk.ComboBoxEntry in the way how
the entry part of the widget is handled. While Gtk.ComboBoxEntry
@ -62,8 +63,7 @@ class ValidatedComboEntry(Gtk.ComboBox):
validator function is given at instantiation.
The entry can be set as editable or not editable using the
L{set_entry_editable} method.
:meth:`set_entry_editable` method.
"""
__gtype_name__ = "ValidatedComboEntry"
@ -116,36 +116,36 @@ class ValidatedComboEntry(Gtk.ComboBox):
# Signal handlers
def _on_entry_activate(self, entry):
"""Signal handler.
"""
Signal handler.
Called when the entry is activated.
"""
self._entry_changed(entry)
def _on_entry_focus_in_event(self, widget, event):
"""Signal handler.
"""
Signal handler.
Called when the focus enters the entry, and is used for saving
the entry's text for later comparison.
"""
self._text_on_focus_in = self._entry.get_text()
def _on_entry_focus_out_event(self, widget, event):
"""Signal handler.
"""
Signal handler.
Called when the focus leaves the entry.
"""
if (self._entry.get_text() != self._text_on_focus_in):
self._entry_changed(widget)
def _on_entry_key_press_event(self, entry, event):
"""Signal handler.
"""
Signal handler.
Its purpose is to handle escape button.
"""
# FIXME Escape never reaches here, the dialog eats it, I assume.
if event.keyval == Gdk.KEY_Escape:
@ -156,10 +156,10 @@ class ValidatedComboEntry(Gtk.ComboBox):
return False
def _on_changed(self, combobox):
"""Signal handler.
"""
Signal handler.
Called when the active row is changed in the combo box.
"""
if self._internal_change:
return
@ -172,10 +172,10 @@ class ValidatedComboEntry(Gtk.ComboBox):
self._entry.set_text(self._active_text)
def _on_notify(self, object, gparamspec):
"""Signal handler.
"""
Signal handler.
Called whenever a property of the object is changed.
"""
if gparamspec and gparamspec.name == 'has-frame':
self._has_frame_changed()
@ -211,13 +211,13 @@ class ValidatedComboEntry(Gtk.ComboBox):
self._entry.set_has_frame(has_frame)
def _is_in_model(self, data):
"""Check if given data is in the model or not.
@param data: data value to check
@type data: depends on the actual data type of the object
@returns: position of 'data' in the model
@returntype: Gtk.TreeIter or None
"""
Check if given data is in the model or not.
:param data: data value to check
:type data: depends on the actual data type of the object
:returns: position of 'data' in the model
:rtype: Gtk.TreeIter or None
"""
model = self.get_model()

118
gramps/gui/widgets/validatedmaskedentry.py
View File

@ -77,8 +77,9 @@ except AttributeError:
#============================================================================
class FadeOut(GObject.GObject):
"""I am a helper class to draw the fading effect of the background
Call my methods start() and stop() to control the fading.
"""
I am a helper class to draw the fading effect of the background
Call my methods :meth:`start` and :meth:`stop` to control the fading.
"""
__gsignals__ = {
'done': (GObject.SignalFlags.RUN_FIRST,
@ -148,9 +149,11 @@ class FadeOut(GObject.GObject):
self._countdown_timeout_id = -1
def start(self, color):
"""Schedules a start of the countdown.
@param color: initial background color
@returns: True if we could start, False if was already in progress
"""
Schedules a start of the countdown.
:param color: initial background color
:returns: True if we could start, False if was already in progress
"""
if self._background_timeout_id != -1:
##_LOG.debug('start: Background change already running')
@ -225,11 +228,12 @@ class MaskedEntry(UndoableEntry):
The MaskedEntry is an Entry subclass with additional features.
Additional features:
- Mask, force the input to meet certain requirements
- IconEntry, allows you to have an icon inside the entry
- convenience functions for completion
Note: Gramps does not use the mask feature at the moment, so that code
.. note:: Gramps does not use the mask feature at the moment, so that code
path is not tested
"""
__gtype_name__ = 'MaskedEntry'
@ -302,6 +306,7 @@ class MaskedEntry(UndoableEntry):
Set the mask of the Entry.
Supported format characters are:
- '0' digit
- 'L' ascii letter (a-z and A-Z)
- '&' alphabet, honors the locale
@ -309,12 +314,12 @@ class MaskedEntry(UndoableEntry):
- 'A' alphanumeric, honors the locale
This is similar to MaskedTextBox:
U{http://msdn2.microsoft.com/en-us/library/system.windows.forms.maskedtextbox.mask(VS.80).aspx}
http://msdn2.microsoft.com/en-us/library/system.windows.forms.maskedtextbox.mask(VS.80).aspx
Example mask for a ISO-8601 date
>>> entry.set_mask('0000-00-00')
@param mask: the mask to set
:param mask: the mask to set
"""
if not mask:
self.modify_font(Pango.FontDescription("sans"))
@ -355,7 +360,7 @@ class MaskedEntry(UndoableEntry):
def get_mask(self):
"""
@returns: the mask
:returns: the mask
"""
return self._mask
@ -376,8 +381,8 @@ class MaskedEntry(UndoableEntry):
if a field is empty it'll return an empty string
otherwise it'll include the content
@returns: fields
@rtype: list of strings
:returns: fields
:rtype: list of strings
"""
if not self._mask:
raise MaskError("a mask must be set before calling get_fields")
@ -395,10 +400,10 @@ class MaskedEntry(UndoableEntry):
"""
Get the empty mask between start and end
@param start:
@param end:
@returns: mask
@rtype: string
:param start:
:param end:
:returns: mask
:rtype: string
"""
if start is None:
@ -464,13 +469,12 @@ class MaskedEntry(UndoableEntry):
Shift the text, to the right or left, n positions. Note that this
does not change the entry text. It returns the shifted text.
@param start:
@param end:
@param direction: DIRECTION_LEFT or DIRECTION_RIGHT
@param positions: the number of positions to shift.
@return: returns the text between start and end, shifted to
the direction provided.
:param start:
:param end:
:param direction: DIRECTION_LEFT or DIRECTION_RIGHT
:param positions: the number of positions to shift.
:returns: returns the text between start and end, shifted to the
direction provided.
"""
text = self.get_text()
new_text = ''
@ -524,8 +528,9 @@ class MaskedEntry(UndoableEntry):
skip=0):
"""
Get next non-static char position, skiping some chars, if necessary.
@param skip: skip first n chars
@param direction: direction of the search.
:param skip: skip first n chars
:param direction: direction of the search.
"""
text = self.get_text()
validators = self._mask_validators
@ -553,8 +558,8 @@ class MaskedEntry(UndoableEntry):
Exact means it needs to start with the value typed
and the case needs to be correct.
@param value: enable exact completion
@type value: boolean
:param value: enable exact completion
:type value: boolean
"""
self._exact_completion = value
@ -640,10 +645,10 @@ class MaskedEntry(UndoableEntry):
"""
Set the way how completion is presented.
@param popup: enable completion in popup window
@type popup: boolean
@param inline: enable inline completion
@type inline: boolean
:param popup: enable completion in popup window
:type popup: boolean
:param inline: enable inline completion
:type inline: boolean
"""
completion = self._get_completion()
if popup is not None:
@ -700,10 +705,9 @@ class MaskedEntry(UndoableEntry):
"""
Check if a chararcter can be inserted at some position
@param new: The char that wants to be inserted.
@param pos: The position where it wants to be inserted.
@return: Returns None if it can be inserted. If it cannot be,
:param new: The char that wants to be inserted.
:param pos: The position where it wants to be inserted.
:returns: Returns None if it can be inserted. If it cannot be,
return the next position where it can be successfuly
inserted.
"""
@ -770,12 +774,11 @@ class MaskedEntry(UndoableEntry):
Inserts the character at the give position in text. Note that the
insertion won't be applied to the entry, but to the text provided.
@param text: Text that it will be inserted into.
@param new: New text to insert.
@param pos: Positon to insert at
@return: Returns a tuple, with the position after the insetion
and the new text.
:param text: Text that it will be inserted into.
:param new: New text to insert.
:param pos: Positon to insert at
:returns: Returns a tuple, with the position after the insetion and the
new text.
"""
field = self._get_field_at_pos(pos)
length = len(new)
@ -1115,7 +1118,8 @@ MANDATORY_ICON = INFO_ICON
ERROR_ICON = Gtk.STOCK_STOP
class ValidatableMaskedEntry(MaskedEntry):
"""It extends the MaskedEntry with validation feature.
"""
It extends the MaskedEntry with validation feature.
Merged from Kiwi's ValidatableProxyWidgetMixin and ProxyEntry.
To provide custom validation connect to the 'validate' signal
@ -1218,9 +1222,9 @@ class ValidatableMaskedEntry(MaskedEntry):
Default error message for an instance is useful when completion is
used, because this case custom validation is not called.
@param text: can contain one and only one '%s', where the actual value
:param text: can contain one and only one '%s', where the actual value
of the Entry will be inserted.
@type text: str
:type text: str
"""
if not isinstance(text, str):
raise TypeError("text must be a string")
@ -1229,16 +1233,17 @@ class ValidatableMaskedEntry(MaskedEntry):
def is_valid(self):
"""
@returns: True if the widget is in validated state
:returns: True if the widget is in validated state
"""
return self._valid
def validate(self, force=False):
"""Checks if the data is valid.
"""
Checks if the data is valid.
Validates data-type and custom validation.
@param force: if True, force validation
@returns: validated data or ValueUnset if it failed
:param force: if True, force validation
:returns: validated data or ValueUnset if it failed
"""
# If we're not visible or sensitive return a blank value, except
@ -1280,7 +1285,8 @@ class ValidatableMaskedEntry(MaskedEntry):
return None
def set_valid(self):
"""Change the validation state to valid, which will remove icons and
"""
Change the validation state to valid, which will remove icons and
reset the background color
"""
##_LOG.debug('Setting state for %s to VALID' % self.model_attribute)
@ -1290,9 +1296,11 @@ class ValidatableMaskedEntry(MaskedEntry):
self.set_pixbuf(None)
def set_invalid(self, text=None, fade=True):
"""Change the validation state to invalid.
@param text: text of tooltip of None
@param fade: if we should fade the background
"""
Change the validation state to invalid.
:param text: text of tooltip of None
:param fade: if we should fade the background
"""
##_LOG.debug('Setting state for %s to INVALID' % self.model_attribute)
@ -1348,8 +1356,10 @@ class ValidatableMaskedEntry(MaskedEntry):
self.set_pixbuf(None)
def set_blank(self):
"""Change the validation state to blank state, this only applies
for mandatory widgets, draw an icon and set a tooltip"""
"""
Change the validation state to blank state, this only applies
for mandatory widgets, draw an icon and set a tooltip
"""
##_LOG.debug('Setting state for %s to BLANK' % self.model_attribute)
@ -1368,7 +1378,7 @@ class ValidatableMaskedEntry(MaskedEntry):
"""
Set the text of the entry
@param text:
:param text:
"""
# If content isn't empty set_text emitts changed twice.

53
gramps/gui/widgets/valueaction.py
View File

@ -53,10 +53,10 @@ from .valuetoolitem import ValueToolItem
#
#-------------------------------------------------------------------------
class ValueAction(Gtk.Action):
"""Value action class.
"""
Value action class.
(A ValueAction with menu item doesn't make any sense.)
"""
__gtype_name__ = "ValueAction"
@ -67,21 +67,22 @@ class ValueAction(Gtk.Action):
}
def __init__(self, name, tooltip, default, itemtype, *args):
"""Create a new ValueAction instance.
@param name: the name of the action
@type name: str
@param tooltip: tooltip string
@type tooltip: str
@param default: default value for the action, it will set the type of
the action and thus the type of all the connected proxies.
@type default: set by itemtype
@param itemtype: default tool item class
@type itemtype: ValueToolItem subclass
@param args: arguments to be passed to the default toolitem class
at creation. see: L{do_create_tool_item}
@type args: list
"""
Create a new ValueAction instance.
:param name: the name of the action
:type name: str
:param tooltip: tooltip string
:type tooltip: str
:param default: default value for the action, it will set the type of
the action and thus the type of all the connected
proxies.
:type default: set by itemtype
:param itemtype: default tool item class
:type itemtype: :class:`.ValueToolItem` subclass
:param args: arguments to be passed to the default toolitem class
at creation. see: :meth:`do_create_tool_item`
:type args: list
"""
GObject.GObject.__init__(self, name=name, label='', tooltip=tooltip,
stock_id=None)
@ -100,10 +101,10 @@ class ValueAction(Gtk.Action):
self._handlers = {}
def do_changed(self):
"""Default signal handler for 'changed' signal.
"""
Default signal handler for 'changed' signal.
Synchronize all the proxies with the active value.
"""
for proxy in self.get_proxies():
proxy.handler_block(self._handlers[proxy])
@ -111,7 +112,8 @@ class ValueAction(Gtk.Action):
proxy.handler_unblock(self._handlers[proxy])
def do_create_tool_item(self):
"""Create a 'default' toolbar item widget.
"""
Create a 'default' toolbar item widget.
Override the default method, to be able to pass the required
parameters to the proxy's constructor.
@ -125,9 +127,8 @@ class ValueAction(Gtk.Action):
Widgets other than the default type has to be created and added
manually with the Gtk.Action.connect_proxy() method.
@returns: a toolbar item connected to the action.
@returntype: L{ValueToolItem} subclass
:returns: a toolbar item connected to the action.
:rtype: :class:`.ValueToolItem` subclass
"""
proxy = self._default_toolitem_type(self._data_type,
self._args_for_toolitem)
@ -141,11 +142,11 @@ class ValueAction(Gtk.Action):
self.set_value(value)
def connect_proxy(self, proxy):
"""Connect a widget to an action object as a proxy.
@param proxy: widget to be connected
@type proxy: L{ValueToolItem} subclass
"""
Connect a widget to an action object as a proxy.
:param proxy: widget to be connected
:type proxy: :class:`.ValueToolItem` subclass
"""
if not isinstance(proxy, ValueToolItem):
raise TypeError