maverig.views.positioning

maverig.views.positioning.section

class maverig.views.positioning.section.Section(name, next_sequence=None, called_by_remote=False)

Bases: object

synchronization of critical sections and automatic walk trough specified section sequences. All section participants are notified via events when a section is entered and leaved (exit).

Sections can either be started directly (run) or be initiated remotely by calling enter and exit.

run()
is_running()
enter()

first call enters section

exit(*args)

last call exits section

class maverig.views.positioning.section.SectionManager

Bases: object

Holds a section sequence for positioning on internal, items and presenter side.

Sections divide position_changed-Event-Handling into multiple subjected Phases which will be handled one after another.

Position changes made during an with section_manager.pos_section-block will only throw events after all pos_section-blocks have been exited and the next section (mouse_section) has been entered automatically.

Then all changed virtual points will throw a position_changed_event in __on_enter_section with the actual section as parameter which can be checked on Event-Handling.

Afterwards all changed virtual points will throw a position_changed_event for the next section and so on...

This is, how positioning works with VPoints and SectionManager:

  1. pos_section:

    in order to set multiple VPoint positions at the same time, use:

    with section_manager.pos_section:
       v_point1.set_pos(pos1, Change.moved)
       v_point2.pos = pos2  # Change == Change.applied
    

    This is equivalent to:

    section_manager.pos_section.enter
    v_point1.set_pos(pos1, Change.moved)
    v_point2.pos = pos2  # Change == Change.applied
    section_manager.pos_section.exit
    

    one VPoint can simply be set like this:

    v_point.pos = pos  # Change == Change.applied
    

    In this case, the pos_section enter and exit will be called remotely by VPoint position setter.

    During the time window marked by [pos_section.enter .. adjust_section.exit], all position changes are applied on old position values in order to prevent side-effects.

  2. mouse_section:

    Mouse section is entered directly after all positioning has been applied on pos_section. (VPoint.__on_enter_section)

    Any mouse moved virtual point triggers adjustment (as specified in VPoint.trigger_section) on mouse_section.

  3. adjust_section:

    Adjustment section is entered after primary positioning and mouse moved positions.

    VPoint followings and fixings will be applied by handling VPoint.position_changed on previous position changes.

    VPoint.pos calls still return the old position. The new set position is saved internally at VPoint.__new_pos and will be applied to VPoint.pos after all adjustment changes have been finished. (VPoint.__on_exit_section)

  4. item_section:

    Item section is entered after all affected positions and their followings/fixings have been updated. All item positions can now be adapted to VPoint positions by registering on VPoint.position_changed event:

    def on_position_changed(self, vp, delta, change, section):
        if section == section_manager.item_section:
            self.graphics_item.setPos(self.graphics_item.pos() + delta)
    
  5. presenter_section:

    Presenter section is entered after all affected item positions have been updated. GroupPresenter can now work on the current VPoint and QGraphicsItem positions and e.g. apply custom followings:

    def on_position_changed(self, vp, delta, change, section):
        if section == section_manager.presenter_section:
            other_v_point = self.snap_zone_dockable(v_point)  # needs correct QGraphicsItem positions
            v_point.follow(other_v_point)
            other_v_point.follow(v_point, [Change.calculated, Change.raster_snapped])
    

    The Presenter section may also apply new positions which restarts the section sequence from position level.

maverig.views.positioning.vPoint

class maverig.views.positioning.vPoint.Changes

Bases: object

none = {}
all = {'calculated', 'applied', 'followed', 'moved', 'avoid_invalid', 'snapped', 'raster_snapped'}
indirect = {'calculated', 'followed', 'moved', 'avoid_invalid', 'snapped', 'raster_snapped'}
class maverig.views.positioning.vPoint.Change

Bases: object

Reason for v_point change.

origin = None
applied = 'applied'
moved = 'moved'
snapped = 'snapped'
raster_snapped = 'raster_snapped'
avoid_invalid = 'avoid_invalid'
calculated = 'calculated'
followed = 'followed'
class maverig.views.positioning.vPoint.VPoint(parent_item=None)

Bases: object

A Virtual Point which represents a position in scenario.

Each Virtual Point can follow other Virtual Points via event triggers and adjustment functions on specific changes.

When setting a position, Position Changed Events are fired section by section through stacked layers, where each section stands for a different type of position adjustments that would conflict each other if they would all run in one section. The position gets applied on pos when the internal layer section_manager.adjust_section is being exited. This is in order to make multiple relative position changes based on the previous position without summing up the movements which would result in negative side effects.

See maverig.views.positioning.section.SectionManager documentation for how positioning works in detail.

position_changed = None

The position changed event with current delta (QtCore.QPointF), change (Change) and section (maverig.views.positioning.section.Section) as params.

last_positions = None

A list of last valid positions controlled by maverig.presenter.group_presenter.abstractGroupPresenter.AbstractGroupPresenter in order to undo position changes to not allowed positions.

trigger_section = None

The section layer (maverig.views.positioning.section.Section) on which adjustment to other virtual points movements should be done.

new_pos = None

The last proposed new position.

delta = None

The last proposed position change distance.

change = None

The last proposed Change reason of position change.

parent_item = None

The parent maverig.views.items.abstractItem.AbstractItem item where this virtual point is added to AbstractItem.v_points.

followers = None

Virtual points that follow this VPoint. A dict of virtual point to adjustment method that reacts on position_changed events.

pos

The position of the virtual point.

Use set_pos() if you want to change the position with a specified change reason. Setting this property will result in a simple Change.applied change reason.

set_pos(value, change)

Set position (QtCore.QPointF) with change reason.

move_pos(delta, change)

Move by delta (QtCore.QPointF) with change reason.

follow(v_point, trigger_changes={'calculated', 'followed', 'moved', 'avoid_invalid', 'snapped', 'raster_snapped'}, result_change='followed', keep_distance=True)

Follow v_point.

Adjust this VPoint when v_point position change applies to trigger_changes. This VPoint will change it’s position with the given result_change reason.

Set keep_distance to False if VPoint should only be moved relatively to v_point movements. Otherwise distance to v_point is being fixed as QtCore.QPointF-vector from now on.

unfollow(v_point)

Stop following v_point.

follows(v_point)

Return whether this VPoint follows v_point when v_point moves.

fix(v_point)

Follow v_point and vice versa.

unfix(v_point)

Loose any attachments to v_point and vice versa.

extern_followers

Return a list of virtual points of other groups that follow this VPoint.

class maverig.views.positioning.vPoint.VPMouse

Bases: maverig.views.positioning.vPoint.VPoint

Virtual point representing the mouse position. All followers trigger on mouse_section before other following-adjustments, which will be done in adjust_section