Intuition Tools
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 InovaTools 1
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.