
	------------------------------------------------
	Proposal for project management frameworkd (PMF)
	------------------------------------------------
	
Version: 0.1
Updated: 2000/01/11
Authors: Aleksandras Gluchovas
 E-mail: <alex@soften.ktu.lt>
    URL: http://www.soften.ktu.lt/~alex/


Some backgournd info:
=====================

This proposal attempts to describe a framework
to be used in project-based applications. The framework
is independent of any concrete application (eg. wxStudio), 
it only provides general interfaces with default impls.,
which could be customized/overridden in concrete 
apps. Therefor i think of it as a library which later 
could become a useful contrib. to wxWindows.

As a coauthor of wxStudio's initial demo, i share
a great deal of fault that the design of it's
project-management is wrong in many ways:

* it allows nesting of projects within each other,,
  though it looks like feature, but usually is a nonsense
  
* It has a concept of workplace, but wxStudio's workplace
  was meant to hold only *one* project. 
  
* That single so-called "root-project" implied one-to-one 
  correspondence with workplace.  This was causing confusion whether 
  the "workplace" was necessary at all. The project instead had 
  subprojects and so on.. Such hierarchy can be useful sometimes 
  (e.g. recursive makefiles..), but adds hedge burden and unreasonable 
  complexity to the app (i've felt it badly while writing project-browser 
  and other plugins)
  
The new proposal suggests to have a workplace, which acts as 
a not-hierarchical container to manage multiple projects. 
A single project can be shared/referenced from multiple workplaces.
In this model workplace, as it's definition implies, stores a 
state of work on several of included project, whereas a project 
stores only project-related non-visual information -- this 
separation is hard to deduce having the previous model.

Besides that, the proposal contains enough detail on how documents,
their views, panes (or toolbars) and menus are interrelated and 
managed within multi-project workplace. Since it is aimed to
be general, it does not include interfaces for dynamic plugins,
because such features do not directly relate to project-management,
but they can be added in the customized/overridden classes which
extend the framework for a concrete app.


Content 
=======

1. Workplace and projects 
2. Projects and storage-files
3. Documents and views
4. Panes and documents
5. Document states

1. Workplace and projects 
=========================

Workplace is a configuration entity, which acts as a
container for projects. It also stores positioning and 
current-state information of the views and panes associated 
with projects contained in a workplace.

Application may contain zero or one opened workplace.

There should always be one and only one active 
project in a workplace. The absence of active project
implies that the workplace is empty, ie. contains no
projects.

Projects cannot be activated outside the containing workplace.
The same project may be referred/contained in different workplaces.
A workplace and a project store their data into separate
files.

When workplace is being closed, it asks all active/modified 
documents and projects to save their state or cancel modifications 
made after loading/creation.


2. Projects and storage-files
=============================

Files cannot be inserted into a project, if their MIME-type
is not recognized, or a document class associated with the 
MIME-type is not present.

When a file is removed from the project, all associated
documents, views and panes are automatically removed.

If the user attempts to open a file which describes a project,
not a workplace, then a default ("untitled") workplace is
automatically created containing that single project.

There should be location object associated with each file in a project. 
It stores a hybrid description, which can contain either an URL 
of the file, or absolute/relative file-name referring to local 
file-system (e.g. this would permit to have application which allows
opening/storing/editing HTML documents located on remote machine 
of hosting-service). Corresponding resource-loader objects should 
be present to allow including files of different locaiton-types.
This object provides functions for storing and retrieving of file's
content in a binary form (e.g. their impl. can be based on VFS).

3. Documents and views
======================

Many views may share one document. Only one view
can be active at a time. Views a displayed in
MDI-child windows.

Instance of document may or may not have it's associated file. 
If it doesn't, then it should have a reference to it's 
"super-document" which in terms should have an associated file. 
Those which have, should not be contained in another "super-document"
(e.g. single Dialog-resource document does not have it's file, but
it's super-document: "project's resources" stores all it's
sub-documents (dialgs/panels) into one .wrx file). Document should 
provide it's MIME-type as a text-literal.

There can be only one document-class matching particular MIME-type.

There can be many views associated with particular documenet-type (MIME).

Document's view may have it's associated menus,
which are described in mergable-menu-format. Menus
are removed when corresponding view is deactivated, and merged
back when it is activated. During activation/deactivation,
all panes which are associated with the same type
of documents are scanned for controls having IDs corresponding
to those in view's menu items. These controls are automatically
enabled/disabled by querying menu-commands with UPDATE_UI message.

Mergable-menu-format describes hierarchical chains of items/subitems
which particular view adds to the menubar. Each chain begins with a
the text-literal referring a to possible precessor of the
chain's root with respect to the surrounding sibling-items.
If matching predcessor was not found, the chain's root is placed
at the end of sibling-list. The list of siblings here implies
either top-levels items of the menu-bar or sub-menus-items in
a particular top-level-menu.

An active view may independently request updating
of associated UI elements, eg. when "undo" command becomes
enabled and "redo" disabled in the course of interactive editing.

If particular document-type has more then one view associated
with it, the request for activating such document should include 
the exact type of view in which this document will be presented.


4. Panes and documents
======================

Panes are similar to views, except that their windows
cannot be embedded into MDI child-frames of
document views, instead they are placed as direct 
children of application's main window, surrounding the
MID-parent window inside the main window. Toolbars are
regraded as regular panes, and receive no special treatment.

A pane may or may not be associated with a document
type. If it is associated, it will be automatically activated 
and attached to the document whenever the view of the matching
document-type is activated.

Pane can be attached to a document at run-time. The
same way it may lose such attachment (eg. when document
was closed, but refered pane was kept visible). There can 
be panes which are never associated with any document
(eg. project-browser panes and it's sub-panes).

Pane may have subpanes. There can be only one subpane
active (or visible) at a time within it's parent pane

There should be an algorithm object, which manages 
layouting of top-level panes within the main window. 
The same algorithm also reacts to the activation
of different documents, and performs appropriate
relayouting/activation of associated panes.
Algorithm should comply to general interface,
so that it's implementations could vary.

NOTE: the mentioned "algorithm" first could be
      implemented using Sashes or simply BoxSizing
      all visible panels proportionally within main 
      window -- this would be one possible "proof-of-concept" 
      implementation. When that succeeded, alternative 
      implementation could be written with assistance of 
      nice-but-buggy wxFrameLayout contib. for implementing 
      generic interfaces of "the algorithm" (that would 
      show the actual power of ideas behind this PMF...)

Each pane has a position-object containing info about
it's relative-position in the layout. The concrete
class of the position-object depends on the
concrete pane layouting algorithm. These objects
are made persistent into associated workplace's 
storage file (see "workplace" desc.)

Each pane should have it's object of layout-preferences, 
which describe where this particular pane should be shown
initially. The type of such object is again dependent
on the concrete layouting algorithm, but it's general
interface is fixed.

The layouting algorithm may optionally provide a feature, 
which allows creating and switching between different 
positioning of panes and views. This information also includes 
currently active project, and active document within that 
project (e.g. user could create custom "Design","Editing",etc 
appearances of main window, and switch between them via menus or
toolbars).

5. Document states
==================

Document is said to be in one of it's possible states.
States be can changed interactively by user (eg. starts debugging) 
or by application (e.g. debugged process terminated). Document
should provide a list of it's possible states as a list of
string literals.

Association between document and view is made by
matching their MIME-types. Besides the MIME-type a view can
provide a list of string literals which correspond to 
the set of states in which the document could be in order
to be represented by this view. By default the provided list 
is empty, meaning that the view is associated with all 
possible states of particular document.

Whenever state of a document changes, environment 
will remove all it's views which do not match the new state,
and will try to replace them (within the same MDI-Child frame)
with those which do match the new state. If such were
not found for some view, that view and it's corresponding 
MID-child is closed.

As with views, the same scenario is followed for panes
(e.g. stackframes-pane shows up when document's state changes
form "edited" to "debugged", this also makes possible to 
have different source-text-views for debugging and editing)

The layouting object should react to document state-changes,
and perform appropriate activation/repositioning of related 
panes and views.

---- end ----


Aleksandras (alex@soften.ktu.lt)