Issues and To Do list for PythonCard release 0.8

Introduction

PythonCard Changes : 0.7.3.x -> 0.8

Release 0.8 is the first step towards making a 1.0 release. It is the release where we will do the most cleanup of old code that is no longer relevant and add the items that we must have for 1.0.

minimal requirements [DONE]

Python 2.3

assert added to model.py

wxPython 2.5 to wxPython 2.6

assert added to model.py

No abbreviations

Please do not use abbreviations in module, class or method names. Fix all occurrences that exist now.

Fix all Singletons [PARTLY DONE]

All singletons ( log.Log, config.Configuration, etc. ) must inherit from singleton.Singleton. This will require changing all usage of the singletons throughout the code.

• registry.py
• resource.py
• log.py
• configuration.py

Remove module functions

PythonCard should contain no module functions. Module functions, such as those currently found in log.py and config.py should be removed and all usage should be via the Singleton package.

Framework internal documentation

Create a script, PythonCard/docs/make.py, that will generate the api documentation for the PythonCard package and all subpackages/modules in PythonCard/docs/api.

package name change [DONE]

Change

• from PythonCardPrototype import

to

• from PythonCard import

Change

• import PythonCardPrototype

to

• import PythonCard

Change

• PythonCardPrototype.

to

• PythonCard.

Remove binding.py [DONE]

• Move binding code to Widget and Background, respectively? Is Background really that different than Widget?
• *Yes - binding code inlined into metds in Background.
• Refactor binding code into Widget and Background, get rid of binding.py

• *event.py now contains IEventBinding and DefaultEventBinding.

• *These classes are still used to bind events for components. Use template method pattern - subclasses of Widget (components), may implement a Widget._bindEvents method to bind component-specific

  wxPython events. No need to have an EventBinding subclass since we're not going to support multiple gui toolkits - it's wxPython or nothing.

  What is the purpose of SystemEvent? Why is it special?

• * It's not special - replaced with direct use of wx.PyCommandEvent.

• Refactor DispatchEvent to EventAdapter.

• *Done

Remove dispatch.py [DONE]

• Move classes in dispatch.py to event.py

Rename model.py -> application.py

Rename PythonCardApp -> Application [DONE]

In PythonCardApp.init, get rid of temporary configuration option variables. - Assign self._config = config.Configuration.getInstance() - Use self._config.get<OptionName> to access configuration options.

Rename Background -> Window

Need to decide if Window is the right name, is Frame, Form or Panel better?

Don't forget to update all the .rsrc.py files, resourceEditor, and documentation once this change is in place. Need to discuss name change on the mailing list since this impacts a lot of stuff.

rename or remove stack references [DONE]

In the rsrc.py files, maybe just remove it entirely or rename it to 'base' or something like that. We still need an overall container to hold the backgrounds (windows) list or do we just reduce that to a single background? There is also the list of strings.

• changed to application 2004-05-09

revisit the resource file format

See above. We could turn .rsrc.py into a normal Python module that we import rather than doing an eval. The module would have a variable = {...} format. We would have to drop the .rsrc.py form

Refactor config.py -> configuration.py [DONE]

= Rewrite configuration.Configuration as a true Singleton =

using the new-style 'class' methods, provide

• a Configuration.getInstance() method. Static method example:

  • >>> class A:

    • def method(x):
      • print "A.method",x
      method = staticmethod(method)

• - Configuration should have an accessor method for each
  • configuration option that is available.
    • For example: config.Configuration.getShowMessageWatcher()
  - The method getShowDebugMenu() should return true if - any of the runtime/debug windows are open.

Remove PythonCardObject and all references to it [DONE]

Remove ObjectMap and all references to it [DONE]

• Replace with simple map if necessary.

***replaced with array

Remove ObjectLookup and all references to it [DONE]

Change on_openBackground to initialize [DONE]

Rename pom.py -> component.py [DONE]

Unit Tests

Unit tests fall into three categories:

GUI Toolkit Tests - Using some (probably platform-specific) tool, test wxPython to ensure that wxWindows on platform X performs as expected.

Framework Unit Tests - use 'unittest' to test the various classes and subsystems of the PythonCard framework - mostly non-gui stuff.

Sample Tests - Use some combination of unittest and GUI test tools to ensure that the samples are well-behaved and perform as expected.

Come up with a series of tests to verify everything is still working as expected as we make changes. This might be as simple as running a few specific samples and tools, but it would be great if we could implement unit tests for some types of tests.

• Use 'unittest' framework to write unit tests for every framework module/class that it is possible to test. GUI testing, especially across platforms is going to be hard. What

  tools can we use? X11Test (GTK/Linux)?, what about Windows, OSX?

ComponentLoader

• Introduce ComponentLoader that can load a component from PythonCard.components,

  • or any other module/package. Allows users to use python packaging to organize their components. Support zipped packages?

Compound Components

Make Panel the basis for building custom, compound components.

blow away all old cruft code and comments [PARTLY DONE]

• "if ..." code blocks that are no longer relevant such as WXMAC_KEA_FIXED, wxPython 2.3.x workaround code
• blow away code that is commented out that doesn't need to stay in to explain why we did something a particular way. Replace comment block with some other comment if appropriate and reference back to a particular revision of the file in cvs if more explanation needed.
• I think I have removed all the WXMAC_KEA_FIXED blocks
• there are some WXMAC blocks left, but those are probably required

Wrap wxTimer [DONE]

Wrap wxTimer as Timer class so we can be consistent with PythonCard naming conventions

rename idle event?

Idle in wxWidgets is poorly named and quite misleading. It is the event that occurs when the event queue empties and has nothing to do with whether the machine is "idle". One typical place you will see a flurry of idle events is while moving the mouse and then beware if you have a long-running task called on idle. <wink> If a TextCtrl has focus then you will see idle events as the cursor blinks, but if the focus is on a control such as a Button you will only see one idle when the event queue empties and then no more until the user does something like move the mouse.

If you are using wx.WakeUpIdle() then you will still want to use an idle event handler, but depending on the situation there might be better alternatives such as wx.CallAfter() or using a timer. A number of samples and tools use idle handlers and these should be reevaluated.

I think that perhaps we should have a renamed method for WakeUpIdle or a special function to do CallAfter on whatever we rename idle too. I guess the event could be called eventQueueEmpty but I'm wary of using an event name with "Queue" in it since that is easy to misspell.

• possible names: eventQueueEmpty, noMoreEvents
• change samples and tools using threads and wxWakeUpIdle to use wxCallAfter instead with event being called keeping the same logic, just not named on_idle?

Enforce mixedCase method names [PARTLY DONE]

find all CamelCase methods still in use in samples and tools and wrap as mixedCase and update the samples and tools

• most of the remaining CamelCase methods in the samples and tools are for CodeEditor/wxSTC or unwrapped wxPython classes

Document API Changes [ONGOING]

make sure all API changes like this are explicitly called out in the changelog.txt file

Create a migration.html document

we should adapt this document for a user migration.html guide. check that one into docs\html. The migration guide has to cover each change that will require users changing their code or environment to run PythonCard 0.8.

More mixedCase vs CamelCase [PARTLY DONE]

decide whether to use class method aliases, instance var aliases, or wrap of CamelCase with mixedCase

• in Widget the methods are wrapped by mixedCase methods
• unless the method needs additional documentation or wrapping to modify behavior, class-level aliases are used

Document all classes and methods

add doc strings to methods

Document spec attributes

add document string to spec items, so attributes are documented

Switch to property() (wxPython 2.5) for attributes [DONE]

• if using wxPython 2.5, switch back to using property() for attributes

• look at getattr and setattr in widget.py and decide if needed

• fixed statusbar.py, font.py
• fixed widget.py and all components

add property attributes to Background, CustomDialog, and Panel [PARTLY DONE]

started for Background and CustomDialog in model.py - KEA 2004-04-13

• should Panel have attributes? If so, make sure this won't screw up the mouseDown, mouseDrag, etc. handling in the resourceEditor or other places where previously a random event from Panel would throw a runtime error because it doesn't have a .name attribute.
• added attributes to tool windows

Add MultipleSelectionList component

add MultipleSelectionList for List components that supports multi-selection?!

Update changelog.txt [ONGOING]

• make sure all changes go in the changelog.txt file as they are made

Developers always provide initials in comments

thoroughly comment as RDS or KEA as we make changes

Horizontal whitespace

• standardize on use of whitespace around () [] <- we can argue about it

Update docs with stylesheets [PARTLY DONE]

Andy Todd wants to update docs with style sheets http://www.halfcooked.com/pythoncard/

• the revised documentation is live on the main site and checked into PythonCardPrototype cvs, but not all the docs have been revised or checked into the PythonCard branch of cvs

Change wxPython import statements [DONE]

Change "from wxPython import wx" to "import wx" once we are on the 2.5.x track This should probably not be done as a global replace, but rather done file by file. see the wxPython migration guide. This is probably the single biggest amount of work that we will have to do. Most places will be a simple replace of "wx.wx" with "wx." and it will work with the new namespace. However certain files like turtle.py and bitmapcanvas.py or anything using DC methods has to go through the laborious change of x, y parameters to tuples (x, y). In fact, that is one of the API changes we have to decide to follow or not, but we probably will. I'm not positive, but some constants, most likely wxEVT kind of constants may still keep their wx prefix. Anyway, that's why we do this file by file, I suspect it will be difficult to track what we broke otherwise.

Remove irrelevant samples

• removed addresses052.py

Remove samples that we no longer want to highlight from the distribution, but leave them in cvs (proof?)

Create 'windows' sub-package [PARTLY DONE]

add windows sub-package to PythonCard for standard "backgrounds" that people might want to import? same thing for common CustomDialogs

this might be better to name templates with a sud-directory for windows and dialogs ? - KEA 2004-04-13

• added templates package with dialogs sub-package
• waiting on Background rename resolution before creating a "windows", "frames", 'panels", or "forms" sub-directory for what used to be called backgrounds

Rewrite samples as components

Rewrite the samples using the component model and composite components.

Rewrite the tools using components

Rewrite the tools using the component model and composite components.

update sound.py to use wx.Sound [PARTLY DONE]

It looks like we can still only play sound files in .wav format. sound.py only supports playing sound from a file, so we might want to expand its capabilities.

decide whether turtle module should use tuples

should the turtle.py module and sample use tuples like BitmapCanvas or keep logo-style x, y parameters? Right now I'm inclined to leave them as x, y to make it more like Logo turtle graphics, but it means when BitmapCanvas drawing is combined with turtle drawing calls it could get confusing, so maybe it would be better to always use tuples?

add additional Background events [PARTLY DONE]

I've added a deactivate event. I was going to add events for when a window is restored from a minimize and reduced from a maximize but all I'm seeing are move and size events. I don't know if that is a wxWidgets bug or a problem with the PythonCard framework, so I'll have to make a minimal wxPython sample to test before proceeding further.

Revisit the old to do list

revisit the to do list and decide which items will and won't make it

• http://wiki.wxpython.org/index.cgi/PythonCardToDoList

Rename res.py -> resource.py [DONE]

cleanup except blocks where pass is used

Many try/except blocks in the framework just call pass in the except block and errors need better handling.

switch to built-in exceptions when appropriate

We have a error.py module with some custom exceptions, but in some cases these aren't needed and it would be better to use Python built-in exceptions instead.

adopt more structured version scheme?

See wxPython version info. We could use a tuple for major and minor versions in addition or instead of a plain string.

make StatusBar a direct subclass [DONE]

also added createStatusBar method to Background and CustomDialog to enable applications to create their own more complex StatusBars

add ToolBar support similar to StatusBar

remove Ptr classes from isinstance checks [DONE]

add About PythonCard dialog to codeEditor and resourceEditor [DONE]

Put Debug About dialog in the codeEditor and resourceEditor to simplify users getting version info. Refactor the About dialog, maybe sticking it in its own module or in util.py

• created new about.py module, so the dialog doesn't rely on debug.py and can be easily used by any PythonCard application.

make a more elaborate About PythonCard dialog [CONTEST IN PROGRESS]

• the dialog can be made more complex, providing more debug info, hyperlinks, etc., and bug reporting submission button, etc. without impacting any code that uses the dialog. Maybe we should have a contest for people to submit designs?

• started content on mailing list for new About Dialog design. contest ends May 9th!

Perhaps we should even have a separate debug info tool that would list other useful info such the users PYTHONPATH, environment variables, and other system info that could provide clues.

refactor WidgetDict to a direct subclass of dict instead of UserDict

Thorougly test to make sure no functionality was lost.

figure out where extra Flush calls are coming from [DONE]

I'm seeing this type of message way too often in the shell while using the codeEditor. Is it in PyCrust or something in PythonCard/debug.py?! It is getting triggered during the autoComplete list display, so you can just type os.getcwd() and after that sequence 2 debug messages will show up.

13:19:49: Debug: ..\..\src\msw\clipbrd.cpp(561): 'OleFlushClipboard' failed with

• error 0x000000b7 (cannot create a file when that file already exists.).

remove or fix command events for Image, BitmapCanvas, Static...?

We have the 'command' event type bound to all components, but command doesn't work for components that don't have some form of wxPython Command event like mouseClick or select. mouse event are a bit tricky with these types of controls so that on GTK you might not even receive a mouse down if the underlying control isn't native. In that case, say Linux/GTK the mouse event will be seen by the underlying panel.

I suppose we might be able to bind the panel events and then manually hook them up to the right component, but that still won't give us command events for those controls. I suppose we could use the mouseUp for command as long as we the mouse event binding right.

figure out if skip handlers can be removed from dialogs [DONE]

There are a number of CustomDialogs that have handlers for the OK and Cancel buttons and do nothing more than call event.skip(). I think this requirement went away as soon as we started providing OK and Cancel ids for the dialogs, but I need to double-check and then update all the findDialogs...

• it appears that as long as the correct button ids are used for "ok" and "cancel" you don't need to have a specific event handler the buttons

• I left the on_mouseClick handler in CustomDialog which automatically calls skip just in case there is more to the issue

standardize runScript

util.py should contain the standard runScript used by the samples launcher, codeEditor, resourceEditor, findfiles, etc. Need to get the quoting right on all platforms.

add TwistedApplication and samples [DONE]

• add a TwistedApplication subclass of Application

• add some twisted samples: echo client, Stephen Waterbury's pbwxthing, battleship?
• added twistedEchoClient on 2004-04-27, will add other samples if they become available

add statusbar subclass example

unit tests for util.py

add wxPythonBugs dir or cvs tree

raw wxPython minimal samples to show particular bugs that impact PythonCard. Provide links to relevant bug reports and mailing list messages and remove bug sample once the issue is fixed.

fix memory leak in event dispatch [DONE]

Rewrite event subsystem [IN PROGRESS]

PythonCardNewEventSubsystem

generalize resourceEditor component handling [PARTLY DONE]

• generalize all component-specific handling if possible, so the needed info comes from the component spec.
  • building the Component menu, take items out of the resource file and instead scan components dir for component modules. will need to scan appcomponents or dynamically update list of available components. [DONE for built-in components]
  • widget creation (on_componentAdd_command). Maybe a simple short-term solution would be to have a method in the component class that the resourceEditor would call to get the info that it currently hard-coded in on_componentAdd_command?! [DONE]
  • update propertyEditor.py
  • update resourceOutput.py

various other resourceEditor fixes

• double-check the default properties for each object, for example the font is being saved for Calendar and it shouldn't be (see widgets.rsrc.py diff in cvs)

fix drag and resize logic in resourceEditor

• new methodology using screen capture of display
• There is a logic problem in the resourceEditor such that clicking in the panel causes the selected object to be lost so that attempting to drag the resize handles has no effect. This is almost certainly in the mouseDown handler, perhaps an earlier workaround for GTK/Linux or the Mac. It looks like 0.7.3.1 has this problem as well. [This item is fixed]

fix addMethod

Need to make sure a handler is bound to the right components after it is added. Maybe addMethod will take a list of objects to call _bindEvents on. See longer comment in addMethod source in model.py

Also see

• PythonCardToDoList

• changelog.txt