Re: Sizing...

[Federico Mena Quintero <federico helixcode com>]

Michael Meeks <michael@helixcode.com> writes:

> 	Since Maciej and I had a flamewar about this recently, and
> now we are friends again I thought we should extend the battle
> ground to the great unwashed:

Scrolling is not the only consideration.  You need to handle two
cases; for the sake of this discussion let's call them case Batman and
case Robin.

Case Batman is as follows:

	- "I want an image viewer in my application".  This is what
          e.g. Nautilus needs from EOG.  In Bonobo-speak, these are
          controls.

	- A control has to handle its whole user interface.  Let's
          consider several examples:

		1. An EOG control needs to handle its own scrolling
                   and zooming.  If you look inside EOG's sources, the
                   control would basically be the UIImage widget
                   (eog/src/ui-image.c) plus its BonoboUIHandler.  It
                   has specific niceties such as doing "hand"
                   scrolling, i.e. you can scroll the image by just
                   dragging it with the mouse; it also lets you use
                   the mouse wheel to change the zoom factor.

		2. A directory tree control for browsing your
                   filesystem tree (say, something Nautilus needs to
                   export for other programs that may want to use
                   it).  Scrolling is done in a trivial way by the
                   control itself.  It does not support a zoom
                   feature, since it makes no sense.

		3. The calendar views could be exported as controls by
                   Evolution.  Let's say you want to put a work-week
                   view in your application, i.e. the 5 adjacent days
                   that you can see in Evolution's calendar.  This has
                   a very specialized user interface and it needs to
                   be handled wholly by the control.

		4. Panel applets should be controls in the perfect
                   world.  They have very particular user interfaces
                   and need to be handled by the control itself.

	- Think of Batman as "I want to stick another program's UI in
          a pane in my application".

Case Robin is as follows:

	- "I want to put part of a spreadsheet in my word processor's
          document".  Or, "I want to put an image in my spreadsheet".
          Or, "I want a Guppi chart in my presentation".  In
          Bonobo-speak, these are embeddables.

	- An embeddable is basically part of a document.  It is *the*
          actual, often WYSIWYG view of a data object.  Note the
          "view" part:  several applications may have embeddables that
          provide views onto the same data; if the user changes the
          data in any one of them, all of them should reflect the
          changes immediately.

	- Since an embeddable goes into a document, there needs to be
          some communication from the parent document to the
          embeddable, such as

		1. The parent document has to tell the embeddable its
                   position and size on the final page, i.e.

			Your top-left corner is (5.5 cm, 7.6 cm) on
			the page.

			Your rectangular size is (10 cm, 8 cm).

		   This lets the embeddable know its final size for
		   when it is printed.

		2. The application which presents the parent document
                   has to tell the embeddable about how it should be
                   shown in the screen:

			Your parent X window is <blah>.

			By the way, due to the current scrolling
			position of the document's view, will you
			please paint yourself at (220, 304) pixels
			down the window.

			Also please use a size of (400, 320) pixels.

		   If you relate this to (1), you will see that the
		   document is being rendered to the screen at 40
		   pixels per centimeter.  This thing applies to the
		   *whole document*, since it is the main WYSIWYG
		   view.

		3. Taking the previous paragraph into account, you
                   will see that if the user scrolls the document down
                   by 10 pixels, then the embeddable will need to
                   paint itself at (220, 294) pixels instead of the
                   old position.  Since the user did not change the
                   zoom factor, it stays with the same size of (400,
                   320) pixels.

	- Note that the document view's zoom factor has NOTHING to do
          with the physical dimensions of the printed document.  This
          is why having Bonobo::View::set_zoom_factor() is *WRONG*.
          What you really want is

		Bonobo::View::set_document_position (double x_points,
						     double y_points,
						     double width_points,
						     double height_points);

		Bonobo::View::set_screen_position (XWindow parent,
						   int x_pixels,
						   int y_pixels,
						   int width_pixels,
						   int height_pixels);

	  That is, you need to inform the view about the size/position
	  it will have on the printed page and the size/position it
	  will have on the screen.

	- Note that an embeddable does not zoom or scroll.  It does
          not make sense.  The whole document's view may zoom or
          scroll, but not any one single embeddable.

	- However, to display the range of a subdocument that a view
          will display, such as

		* the range of the spreadsheet that I want to embed in
                  my word processing document, or

		* the rectangular region of the image (i.e. a cropped
                  region) that I want to put in my spreadsheet, or

		* a whole Guppi chart for my presentation,

	  that is the embeddable's problem; each one needs its own
	  internal user interface for that.

	- You may want to have some negotiation for when the user
          resizes a view.  An image embeddable may want to constrain
          the sizing to be proportional to the original image, or a
          spreadsheet range embeddable may want to constrain the size
          to whole cell dimensions; a music score embeddable may want
          to constrain the size to whole bars and staves, or even
          whole systems of staves for multi-instrument compositions.

	  This may need something like

		Bonobo::View::gimme_closest_size_at_which_you_are_happy (
			in double width_points,
			in double height_points,
			out double with_I_want_points,
			out double height_I_want_points);

	  Of course this is just off the top of my head and may need
	  further investigation.

	  In any case, when the user uses the mouse to resize a
	  subview embedded in a document, the rubberband rectangle
	  needs to be constrained to whatever sizes the view is happy
	  to resize to.

So yes, we may need two factories for components that want to export
both controls and embeddable views.

Batman is for integrating user interfaces of different programs in
different "panes".

Robin is for documents and subdocuments.

Some things may not want to export embeddables; for instance, Nautilus
may only want to export a Batman control for its directory tree
browser (you don't put directory trees in your documents, after all,
and you most certainly do not print them).

The GIMP may want to export both a Batman control (edit your images
inside Nautilus), and a Robin embeddable (stick an image in your
StarWriter document).

That's all I can think of for now.  I hope this makes things clearer.

  Federico