





                IIvviibb -- aa GGrraapphhiiccaall UUsseerr IInntteerrffaaccee bbuuiillddeerr ffoorr IIddooll

                                  _R_o_b_e_r_t _P_a_r_l_e_t_t
                             _(_p_a_r_l_e_t_t_@_d_i_a_l_._p_i_p_e_x_._c_o_m_)





          11..  IInnttrroodduuccttiioonn

          Creating a dialog window with many components can be hard work,
          involving repeated compiles and runs in order to get the compo-
          nents correctly sized and positioned.  Furthermore, much of the
          code in a dialog is lengthy and tiresome to write.

          To help reduce the work involved for the programmer in creating
          a  dialog,  a  visual  interface  builder  is available, called
          ``ivib''.  This program allows a user  to  interactively  place
          and  configure  components in a window area.  A program is then
          generated automatically which will reproduce the dialog.

          The classes used by this program are documented in the file

               gui.ps.


          The main window of ivib,  with  a  dialog  under  construction,
          looks like this :-

                            _F_i_g_u_r_e _1 _- _I_v_i_b _m_a_i_n _w_i_n_d_o_w


          To  create  a  dialog window using Ivib, start the program with
          the name of a new _l_a_y_o_u_t file; for example :-

               ivib myprog.layout

          The Ivib window will appear with a blank ``Canvas'' area, which
          represents  the  dialog  window to be created.  At startup, the
          attributes  of  this  window  are  the  default   Icon   window
          attributes.   We  will  see how to change these attributes in a
          moment,  but first let's add a button to the dialog.   This  is
          done  by simply clicking the button in the top left-hand corner
          of the toolbar.  Try moving and resizing the  resulting  button
          by left-clicking on it with the mouse.

          To  change the label in the button, click on it so that the red
          borders appear in the edges.  Then press Alt-D.  The  following
          dialog appears :-

                      _F_i_g_u_r_e _2 _- _B_u_t_t_o_n _c_o_n_f_i_g_u_r_a_t_i_o_n _w_i_n_d_o_w

          Change  the  label by simply changing the text in the ``Label''
          field and clicking ``okay''.

          As just mentioned, the dialog's attributes  are  initially  the
          default  Icon  window  attributes.  To change these, select the


                                          1









          menu option Canvas -> Dialog prefs.  The following window  will
          appear.

                      _F_i_g_u_r_e _3 _- _D_i_a_l_o_g _c_o_n_f_i_g_u_r_a_t_i_o_n _w_i_n_d_o_w

          To change the dialog attributes :-

          (i)    Click on the Attribs tab

          (ii)   Click on the Add button

          (iii)  Edit the two text fields so that they hold the attribute
                 name and the attribute value respectively;  for  example
                 try adding ``bg'' and ``pale blue''.

          (iv)   Click on Apply

          (v)    Click on Okay.

          Note  that  the button changes its background to pale blue too.
          Each object has its own attributes which it can  set  to  over-
          ride  the  dialog's.   Click  on  the button and press Alt-d to
          bring up the button's configuration dialog again.  Now click on
          the  Attribs tab of this dialog and set the background color to
          (say) white.  The click okay and you will see that the button's
          background changes to white.

          You  will  recall  from the previous example programs that some
          objects can be contained in other objects, such  as  the  Panel
          class.   This  is  handled  in ivib in a convenient way.  Add a
          Panel object to the dialog by clicking on the Panel button  (on
          the  second  row, fourth from the left).  A panel appears.  Now
          drag the button into the panel.  A message should appear in the
          information  label  below  the  toolbar,  ``Placed  inside con-
          tainer''.  Now try dragging  the  panel  about,  and  you  will
          observe  that  the  button moves too - it is now ``inside'' the
          panel.  It may be moved back out by simply dragging it  outside
          the  panel's  area.   This  method applies to all the container
          objects.

          There are several buttons which operate on objects.  The  large
          ``X''  button  deletes  the  currently  selected  objects.  Try
          selecting the button and deleting it.  The  arrow  buttons  are
          ``redo''  and  ``undo''  operations.   Clicking on the ``undo''
          button will undo the delete operation and the button should re-
          appear.

          Now  try  saving  your canvas.  Press Alt-s, and select a file-
          name, or accept the default.  Note that a canvas is saved in  a
          ``.layout''  file.  This is an ASCII file, but it is not really
          human-readable.  Now try creating an Icon-2 source file.  Press
          Alt-c; again select a filename or accept the default file (NB -
          the file will be overwritten).  The extension this time  should
          be  ``.icn''  or  ``.iol'' for a source file.  After selection,
          the program will be output to the given source file.   If  this
          is called, say, myprog.iol, then this can be compiled with

               idol myprog.iol gui.iol


                                          2









          to give an executable file myprog which, when run, will produce
          the same dialog shown in the canvas area.

          Of course, the resulting dialog will not do anything, and it is
          then  up  to  the  programmer  to fill in the blanks by editing
          myprog.iol.

          Hopefully, following the above steps will give an idea  of  how
          the  ivib  program  works.   Below  are more details of how the
          individual components, dialogs and operations work.

          22..  MMoovviinngg,, sseelleeccttiinngg aanndd rreessiizziinngg

          Select an object by clicking on it with the mouse.  Its  selec-
          tion  is  indicated  by  red  edges around the corners.  Multi-
          select objects by holding the shift key down  and  clicking  on
          the  objects.  The first will have red corners, the others will
          have black corners.  There are several operations which operate
          on  multiple objects and map some attribute of the first selec-
          tion to the others, hence the distinction.

          To move an object, select it by clicking on it  with  the  _l_e_f_t
          mouse  button,  and then drag it.  Note that dragging an object
          even by one pixel will set the X or Y position to  an  absolute
          figure,  disturbing  any carefully set up percentage specifica-
          tion!  Because this can be irritating when  done  accidentally,
          the  X  and/or Y position may be fixed in the dialog so that it
          cannot be moved in that plane.  Alternatively,  when  selecting
          an object which you do not intend to move, use the _r_i_g_h_t button
          instead.

          To resize an object, select it and then left click  on  one  of
          the  corners.   The mouse cursor will change to a resize cursor
          and the corner may be dragged.  Note that,  like  the  position
          specification, resizing an object will set the size to an abso-
          lute number and will also reset  the  ``use  default''  option.
          Again,  this  can  be  avoided  by  ``fixing'' the width and/or
          height in the object's dialog box.

          33..  DDiiaalloogg ccoonnffiigguurraattiioonn

          The dialog itself is configured using  this  dialog,  which  is
          selected  by  the menu option Canvas -> Dialog prefs.  The tabs
          work as follows.

          Size
               The minimum width and height entries simply set the  mini-
               mum dimensions of the window.  The width and height may be
               configured here, or more simply  by  resizing  the  canvas
               area by clicking on the red bottom-right-hand corner.


          Attribs
               This has been described briefly above; the Add button pro-
               duces a new entry which is then edited.  The edited  entry
               is  placed  in  the  table with ``Apply''.  The ``Delete''
               button deletes the currently highlighted selection.



                                          3









          Code generation
               The part of the code to setup the dialog is written into a
               method  called  setup.   If  the  ``interpose  in existing
               file'' option is checked then the program  will  read  the
               present  contents  of  the  selected output file up to the
               current setup method, interpose the new setup and copy the
               remainder  out.   This is useful if some changes have been
               made to the file output by  a  previous  run.   NB  It  is
               important to take a copy of the existing file before using
               this option in case unexpected results occur.

               The other options simply select which other methods should
               be  produced.   If  a main procedure is produced, then the
               result will be an executable program.


          Other
               This tab allows the name of the dialog to be set, together
               with a flag indicating whether it is ``modal'' or not.  If
               so, then a method called pending is produced; this  method
               is  repeatedly  called by the toolkit whilst it is waiting
               for events to occur.


          44..  CCoommppoonneenntt ccoonnffiigguurraattiioonn

          Each component dialog has a standard tabbed pane area for  con-
          figuration  of  attributes  common to all components.  The tabs
          are as follows :-

          Position & Size
               X, Y, W and H set the position and  size  of  the  object.
               The drop down list can be used for convenience, or a value
               may be entered by hand.  The ``fix'' buttons  prevent  the
               object being moved or sized from outside the given parame-
               ter in the Canvas area.  This is useful once  an  object's
               position  has  been finalized, and you don't wish to acci-
               dentally move it.  The ``use default'' buttons  mean  that
               the width/height will be set as the default for the object
               based on the parameters and the attributes.  For  example,
               a  button's  size will be based on the label and the font.
               For some objects there is no default size, so  these  but-
               tons are shaded.

               The alignment of the object is also set from this tab.


          Attribs
               This  works in exactly the same way as the Attribs tab for
               the dialog, except that these attributes apply only to the
               object.


          Other
               This tab allows the name of the object to be set - this is
               the name used in the output program code.




                                          4









               The ``draw border'' button applies to some objects  -  see
               the reference section for further information.

               If  the  ``is  shaded'' button is clicked then the initial
               state of the object will be shaded.

               If the ``has initial focus'' button is clicked  then  this
               object  will have the initial keyboard focus when the dia-
               log is opened.


          55..  CCoommppoonneenntt ddeettaaiillss

          Components are added to the dialog by clicking on  the  toolbar
          buttons,  and  dialogs are produced by selecting the object and
          pressing on Alt-d, as explained above.  Most of the dialogs are
          hopefully  straightforward,  but  some warrant further explana-
          tion, as follows.

          TextButton
               The dialog for this component includes an option  for  the
               button  to  be  added to a ButtonGroup structure.  This is
               explained in detail below.


          Border
               This component is rather odd.  To select it,  rather  than
               clicking  inside the border, click in the area at the bot-
               tom right hand corner.  It can then be resized  or  moved.
               Now  try  dragging  another  object, such as a Checkbox or
               Label and release it so that its top left hand  corner  is
               within  the  area  in  the bottom right hand corner of the
               Border object.  The CheckBox/Label or whatever is now  the
               title  of  the  Border.   Thus,  any  object can be in the
               title.  To remove the object from the Border, just drag it
               out.  The alignment of the title object is set in the dia-
               log, but is by default left aligned.


          Image
               Initially this object has an outline.  When a filename  is
               entered  into the dialog however, the image itself is dis-
               played.


          CheckBox
               Customized up/down images may be set from the dialog,  and
               A  CheckBoxGroup may be selected if one is available; this
               is explained in more detail below.


          MenuBar
               The MenuBar dialog enables a complete multi-level menu  to
               be  created.   Clicking on a particular line will allow an
               item to be inserted at that point.   (Only  menus  can  be
               inserted into the lowest level of course).  Clicking on an
               item will allow insertion, deletion or editing of the par-
               ticular  item.   A  CheckBoxGroup can be created by multi-


                                          5









               selecting checkboxes (by holding down the shift key whilst
               clicking on the lines) and clicking the button.


          ScrollBar
               Both  vertical  and  horizontal scroll bars are available;
               for details of how the various options  work,  please  see
               the reference manual for the toolkit.


          Table
               A  table  column  is added by clicking the ``Add'' button;
               the details should then be edited and the ``Apply'' button
               pressed  to transfer the details to the table.  A selected
               column can be deleted with  the  ``Delete''  button.   The
               drop-down  list  selects whether or not lines in the table
               can be selected by clicking.


          TabSet
               Add a TabItem (ie a tabbed pane) by clicking  the  ``Add''
               button.   Note that a single pane is automatically present
               when the object is  created.   To  switch  between  panes,
               select  a  TabItem  button.   An  asterisk  appears by the
               entry, and when the dialog is exited, it is  this  TabItem
               which  is to the front of the TabSet.  To add items to the
               current pane simply drag and drop them into it.  The whole
               of  the  item must be in the pane, and a confirmatory mes-
               sage appears that the item has  been  added  to  the  con-
               tainer.  To take it out of the container, just drag it out
               of the pane.  Note that the selected pane is the one which
               is configured to be initially at the front when the dialog
               is opened.


          MenuButton
               This is just a menu system with one root menu.  The dialog
               is the same as that for MenuBar except that the small icon
               can be configured.


          OverlaySet
               The configuration for an OverlaySet  is  very  similar  to
               that  for a TabSet, except that there are no tab labels to
               configure of course.


          CheckBoxGroup
               This does not create an object on the screen,  but  rather
               places  several selected CheckBox objects into a CheckBox-
               Group object, so that they act as coordinated  radio  but-
               tons.   To  use this button, multi-select several CheckBox
               objects, and press the button.

               The CheckBoxGroup itself is configured  by  selecting  the
               menu  item  Canvas  ->  CheckBoxes.   In  fact,  the  only
               attribute to be configured is the name  of  the  CheckBox-
               Group.   Note  that once a CheckBoxGroup has been created,


                                          6









               it cannot be deleted.  A CheckBox can be taken out or  put
               in to a CheckBoxGroup from its configuration dialog.


          ButtonGroup
               This  operates in a very similar fashion to CheckBoxGroup,
               except that it places buttons into a ButtonGroup.


          66..  OOtthheerr eeddiittiinngg ffuunnccttiioonnss


          Delete
               This simply deletes all the selected  objects;  note  that
               deleting  a  container also deletes all the objects inside
               it.


          Undo and Redo
               These functions undo/redo changes.  The size of the buffer
               used for storing undo information can be configured in the
               File -> Preferences dialog; by default it allows  7  steps
               backward at any one time.


          Centre Horizontally
               This  operation  sets  the selected objects' x position to
               50%, their alignment to centre, and  fixes  them  in  that
               horizontal  position.  To ``unfix'' an object, uncheck the
               ``fix'' box in its dialog box.

               Centre vertically naturally works in just the same way for
               the y position.


          Align Horizontally
               This  operation sets the x position and the x alignment of
               all the selected objects to  the  x  position  and  the  x
               alignment of the first selected object.

               Note  that  whether  the objects end up as appearing to be
               left aligned, centre aligned or right aligned will  depend
               on the alignment of the first selected object.

               Align vertically works just the same way.


          Grid
               To  use  this  function,  place several items roughly in a
               grid, select them all, perform the operation and hopefully
               they will be nicely aligned.


          Copy
               This simply creates a duplicate of each selected object.





                                          7









          Equalize widths
               This  simply copies the width of the first selected object
               to all of the other selections.

               ``Equalize heights'' naturally does the same for  heights.


          Even Space Horizontally
               This  leaves the leftmost and rightmost object of the cur-
               rent selections in  place  and  moves  all  of  the  other
               objects  so that they are equally spaced between the left-
               most and rightmost objects.

               ``Even Space Vertically'' does the same vertically.


          Reorder
               This is used to reorder the selected objects in  the  pro-
               gram's  internal  lists.   This is useful so that they are
               produced in the program output in the desired  order,  for
               example  to  ensure  that the tab key moves from object to
               object  in  the  right  sequence.   By  selecting  several
               objects  and  using reorder, those objects appear first in
               sequence in the order in which they were selected.


          77..  OOnnlliinnee rreessoouurrcceess

          The current version of Ivib and the gui toolkit can be found at
          the       following      location      :-      http://www.cpon-
          line.co.uk/rpp/gui.html





























                                          8



