----------------- The first section is obsolete -----------------

[ Search for '----' for the live stuff at the bottom ]


Some thoughts on coding up layout.

* Resource compiler (rsc/source/*)
	+ rscdep - dependencies ?
	+ rscpp - pre-processor ?
	+ rsc2 - real compile

* Resource reader (tools/source/rc/resmgr)

* Current design:

	+ Hierarchical information
		+ None in the resource file
		+ None in the code

	+ Window construction
		+ can pass ResId for toplevel win, but
		  doesn't have to [ only bother fixing up
		  people using ResIds ].
		+ children instantiated, associated with
		  Window parent (and a ResId).

	+ Resource load (Window -> is a Resource) [ tools/inc/rc.h ]
		+ Window::ImplInitRes( rResId )
			+ GetRes( rResId )
		+ Whole resource load process done via cursor
		  state on GetResManager(); 
		+ ResManager has an Init/PopContext stack
		  
		

* Hacking

	+ Hierarchical information
		+ Add it to the resource format - tied to
		  Window - do we currently have a list of
		  children even ? [ or is it totally abstract e

	+ Window creation
		+ walk hierarchical information
		+ build a set of layout / peers
		+ associate these at Window::ImplLoadRes time
		+ post-association / on Window show => doLayout first.

* Demo

	+ svtools/workben (svdem): hack here ... ?

* Suggested Format:

#define DLG_TEST   1001
#define BTN_OK     1002
#define BTN_CANCEL 1003
#define DLG_TEST_LAYOUT   1100

ModalDialog DLG_TEST
{
        OutputSize = TRUE ;
        Moveable = TRUE ;
        Closeable = TRUE ;
        Sizeable = TRUE;
        LayoutId = DLG_TEST_LAYOUT;

        PushButton BTN_OK
        {
                Text = "OK";
        };
        PushButton BTN_CANCEL

        {
                Text = "Cancel";
        };

        Layout DLG_TEST_LAYOUT {
                Homogeneous = False;
                Layout {
                        PeerId = BTN_OK;
                        Expand = True;
                        Fill = True;
                };
                Layout {
                        PeerId = BTN_CANCEL;
                        Expand = False;
                        Fill = False;
                };
        };
};


* Glade2 XML format:

	  <child>
	    <widget class="GtkHBox" id="hbox4">
	      <property name="visible">True</property>
	      <property name="homogeneous">False</property>
	      <property name="spacing">0</property>

	      <child>
		<widget class="GtkVBox" id="vbox1">
		  <property name="visible">True</property>
		  <property name="homogeneous">False</property>
		  <property name="spacing">6</property>

		  <child>
		    <widget class="GtkCheckButton" id="enable_toggle">
		      <property name="visible">True</property>
		      <property name="can_focus">True</property>
		      <property name="label" translatable="yes">E_nable sound server startup</property>
		      <property name="use_underline">True</property>
		      <property name="relief">GTK_RELIEF_NORMAL</property>
		      <property name="active">False</property>
		      <property name="inconsistent">False</property>
		      <property name="draw_indicator">True</property>
		      <signal name="toggled" handler="enable_toggled_cb"/>
		    </widget>
		    <packing>
		      <property name="padding">0</property>
		      <property name="expand">False</property>
		      <property name="fill">False</property>
		    </packing>
		  </child>
		  ...
		</widget>
	      </child>
	    </widget>
	  </child>
	  etc.

		
* Resource compiler class hierarachy:

# BiNode
    * NameNode
          o IdNode
                + RefNode
                      # RscTop
                            * RscArray
                                  o RscClassArray
                                  o RscLangArray
                            * RscBaseCont
                                  o RscContWriteSrc
                                        + RscCont
                                        + RscContExtraData
                            * RscClass
                                  o RscMgr
                                  o RscSysDepend
                                        + RscFirstSysDepend
                                  o RscTupel
                            * RscClient
                            * RscConst
                                  o RscEnum
                                  o RscFlag
                            * RscIdRange
                            * RscLongRange
                                  o RscLongEnumRange
                            * RscRange
                                  o RscBool
                                  o RscBreakRange
                            * RscString
                + RscInstNode
          o StringNode
                + RscDefine


	+ despite all the .cxx, .hxx etc. stuff it seems to
	  compile direct .src -> .rc with no intermediates.
	+ Post parsing we call WriteRc on the nodes,
	+ We can also call WriteSrc - presumably a legacy
	  from the src -> representation / fiddle / -> src 
	  round-trip process.
	+ RscCont is a generic container class.
	+ code hidden in rsc/source/prj/gui.cxx flow:
		rscyacc.y:
			+ everything built into a RscTypeCont *pTC.
			+ all strings munged into HashString: pHS
			+ pHS->Get( HASHID ) returns it to a string.
		RscTypeCont -> RscTypCont::Init - sets up parser.
		RscCompiler (pTypeCont)->Start.
			+ CheckSyntax -> ParseOneFile -> parser -> yyparse
			  -> DoClassHeader (rscyacc.cxx) -> GetElement (rsctop.cxx)

	+ Problems
		+ each RscClass has to define it's child
		    properties => we have to define all possible
		    child properties in advance for 'Widget')

* VCL Issues

	+ Flow:
		+ Res -> Window -> [ constr. Layout tree ]
	+ We need to associate instances of widgets later;
		+ They do ImplInitRes - and we need to connect them
		  and queue re-draws on the parent etc.
		+ Have a hash of Layout <-> ResId mappings on Window ...
		+ re-flow on re-size etc. 'queue_redraw' ?

	+ Layout -> Widget [ via. Layout tree & peers, toplevel is always a peer ]

	+ Window <-> Layout in all cases ? [ show / hide ? ]
	  cache 'visible' state ? etc. have a Layout ptr. on each
	  Window ...
	+ Need a factory for Layouts ...
	+ We only need to virtualize sizeAllocate on the Layouts,
	  not the widgets - thank goodness.

** Decisions
	+ Totally static layout manipulation
		- ie. no self-building - too complex anyway.

----------------- Above here is obsolete -----------------

[ This is the current notes: ]

** Form XML format:

    + from the basic editor:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dlg:window PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "dialog.dtd">
<dlg:window xmlns:dlg="http://openoffice.org/2000/dialog" xmlns:script="http://openoffice.org/2000/script" dlg:id="Dialog1" dlg:left="204" dlg:top="148" dlg:width="136" dlg:height="115" dlg:closeable="true" dlg:moveable="true">
  <dlg:bulletinboard>
    <dlg:button dlg:id="OkButtonName" dlg:tab-index="0" dlg:left="86" dlg:top="92" dlg:width="44" dlg:height="19" dlg:value="OkButtonLabel"/>
    <dlg:titledbox dlg:id="FrameControl1" dlg:tab-index="1" dlg:left="4" dlg:top="7" dlg:width="68" dlg:height="41">
      <dlg:title dlg:value="FrameControl1"/>
    </dlg:titledbox>
    <dlg:scrollbar dlg:id="ScrollBar1" dlg:tab-index="2" dlg:left="82" dlg:top="10" dlg:width="45" dlg:height="24"/>
    <dlg:scrollbar dlg:id="ScrollBar2" dlg:tab-index="3" dlg:left="107" dlg:top="43" dlg:width="21" dlg:height="37" dlg:align="vertical"/>
    <dlg:timefield dlg:id="TimeField1" dlg:tab-index="4" dlg:left="4" dlg:top="92" dlg:width="28" dlg:height="19"/>
    <dlg:text dlg:id="Label1" dlg:tab-index="5" dlg:left="22" dlg:top="61" dlg:width="44" dlg:height="15" dlg:value="Label1"/>
  </dlg:bulletinboard>
</dlg:window>

    + code to read this & generate UIs is in:
	+ DTD: xmlscript/dtd/dialog.dtd
	+ xmlscript/source/xmldlg_imexp/imp_share.hxx, line 674
	+ xmlscript/source/misc/unoservices.cxx
		xmlscript/source/xmlflat_imexp/xmlbas_import.cxx (?)
		"com.sun.star.comp.xmlscript.XMLBasicImporter"
	+ the dialog piece seems separate ?
		"importDialogModel" ...
	+ cf. the interesting test code ...
	+ cd xmlscript/test
	  dmake
	  ../unxlngi6.pro/bin/imexp /opt/OOInstall ./test.xml
	    + generates & renders a dialog ...

	+ This code has ~all we need to get a simple impl.
	    + compatibility wrappers [!]

    // first create model:
    Reference< container::XNameContainer > xModel( xContext->getServiceManager()->createInstanceWithContext(
	OUString( RTL_CONSTASCII_USTRINGPARAM( "com.sun.star.awt.UnoControlDialogModel" ) ), xContext ), UNO_QUERY );
    // NB. xmldlg_addfunc.cxx not xmldlg_import.cxx [!?] ;-)
    ::xmlscript::importDialogModel( ::xmlscript::createInputStream( bytes ),
				    xModel, xContext );

    // second create view of model:
    Reference< awt::XControl > xDlg( xMSF->createInstance(
	OUString(RTL_CONSTASCII_USTRINGPARAM( "com.sun.star.awt.UnoControlDialog" ) ) ), UNO_QUERY );
    xDlg->setModel( Reference< awt::XControlModel >::query( xModel ) );

    // third - associate toolkit / peer ...
    Reference< awt::XToolkit> xToolkit( xMSF->createInstance(
	OUString( RTL_CONSTASCII_USTRINGPARAM( "com.sun.star.awt.ExtToolkit" ) ) ), UNO_QUERY );
    xDlg->createPeer( xToolkit, 0 );

    // fourth - execute [ nasty ... ]
    Reference< awt::XDialog > xD( xDlg, UNO_QUERY );
    xD->execute();


** Basic dialog editor:

    + basctl/source/dlged/dlged.cxx
	+ dialog editor (?)
    + basctl/source/basicide/basobj3.cxx
    + basctl/source/basicide/basides3.cxx
	+ BasicIDEShell:CreateDlgWin ...

** AWT interfaces:
    + offapi/com/sun/star/awt/* - eg. XButton.idl
	+ 'XLayoutConstrains.idl' [ published & mis-named ! ]

    + We can build 'Layout' into the AWT at the toolkit level
	+ this should be fairly easy, and wouldn't touch VCL much.

** Toolkit (awt) implementation:
    + toolkit/source/awt/vclxwindows.cxx:
	+ much of the implementation lurks in here ...
    + The size information is in 'vclxwindows.cxx' ...

    + toolkit/source/helper/unowrapper.cxx
	+ factories / code to associate UNO peers with VCL windows
	+ pWindow->


** TODO:
    + the dialog editor needs containers
	+ we need a hierarchy / tree view there ...
	+ 

    + The sizing logic is in 
	+ toolkit/source/awt/vclxtoolkit.cxx (ImplCreateWindow)
	    + the sizing is done on creation [ hmm ... ]

    + 1st Axiom:
	+ all layout is containment based: with
	  special back-compat 'Fixed' case
	    + perhaps this is: <dlg:bulletinboard>

** How my layout patch worked:
    + introduce a parallel 'Layout' hierarchy
	+ ie. all windows continue to have flat children
	+ we do the layout in parallel to that, by absolute
	  positioning.

    + ie. store the UNO peers in a tree;
	+ and simply ensure that the layout entries don't
	  yield widgets.


** A plan:
    + a) add a few layout XML elements / attributes to a
         sample XML file.
    + b) port layout-vcl-layout.diff to use UNO controls
    + c) populate layout data from XML
    + d) render dialog.

    + e) add UI designer work ...

---

    + f) wrapper API to allow old code to work with new dialogs.
    + g) porting of lots of dialogs.


** xmlscript/ElementDescriptor - can cope to these.
   + xml_helper/xml_impctx.cxx - builds lists of m_elements etc.


--- How hierarchies should work IMHO ---

On-screen:

+-------------------+
| Label:   [Entry]  |
| - - - - - - - - - |                  |
|             [ Ok ]|
+-------------------+

VCL Window hierarcy:
	Window
		+ Label
		+ Entry
		+ Ok

	ie. unchanged, and backwards compatible - a flat
representation.

Toolkit Hierachy

	WindowContainer [Bin?]
		+ Vbox
			+ HBox
				+ Label
				+ Entry
		+ Alignment
			+ Ok

	the layout process would happen inside the toolkit code
(perhaps eventually genericisd itself), and the result from the
(re-)layout process would be a set of SetPosition/SetSize calls made
to VCL.

* xmlscript
	+ xmldlg_import.cxx - 
	+ xml_helper/xml_impctx.cxx - foo ...


* plan:
	+ hard-code container hooks into the xmlscript/ parser ...
	+ create a layout object in toolkit/
		+ populate it with good things ...

	+ coupling to toolkit - widget instantiation: how ...
		+ ComponentInfos
			+ vclxtoolkit.cxx:
		+ has a 'hook function' for 'fnSvtCreateWindow'
		  for SVT widgets :-) [ grotesque ;-]
			+ [ wow - fetched by dlopen! ;-]

	+ A little app - a-la solver: using awt (?)
		+ XMessageBoxFactory ...
		+ XToolkit:
			+ CreateWindow ...
		+ ** how does the xml code generate these guys ? **

	+ what APIs does the xmlimporter use ? not 'createWindow' seemingly.

+ existing xml import uses: property bag a -lot-:
	Reference< beans::XPropertySet > xProps(
	        _pImport->_xDialogModel, UNO_QUERY_THROW );
	* we do _xDialogModel->insertByName (new any<XControlModel>())
		+ to build hierarchy ( cf. ~ControlImportContext )

	DialogImport:
		css::uno::Reference< css::container::XNameContainer > _xDialogModel;

	Reference< container::XNameContainer > xModel( xContext->getServiceManager()->createInstanceWithContext(
			OUString( RTL_CONSTASCII_USTRINGPARAM( "com.sun.star.awt.UnoControlDialogModel" ) ), xContext ), UNO_QUERY );

	toolkit/source/controls/dialogcontrol.cxx
		+ UnoControlButtonModel (eg.)
		+ service 'UnoControlModel' ...

	+ poke at 'titledbox' or 'radiogroup' to see how containment works there ...
		+ how will child widget properties work ?
		+ bug with a 'vbox' inside a 'titledbox' ...
	+ titledbox - acts as a container (interesting)
		- offsetting child positions
	+ how will pseudo-containers eg. "radiogroup" cope ?

	+ propose new syntax: [ with child properties a-la glade ]:

	<hbox id="baa" flange="true">
		<child padding="0" expand="false" fill="false">
			<radio id="foo" value="..."/>
		</child>
		<radio id="foo" value="..."/>
	</hbox>
	
	+ if 'child' element omitted - default properties used ...
	+ if multiple elements in same 'child' set: all have the same props.

	+ LayoutContainerElement:
		+ should maintain a stack of elements on the context ...
		+ in ~LayoutContainerElement - remove them etc.

		OUString( RTL_CONSTASCII_USTRINGPARAM("com.sun.star.awt.UnoControlButtonModel") ) );
		OUString( RTL_CONSTASCII_USTRINGPARAM("com.sun.star.awt.UnoControlVBoxModel") ) );

	+ toolkit:
		+ how do we go from an 'UnoControlXYZModel' to an 'UnoControlXYZ' ?