Contents page

Intuition Tools

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



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:

RefreshGadget(Window,GadgetID);
EnableGadget(Window,GadgetID,Flag);
SelectGadget(Window,GadgetID,Flag);
SetStringInfo(Window,GadgetID,String);
SetStringInfoNumber(Window,GadgetID,Integer,Base);
SetPropInfo(Window,GadgetID,HPos,VPos);
Number = GetStringInfoNumber(Window,GadgetID,Base);

All of these functions are documented in detail in the section InovaTools1 Routines.



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);
FreeNewWindow(newwindowcopy);

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. */
CloseWindow(window);
FreeNewWindow(newwindowcopy);

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 Routines.



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);
EnableMenuItem(MenuList,Menunum,Itemnum,Subnum,Enable);
EnableMenu(MenuList,Menunum,Enable);
CheckMenuItem(MenuList,Menunum,Itemnum,Subnum,Check);

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);
DeleteMenu(MenuList);



Reentrant Lists

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

listinfo = DupeListInfo(ListInfoSource);
DeleteListInfo(listinfo);

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);
FlashyCloseWindow(Window);

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 easier.



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.

---