User:Fiddle~enwikibooks/WinCVS

This page describes the WinCVS 2.0 Python API. WinCVS can be downloaded from the WinCVS Home page. See also here for Copyright info.

=WinCVS Python API=

cvsgui.Macro module
This module defines the Macro class, which is used to extend the capabilities of cvsgui. The user can add new macros by subclassing the Macro class. Here is a trivial example:

import cvsgui.Macro class ThisIsATrivialUserMacro( Macro ): def __init__( self ): cvsgui.Macro.Macro.__init__( self, 'MyItem', MACRO_SELECTION, 0, 'MySubMenu' ) def Run( self ): print 'MyMacro has been called' ThisIsATrivialUserMacro Registering this macro adds a submenu 'MySubMenu' to the 'Macros' menu (if the submenu doesn't exist already), and in it creates one new item 'MyItem', with trivial action. See below for more details.
 * 1) Register the new macro by executing the class

Variables
Constants used by the Macro class: MACRO_SELECTION = "SELECTION" MACRO_ADMIN 	= "ADMIN"

Functions
none

Class: Macro
This class needs to be subclassed to implement a user macro. Executing the new subclass adds the macro to the cvsgui macro registry (this is done by a call to Macro.__init__). You can overwrite the methods of the Macro class and add your own methods. See method descriptions below for details.

Methods:
Since Macro is usually subclassed, the self argument has been retained in the following descriptions. To implement your own macro override each of the following methods


 * __init__(self) : This method should always be overridden. It should always start with a call to: Macro.__init__(self, title, group, isCheck=0, subgroup="", xpmicon="") to register the macro in the registry with the appropriate arguments:Title is the text that will appear on the menu entry; appending a tab(\t) and a combination of either CTRL or ALT, or both, and a letter will register that as the menu accelerator(e.g. "MenuTitle\tCTRL+ALT+M"). Group needs to be MACRO_SELECTION or MACRO_ADMIN; if it is not macro registration will fail. MACRO_SELECTION macros appear in the 'Macros' menu, MACRO_ADMIN macros appear in the 'Admin>>Macro' menu item.IsCheck specifies whether the menu item can have a checkmark in front. Default = 0 (no check mark) . If the macro menu item should appear in a subfolder, specify the subfolder name in subgroup; default is "" (no subfolder).Xpmicon specifies an optional icon that appears in front of the item; default is "" (no icon). Xpmicon uses a special string format .After this call add initilisation your macro may require.


 * OnCmdUI( self, cmdui ) : This method is called from the Python interface (_cvsgui) for the macro to define its state (enabled/disabled). This call occurs whenthe users clicks on the 'Macros' or the 'Admin>>Macro' menu. The 'cmdui' argument passed by the interface is the CmdUI object corresponding to the selected macro. For a MACRO_SELECTION macro, default behavior is that the menu item is only enabled when there is a (non-zero) selection active. Default for MACRO_ADMIN macros is to be enabled them on this call. Override this method to change the default behavior.


 * Run(self) : This Method is called from the interface when the macro is selected. Default is to do nothing. Override to add an action to the macro.

Class: TclMacro
Subclass of Macro: This class wraps Tcl macros
 * TclMacro( title, group, file ) : Create a Tcl Macro from file.

Methods:

 * Run : Called from the interface when the macro is selected

Class: MenuSeparator( subclass of Macro)
This class is a convenient way to insert a menu separator
 * MenuSeparator( group, subgroup="" ) :

cvsgui.App module
Provides interaction with the cvsgui application.

Functions

 * cvs_out( s ) [deprecated] : Print text in the application console. This is for backward compatibility only, you can use sys.stdout directly


 * cvs_err( s ) [deprecated] : Print text in the application console. This is for backward compatibility only, you can use sys.stderr directly


 * GetSelection : Return a list of the CvsEntry, or CvsEntries, that is/are currently selected in the file or folder browser. Each element in the list is a CvsEntry class.


 * PromptMessage( msg, title="Message", default="OK", cncl="Cancel" ) : Pops up a message box with a message. Returns 1 (OK button pressed, default) or 0 (cancel).


 * PromptEditMessage( msg, value, title="Message", default="OK", cncl="Cancel" ) : Pops up a message box with message string 'msg', and an edit box in which the user can verify or edit 'value'. Returns a list with two entries 1 + (updated) value when the user presses OK (default) or 0 (cancel). Note: the value of the title parameter is not passed and always shows up as "Title". This is a bug in the Cvsgui source code (not in the python interface).


 * LaunchBrowser( url ) : Launch a web browser with the URL

cvsgui.CmdUI module
CmdUI class, set the state of an object in the interface

Variables
TRUE FALSE

Class: CmdUI
This class is a wrapper around Windows CmdUI objects defined in the WinCVS interface. It defines the UI element associated with a command and lets you manipulate its state. The instances of this class are always created by the interface _cvsgui (and the corresponding Windows object is placed in an internal variable) <need check this - but I haven't found any place where CmdUI is called>. When passed back to Python, they usually show up as argument to a OnCmdUI call, where the user can set attributes: en-/dis-abled, set text, checkmarks etc.

Methods:

 * Enable( state ) : Enable (state=1)/Disable (state=0) the object (i.e. menu entry, icon...).


 * SetCheck( state ) : Check(state=1)/uncheck(state=0) the object (i.e. menu entry, icon...)


 * SetText( text ) : Rename the object (i.e. menu entry, icon...)

cvsgui.ColorConsole module
ColorConsole class, provides *some* coloring in the console window

Variables
kNormal, kBrown, kGreen, kMagenta, kRed, kBlue,	kBold, kItalic, kUnderline, kNL

Class: ColorConsole

 * ColorConsole : ColorConsole class, provides *some* coloring in the console window

Methods:

 * out( stringOrStyle ) : Print text in the application console


 * Operator << : Print text in the application console, e.g.: <tt>ColorConsole << kRed << "This is red"</tt>.

cvsgui.Cvs module
Defines Cvs class, which launches cvs

Variables
None

Functions
None

Class: Cvs

 * Cvs( quiet = 0, exitOnError = 1 ) : Initialize and optionally set the exitOnError flag; if true, cvs will throw an exception on an error (default is true). The quiet flag tells if stderr and stdout of the cvs process are reported into the client console (default is false)

Methods:

 * Run( *args ) : Launch a cvs process with some arguments, return the error code, stdout and stderr of the process. Throws if an error occur if exitOnError is true

cvsgui.CvsEntry module
CvsEntry class, information for an entry of CVS/Entries

Variables
none

Functions
none

Class: CvsEntry

 * CvsEntry( entry ) : Create instance of CvsEntry class for entry

Methods:

 * GetName : Return the name of the entry (file/folder) without its path


 * GetFullName : Return the full qualified name of the entry (file or folder)


 * GetPath : Return the full qualified name of the parent folder, i.e. the folder the entry is in


 * GetVersion : Return the revision number of the file


 * GetUTC : Return the modification time (in UTC) of the repository file which was used to update the file for the last time


 * GetKeyword : Return the substitution keyword for the file


 * GetTag : Return the name of the tag (or the branch) where the file is checked out


 * IsFile : Return true for a file, false for a folder


 * IsModified : Return true if the file is modified locally


 * IsMissing : Return true if the file/folder is missing locally


 * IsUnknown : Return true if the file/folder is not part of cvs (i.e. needs to be added)


 * IsIgnored : Return true if the file/folder is ignored because of the presence of a .cvsignore file (either in the same folder or in the home folder)


 * IsReadOnly : Return true if the file is read only on the file system


 * IsRemoved : Return true if the file is scheduled for removing


 * IsAdded : Return true if the file is scheduled for adding


 * GetDesc : Return a literal description of the state of the file


 * GetConflict : Return the conflict information for the file (if any) or an empty string


 * GetCvsEntriesList( path ) : Return a list of CvsEntries for the directory


 * GetCvsEntriesDict( path ) : Return a dictionary of CvsEntries for the directory (filename -> CvsEntry)


 * GetFileModTime( path ) : Return the UTC modification time for a file. Corrects for DST bug.

cvsgui.CvsLog module
CvsLog class, return the history of the file

Functions

 * GetHistoryAsXML( filename ) : Return the cvs history of the file in an xml format, it returns the result in a temporay file you can erase or rename afterwards.

cvsgui.MenuMgr module
Menu manager class, manipulates the menu bar of the cvsgui client

Variables
none

Functions
none

Class: Menu

 * Menu( menu ): Menu class, let you extend the menu entries

Methods:

 * AddPulldown( widid, name ) : Add a pulldown to the top menu. If top is NULL, then add it to the main menu bar


 * AddToggle( widid, name, cmd, pixmap = "" ) : Add a check box to the top menu.


 * AddButton( widid, name, cmd, pixmap = "" ) : Add a regular text entry to the top menu.


 * AddSeparator( widid ) : Add a separator to the top menu.


 * Delete( afterIndex ) : Remove a menu entry after an index (all of them).


 * DeleteByCmd( cmd ) : Remove a menu entry by command id.


 * Count : Return the number of menu entries in the top menu.


 * GetNewCmdID: Return a new command ID to use for a menu entry. The ID values are incremented by one on each call. By default they start at 10000; for Windows the first ID is 34000, for the Darwin OS or macOS the first ID is 3200.


 * GetTopMacroSelectionMenu : Return the default pulldown for the macro selection menu


 * GetTopMacroAdminMenu : Return the default pulldown for the macro admin menu


 * GetMainMenuWidget : Return the id of the default menu controller (pseudo widget)

cvsgui.Persistent module
Persistent class, allows to store persistent values on disk, i.e. values that are kept after the application restarts

Variables
none

Functions
none

Class: Persistent

 * Persistent( token, defvalue="", addToSettings=0 ): Create/access a persistent value, the token is used to identify the persistent value

Methods:

 * GetValue : Return the current value


 * SetValue( value ) :	Set to Value


 * Operator << :	Same as SetValue, e.g.: Persistent << 'value'


 * __str__: Return the current value

cvsgui.MacroRegistry module
Macro registry class, place to register and manipulate macros This module is called by WinCVS at startup; it loads the Python API and the macro script file in the $(CVS_HOME)/Macros folder.

Variables

 * gMacroRegistry : contains the CVSgui macro registry

Functions
none

Class: MacroRegistry
Class which retains the active macros
 * MacroRegistry : Create a new MacroRegistry instance.

Methods:

 * AddMacro( macro ) : Add a instance of Macro class to the registry. Will generate an error if the macro has not been created with group <tt>MACRO_SELECTION</tt> or <tt>MACRO_ADMIN</tt>.


 * CreateMenusForGroup( top, group ) : <Add help here>


 * CreateMenus : Called by the cvsgui client to create the macros menus


 * AddTclMacro( filename ) : Adds macro from Tcl file. Requires the Tcl file to have a header on the first line as follows: <tt>#!CVSGUI1.0 [--admin|--selection] --name "The name which appears in the menu"</tt> If either this header line or <tt>--name</tt> attribute are missing the method does nothing.


 * LoadMacrosRecurs( dir ) : Recursively loads all macro file in folder dir


 * LoadMacros( dir ) : Iterate thru a folder and evaluate each python file


 * DeleteMenus : Delete the menus used by the macros


 * ReloadMacros : Reload the macros, re-create the menus


 * DoCmdUI( cmdui, cmdid ) : Triggered by the interface when a menu entry needs to update its state


 * DoCmd( cmdid ) : Triggered by the interface when a menu entry is selected

cvsgui.MyPyShellWindow module
Creates new shell if called from __main__

Variables
New style numbers: _stdout_style = 15,_stderr_style = 16, _trace_style = 17 shell - contains the global shell in a MyPyShellWindow.

Functions
None

Class: MyPyShellWindow
Parent class is: InteractiveInterpreter
 * MyPyShellWindow( locals=None, banner=None ) : Create new window with PythonInterpreter

Methods:

 * _write( text, style=_stdout_style ): used for writing to stdout, etc.


 * writeTrace( text ): used for writing to stdout, etc. <Add help here>

Following are overloaded methods from InteractiveInterpreter:
 * runsource( source ) : <Add text here>


 * showsyntaxerror( filename=None ) : <Add text here>


 * showtraceback : <Add text here>

Class: FauxFile

 * FauxFile( psw, style ) : <Add text here>

Methods:

 * write( text ) : <Add text here>


 * writelines( lst ) : <Add text here>


 * flush : <Add text here>

_cvsgui module
Built-in module that provides the low level Python interface to the Cvsgui application. Do not call directly; instead use the cvgui.* submodules.

Module variables/Functions
Here's a list of symbols defined in _cvsgui. I have tentatively added some brackets where I think the functions are but I have to check this...
 * CCmdUI
 * CColorConsole
 * CCvsEntry
 * CMenuMgr
 * CPersistent
 * CVSGUI_VERSION
 * GetCvsEntries
 * GetFileModTime
 * GetHistoryAsXML <Appears to crash WinCVS on my Win98SE>
 * GetMainMenuWidget
 * GetSelection
 * GetTopMacroAdminMenu
 * GetTopMacroSelectionMenu
 * LaunchBrowser
 * LaunchTclMacro
 * PromptEditMessage
 * PromptMessage
 * RunCvs
 * __doc__
 * __name__
 * error
 * kBlue, kBold, kBrown, kGreen, kItalic, kMagenta, kNL, kNormal, kRed, kUnderline
 * write

=Support Modules= The following modules are written by Oliver Giesen

Variables
None

Functions

 * prepareTargets(entries, args, doChDir = 1) : Given a CvsEntries list, calculates a common basedir and a corresponding list of targets. This is necessary in order to ensure correct behaviour when working on flat view selections. See macros cvs2cl.py or TagAndUpdate.py for examples of usage.


 * purgeTree(path) : shutil.rmtree cannot delete read-only files, so we need to do it manually by changing the attributes on each file to r/w before deleting.

Classes
None

cvsgui.SafeTk module
When using Tkinter, the module FixTk is imported which creates an environment variable TCL_LIBRARY and points it at the TCL libraries within the Python installation. This has the unfortunate effect that TCL macros running from a separate installation of TCL will now try to locate packages within the Python directories instead of the TCL ones, which usually fails because the directories within the Python installation are named differently. This module employs a fix to this by removing said environment variable and only temporarily enabling it for the lifetime of a Tkinter-based Tk instance.

Variables
TCL_LIB = 'TCL_LIBRARY' tcllib : set with value of 'TCL_LIBRARY' environment variable when module is loaded.

Functions

 * prepTk : Ensure that TCL_LIBRARY points to the path determined in the FixTk module


 * resetTk : Delete the TCL_LIBRARY environment variable, so TCL has to go searching for extension packages on its own instead of depending on the Python search path. Make a backup of the value determined in the FixTk module so we could write it back again later.

Class: SafeTkRoot

 * SafeTkRoot( Tk ) : A replacement for the Tk class which ensures the TCL_LIBRARY variable lives only as long as the Tk-instance does.


 * SafeTkRoot( obj ) : set basename to obj

Methods:

 * destroy : <Add text here>


 * checkTk : Checks whether Tk could be invoked without exceptions. The check is only performed once. Later calls simply return the previous result.

Known Issues

 * It is currently possible to select invalid combinations of flags, e.g. -kbo.

Variables
none

Functions
none

Class: CvsSubstModeMenu

 * CvsSubstModeMenu( Menu ) : ADD HELP. Will only be created if Tk is available (check with checkTk.

Methods:

 * update(text) : <Add text here>


 * createWidgets( oldenc ) : <Add text here>


 * clear : <Add text here>

Class: CvsSubstModeUI

 * class CvsSubstModeUI( Frame ) : <Add text here>


 * CvsSubstModeUI( master, var ) : Will only be created if Tk is available. <Add text here>

Methods:

 * get_mnu : <Add text here>


 * popup(event=None) : <Add text here>


 * createWidgets : <Add text here>


 * updateMnu(event) : <Add text here>


 * setFlags : <Add text here>


 * CvsSubstModeUI.updateLabel(flags) : <Add text here>

Copyright
This page describes the functions in WinCVS 2.0 Python API, which is part of WinCVS (download here). WinCVS is distributed under the GNU GPL.

This program 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 1, or (at your option) any later version.

This program 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 this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.