Crawly Crypt Collection 1/crawlyvol1.bin/program/books/progem/hooks.11

Text File | 1986-11-01 | 27KB | 519 lines

      Permission to reprint or excerpt is granted only if the following
      line appears at the top of the article:

       ANTIC PUBLISHING INC., COPYRIGHT 1986.  REPRINTED BY PERMISSION.



      PROFESSIONAL GEM  by Tim Oren
      Column #11 - GEM Hooks and Hacks, An Insider's AES Tricks


           Welcome  to  the  eleventh episode of ST PRO  GEM,  which  is
      devoted to exploring some of the little documented,  but powerful,
      features  of GEM.   Like the authors of most complex systems,  the
      GEM  programmers left behind a set of "hooks",  powerful  features
      which would aid them in enhancing the system later.  I am going to
      lay  out  a number of these methods which have served me  well  in
      making  creative use of the AES.   You will find that most of them
      concern  the object and form libraries,  since I was most involved
      in those parts of GEM.  There are probably many more useful tricks
      waiting  to be found in other parts of GEM,  so if you happen onto
      one, please let me know in the Feedback!   Before  you  begin,  be
      sure to pick up the download for this column:  GMCL11.C  in DL3 of
      PCS-57.

           POWERFUL   OBJECTS.    The  first  four  tricks  all  involve
      augmenting  standard  AES  objects.   This is a powerful technique
      for two reasons.  First, you can  take  advantage  of the  regular
      AES  object  and  form  libraries  to draw and handle most of your
      objects,  so that  your  program need only process the exceptions.
      Second, you can use the RCS  to  copy  the  special  objects  into
      multiple  dialogs  or resources.   These  four tricks are Extended
      Object  Types,  User-defined  Objects,  TOUCHEXIT,  and  INDIRECT.
      Let's look at each of them in turn.

           EXTENDED OBJECT TYPES.  If you look at the AES Object Library
      documentation,  you  will  notice  that the values for the OB_TYPE
      field in an object are  all 32 or less.   This means that a number
      of bits are unused in  this  field.   In fact,  the AES completely
      ignores the top byte of  the OB_TYPE field.   In addition, the RCS
      ignores the top byte, but it  also  preserves  its  value  when an
      object is read, written, or copied.

           This  gives  you one byte per object to use as you  see  fit.
      Since  the  processing of an object or dialog is (so far)  in  the
      hands of the AES,  the best uses of Extended Types are in flagging
      methods for initializing an object or handling its value when  the
      dialog  completes.

           For  example,  you  might  have  several  dialogs  containing
      editable numeric fields.   The Extended Type of each numeric field
      could be set to the index of the corresponding value in an  array.
      Then your application's dialog initialization code could scan  the
      object  tree  for  such objects,  pick up  the  appropriate  value
      from the array and convert it to ASCII,  storing the result in the
      resource's  string  area.   When the dialog was finished,  another
      pass could be made to reconvert the ASCII to binary and store away
      the results in the array.   (Note that the map_tree() utility from
      column #5 will scan an entire resource tree.)

           Another  application  is  to assign  uniform  codes  to  exit
      buttons  in  dialogs.   If you give every "OK" button an  Extended
      Type  of one,  and every "Cancel" button an Extended Type of  two,
      then  you  needn't  worry about naming every  exit  object.   Just
      examine  the Extended Type of the object returned by form_do,  and
      proceed accordingly.

           The catch, of course, is that you have to find a way to enter
      the  Extended  Type code in the first place.   Version 1.0 of  the
      RCS, as shipped with the Atari developer's kit, makes no provision
      for this.  So you have your choice of two methods for creating the
      first  object with each Extended Type code.

           First,  you can dump out a C source of a resource, insert the
      new type code by hand,  and regenerate the resource with STCREATE.
      Alternately,  you could carefully modify the binary resource using
      SID.   You will probably want to reread the AES object manual,  ST
      PRO GEM #4 and #5,  and use the C source as a guide when doing so.
      In both cases, you should make things easy on yourself by creating
      a  one  dialog resource with only a single object other  than  the
      root.   Version  2.0  of  the RCS will let you directly  enter  an
      Extended Type, but it has not yet been released for the ST by DRI.

           Once  you have created a prototype extended object by  either
      method, you can use the RCS to propogate it.  The safest way is to
      use the MERGE option to add the modified tree to the resource  you
      are building.  Then copy the prototype object via the clipboard to
      your dialog(s), deleting the extra tree when you are done.  If you
      are  using several different extended objects,  you can use  MERGE
      and clipboard copies to get them all into one tree which will then
      become your own object library.

           The  second way of using RCS is easier,  but more  dangerous.
      If you want to try the following technique,  BACK UP YOUR RCS DISK
      FIRST!   Put  simply,  the RCS does not care what is in its dialog
      partbox. It will make copies of anything that it finds there! This
      gives you the option of using the RCS on ITS OWN RESOURCE in order
      to add your customized objects to the partbox.

           To do this, open RCS.RSC from the RCS.  Since there is no DEF
      file,  you will get a collection of question mark icons.   Use the
      NAME option to make TREE5 into a DIALOG.    Open it,  and you will
      see the dialog partbox.

           Now you can use the MERGE technique described above to insert
      your  customized  objects.   Then SAVE the modified resource,  and
      rerun the RCS.  Your new objects should now appear in the partbox.
      If  you added several,  you may have to stretch the partbox to see
      them  all.   You can now make copies of the new objects just  like
      any other part.  (Note: DO NOT modify the alert or menu partboxes,
      you will probably crash the RCS.)

           USER-DEFINED  OBJECTS.   The one type of object which was not
      discussed in the  earlier articles  on  AES objects was G_USERDEF,
      the programmer defined object.  This  is  the  hook  for  creating
      objects  with  other  appearances  beyond  those  provided  by the
      standard  AES.   By  the  way,  you should note that the G_PROGDEF
      and APPLBLK mnemonics  used  in  the  AES documents are incorrect;
      the actual  names  as  used  defined  OBDEFS.H  are  G_USERDEF and
      USERBLK.

           The  RCS does not support the creation of G_USERDEF  objects,
      since  it  has  no idea how they will be drawn  by  your  program.
      Instead,  you  must insert a dummy object into your resource where
      you  want  the  G_USERDEF  to appear,  and  patch  it  after  your
      application performs its resource load.

           You   must  replace  the  object's  existing   OB_TYPE   with
      G_USERDEF,  though you may still use the upper byte as an Extended
      Type.   You  must  also  change the OB_SPEC field to be  a  32-bit
      pointer  to  a USERBLK structure.   An USERBLK is simply two  LONG
      (32-bit)  fields.   The  first is the address of the drawing  code
      associated  with  the  user  defined object.   The  second  is  an
      arbitrary 32-bit value assigned to the object by your application.

           You can designate objects for conversion to G_USERDEFs in the
      normal fashion by assigning them names which are referenced one by
      one in your initialization code.   You can also combine two tricks
      by using the Extended Type field as a designator for objects to be
      converted to G_USERDEF.  Each tree can then be scanned for objects
      to  be converted.   There is a short code segment in the  download
      which demonstrates this technique.

           My  usual  convention  is to define new  drawing  objects  as
      variants  of  existing objects,  using the Extended Type field  to
      designate the particular variation.   Thus an Extended Type of one
      might designate a G_BUTTON with rounded corners,  while a value of
      two  could  flag  a G_STRING of boldface text.   When  using  this
      technique,  the  RCS can be used to build a rough facsimile of the
      dialog  by inserting the basic object type as  placeholders.   The
      existing  OB_SPEC  information can then be copied  to  the  second
      position in the USERBLK when the object is initialized.

           One final note before moving on:  There is no reason that the
      USERBLK  cannot be extended beyond two fields.   You might want to
      add  extra words to store more information related to drawing  the
      object, such as its original type.

           The  AES will call your drawing code whenever  the  G_USERDEF
      needs  to be drawn.   This occurs when you make an objc_draw  call
      for its tree,  or when an objc_change occurs for that object.   If
      your user-defined object is in a menu drop-drop, then your drawing
      code will be called any time the user exposes that menu.

           Before  getting  into the details of the AES  to  application
      calling  sequence,  some  warnings are in order.   First,  remember
      that your drawing code will execute in the AES' context, using its
      stack.   Therefore,  be careful not to overuse the stack with deep
      recursion, long parameter lists, or large dynamic arrays.  Second,
      the  AES  is NOT re-entrant,  so you may not make ANY calls to  it
      from within a G_USERDEF procedure.   You may,  of course, call the
      VDI.   Finally,  realize  that drawing code associated with a menu
      object may be called by the AES at any time.   Exercise great care
      in  sharing  data  space between such code and  the  rest  of  the
      application!

           When your drawing code is called by the AES, the stack is set
      up  as if a normal procedure call had occured.   There will be one
      parameter  on the stack:  a 32-bit pointer to a PARMBLK structure.
      This structure lies in the AES' data space, so do not write beyond
      its end!

           The  PARMBLK contains 15 words.   The first two are the  long
      address of the object tree being drawn,  and the third word is the
      number of the G_USERDEF object.   You may need these values if the
      same  drawing  code is used for more than one object  at  a  time.
      Words  four  and five contain the previous  and  current  OB_STATE
      values of the object.  If these values are different, your drawing
      code  is  being  called in response  to  an  objc_change  request.
      Otherwise, the active AES call is an objc_draw.

           Words six through nine contain the object's rectangle on  the
      screen.   Remember  that  you cannot call objc_offset  within  the
      drawing code,  so you will need these values!  The next four words
      contain the clipping rectangle specified in the active objc_change
      or objc_draw call.   You should set the VDI clip rectangle to this
      value before doing any output to the screen.

           The last two words in the PARMBLK contain a copy of the extra
      32-bit parameter from the object's USERBLK.   If you have followed
      the  method of copying an OB_SPEC into this location,  these words
      will be your pointer to a string, or BITBLK, or whatever.

           When  your drawing routine is done,  it should return a  zero
      value  to  the AES.   This is a "magic" value;  anything else will
      stop the drawing operation.

           The download contains a sample drawing routine which  defines
      one extended drawing object,  a rounded rectangle button.  You can
      use  this procedure as a starting point for your own User  Defined
      objects.

           PUT ANYTHING YOU WANT ON THE DESKTOP!    In ST PRO GEM #2,  I
      described the use  of  the WF_NEWDESK wind_set  call to substitute
      your own object tree for  the  normal  green  desktop  background.
      If the tree you supply contains User Defined objects, you can draw
      whatever you want on the  desktop!  Some  of  the things you might
      try are free  hand  drawings  imported  in  metafile  format  from
      EasyDraw,  or whole  screen bit images generated by Degas.  If you
      do the latter, you will have to store  the entire image off screen
      and blit parts of it to the display as requested.

           In  any case,  remember that your desktop drawing code can be
      called any time that a window is moved,  so exercise the same care
      as with a menu drawer.   Also, be aware that making the WF_NEWDESK
      call  does  not force an immediate redraw of the desktop.   To  do
      that, do a form_dial(3) call for the entire desktop rectangle.

           THE TOUCHEXIT FLAG. The TOUCHEXIT attribute is an alternative
      to  the  more  usual  EXIT.   When  the TOUCHEXIT bit is set in an
      object's OB_FLAG word,  the  form_do routine will exit immediately
      when the mouse button is pressed with the cursor over the  object.
      Your  code  can immediately take control of the mouse and display,
      without  waiting  for  the release of the button.  This method  is
      used  for  generating effects such as slider bars within otherwise
      normal dialogs.

           The  easiest  way to code a TOUCHEXIT handler is to  place  a
      loop  around the form_do call.   If the object number returned  is
      TOUCHEXIT,  then the animation procedure is called,  followed by a
      resumption   of  the  form_do  (WITHOUT  recalling  form_dial   or
      objc_draw!).   If the object returned is a normal EXIT, the dialog
      is  complete and control flows to the cleanup code.

           There is one idiosyncrasy of TOUCHEXIT which should be noted.
      When the AES "notices" that the mouse button has been pressed over
      a TOUCHEXIT,  it immediately retests the button state.   If it has
      already  been  released,  it  waits to see if  a  double click  is
      performed.  If so, the object number returned by form_do will have
      its  high  bit set.   If you don't care about double clicks,  your
      code should mask off this flag.   However, you may want to use the
      double click to denote some enhanced action.  For example, the GEM
      file selector uses a double click on one of the file name  objects
      to indicate a selection plus immediate exit.

           THE INDIRECT FLAG.  If the INDIRECT bit is set in an object's
      OB_STATE  word,  the  AES interprets the 32-bit OB_SPEC field as a
      pointer to the memory  location  in which the ACTUAL OB_SPEC is to
      be found.   Like  User  Defined  objects,  this  capability is not
      supported by the RCS, so  you  have to set up the INDIRECT bit and
      alter the OB_SPEC at run time.

           The value of INDIRECT is that you can use it to associate  an
      AES  object with other data or code.   The general technique is to
      set  up  a table with a spare 32-bit location  at  its  beginning.
      Then,  when initializing the application's resource,  you move the
      true  OB_SPEC  into  this location,  set the  INDIRECT  flag,  and
      replace the OB_SPEC field with a pointer to the table.  The object
      behaves normally during drawing and form handling. However, if you
      receive  its  number  from  form_do  or  objc_find,  you  have  an
      immediate  pointer to the associated table,  without having to  go
      through a lookup procedure.

           This  technique works well in programs like the GEM  Desktop.
      Each  G_ICON object is set up with INDIRECT.   Its OB_SPEC goes to
      the  beginning of a data area defining the associated  file.   The
      blank  location at the beginning of file table is filled  up  with
      the former OB_SPEC, which points to a ICONBLK.

           You  can also combine INDIRECT with TOUCHEXIT  when  creating
      objects  that  must change when they are clicked by a  user.   For
      instance,  a  color  selection  box  might be linked  to  a  table
      containing  the various OB_SPEC values through which  the  program
      will cycle.   Each time the user clicked on the box, the TOUCHEXIT
      routine would advance the table pointer,  copy the next value into
      the  dummy OB_SPEC location at the front of the table,  and redraw
      the object in its new appearance.

           A  programmer  who wanted to follow a  truly  object-oriented
      "Smalltalkish" approach could use the INDIRECT method to bind  AES
      drawing  object to tables of associated procedures  or  "methods".
      For instance, one procedure could be flagged for use when the user
      clicked  on the object,  one when the object was dragged,  one for
      double-click,  and  so on.   If the table structure was capable of
      indicating  that  the true method was stored in another  table,  a
      rudimentary form of class inheritance could be obtained.

           INSTANT CO-ROUTINES.     We turn to the AES event and message
      system for this  trick.    While  some  languages  like  Modula  2
      provide a method for implementing co-routines,  there  is  no such
      capability in C.  However, we can effectively fake it by using the
      AES  event library.

           As  already  seen in an earlier column,  an  application  can
      write a message to its own event queue using the appl_write  call.
      Usually, this is a redraw message, but there is nothing to prevent
      you from using this facility to send messages from one routine  in
      your program to another.  To set up co-routines using this method,
      they  would  be  coded  as separate  procedures  called  from  the
      application's main event loop.

           When  one  of the co-routines wanted to call  the  other,  it
      would  post  a message containing the request and  any  associated
      parameters into the application's queue and then return.  The main
      loop  would find the message and make the appropriate call to  the
      second co-routine.  If it was necessary to then re-enter the first
      co-routine  at  the  calling point,  the  original  message  could
      contain an imbedded reply message to be sent back when the request
      was  complete.   A  simple switch structure could then be used  to
      resume at the appropriate point.

           There  are two potential problems in using this method.   The
      first is the limited capacity of the application event queue.  The
      queue  contains  eight entries.    While the AES  economizes  this
      space  by  merging redraws and multiple events,  it  cannot  merge
      messages.   Because  of this limit,  you must be extremely careful
      when  one  message received has the potential to generate  two  or
      more  messages sent.   Unless this situation is carefully managed,
      you  can get a sort of "cancer" which will overflow the queue  and
      probably crash your application.

           The second danger involves race conditions.   Message sent by
      the  application  are posted to the end of the  queue.   If  other
      events  have occurred,  such as mouse clicks or keyboard  presses,
      they will be seen and processed ahead of the application generated
      message.   This  implies  that you cannot use this method  if  the
      program must complete its action before a new user generated event
      can be processed.

           THAT'S ALL FOR NOW.   Hopefully  these hints  will  keep  you
      profitably occupied for  a  while.   ST PRO GEM number twelve will
      return to the topic of user interfaces.   Reaction  to  the  first
      article on this  subject was mostly  positive,  but a lot of folks
      wanted to see real code  as  well.   In response to your feedback,
      there will also be code for implemented your own "mouse sensitive"
      objects which highlight when the cursor touches  them.  This  will
      be presented as part of an alternate form manager.

           UPDATE: ATARI ST.  I have recently gotten more information on
     some topics mentioned in earlier articles.   These notes will bring
     you up to date:

           A number of developers reported that they were unable to  get
      the  self-redraw  technique described in ST PRO GEM  #2  to  work.
      This is usually due to a bug in the appl_init binding in Alcyon C.
      The  value  returned from the function,  which would  normally  be
      assigned  to gl_apid,  is coming back as garbage.   To work around
      the problem,  declare EXTERN WORD gl_apid;  in your program and DO
      NOT  assign the value from appl_init.   The binding WILL make  the
      assignment.  A tip of the hat to Russ Wetmore for this report.

           The   last  column  mentioned  that  turning  off  the   clip
      rectangle  while drawing graphics text will speed things  up.   It
      turns  out that the VDI will also run at the non-clipped speed  if
      the  ENTIRE  string  to  be written is  within  the  current  clip
      rectangle.  To compound the problem, there is a one-off bug in the
      detection  algorithm  for  the right  edge.   That  is,  the  clip
      rectangle  has to be one pixel BEYOND the right edge of  the  text
      for the fast write to work.

           The Feedback in ST PRO GEM #10 mentioned that there are known
      bugs  in  the  Alcyon C floating point  library.   In  fact,  this
      library  has been replaced with a new,  debugged version in recent
      shipments  of the Toolkit.   If you need to use floating point and
      have  run into this bug,  you should be able to get an update from
      Atari.   Also,  check  the  Atari  Developer's SIG (PCS-57) for  a
      possible download.

           In addition, it turns out there is an undocumented feature in
      Alcyon  C  which allows you to imbed assembly code  in-line.   Try
      using:

           asm(".....");

      where the dots are replaced with an assembly instruction.  You get
      one instruction per asm(),  one asm() per line.  Thanks to Leonard
      Tramiel for both of the above tidbits.




>>>>>>>>>>>>>>> Sample code for initializing User Objects <<<<<<<<<<<<<<<<

GLOBAL    USERBLK extobjs[MAX_OBJS];    /* APPLBLK defined in OBDEFS.H    */
GLOBAL    WORD    n_extobjs;        /* Set MAX_OBJS to total user   */
                    /* objects in resource        */

    VOID
obj_init()                /* Scan whole resource for user   */
    {                /* objects.  Uses map_tree()      */
    LONG    tree, obspec;        /* from GEMCL5.C          */
    WORD    itree, i, obj;

    n_extobjs = 0;            /* Replace TREE0 with your first  */
                    /* tree, TREEN with the last      */
    for (itree = TREE0; itree <= TREEN; itree++)
        {
        rsrc_gaddr(R_TREE, itree, &tree);
        map_tree(tree, ROOT, NIL, fix_obj);
        }
    }

    WORD
fix_obj(tree, obj)            /* Code to check and fix up    */
    LONG    tree;            /* a user defined object    */
    WORD    obj;
    {
    WORD    hibyte;

    hibyte = LWGET(OB_TYPE(obj)) & 0xff00;        /* check extended */
    if (!hibyte)                    /* type - if none */
        return (TRUE);                /* ignore object  */
    extobjs[n_extobjs].ub_code = dr_code;        /* set drawcode   */
    extobjs[n_extobjs].ub_parm = LLGET(OB_SPEC(obj)); /* copy obspec  */
    LLSET(OB_SPEC(obj), ADDR(&extobjs[n_extobjs]));   /* point obspec */
    LWSET(OB_TYPE(obj), G_USERDEF | hibyte);    /* to userblk &   */
    n_extobjs++;                    /* patch type     */
    return (TRUE);
    }


>>>>>>>>>>>>>>>>>>>>>> Sample User Object Drawing Code <<<<<<<<<<<<<<<<<<<<
>>>>>>>>>>>>>>>>>>>>>> Implements Rounded Box based    <<<<<<<<<<<<<<<<<<<<
>>>>>>>>>>>>>>>>>>>>>> on G_BOX type               <<<<<<<<<<<<<<<<<<<<

    WORD
dr_code(pb)                /* Sample user object drawing   */
    PARMBLK    *pb;            /* code.  Caution: NOT portable */
    {                /* to Intel small data models   */
    LONG    tree, obspec;
    WORD    slct, flip, type, ext_type, flags;
    WORD    pxy[4];
    WORD    bgc, interior, style, bdc, width, chc;

    tree = pb->pb_tree;
    obspec = LLGET(pb->pb_parm);    /* original obspec from USERBLK  */
    ext_type = LHIBT(LWGET(OB_TYPE(pb->pb_obj)));
    slct = SELECTED & pb->pb_currstate;
    flip = SELECTED & (pb->pb_currstate ^ pb->pb_prevstate);
    set_clip(TRUE, &pb->pb_xc);    /* These two routines in GEMCL9.C */
    grect_to_array(&pb->pb_x, pxy);

    switch (ext_type) {
        case 1:            /* Rounded box       */
                    /* Crack color word  */
            get_colrwd(obspec, &bgc, &style, &interior,
                &bdc, &width, &chc);
                    /* For select effect, use char color */
            if (slct)    /* In place of background         */
                bgc = chc;
                    /* Fill in background             */
            rr_fill(MD_REPLACE, (width? 0: 1), bgc, interior,
                style, pxy);
                    /* Do perimeter if needed         */
                    /* rr_perim is in GEMCL9.C         */
            if (width && !flip)
                {
                pxy[0] -= width; pxy[2] += width;
                rr_perim(MD_REPLACE,bdc,FIS_SOLID,width,pxy);
                }
            break;
        default:        /* Add more types here            */
            break;
        }
    return (0);
    }

    VOID                /* Cracks the obspec color word    */
get_colrwd(obspec, bgc, style, interior, bdc, width, chc)
    LONG    obspec;
    WORD    *bgc, *style, *interior, *bdc, *width, *chc, *chmode;
    {
    WORD    colorwd;

    colorwd = LLOWD(obspec);
    *bgc = colorwd & 0xf;
    *style = (colorwd & 0x70) >> 4;
    if ( !(*style) )
        *interior = 0;
    else if (*style == 7)
        *interior = 1;
    else if (colorwd & 0x80)    /* HACK: Uses character writing mode */
        *interior = 3;        /* bit to select alternate interior  */
    else                /* styles!                 */
        *interior = 2;
    *bdc = (colorwd & 0xf000) >> 12;

    *width = LHIWD(obspec) & 0xff;
    if (*width > 127)
        *width = 256 - *width;

    if (*width && !(*width & 0x1))        /* VDI only renders odd */
        (*width)--;            /* widths!        */

    *chc = (colorwd & 0x0f00) >> 8;        /* used for select effect */
    }

    VOID                /* Fill a rounded rectangle    */
rr_fill(mode, perim, color, interior, style, pxy)
    WORD    mode, perim, color, style, interior, *pxy;
    {
    vswr_mode(vdi_handle, mode);
    vsf_color(vdi_handle, color);
    vsf_style(vdi_handle, style);
    vsf_interior(vdi_handle, interior);
    vsf_perimeter(vdi_handle, perim);
    v_rfbox(vdi_handle, pxy);
    }