Contents page

Intuition Tools

Intuition Tools
    There are a bunch of routines that are designed to streamline  working  with

    Gadget Routines

    The InovaTools 1 gadget handling routines all work  with  the  gadget  being
    specified  by its GadgetID, rather than a pointer to the gadget itself. This
    tends to be a lot less messy. You can have  all  your  gadgets  declared  as
    static  structures  in one file, so they are not accessible from the outside
    by name (saving the headache of trying to remember a lot  of  cryptic  names
    and avoiding multiply defined symbols.)

    There are routines that return pointers to Gadget, StringInfo, and  PropInfo
    structures, given a window and a GadgetID:

    gadget = GetGadget(Window,GadgetID);
    propinfo = GetPropInfo(Window,GadgetID);
    stringinfo = GetStringInfo(Window,GadgetID);

    There are routines that initialise, change, and  read  values  from  Gadget,
    StringInfo, and PropInfo structures:

    Number = GetStringInfoNumber(Window,GadgetID,Base);

    All of these functions are documented in detail in the section InovaTools  1

    Reentrant Windows

    If you are writing a program that allows multiple copies of the same  window
    to  open, you run into a problem: Although you can open multiple windows all
    with the same NewWindow structure, the Gadget  lists  for  each  window  are
    identical. If the user does something with a gadget in one window, the other
    windows are affected.

    The only reasonable solution is to make a copy of the Gadget  list  and  the
    NewWindow  structure  for each window copy opened. The gadget lists for each
    window are independent, they can not interfere with each other. Later, after
    each  window is closed, free the copied NewWindow and Gadget structures that
    pertain to it.

    So, there are two routines, one to duplicate a  NewWindow  and  the  Gadgets
    attached to it, the second to delete the duplicates:

    newwindowcopy = DupeNewWindow(NewWindow);

    To use these routines, create a NewWindow structure as you  normally  would.
    But,  rather  than  calling OpenWindow directly with the NewWindow structure
    you designed, first make a duplicate  of  it  with  DupeNewWindow  and  call
    OpenWindow with the duplicate. Later, after you have closed the window, call
    FreeNewWindow to remove it.

    struct NewWindow *newwindowcopy;
    struct Window *window;
    newwindowcopy = DupeNewWindow(&NewWindow);
    window =  OpenWindow(newwindowcopy); /* Do something with the window. */

    By the way, now that you are working with copies of your  gadget  lists,  it
    makes  even  more  sense  to refer to the gadgets by their GadgetID numbers,
    since hard coded addresses can no longer be used.

    These two functions are documented in detail in  the  section  InovaTools  1

    Menu Routines

    As with Gadgets, it's much easier to manipulate Menus and MenuItems  by  id,
    rather  than  name.  Intuition  does  provide such a mechanism with MENUNUM,
    ITEMNUM, and SUBNUM. So, I've added a few routines that think of  Menus  and
    MenuItems this way:

    menu = GetMenu(MenuList,MenuNum);
    menuitem = GetMenuItem(MenuList,Menunum,Itemnum,Subnxxm);

    As with the gadget list, if you plan to have multiple  copies  of  the  same
    window, you should also make multiple copies of the menus.

    There are routines to copy and free menus if you want multiple copies of the
    same menu:

    menulist = DupeMenu(MenuList);

    Reentrant Lists

    You can also make duplicates of ListInfo structures, and free them later:

    listinfo = DupeListInfo(ListInfoSource);

    All other  List routines are documented in the section Lists.

    Cleaning Up

    All of the routines that duplicate and delete NewWindow, Gadget, Menu, and
    other structures  keep  track  of  what has been allocated. The delete
    routines will only delete structures  that  were  allocated  with  the  dupe
    routines. This avoids  the  danger  of  deleting  something that was never
    allocated. For example, you may innocently insert  a  new  gadget  into  the
    gadget  list  for a window that is already opened. It could be dangerous to
    delete that if it was a static structure. So, DeleteNewWindow simply deletes
    all of the other gadgets and leaves the imposter alone.

    Flashy Windows

    There are two routines that embellish the opening and closing of windows:

    window = FlashyOpenWindow(NewWindowStructure);

    Use these as a replacement for OpenWindow and CloseWindow  if  you  want  to
    impress the natives.

    Intuition Event Handling

    There are a few routines  that  make  handling  Intuition  events  a  little

          GetIntuiMessage  Use this routine to get IntuiMessage events from your
                           window.  It  saves  you  the hassle of writing a wait
                           loop with WaitPort and GetMsg in it. It gets annoying
                           when  you  find yourself writing the sasne five or so
                           lines of code at  the  head  of  every  window  event
                           handler. This saves you from that minor frustration.

    GetSelectIntuiMessage  Sometimes, you  may  be  looking  for  only  specific
                           events  and  are happy to throw away other types that
                           you normally receive. Give this routine  your  window
                           and  the IDCMP types you want and it will return with
                           a message of one of those types,  having  replied  to
                           all other events.

       ClearIntuiMessages  This takes care  of  mouse  ahead.  Call  it  and  it
                           empties  the event queue. Sometimes, there may be one
                           particular kind of event you don't want to  ignore. If
                           so, use GetSelectIntuiMessage.

          SendCloseWindow  The easiest and cleanest way to work  with  Intuition
                           is  to spin off a task for each window. However, when
                           it comes time to close down your program, you need to
                           tell each of these windows (and their tasks) to close
                           down. This routine will  simply  send  a  CLOSEWINDOW
                           IntuiMessage event to the specified window.