About this Guide

This guide is intended to explain how to create a Mapper Profile for mouseTrap.

What is a Mapper Profile?

A mapper profile is a mouse movement code combined with the mapper diagram and the different events corresponding to that mode. It can be developed as a plugin and placed in the ~/.mouseTrap/scripts/profiles/ folder. This allow users and developers to use different mapper profiles and select the best adapted to them.

Structure

The structure of a mapper profile is this:

(Of course it must be written in python)

Part	Description
# -*- coding: utf-8 -*-	The charset type
License	The mapper profile License
File Information	Information related to the file, including Id, Revision, Copyright...
Importing	The different modules to import
Global Variables	Global Variables needed for the profile inclusion
Profile Class	The profile main class
Extra	Anything else needed

Standard Example

# -*- coding: utf-8 -*-

# mouseTrap
#
# Copyright 2008 Flavio Percoco Premoli
#
# This file is part of mouseTrap.
#
# mouseTrap is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#
# mouseTrap is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with mouseTrap.  If not, see <http://www.gnu.org/licenses/>.

"""The Drag Mode script."""

__id__        = "$Id$"
__version__   = "$Revision$"
__date__      = "$Date$"
__copyright__ = "Copyright (c) 2008 Flavio Percoco Premoli"
__license__   = "GPLv2"

import mouseTrap.events as events

# The name given for the config file
setName = "drag"

## Internal Modes
# This will be shown in the preference gui. The key will be used for the settings file
# and the value as pointer to the mode in the prefGui.
modes = { "%s|none" % setName   :  _( "New Mode Profile" ) }

class Profile:

    def __init__( self, mouseTrap, cAm ):
        """
        The MODE NAME Class Constructor.
        
        Initialize the MODE NAME class and sets the needed attributes.
        
        Arguments:
        - self: The main object pointer.
        - mouseTrap: The mouseTrap object pointer.
        - cAm: The camera object pointer.
        """

        self.mTp      = mouseTrap
        self.settings = mouseTrap.settings
        self.cAm      = cAm
        self.mouse    = cAm.mouse
        
        self.step     = self.settings.stepSpeed
        self.active   = False

        self._registerMapperEvents()

    def _registerMapperEvents( self ):
        """
        Register the mapper events needed.
        
        Arguments:
        - self: The main object pointer.
        """

        events.registerMapperEvent( "newProf", [ initX, initY ],
                                        [ endX, endY ], True, ["moveMode:%s" % setName, "clickDlgVisible:False"], self._moveMouse, 0, ARGS )


    def _moveMouse( self, *args ):
        """
        Perform the mouse pointer movements based on the 'MODE NAME'

        Arguments:
        - self: The main object pointer.
        """
        self.mouse.moveTo( X, Y )



    def drawMapper( self, context ):
        """
        Perform the mouse pointer movements based on the 'Drag Drop Mode'

        Arguments:
        - self: The main object pointer.
        - context: The Drawing area context to paint.
        """
        
        self.cAm.gui.mapper.drawLine(context, initX, initY, endX, endY,  (255, 255, 255) )
        return True
    

NOTE: For Extra information about the functions called inside each function see the docs found under the docs/ folder.