beta requirements

general concerns

what's the beta milestone to be? building fluency in fluency — too hard??? building an editable text-editor or web-browser – too easy??? an editable web-browser with a derby db backend to allow on-the-fly data annotation and visualization? (a la knownspace, or alek's reimplementation, IS^2)? a set of widgets plus widget framework built around gaming? allowing fluency to build web apps instead of/in addition to swing apps? whatever it is it should be sexy and fun, or really practical, or really demonstrative of fluency's power — ideally all three. if we can't think of something with all three properties perhaps the best thing is to have two milestones (simultaneously). two good choices might be the easily editable text editor that the author can swap in and out arbitrary controls for and something to do with gaming. that'd mix practicality appeal and fun appeal.

Dev Note Milestone - is editor that has "specific" functionality (as listed elsewhere) WITHOUT breaking.

functionality-preserving change — we should always have a working fluency. we need a robot (or something) that runs through some standard set of ui actions to increase the chance that we've preserved functionality with each code change.

Dev Note Functionality-preserving - Robot is bad way to test UI.

performance-preserving change — we need some kind of guarantee about preservation of performance. how to do that? fluency isn't about just being able to build some milestone, it's also about being able to build that milestone fluently (i.e. easily and well). continuous interaction with rick, and having rick try out the webstartable version often, should help. but it would be nice to have some automated help too. computers are better police than people. they're tireless--and they never make mistakes.

Dev Note Performance-preserving - We would really like to do this. We need a better definition of performance or some sort of metrics to measure this.

demos

• whatever the milestone for beta, fluency should come with a set of (separable) demos and tutorials of what it can do. at least one of them should be in an author-editable state, with suggestions on what to do to the app next so that it becomes cooler or more powerful. such steps should be easy at first then progressively more challenging. the author should get the idea quickly and easily that anything is (potentially if not actually) changeable, and that fluency can be a powerful or fun (ideally both) tool but it can also be approached in a staged fashion, with a very low learning curve needed to then build fun or interesting or practical things (ideally all three, of course). making simple 'widget games' (like the whack-a-mole checkbox example) might be good. minesweeper with invisible buttons or possibly solitaire with text labels are other possibilities.

  Dev Note Demos & Tutorials - Definitely. Based on milestones. Not for this beta. Definitely based on audience.

• there should also be a demo for building a new widget, given a java class. we want to encourage widget creation.

  Dev Note Basic function demos - Without a doubt. But this should come after basic textual help (with screenshots).

documentation

• fluency should come with an author manual, with emphasis on examples, not on the typical bunch of rules of how to use (or misuse) the program.

• fluency should come with a developer's manual as well. we want to encourage (at least) widget developers too.

  Dev Note Manuals - Yes. But when and by whom? We will slowly be creating developers manual as time goes on (and some author stuff)

• sets of pipes should be markupable with comment blocks so that a fluency app is 'documentable' within fluency itself (i.e. by just running the app in the editor, not by first having to read some big manual first).

  Dev Note Markups - Absolutely. But that is thinking too small. EVERYTHING should be able to have markup attached to. Should be an integral part of editor

infrastructure

• move to subversion.

  Dev Note SVN - After beta, plan is to put it on SourceForge and then we can use their SVN setup.

• rename 'unknownspace' back to 'knownspace'.

• rename/reorganize packages to better reflect the actual subdivisions of the program. this will require some debate to decide what those should actually be; right now dennis and mark want to call the backend 'the engine'. but we also need to decide how various versions of fluency should be deployed---editor + runtime, runtime only, apps made into jars, etc.

  Dev Note Rename/Reorganize - Done.

• near-automatic demo production as part of the build cycle for successful builds. (we'll first need a robot--see 'refactoring' below.)

  Dev Note Auto demos - See robot comment above. Good idea for much, much later.

• webstartable version produced and made web-accessible automatically after each successful build.

  Dev Note Webstartable - Agreed. Sounds like a good thing for Jeff and Nate.

• fluency (both editor and app runner) must run standalone outside eclipse.

  Dev Note App runner - Done. Editor runner - Easy. We will make this part of the transfer to SourceForge (will do an autobuild to a JAR that can be run)

• once we get around to making an installer (or, more likely, using a badly done but free installer ) perhaps decent file associations might be .flu and .fly file associations. double-clicking a .flu file fires up fluency-the-editor, double-clicking a .fly file fires up fluency-the-pure-runtime. authors would care about .flu's and users would only see .fly's.
  • Lots of installer choices (some free, some not)

    Dev Note Installer - We really want an installer and more connection between extensions and program but not until Beta.

• demos should be recorded periodically (maybe once every 2 weeks) using wink. we should never be far, one way or the other, from a working, demoable, webstartable fluency.

  Dev Note Regular demos - Jeff? Someone will do this.

testing

• we need to get to near 100% code coverage with tests. frontend testing in particular is a problem area and i'm not sure how to work it (as with profiling and installing, it's still a common problem in all ui development though so maybe better tools are out there now).

Warning read this first. i just checked around a little and GUI testing is still a nightmare. the only one i could find with an online demo was squish (which is commercial). watch the demo to get an idea of what they support and how lame it is (but better than nothing, which is what we have). this puff-piece suggests some of the main problems. this wiki page gives a list of available testing tools. most are commercial---and really expensive. test-drive is $8,000 a seat. of the open-source ones, i'm only familiar with abbot, as it's the only one that was around when i first went looking for GUI testing harnesses many moons ago. see abbot run — requires cvs checkout and command line startup

Dev Note 100% Coverage - This is part of the new standards that we are working with. 100% is unlikely in all cases but obviously the goal. GUI testing seems pointless but we would love to hear a good justification for how and why this should be done automatically.

refactoring

• we need a robot to stand-in for the user to thus make demos and tutorials for fluency easy to do. to do this, all ui actions, not just some, need to be made into commands. it might also make functional testing easier.

  Dev Note Robot - See all above comments about Robots. Easy but not yet.

• the backend/engine needs to be cleaned up so that fluency can function without having to restart it all the time. fluency should be made bombproof.

• there needs to be a complete code refactoring to cleanup the abundant style crime. no more use of ArrayList when you mean List, etc. no more C-based style crime like trinary-if.

  Dev Note Backend cleanup - Done.

• the busy-waits have to go.

  Dev Note Busy-waits - N/A

• backend/engine use of a mix of concurrent and non-concurrent collection classes needs to be normalized to concurrent ones only.

• the business of non-sychronized backend/engine calls needs to be resolved. how are they even possible? perhaps the facade is flaky?

  Dev Note Backend Concurrency - N/A

• backend/engine needs listeners a la the event-channel of years gone by so that fluency can be run in 'simulate-mode' (and not just 'build-mode' and 'run-mode' only).

  Dev Note Backend Listeners - N/A Editor Listeners - Done. Simulate Mode - Suggest a debug engine as a specific plugin. Easy to do by dropping in debugger widgets on all connections and outputing their throughput.

• widgetid needs to be fully encapsulated. no more messing around with being able to extract strings and longs and whatnot and then monkeying with them to make new ids. to support that the backend/engine needs to change to support groupid's (i.e. a group is a thing that needs an id, just like a widget does. pipes also might need ids.) all the iding stuff needs to be localized and encapsulated. plus it needs to work better with the persistence layer. maybe there should be two persistence layers — one for the backend/engine, one for the frontend/ui/editor/whatever, but both should use the same id system and it shouldn't be monkeyable with (i.e. should be fully encapsulated). ids are a means of communication between backend and frontend, but they're also used heavily by the persistence layer. they should probably be their own package (and should not be called 'widgetid' as that is too narrow a meaning of what ids are for.

  Dev Note WidgetID Encapsulate - Done.

• we need to get away from eclipse. fluency should run standalone. a jar would be fine for now but eventually we'll need an installer to make exes for the windows lusers of the world who don't know from jars. then we can do associations so that doubleclicking a .flu file fires up fluency. we also need to start making distinctions between the runtime needed to run a fluency app and the runtime being used to support the editor. the id issue above illustrates why those two things are different. the runtime being used to support an editor should know about group ids. a runtime being used solely as an app executor doesn't necessarily need that knowledge since the user (as opposed to the author) can't mess with, or change, or even notice, groups. similarly for the persistence layer. it's (currently) something that needs to work when the author is editing, not when the user is running. ditto for undo/redo. that's an author thing, not a user thing. all such parts need refactoring out into separate modules so that a successful build can automatically result in two kinds of fluency: pure runtime (for users) versus editor/builder runtime (for authors).

  Dev Note See notes regarding this above.

usability

• we need at least one layout manager (besides the null layout manager). nate's planning to do Spring.

  Dev Note Layout manager - Definitely. Second half of semester.

• we need layout helper code. for example, a backgrounded and fadeable grid for placement, or faint and transient lines on mouse widget-drag for layout alignment (as in Interface Builder), etc.

  Dev Note Layout helper code - Yes, part of editor preferences, etc.

• instead of scrollbars on the linkage pane we should implement drag/select autozoom. we have an infinite desktop (a project i made up for c212 back in the day). there's no shortage of space with infinite pan and zoom. instead of doing the obvious but braindamaged things we're used to from the layout world of fixed and small space and fixed resolution we can get much more creative and do much more intuitive things that should help make fluency a joy to use.

  Dev Note Linkage scrolling - N/A

• everything that's visual in any view needs to have properties. pipes in particular need properties. most properties should not be directly settable by the author via property pane (or otherwise).

  Dev Note Dynamic Properties - In the works, really hard. We'll get back to you on this.

• zoom out should work more smoothly in linkage. related to this: we need some kind of policy on when widgets should stay expanded: maybe if the author double-clicks a widget it stays expanded until he double-clicks it again, but if he single-clicks it to open it it only stays open until he next zooms out or something at which time it automatically closes. also: zooming in far enough could trigger opening. also also: click-drag to select should trigger zoom control if more widgets are being selected than can be shown at the current zoom level. in other words, we should make better use of piccolo's gift to us of programmable zoom control.

  Dev Note Zoom out - N/A

• harbors and docks need to pop-out on widget mouse-over rather than the author having to directly open each widget then directly open a particular harbour to get to a particular dock to then link a pipe to it.

  Dev Note Autopopups - This isn't as concrete/neat as it would seem. Should probably be an editor preference.

• widget linkage location needs to be set-droppable (no more (0,0) drivel), as widget layout location is. widget names need to be settable (and persistent) in linkage. pipe control points need to be persistent too.

  Dev Note Linkage loc - N/A

• in-docks and out-docks need better marking. perhaps solid arrow-heads would be better than the circles/half-circles. pipes would then not have arrow-heads themselves. they'd just be lines. selecting a particular arrowhead would link the pipe to the in- or out-dock, thus 'completing the arrow' and thus making clear to the author what's happening.

  Dev Note Dock markup - Yes. In the works.

• implement the 'comment-block-linked-to-pipe-subsets' idea. a well-made fluency app should be self-documented.

  Dev Note See other markup comments.

• ctl-z is a terrible choice for the undo keyboard shortcut because for all unix users in the world it means pause-and-background on the command line. the point here isn't ctl-z per se but keypress associations set in concrete, a topic i briefly commented on during term when the business of the hackage associated with the delete (and backspace) key in layout (for macs) came up. this business of tying up such decisions in at the code level is pretty lame, as is the idea of tying up screen default sizes instead of making them dependent on the author's actual screen size, or not using the os-portability features of java (like fileseparators). in java, such things are, and should be, configurable by the author. there should be defaults of course, but they should be overridable with at least a config file (or/and a setting mechanism for them on startup).

  Dev Note Keyboard shortcuts - Yes. Editor preferences. There can be platform dependent defaults. Will get to it later.

• when widget labels are changed they should change in real-time, directly on the widget itself in layout (i.e. not in its property sheet), and the widget should automatically expand or contract to accommodate its label as it's being changed.

  Dev Note Label accomodation - Done.

• there should be a 'button-bar' widget so that, for example, when the author needs to place two buttons for text-editor controls he could just choose a button-bar widget (rather than separate buttons), then click-drags and the area fills with buttons of some default size that fit into the area he drags. that should work both for click-expand and click-reduce of the drag area.

  Dev Note Widget management - In the works

• the icons need redoing to be more indicative of what the widgets are.

  Dev Note Icon refactor - Yes. Bottom of priority list.

• the rounding and floating point location error accumulations occurring when zooming in or out need to be fixed.

  Dev Note Rounding error - N/A

• some (most?) of the mode-control menu options probably should migrate into buttons on a toolbar. the toolbar should be made either collapsible a la firefox etc or it should be made detachable and moveable a la photoshop etc. the big thing is maximizing the screen real-estate devoted primarily to widget manipulation. don't let the controls crowd, clutter, or obscure the workspace.

  Dev Note Modecontrol Menu - Done.

• linkage between linkage and layout: right now there is very little, from the author's perspective. i'd like to be able to click on a widget or set of widgets in layout (where i know what they are and what they're supposed to do), then flip over to linkage and see just those widgets (or see just those widgets highlighted) so that i can work on them alone without the clutter of the other widgets. probably such selection should open the widgets for connection as well (i.e. with harbors exposed, so that as i mouse over a widget its docks pop in and out as i do). i saw matt doing just that in the demo, but he didn't have the aid of being able to select widgets in layout then having them highlight in linkage, so he had to do it partly by memory and partly by renaming widgets in layout so that he knew what they were when he got to linkage. (that renaming ability should stay, but the above visual trick should make it much less necessary).

  Dev Note Linkage/Layout coupling - One of the biggest problems. Working on it.

groups

• ui groups need solidification. selecting widgets to declare them a group is a separate thing from telling fluency what to do with that group. so far we have at least 4 potential actions:
  • make them appear/disappear as a group
  • save/restore them as a group
  • save/restore them as a group, but treat them as 'zoomed-out' by default
  • save/restore them as a separate widget, which can be drilled into again there will surely be more (for example: 'move them as a group' which is already implicit in the grouping mechanism.

    Dev Note UI Groups - Molecules?

• pipes should be groupable too. that would help support the comment-block idea.

  Dev Note Pipe groups - This is what paths are.

• holders should be able to hold other holders.

  Dev Note Holders - Molecules. And then containers.

• holders should be reopenable.

  Dev Note Holder reopening - Make sense for Molecules. For containers, not so much.

• (would be nice but probably not necessary for beta) holders shouldn't force the author into tree-hierarchies of holders.

  Dev Note Tree hierarchies - N/A

pipes

• i still like the name 'pipes' rather than 'ships' out in the frontend, if nowhere else. to the author a pipe is a real thing, just as real as a widget. a ship is a process more than anything else. a natural analogy for the linkage pane is plumbing, not shipping. of course that need have no relevance on the backend. the closest analogy to pipe in the nautical metaphor is 'shipping lane', which is much longer. 'pipe' is both short and clear.

  Dev Note Naming - They are called connections now because that's what they are. "Pipe" has too many other connotations associated with it.

• clicking on a pipe should select it, not add 3 control points. clicking again should add one control point at the clickpoint (and not two more on either side). what's happening now is that useless control points are proliferating since trying to move one brings two more. trying to move any of those brings two more. etc.

  Dev Note Click select - Agreed. Was working but got a bit muddled in a recent refactor. Will be done by beta.

• separating selecting a pipe from adding control points to it allows us to add other things you can do to pipes---like change their color or width (or add comments or tips) so that the author can markup the linkage view to make its functioning (or intended functioning) more visually clear and less burdensome on his memory (or the memory of the people he sends the app to).

  Dev Note Select vs Modify - Agreed. How to do this isnt as clear. Not a high priority.

panes

• the property pane needs to be better handled to minimize the screen space it gobbles. distinctions should be drawn between layout properties and linkage properties. the 'groups' piece (pane?) of linkage ditto.

• some of the properties presently listed in the properties pane should just go away. location in x-y coordinates, for example. rarer but useful ones that can't easily be controlled directly with the mouse, or with keyboard shortcuts, like background and foreground color, can stay for now. i personally would like to see those go to popup controls near the widget being worked on, but that's just me. rick didn't seem to mind the property sheet eating so much space to so little purpose. not so far, anyway.

  Dev Note Property Pane - N/A

• the 'groups bar' (or pane or whatever it is) in linkage should be made separate and collapsible.

  Dev Note Groups Bar - N/A

a unified linkage pane?

with piccolo, even if the author is building a multi-pane app (say, with tabbing or some other control mechanism to control movement between them) ALL PANES CAN BE IN ONE LINKAGE PANE. say there are 3 (note that each one can be a different 'size' since 'size' is proportional to how many widgets need to be accommodated in any particular 'linkage view' that associated with some particular layout pane):

overall linkage view:
------------------------------------------------------------------------
|                                                                      |
|        view1____  view1____  view3_____________________________      |
|        |       |  |       |  |                                |      |
|        |       |  |       |  |                                |      |
|        |       |  |       |  |                                |      |
|        |       |  |       |  |                                |      |
|        |_______|  |_______|  |________________________________|      |
|                                                                      |
------------------------------------------------------------------------

the above corresponds to a single linkage view that's composed of three linkage views, each of which represents the linkage view of one of three layout views (i.e. in the traditional definition, the app this represents has 3 separate panes of layout).

why this works: we have piccolo! piccolo can zoom in and out. there's no reason for 3 separate linkage panes and all the headaches that's going to cause the author in connecting them up and keeping stuff straight. further, when the author wants to work on some particular view within the overall view he can navigate around to it---but that's lame because we have zoom! he can simply zoom out' then select a particular view to work on next. when he does, it autozooms back in to the overall view!

one lameness about this is: what if the author needs to see parts of two separate views at once (to connect the widgets in them)? well, we don't have to make the author only select views from the 3 above natural subdivisions. we can give the author 'drag-zoom' by letting him do a rubberband rectangle and everything in the rectangular area he selects becomes the current view. clicking to zoom out again will return the author to the above overall view (perhaps with the last area worked on included in a rubberband rectangle so that he keeps context of where he was last). we might even keep several such 'zoom areas' around and outline each box in a different grade colour to indicate time, starting with, say, red for most recent all the way to blue for least recent, but that's a detail for later discussion.

Dev Note This will be one of the first plugins we make. Not only for the sake of testing the plugins but also to demo the idea of plugins and add this functionality. Will not have all the desired features but should be easy to expand later.

adding layout to one piccolo pane as well??

we could have only one pane if we put everything in piccolo, including layout.

it might look something like this:

 ------------------------------------------------------------------------
 |                                                                      |
 |        Aview1___  Aview1___  Aview3___                               |
 |        |       |  |       |  |       |                               |
 |        |       |  |       |  |       |                               |
 |        |       |  |       |  |       |                               |
 |        |       |  |       |  |       |                               |
 |        |_______|  |_______|  |_______|                               |
 |                                                                      |
 |                                                                      |
 |        Bview1___  Bview1___  Bview3____________________________      |
 |        |       |  |       |  |                                |      |
 |        |       |  |       |  |                                |      |
 |        |       |  |       |  |                                |      |
 |        |       |  |       |  |                                |      |
 |        |_______|  |_______|  |________________________________|      |
 |                                                                      |
 ------------------------------------------------------------------------

where 'Aview' = 'layout view' and 'Bview' = 'linkage view' (perhaps with suitable modifications for having more than one layout view fitting into only one linkage view (as in my posting below).

here there's only one pane, not two (or more), and everything fits into piccolo (of course this would mean going back to the hacky snapshot-only layout view scheme with separate live mode that we had in past terms, so that dynamically changing images of layouts can be fit into piccolo). plus the author could see more of what matters all at once (of course, the more he zooms out, the less detail he can see).

is this a feasable idea? (either for implementation — for example, does piccolo support dynamic image replacement? or for usability — for example, would rick go for this idea or is it totally unusable for authors?) if rick thinks it's worth pursuing the idea of putting everything in one pane and not having the author have to deal with switching back and forth between layout and linkage and so on we could look into what it might take to implement fluency's editor ui this way.

here are two relevant post on the piccolo mailing list: pswing and more pswing.

bottom line: it's not an unthinkable idea to embed swing components in piccolo (as opposed to embedding piccolo components in swing, which we do already and is supported by piccolo), but it likely won't be easy. there may also seem to be performance problems to worry about since to make it work, text appearing in swing controls (example: labels, or text in a text control, like an editor) must be re-rendered to allow zooming and that can sometimes produce jibberish.

fortunately, we don't have to worry about this idea unless rick goes hog wild on it when he hears about it. even then, we should be cautious and go for it one step at a time. first, we'll keep with what we know and have already (just piccolo in swing, not swing in piccolo) until we have all the bugs there ironed out. then, and only then, should we consider venturing into such new territory. likely that won't be necessary for a beta anyway. other people can worry about it, if and when.