Project
index
/home/david/Projects/Jokosher/trunk/Jokosher/Project.py

#       THIS FILE IS PART OF THE JOKOSHER PROJECT AND LICENSED UNDER THE GPL. SEE
#       THE 'COPYING' FILE FOR DETAILS
#
#       Project.py
#       
#       This module is the central non-gui class for Jokosher. It saves and loads
#       project files, and handles any project wide functionality including;
#       settings, instruments, recording, playing, exporint, zooming, scrolling, 
#       undo, redo, volume, etc.
#
#-------------------------------------------------------------------------------

 
Modules
       
AlsaDevices
Globals
TransportManager
Utils
dbus
gettext
gnomevfs
gobject
gst
gtk
gzip
math
os
pygst
re
shutil
time
urlparse
xml.dom.minidom

 
Classes
       
Monitored.Monitored
Project
exceptions.EnvironmentError(exceptions.StandardError)
OpenProjectError
exceptions.Exception
AudioInputsError
CreateProjectError
InvalidProjectError

 
class AudioInputsError(exceptions.Exception)
    This class will get created when there are problems with the soundcard inputs.
It's used for handling errors.
 
  Methods defined here:
__init__(self, errno)
Creates a new instance of AudioInputsError.
 
Parameters:
        errno -- number indicating the type of error:
                        1 = no recording channels found.
                        2 = sound card is not capable of multiple simultaneous inputs.
                        3 = channel splitting element not found.

Methods inherited from exceptions.Exception:
__getitem__(...)
__str__(...)

 
class CreateProjectError(exceptions.Exception)
    This class will get created when creating a Project fails.
It's used for handling errors.
 
  Methods defined here:
__init__(self, errno)
Creates a new instance of CreateProjectError.
 
Parameters:
        errno -- number indicating the type of error:
                        1 = unable to create a Project object.
                        2 = path for Project file already exists.
                        3 = unable to create file. (Invalid permissions, read-only, or the disk is full).
                        4 = invalid path, name or author.
                        5 = invalid uri passed for the Project file.

Methods inherited from exceptions.Exception:
__getitem__(...)
__str__(...)

 
class InvalidProjectError(exceptions.Exception)
    This class will get created when there's an invalid Project.
It's used for handling errors.
 
  Methods defined here:
__init__(self, missingfiles, missingimages)
Creates a new instance of InvalidProjectError.
 
Parameters:
        missingfiles -- filenames of the missing files.
        missingimages -- filenames of the missing images.

Methods inherited from exceptions.Exception:
__getitem__(...)
__str__(...)

 
class OpenProjectError(exceptions.EnvironmentError)
    This class will get created when a opening a Project fails.
It's used for handling errors.
 
 
Method resolution order:
OpenProjectError
exceptions.EnvironmentError
exceptions.StandardError
exceptions.Exception

Methods defined here:
__init__(self, errno, info=None)
Creates a new instance of OpenProjectError.
 
Parameters:
        errno -- number indicating the type of error:
                        1 = invalid uri passed for the Project file.
                        2 = unable to unzip the Project.
                        3 = Project created by a different version of Jokosher.
                        4 = Project file doesn't exist.
        info -- version of Jokosher that created the Project.
                        Will be present only along with error #3.

Methods inherited from exceptions.EnvironmentError:
__str__(...)

Methods inherited from exceptions.Exception:
__getitem__(...)

 
class Project(Monitored.Monitored)
    This class maintains all of the information required about single Project. It also
saves and loads Project files.
 
  Methods defined here:
AddInstrument = UndoWrapper(funcSelf, *args, **kwargs)
This function will wrap and take the place of the function
that is being decorated. All arguments to the original function
will be saved, and sent to the decorated function call.
The funcSelf value must be the first parameter, because
the first parameter will always be self, and it carries a
reference to the decorated function's class.
 
Considerations:
        All decorated undo functions *must* be in a class or this will fail.
        
Parameters:
        funcSelf -- reference to the decorated function's class.
        *args -- parameters meant for the decorated function.
        **kwargs -- dictionary of keyword:value parameters meant
                                for the decorated function.
 
Returns:
        the wrapped function resulting value.
AppendToCurrentStack(self, object)
Appends the action specified by object onto the relevant
undo/redo stack.
 
Parameters:
        object -- action to be added to the undo/redo stack
CanPerformRedo(self)
Whether it's possible to perform an redo operation.
 
Returns:
        True -- there is another redo command in the stack that can be performed.
        False -- there are no available redo commands.
CanPerformUndo(self)
Whether it's possible to perform an undo operation.
 
Returns:
        True -- there is another undo command in the stack that can be performed.
        False -- there are no available undo commands.
CheckUnsavedChanges(self)
Uses boolean self.unsavedChanges and Undo/Redo to 
determine if the program needs to save anything on exit.
 
Return:
        True -- there's unsaved changes, undoes or redoes
        False -- the Project can be safely closed.
ClearClickTimes(self)
Clears the click track controller times.
ClearEventSelections(self)
Clears the selection of any events.
CloseProject(self)
Closes down this Project.
DeleteInstrument = UndoWrapper(funcSelf, *args, **kwargs)
This function will wrap and take the place of the function
that is being decorated. All arguments to the original function
will be saved, and sent to the decorated function call.
The funcSelf value must be the first parameter, because
the first parameter will always be self, and it carries a
reference to the decorated function's class.
 
Considerations:
        All decorated undo functions *must* be in a class or this will fail.
        
Parameters:
        funcSelf -- reference to the decorated function's class.
        *args -- parameters meant for the decorated function.
        **kwargs -- dictionary of keyword:value parameters meant
                                for the decorated function.
 
Returns:
        the wrapped function resulting value.
DisableClick(self)
Mutes and disables the click track.
EnableClick(self)
Unmutes and enables the click track.
ExecuteAction(self, undoAction)
Executes an AtomicUndoAction object, reverting all operations stored
in it.
        
Parameters:
        undoAction -- the instance of AtomicUndoAction to be executed.
Export(self, filename, format=None)
Export to location filename with format specified by format variable.
 
Parameters:
        filename -- filename where the exported audio will be saved.
        format -- string of the file extension as used in Globals.EXPORT_FORMATS:
                        "ogg"
                        "mp3"
                        "wav"
                        *if no format is given, it'll be guessed by the file extension*
GenerateUniqueID(self, id=None)
Creates a new unique ID which can be assigned to an new Project object.
 
Parameters:
        id -- an unique ID proposal. If it's already taken, a new one is generated.
        
Returns:
        an unique ID suitable for a new Project.
GetExportProgress(self)
Returns a tuple with the number of seconds exported
and the number of total seconds.
GetIsExporting(self)
Returns true if the Project is not in the stopped state,
because paused, playing and recording are all forms of playing.
GetIsPlaying(self)
Returns true if the Project is not in the stopped state,
because paused, playing and recording are all forms of playing.
GetProjectLength(self)
Returns the length of the Project.
 
Returns:
        lenght of the Project in seconds.
MakeProjectSink(self)
Contructs a GStreamer sink element (or bin with ghost pads) for the 
Project's audio output, according to the Global "audiosink" property.
 
Return:
        the newly created GStreamer sink element.
MoveInstrument = UndoWrapper(funcSelf, *args, **kwargs)
This function will wrap and take the place of the function
that is being decorated. All arguments to the original function
will be saved, and sent to the decorated function call.
The funcSelf value must be the first parameter, because
the first parameter will always be self, and it carries a
reference to the decorated function's class.
 
Considerations:
        All decorated undo functions *must* be in a class or this will fail.
        
Parameters:
        funcSelf -- reference to the decorated function's class.
        *args -- parameters meant for the decorated function.
        **kwargs -- dictionary of keyword:value parameters meant
                                for the decorated function.
 
Returns:
        the wrapped function resulting value.
OnAllInstrumentsMute(self)
Mutes all Instruments in this Project.
Pause(self)
Play(self, newAudioState=None)
Start playback or recording.
 
Parameters:
        newAudioState -- determines the Project audio state to set when playback commences:
                                        AUDIO_PAUSED or AUDIO_PLAYING = move the graphical indicator along playback.
                                        AUDIO_EXPORTING = perform playback without moving the graphical bar.
        recording -- determines if the Project should only playback or playback and record:
                                True = playback and record.
                                False = playback only.
PrepareClick(self)
Prepares the click track.
Record(self)
Start recording all selected instruments.
Redo(self)
Attempts to redo the last undone action.
ResurrectInstrument = UndoWrapper(funcSelf, *args, **kwargs)
This function will wrap and take the place of the function
that is being decorated. All arguments to the original function
will be saved, and sent to the decorated function call.
The funcSelf value must be the first parameter, because
the first parameter will always be self, and it carries a
reference to the decorated function's class.
 
Considerations:
        All decorated undo functions *must* be in a class or this will fail.
        
Parameters:
        funcSelf -- reference to the decorated function's class.
        *args -- parameters meant for the decorated function.
        **kwargs -- dictionary of keyword:value parameters meant
                                for the decorated function.
 
Returns:
        the wrapped function resulting value.
SaveProjectFile(self, path=None)
Saves the Project and its children as an XML file
to the path specified by file.
 
Parameters:
        path -- path to the Project file.
SelectInstrument(self, instrument=None)
Selects an instrument and clears the selection of all other instruments.
 
Parameters:
        instrument -- Instrument object corresponding to the selected instrument.
SetAudioState(self, newState)
Set the Project's audio state to the new state enum value.
 
Parameters:
        newState -- the new state to set the Project to.
SetBPM = UndoWrapper(funcSelf, *args, **kwargs)
This function will wrap and take the place of the function
that is being decorated. All arguments to the original function
will be saved, and sent to the decorated function call.
The funcSelf value must be the first parameter, because
the first parameter will always be self, and it carries a
reference to the decorated function's class.
 
Considerations:
        All decorated undo functions *must* be in a class or this will fail.
        
Parameters:
        funcSelf -- reference to the decorated function's class.
        *args -- parameters meant for the decorated function.
        **kwargs -- dictionary of keyword:value parameters meant
                                for the decorated function.
 
Returns:
        the wrapped function resulting value.
SetLevel(self, level)
Sets the current REPORTED level, NOT THE VOLUME!
 
Parameters:
        level -- a value in the range [0,1]
SetMeter = UndoWrapper(funcSelf, *args, **kwargs)
This function will wrap and take the place of the function
that is being decorated. All arguments to the original function
will be saved, and sent to the decorated function call.
The funcSelf value must be the first parameter, because
the first parameter will always be self, and it carries a
reference to the decorated function's class.
 
Considerations:
        All decorated undo functions *must* be in a class or this will fail.
        
Parameters:
        funcSelf -- reference to the decorated function's class.
        *args -- parameters meant for the decorated function.
        **kwargs -- dictionary of keyword:value parameters meant
                                for the decorated function.
 
Returns:
        the wrapped function resulting value.
SetTransportMode = UndoWrapper(funcSelf, *args, **kwargs)
This function will wrap and take the place of the function
that is being decorated. All arguments to the original function
will be saved, and sent to the decorated function call.
The funcSelf value must be the first parameter, because
the first parameter will always be self, and it carries a
reference to the decorated function's class.
 
Considerations:
        All decorated undo functions *must* be in a class or this will fail.
        
Parameters:
        funcSelf -- reference to the decorated function's class.
        *args -- parameters meant for the decorated function.
        **kwargs -- dictionary of keyword:value parameters meant
                                for the decorated function.
 
Returns:
        the wrapped function resulting value.
SetViewScale(self, scale)
Sets the scale of the Project view.
 
Parameters:
        scale -- view scale in pixels per second.
SetViewStart(self, start)
Sets the time at which the Project view should start.
 
Parameters:
        start -- start time for the view in seconds.
SetVolume(self, volume)
Sets the volume of an instrument.
 
Parameters:
        volume - a value in the range [0,1]
Stop(self, bus=None, message=None)
Stop playback or recording
 
Parameters:
        bus -- reserved for GStreamer callbacks, don't use it explicitly.
        message -- reserved for GStreamer callbacks, don't use it explicitly.
TerminateExport(self, bus=None, message=None)
GStreamer End Of Stream handler. It is connected to eos on 
mainpipeline while export is taking place.
 
Parameters:
        bus -- reserved for GStreamer callbacks, don't use it explicitly.
        message -- reserved for GStreamer callbacks, don't use it explicitly.
TerminateRecording(self)
Terminate all instruments. Disregards recording when an 
error occurs after instruments have started.
Undo(self)
Attempts to revert the last user action by popping an action
from the undo stack and executing it.
ValidateProject(self)
Checks that the Project is valid - i.e. that the files and 
images it references can be found.
 
Returns:
        True -- the Project is valid.
        False -- the Project contains non-existant files and/or images.
__init__(self)
Creates a new instance of Project with default values.

Data and other attributes defined here:
AUDIO_EXPORTING = 4
AUDIO_PAUSED = 3
AUDIO_PLAYING = 2
AUDIO_RECORDING = 1
AUDIO_STOPPED = 0

Methods inherited from Monitored.Monitored:
AddListener(self, obj)
Adds an object to report changes to.
 
Parameters:
        obj -- an object to inform when StateChanged is called.
ClearListeners(self)
Remove all listeners to allow them to be destroyed.
RemoveListener(self, obj)
Stop reporting changes to the specified object.
 
Parameters:
        obj -- the object which should no longer receive change updates.
StateChanged(self, change=None, *extra)
This method should be called when we want a change to be reported
to all objects previously added by AddListener. 
 
Parameters:
        change -- the change which has occured.
        extra -- any extra parameters that should be passed.

 
Functions
       
CreateNew(projecturi, name, author)
Creates a new Project.
 
Parameters:
        projecturi -- the filesystem location for the new Project.
                                        Currently, only file:// URIs are considered valid.
        name -- the name of the Project.
        author - the name of the Project's author.
        
Returns:
        the newly created Project object.
LoadFromFile(uri)
Loads a Project from a saved file on disk.
 
Parameters:
        uri -- the filesystem location of the Project file to load. 
                        Currently only file:// URIs are considered valid.
                        
Returns:
        the loaded Project object.
LoadFromZPOFile(project, doc)
Loads a project from a Jokosher 0.1 (ZPO) Project file into
the given Project object using the XML document doc.
 
Parameters:
        project -- Jokosher 0.1 (ZPO) Project file.
        doc -- XML document doc used to load the 0.1 Project into the given 0.2+ Project object.
        
Returns:
        the loaded Project object.

 
Data
        GlobalProjectObject = None