

               -------------------------------
               What to try in wxWorkshop 0.3 ?
               -------------------------------

Version: 0.1
Updated: 2000/07/27
Authors: Aleksandras Gluchovas
 E-mail: <alex@soften.ktu.lt>
    URL: http://www.soften.ktu.lt/~alex/


Content
=======

1. Steps
2. Bugs, kludges and tips
3. About widget (dialog/panel/etc) editor
4. Other nifty features, you would not care about yet
5. Newer notes

There is a sample workplace and project included
with executable. To try it you'd have to extract
archive into to c:\demo\ (because contained .wsw and .wsp 
files currently can store only absolute paths)

However, i would recommend to start over with the
following scenario:

First, you would create workplace and project,
then couple of .xml resources for it, one describing
a dialog, another a menubar. Then, using "Source Wizard"
you will generated .h and .cpp files and bind them
to those two resources. Then you would try editing
with resource and source-code documents simultaneously,
to test the RAD-ish development, where you can add
things visually to a GUI resources and bind them
to member variables and event-handling functions
of your source-code documents by "point-and-clicking"
in wizard-dialogs, or manually editing the source code.

Steps
=====

* extract .zip anywhere

* launch demo3.exe. If it's missing .dlls, download them
from "msvcrtd_dlls.zip" from the same site

* "File | New" select "Project...", then select any of the
template from "wxWindows C++ Applications" folder,
enter project name. The project and surrounding workplace
will be created under the name you've given (saved
to <name>.wsp and <name>.wsw). NOTE: see "kludges"
section for important notes related to project-creation.

* "File|New", select "wxWin-Resource document".
A "Select Resource" dialog will appear, where
you select "New" and "dialog". After entering
it's name the document window will be created
showing an empty dialog frame in it. Also, an
item with the given name will appear in the
workplace-view with .xml extension.

* add couple buttons and text-controls to
it (see "Layout", "Canvas" and "Edit" menus
for operations available in GUI-resource document)

* double-click the .xml item in the workplace-view,
in the resource-dialog create "MenuBar" resource. Add 
couple of items to it (see "Edit" and "Item" menus for
available operations and short-cut keys)

* "Events | New source...", from the list select 
"Dialog for C++", enter name of the class for the
dialog, file name (without extension) that will be
used for generating .cpp and .h. Then sequentially:
select Resource (.xml), then window and menu items
form this resource file to be bound to the source
code. The wizard will generate and open .cpp and 
.h files.

* Being in in either .h or .cpp document, see 
items which became enabled in the "Events" menu.
"Edit events" and "Edit members" dialogs
need no further comments.. You may also edit
bodies of generated methods and see how your
manual changes "persist" while the code around 
them is regenerated over again. Do not change
code-fragments maintained by wizzerd enclosed
within // %%-...{ and // %%-...} fragments.

* Try adding new items to the menu and dialog
resources and see how they become available (by "name')
for binding in the member and event-editing dialogs,
while you switch back to the source code documents.


Bugs, kludges and tips
======================

* take a look at "Tips" menu

* if you create a new project, while
typing name of the project, "Directory" field
will be filling itself automagically, with the project's 
directory as it's name, go to that field and delete auto-attached
directory name so as to create project in the same directory from
which dome3.exe was executed. It is a bug, still if you whish
to create project in separate directory - do this, but then
exit demo, and copy all config_* from executable's directory into
the one of your created project and launch the demo3.exe again.

* watch for top-level menus which may disappear/hide while 
you switch between different types of documents.

* after clicking "Edit code" the source is shown in the
wrong place sometimes, try scrolling - it will update
itself and cursor correctly then

* panels may be nested

* "File | Close Workplace" works

* format of stored/loaded .xml conforms to the first release
of Vaclav's XML-resource system ("property-oriented"), 
except that it assumes some more widgets, handlers for which
i've added to wxxml package, that you may download from 

	http://soften.ktu.lt/~alex/xml2.zip
	
also, this one has third-party libxml (1.MB) replaced with 
lightweight (30K) xml parsing and generation routines 
from wxWorkshop, so it is much smaller then the 
original distr.

I cannot give any guarantee the correctness
of generated source-code which should confrom with
wxxml's API, because i haven't tried to compiled it yet. 
If the generated sources fail to build for you, you may 
try fixing scripts in "config_widgets.txt" which is briefly 
described at the end of this doc.

You shall not expect a lot of usability from it, unless 
you are challenged to dive into it's "scripting bushiness"
which is not documented here, nor anywhere yet.


About widget (dialog/panel/etc) editor
======================================

with the new .xml-resource system it is possible
to use sizers and nest components hierarchically within each other,
all this is supported in domo3. 

Currently "Set sizer" operation is no imp, instead you have to 
select "wxBoxSizer" from "Insert", and place it where you whish 
by point-and-clicking within the canvas.

There are widgets which may contain others and serve as "parents",
these are:

wxDialog, wxPanel, wxStaticBox and wxBoxSizer.

If the component has only one child and it is wxBoxSizer, then
the contained sizer is stretched to cover the whole client
area, otherwise the contents of the components are laid out
using as they are placed (in DialogEd manner). Components
having in such "X/Y" mode of internal layouting, are
capable of common CAD-style operations, like multiple
selections, dragability, group-layouting (via "Layout" menu).

When inserting a sizer into component, it is not streched
immediately, only after resizing or dropping other components
around - it is a bug.

In the case of sizer-based layouting model, only single-selection
is possible. Dragging of component in this mode is meant 
for altering the order of child-items. If user's intention
is to place dragged component A before component B, then
the A shell be dropped at the first upper-most AND right-most
area of component B, e.g.

********
********
****....
****....

if top-left vertex of A hits '*'-marked area
of B, then A is placed before B, otherwise after it.

If a dragged component is dragged anywhere away from bounds
of it's former parent, it is removed from it's containing sizer 
and inserted into a component onto which it was dropped. This 
behaviour allows for dragability of items across boundaries of 
the hierarchical item-composition.

Copy/Paste as well as Undo/Redo operations are available 
in both X/Y and sizer modes (the mode is not global to
the resource, rather it is local to a particular component 
which has or hasn't a sizer set up within). 

Undo/Redo is hiearachical, unlimited and doesn't crash 
(at least for me) - you may safely use it against all sorts 
of screw-ups in sizer-based layouting. However, the buffer 
is cleared when the document is saved.

Shortcut for "Undo" is Ctrl-Z or "Alt+Back", the
later works from everywhere (globally), the former
is caught only when the focus in within the document
MDI-child frame, e.g. it wont work if focus was moved
to property-sheet and left there, then try clicking
back onto document-frame to regain the document-focus,
to allow all non-Alt+ shortcuts to work.


Other nifty features, you would not care about yet
==================================================

there are number of nice but rather complex options to
customize wxWorkshop's defaults via semi-programable
scripts and templates. Descriptions of those deserve
separate and lengthy chapter. It is still possible
hack them, so i give a brief overview for
each of the config_* files:

    config_srctempl.txt - contains any number of custom
    source-code generation templates, possibly for
    multiple languages. Supports variable substitutions $(..),
    branching of control with $(IF (...) and nested invocations
    with $(@subscribt[<name>).

	config_widgets.txt - contains any number custom widget-descriptions
	(actually, there are no "standard" widgets), describing each
	of their property-sets in a hierarchical manner so as to 
	allow reusing repeating groups of fields in different widgets.
	
	config_stdwlooks.wlk - constrains "instructions" and formulas
	for generation of visual image for a widget. wxWorkshop does not 
	use native widgets in editing (design) modes, for performance
	and design reasons. This file describes how to render
	look of widgets as close as possible to that of native ones,
	thereby allowing to view the same composition using look-standards
	of different platforms, provided that .wlk file contains
	appropriate rendering-instructions. 
		The content of .wlk files can be edited validated and previewed 
	within wxWorkshop itself, for that it should be included into
	a project and activated in the editor.
		Currently, contains very few look-descriptions, for
	most common widgets targeting wxMSW-look and wxButton for wxGTK.
		If the resource-editor cannot locate rendering-instructions
	it will show red-rectangle with crossed with white stripes,
	indicating the missing description.
	
	All three configuration files are read from the directory of demo3.exe,
	or from project's directory if currently active project has it's own directory.
	(this is a bug).

	
Happy hacking! :)


Aleks.

-----------------------------------------
-------------- NEWER NOTES --------------
-----------------------------------------



Extract new_scripts.zip into the directory of demo3.exe and
to directories of all projects that you've created (if any).

build xml.lib library from xml2_1.zip (.dsw included),
setup your include path to contain include/ directory
of of the extracted xml sources.

go through scenariou of whattotry.txt, with the following
exceptions:

instead of creating "dialog", choose "frame", because
it will be needed as application's main window resoruce.
After adding some buttons and data-entry controls to the frame, 
select the frame itself, and make sure the following fields are checked:

"has caption"
"system menu"
"minimize box"
"maximize box"
"resize border"
"thick frame"

this is a bug, because window-style defaulting does not work yet.
Also, make sure you add more then one child-widget into the
frame, otherwise the single one will be stretched to cover
frame's client area.

When creating a menubar resource, insert a couple submenus
(at least one) into each of the top-level menus - otherwise you'll 
get run-time errors in your app - a bug. For inserting subitems select 
on of top-level items and use "Insert | Insert menu - M".

After generating source files and saving all documents, run
your favorite IDE (e.g. DevStudio) and create a project around
generated .h and .cpp files. Create it in the same directory
where all generated files reside, so that "working directory"
during execution would be same, otherwise your application will
not locate generated .xml file and fail.

If files build ok and application runs, try adding event-handlers
for buttons you've added into the frame, use "Events | Edit events".
After adding, do "File | Save all" and switch back to your IDE to
recompile changes and run the app again. Then try binding controls
to member variables (e.g. text controls, check boxes, radio buttons).
To test binding, add a test-command into one of the menus, then add
corresponding event-handler method (use wizzerds from "Events" menu), 
in which first call ExchangeValues( FALSE ) to retrieve values from controls
to member variables, then use wxMessageBox() to display member variable 
values and check if they match with those in GUI-controls.

NOTE: You may safely edit generated filles while not leaving
      wxWorkplace, except blocks enclosed within %% sometag-{ and %% soemtag-} 
      blocks. Aloso you may edit bodies of event-handler methods, as long as you
      don't change their declarations. Your changes will be preserved
      during regeneration passes, which happen after adding/removing
      event-handlers or mebmber-varialbe bindings.

some troubleshooting
====================

After restarting demo3 and loading your workplace, it may no longer
contain your project (known bug). To recover, right-click on workplace-icon
in the browser, select "Insert Existing project" to reinsert the your
project, then do "File | Save all"

After creating your first resource-document, it does not get to 
workplace-browser's tree immediately, you have to close the demo
and restart it, upon closure you'll be asked to give a file-name
for the newly created resource-document. Note, that .xml resource-document
is not editable as a whole, only it's parts can be selectively edited
in separate document-windows, e.g. menubars, dialogs, frames, etc which
belong to the same .xml resource file. To create or edit them, double 
click on .xml file item in the browser.


Regards,
Aleksandars