update manual

Author: dmcoles

Rebuild.info

@@ -28,6 +28,7 @@ Just a few of the improvements are:
 4) Copy buffer making it easier to move or duplicate gadgets 
 5) More flexible system of arranging gadgets and layouts
 
+
 2. License
 
 The program is released into the public domain for anyone to use however
@@ -39,6 +40,7 @@ without restriction however use of this project is entirely at your own
 risk. I will not accept responsibilty for any issues arising from the
 use of Rebuild.
 
+
 3. Using Rebuild
 
 Upon loading Rebuild you will be presented with the main working window of
@@ -93,12 +95,47 @@ You could create it using an arrangement like this:
 
 There are some example files included in the examples folder.
 
+In addition to the layout control there are two other gadget types that
+can have child controls added to them. The ClickTab gadget and the Virtual
+gadget.
+
+The ClickTab gadget displays tabs according to its list (see list manager
+section below). In addition it can also support different pages of controls
+for each tab. Child gadgets are added to a ClickTab control in exactly the
+same way as they are added to a layout control. Each child control will
+be displayed in a different tab. Typically you would add a layout control
+to the ClickTab for each tab. Then you can build up a UI design for that tab
+by adding further child controls to each layout.
+
+The Virtual gadget displays a group of gadgets within a scrollable area.
+You can display a larger number of gadgets than would normally be visible
+in the window by allowing the user to scroll around the virtual area. The
+virtual gadget allows only one child control to be added directly. That
+would typically be a layout control in order that further gadgets can
+be displayed within the virtual scroll area.
+
 You can also control the screen settings that are using for your GUI design
 and add menu definitions for each window. You can also specify a set of
 Arexx commands. The screen settings and Arexx commands will not affect how
 the design works in Rebuild but they will be included in the source code
 that you generate.
 
+Note:
+
+The TextField gadget is not a Reaction gadget and is not included by defaullt
+in OS 3.2. You should avoid using this gadget. It was included in the
+original ClassAct library but was not carried forwards into the Reaction
+implementation. The stand alone textfield gadget can be downloaded from
+the Aminet here:
+
+http://aminet.net/package/dev/gui/textfield
+
+If you use this gadget in your GUI design and it is not installed on your
+system you will only see a placeholder graphic in the preview window.
+If you generate code and attempt to run that code on a system where the
+TextField gadget is not installed it will fail on startup.
+
+
 4. The list manager
 
 Some of the gadget types (List Browser, Chooser, RadioButton and ClickTab)
@@ -109,6 +146,7 @@ add them to a gadget. You can add the same list to more than one gadget.
 If you need to go back later and modify the list, it can easily be edited
 in the list manager even after it has been added to a gadget.
 
+
 5. The copy buffer
 
 On the right side of the main window you will see the copy buffer.
@@ -117,6 +155,7 @@ window into the copy buffer. This is highly useful if you want to
 duplicate a gadget several times with the same settings or move a gadget
 from one window to another in your design.
 
+
 6. Source code generation
 
 Rebuild is able to generate fully working SAS C and Amiga E code for the
@@ -179,9 +218,290 @@ values into your custom code then it will need to be re-coded.
 
 There is more information regarding this in the next section.
 
+
 7. Tips on working with the rebuild generated source code.
 
-   to be completed.
+Here is an example of some C code generated by rebuild. I have annotated it
+with some comments to explain the intended use of some of the parts of the
+code. The generated code is only intended as a possible starting point for
+the application. In order to make the application functional there will be
+a lot of additional coded needed to drive the GUI.
+
+Rebuild is not designed to be a fully functional development environment,
+it is purely a GUI design tool. If you use this code structure as a basis
+for your application, it would be recommended that you try to separate
+your custom code from the auto-generated code as much as possible in
+order to reduce the amount of rework needed if you change the GUI design
+and have to regenerate the code.
+
+#include <clib/macros.h>
+#include <clib/alib_protos.h>
+#include <clib/compiler-specific.h>
+
+#include <proto/exec.h>
+#include <proto/dos.h>
+#include <proto/utility.h>
+#include <proto/graphics.h>
+#include <proto/intuition.h>
+#include <proto/gadtools.h>
+#include <proto/icon.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <proto/window.h>
+#include <proto/layout.h>
+#include <proto/button.h>
+#include <proto/string.h>
+#include <proto/label.h>
+
+#include <libraries/gadtools.h>
+#include <reaction/reaction.h>
+#include <intuition/gadgetclass.h>
+#include <reaction/reaction_macros.h>
+#include <classes/window.h>
+#include <exec/memory.h>
+
+void window_3( void );
+
+struct Screen	*gScreen = NULL;
+struct DrawInfo	*gDrawInfo = NULL;
+APTR gVisinfo = NULL;
+struct MsgPort	*gAppPort = NULL;
+
+struct Library *WindowBase = NULL,
+               *ButtonBase = NULL,
+               *StringBase = NULL,
+               *LabelBase = NULL,
+               *GadToolsBase = NULL,
+               *LayoutBase = NULL,
+               *IconBase = NULL;
+struct IntuitionBase *IntuitionBase = NULL;
+
+//Window_3
+//this enumeration should be used to access the main_gadgets array. the names
+//of the enumerations have the reaction gadget id's on the end so these names
+//will never change even if the design is update (eg another gadget added).
+//If the code is regenerated then the positions will change but the names
+//will not. This means its safe to use these enumeration names in any custom
+//code you may write.
+enum window_3_idx { layout_5, string_6, string_7, layout_8, button_9, button_10 };
+
+//this enumeration should be used when you need to check the GA_ID values
+//against a particular gadget (eg when writing your message handling code
+//the enumeration names will be in the same order as those in the enum
+//above and the names will be the same as those above with _id appended.
+enum window_3_id { layout_5_id = 5, string_6_id = 6, string_7_id = 7, layout_8_id = 8, 
+  button_9_id = 9, button_10_id = 10 };
+
+int setup( void )
+{
+  if( !(IntuitionBase = (struct IntuitionBase*) OpenLibrary("intuition.library",0L)) ) return 0;
+  if( !(GadToolsBase = (struct Library*) OpenLibrary("gadtools.library",0L) ) ) return 0;
+  if( !(WindowBase = (struct Library*) OpenLibrary("window.class",0L) ) ) return 0;
+  if( !(IconBase = (struct Library*) OpenLibrary("icon.library",0L) ) ) return 0;
+  if( !(LayoutBase = (struct Library*) OpenLibrary("gadgets/layout.gadget",0L) ) ) return 0;
+  if( !(ButtonBase = (struct Library*) OpenLibrary("gadgets/button.gadget",0L) ) ) return 0;
+  if( !(StringBase = (struct Library*) OpenLibrary("gadgets/string.gadget",0L) ) ) return 0;
+  if( !(LabelBase = (struct Library*) OpenLibrary("images/label.image",0L) ) ) return 0;
+  if( !(gScreen = LockPubScreen( 0 ) ) ) return 0;
+  if( !(gVisinfo = GetVisualInfo( gScreen, TAG_DONE ) ) ) return 0;
+  if( !(gDrawInfo = GetScreenDrawInfo ( gScreen ) ) ) return 0;
+  if( !(gAppPort = CreateMsgPort() ) ) return 0;
+
+  return -1;
+}
+
+void cleanup( void )
+{
+  if ( gDrawInfo ) FreeScreenDrawInfo( gScreen, gDrawInfo);
+  if ( gVisinfo ) FreeVisualInfo( gVisinfo );
+  if ( gAppPort ) DeleteMsgPort( gAppPort );
+  if ( gScreen ) UnlockPubScreen( 0, gScreen );
+
+  if (GadToolsBase) CloseLibrary( (struct Library *)GadToolsBase );
+  if (IconBase) CloseLibrary( (struct Library *)IconBase );
+  if (IntuitionBase) CloseLibrary( (struct Library *)IntuitionBase );
+  if (ButtonBase) CloseLibrary( (struct Library *)ButtonBase );
+  if (StringBase) CloseLibrary( (struct Library *)StringBase );
+  if (LabelBase) CloseLibrary( (struct Library *)LabelBase );
+  if (LayoutBase) CloseLibrary( (struct Library *)LayoutBase );
+  if (WindowBase) CloseLibrary( (struct Library *)WindowBase );
+}
+
+//this is a generic routine that will be used to run the message loop
+//for all windows in this project. You should use the window id to determine
+//which window is being displayed. In order to avoid a huge message
+//processing loop with many different windows and gadgets being handled
+//I would recommend creating a function for each window and calling that
+//according to the window id.
+//
+//Currently this code structure is designed for projects with modal windows.
+//If you wanted to display a settings page for example you would call the
+//window function in the gadget press handling code you have written.
+//This would create the window object and call runWindow. Once that
+//window is closed control would return to the calling window.
+//
+//If this structure does not suit your application then you can code the
+//message handling from scratch and just use the window definitions that
+//can be generated using Rebuild.
+//
+void runWindow( Object *window_object, int window_id, struct Menu *menu_strip, struct Gadget *win_gadgets[] )
+{
+  struct Window	*main_window = NULL;
+
+  if ( window_object )
+  {
+    if ( main_window = (struct Window *) RA_OpenWindow( window_object ))
+    {
+      WORD Code;
+      ULONG wait = 0, signal = 0, result = 0, done = FALSE;
+      GetAttr( WINDOW_SigMask, window_object, &signal );
+      if ( menu_strip)  SetMenuStrip( main_window, menu_strip );
+      while ( !done)
+      {
+        wait = Wait( signal | SIGBREAKF_CTRL_C );
+
+        if ( wait & SIGBREAKF_CTRL_C )
+          done = TRUE;
+        else
+          while (( result = RA_HandleInput( window_object, &Code )) != WMHI_LASTMSG)
+          {
+            switch ( result & WMHI_CLASSMASK )
+            {
+              case WMHI_CLOSEWINDOW:
+                done = TRUE;
+                break;
+
+              case WMHI_MENUPICK:
+              //put your menu handling code here
+              //it is advised that you call a separate function for this
+                puts("menu pick");
+                break;
+
+              case WMHI_GADGETUP:
+              //put your gadget handling code here
+              //it is advised that you call a separate function for this
+                puts("gadget press");
+                break;
+
+              case WMHI_ICONIFY:
+                if ( RA_Iconify( window_object ) )
+                  main_window = NULL;
+                break;
+
+              case WMHI_UNICONIFY:
+                main_window = RA_OpenWindow( window_object );
+                if ( menu_strip)  SetMenuStrip( main_window, menu_strip );
+              break;
+
+            }
+          }
+      }
+    }
+  }
+}
+
+
+//this is the window function, it creates the window and displays it
+//it will return once the window is closed
+//
+void window_3( void )
+{
+  struct Gadget	*main_gadgets[ 7 ];
+  Object *window_object = NULL;
+
+  window_object = WindowObject,
+    WA_Title, "Please log in...",
+    WA_Left, 5,
+    WA_Top, 20,
+    WA_Width, 250,
+    WA_Height, 80,
+    WA_MinWidth, 150,
+    WA_MinHeight, 80,
+    WA_MaxWidth, 8192,
+    WA_MaxHeight, 8192,
+    WINDOW_AppPort, gAppPort,
+    WA_CloseGadget, TRUE,
+    WA_DepthGadget, TRUE,
+    WA_SizeGadget, TRUE,
+    WA_DragBar, TRUE,
+    WINDOW_Position, WPOS_CENTERSCREEN,
+    WINDOW_IconTitle, "MyApp",
+    WA_NoCareRefresh, TRUE,
+    WA_IDCMP, IDCMP_GADGETDOWN | IDCMP_GADGETUP | IDCMP_CLOSEWINDOW,
+    WINDOW_ParentGroup, VLayoutObject,
+    LAYOUT_SpaceOuter, TRUE,
+    LAYOUT_DeferLayout, TRUE,
+      LAYOUT_AddChild, main_gadgets[layout_5] = LayoutObject,
+        GA_ID, layout_5_id,
+        LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
+        LAYOUT_AddChild, main_gadgets[string_6] = StringObject,
+          GA_ID, string_6_id,
+          GA_RelVerify, TRUE,
+          GA_TabCycle, TRUE,
+          STRINGA_MaxChars, 80,
+        StringEnd,
+        CHILD_Label, LabelObject,
+          LABEL_Text, "User name",
+        LabelEnd,
+        LAYOUT_AddChild, main_gadgets[string_7] = StringObject,
+          GA_ID, string_7_id,
+          GA_RelVerify, TRUE,
+          GA_TabCycle, TRUE,
+          STRINGA_MaxChars, 80,
+        StringEnd,
+        CHILD_Label, LabelObject,
+          LABEL_Text, "Password",
+        LabelEnd,
+        LAYOUT_AddChild, main_gadgets[layout_8] = LayoutObject,
+          GA_ID, layout_8_id,
+          LAYOUT_Orientation, LAYOUT_ORIENT_HORIZ,
+          LAYOUT_AddChild, main_gadgets[button_9] = ButtonObject,
+            GA_ID, button_9_id,
+            GA_Text, "OK",
+            GA_RelVerify, TRUE,
+            GA_TabCycle, TRUE,
+            BUTTON_TextPen, 1,
+            BUTTON_BackgroundPen, 0,
+            BUTTON_FillTextPen, 1,
+            BUTTON_FillPen, 3,
+          ButtonEnd,
+          LAYOUT_AddChild, main_gadgets[button_10] = ButtonObject,
+            GA_ID, button_10_id,
+            GA_Text, "Cancel",
+            GA_RelVerify, TRUE,
+            GA_TabCycle, TRUE,
+            BUTTON_TextPen, 1,
+            BUTTON_BackgroundPen, 0,
+            BUTTON_FillTextPen, 1,
+            BUTTON_FillPen, 3,
+          ButtonEnd,
+        LayoutEnd,
+      LayoutEnd,
+    LayoutEnd,
+  WindowEnd;  
+  //a blank entry at the end in case you need to loop through the
+  //array and know where the end of the data is
+  main_gadgets[6] = 0;
+
+  //call the code to display the window
+  //the window id is 3 and it has no menu structure.
+  runWindow( window_object, 3, 0, main_gadgets );
+
+  if ( window_object ) DisposeObject( window_object );
+}
+
+int main( int argc, char **argv )
+{
+  if ( setup() )
+  {
+    window_3();
+  }
+  cleanup();
+}
+
 
 8. Tooltype settings
 
@@ -207,6 +527,7 @@ Here is a list of the tooltypes that can be defined
    WINDOWWIDTH =
    WINDOWHEIGHT = (override the main window size and position)
 
+
 9. Futher inforation
 
 ReBuild is written using my own E-VO compiler.
@@ -218,6 +539,17 @@ If you find any issues with this product please do feel free to raise an
 issue in the gitgub repo or if you wish to contact me for any reason
 regarding this project please do.
 
+Michael Bergmann has put in a lot of time and effort in testing Rebuild and
+has also developed a tutorial for Rebuild. This tutorial goes into depth
+regarding the use of Rebuild and each of the gadget types.
+
+The tutorial is available separately from gitub repository:
+
+https://github.com/dmcoles/ReBuild/tree/main/tutorial
+
+My thanks go to Michael for this great work.
+
+
 10. Future (possible) enhancements
 
 I have many ideas for future enhancements to this project. My plan was to