TABLE OF CONTENTS intuition.library/--boopsi-- intuition.library/ActivateGadget intuition.library/ActivateWindow intuition.library/AddClass intuition.library/AddGadget intuition.library/AddGList intuition.library/AllocRemember intuition.library/AllocScreenBuffer intuition.library/AutoRequest intuition.library/BeginRefresh intuition.library/BitMapInstanceControlA intuition.library/BuildEasyRequestArgs intuition.library/BuildSysRequest intuition.library/ChangeScreenBuffer intuition.library/ChangeWindowBox intuition.library/ClearDMRequest intuition.library/ClearMenuStrip intuition.library/ClearPointer intuition.library/CloseClass intuition.library/CloseScreen intuition.library/CloseWindow intuition.library/CloseWorkBench intuition.library/CurrentTime intuition.library/DirectionVector intuition.library/DisableTemplate intuition.library/DisplayAlert intuition.library/DisplayBeep intuition.library/DisposeObject intuition.library/DoGadgetMethodA intuition.library/DoRender intuition.library/DoScrollHook intuition.library/DoubleClick intuition.library/DrawBorder intuition.library/DrawGradient intuition.library/DrawImage intuition.library/DrawImageState intuition.library/EasyRequestArgs intuition.library/EmbossDisableRect intuition.library/EmbossDisableText intuition.library/EndRefresh intuition.library/EndRequest intuition.library/EndScreenNotify intuition.library/EraseImage intuition.library/FreeClass intuition.library/FreeRemember intuition.library/FreeScreenBuffer intuition.library/FreeScreenDrawInfo intuition.library/FreeSysRequest intuition.library/GadgetBox intuition.library/GadgetMouse intuition.library/GetAttr intuition.library/GetAttrsA intuition.library/GetDefaultPubScreen intuition.library/GetDefPrefs intuition.library/GetGUIAttrsA intuition.library/GetHalfPens intuition.library/GetPrefs intuition.library/GetRenderDomain intuition.library/GetScreenAttr intuition.library/GetScreenAttrsA intuition.library/GetScreenData intuition.library/GetScreenDrawInfo intuition.library/GetWindowAttr intuition.library/GetWindowAttrsA intuition.library/HelpControl intuition.library/HideWindow intuition.library/ICoerceMethodA intuition.library/IDoMethodA intuition.library/IDoSuperMethodA intuition.library/InitRequester intuition.library/IntuiTextExtent intuition.library/IntuiTextLength intuition.library/ISetSuperAttrsA intuition.library/ItemAddress intuition.library/LendMenus intuition.library/LockIBase intuition.library/LockPubScreen intuition.library/LockPubScreenList intuition.library/LockScreen intuition.library/LockScreenGI intuition.library/LockScreenList intuition.library/MakeClass intuition.library/MakeScreen intuition.library/ModifyIDCMP intuition.library/ModifyProp intuition.library/MoveScreen intuition.library/MoveWindow intuition.library/MoveWindowInFrontOf intuition.library/NewModifyProp intuition.library/NewObject intuition.library/NextObject intuition.library/NextPubScreen intuition.library/ObtainBitMapInstanceA intuition.library/ObtainBitMapSourceA intuition.library/ObtainGIRPort intuition.library/ObtainIBackFill intuition.library/OffGadget intuition.library/OffMenu intuition.library/OnGadget intuition.library/OnMenu intuition.library/OpenClass intuition.library/OpenScreen intuition.library/OpenScreenTagList intuition.library/OpenWindow intuition.library/OpenWindowTagList intuition.library/OpenWorkBench intuition.library/PointInImage intuition.library/PrintEmbossedDisabledIText intuition.library/PrintIText intuition.library/PubScreenStatus intuition.library/QueryOverscan intuition.library/RefreshGadgets intuition.library/RefreshGList intuition.library/RefreshSetGadgetAttrsA intuition.library/RefreshWindowFrame intuition.library/ReleaseBitMapInstance intuition.library/ReleaseBitMapSource intuition.library/ReleaseGIRPort intuition.library/ReleaseIBackFill intuition.library/RemakeDisplay intuition.library/RemoveClass intuition.library/RemoveGadget intuition.library/RemoveGList intuition.library/ReportMouse intuition.library/Request intuition.library/ResetMenuStrip intuition.library/RethinkDisplay intuition.library/ScreenDepth intuition.library/ScreenPosition intuition.library/ScreenToBack intuition.library/ScreenToFront intuition.library/ScrollWindowRaster intuition.library/SetAttrsA intuition.library/SetDefaultPubScreen intuition.library/SetDMRequest intuition.library/SetEditHook intuition.library/SetGadgetAttrsA intuition.library/SetGUIAttrsA intuition.library/SetMenuStrip intuition.library/SetMouseQueue intuition.library/SetPointer intuition.library/SetPrefs intuition.library/SetPubScreenModes intuition.library/SetRenderDomain intuition.library/SetScreenAttr intuition.library/SetScreenAttrsA intuition.library/SetWindowAttr intuition.library/SetWindowAttrsA intuition.library/SetWindowPointerA intuition.library/SetWindowTitles intuition.library/ShadeRectA intuition.library/ShowTitle intuition.library/ShowWindow intuition.library/SizeWindow intuition.library/StartScreenNotifyTagList intuition.library/StripIntuiMessages intuition.library/SysReqHandler intuition.library/TimedDisplayAlert intuition.library/UnlockIBase intuition.library/UnlockPubScreen intuition.library/UnlockPubScreenList intuition.library/UnlockScreen intuition.library/UnlockScreenGI intuition.library/UnlockScreenList intuition.library/ViewAddress intuition.library/ViewPortAddress intuition.library/WBenchToBack intuition.library/WBenchToFront intuition.library/WindowLimits intuition.library/WindowToBack intuition.library/WindowToFront intuition.library/ZipWindow intuition.library/--boopsi-- intuition.library/--boopsi-- NAME BOOPSI Public Class Reference INTRODUCTION Intuition provides many public BOOPSI classes which programmers may use to build their application GUIs. Some classes are built into the intuition.library itself. Many more are stored in the SYS:Classes directory tree. CLASS DIAGRAM The following class diagram shows all the public classes available including the relationships between them: [rootclass] | +--arexx.class | +--[imageclass] | | | +--bevel.image | +--bitmap.image | +--drawlist.image | +--[itexticlass] | +--filler.image | +--[fillrectclass] | +--[frameiclass] | +--[gaugeiclass] | +--glyph.image | +--label.image | +--penmap.image | +--[sysiclass] | +--[gadgetclass] | | | +--button.gadget | | | +--[buttongclass] | | | | | +--[frbuttonclass] | | | +--checkbox.gadget | +--chooser.gadget | +--clicktab.gadget | +--colorwheel.gadget | +--datebrowser.gadget | +--diffviewgclass | +--fuelgauge.gadget | +--getcolor.gadget | +--getfile.gadget | +--getfont.gadget | +--getscreenmode.gadget | +--gradientslider.gadget | +--[groupgclass] | +--integer.gadget | +--layout.gadget | +--linecmpgclass | +--listbrowser.gadget | +--page.gadget | +--palette.gadget | +--partitiongclass | +--[propgclass] | +--radiobutton.gadget | +--scroller.gadget | +--[scrollergclass] | +--sketchboard.gadget | +--slider.gadget | +--space.gadget | +--speedbar.gadget | +--string.gadget | +--[strgclass] | +--tapedeck.gadget | +--texteditor.gadget | +--virtual.gadget | +--[menuclass] | +--[icclass] | | | +--[modelclass] | +--[pointerclass] | +--popupmenu.class +--popupmenuitem.class +--requester.class +--window.class The names above are the class IDs embedded in each of the classes and can be used to create an instance of that class with NewObjectA(). Beside each class name is the autodoc file name. Class names enclosed in []'s are built into intuition.library. DESCRIPTION Classes built-in to intuition.library can be referenced by their name alone. Disk based classes should be opened with OpenClass(). Some classes also include interfaces with additional functions which can be accessed using exec.library/GetInterface() using the Class pointer returned by OpenClass(). Each class description can have two sets of methods: new methods that the class defines and inherited methods that the class has modified. Similarly, each class entry can have two sets of attributes: those that the class defines and those that the class inherited and modified. Unless documented otherwise, all classes inherit all of its superclass's methods and attributes. Each method has a BOOPSI message associated with it. These messages are in the form of C structures. Many methods use the default message structure: typedef struct _Msg { uint32 MethodID; } *Msg; Some methods require a customized message so they can pass other parameters besides the Method ID. If a method requires a custom message, its custom message structure is documented along with the method. All methods have to return some sort of return value. The meaning of the return value depends on the class and method. Normally a return value of zero indicates that either the method failed or it is not supported by the class. A method can use the return value to return a pointer to an object. If a class does not directly support a particular method, the class' dispatcher should pass the method on to its superclass for processing. The class dispatcher should record the return value it gets from its superclass and use that as its return value. Methods that assign no meaning to their return value can return 1 to indicate that the method is implemented. All methods are called via a class dispatcher: uint32 classDispatcher(Class *class, Object *object, Msg msg); The first argument, class, is a pointer to the dispatcher's Class structure (defined in ). The second parameter, object, is a pointer to the BOOPSI object to which the BOOPSI message (the third argument, msg) refers. Both Object and Msg are defined in . intuition.library/ActivateGadget intuition.library/ActivateGadget NAME ActivateGadget -- Activate a (string or custom) gadget. SYNOPSIS Success = ActivateGadget( Gadget, Window, Request ) BOOL ActivateGadget( struct Gadget *, struct Window *, struct Requester * ); FUNCTION Activates a string or custom gadget. If successful, this means that the user does not need to click in the gadget before typing. The window parameter must point to the window which contains the gadget. If the gadget is actually in a requester, the window must contain the requester, and a pointer to the requester must also be passed. The requester parameter must only be valid if the gadget has the GTYP_REQGADGET flag set, a requirement for all requester gadgets. The success of this function depends on a rather complex set of conditions. The intent is that the user is never interrupted from what interactions he may have underway. The current set of conditions includes: - The window must be active. If you are opening a new window and want an active gadget in it, it is not sufficient to assume that the WFLG_ACTIVATE flag has taken effect by the time OpenWindow() returns, even if you insert a delay of some finite amount of time. Use the IDCMP_ACTIVEWINDOW IntuiMessage to tell when your window really becomes active. Many programs use an event loop that calls ActivateGadget() whenever they receive the IDCMP_ACTIVEWINDOW message, and also the IDCMP_MOUSEBUTTONS messages, and so on, to keep the gadget active until it is used (or the user selects some other "Cancel" gadget). - No other gadgets may be in use. This includes system gadgets, such as those for window sizing, dragging, etc. - If the gadget is in a requester, that requester must be active. (Use IDCMP_REQSET and IDCMP_REQCLEAR). - The right mouse button cannot be held down (e.g. menus) NOTE: Don't try to activate a gadget which is disabled or not attached to a window or requester. INPUTS Gadget = pointer to the gadget that you want activated. Window = pointer to a window structure containing the gadget. Requester = pointer to a requester (may by NULL if this isn't a requester gadget (i.e. GTYP_REQGADGET is not set)). RESULT If the conditions above are met, and the gadget is in fact a string gadget, then this function will return TRUE, else FALSE. BUGS At present, this function will not return FALSE if a custom gadget declines to be activated. SEE ALSO intuition.library/ActivateWindow intuition.library/ActivateWindow NAME ActivateWindow -- Activate an Intuition window. SYNOPSIS ActivateWindow( Window ) VOID ActivateWindow( struct Window * ); FUNCTION Activates an Intuition window. Note that this call may have its action deferred: you cannot assume that when this call is made the selected window has become active. This action will be postponed while the user plays with gadgets and menus, or sizes and drags windows. You may detect when the window actually has become active by the IDCMP_ACTIVEWINDOW IDCMP message. This call is intended to provide flexibility but not to confuse the user. Please call this function synchronously with some action by the user. Note: windows opened with the { WA_ToolBox, TRUE } property cannot be activated with this function. If you need (for whatever reason) to call ActivateWindow() on such a window, be careful not to wait for the aforementioned IDCMP_ACTIVEWINDOW verification message, or your program will get stuck forever! INPUTS Window = a pointer to a Window structure RESULT None. BUGS Some versions of the documentation claimed that this function had a meaningful return value under V36 and higher. That is not true. Calling this function in a tight loop can blow out Intuition's deferred action queue. SEE ALSO OpenWindow(), and the WFLG_ACTIVATE window flag intuition.library/AddClass intuition.library/AddClass NAME AddClass -- Make a public class available (V36) SYNOPSIS void AddClass(Class *cl); FUNCTION Adds a public BOOPSI class to the internal list of classes available for public consumption. You must call this function after you call MakeClass(). INPUTS cl - pointer returned by MakeClass() BUGS Although there is some protection against creating classes with the same name as an existing class, this function does not do any checking or other dealings with like-named classes. Until this is rectified, only officially registered names can be used for public classes, and there is no "class replacement" policy in effect. SEE ALSO MakeClass(), FreeClass(), RemoveClass() Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/AddGadget intuition.library/AddGadget NAME AddGadget -- Add a gadget to the gadget list of a window. SYNOPSIS RealPosition = AddGadget( Window, Gadget, Position ) UWORD AddGadget( struct Window *, struct Gadget *, UWORD ); FUNCTION Adds the specified gadget to the gadget list of the given window, linked in at the position in the list specified by the position argument (that is, if Position == 0, the gadget will be inserted at the head of the list, and if Position == 1 then the gadget will be inserted after the first gadget and before the second). If the position you specify is greater than the number of gadgets in the list, your gadget will be added to the end of the list. Calling AddGadget() does not cause your gadget to be redisplayed. The benefit of this is that you may add several gadgets without having the gadget list redrawn every time. This procedure returns the position at which your gadget was added. NOTE: A relatively safe way to add the gadget to the end of the list is to specify a position of -1 (i.e., (UWORD) ~0). That way, only the 65536th (and multiples of it) will be inserted at the wrong position. The return value of the procedure will tell you where it was actually inserted. NOTE: The system window gadgets are initially added to the front of the gadget list. The reason for this is: If you position your own gadgets in some way that interferes with the graphical representation of the system gadgets, the system's ones will be "hit" first by user. If you then start adding gadgets to the front of the list, you will disturb this plan, so beware. On the other hand, if you don't violate the design rule of never overlapping your gadgets, there's no problem. NOTE: You may not add your own gadgets to a screen. Gadgets may be added to backdrop windows, however, which can be visually similar, but also provide an IDCMP channel for gadget input messages. INPUTS Window = pointer to the window to get your gadget Gadget = pointer to the new gadget Position = integer position in the list for the new gadget (starting from zero as the first position in the list) RESULT Returns the position of where the gadget was actually added. BUGS SEE ALSO AddGList(), RemoveGadget(), RemoveGList() intuition.library/AddGList intuition.library/AddGList NAME AddGList -- Add a linked list of gadgets to a window or requester. SYNOPSIS RealPosition = AddGList( Window, Gadget, Position, Numgad, Requester ) UWORD AddGList( struct Window *, struct Gadget *, UWORD, WORD, struct Requester * ); FUNCTION Adds the list of gadgets to the gadget list of the given window or requester linked in at the position in the list specified by the position argument. See AddGadget() for more information about gadget list position, and more information about gadgets in general. The requester parameter will be ignored unless the GTYP_REQGADGET bit is set in the GadgetType field of the first gadget in the list. In that case, the gadget list is added to the requester gadgets. NOTE: be sure that GTYP_REQGADGET is either set or cleared consistently for all gadgets in the list. NOTE ALSO: The window parameter should point to the window that the requester (will) appear in. Will add 'Numgad' gadgets from gadget list linked by the field NextGadget, or until some NextGadget field is found to be NULL. Does not assume that the Numgad'th gadget has NextGadget equal to NULL. NOTE WELL: In order to link your gadget list in, the NextGadget field of the Numgad'th (or last) gadget will be modified. Thus, if you are adding the first 3 gadgets from a linked list of five gadgets, this call will sever the connection between your third and fourth gadgets. INPUTS Window = pointer to the window to get your gadget Gadget = pointer to the first gadget to be added Position = integer position in the list for the new gadget (starting from zero as the first position in the list) Numgad = the number of gadgets from the linked list to be added if Numgad equals -1, the entire null-terminated list of gadgets will be added. Requester = the requester the gadgets will be added to if the GTYP_REQGADGET GadgetType flag is set for the first gadget in the list RESULT Returns the position of where the first gadget in the list was actually added. BUGS SEE ALSO AddGadget(), RemoveGadget(), RemoveGList() intuition.library/AllocRemember intuition.library/AllocRemember NAME AllocRemember -- AllocMem() with tracking to make freeing easy. SYNOPSIS MemBlock = AllocRemember( RememberKey, Size, Flags ) APTR AllocRemember( struct Remember **, ULONG, ULONG ); FUNCTION This routine calls the Exec AllocMem() function for you, but also links the parameters of the allocation into a master list, so that you can simply call the Intuition routine FreeRemember() at a later time to deallocate all allocated memory without being required to remember the details of the memory you've allocated. This routine will have two primary uses: - Let's say that you're doing a long series of allocations in a procedure. If any one of the allocations fails, your program may need to abort the procedure. Abandoning ship correctly involves freeing up what memory you've already allocated. This procedure allows you to free up that memory easily, without being required to keep track of how many allocations you've already done, what the sizes of the allocations were, or where the memory was allocated. - Also, in the more general case, you may do all of the allocations in your entire program using this routine. Then, when your program is exiting, you can free it all up at once with a simple call to FreeRemember(). You create the "anchor" for the allocation master list by creating a variable that's a pointer to struct Remember, and initializing that pointer to NULL. This is called the RememberKey. Whenever you call AllocRemember(), the routine actually does two memory allocations, one for the memory you want and the other for a copy of a Remember structure. The Remember structure is filled in with data describing your memory allocation, and it's linked into the master list pointed to by your RememberKey. Then, to free up any memory that's been allocated, all you have to do is call FreeRemember() with your RememberKey. Please read the FreeRemember() function description, too. As you will see, you can select either to free just the link nodes and keep all the allocated memory for yourself, or to free both the nodes and your memory buffers. INPUTS RememberKey = the address of a pointer to struct Remember. Before the very first call to AllocRemember, initialize this pointer to NULL. Size = the size in bytes of the memory allocation. Please refer to the exec.library/AllocMem() function for details. Flags = the specifications for the memory allocation. Please refer to the exec.library/AllocMem() function for details. EXAMPLE struct Remember *RememberKey; RememberKey = NULL; buffer = AllocRemember(&RememberKey, BUFSIZE, MEMF_CHIP); if (buffer) { /* Use the buffer */ ... } FreeRemember(&RememberKey, TRUE); RESULT If the memory allocation is successful, this routine returns the byte address of your requested memory block. Also, the node to your block will be linked into the list pointed to by your RememberKey variable. If the allocation fails, this routine returns NULL and the list pointed to by RememberKey, if any, will be unchanged. BUGS This function makes two allocations for each memory buffer you request. This is neither fast nor good for memory fragmentation. This function should use the exec AllocPool() function internally, at least for the Remember headers. SEE ALSO FreeRemember(), exec.library/AllocMem() intuition.library/AllocScreenBuffer intuition.library/AllocScreenBuffer NAME AllocScreenBuffer -- Get a ScreenBuffer for double-buffering. (V39) SYNOPSIS sbuffer = AllocScreenBuffer( Screen, BitMap, flags ) struct ScreenBuffer *AllocScreenBuffer( struct Screen *, struct BitMap *, ULONG ); FUNCTION Allocates a ScreenBuffer structure and usually a BitMap. This structure can be used for double (or multiple) buffering in Intuition screens. You may use this call to obtain a ScreenBuffer structure for the screen's initial BitMap, or for other BitMaps you intend to swap in. AllocScreenBuffer() also allocates a graphics.library DBufInfo structure. The ScreenBuffer structure this call returns contains a pointer to that DBufInfo structure, which is free for your use. See graphics.library/AllocDBufInfo() for full details on using this structure to achieve notification of when it is safe to render into an old buffer and when it is right to switch again. INPUTS Screen = pointer to the screen to double-buffer BitMap = For CUSTOMBITMAP screens, you may pre-allocate a BitMap matching the screen's BitMap's properties, and pass that in, to get a ScreenBuffer referring to that BitMap. Set this parameter to NULL if you'd prefer that Intuition allocate the alternate buffer. This parameter must be NULL for non-CUSTOMBITMAP screens. Flags = Set a combination of these flags: For non-CUSTOMBITMAP screens, set SB_SCREEN_BITMAP in order to get a ScreenBuffer referring to the screen's actual BitMap. (For CUSTOMBITMAP screens, just set the BitMap parameter to the BitMap you passed to OpenScreen()). Set SB_COPY_BITMAP if you would like the screen's BitMap copied into this ScreenBuffer's BitMap. This is required to get any menu-bar or gadget imagery into each ScreenBuffer's BitMap. If the screen has no Intuition rendering, you may omit this flag. Also, when allocating a ScreenBuffer for the screen's initial BitMap, this flag should not be set. RESULT Pointer to a valid ScreenBuffer structure, or NULL if failure. You may render into the resulting BitMap as appropriate. You may use the sb_DBufInfo field to access graphics.library ViewPort-buffering features such as learning when it is safe to reuse the previous BitMap. If not, you risk writing into the on-screen BitMap, which can damage menu or gadget rendering! NOTES The role of SB_SCREEN_BITMAP is to wrap a ScreenBuffer around the actual current BitMap used by the non-CUSTOMBITMAP screen. The words actual or current are used instead of initial, since an application could do some double-buffering, leave the non-initial buffer installed into the screen, free up the others, then re-allocate ScreenBuffer structures to do more double-buffering. In that case, the actual screen BitMap is not necessarily the initial one. The role of SB_COPY_BITMAP is to say "please put whatever imagery is currently on-screen into this new BitMap too". That's how the screen titlebar and other imagery get copied over into each buffer. BUGS SEE ALSO FreeScreenBuffer(), ChangeScreenBuffer(), graphics.library/AllocDBufInfo(), graphics.library/ChangeVPBitMap() intuition.library/AutoRequest intuition.library/AutoRequest NAME AutoRequest -- Automatically build and get response from a requester. SYNOPSIS Response = AutoRequest( Window, BodyText, PosText, NegText, PosFlags, NegFlags, Width, Height ) BOOL AutoRequest( struct Window *, struct IntuiText *, struct IntuiText *, struct IntuiText *, ULONG, ULONG, WORD, WORD ); FUNCTION This procedure automatically builds a requester for you and then waits for a response from the user, or for the system to satisfy your request. If the response is positive, this procedure returns TRUE. If the response is negative, this procedure returns FALSE. An IDCMPFlag specification is created by bitwise "or'ing" your PosFlags, NegFlags, and the IDCMP classes IDCMP_GADGETUP and IDCMP_RAWKEY. You may specify zero flags for either the PosFlags or NegFlags arguments. The IntuiText arguments, and the width and height values, are passed directly to the BuildSysRequest() procedure along with your window pointer and the IDCMP flags. Please refer to BuildSysRequest() for a description of the IntuiText that you are expected to supply when calling this routine. It's an important but long-winded description that need not be duplicated here. If the BuildSysRequest() procedure does not return a pointer to a window, it will return TRUE or FALSE (not valid structure pointers) instead, and these BOOL values will be returned to you immediately. On the other hand, if a valid window pointer is returned, that window will have had its IDCMP ports and flags initialized according to your specifications. AutoRequest() then waits for IDCMP messages on the UserPort, which satisfies one of four requirements: - either the message is of a class that matches one of your PosFlags arguments (if you've supplied any), in which case this routine returns TRUE. Or - the message class matches one of your NegFlags arguments (if you've supplied any), in which case this routine returns FALSE. Or - the IDCMP message is of class IDCMP_GADGETUP, which means that one of the two gadgets, as provided with the PosText and NegText arguments, was selected by the user. If the TRUE gadget was selected, TRUE is returned. If the FALSE gadget was selected, FALSE is returned. - Lastly, two IDCMP_RAWKEY messages may satisfy the request: those for the V and B keys with the left Amiga key depressed. These keys, satisfy the gadgets on the left or right side of the requester--TRUE or FALSE--, respectively. NOTE: For V36, these two keys left-Amiga-B and V are processed through the default keymap. When the dust has settled, this routine calls FreeSysRequest() if necessary to clean up the requester and any other allocated memory. NOTE: For V36, this function now switches the processor stack to ensure sufficient stack space for the function to succeed. INPUTS Window = pointer to a Window structure. See BuildSysRequest() for a full discussion. BodyText = pointer to an IntuiText structure PosText = pointer to an IntuiText structure, may by NULL. NegText = pointer to an IntuiText structure, MUST be valid! PosFlags = flags for the IDCMP NegFlags = flags for the IDCMP Width, Height = the sizes to be used for the rendering of the requester NOTE for V36: The width and height parameters are ignored, as are several other specifications in the IntuiText, to make AutoRequest() requesters retroactively conform to the new look designed for EasyRequest(). RESULT The return value is either TRUE or FALSE. See the text above for a complete description of the chain of events that might lead to either of these values being returned. NOTES When DOS brings up AutoRequests() on your process (eg. "Please insert volume XXX in any drive", they normally come up on the Workbench screen. If you set your Process pr_WindowPtr field to point to one of your windows, then DOS will bring its requesters up on the same screen as that window. A pr_WindowPtr of -1 prevents requesters from coming up at all. (Some FileSystem requesters cannot be redirected or supressed). BUGS The requester no longer devolves into a call to DisplayAlert() if there is not enough memory for the requester. SEE ALSO EasyRequestArgs(), BuildSysRequest(), SysReqHandler() intuition.library/BeginRefresh intuition.library/BeginRefresh NAME BeginRefresh -- Sets up a window for optimized refreshing. SYNOPSIS BeginRefresh( Window ) VOID BeginRefresh( struct Window * ); FUNCTION This routine sets up your window for optimized refreshing. Its role is to provide Intuition integrated access to the Layers library function BeginUpdate(). Its additional contribution is to be sure that locking protocols for layers are followed, by locking both layers of a WFLG_GIMMEZEROZERO window only after the parent Layer_Info has been locked. Also, the WFLG_WINDOWREFRESH flag is set in your window, for your information. The purpose of BeginUpdate(), and hence BeginRefresh(), is to restrict rendering in a window (layer) to the region that needs refreshing after an operation such as window sizing or uncovering. This restriction to the "damage region" persists until you call EndRefresh(). For instance, if you have a WFLG_SIMPLE_REFRESH window which is partially concealed and the user brings it to the front, you can receive an IDCMP_REFRESHWINDOW message asking you to refresh your display. If you call BeginRefresh() before doing any of the rendering, then the layer that underlies your window will be arranged so that the only rendering that will actually take place will be that which goes to the newly-revealed areas. This is very performance- efficient, and visually attractive. After you have performed your refresh of the display, you should call EndRefresh() to reset the state of the layer and the window. Then you may proceed with rendering to the entire window as usual. You learn that your window needs refreshing by receiving either a message of class IDCMP_REFRESHWINDOW through the IDCMP, or an input event of class IECLASS_REFRESHWINDOW through the Console device. Whenever you are told that your window needs refreshing, you should call BeginRefresh() and EndRefresh() to clear the refresh-needed state, even if you don't plan on doing any rendering. You may relieve yourself of even this burden by setting the WFLG_NOCAREREFRESH flag when opening your window. NOTES WARNING: You should only perform simple graphics refreshing operations between BeginRefresh() and EndRefresh(). These include any graphics.library drawing functions or the simple Intuition rendering functions (DrawImage(), PrintIText(), DrawBorder(), and so on). In particular, do not call RefreshGadgets(), RefreshGList(), RefreshWindowFrame(), etc., since any of the complex Intuition functions run the risk of creating a deadlock. Also avoid any other high-level calls in Intuition or ones that might invoke Intuition. This means no calling SetPointer(), no calling LockIBase(), no dos.library functions (since an EasyRequest() might result), etc. Keep it simple. By the time the application receives its IDCMP_REFRESHWINDWOW message, Intuition has already repaired any damaged regions of the window border or the gadgets in the window, so attempts to redraw gadgets or borders are as unnecessary as they are dangerous. ANOTHER WARNING: The concept of multiple refresh passes using EndRefresh( w, FALSE ) is not completely sound without further protection. The reason is that between two sessions, more damage can occur to your window. Your final EndRefresh( w, TRUE ) will dispose of all damage, including the new, and your initial refreshing pass will never get the chance to refresh the new damage. To avoid this, you must protect your session using LockLayerInfo() which will prevent Intuition from performing window operations or anything else which might cause further damage from occurring. Again, while holding the LayerInfo lock make no Intuition function calls dealing with gadgets; just render. You can, however, call InstallClipRegion() for the different refresh passes, if you have two clip regions. SIMILAR WARNING: Your program and Intuition "share" your window layer's DamageList. BeginRefresh() helps arbitrate this sharing, but the lower-level function layers.library/BeginUpdate() does not. It isn't really supported to use BeginUpdate() on a window's layer, but if you do--for whatever reason--it is critical that you first acquire the LayerInfo lock as in the above example: even if you only have one pass of refresh rendering to do. Otherwise, the refreshing of your window's borders and gadgets can be incomplete, and the problem might occur only under certain conditions of task priority and system load. EXAMPLE Code fragment for "two pass" window refreshing, in response to an IDCMP_REFRESHWINDOW message: switch ( imsg->Class ) { ... case IDCMP_REFRESHWINDOW: window = imsg->IDCMPWindow; /* this lock only needed for "two-pass" refreshing */ LockLayerInfo( &window->WScreen->LayerInfo ); /* refresh pass for region 1 */ origclip = InstallClipRegion( window->WLayer, region1 ); BeginRefresh( window ); myRefreshRegion1( window ); EndRefresh( window, FALSE ); /* refresh pass for region 2 */ InstallClipRegion( window->WLayer, region2 ); BeginRefresh( window ); myRefreshRegion2( window ); EndRefresh( window, TRUE ); /* and dispose damage list */ /* restore and unlock */ InstallClipRegion( window->WLayer, origclip ); UnlockLayerInfo( &window->WScreen->LayerInfo ); break; ... } INPUTS Window = pointer to the window structure which needs refreshing RESULT None BUGS This function should check the return code of layers.library/BeginUpdate(), and abort if that function fails. SEE ALSO EndRefresh(), layers.library/BeginUpdate(), OpenWindow() layer.library/InstallClipRegion(), layers.library/LockLayerInfo() The "Windows" chapter of the Intuition Reference Manual intuition.library/BitMapInstanceControlA intuition.library/BitMapInstanceControlA NAME BitMapInstanceControlA -- Set and get bitmap instance attributes. (V50) BitMapInstanceControl -- Varargs stub for BitMapInstanceControlA(). (V50) SYNOPSIS Result = BitMapInstanceControlA( Instance, TagList ) ULONG BitMapInstanceControlA( APTR, struct TagItem * ); Result = BitMapInstanceControl( Instance, Tag1, ... ) ULONG BitMapInstanceControl( APTR, Tag, ... ); FUNCTION This function can be used to change or inquire the attributes of a "bitmap instance" object returned by ObtainBitMapInstanceA(). You can only change attributes of bitmap instances obtained in exclusive mode, whereas reading is always allowed. The attributes are passed to this function as a list of tag items, defined in . When inquiring an attribute, the ti_Data field of the corresponding tag item must be a pointer to a longword-sized variable where the requested attribute value will be stored. INPUTS Instance = abstract handle to a bitmap instance object TagList = pointer to an array of tags specifying the attributes to be read or modified TAGS These are the tags defined for BitMapInstanceControlA() as of V50: BMICTRL_GetBitMap - (struct BitMap **) Get the actual bitmap's address. BMICTRL_GetHook - (struct Hook **) Get the backfill hook's address. BMICTRL_GetOffsets - (ULONG *) Get the backfill offsets, packed in a single longword. BMICTRL_SetOffsets - (ULONG) Set the backfill offsets, packed in a single longword; this ONLY applies to instances allocated in exclusive mode. BMICTRL_GetWidth - (ULONG *) Get the width of the bitmap. BMICTRL_GetHeight - (ULONG *) Get the height of the bitmap. BMICTRL_GetBrightBitMap - (struct BitMap **) Get the address of the bright-level bitmap (if any). This is the bitmap that's used by the instance's backfill hook when Intuition needs to render bright details of a backfilled pseudo-3D shape. BMICTRL_GetHalfBrightBitMap - (struct BitMap **) Get the address of the half-bright-level bitmap (if any). This is the bitmap that's used by the instance's backfill hook when Intuition needs to render half-bright details of a backfilled pseudo-3D shape. BMICTRL_GetHalfDarkBitMap - (struct BitMap **) Get the address of the half-dark-level bitmap (if any). This is the bitmap that's used by the instance's backfill hook when Intuition needs to render half-dark details of a backfilled pseudo-3D shape. BMICTRL_GetDarkBitMap - (struct BitMap **) Get the address of the dark-level bitmap (if any). This is the bitmap that's used by the instance's backfill hook when Intuition needs to render dark details of a backfilled pseudo-3D shape. BMICTRL_GetMaskBitMap - (struct BitMap **) Get the address of the instance's single-plane mask bitmap (if any). BMICTRL_GetOutlineBitMap - (struct BitMap **) Get the address of the instance's single-plane outline bitmap (if any). BMICTRL_GetShineMap - (UBYTE **) Get the address of the instance's bright shading alpha map array (if any). BMICTRL_GetShadowMap - (UBYTE **) Get the address of the instance's dark shading alpha map array (if any). BMICTRL_GetAlphaMap - (UBYTE **) Get the address of the instance's alpha blending map array (if any). BMICTRL_GetOutlineMap - (UBYTE **) Get the address of the instance's outline alpha map array (if any). BMICTRL_GetShadeMaskBitMap - (struct BitMap **) Get the address of the instance's single-plane shade mask bitmap (if any). BMICTRL_GetScreen - (struct Screen **) Get the address of the reference screen of the instance (may be NULL). BMICTRL_GetBitMapSource - (APTR *) Get the address of the bitmap source the instance was obtained from (may be NULL). BMICTRL_GetGradientSpec - (GRADSPEC **) Get the address of the gradient specification of the instance (if any). BMICTRL_SetGradientSpec - (GRADSPEC *) Set a gradient specification for the instance; this ONLY applies to instances allocated in exclusive mode. [NOT IMPLEMENTED YET] BMICTRL_GetReferencePen - (ULONG *) Get the instance's reference pen index. BMICTRL_SetReferencePen - (ULONG) Set the instance's reference pen index; this ONLY applies to instances allocated in exclusive mode. EXAMPLES /* Read the address of the actual bitmap of a bitmap instance */ struct BitMap *bitmap; BitMapInstanceControl(myinstance,BMICTRL_GetBitMap,&bitmap,TAG_END); RESULT The number of attributes successfully processed. NOTES SEE ALSO ObtainBitMapInstanceA() intuition.library/BuildEasyRequestArgs intuition.library/BuildEasyRequestArgs NAME BuildEasyRequestArgs -- Simple creation of system request. (V36) BuildEasyRequest -- Varargs stub for BuildEasyRequestArgs(). (V36) SYNOPSIS ReqWindow = BuildEasyRequestArgs( RefWindow, easyStruct, IDCMP, Args ) struct Window *BuildEasyRequestArgs( struct Window *, struct EasyStruct *, ULONG, APTR ); ReqWindow = BuildEasyRequest( RefWindow, easyStruct, IDCMP, Arg1, ... ) struct Window *BuildEasyRequest( struct Window *, struct EasyStruct *, ULONG, APTR, ... ); FUNCTION This function is to EasyRequest() as BuildSysRequest() is to AutoRequest(): it returns a pointer to the system requester window. The input from that window can then be processed under application control. It is recommended that this processing be done with SysReqHandler(), so that future enhancement to the processing will be enjoyed. After you have determined that the requester is satisfied or cancelled, you must free this requester using FreeSysRequest(). Please see the autodoc for EasyRequest(). NOTE: This function switches the processor stack to ensure sufficient stack space for the function to complete. INPUTS Window = reference window for requester: determines the requester window title and screen. As of V50, the screen can also be specified in the EasyStruct structure (see EasyRequest() autodoc). easyStruct = pointer to EasyStruct structure, as described in the EasyRequest() autodocs. IDCMP = (NOT A POINTER) provided application specific IDCMP flags for the system requester window. Args = see EasyRequestArgs() RESULT A pointer to the system request window opened. In the event of problems, you may also be returned the value '0' which is to be interpreted as the "FALSE, Cancel" choice, or (if you have a second gadget defined) the value '1', which is to be taken to mean the equivalent of your corresponding left-most gadget. If there is a problem creating the window, a recoverable alert may be substituted for the requester, and the result, either 0 or 1, returned. BUGS Does not put up alternative alert. See also BUGS listed for EasyRequestArgs(). SEE ALSO EasyRequestArgs(), FreeSysRequest(), SysReqHandler(), BuildSysRequest(), AutoRequest() intuition.library/BuildSysRequest intuition.library/BuildSysRequest NAME BuildSysRequest -- Build and display a system requester. SYNOPSIS ReqWindow = BuildSysRequest( Window, BodyText, PosText, NegText, IDCMPFlags, Width, Height ) struct Window *BuildSysRequest( struct Window *, struct IntuiText *, struct IntuiText *, struct IntuiText *, ULONG, WORD, WORD ); FUNCTION This procedure builds a system requester based on the supplied information. If all goes well and the requester is constructed, this procedure returns a pointer to the window in which the requester appears. That window will have its IDCMP initialized to reflect the flags found in the IDCMPFlags argument. You may then wait on those ports to detect the user's response to your requester, which response may include either selecting one of the gadgets or causing some other event to be noticed by Intuition (like IDCMP_DISKINSERTED, for instance). After the requester is satisfied, you should call the FreeSysRequest() procedure to remove the requester and free up any allocated memory. See the autodoc for SysReqHandler() for more information on the how to handle the IntuiMessages this window will receive. The requester used by this function has the NOISYREQ flag bit set, which means that the set of IDCMPFlags that may be used here include IDCMP_RAWKEY, IDCMP_MOUSEBUTTONS, and others. In release previous to V36, if the requester could not be built, this function would try to call DisplayAlert() with the same information, with more or less favorable results. In V36, the requesters themselves require less memory (SIMPLEREQ), but there is no alert attempt. The function may return TRUE (1) or FALSE if it cannot post the requester. (V36 will always return FALSE, but be sure to test for TRUE in case somebody reinstates the fallback alert.) If the window argument you supply is equal to NULL, a new window will be created for you in the Workbench screen, or the default public screen, for V36. If you want the requester created by this routine to be bound to a particular window (i.e., to appear in the same screen as the window), you should not supply a window argument of NULL. New for V36: if you pass a NULL window pointer, the system requester will appear on the default public screen, which is not always the Workbench. The text arguments are used to construct the display. Each is a pointer to an instance of the structure IntuiText. The BodyText argument should be used to describe the nature of the requester. As usual with IntuiText data, you may link several lines of text together, and the text may be placed in various locations in the requester. This IntuiText pointer will be stored in the ReqText variable of the new requester. The PosText argument describes the text that you want associated with the user choice of "Yes, TRUE, Retry, Good." If the requester is successfully opened, this text will be rendered in a gadget in the lower-left of the requester, which gadget will have the GadgetID field set to TRUE. If the requester cannot be opened and the DisplayAlert() mechanism is used, this text will be rendered in the lower-left corner of the alert display with additional text specifying that the left mouse button will select this choice. This pointer can be set to NULL, which specifies that there is no TRUE choice that can be made. The NegText argument describes the text that you want associated with the user choice of "No, FALSE, Cancel, Bad." If the requester is successfully opened, this text will be rendered in a gadget in the lower-right of the requester, which gadget will have the GadgetID field set to FALSE. If the requester cannot be opened and the DisplayAlert() mechanism is used, this text will be rendered in the lower-right corner of the alert display with additional text specifying that the right mouse button will select this choice. This pointer cannot be set to NULL. There must always be a way for the user to cancel this requester. The Positive and Negative Gadgets created by this routine have the following features: - GTYP_BOOLGADGET - GACT_RELVERIFY - GTYP_REQGADGET - GACT_TOGGLESELECT When defining the text for your gadgets, you may find it convenient to use the special constants used by Intuition for the construction of the gadgets. These include defines like AUTODRAWMODE, AUTOLEFTEDGE, AUTOTOPEDGE and AUTOFRONTPEN. You can find these in your local intuition.h (or intuition.i) file. These hard-coded constants are not very resolution or font sensitive, but V36 will override them to provide more modern layout. New for V36, linked lists of IntuiText are not correctly supported for gadget labels. The width and height values describe the size of the requester. All of your BodyText must fit within the width and height of your requester. The gadgets will be created to conform to your sizes. VERY IMPORTANT NOTE: for this release of this procedure, a new window is opened in the same screen as the one containing your window. Future alternatives may be provided as a function distinct from this one. NOTE: This function will pop the screen the requester and its window appears in to the front of all screens. New for V36, if the user doesn't perform any other screen arrangement before finishing with the requester, a popped screen will be pushed back behind. INPUTS Window = pointer to a Window structure BodyText = pointer to an IntuiText structure PosText = pointer to an IntuiText structure NegText = pointer to an IntuiText structure IDCMPFlags = the IDCMP flags you want used for the initialization of the IDCMP of the window containing this requester Width, Height = the size required to render your requester NOTE for V36: the width and height you pass are ignored, as are some of the parameters of your IntuiText, so that Intuition can make the Requesters real nice for the new look. RESULT If the requester was successfully created, the value returned by this procedure is a pointer to the window in which the requester is rendered. If the requester could not be created, this routine might have called DisplayAlert() before returning (it depends on the version) and will pass back TRUE if the user pressed the left mouse button and FALSE if the user pressed the right mouse button. If the version of Intuition doesn't call DisplayAlert(), or if it does, and there's not enough memory for the alert, the value of FALSE is returned. BUGS This procedure currently opens a window in the Screen which contains the window which is passed as a parameter, or the default public screen, if that parameter is NULL. Although not as originally envisioned, this will probably always be the behavior of this function. DisplayAlert() is not called in version V36. It's almost impossible to make complete, correct account of different system fonts, window border dimensions, and screen resolution to get the layout of a System Requester just right using this routine. For V36, we recommend the automatic layout implemented in BuildEasyRequestArgs() and EasyRequestArgs(). SEE ALSO FreeSysRequest(), DisplayAlert(), ModifyIDCMP(), exec.library/Wait(), Request(), AutoRequest(), EasyRequestArgs(), BuildEasyRequestArgs() intuition.library/ChangeScreenBuffer intuition.library/ChangeScreenBuffer NAME ChangeScreenBuffer -- Swap the screen's BitMap. (V39) SYNOPSIS success = ChangeScreenBuffer( Screen, ScreenBuffer ) ULONG ChangeScreenBuffer( struct Screen *, struct ScreenBuffer * ); FUNCTION Performs double (or multiple) buffering on an Intuition screen in an Intuition-cooperative manner. The BitMap associated with the supplied ScreenBuffer will be installed in the specified screen, if possible. The previously-installed BitMap is available for re-use upon receiving a signal from graphics.library. See the graphics.library autodocs for graphics.library/AllocDBufInfo() and graphics.library/ChangeVPBitMap() for details. INPUTS Screen: pointer to the screen whose bitmap is to be swapped. ScreenBuffer: pointer to a ScreenBuffer structure obtained from AllocScreenBuffer(). RESULT Returns non-zero if the operation succeeded. Returns zero if the operation cannot be performed. This function will fail if Intuition's state cannot permit it, for example the user is playing with menus or gadgets. NOTES It is not required to restore the original ScreenBuffer before closing the screen. Simply FreeScreenBuffer() each buffer (including the original and the currently-installed one) then close the screen. Of course, you cannot call ChangeScreenBuffer() after freeing the currently-installed one. BUGS SEE ALSO AllocScreenBuffer(), FreeScreenBuffer(), graphics.library/ChangeVPBitMap() intuition.library/ChangeWindowBox intuition.library/ChangeWindowBox NAME ChangeWindowBox -- Change window position and dimensions. (V36) SYNOPSIS ChangeWindowBox( Window, Left, Top, Width, Height ) VOID ChangeWindowBox( struct Window *, WORD, WORD, WORD, WORD ); FUNCTION Makes simultaneous changes in window position and dimensions, in absolute (not relative) coordinates. Like MoveWindow() and SizeWindow(), the effect of this function is deferred until the next input comes along. Unlike these functions, ChangeWindowBox() specifies absolute window position and dimensions, not relative. This makes for more reliable results considering that the action is deferred, so this function is typically preferable to MoveWindow() and SizeWindow() paired. You can detect that this operation has completed by receiving the IDCMP_CHANGEWINDOW IDCMP message The dimensions are limited to legal range, but you should still take care to specify sensible inputs based on the window's dimension limits and the size of its screen. This function limits the position and dimensions to legal values. INPUTS Window = the window to change position/dimension Left, Top, Width, Height = new position and dimensions RESULT Position and dimension are changed to your specification, or as close as possible. Returns nothing. BUGS SEE ALSO MoveWindow(), SizeWindow(), ZipWindow(), layers.library/MoveSizeLayer() intuition.library/ClearDMRequest intuition.library/ClearDMRequest NAME ClearDMRequest -- Clear (detaches) the DMRequest of the window. SYNOPSIS Response = ClearDMRequest( Window ) BOOL ClearDMRequest( struct Window * ); FUNCTION Attempts to clear the DMRequest from the specified window, that is detaches the special requester that you attach to the double-click of the menu button which the user can then bring up on demand. This routine WILL NOT clear the DMRequest if it's active (in use by the user). The IDCMP message class IDCMP_REQCLEAR can be used to detect that the requester is not in use, but that message is sent only when the last of perhaps several requesters in use in a window is terminated. INPUTS Window = pointer to the window from which the DMRequest is to be cleared. RESULT If the DMRequest was not currently in use, detaches the DMRequest from the window and returns TRUE. If the DMRequest was currently in use, doesn't change anything and returns FALSE. BUGS SEE ALSO SetDMRequest(), Request() intuition.library/ClearMenuStrip intuition.library/ClearMenuStrip NAME ClearMenuStrip -- Clear (detach) the menu strip from the window. SYNOPSIS ClearMenuStrip( Window ) VOID ClearMenuStrip( struct Window * ); FUNCTION Detaches the current menu strip from the window; menu strips are attached to windows using the SetMenuStrip() function (or, for V36, ResetMenuStrip() ). If the menu is in use (for that matter if any menu is in use) this function will block (Wait()) until the user has finished. Call this function before you make any changes to the data in a Menu or MenuItem structure which is part of a menu strip linked into a window. INPUTS Window = pointer to a window structure RESULT None BUGS SEE ALSO SetMenuStrip(), ResetMenuStrip() intuition.library/ClearPointer intuition.library/ClearPointer NAME ClearPointer -- Clear the mouse pointer definition from a window. SYNOPSIS ClearPointer( Window ) VOID ClearPointer( struct Window * ); FUNCTION Clears the window of its own definition of the Intuition mouse pointer. After calling ClearPointer(), every time this window is the active one the default Intuition pointer will be the pointer displayed to the user. If your window is the active one when this routine is called, the change will take place immediately. Custom definitions of the mouse pointer which this function clears are installed by a call to SetPointer(). INPUTS Window = pointer to the window to be cleared of its pointer definition RESULT None BUGS SEE ALSO SetWindowPointerA(), SetPointer() intuition.library/CloseClass intuition.library/CloseClass NAME CloseClass -- Close a class previously opened by OpenClass(). (V50) SYNOPSIS void CloseClass(struct ClassLibrary *base); FUNCTION Closes a class that was previously opened by OpenClass(). INPUTS base - The ClassLibrary pointer as returned by OpenClass(). Safe to call with a NULL pointer. SEE ALSO OpenClass() intuition.library/CloseScreen intuition.library/CloseScreen NAME CloseScreen -- Close an Intuition screen. SYNOPSIS Success = CloseScreen( Screen ) BOOL CloseScreen( struct Screen * ); /* returns BOOL in V36 and greater */ FUNCTION Unlinks the screen, unlinks the viewport, deallocates everything that Intuition allocated when the screen was opened (using OpenScreen()). Doesn't care whether or not there are still any windows attached to the screen. Doesn't try to close any attached windows; in fact, ignores them altogether (but see below for changes in V36). If this is the last screen to go, attempts to reopen Workbench. New for V36: this function will refuse to close the screen if there are windows open on the screen or if there are any outstanding screen locks (see LockPubScreen()) when CloseScreen() is called. This avoids the almost certain crash when a screen is closed out from under a window. INPUTS Screen = pointer to the screen to be closed. RESULT New for V36: returns TRUE (1) if screen is closed, returns FALSE (0) if screen had open windows when called. BUGS SEE ALSO OpenScreen() intuition.library/CloseWindow intuition.library/CloseWindow NAME CloseWindow -- Close an Intuition window. SYNOPSIS CloseWindow( Window ) VOID CloseWindow( struct Window * ); FUNCTION Closes an Intuition window. Unlinks it from the system, deallocates its memory, and makes it disappear. When this function is called, all IDCMP messages which have been sent to your window are deallocated. If the window had shared a message Port with other windows, you must be sure that there are no unreplied messages for this window in the message queue. Otherwise, your program will try to make use of a linked list (the queue) which contains free memory (the old messages). This will give you big problems. See the code fragment CloseWindowSafely(), below. NOTE: If you have added a Menu strip to this Window (via a call to SetMenuStrip()) you must be sure to remove that Menu strip (via a call to ClearMenuStrip()) before closing your Window. NOTE: This function may block until it is safe to de-link and free your window. Your program may thus be suspended while the user plays with gadgets, menus, or window sizes and position. New for V36: If your window is a "Visitor Window" (see OpenWindow) CloseWindow will decrement the "visitor count" in the public screen on which the window was open. When the last visitor window is closed, a signal will be sent to the public screen task, if this was pre-arranged (see OpenScreen). New for V50: CloseWindow() can be turned into CloseWindowSafely() (see below) by specifying WA_UserPort when creating the window. See OpenWindow() for more. INPUTS Window = a pointer to a Window structure. As of V50 passing NULL is safe. RESULT None BUGS SEE ALSO OpenWindow(), OpenScreen(), CloseScreen() EXAMPLE /* CloseWindowSafely */ /* these functions close an Intuition window * that shares a port with other Intuition * windows or IPC customers. * * We are careful to set the UserPort to * null before closing, and to free * any messages that it might have been * sent. */ #include "exec/types.h" #include "exec/nodes.h" #include "exec/lists.h" #include "exec/ports.h" #include "intuition/intuition.h" CloseWindowSafely( win ) struct Window *win; { /* we forbid here to keep out of race conditions with Intuition */ Forbid(); /* send back any messages for this window * that have not yet been processed */ StripIntuiMessages( win->UserPort, win ); /* clear UserPort so Intuition will not free it */ win->UserPort = NULL; /* tell Intuition to stop sending more messages */ ModifyIDCMP( win, 0L ); /* turn multitasking back on */ Permit(); /* and really close the window */ CloseWindow( win ); } /* remove and reply all IntuiMessages on a port that * have been sent to a particular window * (note that we don't rely on the ln_Succ pointer * of a message after we have replied it) */ StripIntuiMessages( mp, win ) struct MsgPort *mp; struct Window *win; { struct IntuiMessage *msg; struct Node *succ; msg = (struct IntuiMessage *) mp->mp_MsgList.lh_Head; while( succ = msg->ExecMessage.mn_Node.ln_Succ ) { if( msg->IDCMPWindow == win ) { /* Intuition is about to free this message. * Make sure that we have politely sent it back. */ Remove( msg ); ReplyMsg( msg ); } msg = (struct IntuiMessage *) succ; } } intuition.library/CloseWorkBench intuition.library/CloseWorkBench NAME CloseWorkBench -- Closes the Workbench screen. SYNOPSIS Success = CloseWorkBench() LONG CloseWorkBench( VOID ); FUNCTION This routine attempts to close the Workbench screen: - Test whether or not any applications have opened windows on the Workbench, and return FALSE if so. Otherwise ... - Clean up all special buffers - Close the Workbench screen - Make the Workbench program mostly inactive (it will still monitor disk activity) - Return TRUE INPUTS None RESULT TRUE if the Workbench screen closed successfully FALSE if the Workbench was not open, or if it has windows open which are not Workbench drawers. NOTES This routine has been drastically rewritten for V36. It is much more solid, although we haven't eliminated all the problem cases yet. BUGS The name of this function is improperly spelled. It ought to have been CloseWorkbench(). It might be more convenient to have it return TRUE if the Workbench wasn't opened when called. The idea as it is now is probably this: if you want to free up the memory of the Workbench screen when your program begins, you can call CloseWorkBench(). The return value of that call indicates whether you should call OpenWorkBench() when your program exits: if FALSE, that means either the the Workbench existed but you could not close it, or that it wasn't around to begin with, and you should not try to re-open it. We would prefer that you provide a user selection to attempt to open or close the Workbench screen from within your application, rather than your making assumptions like these. SEE ALSO OpenWorkBench() intuition.library/CurrentTime intuition.library/CurrentTime NAME CurrentTime -- Get the current time values. SYNOPSIS CurrentTime( Seconds, Micros ) VOID CurrentTime( ULONG *, ULONG * ); FUNCTION Puts copies of the current time into the supplied argument pointers. This time value is not extremely accurate, nor is it of a very fine resolution. This time will be updated no more than sixty times a a second, and will typically be updated far fewer times a second. INPUTS Seconds = pointer to a LONG variable to receive the current seconds value Micros = pointer to a LONG variable for the current microseconds value RESULT Puts the time values into the memory locations specified by the arguments Return value is not defined. BUGS SEE ALSO timer.device/TR_GETSYSTIME intuition.library/DirectionVector intuition.library/DirectionVector NAME DirectionVector -- Convert degrees to a X:Y ratio. (V50) SYNOPSIS Vector = DirectionVector( Degrees ) ULONG DirectionVector( ULONG ); FUNCTION This function calculates a packed X:Y ratio longword from the passed amount of degrees. This vector identifies a direction (more precisely, a rotation value relative to the X axis) suitable to initialize the Direction field of a GradientSpec structure. Valid values for 'Degrees' range from 0 to 359. INPUTS Degrees = amount of degrees whose direction vector is to be calculated EXAMPLES /* Calculate the direction vector for 154 degrees */ direction = DirectionVector(154); /* Now use it to specify the orientation of a gradient */ gradientspec.Direction = direction; RESULT The direction vector for the specified angle. NOTES SEE ALSO DrawGradient() intuition.library/DisableTemplate intuition.library/DisableTemplate NAME DisableTemplate -- Blit a shape in "disabled" style. (V51) SYNOPSIS DisableTemplate( RastPort, Left, Top, Width, Height, Template, OffX, TemplateType, BytesPerRow, BackType, DrawInfo ) VOID DisableTemplate( struct RastPort *, LONG, LONG, LONG, LONG, APTR, LONG, ULONG, ULONG, ULONG, struct DrawInfo * ); FUNCTION This function can be used to draw a "disabled" representation of an arbitrary shape. It is conceptually analogous to BltTemplate(), with two important differences: the shape is rendered in the most suitable style for an image in "disabled" state (according to the supplied context information), and the template which defines the shape can be either a traditional planar mask or a chunky alpha blending map. Depending on the user preferences for the GUI, the shape will be drawn (as of Intuition V51) either as if it were a recessed part of the background, or as a flat monochrome image in the target RastPort's DISABLEDTEXTPEN color. To ensure a correct appearance in all cases, you should tell the function exactly which kind of GUI element will be the background for the rendered shape; you can do this by passing the appropriate BT_ constant from those defined in (see the ShadeRectA() autodoc for more information on background types). You indicate a traditional planar template by passing TT_BITPLANE as TemplateType. If the template data is instead an alpha blending map, you can specify its exact modulo (1 to 4 bytes per pixel) by passing one of TT_ALPHA8, TT_ALPHA16, TT_ALPHA24 or TT_ALPHA32 as TemplateType. If the modulo of the alpha map is greater than 1, the first byte of the template data MUST be one containing alpha information; each subsequent alpha byte is found by advancing the template data pointer by the specified modulo (all bytes between an alpha byte and the next are ignored). This allows you to pass a simple alpha map where each byte represents an alpha value, or an array holding full ARGB data (and everything else in-between). Make sure to correctly set BytesPerRow according to the modulo! Note: if the template is a bitplane, the Template pointer should point to the "nearest" word (rounded down) of the template mask. Fine alignment of the mask is achieved by setting the OffX bit offset within the range of 0 to 15 decimal. If the template is an alpha blending map, the OffX parameter is ignored. INPUTS RastPort = pointer to the RastPort where rendering must take place Left, Top = upper left corner of the destination for the blit Width, Height = size of the rectangle to be used as the template Template = pointer to the template data (planar mask or alpha map) OffX = offset into the template mask (0..15); ignored for alpha map TemplateType = mask or map; see TT_ definitions in BytesPerRow = number of bytes per row in the template data BackType = type of the GUI element the rendering is performed over DrawInfo = pointer to a DrawInfo for additional context information EXAMPLES /* Blit a section of a planar mask (512 pixels wide) */ /* as disabled, over a menu panel background */ DisableTemplate(rp,40,40,200,100,plane,4,TT_BITPLANE,64,BT_MENU,dri); /* Blit a section of an alpha map (320 pixels wide) */ /* as disabled, over a menu panel background */ DisableTemplate(rp,40,40,200,100,amap,0,TT_ALPHA8,320,BT_MENU,dri); /* As above, but the alpha map has now 4 bytes per pixel */ DisableTemplate(rp,40,40,200,100,amap,0,TT_ALPHA32,1280,BT_MENU,dri); RESULT None. NOTES This rendering operation might not always yield optimal results on CLUT screens, due to palette sharing restrictions. SEE ALSO ShadeRectA(), EmbossDisableRect(), graphics.library/BltTemplate() intuition.library/DisplayAlert intuition.library/DisplayAlert NAME DisplayAlert -- Create the display of an alert message. SYNOPSIS BOOL response = DisplayAlert(uint32 alertnum, CONST_STRPTR string, uint16 height); FUNCTION Creates an alert display with the specified message. If the system can recover from this alert, it's a RECOVERY_ALERT and this routine waits until the user presses one of the mouse buttons, after which the display is restored to its original state and a BOOL value is returned by this routine to specify whether or not the user pressed the LEFT mouse button. If the system cannot recover from this alert, it's a DEADEND_ALERT and this routine returns immediately upon creating the alert display. The return value is FALSE. NOTE: Starting with V33, if Intuition can't get enough memory for a RECOVERY_ALERT, the value FALSE will be returned. The alertnum is a uint32 value historically related to the value sent to the Alert() routine. But the only bits that are pertinent to this routine are the ALERT_TYPE bit(s). These bits must be set to either RECOVERY_ALERT for alerts from which the system may safely recover, or DEADEND_ALERT for those fatal alerts. These states are described in the paragraph above. There is a third type of alert, the DAISY_ALERT, which is used only by the Exec. The string argument points to an AlertMessage string. The AlertMessage string is comprised of one or more substrings, each of which is composed of the following components: - first, a 16-bit x-coordinate and an 8-bit y-coordinate, describing where on the alert display you want this string to appear. The y-coordinate describes the offset to the baseline of the text. - then, the bytes of the string itself, which must be null-terminated (end with a byte of zero) - lastly, the continuation byte, which specifies whether or not there's another substring following this one. If the continuation byte is non-zero, there IS another substring to be processed in this alert message. If the continuation byte is zero, this is the last substring in the message. The last argument, height, describes how many video lines tall you want the alert display to be. New for V36: Alerts are always rendered in Topaz 8 (80 column font), regardless of the system default font. Also, RECOVERY_ALERTs are displayed in amber, while DEADEND_ALERTs are still red. Alerts no longer push down the application screens to be displayed. Rather, they appear alone in a black display. Also new for V36: Alerts block each other out, and input during an alert is deprived of the rest of the system. Internal input buffers still cause alert clicks to be processed by applications sometimes. INPUTS alertnum - the number of this alert message. The only pertinent bits of this number are the ALERT_TYPE bit(s). The rest of the number is ignored by this routine. string - pointer to the alert message string as described above height - minimum display lines required for your message RESULT response - A BOOL value of TRUE or FALSE. If this is a DEADEND_ALERT, FALSE is always the return value. If this is a RECOVERY_ALERT. The return value will be TRUE if the user presses the left mouse button in response to your message, and FALSE if the user presses the right hand button is response to your text, or if the alert could not be posted. BUGS If the system is worse off than you think, the level of your alert may become DEADEND_ALERT without you ever knowing about it. This will NOT happen due simply to low memory. Rather, the alert display will be skipped, and FALSE will be returned. The left and right button clicks satisfying the alerts are unfortunately passed to the normal applications, because of some internal system input buffering. SEE ALSO TimedDisplayAlert() intuition.library/DisplayBeep intuition.library/DisplayBeep NAME DisplayBeep -- Flash the video display. SYNOPSIS DisplayBeep( Screen ) VOID DisplayBeep( struct Screen * ); FUNCTION "Beeps" the video display by flashing the background color of the specified screen. If the screen argument is NULL, every screen in the display will be beeped. Flashing everyone's screen is not a polite thing to do, so this should be reserved for dire circumstances. The reason such a routine is supported is because the Amiga has no internal bell or speaker. When the user needs to know of an event that is not serious enough to require the use of a requester, the DisplayBeep() function may be called. New for V36: Intuition now calls DisplayBeep through the external library vector. This means that if you call SetFunction() to replace DisplayBeep with an audible beep, for example, then your change will affect even Intuition's calls to DisplayBeep. INPUTS Screen = pointer to a screen. If NULL, every screen in the display will be flashed RESULT None NOTES Since this function changes color zero of the affected screen(s), surprising results could occur if the screen's owner reading colors or perhaps cycling them. BUGS SEE ALSO intuition.library/DisposeObject intuition.library/DisposeObject NAME DisposeObject -- Deletes a BOOPSI object. (V36) SYNOPSIS void DisposeObject(Object *obj); FUNCTION Deletes a BOOPSI object and all of it auxiliary data. These objects are all created by NewObject(). Objects of certain classes "own" other objects, which will also be deleted when the object is passed to DisposeObject(). Read the per-class documentation carefully to be aware of these instances. INPUTS obj - abstract pointer to a BOOPSI object returned by NewObject(). The pointer may be NULL in which case this function has no effect. NOTES This function invokes the OM_DISPOSE method. SEE ALSO NewObject(), SetAttrs(), GetAttr(), MakeClass(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/DoGadgetMethodA intuition.library/DoGadgetMethodA NAME DoGadgetMethodA -- Invoke method on a BOOPSI gadget. (V39) DoGadgetMethod -- Varargs stub for DoGadgetMethodA(). (V39) SYNOPSIS uint32 result = DoGadgetMethodA(struct Gadget *gad, struct Window *win, struct Requester *req, Msg msg); uint32 result = DoGadgetMethod(struct Gadget *gad, struct Window *win, struct Requester *req, uint32 MethodID, ...); FUNCTION Same as the IDoMethodA() function but provides context information and arbitration for classes which implement custom Intuition gadgets. You should use this function for BOOPSI gadget objects, or for "models" which propagate information to gadgets. Unlike IDoMethodA(), this function provides a GadgetInfo pointer (if possible) when invoking the method. Some classes may require or benefit from this. INPUTS gad - abstract pointer to a BOOPSI gadget win - window gadget has been added to using AddGList() or AddGadget() req - for REQGADGETs, requester containing the gadget msg - the BOOPSI message to send RESULT result - The object does whatever it wants with the message you sent which might include updating its gadget visuals. The return value is defined per-method. NOTES This function invokes the specified method with a GadgetInfo derived from the 'Window' and 'Requester' pointers. The GadgetInfo is passed as the second parameter of the message, except for OM_NEW, OM_SET, OM_NOTIFY and OM_UPDATE, where the GadgetInfo is passed as the third parameter. Implementers of new gadget methods should always ensure that the GadgetInfo is the second long-word of their message! Prior to V50 it was not possible to invoke the GM_RENDER method on a gadget because gpr_RPort field of the gpRender message requires a rastport pointer obtained via ObtainGIRPort() which itself requires a ginfo pointer. WARNING: Do not use this function for methods whose structure does not contain a GadgetInfo field! SEE ALSO NewObject(), DisposeObject(), GetAttr(), MakeClass(), IDoMethod(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/DoRender intuition.library/DoRender NAME DoRender -- Redraw a BOOPSI gadget. (V50) SYNOPSIS void DoRender(Object *obj, struct GadgetInfo *ginfo, uint32 flags); FUNCTION For class implementors only: This function should be used whenever it is necessary to redraw a gadget (ie. after attribute changes that require a visual update). The only place in your class where you should render is the GM_RENDER method and that's what this function invokes on your object. For future compatibility we strongly suggest to use this function in your classes. Applications must use RefreshGList() instead. INPUTS obj - the gadget/object pointer. ginfo - a GadgetInfo pointer you got from Intuition. flags - one of the GREDRAW flags. SEE ALSO RefreshGList() intuition.library/DoScrollHook intuition.library/DoScrollHook NAME DoScrollHook -- Optimized real-time scrolling framework (V50). SYNOPSIS DoScrollHook( Scroll_hook, Scroll_mode ) VOID DoScrollHook( struct ScrollHook *, LONG ); FUNCTION Implementing a responsive, optimized scrolling routine is a tedious task. The DoScrollHook() function considerably simplifies this. All you need to do is to provide for a hook function which implements certain functionality, which will be invoked by DoScrollHook() until the scrolling operation has been performed. INPUTS Scroll_hook = Pointer to an initialized ScrollHook structure, which looks as follows: struct ScrollHook { struct Hook sh_Hook; LONG sh_Top; LONG sh_Total; LONG sh_Visible; LONG sh_Size; }; The structure members have the following purposes: sh_Hook Standard Hook structure. This must be initialized prior to use. sh_Top The number of the first item to be displayed. This is equivalent to the PGA_Top attribute of a PROPGCLASS gadget. sh_Total The total number of items available for display. This is equivalent to the PGA_Total attribute of a PROPGCLASS gadget. sh_Visible How many items can be displayed at a time. This is equivalent to the PGA_Visible attribute of a PROPGCLASS gadget. sh_Size The size of each item to be displayed, given in pixels. This must be >= 1. Your hook function will be invoked as follows: result = hook_function(hook, reserved, scroll_message) D0 A0 A2 A1 LONG hook_function(struct Hook *hook, APTR reserved, struct ScrollMsg *scroll_message); The ScrollMsg structure looks as follows: struct ScrollMsg { ULONG sm_Action; LONG sm_NumItems; LONG sm_NumPixels; LONG sm_TopItem; LONG sm_TopPixel; }; The structure members have the following purposes: sm_Action The action to be performed by your hook function. This will be one of SMA_GetScrollerTop, SMA_RedrawAll, SMA_Scroll, SMA_Draw or SMA_RepairDamage. sm_NumItems Number of items to be drawn; this is valid only for the actions SMA_Draw and SMA_RepairDamage. sm_NumPixels Number of pixels to scroll, suitable for use as a parameter to ScrollRaster(); this is valid only for the action SMA_Scroll. sm_TopItem Number of the first item to be rendered; this is valid only for the actions SMA_Draw and SMA_RepairDamage. sm_TopPixel Pixel offset at which to start printing the first item; this is valid only for the actions SMA_Draw and SMA_RepairDamage. You may modify the contents of the ScrollMsg structure if necessary (see the notes for the SMA_Draw and SMA_RepairDamage methods below). The different actions have the following purposes: SMA_GetScrollerTop You need to return the scroller's top position, e.g. the PGA_Top attribute of a PROPGCLASS gadget. SMA_RedrawAll You need to redraw the entire display, starting with the first line given in ScrollHook->sh_Top. SMA_Scroll You need to scroll the display by a number of pixels, as given in the ScrollMsg->sm_NumPixels field. This value is suitable to submit as a parameter to the ScrollRaster() function. If the scrolling operation has produced any layer damage which needs to be subsequently repaired, your hook function must return TRUE and FALSE otherwise. This feature is for scrolling within SIMPLE_REFRESH windows. SMA_Draw You need to draw some items. The first item to be drawn is given in the ScrollMsg->sm_TopItem field, and it should be rendered at the pixel position given in the ScrollMsg->sm_TopPixel field, followed by further items as necessary. How many items need to be printed is given in the ScrollMsg->sm_NumItems field. NOTE: The ScrollMsg->sm_TopPixel field can be negative, which means that only part of the first line should be drawn. If your code cannot do that, you can adjust the parameters as follows: while(ScrollMsg->sm_NumItems > 0 && ScrollMsg->sm_TopPixel < 0) { ScrollMsg->sm_TopPixel += ScrollHook->sh_Size; ScrollMsg->sm_TopItem++; ScrollMsg->sm_NumItems--; } When this loop has terminated, check the ScrollMsg->sm_NumItems field to see if any rendering is necessary and proceed as usual. SMA_RepairDamage This is functionally equivalent to SMA_Draw, except that you should bracket the drawing operation between BeginRefresh()..EndRefresh() to limit the drawing operations to those portions of the display which sustained layer damage during the previous SMA_Scroll scrolling operation. Note that only those members of the ScrollMsg structure will be valid which have been documented above. Other fields may contain random data. Scroll_mode = Either DSHM_Smooth or DSHM_Jump. DSHM_Smooth will try to perform a smooth drawing operation which may be broken down into several scrolling/redrawing passes. The DSHM_Jump mode will complete the same operation, but will do this using a minimum of effort and generally faster. SEE ALSO graphics.library/ScrollRaster(), utility.library/CallHookPkt() intuition.library/DoubleClick intuition.library/DoubleClick NAME DoubleClick -- Test two time values for double-click timing. SYNOPSIS IsDouble = DoubleClick( StartSecs, StartMicros, CurrentSecs, CurrentMicros ) BOOL DoubleClick( ULONG, ULONG, ULONG, ULONG ); FUNCTION Compares the difference in the time values with the double-click timeout range that the user has set (using the "Preferences" tool) or some other program has configured into the system. If the difference between the specified time values is within the current double-click time range, this function returns TRUE, else it returns FALSE. These time values can be found in input events and IDCMP messages. The time values are not perfect; however, they are precise enough for nearly all applications. INPUTS StartSeconds, StartMicros = the timestamp value describing the start of the double-click time period you are considering CurrentSeconds, CurrentMicros = the timestamp value describing the end of the double-click time period you are considering RESULT If the difference between the supplied timestamp values is within the double-click time range in the current set of Preferences, this function returns TRUE, else it returns FALSE BUGS SEE ALSO CurrentTime() intuition.library/DrawBorder intuition.library/DrawBorder NAME DrawBorder -- Draw the specified Border structure into a RastPort. SYNOPSIS DrawBorder( RastPort, Border, LeftOffset, TopOffset ) VOID DrawBorder( struct RastPort *, struct Border *, WORD, WORD ); FUNCTION First, sets up the draw mode and pens in the RastPort according to the arguments of the Border structure. Then, draws the vectors of the border argument into the RastPort, offset by the left and top offsets. As with all graphics rendering routines, the border will be clipped to to the boundaries of the RastPort's layer, if it exists. This is the case with window RastPorts. This routine will draw all borders in the NULL-terminated list linked by the NextBorder field of the border argument. INPUTS RastPort = pointer to the RastPort to receive the border rendering Border = pointer to a Border structure LeftOffset = the offset to be added to each vector's x coordinate TopOffset = the offset to be added to each vector's y coordinate RESULT None BUGS SEE ALSO intuition.library/DrawGradient intuition.library/DrawGradient NAME DrawGradient -- Draw a gradient effect into a RastPort. (V50) SYNOPSIS Success = DrawGradient( RastPort, Left, Top, Width, Height, Domain, Reserved, GradientSpec, DrawInfo ) ULONG DrawGradient( struct RastPort *, LONG, LONG, LONG, LONG, struct IBox *, ULONG, struct GradientSpec *, struct DrawInfo * ); FUNCTION This function is used to draw a gradient effect into a RastPort on the basis of a number of parameters. The actual gradient features, such as type, color range and orientation are specified in the passed GradientSpec structure (see ); the rectangle which must be filled with the gradient is defined by the Left, Top, Width and Height parameters. Additionally, you can pass an optional IBox structure which describes a rectangle enclosing the one where rendering takes place: in this case, Intuition will layout the gradient as if its bounds were those of the external rectangle, but only draw the part of it that lies inside the inner rendering area. This can be useful when you only need to refresh a small section of a large gradient. INPUTS RastPort = pointer to the RastPort where rendering must take place Left, Top, Width, Height = rendering bounds of the gradient effect Domain = optional pointer to an IBox structure describing the real gradient bounds (must enclose the whole rendering area) Reserved = reserved for future use, pass zero until further notice GradientSpec = pointer to a GradientSpec structure DrawInfo = pointer to a DrawInfo for additional context information EXAMPLES /* Draw a simple horizontal red-to-white gradient */ struct GradientSpec gradspec; struct IBox domain; memset(&gradspec,0,sizeof(gradspec)); /* Set everything to zero! */ gradspec.Direction = DirectionVector(0); gradspec.Mode = GRADMODE_COLOR; gradspec.Specs.Abs.RGBStart[0] = 255; gradspec.Specs.Abs.RGBEnd[0] = 255; gradspec.Specs.Abs.RGBEnd[1] = 255; gradspec.Specs.Abs.RGBEnd[2] = 255; DrawGradient(rp,50,50,400,200,NULL,0L,&gradspec,dri); /* Now make it oblique, at 45 degrees, and */ /* also superimpose it to the background */ gradspec.Direction = DirectionVector(45); gradspec.Mode |= GRADMODE_IMPOSE; DrawGradient(rp,50,400,100,100,NULL,0L,&gradspec,dri); /* Now draw a smaller section of a large gradient: */ /* the "real" gradient is 300 x 300 in size, but */ /* we only want to draw a 50 x 50 part of it... */ domain.Left = 700; domain.Top = 200; domain.Width = 300; domain.Height = 300; DrawGradient(rp,750,250,50,50,&domain,0L,&gradspec,dri); RESULT TRUE if the gradient was drawn successfully, otherwise FALSE. Failure is usually due to a low-memory condition. NOTES To specify the orientation of a gradient effect, you must supply a packed X:Y ratio longword in the GradientSpec.Direction field; the DirectionVector() function can calculate this value for you. Remember to set to zero the reserved fields of the GradientSpec structure before passing it to DrawGradient()! The best way to ensure this is to always allocate it with MEMF_CLEAR. If it is created on the stack, you'll have to take care of this manually. Failure to do so WILL break your software in future OS releases. Gradient effects are thought for hicolor and truecolor screens. Attempting to use them on CLUT screens might not always work, and even in the best of cases will yield poor results. There's no guarantee that CLUT screens will continue to be supported at all in future revisions of this function, so don't rely on that! SEE ALSO DirectionVector() intuition.library/DrawImage intuition.library/DrawImage NAME DrawImage -- Draw the specified Image structure into a RastPort. SYNOPSIS DrawImage( RastPort, Image, LeftOffset, TopOffset ) VOID DrawImage( struct RastPort *, struct Image *, WORD, WORD ); FUNCTION First, sets up the draw mode and pens in the RastPort according to the arguments of the Image structure. Then, moves the image data of the image argument into the RastPort, offset by the left and top offsets. This routine does window layer clipping if you pass your window's (layered) RastPort -- if you draw an image outside of your window, your imagery will be clipped at the window's edge. If you pass a (non-layered) screen RastPort, you MUST be sure your image is wholly contained within the rastport bounds. If the NextImage field of the image argument is non-NULL, the next image is rendered as well, and so on until some NextImage field is found to be NULL. INPUTS RastPort = pointer to the RastPort to receive image rendering Image = pointer to an image structure LeftOffset = the offset which will be added to the image's x coordinate TopOffset = the offset which will be added to the image's y coordinate RESULT None NOTES Intuition always has and will continue to assume there are at least as many planes of data pointed to by ImageData as there are '1' bits in the PlanePick field. Please ensure that this is so. (See the intuition.h include file for full details on using PlanePick). BUGS SEE ALSO DrawImageState(), EraseImage() intuition.library/DrawImageState intuition.library/DrawImageState NAME DrawImageState -- Draw an (extended) Intuition Image with special visual state. (V36) SYNOPSIS DrawImageState( RPort, Image, LeftOffset, TopOffset, State, DrawInfo ) VOID DrawImageState( struct RastPort *, struct Image *, WORD, WORD, ULONG, struct DrawInfo * ); FUNCTION This function draws an Intuition Image structure in a variety of "visual states," which are defined by constants in intuition/imageclass.h. These include: IDS_NORMAL - like DrawImage() IDS_SELECTED - represents the "selected state" of a Gadget IDS_DISABLED - the "ghosted state" of a gadget IDS_BUSY - for future functionality IDS_INDETERMINATE - for future functionality IDS_INACTIVENORMAL - for gadgets in window border IDS_INACTIVESELECTED - for gadgets in window border IDS_INACTIVEDISABLED - for gadgets in window border Only IDS_NORMAL will make sense for traditional Image structures, this function is more useful when applied to new custom images or "object-oriented image classes." Each class of custom images is responsible for documenting which visual states it supports, and you typically want to use images which support the appropriate states with your custom gadgets. The DrawInfo parameter provides information invaluable to "rendered" images, such as pen color and resolution. Each image class must document whether this parameter is required. INPUTS RPort - RastPort for rendering Image - pointer to a (preferably custom) image LeftOffset,RightOffset - positional offsets in pixels State - visual state selected from above DrawInfo - pointer to packed of pen selections and resolution. RESULT None. EXAMPLE Provided separately in the DevCon '90 disk set. NOTES BUGS SEE ALSO DrawImage(), GetScreenDrawInfo(), intuition/imageclass.h intuition.library/EasyRequestArgs intuition.library/EasyRequestArgs NAME EasyRequestArgs -- Easy alternative to AutoRequest(). (V36) EasyRequest -- Varargs stub for EasyRequestArgs(). (V36) SYNOPSIS num = EasyRequestArgs( Window, easyStruct, IDCMP_ptr, ArgList ) LONG EasyRequestArgs( struct Window *, struct EasyStruct *, ULONG *, APTR ); num = EasyRequest( Window, easyStruct, IDCMP_ptr, Arg1, Arg2, ... ) LONG EasyRequest( struct Window *, struct EasyStruct *, ULONG *, APTR, ... ); ( from intuition.h ) struct EasyStruct { ULONG es_StructSize; ULONG es_Flags; STRPTR es_Title; STRPTR es_TextFormat; STRPTR es_GadgetFormat; struct Screen *es_Screen; /* New for V50 */ struct TagItem *es_TagList; /* New for V50 */ }; FUNCTION This function provides a simpler method of using a 'System Requester' than provided by AutoRequest(). It performs layout and size calculations sensitive to the current font and screen resolution. It provides for the descriptive 'body' text and the gadget text to be constructed from 'printf' style format strings. It also provides a general way for the requester to be sensitive to particular IDCMP messages. The first function listed is the actual Intuition library function. It is passed the arguments for the formatting operations as a pointer to the first argument. The second function uses a C-style variable number of argument (varargs) calling convention. It should be implemented as a call to the first function, and might be supplied by your compiler vendor, in amiga.lib, or using the first example below, for most C compilers. NOTE: The formatting is done by exec.library/RawDoFmt(), so be aware that to display a 32-bit integer argument, for example, you must say "%ld", not "%d", since RawDoFmt() is "word-oriented." NOTE: This function switches the processor stack to ensure sufficient stack space for the function to complete. EXAMPLES /* varargs interface works for most C compilers */ EasyRequest( w, es, ip, arg1, ... ) struct Window *w; struct EasyStruct *es; ULONG *ip; int arg1; { return ( EasyRequestArgs( w, es, ip, &arg1 ) ); } /*********************************************/ /* typical use */ struct EasyStruct volumeES = { sizeof (struct EasyStruct), 0, "Volume Request", "Please insert volume %s in any drive.", "Retry|Cancel" }; #define CANCEL (0) Volume * getVolume( STRPTR volname ) { Volume *vptr; Volume *findVolume(); UWORD reply; ULONG iflags; iflags = IDCMP_DISKINSERTED; while ( ((vptr = findVolume( volname )) == NULL) && (EasyRequest( w, &volumeES, &iflags, volname ) != CANCEL) ) /* loop */ ; /* note that in some circumstances, you will have to re-initialize the value of 'iflags'. Here, it is either unchanged, or returned as the single IDCMPFlag value IDCMP_DISKINSERTED. If you combine multiple IDCMPFlag values in 'iflags,' only one will be returned, so you must reinitialize 'iflags' to be the combination. */ return ( vptr ); } INPUTS Window = Reference window pointer, determines the screen and title of the requester window. This can be NULL, which means the requester is to appear on the Workbench screen, or default public screen, if defined. Starting with V50, the screen can also be specified with the new es_Screen field of the EasyStruct structure; note that you must _also_ set the ESF_SCREEN flag in es_Flags, or es_Screen will be ignored. IDCMP_ptr = Pointer to IDCMP flags that you want to terminate the requester. This pointer may be NULL. easyStruct = Pointer to EasyStruct structure with fields interpreted as follows: es_StructSize = sizeof (struct EasyStruct), for future extension. es_Flags = as of V51, only four flags are defined: ESF_SCREEN - open the requester on the screen specified in es_Screen (if that is NULL, the default public screen will be used). (V50) ESF_TAGGED - read and use the additional information provided via es_TagList. (V50) ESF_EVENSIZE - make all requester buttons the same width, i.e. as wide as the widest one. (V50) ESF_INACTIVE - open the requester window in inactive state, preventing it from stealing the user input focus. (V51) es_Title = Title of system requester window. If this is NULL, the title will be taken to be the same as the title of 'Window', if provided, or else "System Request." es_TextFormat = Format string, a la RawDoFmt(), for message in requester body. Lines are separated by the newline character. This character is represented in C by '\n', in the Amiga Shell by "*N", etc. Formatting '%' functions are supported exactly as in RawDoFmt(). es_GadgetFormat = Format string for gadgets. Text for separate gadgets is separated by '|'. Format functions are supported. You MUST specify at least one gadget. es_Screen = Screen the requester must open on, only used if ESF_SCREEN is also set in es_Flags. (New for V50) es_TagList = Optional list of TagItems supplying additional information, only used if ESF_TAGGED is also set in es_Flags. See below for a list of known tags. (New for V50) ArgList = Arguments for format commands. Arguments for GadFmt follow arguments for TextFmt. TAGS These are the tags defined for EasyStruct.es_TagList as of V51: ESA_Position - (UWORD) The on-screen position the requester is to be opened at. The possible choices are: REQPOS_DEFAULT - use position from user preferences REQPOS_CORNER - top left screen corner REQPOS_BELOWBAR - top left corner, below the screen titlebar REQPOS_CENTERMOUSE - center under the mouse pointer REQPOS_CENTERSCREEN - center in visible screen clip REQPOS_CENTERWINDOW - center in supplied reference window (if this is NULL, center in screen) ESA_Underscore - (TEXT) The character used in the gadget format string to indicate that the following letter must be displayed underscored and act as a gadget keyboard shortcut. If this tag is not present, no underscoring is performed for compatibility. RESULT 0, 1, ..., N = Successive GadgetID values, for the gadgets you specify for the requester. NOTE: The numbering from left to right is actually: 1, 2, ..., N, 0. This is for compatibility with AutoRequest(), which has FALSE for the rightmost gadget. -1 = Means that one of the caller-supplied IDCMPFlags occurred. The IDCMPFlag value is in the longword pointed to by IDCMP_ptr. NOTES When DOS brings up EasyRequests() on your process (eg. "Please insert volume XXX in any drive", they normally come up on the default public screen, which is usually the Workbench screen. If you set your Process pr_WindowPtr field to point to one of your windows, then DOS will bring its requesters up on the same screen as that window. A pr_WindowPtr of -1 prevents requesters from coming up at all. (Some FileSystem requesters cannot be redirected or supressed). BUGS Does not fall back to a recoverable alert if the requester cannot be created. Does not handle case when gadgets don't fit or window title is too long, although it does trim trailing spaces from the title for calculating dimensions. PLANS Possible enhancements include: centering of text, size-sensitive layout, window-relative requester, vertical gadget layout, window placement, more keyboard shortcuts. We also reserve the use of the newline character ('\n') in gadget format strings for future use as a line separator. SEE ALSO exec.library/RawDoFmt(), BuildEasyRequestArgs(), SysReqHandler(), AutoRequest(), BuildSysRequest() intuition.library/EmbossDisableRect intuition.library/EmbossDisableRect NAME EmbossDisableRect -- Draw a rectangle in "disabled" style. (V50) SYNOPSIS void EmbossDisableRect(struct RastPort *rp, int32 minx, int32 miny, int32 maxx, int32 maxy, uint32 backtype, uint32 contrast, struct DrawInfo* dri); FUNCTION This function can be used to draw a "disabled" representation of a solid rectangle. The rectangle will be rendered as if it were a recessed part of the background. To ensure a correct appearance in all cases, you should tell the function exactly which kind of GUI element will be the background for the recessed rectangle; you can do this by passing the appropriate BT_ constant from those defined in (see the ShadeRectA() autodoc for more information on background types). The contrast for the shading of the embossed rectangular shape can be specified with the 'Contrast' parameter; however, it is strongly advised that you always pass the STD_DISABLE_CONTRAST constant (from ) for this, which will make the function choose the same contrast level that Intuition uses for all its disabled GUI elements. INPUTS rp - pointer to the RastPort where rendering must take place minx - minimum x coordinate of the rectangle to be drawn miny - minimum y coordinate of the rectangle to be drawn maxx - maximum x coordinate of the rectangle to be drawn maxy - maximum y coordinate of the rectangle to be drawn backtype - type of the GUI element the rendering is performed over contrast - contrast level for the shading of the embossed shape dri - pointer to a DrawInfo for additional context information EXAMPLES /* Draw a recessed rectangle over a menu panel background */ EmbossDisableRect(rp,100,100,299,199,BT_MENU,STD_DISABLE_CONTRAST,dri); NOTES This rendering operation might not always yield optimal results on CLUT screens due to palette sharing restrictions. SEE ALSO EmbossDisableText(), ShadeRectA() intuition.library/EmbossDisableText intuition.library/EmbossDisableText NAME EmbossDisableText -- Write text in "disabled" style. (V50) SYNOPSIS void EmbossDisableText(struct RastPort *rp, CONST_STRPTR string, int32 length, uint32 backtype, uint32 contrast, struct DrawInfo *dri); FUNCTION This function can be used to render a "disabled" representation of a text string. It works in a similar way to graphics.library/Text() but the text characters will be drawn with a 3D effect, as if they were engraved in the background. The main purpose of this function is to ensure that any disabled text written by applications looks consistent with Intuition's own graphic style for disabled text. In order to achieve a correct appearance in all cases, you should tell the function exactly which kind of GUI element will be the background for the recessed text; you can do this by passing the appropriate BT_ constant from those defined in (see the ShadeRectA() autodoc for more information on background types). The contrast for the shading of the embossed text characters can be specified with the 'contrast' parameter; however, it is strongly advised that you always pass the STD_DISABLE_CONTRAST constant (from ) for this, which will make the function choose the same contrast level that Intuition uses for all its disabled text renderings. INPUTS rp - pointer to the RastPort where the text is to be output string - the address of string to output length - the number of characters in the string; if zero, there are no characters to be output backtype - type of the GUI element the text is being written over contrast - contrast level for the shading of the embossed text dri - pointer to a DrawInfo for additional context information EXAMPLES /* Write some disabled text over a menu panel background */ EmbossDisableText(rp,"I'm disabled",12,BT_MENU,STD_DISABLE_CONTRAST,dri); NOTES This rendering operation might not always yield optimal results on CLUT screens, due to palette sharing restrictions. Note well: the text written by this function will always extend one pixel more to the right, and one to the bottom, compared to the regular Text() function, due to how the pseudo-3D effect is performed. If you used TextExtent() to pre-calculate the maximum extent of your text, please make sure you take these extra pixels into account if you plan to write it with this function! SEE ALSO PrintEmbossedDisabledIText(), EmbossDisableRect(), ShadeRectA() intuition.library/EndRefresh intuition.library/EndRefresh NAME EndRefresh -- End the optimized refresh state of the window. SYNOPSIS EndRefresh( Window, Complete ) VOID EndRefresh( struct Window *, BOOL ); FUNCTION This function gets you out of the special refresh state of your window. It is called following a call to BeginRefresh(), which routine puts you into the special refresh state. While your window is in the refresh state, the only rendering that will be wrought in your window will be to those areas which were recently revealed and need to be refreshed. After you've done all the refreshing you want to do for this window, you should call this routine to restore the window to its non-refreshing state. Then all rendering will go to the entire window, as usual. The 'Complete' argument is a boolean TRUE or FALSE value used to describe whether or not the refreshing you've done was all the refreshing that needs to be done at this time. Most often, this argument will be TRUE. But if, for instance, you have multiple tasks or multiple procedure calls which must run to completely refresh the window, then each can call its own Begin/EndRefresh() pair with a Complete argument of FALSE, and only the last calls with a Complete argument of TRUE. WARNING: Passing this function the value of FALSE has its pitfalls. Please see the several caveats in the autodoc for BeginRefresh(). For your information, this routine calls the Layers library function EndUpdate(), unlocks your layers (calls UnlockLayerRom()), clears the LAYERREFRESH bit in your Layer Flags, and clears the WFLG_WINDOWREFRESH bit in your window Flags. INPUTS Window = pointer to the window currently in optimized-refresh mode Complete = Boolean TRUE or FALSE describing whether or not this window is completely refreshed RESULT None BUGS SEE ALSO BeginRefresh(), layers.library/EndUpdate(), graphics.library/UnlockLayerRom() intuition.library/EndRequest intuition.library/EndRequest NAME EndRequest -- Remove a currently active requester. SYNOPSIS EndRequest( Requester, Window ) VOID EndRequest( struct Requester *, struct Window * ); FUNCTION Ends the request by erasing the requester and decoupling it from the window. Note that this doesn't necessarily clear all requesters from the window, only the specified one. If the window labors under other requesters, they will remain in the window. INPUTS Requester = pointer to the requester to be removed Window = pointer to the Window structure with which this requester is associated RESULT None BUGS SEE ALSO Request() intuition.library/EndScreenNotify intuition.library/EndScreenNotify NAME EndScreenNotify -- end notification request. (V50) SYNOPSIS Result = EndScreenNotify( RequestHandle ) BOOL EndScreenNotify( APTR ); FUNCTION Removes a notification request. It searches your port (if any) for any messages about the request in question and removes and replies them before returning. INPUTS RequestHandle = pointer returned by StartScreenNotifyTagList(). RESULT Returns FALSE when trying to remove a request that is currently active. SEE ALSO StartScreenNotifyTagList() intuition.library/EraseImage intuition.library/EraseImage NAME EraseImage -- Erases an Image. (V36) SYNOPSIS EraseImage( RPort, Image, LeftOffset, TopOffset ) VOID EraseImage( struct RastPort *, struct Image *, WORD, WORD ); FUNCTION Erases an Image. For a normal Image structure, this will call the graphics function EraseRect() (clear using layer backfill, if any) for the Image box (LeftEdge/TopEdge/Width/Height). For custom image, the exact behavior is determined by the custom image class. INPUTS RPort - RastPort to erase a part of Image - custom or standard image LeftOffset,RightOffset - pixel offsets of Image position RESULT None. EXAMPLE NOTES BUGS SEE ALSO graphics.library/EraseRect(). intuition.library/FreeClass intuition.library/FreeClass NAME FreeClass -- Frees a BOOPSI class created by MakeClass(). (V36) SYNOPSIS BOOL success = FreeClass(Class *cl); FUNCTION For class implementors only. Tries to free a BOOPSI class created by MakeClass(). This won't always succeed: classes with outstanding objects or with subclasses cannot be freed. You cannot allow the code which implements the class to be unloaded in this case. For public classes, this function will *always* remove the class (see RemoveClass()) making it unavailable, whether it succeeds or not. If you have any dynamically allocated data for your class (hanging off of cl_UserData) try to free the class before you free the user data so you don't get stuck with a half-freed class. INPUTS cl - pointer to a class created by MakeClass() RESULT success - Returns FALSE if the class could not be freed. Reasons include but will not be limited to having non-zero cl_ObjectCount or cl_SubclassCount. Returns TRUE if the class could be freed. Calls RemoveClass() for the class in either case. EXAMPLE Freeing a private class with dynamically allocated user data: freeMyClass(Class *cl) { struct MyPerClassData *mpcd; mpcd = (struct MyPerClassData *) cl->cl_UserData; if ( FreeClass( cl ) ) { FreeMem( mpcd, sizeof(mpcd) ); return ( TRUE ); } else { return ( FALSE ); } } SEE ALSO MakeClass(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/FreeRemember intuition.library/FreeRemember NAME FreeRemember -- Free memory allocated by calls to AllocRemember(). SYNOPSIS FreeRemember( RememberKey, ReallyForget ) VOID FreeRemember( struct Remember **, BOOL ); FUNCTION This function frees up memory allocated by the AllocRemember() function. It will either free up just the Remember structures, which supply the link nodes that tie your allocations together, or it will deallocate both the link nodes AND your memory buffers too. If you want to deallocate just the Remember structure link nodes, you should set the ReallyForget argument to FALSE. However, if you want FreeRemember to really deallocate all the memory, including both the Remember structure link nodes and the buffers you requested via earlier calls to AllocRemember(), then you should set the ReallyForget argument to TRUE. NOTE WELL: Once you call this function passing it FALSE, the linkages between all the memory chunks are lost, and you cannot subsequently use FreeRemember() to free them. INPUTS RememberKey = the address of a pointer to struct Remember. This pointer should either be NULL or set to some value (possibly NULL) by a call to AllocRemember(). ReallyForget = a BOOL FALSE or TRUE describing, respectively, whether you want to free up only the Remember nodes or if you want this procedure to really forget about all of the memory, including both the nodes and the memory buffers referenced by the nodes. EXAMPLE struct Remember *RememberKey; RememberKey = NULL; AllocRemember(&RememberKey, BUFSIZE, MEMF_CHIP); FreeRemember(&RememberKey, TRUE); RESULT None BUGS SEE ALSO AllocRemember(), exec.library/FreeMem() intuition.library/FreeScreenBuffer intuition.library/FreeScreenBuffer NAME FreeScreenBuffer -- Free a ScreenBuffer structure. (V39) SYNOPSIS FreeScreenBuffer( Screen, ScreenBuffer ) VOID FreeScreenBuffer( struct Screen *, struct ScreenBuffer * ); FUNCTION Frees a ScreenBuffer structure you got from AllocScreenBuffer(), and releases associated resources. You must call FreeScreenBuffer() before you close your screen. INPUTS Screen: pointer to the screen this ScreenBuffer is associated with. ScreenBuffer: pointer to a ScreenBuffer structure obtained from AllocScreenBuffer(). It is safe to call this function with a NULL argument. It will have no effect. RESULT None. NOTES Originally, FreeScreenBuffer() did not WaitBlit() before freeing a BitMap. The intent was that the application should do this. However, as this sort of thing is easily forgotten, WaitBlit() was added in V40. Application writers should ensure that freeing the buffer is safe by calling WaitBlit() themselves. The SB_SCREEN_BITMAP flag instructs AllocScreenBuffer() to provide a ScreenBuffer referring to the screen's actual bitmap. When you are done changing screen buffers, you must FreeScreenBuffer() the currently-installed ScreenBuffer before you close the screen. Intuition will recognize when FreeScreenBuffer() is called for the currently-installed ScreenBuffer, and will know to free the supporting structures but not the BitMap. CloseScreen() will take care of that. BUGS SEE ALSO AllocScreenBuffer(), ChangeScreenBuffer(), graphics.library/ChangeVPBitMap() intuition.library/FreeScreenDrawInfo intuition.library/FreeScreenDrawInfo NAME FreeScreenDrawInfo -- Finish using a DrawInfo structure. (V36) SYNOPSIS FreeScreenDrawInfo( Screen, DrInfo ) VOID FreeScreenDrawInfo( struct Screen *, struct DrawInfo * ); FUNCTION Declares that you are finished with the DrawInfo structure returned by GetScreenDrawInfo(). INPUTS Screen - pointer to screen passed to GetScreenDrawInfo(). DrInfo - pointer to DrawInfo returned by GetScreenDrawInfo(). A NULL DrawInfo pointer is a valid parameter, signifying "do nothing". RESULT None NOTES This function, and GetScreenDrawInfo(), don't really do much, but they provide an upward compatibility path. That means that if you misuse them today, they probably won't cause a problem, although they may someday later. So, please be very careful only to use the DrawInfo structure between calls to GetScreenDrawInfo() and FreeScreenDrawInfo(), and be sure that you don't forget FreeScreenDrawInfo(). BUGS SEE ALSO GetScreenDrawInfo() intuition.library/FreeSysRequest intuition.library/FreeSysRequest NAME FreeSysRequest -- Free resources gotten by a call to BuildSysRequest(). SYNOPSIS FreeSysRequest( Window ) VOID FreeSysRequest( struct Window * ); FUNCTION This routine frees up all memory allocated by a successful call to the BuildSysRequest() procedure. If BuildSysRequest() returned a pointer to a window, then you are able to wait on the message port of that window to detect an event which satisfies the requester. When you want to remove the requester, you call this procedure. It ends the requester and deallocates any memory used in the creation of the requester. It also closes the special window that was opened for your system requester. For V36: It's OK if you pass a NULL or a TRUE (1) value to this function. Also, this function properly disposes of requesters gotten using BuildEasyRequestArgs(). INPUTS Window = value of the window pointer returned by a successful call to the BuildSysRequest() procedure RESULT None BUGS SEE ALSO BuildSysRequest(), AutoRequest(), CloseWindow() intuition.library/GadgetBox intuition.library/GadgetBox NAME GadgetBox -- Return the absolute position and size of a gadget. (V50) SYNOPSIS Success = GadgetBox( Gadget, Domain, DomainType, Flags, Box ) ULONG GadgetBox( struct Gadget *, APTR, ULONG, ULONG, APTR ); FUNCTION Calculates the absolute position and size of a possibly GREL_ gadget relative to a specified domain. The domain can be a simple IBox structure, a Rectangle structure, or a Window, as indicated by the DomainType parameter. Starting with V51, the domain can also be a GadgetInfo structure. Some flags are also available to specify whether to calculate the gadget's hit box or its bounding box (if available), and whether the result must be in the form of an IBox structure or a Rectangle structure. The resulting position and size are stored in the data structure pointed to by the Box parameter. INPUTS Gadget = pointer to a gadget Domain = pointer to the domain, whose exact type is specified with the next parameter DomainType = type of domain; available types are: GBD_WINDOW -- the domain is a Window (default) GBD_BOX -- the domain is an IBox GBD_RECTANGLE -- the domain is a Rectangle GBD_GINFO -- the domain is a GadgetInfo (V51) Flags = additional options; available flags are: GBF_BOUNDS -- compute bounding box, not hit box GBF_MAKERECT -- result is a Rectangle, not an IBox Box = pointer to storage space for the result. This must allow for at least eight bytes (the size of an IBox structure) RESULT TRUE for success, FALSE for failure. Failure can be caused by an incorrect parameter, such as a NULL pointer. NOTES BOOPSI gadget implementors should always pass a GadgetInfo as domain. In all other cases, if the gadget is a window gadget (i.e. not a screen or requester gadget) it is advised to pass a window as domain whenever possible, in order to provide the maximum amount of context information. BUGS SEE ALSO intuition.library/GadgetMouse intuition.library/GadgetMouse NAME GadgetMouse -- Calculate gadget-relative mouse position. (V36) SYNOPSIS GadgetMouse( Gadget, GInfo, MousePoint ) VOID GadgetMouse( struct GadgetInfo *, WORD * ); FUNCTION Determines the current location of the mouse pointer relative to the upper-left corner of a custom gadget. Typically used only in the GM_HANDLEINPUT and GM_GOACTIVE custom gadget hook routines. NEWS FLASH!!: These two hook routines are now passed the mouse coordinates, so this function has no known usefulness. We recommend that you don't call it. Note that this function calculates the mouse position taking "gadget relativity" (GFLG_RELRIGHT, GFLG_RELBOTTOM) into consideration. If your custom gadget intends to ignore these properties, then you should either enjoin or inhibit your users from setting those bits, since Intuition won't ask if you respect them. INPUTS GInfo = A pointer to a GadgetInfo structure as passed to the custom gadget hook routine. MousePoint = address of two WORDS, or a pointer to a structure of type Point. RESULT Returns nothing. Fills in the two words pointed to by MousePoint with the gadget-relative mouse position. BUGS Useless, since equivalent information is now passed to every function that might have a use for this. SEE ALSO intuition.library/GetAttr intuition.library/GetAttr NAME GetAttr -- Inquire the value of some attribute of an object. (V36) SYNOPSIS uint32 attr = GetAttr(uint32 attrId, Object *object, uint32 *storage); FUNCTION Inquires from the specified object the value of the specified attribute. You always pass the address of a uint32 variable which will receive the same value that would be passed to SetAttrs() in the ti_Data portion of a TagItem element. See the documentation for the class for exceptions to this general rule. Not all attributes will respond to this function. Those that will are documented on a class-by-class basis. INPUTS attrId - the attribute tag ID understood by the object's class object - abstract pointer to the BOOPSI object you are interested in storage - pointer to appropriate storage for the answer RESULT attr - Returns 0 if the attribute inquery is not provided by the object's class. NOTES This function invokes the OM_GET method of the object. SEE ALSO NewObject(), DisposeObject(), SetAttrs(), MakeClass(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/GetAttrsA intuition.library/GetAttrsA NAME GetAttrsA - Obtain attributes for an object. (V50) SYNOPSIS uint32 retval = GetAttrsA(Object *object, struct TagItem *attrs); uint32 retval = GetAttrs(Object *object, Tag tag1, ...); FUNCTION This function is used to get one or more attributes of a BOOPSI object. INPUTS object - pointer to an object as returned by NewObjectA() attrs - attributes to get terminated with TAG_DONE. The data element of each pair contains the address of the storage variable. RESULT retval - contains the number of attributes the system was able to obtain SEE ALSO NewObject(), DisposeObject(), SetAttrs(), MakeClass(), GetAttr(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/GetDefaultPubScreen intuition.library/GetDefaultPubScreen NAME GetDefaultPubScreen -- Get name of default public screen. (V36) SYNOPSIS GetDefaultPubScreen( Namebuff ) VOID GetDefaultPubScreen( STRPTR ); FUNCTION Provides the name of the current default public screen. Only anticipated use is for Public Screen Manager utilities, since it is easy to open a visitor window on the default public screen without specifying the name. INPUTS Namebuff = a buffer of MAXPUBSCREENNAME. This can be NULL. RESULT None. Will provide the string "Workbench" in Namebuff if there is no current default public screen. NOTES This function actually "returns" in register D0 a pointer to the public screen. Unfortunately, the lifespan of this pointer is not ensured; the screen could be closed at any time. The *ONLY* legitimate use we can see for this return value is to compare for identity with the pointer to a public screen you either have a window open in, or a lock on using LockPubScreen(), to determine if that screen is in fact the default screen. Also note that if there no default public screen has been set, the return value of this function will be zero, and not a pointer to the Workbench screen. BUGS The function prototype does not reflect the return value. SEE ALSO SetDefaultPubScreen(), OpenWindow() intuition.library/GetDefPrefs intuition.library/GetDefPrefs NAME GetDefPrefs -- Get a copy of the the Intuition default Preferences. SYNOPSIS Prefs = GetDefPrefs( PrefBuffer, Size ) struct Preferences *GetDefPrefs( struct Preferences *, WORD ); FUNCTION Gets a copy of the Intuition default preferences data. Writes the data into the buffer you specify. The number of bytes you want copied is specified by the size argument. The default preferences are those that Intuition uses when it is first opened. If no preferences file is found, these are the preferences that are used. These would also be the startup preferences in an AmigaDOS-less environment. It is legal to take a partial copy of the Preferences structure. The more pertinent preferences variables have been grouped near the top of the structure to facilitate the memory conservation that can be had by taking a copy of only some of the Preferences structure. INPUTS PrefBuffer = pointer to the memory buffer to receive your copy of the Intuition Preferences structure Size = the number of bytes in your PrefBuffer, the number of bytes you want copied from the system's internal Preference settings RESULT Returns your parameter PrefBuffer. BUGS SEE ALSO GetPrefs() intuition.library/GetGUIAttrsA intuition.library/GetGUIAttrsA NAME GetGUIAttrsA -- Inquire the value of Intuition GUI attributes. (V50) GetGUIAttrs -- Varargs stub for GetGUIAttrsA(). (V50) SYNOPSIS Result = GetGUIAttrsA( Reserved, DrawInfo, TagList ) ULONG GetGUIAttrsA( APTR, struct DrawInfo *, struct TagItem * ); Result = GetGUIAttrs( Reserved, DrawInfo, Tag1, ... ) ULONG GetGUIAttrs( APTR, struct DrawInfo *, Tag, ... ); FUNCTION With this function you can get the values of one or more attributes defining the look or behavior of specific parts of the Intuition Graphic User Interface (GUI). The DrawInfo you pass to the function identifies a particular screen whose GUI attributes you're interested in reading. If you pass NULL as a DrawInfo, you'll be inquiring the global GUI preferences of Intuition, which are the default GUI attributes used for any screen before any individual preferences are set for it. The attributes are passed to this function as a list of tag items, defined in . The ti_Data field of each tag should hold a pointer to a longword-sized variable where the requested attribute value will be stored. This function is not meant to be used by normal applications, but rather by special components such as GUI-related libraries, BOOPSI classes or GUI plugins; these might need the information provided by GetGUIAttrsA() to adapt their rendering and behavior in order to stay consistent with the GUI preferences selected by the user. INPUTS Reserved = reserved for future use, set to NULL until further notice DrawInfo = pointer to a DrawInfo for the screen whose GUI attributes you want to inquire TagList = pointer to an array of tags specifying the attributes to inquire and appropriate storage for their values TAGS See for the full list of GUI attribute tags and a description of their meaning and possible values. EXAMPLES /* Read some GUI attributes of a screen */ ULONG framebuttonlook = FRAMEBUTTON_3D; ULONG reqposition = REQPOS_CORNER; struct TextAttr *gadtextattr = NULL; struct DrawInfo *dri; if (dri = GetScreenDrawInfo(screen)) { /* Find out the current look for button-like frames */ GetGUIAttrs(NULL,dri,GUIA_FrameButtonLook,&framebuttonlook,TAG_END); /* Find out the current gadget font and requester opening position */ GetGUIAttrs(NULL,dri,GUIA_GadgetTextAttr,&gadtextattr, GUIA_RequestersPosition,&reqposition, TAG_END); FreeScreenDrawInfo(screen,dri); } RESULT The number of GUI attributes successfully retrieved. NOTES SEE ALSO SetGUIAttrsA() intuition.library/GetHalfPens intuition.library/GetHalfPens NAME GetHalfPens -- Retrieve the half-intensity bright and dark variants of a background-like DrawInfo pen. (V50) SYNOPSIS Success = GetHalfPens( DrawInfo, BasePen, HalfShinePtr, HalfShadowPtr ) ULONG GetHalfPens( struct DrawInfo *, ULONG, UWORD *, UWORD * ); FUNCTION This function stores in the passed UWORDs the palette index numbers of the half-intensity bright and dark variants of a particular DrawInfo pen. The reference DrawInfo pen must be background-like, i.e. one that is used to fill some kind of background (such as BARBLOCKPEN, FILLPEN or BACKGROUNDPEN), and NOT a bright or dark variant itself. If the function succeeds, you can use the returned color numbers for as long as the screen associated to the passed DrawInfo stays open; you don't need to release the returned colors, Intuition will do that automatically when the screen closes. INPUTS DrawInfo = pointer to a DrawInfo structure associated to some screen BasePen = index of a background-like DrawInfo pen HalfShinePtr = pointer to an UWORD to hold the palette index of the half-bright variant of the DrawInfo pen HalfShadowPtr = pointer to an UWORD to hold the palette index of the half-dark variant of the DrawInfo pen EXAMPLES /* Get the half-bright and half-dark variants of FILLPEN */ UWORD fillhalfshine, fillhalfshadow; success = GetHalfPens(dri,FILLPEN,&fillhalfshine,&fillhalfshadow); RESULT TRUE if the function succeeded, FALSE otherwise. Failure can only be due to incorrect parameters. If the function fails, you should not expect the two passed UWORDs to contain any meaningful values. NOTES SEE ALSO intuition.library/GetPrefs intuition.library/GetPrefs NAME GetPrefs -- Get the current Intuition Preferences structure. SYNOPSIS Prefs = GetPrefs( PrefBuffer, Size ) struct Preferences *GetPrefs( struct Preferences *, WORD ); FUNCTION Gets a copy of the current Intuition Preferences structure. Writes the data into the buffer you specify. The number of bytes you want copied is specified by the size argument. It is legal to take a partial copy of the Preferences structure. The more pertinent preferences variables have been grouped near the top of the structure to facilitate the memory conservation that can be had by taking a copy of only some of the Preferences structure. New for V36: A new and more extensible method for supplying Preferences has been introduced in V36, and relies on file system notification. The Intuition preferences items rely also on the IPrefs program. Certain elements of the Preferences structure have been superseded by this new method. As much as possible, the Preferences structure returned by GetPrefs() reflect the current state of Preferences. However, it is impossible to represent some of the V36-style preferences items using the existing Preferences structure. INPUTS PrefBuffer = pointer to the memory buffer to receive your copy of the Intuition Preferences Size = the number of bytes in your PrefBuffer, the number of bytes you want copied from the system's internal Preference settings RESULT Returns your parameter PrefBuffer. BUGS SEE ALSO GetDefPrefs(), SetPrefs() intuition.library/GetRenderDomain intuition.library/GetRenderDomain NAME GetRenderDomain -- Get the logical container for GUI rendering. (V50) SYNOPSIS Status = GetRenderDomain( RastPort, Rectangle ) ULONG GetRenderDomain( struct RastPort *, struct Rectangle * ); FUNCTION Inquires about the current logical rendering domain for the RastPort. The domain is copied into the passed rectangle. If a domain rectangle was explicitly set for this RastPort, the function stores it into the passed rectangle and returns 1; otherwise the rectangle is filled with the full extent of the RastPort and the function returns 2. This way you always get an usable domain rectangle, but can still distinguish between one that was intentionally set with SetRenderDomain() and the default (fallback) domain rectangle. You can use the returned rectangle to layout your rendering in a more accurate way for the display element it applies to. Note that the domain rectangle does NOT represent the raster area you should fill, nor is it a "bounding box" for rendering; it just defines the visual extent of some GUI element the current rendering operations are drawing a part of. If you do not require this kind of information to correctly perform your rendering, you have no need to call this function. The rectangle is expressed in RastPort-relative coordinates, i.e. layer coordinates if the RastPort is layered, otherwise absolute BitMap coordinates. INPUTS RastPort = pointer to a RastPort Rectangle = pointer to a Rectangle RESULT 1 if an explicit domain rectangle was set in the RastPort, 2 if the returned domain is a fallback rectangle (the whole RastPort extent), or 0 for failure. Failure can be caused by an incorrect parameter, such as a NULL RastPort or Rectangle. BUGS SEE ALSO SetRenderDomain() intuition.library/GetScreenAttr intuition.library/GetScreenAttr NAME GetScreenAttr -- Query a screen attribute. (V50) SYNOPSIS Result = GetScreenAttr( Scr, Attr, Data, Size ) LONG GetScreenAttr( struct Screen *, ULONG, LONG, LONG ); FUNCTION To find out about a Screen attribute, you use GetScreenAttr(). The following attributes are recognized: SA_Left, SA_Top, SA_Width, SA_Height, SA_Depth - size is sizeof LONG. SA_DClip - returns the display region of the screen. Data must point to a struct Rectangle. Size is sizeof struct Rectangle. SA_PubName - (STRPTR) returns name of public screen. Data must point to a buffer of at least MAXPUBSCREENNAME+1 bytes. SA_Font - (struct TextAttr *) returns Scr->Font pointer. SA_BitMap - (struct BitMap *) same as Scr->RastPort.BitMap. SA_DisplayID - (ULONG) returns the display ID of the screen. SA_BlockPen, SA_DetailPen - (UBYTE) returns Scr->BlockPen, Scr->DetailPen. SA_Quiet - (BOOL) see ShowTitle(). SA_Interleaved - (BOOL) returns TRUE when the screen bitmap is interleaved. SA_Colors32 - (ULONG *) copies the screen colors into the given memory area. The format of the storage table must be the same as LoadRGB32() uses, this means that you need to initialize the first WORD with number of colors to get and the 2nd WORD with the index of the first color register to get. SA_ActiveWindow - (struct Window *) returns IntuitionBase->ActiveWindow when 'Scr' is the currently active screen otherwise you'll get pointer to the window that was active before a different screen went active. NOTE WELL: Due to multitasking issues there's no guarantee that the pointer you receive is still valid when this functions returns, it can be even NULL! SA_Compositing - (BOOL) returns TRUE when the screen builds its display through (usually 3D accelerated) real-time composition of off-screen rendered layers, rather than using the traditional layering system and refresh modes. SA_WindowDropShadows - (BOOL) returns TRUE when drop shadows are allowed for windows of this screen. Only meaningful if SA_Compositing is TRUE. See OpenScreen() for more details. INPUTS Scr = the screen Attr = the attribute to query Data = pointer to the storage variable Size = the size of the storage variable RESULT Result = number of bytes filled in or 0 for an error. EXAMPLE To get the display clip of the screen use: struct Rectangle rect; GetScreenAttr( scr, SA_DClip, &rect, sizeof( rect ) ); NOTES The 'Data' area must be at least 4 bytes large, no matter if the parameter is a byte or a word. BUGS SEE ALSO OpenScreen(), GetScreenAttrsA() intuition.library/GetScreenAttrsA intuition.library/GetScreenAttrsA NAME GetScreenAttrsA -- Query multiple screen attributes. (V50) GetScreenAttrs -- Varargs stub for the above. (V50) SYNOPSIS Result = GetScreenAttrsA( Scr, Tags ) LONG GetScreenAttrsA( struct Screen *, struct TagItem * ); LONG GetScreenAttrs( struct Screen *, Tag tag1, ... ); FUNCTION This is same as GetScreenAttr() except that you can query multiple attributes at once with this function. See GetScreenAttr() for all the details. INPUTS Scr = the screen Tags = the attributes to query. ti_Data holds a POINTER to the storage variable, which needs to be at least as large as an ULONG. RESULT Result = 0 for success, otherwise the number of the first attribute that couldn't be queried (1..n). EXAMPLE NOTES The memory area ti_Data points to must be at least 4 bytes large. BUGS SEE ALSO OpenScreen(), GetScreenAttr() intuition.library/GetScreenData intuition.library/GetScreenData NAME GetScreenData -- Get copy of a screen data structure. SYNOPSIS Success = GetScreenData( Buffer, Size, Type, Screen ) BOOL GetScreenData( APTR, UWORD, UWORD, struct Screen * ); FUNCTION This function copies into the caller's buffer data from a Screen structure. Typically, this call will be used to find the size, title bar height, and other values for a standard screen, such as the Workbench screen. To get the data for the Workbench screen, one would call: GetScreenData(buff, sizeof(struct Screen), WBENCHSCREEN, NULL) NOTE: if the requested standard screen is not open, this function will have the effect of opening it. This function has been useful for two basic types of things: 1) Determining information about the Workbench screen, in preparation for opening a window on it. 2) Attempts at discerning the user's preferences in a working screen, for "cloning" the Workbench modes and dimensions when opening a similar custom screen. Providing compatibility with both of these goals has proven difficult, as we introduce new display modes and screen scrolling in V36. Read carefully the somewhat involved exceptions we elected to implement ... Changes as of V36: For V36 and later, the function LockPubScreen() is an improvement over this function, in that it doesn't copy the screen data but returns a pointer and a guarantee that the screen will not be closed. If the global public screen SHANGHAI mode is in effect (see SetPubScreenModes() ), this function will actually report on the default public screen, where "Workbench" windows will actually open. For V36 and later, this function does some "compatibility tricks" when you inquire about the WBENCHSCREEN. To keep programs from "stumbling" into modes they don't understand, and because an NTSC machine may be running a PAL Workbench or PRODUCTIVITY, for example, the following "false" information is returned. The Screen.ViewPort.Modes field will either be HIRES or HIRES+LACE (with the SPRITES flag also set, as usual). HIRES+LACE is used if the display mode selected for the Workbench screen is an interlaced screen of any type. The dimensions returned will be the *smaller* of the OSCAN_TEXT dimensions for the returned mode, and the actual dimensions of the Workbench screen. EXCEPTION: For specific compatibility considerations, if the Workbench is in one of the A2024 modes, the mode returned in Screen.ViewPort.Modes will be HIRES+LACE (with perhaps some "special" bits also set for future improvement), but with dimensions equal to the actual A2024-mode Workbench screen. This will favor programs which open windows on the A2024 Workbench, but will cause some problems for programs which try to "clone" the Workbench screen using this function. If you want the real information about the modern Workbench screen, call LockPubScreen( "Workbench" ) and acquire its display mode ID by inquiring of the actual ViewPort (using graphics.library/GetVPModeID() ). You may then use the information you get to clone as many of the properties of the Workbench screen that you wish. In the long run, it's probably better to provide your user with a screen mode selection option, and skip all this. INPUTS Buffer = pointer to a buffer into which data can be copied Size = the size of the buffer provided, in bytes Type = the screen type, as specified in OpenWindow() (WBENCHSCREEN, CUSTOMSCREEN, ...) Screen = ignored, unless type is CUSTOMSCREEN, which results only in copying 'size' bytes from 'screen' to 'buffer' RESULT TRUE if successful FALSE if standard screen of Type 'type' could not be opened. BUGS You cannot support the new V36 display modes using this function. SEE ALSO OpenWindow(), LockPubScreen(), graphics.library/GetVPModeID(), SetPubScreenModes(), OpenScreen() intuition.library/GetScreenDrawInfo intuition.library/GetScreenDrawInfo NAME GetScreenDrawInfo -- Get pointer to rendering information. (V36) SYNOPSIS DrInfo = GetScreenDrawInfo( Screen ) struct DrawInfo *GetScreenDrawInfo( struct Screen * ); FUNCTION Returns a pointer to a DrawInfo structure derived from the screen passed. This data structure is READ ONLY. The field dri_Version identifies which version of struct DrawInfo you are given a pointer to. INPUTS Screen - pointer to a valid, open screen. RESULT DrInfo - pointer to a system-allocated DrawInfo structure, as defined in intuition/screens.h. NOTES Some information in the DrawInfo structure may in the future be calculated the first time this function is called for a particular screen. You must call FreeScreenDrawInfo() when you are done using the returned pointer. This function does not prevent a screen from closing. Apply it only to the screens you opened yourself, or apply a protocol such as LockPubScreen(). WARNING: Until further notice, the pointer returned does not remain valid after the screen is closed. This function and FreeScreenDrawInfo() don't really do much now, but they provide an upward compatibility path. That means that if you misuse them today, they probably won't cause a problem, although they may someday later. So, please be very careful only to use the DrawInfo structure between calls to GetScreenDrawInfo() and FreeScreenDrawInfo(), and be sure that you don't forget FreeScreenDrawInfo(). BUGS Does not reflect to changes in screen modes, depth, or pens. SEE ALSO FreeScreenDrawInfo(), LockPubScreen(), intuition/screens.h intuition.library/GetWindowAttr intuition.library/GetWindowAttr NAME GetWindowAttr -- Query a window attribute. (V50) SYNOPSIS Result = GetWindowAttr( Win, Attr, Data, Size ) LONG GetWindowAttr( struct Window *, ULONG, APTR, LONG ); FUNCTION Use GetWindowAttr() to query a window's attribute. The following attributes are recognized: WA_Left (int32 *) WA_Top (int32 *) WA_Width (int32 *) WA_Height (int32 *) WA_DetailPen (int32 *) WA_BlockPen (int32 *) WA_MinWidth (int32 *) WA_MinHeight (int32 *) WA_InnerWidth (int32 *) WA_InnerHeight (int32 *) WA_MaxWidth (int32 *) WA_MaxHeight (int32 *) WA_Zoom (struct IBox *) Zoom box of the window. When the window is in zoomed state, the current size is returned. WA_WindowBox (struct IBox *) The window position in a struct IBox. WA_IDCMP (uint32 *) WA_Flags (uint32 *) WA_MouseQueue (uint32 *) WA_RptQueue (uint32 *) WA_NotifyDepth (BOOL *) WA_TabletMessages (BOOL *) WA_MenuHelp (BOOL *) WA_PointerDelay (BOOL *) WA_RMBTrap (BOOL *) WA_WindowName (STRPTR *) WA_ShapeRegion (struct Region **) WA_ShapeHook (struct Hook **) WA_AlphaClips (struct ClipRect **) WA_AlphaHook (struct Hook **) WA_Opaqueness (uint8 *) WA_OverrideOpaqueness (BOOL *) WA_FadeTime (uint32 *) WA_NoHitThreshold (int32 *) WA_DropShadows (int32 *) WA_MenuStrip (struct Menu **) WA_ContextMenuHook (struct Hook **) WA_HelpGroup (uint32 *) WA_Activate (BOOL *) TRUE when window is the active one. WA_Checkmark (struct Image **) Returns pointer Win->CheckMark. WA_AmigaKey (struct Image **) Returns pointer of the Amiga-key equiv. in menus. See OpenWindow() for more details. INPUTS Win = the window Attr = the attribute to query Data = pointer to the storage variable Size = the size of the storage variable RESULT Result = number of bytes filled in or 0 for an error. EXAMPLE To get the current window dimension use: struct IBox box; GetWindowAttr( win, WA_WindowBox, &box, sizeof( box ) ); NOTES The 'Data' area must be at least 4 bytes no matter what the parameter type (e.g. BOOL). BUGS SEE ALSO OpenWindow(), GetWindowAttrsA() intuition.library/GetWindowAttrsA intuition.library/GetWindowAttrsA NAME GetWindowAttrsA -- Query multiple window attributes. (V50) GetWindowAttrs -- Varargs stub for the above. (V50) SYNOPSIS Result = GetWindowAttrsA( Win, Tags ) LONG GetWindowAttrsA( struct Window *, struct TagItem * ); Result = GetWindowAttrs( Win, Tag1, ... ) LONG GetWindowAttrs( struct Window *, Tag tag1, ... ); FUNCTION This is same as GetWindowAttr() except that you can query multiple attributes at once with this function. See GetWindowAttr() for all the details. INPUTS Win = the window Tags = the attributes to query. ti_Data holds a POINTER to the storage variable, which needs to be at least as large as an ULONG. RESULT Result = 0 for success, otherwise the number of the first attribute that couldn't be queried (1..n). EXAMPLE To query the zoom box and the mouse queue, you would use the following call: struct IBox zoom_box; LONG mouse_queue_length; LONG error_item; error_item = GetWindowAttrs(window, WA_Zoom, &zoom_box, WA_MouseQueue, &mouse_queue_length, TAG_END); NOTES The memory area pointed to by ti_Data must be at least 4 bytes large. BUGS SEE ALSO OpenWindow(), GetWindowAttr() intuition.library/HelpControl intuition.library/HelpControl NAME HelpControl -- Enable/disable Gadget-Help feature. (V39) SYNOPSIS HelpControl( window, flags ) VOID HelpControl( struct Window *, ULONG ); FUNCTION This function can be used to turn Gadget-Help on or off for your window. Gadget-Help will also be enabled/disabled accordingly for all other windows which share the same help-group. This allows Gadget-Help to be well-behaved for multiple-window applications. INPUTS window - Pointer to the window you wish to affect. (Other windows will also be affected, as explained above. flags - Currently, HC_GADGETHELP or zero are the allowed values. RESULT One or more windows will have Gadget-Help turned on or off. NOTES You must use utility.library/GetUniqueID() to get a help-group identifier. Never ever supply your own! SEE ALSO WA_HelpGroup intuition.library/HideWindow intuition.library/HideWindow NAME HideWindow -- Make visible window invisible (V50) SYNOPSIS Result = HideWindow( Window ) BOOL HideWindow( struct Window * ); FUNCTION Move this window behind the bottommost window and make all of its cliprects invisible. For SMARTREFRESH windows, copy all image data into the backing store of the window. This operation may generate refresh events for other windows located on the same screen. If the window is the active one Intuition will make it inactive and reject any attempts to make it active again while it is hidden. INPUTS Window = pointer to a window to hide RESULTS Result = TRUE if operation successful FALSE if operation unsuccessful (probably out of memory) BUGS SEE ALSO ShowWindow() intuition.library/ICoerceMethodA intuition.library/ICoerceMethodA NAME ICoerceMethodA -- Perform method on coerced object. (V50) ICoerceMethod -- Varargs stub for ICoerceMethodA(). (V50) SYNOPSIS uint32 result = ICoerceMethodA(Class *cl, Object *obj, Msg msg); uint32 result = ICoerceMethod(Class *cl, Object *obj, uint32 MethodID, ...); FUNCTION BOOPSI support function that invokes the supplied message on the specified object as though it were the specified class. INPUTS cl - pointer to BOOPSI class to receive the message obj - pointer to BOOPSI object msg - pointer to method-specific message to send RESULT result - class and message-specific result. NOTES Don't use this function unless you're a class implementor. There's no BOOPSI reentrancy protection when using this function. SEE ALSO IDoSuperMethodA(), DoGadgetMethodA(), IDoMethodA() intuition.library/IDoMethodA intuition.library/IDoMethodA NAME IDoMethodA -- Perform method on object. (V50) IDoMethod -- Varargs stub for IDoMethodA(). (V50) SYNOPSIS uint32 result = IDoMethodA(Object *obj, Msg msg); uint32 result = IDoMethod(Object *obj, uint32 MethodID, ...); FUNCTION BOOPSI support function that invokes the supplied message on the specified object. INPUTS obj - pointer to BOOPSI object msg - pointer to method-specific message to send RESULT result - specific to the message and the object's class. NOTES Don't use this function unless you're a class implementor. There's no BOOPSI reentrancy protection when using this function. SEE ALSO IDoSuperMethodA(), DoGadgetMethodA(), ISetSuperAttrsA() intuition.library/IDoSuperMethodA intuition.library/IDoSuperMethodA NAME IDoSuperMethodA -- Perform method on object coerced to superclass. (V50) IDoSuperMethod -- Varargs stub for IDoSuperMethodA(). (V50) SYNOPSIS uint32 result = IDoSuperMethodA(Class *cl, Object *obj, Msg msg); uint32 result = IDoSuperMethod(Class *cl, Object *obj, uint32 MethodID, ...); FUNCTION BOOPSI support function that invokes the supplied message on the specified object, as though it were the superclass of the specified class. INPUTS cl - pointer to BOOPSI class whose superclass is to receive the message obj - pointer to BOOPSI object msg - pointer to method-specific message to send RESULT result - class and message-specific result. NOTES Don't use this function unless you're a class implementor. There's no BOOPSI reentrancy protection when using this function. SEE ALSO ISetSuperAttrsA(), DoGadgetMethodA(), IDoMethodA() intuition.library/InitRequester intuition.library/InitRequester NAME InitRequester -- Initialize a Requester structure. SYNOPSIS InitRequester( Requester ) VOID InitRequester( struct Requester * ); FUNCTION Initializes a requester for general use. After calling InitRequester, you need fill in only those Requester values that fit your needs. The other values are set to NULL--or zero--states. Note that the example in the early versions of the Intuition Reference Manual is flawed because the Requester structure is initialized BEFORE InitRequester is called. Be sure to perform your initialization AFTER calling InitRequester. INPUTS Requester = a pointer to a Requester structure RESULT None BUGS Since the publication of the first Intuition Manual to this day, most people haven't used this function, and for compatibility reasons, we'll never be able to assume that they do. Thus, this function is useless. SEE ALSO intuition.library/IntuiTextExtent intuition.library/IntuiTextExtent NAME IntuiTextExtent -- Return the extent of a chain of IntuiTexts. (V50) SYNOPSIS Success = IntuiTextExtent( RastPort, IText, Extent ) ULONG IntuiTextExtent( struct RastPort *, struct IntuiText *, struct TextExtent * ); FUNCTION This routine computes the full pixel extent a chain of IntuiText structures would require when rendered into the specified RastPort. The passed TextExtent structure is filled with said information, in the following way: - te_Extent contains the minimum and maximum offsets of the rectangle where rendering can occur, relative to the starting coordinates passed to PrintIText(); - te_Width and te_Height hold the rectangle's size. NOTE: if the Font pointer of any IntuiText structure is set to NULL, you'll get the extent of its text in terms of the passed RastPort's font. INPUTS RastPort = pointer to a RastPort IText = pointer to the first item of an IntuiText chain Extent = pointer to a TextExtent structure RESULT Extent is filled with information describing the total pixel extent of the text specified by the IntuiText structures; returns TRUE if all went ok and the returned information is valid, FALSE otherwise (invalid parameters were passed to the function, or some memory allocation failed). BUGS SEE ALSO PrintIText(), IntuiTextLength() intuition.library/IntuiTextLength intuition.library/IntuiTextLength NAME IntuiTextLength -- Return the length (pixel-width) of an IntuiText. SYNOPSIS Length = IntuiTextLength( IText ) LONG IntuiTextLength( struct IntuiText * ); FUNCTION This routine accepts a pointer to an instance of an IntuiText structure, and returns the length (the pixel-width) of the string which that instance of the structure represents. NOTE: if the Font pointer of your IntuiText structure is set to NULL, you'll get the pixel-width of your text in terms of the current system default font. You may wish to be sure that the field IText->ITextFont for 'default font' text is equal to the Font field of the screen it is being measured for. INPUTS IText = pointer to an instance of an IntuiText structure RESULT Returns the pixel-width of the text specified by the IntuiText data BUGS Would do better to take a RastPort as argument, so that a NULL in the Font pointer would lead automatically to the font for the intended target RastPort, rather than the system default font. SEE ALSO OpenScreen() intuition.library/ISetSuperAttrsA intuition.library/ISetSuperAttrsA NAME ISetSuperAttrsA -- Invoke OM_SET method on superclass. (V50) ISetSuperAttrs -- Varargs stub for ISetSuperAttrsA(). (V50) SYNOPSIS uint32 result = ISetSuperAttrsA(Class *cl, Object *obj, struct TagItem *tags); uint32 result = ISetSuperAttrs(Class *cl, Object *obj, Tag tag1, ...); FUNCTION BOOPSI support function which invokes the OM_SET method on the superclass of the supplied class for the supplied object. INPUTS cl - pointer to BOOPSI class whose superclass is to receive the OM_SET message. obj - pointer to BOOPSI object tags - list of tag-attribute pairs, ending in TAG_DONE RESULT result - class and message-specific result. NOTES Don't use this function unless you're a class implementor. There's no BOOPSI reentrancy protection when using this function. SEE ALSO IDoSuperMethodA(), DoGadgetMethodA(), IDoMethodA() intuition.library/ItemAddress intuition.library/ItemAddress NAME ItemAddress -- Returns the address of the specified MenuItem. SYNOPSIS Item = ItemAddress( MenuStrip, MenuNumber ) struct MenuItem *ItemAddress( struct Menu *, UWORD ); FUNCTION This routine feels through the specified menu strip and returns the address of the item specified by the menu number. Typically, you will use this routine to get the address of a menu item from a menu number sent to you by Intuition after user has chosen from a window's menus. This routine requires that the arguments are well-defined. MenuNumber may be equal to MENUNULL, in which case this routine returns NULL. If MenuNumber doesn't equal MENUNULL, it's presumed to be a valid item number selector for your menu strip, which includes: - a valid menu number - a valid item number - if the item specified by the above two components has a sub-item, the menu number may have a sub-item component, too. Note that there must be BOTH a menu number and an item number. Because a sub-item specifier is optional, the address returned by this routine may point to either an item or a sub-item. INPUTS MenuStrip = a pointer to the first menu in your menu strip MenuNumber = the value which contains the packed data that selects the menu and item (and sub-item). See the Intuition Reference Manual for information on menu numbers. RESULT If MenuNumber == MENUNULL, this routine returns NULL, else this routine returns the address of the menu item specified by MenuNumber. BUGS SEE ALSO The "Menus" chapter of the Intuition Reference Manual, or the Amiga ROM Kernel Manual intuition.library/LendMenus intuition.library/LendMenus NAME LendMenus -- Lend window's menu action to another window. (V39) SYNOPSIS LendMenus( fromWindow, toWindow ) VOID LendMenus( struct Window *, struct Window * ); FUNCTION This function is used to "lend" the menus of one window to another. This means that menu events (for example, the user presses the mouse menu button) will take place in another window's menu (using that other window's menu strip and screen). The sole intended use of this function is to unify two windows on different screens that are attached. (See SA_Parent, SA_FrontChild, SA_BackChild). An example would be a program with a full-sized parent screen which has a short control panel screen attached in the front. Pressing the menu button even when the control panel window of the canvas screen is active can now cause the menus of the parent screen to appear. INPUTS fromWindow = pointer to the Window structure whose menu actions are to go to another window. toWindow = pointer to the Window structure whose menus are to be displayed in place of the fromWindow's. If NULL, turns off menu-lending from the fromWindow. RESULT None. BUGS The current behavior is such that the toWindow is temporarily activated. This may not continue to be the case. Be prepared to handle this! SEE ALSO SetMenuStrip(), ClearMenuStrip() intuition.library/LockIBase intuition.library/LockIBase NAME LockIBase -- Invoke semaphore arbitration of IntuitionBase. SYNOPSIS Lock = LockIBase( LockNumber ) ULONG LockIBase( ULONG ); FUNCTION Grabs Intuition internal semaphore so that caller may examine IntuitionBase safely. This function is not a magic "fix all my race conditions" panacea. The idea here is that you can get the locks Intuition needs before such IntuitionBase fields as ActiveWindow and FirstScreen are changed, or linked lists of windows and screens are changed. Do Not Get Tricky with this entry point, and do not hold these locks for long, as all Intuition input processing will wait for you to surrender the lock by a call to UnlockIBase(). NOTE WELL: A call to this function MUST be paired with a subsequent call to UnlockIBase(), and soon, please. NOTE WELL: Do not call any Intuition functions (nor any graphics, layers, dos, or other high-level system function) while holding this lock. INPUTS A long unsigned integer, LockNumber, specifies which of Intuition's internal locks you want to get. This parameter should be zero for all forseeable uses of this function, which will let you examine active fields and linked lists of screens and windows with safety. RESULT Returns another ULONG which should be passed to UnlockIBase() to surrender the lock gotten by this call. BUGS This function must not be called while holding any other system locks such as layer or LayerInfo locks. SEE ALSO UnlockIBase(), layers.library/LockLayerInfo(), exec.library/ObtainSemaphore() intuition.library/LockPubScreen intuition.library/LockPubScreen NAME LockPubScreen -- Prevent a public screen from closing. (V36) SYNOPSIS struct Screen *screen = LockPubScreen(CONST_STRPTR name); FUNCTION Prevents a public screen (or the Workbench) from closing while you examine it in preparation of opening a visitor window. The sequence you use to open a visitor window that needs to examine fields in the screen it is about to open on is: LockPubScreen() ... examine fields ... OpenWindow() on public screen UnlockPubScreen() ... use your window ... CloseWindow() NOTE You needn't hold the "pubscreen lock" for the duration that your window is opened. LockPubScreen() basically has the same effect as an open visitor window: it prevents the screen from being closed. If you pass the string "Workbench" or you pass NULL and there is no default public screen, the Workbench screen will be automatically opened if it is not already present. INPUTS name - name string for public screen or NULL for default public screen. The string "Workbench" indicates the Workbench screen. RESULT screen - Returns pointer to a screen if successful or NULL. The call can fail for reasons including that the named public screen doesn't exist or is in private state. SEE ALSO OpenWindow(), UnlockPubScreen(), GetScreenData() intuition.library/LockPubScreenList intuition.library/LockPubScreenList NAME LockPubScreenList -- Prevent changes to the system list. (V36) SYNOPSIS List = LockPubScreenList() struct List *LockPubScreenList( VOID ); FUNCTION Arbitrates access to public screen list while you quickly make a copy of it for display to the user. Note that this is intended only for the Public Screen Manager program. NOTES The nodes on the list are PubScreenNode structures. Act quickly while holding this lock. The restrictions on LockIBase() apply here as well. INPUTS None. RESULT A pointer to the public screen list. BUGS SEE ALSO UnlockPubScreenList(), OpenScreen(), Intuition V36 update documentation intuition.library/LockScreen intuition.library/LockScreen NAME LockScreen -- Do an Intuition friendly LockLayers(). (V50) SYNOPSIS Result = LockScreen( Scr, Micros ) BOOL LockScreen( struct Screen *, ULONG ); FUNCTION Before V50, applications wishing to block all screen rendering so that they can do "exceptional" rendering (eg. dragging icons, pop-up menus, etc.) need to call LockLayers(). Typically, however, such applications run the risk of deadlocking with Intuition, because they usually need information such as MOUSEMOVE messages. V50 introduces an Intuition-synchronized way of freezing a screen. The new LockScreen() and UnlockScreen() calls can be used to arbitrate access to the screen's bitmap. Intuition will behave much like it does when menus are down; that is to say that layer-related events such as window size, depth, or position changes are deferred until the screen is unfrozen. The application has the following obligations: 1. When UnlockScreen() is finally called, the screen's bitmap must be bit-for-bit the same as when you called LockScreen(), with the exception of rendering into your own windows' RastPorts. That is to say, you are responsible for doing non-destructive rendering during the time you have the screen frozen. 2. You may only make regular rendering calls (graphics calls, plus Intuition imagery functions such as PrintIText(), DrawImage(), DrawBorder()). Do not call any gadget refresh functions, OpenWindow(), Begin/EndRefresh(), etc. or any Intuition function that involves locking IntuitionBase (namely LockIBase()). 3. Don't freeze the screen on the user. Freeze it only in response to the user. Typically, if you don't unfreeze the screen when the user lets the mouse button go, you're freezing for too long. 4. Do not freeze a screen you don't own. It's OK to freeze a public screen (including the Workbench screen), or your own custom screen. If it's a public screen, be sure you hold a public-screen lock (see LockPubScreen()) or have a window open on it. The active window will still receive mouse-, keyboard- and timer- messages. So if you want your window to get the IDCMP messages, the following must be done: - make your window the active one, if it isn't (see ActivateWindow) - wait for IDCMP_ACTIVEWINDOW - then call LockScreen() - do your input processing. When receiving IDCMP_INACTIVEWINDOW abort and call UnlockScreen() (your window could have gone inactive before you had the chance to call LockScreen()) - when done, call UnlockScreen() INPUTS Scr = pointer to the screen to lock. Micros = specifies the time limit in microseconds within which the layers lock must be obtained. This functions returns FALSE when the screen cannot be locked before this time limit expires. RESULTS Result = TRUE if operation successful FALSE if operation unsuccessful (screen doesn't exist or is already locked). NOTES As of V50 locking a single screen means freezing ALL screens (without locking their layers!), so the user won't be able to continue working on a different screen. This may change in future releases of Intuition. BOOPSI class implementors must use the LockScreenGI() function. SEE ALSO UnlockScreen(), LockScreenGI() intuition.library/LockScreenGI intuition.library/LockScreenGI NAME LockScreenGI -- Do an Intuition friendly LockLayers(). (V50) SYNOPSIS RPort = LockScreenGI( GInfo, Micros ) struct RastPort *LockScreenGI( struct GadgetInfo *, ULONG ); FUNCTION This is same as LockScreen() except that this function is meant for custom class implementors. Instead of passing a screen pointer to this function, the GadgetInfo pointer from a BOOPSI message must be passed to it. INPUTS GInfo = the struct GadgetInfo you got from Intuition. Passing NULL is safe in which case the function fails. Micros = specifies the time limit in microseconds within which the layers lock must be obtained. This functions returns NULL when the screen cannot be locked before this timelimit expires. RESULTS RPort = a copy of the screen's rastport. Must be passed to UnlockScreenGI(). In case of a failure NULL is returned. This rastport can be used for rendering, as you already have a layers lock there's no need to call ObtainGIRPort(). NOTES GM_GOACTIVE, GM_GOINACTIVE and GM_HANDLEINPUT may not happen in the context of the same task. So never lock a screen in GM_GOACTIVE to release it later in GM_GOINACTIVE. It's okay to lock the screen in GM_HANDLEINPUT and release the lock in a different invocation of the same method. This is because once the screen is locked, Intuition will not attempt to abort your gadget while you hold the lock. SEE ALSO UnlockScreenGI(), LockScreen() intuition.library/LockScreenList intuition.library/LockScreenList NAME LockScreenList -- Prevent changes to the screen list. (V50) SYNOPSIS FirstScreen = LockScreenList() struct Screen *LockScreenList( VOID ); FUNCTION Arbitrates access to screen list while you quickly make a copy of it for display to the user. NOTES Act quickly while holding this lock. The restrictions on LockIBase() apply here as well. INPUTS None. RESULT A pointer to the first screen. BUGS SEE ALSO UnlockScreenList() intuition.library/MakeClass intuition.library/MakeClass NAME MakeClass -- Create and initialize a boopsi class. (V36) SYNOPSIS Class *iclass = MakeClass(ClassID classid, ClassID superclassid, const Class *superclassptr, uint16 instsize, uint32 flags); FUNCTION For class implementors only. This function creates a new public or private boopsi class. The superclass should be defined to be another boopsi class: all classes are descendants of the class "rootclass". Superclasses can be public or private. You provide a name/ID for your class if it is to be a public class (but you must have registered your class name and your attribute ID's with before you do this!). For a public class, you would also call AddClass() to make it available after you have finished your initialization. Returns pointer to a Class data structure for your class. You then initialize the Hook cl_Dispatcher for your class methods code. You can also set up special data shared by all objects in your class and point cl_UserData at it. The last step for public classes is to call AddClass(). You dispose of a class created by this function by calling FreeClass(). INPUTS classid - Name/ID string for public classes. NULL for private classes superclassid - Name/ID of your new class's superclass. NULL if superclass is a private class superclassptr - Pointer to private superclass. Only used if superclassid is NULL. You are required never to provide a NULL superclass. instsize - Size of the instance data that your class's objects will require, beyond that data defined for your superclass's objects. flags - For future enhancement including possible additional parameters. Provide zero for now. RESULT iclass - Pointer to the resulting class or NULL on error. Possible error conditions include: - no memory for class data structure - public superclass not found - public class of same name/ID already exists EXAMPLE Creating a private subclass of a public class: /* per-object instance data defined by my class */ struct MyInstanceData { uint32 mid_SomeData; }; /* some useful table I'll share use for all objects */ uint16 myTable[] = { 5, 4, 3, 2, 1, 0 }; Class * initMyClass() { uint32 myDispatcher(); Class *cl; Class *MakeClass(); if ( cl = MakeClass( NULL, SUPERCLASSID, NULL, /* superclass is public */ sizeof (struct MyInstanceData), 0 )) { /* initialize the cl_Dispatcher Hook */ cl->cl_Dispatcher.h_Entry = myDispatcher; cl->cl_Dispatcher.h_Data = 0xFACE; /* unused */ cl-cl_UserData = (uint32) myTable; } return ( cl ); } SEE ALSO FreeClass(), AddClass(), RemoveClass(), NewObject(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/MakeScreen intuition.library/MakeScreen NAME MakeScreen -- Do an Intuition-integrated MakeVPort() of a screen. SYNOPSIS failure = MakeScreen( Screen ) LONG MakeScreen( struct Screen * ); /* Returns LONG in V39 and greater */ FUNCTION This procedure allows you to do a MakeVPort() for the viewport of your custom screen in an Intuition-integrated way. This way you can do your own screen manipulations without worrying about interference with Intuition's usage of the same viewport. The operation of this function is as follows: - Block until the Intuition View structure is not in being changed. - Set the view modes correctly to reflect if there is a (visible) interlaced screen. - call MakeVPort(), passing the Intuition View and your screen's ViewPort. - Unlocks the Intuition View. After calling this routine, you should call RethinkDisplay() to incorporate the new viewport of your custom screen into the Intuition display. NOTE: Intuition may determine that because of a change in global interlace needs that all viewports need to be remade, so it may effectively call RemakeDisplay(). INPUTS Screen = address of the custom screen structure RESULT Starting with V39, returns zero for success, non-zero for failure. Probable cause of failure is failure of graphics.library/MakeVPort(). Prior to V39, the return code is invalid. Do not interpret it when running on pre-V39 systems! BUGS SEE ALSO RethinkDisplay(), RemakeDisplay(), graphics.library/MakeVPort() intuition.library/ModifyIDCMP intuition.library/ModifyIDCMP NAME ModifyIDCMP -- Modify the state of a window's IDCMPFlags. SYNOPSIS Success = ModifyIDCMP( Window, IDCMPFlags ) BOOL ModifyIDCMP( struct Window *, ULONG ); /* returns BOOL in V37 and greater */ FUNCTION This routine modifies the state of your window's IDCMP (Intuition Direct Communication Message Port). The state is modified to reflect your desires as described by the flag bits in the value IDCMPFlags. The four actions that might be taken are: - if there is currently no IDCMP in the given window, and IDCMPFlags is zero, nothing happens - if there is currently no IDCMP in the given window, and any of the IDCMPFlags is selected (set), then the IDCMP of the window is created, including allocating and initializing the message ports and allocating a signal bit for your port. See the "Input and Output Methods" chapter of the Intuition Reference Manual for full details - if the IDCMP for the given window exists, and the IDCMPFlags argument is zero, this says that you want Intuition to close the ports, free the buffers and free your signal bit. You MUST be the same task that was active when this signal bit was allocated (either by ModifyIDCMP() or OpenWindow() ). - if the IDCMP for the given window is opened, and the IDCMPFlags argument is not zero, this means that you want to change the state of which events will be broadcast to you through the IDCMP NOTE: You can set up the Window->UserPort to any port of your own before you call ModifyIDCMP(). If IDCMPFlags is non-null but your UserPort is already initialized, Intuition will assume that it's a valid port with task and signal data preset and Intuition won't disturb your set-up at all, Intuition will just allocate the Intuition message port half of it. The converse is true as well: if UserPort is NULL when you call here with IDCMPFlags == NULL, Intuition will deallocate only the Intuition side of the port. This allows you to use a port that you already have allocated: - OpenWindow() with IDCMPFlags equal to NULL (open no ports) - set the UserPort variable of your window to any valid port of your own choosing - call ModifyIDCMP with IDCMPFlags set to what you want - then, to clean up later, set UserPort equal to NULL before calling CloseWindow() (leave IDCMPFlags alone) BUT FIRST: you must make sure that no messages sent your window are queued at the port, since they will be returned to the memory free pool. For an example of how to close a window with a shared IDCMP, see the description for CloseWindow(). INPUTS Window = pointer to the Window structure containing the IDCMP ports IDCMPFlags = the flag bits describing the new desired state of the IDCMP. The flags are: - IDCMP_REQVERIFY is the flag which, like IDCMP_SIZEVERIFY and ... - IDCMP_MENUVERIFY (see immediately below), specifies that you want to make sure that your graphical state is quiescent before something extraordinary happens. In this case, the extraordinary event is that a rectangle of graphical data is about to be blasted into your Window. If you're drawing directly into its screen, you probably will wish to make sure that you've ceased drawing before the user is allowed to bring up the DMRequest you've set up, and the same for when system has a request for the user. Set this flag to ask for that verification step. - IDCMP_REQCLEAR is the flag you set to hear a message whenever a requester is cleared from your window. If you are using IDCMP_REQVERIFY to arbitrate access to your screen's bitmap, it is safe to start your output once you have heard an IDCMP_REQCLEAR for each IDCMP_REQSET. - IDCMP_REQSET is a flag that you set to receive a broadcast for each requester that is opened in your window. Compare this with IDCMP_REQCLEAR above. This function is distinct from IDCMP_REQVERIFY. This functions merely tells you that a requester has opened, whereas IDCMP_REQVERIFY requires you to respond before the requester is opened. - IDCMP_MENUVERIFY is the flag you set to have Intuition stop and wait for you to finish all graphical output to your window before rendering the menus. Menus are currently rendered in the most memory-efficient way, which involves interrupting output to all windows in the screen before the menus are drawn. If you need to finish your graphical output before this happens, you can set this flag to make sure that you do. - IDCMP_SIZEVERIFY means that you will be doing output to your window which depends on a knowledge of the current size of the window. If the user wants to resize the window, you may want to make sure that any queued output completes before the sizing takes place (critical text, for instance). If this is the case, set this flag. Then, when the user wants to size, Intuition will send you the IDCMP_SIZEVERIFY message and Wait() until you reply that it's OK to proceed with the sizing. NOTE: when we say that Intuition will Wait() until you reply, what we're really saying is that user will WAIT until you reply, which suffers the great negative potential of User-Unfriendliness. So remember: use this flag sparingly, and, as always with any IDCMP Message you receive, reply to it promptly! Then, after user has sized the window, you can find out about it using IDCMP_NEWSIZE. With all the "VERIFY" functions, it is not save to leave them enabled at any time when your task may not be able to respond for a long period. It is NEVER safe to call AmigaDOS, directly or indirectly, when a "VERIFY" function is active. If AmigaDOS needs to put up a disk requester for you, your task might end up waiting for the requester to be satisfied, at the same time as Intuition is waiting for your response. The result is a complete machine lockup. USE ModifyIDCMP() TO TURN OFF ANY VERIFY MESSAGES BEFORE CALLING dos.library!! For V36: If you do not respond to the verification IntuiMessages within the user specified timeout duration, Intuition will abort the operation. This eliminates the threat of these easy deadlocks, but can result in a confused user. Please try hard to continue to avoid "logical deadlocks". - IDCMP_NEWSIZE is the flag that tells Intuition to send an IDCMP message to you after the user has resized your window. At this point, you could examine the size variables in your window structure to discover the new size of the window. See also the IDCMP_CHANGEWINDOW IDCMP flag. New for V53.43 the Code field of the IntuiMessage is set to NSCODE_FINAL if this is the final IDCMP_NEWSIZE message. Otherwise Code is set to NSCODE_INTERIM. While opaque window resizing there are likely to be many NSCODE_INTERIM messages. - IDCMP_REFRESHWINDOW when set will cause a message to be sent whenever your window needs refreshing. This flag makes sense only with WFLG_SIMPLE_REFRESH and WFLG_SMART_REFRESH windows. - IDCMP_MOUSEBUTTONS will get reports about mouse-button up/down events broadcast to you (Note: only the ones that don't mean something to Intuition. If the user clicks the select button over a gadget, Intuition deals with it and you don't find out about it through here). - IDCMP_MOUSEMOVE will work only if you've set the WFLG_REPORTMOUSE flag above, or if one of your gadgets has the GACT_FOLLOWMOUSE flag set. Then all mouse movements will be reported here, providing your window is active. - IDCMP_GADGETDOWN means that when the User "selects" a gadget you've created with the GACT_IMMEDIATE flag set, the fact will be broadcast through the IDCMP. - IDCMP_GADGETUP means that when the user "releases" a gadget that you've created with the GACT_RELVERIFY flag set, the fact will be broadcast through the IDCMP. This message is only generated if the release is "good", such as releasing the select button over a Boolean gadget, or typing ENTER in a string gadget. - IDCMP_MENUPICK selects that menu number data will be sent via the IDCMP. - IDCMP_CLOSEWINDOW means broadcast the IDCMP_CLOSEWINDOW event through the IDCMP rather than the console. - IDCMP_RAWKEY selects that all IDCMP_RAWKEY events are transmitted via the IDCMP. Note that these are absolutely RAW keycodes, which you will have to translate before using. Setting this and the MOUSE flags effectively eliminates the need to open a Console device to get input from the keyboard and mouse. Of course, in exchange you lose all of the console features, most notably the "cooking" of input data and the systematic output of text to your window. - IDCMP_VANILLAKEY is for developers who don't want the hassle of IDCMP_RAWKEYS. This flag will return all the keycodes after translation via the current country-dependent keymap. When you set this flag, you will get IntuiMessages where the Code field has a decoded ANSI character code representing the key struck on the keyboard. Only codes that map to a single character are returned: you can't read such keys as HELP or the function keys with IDCMP_VANILLAKEY. NEW FOR V36: If you have both IDCMP_RAWKEY and IDCMP_VANILLAKEY set, Intuition will send an IDCMP_RAWKEY event for those *downstrokes* which do not map to single-byte characters ("non-vanilla" keys). In this way you can easily detect cursor keys, function keys, and the Help key without sacrificing the convenience of IDCMP_VANILLAKEY. NB: A side-effect of having both IDCMP_RAWKEY and IDCMP_VANILLAKEY set is that you never hear IDCMP_RAWKEY upstrokes, even for keys that caused IDCMP_RAWKEY downstrokes. - IDCMP_INTUITICKS gives you simple timer events from Intuition when your window is the active one; it may help you avoid opening and managing the timer device. With this flag set, you will get only one queued-up INTUITICKS message at a time. If Intuition notices that you've been sent an IDCMP_INTUITICKS message and haven't replied to it, another message will not be sent. Intuition receives timer events and considers sending you an IDCMP_INTUITICKS message approximately ten times a second. - IDCMP_DELTAMOVE gives raw (unscaled) input event delta X/Y values. This is so you can detect mouse motion regardless of screen/window/display boundaries. This works a little strangely: if you set both IDCMP_MOUSEMOVE and IDCMP_DELTAMOVE. IDCMPFlags, you will get IDCMP_MOUSEMOVE messages with delta x/y values in the MouseX and MouseY fields of the IDCMPMessage. - IDCMP_NEWPREFS indicates you wish to be notified when the system-wide Preferences changes. For V36, there is a new environment mechanism to replace Preferences, which we recommend you consider using instead. - Set IDCMP_ACTIVEWINDOW and IDCMP_INACTIVEWINDOW to get messages when those events happen to your window. Take care not to confuse this "ACTIVEWINDOW" with the familiar sounding, but totally different "WINDOWACTIVE" flag. These two flags have been supplanted by "IDCMP_ACTIVEWINDOW" and "WFLG_WINDOWACTIVE". Use the new equivalent terms to avoid confusion. - Set IDCMP_DISKINSERTED or IDCMP_DISKREMOVED to learn when removable disks are inserted or removed, respectively. - IDCMP_IDCMPUPDATE is a new class for V36 which is used as a channel of communication from custom and boopsi gadgets to your application. - IDCMP_CHANGEWINDOW is a new class for V36 that will be sent to your window whenever its dimensions or position are changed by the user or the functions SizeWindow(), MoveWindow(), ChangeWindowBox(), or ZipWindow(). - IDCMP_MENUHELP is new for V37. If you specify the WA_MenuHelp tag when you open your window, then when the user presses the HELP key on the keyboard during a menu session, Intuition will terminate the menu session and issue this even in place of an IDCMP_MENUPICK message. - NEVER follow the NextSelect link for MENUHELP messages. - You will be able to hear MENUHELP for ghosted menus. (This lets you tell the user why the option is ghosted.) - Be aware that you can receive a MENUHELP message whose code corresponds to a menu header or an item that has sub-items (which does not happen for MENUPICK). The code may also be MENUNULL. - LIMITATION: if the user extend-selects some checkmarked items with the mouse, then presses MENUHELP, your application will only hear the MENUHELP report. You must re-examine the state of your checkmarks when you get a MENUHELP. - Availability of MENUHELP in V36 is not directly controllable. We apologize... - IDCMP_GADGETHELP is new for V39. If you turn on gadget help for your window (using the HelpControl()) function, then Intuition will send IDCMP_GADGETHELP messages when the mouse passes over certain gadgets or your window. The IntuiMessage->Code field is normally ~0, but a boopsi gadget can return any word value it wishes. Ordinarily, gadget help is only processed for the active window. When Intuition has determined that the mouse is pointing at a gadget which has the GMORE_GADGETHELP property, you will be sent an IDCMP_GADGETHELP message whose IAddress points to the gadget. When the mouse is over your window but not over any help-aware gadget, you will be sent a message whose IAddress is the window itself. When the mouse is not over your window, Intuition sends a message whose IAddress is zero. A multi-window application can use the WA_HelpGroup or WA_HelpGroupWindow tags to indicate that all its windows belong in a group. (The help group identifier should be obtained with utility.library/GetUniqueID().) This makes Intuition test gadget help in all windows of the group when any one of them is the active one. Inactive windows whose WA_HelpGroup matches the active window's receive IDCMP_GADGETHELP messages when the mouse is over that window or any of its help-aware gadgets. The GADGETHELP message with an IAddress of zero means the mouse is not over the active window or any other window of the same group. It is always sent to the active window (which is not necessarily the window in your group that last got a message). To maximize performance, gadget help is not checked while the mouse is travelling quickly, or if it has not moved at all since the last test. As well, if Intuition discovers that the mouse is still over same gadget and that gadget does not wish to send a different IntuiMessage->Code from the last message, no new IntuiMessage is sent. - IDCMP_EXTENDEDMOUSE is a new class for V51 that will be sent to your window whenever the mousewheel is used. When the Code field of the IntuiMessage is set to EXMCODE_INTUIWHEELDATA the IAddress field points to the following structure: struct IntuiWheelData { UWORD Version; set to INTUIWHEELDATA_VERSION UWORD Reserved; always 0 UWORD WheelX; horizontal mouse wheel delta UWORD WheelY; vertical mouse wheel delta }; Do not make any assumptions about the contents of IMsg.IAddress when you find a different code than the one mentioned above! IDCMP_EXTENDEDMOUSE is only sent to the active window. RESULT Starting in V37, this function returns NULL if it was unable to create the necessary message ports. (The possibility of failure exists in earlier releases, but no return code was offered). Do not check the return code under V36 or earlier. BUGS SEE ALSO OpenWindowTagList(), OpenWindow(), CloseWindow() intuition.library/ModifyProp intuition.library/ModifyProp NAME ModifyProp -- Modify the current parameters of a proportional gadget. SYNOPSIS ModifyProp( Gadget, Window, Requester, Flags, HorizPot, VertPot, HorizBody, VertBody ) VOID ModifyProp( struct Gadget *, struct Window *, struct Requester *, UWORD, UWORD, UWORD, UWORD, UWORD ); FUNCTION Modifies the parameters of the specified proportional gadget. The gadget's internal state is then recalculated and the imagery is redisplayed in the window or requester that contains the gadget. The requester variable can point to a requester structure. If the gadget has the GTYP_REQGADGET flag set, the gadget is in a requester and the window pointer must point to the window of the requester. If this is not the gadget of a requester, the requester argument may be NULL. NOTE: this function causes all gadgets from the proportional gadget to the end of the gadget list to be refreshed, for reasons of compatibility. For more refined display updating, use NewModifyProp(). New for V36: ModifyProp() refreshing consists of redrawing gadgets completely. NewModifyProp() has changed this behavior (see NewModifyProp()). INPUTS PropGadget = pointer to a proportional gadget Window = pointer to the window containing the gadget or the window containing the requester containing the gadget. Requester = pointer to a requester (may be NULL if this isn't a requester gadget) Flags = value to be stored in the Flags field of the PropInfo HorizPot = value to be stored in the HorizPot field of the PropInfo VertPot = value to be stored in the VertPot field of the PropInfo HorizBody = value to be stored in the HorizBody field of the PropInfo VertBody = value to be stored in the VertBody field of the PropInfo RESULT None BUGS SEE ALSO NewModifyProp() The Intuition Reference Manual and Amiga ROM Kernel Manual contain more information on Proportional Gadgets. intuition.library/MoveScreen intuition.library/MoveScreen NAME MoveScreen -- Attempt to move the screen by the increments provided. SYNOPSIS MoveScreen( Screen, DeltaX, DeltaY ) VOID MoveScreen( struct Screen *, WORD, WORD ); FUNCTION Moves the screen the specified increment, specified in screen pixel resolution coordinates. New for V36: Screen movement limits have been greatly relaxed, to support screen scrolling. In particular, negative values for screen LeftEdge and TopEdge may now be valid. If the DeltaX and DeltaY variables you specify would move the screen in a way that violates any restrictions, the screen will be moved as far as possible. You may examine the LeftEdge and TopEdge fields of the Screen structure after this function returns to see where the screen really ended up. INPUTS Screen = pointer to a Screen structure DeltaX = amount to move the screen on the x-axis Note that DeltaX no longer (V36) need be set to zero DeltaY = amount to move the screen on the y-axis Note that these coordinates are in the same resolution as the screen (such as HIRES or INTERLACE) RESULT None BUGS SEE ALSO ScreenPosition(), RethinkDisplay() intuition.library/MoveWindow intuition.library/MoveWindow NAME MoveWindow -- Ask Intuition to move a window. SYNOPSIS MoveWindow( Window, DeltaX, DeltaY ) VOID MoveWindow( struct Window *, WORD, WORD ); FUNCTION This routine sends a request to Intuition asking to move the window the specified distance. The delta arguments describe how far to move the window along the respective axes. Note that the window will not be moved immediately, but rather will be moved the next time Intuition receives an input event, which happens currently at a minimum rate of ten times per second, and a maximum of sixty times a second. Interactions with other arbitration of Intuition data structures may defer this operation longer. For V36, you can use the new IDCMP class IDCMP_CHANGEWINDOW to detect when this operation has completed. New for V36: Intuition now will do validity checking on the final position. To send absolute movements, or to move and size a window in one step, use ChangeWindowBox(). INPUTS Window = pointer to the structure of the Window to be moved DeltaX = how far to move the Window on the x-axis DeltaY = how far to move the Window on the y-axis RESULT None BUGS SEE ALSO ChangeWindowBox(), SizeWindow(), WindowToFront(), WindowToBack() intuition.library/MoveWindowInFrontOf intuition.library/MoveWindowInFrontOf NAME MoveWindowInFrontOf -- Arrange the relative depth of a window. (V36) SYNOPSIS MoveWindowInFrontOf( Window, BehindWindow ) VOID MoveWindowInFrontOf( struct Window *, struct Window * ); FUNCTION Depth-arranges a window in front of an another window. Brings out the layers.library MoveLayerInFrontOf() to the Intuition user. INPUTS Window = window to re-position in front of another window BehindWindow = window to re-position in front of RESULT Repositions window. BUGS Doesn't respect backdrop windows. SEE ALSO WindowToFront(), WindowToBack(), layers.library/MoveLayerInFrontOf() intuition.library/NewModifyProp intuition.library/NewModifyProp NAME NewModifyProp -- ModifyProp(), but with selective refresh. SYNOPSIS NewModifyProp( Gadget, Window, Requester, Flags, HorizPot, VertPot, HorizBody, VertBody, NumGad ) VOID NewModifyProp( struct Gadget *, struct Window *, struct Requester *, UWORD, UWORD, UWORD, UWORD, UWORD, WORD ); FUNCTION Performs the function of ModifyProp(), but refreshes gadgets in the list as specified by the NumGad parameter. With NumGad = -1, this function is identical to ModifyProp(). New for V36: When NumGad = 1, this function will now perform an incremental update of the proportional gadget knob image, rather than refreshing the entire gadget. This means much less flashing when programmatically scrolling a proportional gadget. INPUTS PropGadget = pointer to a proportional gadget Window = pointer to the window containing the gadget or the window containing the requester containing the gadget. Requester = pointer to a requester (may be NULL if this isn't a requester gadget) Flags = value to be stored in the Flags field of the PropInfo HorizPot = value to be stored in the HorizPot field of the PropInfo VertPot = value to be stored in the VertPot field of the PropInfo HorizBody = value to be stored in the HorizBody field of the PropInfo VertBody = value to be stored in the VertBody field of the PropInfo NumGad = number of gadgets to be refreshed after propgadget internals have been adjusted. -1 means "to end of list." RESULT None BUGS SEE ALSO ModifyProp() The Intuition Reference Manual contains more information on Proportional Gadgets. intuition.library/NewObject intuition.library/NewObject NAME NewObjectA -- Create an object from a class. (V36) NewObject -- Varargs stub for NewObjectA(). (V36) SYNOPSIS Object *object = NewObjectA(Class *cl, ClassID classID, const struct TagItem *tags); Object *object = NewObject(Class *cl, ClassID classID, Tag tag1, ...); FUNCTION This is the general method of creating objects from BOOPSI classes. (BOOPSI stands for "Basic Object-Oriented Programming System for Intuition".) You specify a class either as a pointer (for a private class) or by its ID string (for public classes). If the class pointer is NULL, then the classID is used. You further specify initial "create-time" attributes for the object via a TagItem list, and they are applied to the resulting generic data object that is returned. The attributes, their meanings, attributes applied only at create-time, and required attributes are all defined and documented on a class-by-class basis. INPUTS cl - abstract pointer to a BOOPSI class gotten via MakeClass(). classID - the name/ID string of a public class. This parameter is only used if 'class' is NULL. tags - pointer to array of TagItems containing attribute/value pairs to be applied to the object being created RESULT object - A BOOPSI object, which may be used in different contexts such as a Gadget or Image and may be manipulated by generic functions. You eventually free the object using DisposeObject(). NOTES This function invokes the OM_NEW "method" for the class specified. SEE ALSO DisposeObject(), SetAttrs(), GetAttr(), MakeClass(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/NextObject intuition.library/NextObject NAME NextObject -- iterate through the object on an Exec list. (V36) SYNOPSIS Object *object = NextObject(Object **objectPtrPtr); FUNCTION This function is for BOOPSI class implementors only. When you collect a set of BOOPSI objects on an Exec List structure by invoking their OM_ADDMEMBER method, you can (only) retrieve them by iterations of this function. Works even if you remove and dispose the returned list members in turn. INPUTS Initially, you set a pointer variable to equal the lh_Head field of the list (or mlh_Head field of a MinList). You pass the *address* of that pointer repeatedly to NextObject() until it returns NULL. EXAMPLE /* here is the OM_DISPOSE case of some class's dispatcher */ case OM_DISPOSE: /* dispose members */ object_state = mydata->md_CollectionList.lh_Head; while ( member_object = NextObject( &object_state ) ) { IDoMethod( member_object, OM_REMOVE ); /* remove from list */ IDoMethodA( member, msg ); /* and pass along dispose */ } RESULT object - Returns pointers to each object in the list in turn and NULL when there are no more. SEE ALSO DisposeObject(), SetAttrs(), GetAttr(), MakeClass(), Document "Basic Object-Oriented Programming System for Intuition" and the --boopsi-- section of the intuition.doc autodoc. intuition.library/NextPubScreen intuition.library/NextPubScreen NAME NextPubScreen -- Identify next public screen in the cycle. (V36) SYNOPSIS Buff = NextPubScreen( Screen, NameBuff ) STRPTR NextPubScreen( struct Screen *, STRPTR ); FUNCTION Returns name of next public screen in system rotation, to allow visitor windows to provide function to "jump" among public-screens in a cycle. INPUTS Screen = pointer to the screen your window is currently open in, or NULL, if you don't have a pointer to a public screen. NameBuff = pointer to a buffer of MAXPUBSCREENNAME+1 characters, for Intuition to fill in with the name of the next public screen in rotation. RESULT Returns NULL if there are no public screens, otherwise a pointer to your NameBuff. NOTES There is no guarantee that the public screen whose name was returned by this function will exist or be in "public" state by the time you call LockPubScreen(), etc. You must handle cases where LockPubScreen(), etc. will fail. Note that this function may return the name of a public screen which is open but in "private mode" (see PubScreenStatus() and PSNF_PRIVATE). BUGS Due to a bug, your buffer needs to be (MAXPUBSCREENNAME + 1) characters big, which is one more than originally documented. The starting screen and cycle order of the public screens isn't defined, so do not draw conclusions about the order you see in the current version of Intuition. We reserve the right to add meaning to the ordering at a future time. SEE ALSO OpenScreen(), Intuition V36 update documentation intuition.library/ObtainBitMapInstanceA intuition.library/ObtainBitMapInstanceA NAME ObtainBitMapInstanceA -- Get a lock on a shared bitmap object. (V50) ObtainBitMapInstance -- Varargs stub for ObtainBitMapInstanceA(). (V50) SYNOPSIS Instance = ObtainBitMapInstanceA( Source, Screen, TagList ) APTR ObtainBitMapInstanceA( APTR, struct Screen *, struct TagItem * ); Instance = ObtainBitMapInstance( Source, Screen, Tag1, ... ) APTR ObtainBitMapInstance( APTR, struct Screen *, Tag, ... ); FUNCTION This function is used to derive a ready-to-use bitmap from a bitmap source object obtained from ObtainBitMapSourceA(). It returns an opaque handle to a "bitmap instance" object from which you can read (with BitMapInstanceControlA()) the actual bitmap pointer and other useful information like width, height, or a possible mask plane. The returned bitmap will have been remapped or otherwise adapted to the specified screen, so that it can have a correct appearance when displayed on it. The advantage of using this method, rather than just loading and remapping a picture through datatypes, is that bitmaps generated with ObtainBitMapInstanceA() (just like bitmap sources loaded with ObtainBitMapSourceA()) are cached in memory as sharable data. This means that there will always be at most one copy of a particular bitmap (remapped for a specific screen) in memory, that several applications can use simultaneously for their rendering purposes. In case the target screen is hicolor or truecolor, the generated bitmap will even be sharable for use on all screens with the same pixel format. Another advantage is that every bitmap instance object contains a built-in backfill hook, using the bitmap as a tile, which can be directly fed to any system components employing backfill hooks. Additionally, the backfill hook of a bitmap instance is able - if the appropriate tags are passed to ObtainBitMapInstanceA() - to render "shaded" (brighter or darker) variants of its bitmap when requested, and even to draw a gradient effect (stand-alone, or superimposed to the tiled bitmap). In fact, ObtainBitMapInstanceA() is the most convenient way to generate a backfill hook which is aware of the Release 4 Intuition's new cosmetic features. You can supply a few parameters in the form of tag items which define the attributes of the returned bitmap instance. The parameters you specify are taken into account when deciding whether an existing bitmap instance is suitable for the current request; only those instances that were generated with matching (or otherwise equivalent) parameters are acceptable candidates. When you no longer need the bitmap instance, you should release it with ReleaseBitMapInstance(). Once the usage count of the object is zero, its memory will actually be freed. It is legal to release a bitmap instance even after having already released its source object. INPUTS Source = pointer to a bitmap source to instantiate Screen = pointer to the screen the bitmap will be displayed on TagList = pointer to an array of tags providing extra parameters TAGS These are the tags defined for ObtainBitMapInstanceA() as of V50: BMI_Exclusive - (BOOL) If TRUE, a new bitmap instance for the given source will be generated, even if one already exists which is suitable for display on the specified screen. The returned instance won't be usable by anyone else either. Use this tag sparingly, as it defies the purpose of bitmap sharing; it is provided for those rare cases where sharing a bitmap instance is not an option. Default is FALSE. OBP_Precision - (LONG) The precision level to use when remapping the picture on a CLUT (palette-mapped) screen; set this to one of the PRECISION_ constants defined in . (Note: you might always get a bitmap remapped with _higher_ precision than what you ask for, if one exists that matches your request in all other aspects.) Default is PRECISION_IMAGE. The following tags only apply if you're going to use the bitmap instance as a backfill hook: BMI_LayerInfo - (BOOL) Set this to TRUE if the backfill hook provided by the bitmap instance is going to be used as a LayerInfo backfill hook. Default is FALSE. BMI_Offsets - (ULONG) With this tag you can specify a couple of (left, top) offsets, packed in a single longword, that the backfill hook will add to the offset values received in the backfill message to determine the alignment of the tiles. Default is (0, 0). BMI_DoLevels - (BOOL) If TRUE, the function will generate four additional bitmaps from the given source, in addition to the main one. Each of these bitmaps represents a shaded (brighter or darker) variant of the original image, and is used by the instance's backfill hook when it is called by Intuition to fill bright or dark details of a pseudo-3D shape. Applications will usually not need to use this tag; its main usefulness is to speed up rendering, as the cached bitmaps avoid the need of performing shading in real time. Default is FALSE. BMI_ReferencePen - (UWORD) When using BMI_DoLevels, you should specify a reference DrawInfo pen index with this tag; it will be used to decide the exact level of contrast used for brightening and darkening the main bitmap. This is because each DrawInfo pen can have different (user defined) contrast levels for its brighter and darker shades. You should choose a DrawInfo pen which closely matches the purpose of the backfill hook you're generating (e.g. choose INACTIVEFILLPEN if the backfill is going to be used to fill inactive window borders). Default is BACKGROUNDPEN. The following tags only apply if you want to make the instance's backfill hook draw a gradient effect in place of (or in addition to) the tiled pattern: BMI_GradientSpec - (struct GradientSpec *) You can use this tag to pass a pointer to an initialized GradientSpec structure. The backfill hook of the returned bitmap instance will use this specification to fill its target area with a gradient effect, rather than with the tiled bitmap. You can also set the GRADMODE_IMPOSE flag to have the gradient superimposed to the bitmap. This doesn't affect the original bitmap, which can always be retrieved with BitMapInstanceControlA(). If you pass this tag with a valid GradientSpec pointer and don't need any bitmap for the gradient effect of the backfill hook, you may pass NULL as bitmap source pointer. The GradientSpec you pass is copied, so you can reuse or free its memory once the function returns. Default is NULL. BMI_CacheGradient - (ULONG) You can use this tag to tell the function to generate a rasterized version of the gradient described by the passed GradientSpec, in order to speed up the backfill hook's rendering. This can only be done if the gradient has a straight horizontal or vertical orientation, and is NOT to be superimposed to the original bitmap (if one exists). Also, a rasterized gradient can only be tiled along ONE axis, for obvious reasons. The value passed with this tag is a couple of UWORDs packed in a longword, that specify the width and height the rasterized gradient tile must have. Both sizes must be greater than zero. If you rasterize a gradient, the original bitmap is lost and replaced by the cached gradient bitmap. Default is zero (no gradient caching). BMI_GradientAxis - (ULONG) To help Intuition optimize the rendering of rasterized horizontal or vertical gradients, you can indicate with this tag the axis along which the backfill hook's gradient should be considered free to be tiled. Possible values are 1 (horizontal) or 2 (vertical). Default is zero, meaning no information is available. EXAMPLES /* Load a picture and extract its bitmap for rendering */ APTR source, instance; struct BitMap *bitmap; ULONG width, height; if (source = ObtainBitMapSource("WORK:Pictures/Foo.png",TAG_END)) { if (instance = ObtainBitMapInstance(source,myscreen,TAG_END)) { BitMapInstanceControl(instance,BMICTRL_GetBitMap,&bitmap, BMICTRL_GetWidth,&width, BMICTRL_GetHeight,&height, TAG_END); /* Now use the bitmap as needed */ ... ReleaseBitMapInstance(instance); } ReleaseBitMapSource(source); } RESULT An opaque handle to a bitmap instance object if successful, or NULL if anything went wrong. Failure is usually due to lack of memory. NOTES SEE ALSO ReleaseBitMapInstance(), ObtainBitMapSourceA(), BitMapInstanceControlA() intuition.library/ObtainBitMapSourceA intuition.library/ObtainBitMapSourceA NAME ObtainBitMapSourceA -- Load a picture as a sharable template. (V50) ObtainBitMapSource -- Varargs stub for ObtainBitMapSourceA(). (V50) SYNOPSIS APTR source = ObtainBitMapSourceA(CONST_STRPTR name, struct TagItem *tags); APTR source = ObtainBitMapSource(CONST_STRPTR name, Tag tag1, ...); FUNCTION This function can be used to obtain a lock on an abstract "source" of graphic data read from a picture file via datatypes. The returned handle can then be passed to ObtainBitMapInstanceA() to generate an actual bitmap suitable for display on a particular screen. The advantage of using this function rather than loading directly with datatypes lies in the sharing of the loaded data. The picture file whose name you specify might be loaded from disk as a result of this call, in which case a new "source" object is created from it and returned to you. However, if a source object for that file does already exist in memory (for example, because another program loaded it first), the file is NOT loaded again; instead, you're just returned the already existing object, which you can then access in shared mode until you relinquish your lock on it. This means that for any picture file on disk there will always be at most one "bitmap source" in memory, which several applications can use simultaneously as a template to generate bitmap instances for different screens, resolutions and color depths. This data sharing saves memory, disk access and computation time. You can specify a few parameters in the form of tag items which control the behavior of this function and the attributes of the loaded bitmap source object. When you no longer need the source object, you should release it with ReleaseBitMapSource(). Once the usage count of the object is zero, and all of the bitmap instances obtained from it have been released as well, its memory will be actually freed. It is legal to release a bitmap source before having released all of its bitmap instances; it will stay around as long as necessary. INPUTS name - name of the picture file to load (if not already in memory) tags - pointer to an array of tags providing extra parameters TAGS These are the tags defined for ObtainBitMapSourceA() as of V50: BMS_NoDiskIO - (BOOL) If TRUE, the function will avoid accessing the disk when attempting to retrieve the named picture. If the picture object is already in memory (because some other program loaded it first) the function will succeed, otherwise it will fail and return NULL. Default is FALSE. BMS_DoMask - (BOOL) If TRUE, a mask plane will be generated for the loaded picture (if possible), which can then be used to blit the bitmap instances generated from this source with partial transparency. By default, the mask is extracted from the picture file itself, if the needed information is found. It can also be supplied by an external picture file which must be named as the main file to be loaded, plus a ".mask" extension. The picture read from this additional file MUST have exactly one bitplane and the same width and height as the main picture. Default is FALSE. The next two tags are mainly useful when dealing with bitmap sets used for GUI customization, and can be safely ignored for normal pictures by most applications. BMS_DoOutline - (BOOL) This is similar to BMS_DoMask in that it generates a mask plane for the loaded picture; but this mask will always be loaded from an additional file, which must be named as the main file plus a ".outl" extension. The same requirements as for the regular mask file apply. This "outline" mask is intended to provide a recognizable outline of the image represented by the main picture, that can be used to achieve particular graphic effects such as drawing a recessed "disabled" version of said image (for which, in most cases, the normal mask would look too bulky). BMS_DoShade - (BOOL) If TRUE, the function will try to read a number of additional picture files which (if present) hold different kind of alpha channel information, which the bitmap instances generated from the loaded source will be able to use when blitting themselves on hicolor or truecolor screens. All of these optional files must be named as the main file, plus different extensions: ".shin" for a shine map, ".shad" for a shadow map, ".amap" for an alpha blending map, and ".omap" for an alpha outline map (equivalent to the outline mask, but with a smoother appearance due to alpha blending). All of these picture files must have the exact same width and height as the main file, and a 256-color palette where each palette index represents an alpha blending level. Note: starting with V51, the alpha blending map is extracted from the picture file itself, if the needed information is found (that is, if the relevant datatype supports it). This can still be overridden by the ".amap" file, if present. See the Release 4 Intuition documentation for more details on the different types of alpha effects and their purposes. EXAMPLES /* Load a simple picture file as a shared "source" object */ APTR source; if (source = ObtainBitMapSource("WORK:Pictures/Foo.png",TAG_END)) { /* Use it as needed, and then... */ ReleaseBitMapSource(source); } RESULT An opaque handle to the bitmap source object, if it was found, or NULL if the picture didn't exist in memory and couldn't be loaded from disk either. SEE ALSO ReleaseBitMapSourceA(), ObtainBitMapInstanceA() intuition.library/ObtainGIRPort intuition.library/ObtainGIRPort NAME ObtainGIRPort -- Set up a RastPort for a custom gadget. (V36) SYNOPSIS struct RastPort *rport = ObtainGIRPort(struct GadgetInfo *ginfo); FUNCTION Sets up a RastPort for use (only) by custom gadget hook routines. This function must be called EACH time a hook routine needing to perform gadget rendering is called, and must be accompanied by a corresponding call to ReleaseGIRPort(). Note that if a hook function passes you a RastPort pointer, e.g., GM_RENDER, you needn't call ObtainGIRPort() in that case. INPUTS ginfo - A pointer to a GadgetInfo structure as passed to each custom gadget hook function. Safe to call with a NULL pointer in which case it returns NULL. RESULT A pointer to a RastPort that may be used for gadget rendering. This pointer may be NULL in which case you should do no rendering. You may (optionally) pass a NULL return value to ReleaseGIRPort(). SEE ALSO ReleaseGIRPort(), Custom Gadget documentation intuition.library/ObtainIBackFill intuition.library/ObtainIBackFill NAME ObtainIBackFill -- Lock and return an Intuition backfill hook. (V50) SYNOPSIS Hook = ObtainIBackFill( DrawInfo, Element, State, Flags ) struct Hook *ObtainIBackFill( struct DrawInfo *, ULONG, ULONG, ULONG ); FUNCTION Returns the address of the backfill hook used by Intuition to fill the background of a particular user interface element, on the screen associated with the specified DrawInfo. If the backfill hook was derived from user preferences, it is also locked in order to guarantee that it doesn't go away until released, even if the user preferences change in the meantime. You can specify the interface element whose backfill hook you're inquiring about, and also the exact state of that element (since an element can use different backfills for different states). You're advised to use this function, rather than GetGUIAttrsA(), to retrieve the address of an Intuition backfill hook; using GetGUIAttrsA() doesn't guarantee the validity of the returned hook, which could change and even be freed at any time. Once you're done with the backfill hook, you MUST release it with ReleaseIBackFill(). Failure to do so will eventually result in loss of memory. INPUTS DrawInfo = pointer to a DrawInfo structure Element = one of the BT_#? background types from intuition/gui.h State = one of the IDS_#? states from intuition/imageclass.h Flags = reserved for now, always pass zero until further notice RESULT The requested backfill hook address, or NULL if the specified interface element doesn't use any backfill. BUGS SEE ALSO ReleaseIBackFill() intuition.library/OffGadget intuition.library/OffGadget NAME OffGadget -- Disable the specified gadget. SYNOPSIS OffGadget( Gadget, Window, Requester ) VOID OffGadget( struct Gadget *, struct Window *, struct Requester * ); FUNCTION This command disables the specified gadget. When a gadget is disabled, these things happen: - its imagery is displayed ghosted - the GFLG_DISABLED flag is set - the gadget cannot be selected by User The window parameter must point to the window which contains the gadget, or which contains the requester that contains the gadget. The requester parameter must only be valid if the gadget has the GTYP_REQGADGET flag set, a requirement for all requester gadgets. NOTE: it's never safe to tinker with the gadget list yourself. Don't supply some gadget that Intuition hasn't already processed in the usual way. NOTE: for compatibility reasons, this function will refresh all gadgets in a requester, and all gadgets from gadget to the end of the gadget list if gadget is in a window. If you want to improve on this behavior, you may perform the equivalent operation yourself: remove a gadget or gadgets, change the state of their GFLG_DISABLED flag, replace the gadgets using AddGList(), and selectively call RefreshGList(). INPUTS Gadget = pointer to the gadget that you want disabled Window = pointer to a window structure containing the gadget or containing the requester which contains the gadget Requester = pointer to a requester (may by NULL if this isn't a requester gadget (i.e. GTYP_REQGADGET is not set)). RESULT None BUGS SEE ALSO OnGadget(), AddGadget(), RefreshGadgets() intuition.library/OffMenu intuition.library/OffMenu NAME OffMenu -- Disable the given menu or menu item. SYNOPSIS OffMenu( Window, MenuNumber ) VOID OffMenu( struct Window *, UWORD ); FUNCTION This command disables a sub-item, an item, or a whole menu. This depends on the contents of the data packed into MenuNumber, which is described in the Intuition Reference Manual. INPUTS Window = pointer to the window MenuNumber = the menu piece to be disabled RESULT None BUGS SEE ALSO OnMenu(), ResetMenuStrip() intuition.library/OnGadget intuition.library/OnGadget NAME OnGadget -- Enable the specified gadget. SYNOPSIS OnGadget( Gadget, Window, Requester ) VOID OnGadget( struct Gadget *, struct Window *, struct Requester * ); FUNCTION This command enables the specified gadget. When a gadget is enabled, these things happen: - its imagery is displayed normally (not ghosted) - the GFLG_DISABLED flag is cleared - the gadget can thereafter be selected by the user The window parameter must point to the window which contains the gadget, or which contains the requester that contains the gadget The requester parameter must only be valid if the gadget has the GTYP_REQGADGET flag set, a requirement for all requester gadgets. NOTE: it's never safe to tinker with the gadget list yourself. Don't supply some gadget that Intuition hasn't already processed in the usual way. NOTE: for compatibility reasons, this function will refresh all gadgets in a requester, and all gadgets from gadget to the end of the gadget list if gadget is in a window. If you want to improve on this behavior, you may perform the equivalent operation yourself: remove a gadget or gadgets, change the state of their GFLG_DISABLED flag, replace the gadgets using AddGList(), and selectively call RefreshGList(). INPUTS Gadget = pointer to the gadget that you want disabled Window = pointer to a window structure containing the gadget or containing the requester which contains the gadget Requester = pointer to a requester (may by NULL if this isn't a requester gadget (i.e. GTYP_REQGADGET is not set)). RESULT None BUGS Traditional gadgets are rendered very simply. This can result in incomplete clearing away of the ghosting pattern when OnGadget() is used. For example, a button whose imagery consists of an IntuiText inside a rectangular Border doesn't have the button interior cleared by OnGadget(). This is because OnGadget() clears the GFLG_DISABLED flag then redraws the gadget. Redrawing this gadget consists of redrawing the border and text. Nothing redraws the field. The solution to this type of problem is to either use a gadget whose imagery is a struct Image that covers the whole select area, or to manually remove the gadget, erase the gadget's select area (say using EraseRect()), then clear the GFLG_DISABLED flag, add the gadget back to the window, and refresh it. SEE ALSO OffGadget() intuition.library/OnMenu intuition.library/OnMenu NAME OnMenu -- Enable the given menu or menu item. SYNOPSIS OnMenu( Window, MenuNumber ) VOID OnMenu( struct Window *, UWORD ); FUNCTION This command enables a sub-item, an item, or a whole menu. This depends on the contents of the data packed into MenuNumber, which is described in the Intuition Reference Manual. INPUTS Window = pointer to the window MenuNumber = the menu piece to be enables RESULT None BUGS SEE ALSO OffMenu(), ResetMenuStrip() intuition.library/OpenClass intuition.library/OpenClass NAME OpenClass -- Open a diskbased BOOPSI class. (V50) SYNOPSIS struct ClassLibrary *result = OpenClass(CONST_STRPTR name, uint32 version, Class **class_ptr); FUNCTION This function can be used to open a disk-based BOOPSI class. It works like exec.library/OpenLibrary() but also returns a pointer to the class. Use of this function can eliminate the need for getting the class interface and using the deprecated *_GetClass() functions. INPUTS name - Name of the BOOPSI class to open (including possible path prefix like "gadgets/" or "images/"). version - Minimum version of the class required. class_ptr - Pointer to a Class pointer. Use this pointer with NewObject(). RESULT result - Pointer to the ClassLibrary base or NULL on error. NOTES Take care this function may fail miserably when the class doesn't use a struct ClassLibrary * base! SEE ALSO CloseClass(), NewObject() intuition.library/OpenScreen intuition.library/OpenScreen NAME OpenScreen -- Open an Intuition screen. SYNOPSIS struct Screen *screen = OpenScreen(struct NewScreen *NewScreen); or struct Screen *screen = OpenScreen(struct ExtNewScreen *ExtScreen); FUNCTION Opens an Intuition screen according to the specified parameters found in the NewScreen structure. Does all the allocations, sets up the screen structure and all substructures completely, and links this screen's viewport into Intuition's View structure. Before you call OpenScreen(), you must initialize an instance of a NewScreen structure. NewScreen is a structure that contains all of the arguments needed to open a screen. The NewScreen structure may be discarded immediately after OpenScreen() returns. The SHOWTITLE flag is set to TRUE by default when a screen is opened. To change this, you must call the routine ShowTitle(). INPUTS NewScreen = pointer to an instance of a NewScreen structure. ExtScreen = pointer to an instance of a ExtNewScreen structure. New for V36: In addition to the information contained in the NewScreen structure, Intuition now recognizes extended data passed in the form of an array of TagItem structures (from ), commonly called a "tag list." There are two ways to provide this array. The first is to use the new Intuition entry point OpenScreenTagList() and pass the tag list as a parameter. This is the recommended method, and has a convenient format variation for C programs using a variable number of arguments. An older way used for some V36 development uses the OpenScreen() entry point, and an extension of the NewScreen structure named ExtNewScreen. See the documentation of the flag NS_EXTENDED, below. While we recommend that you use OpenScreenTagList() rather than OpenScreen() when using the extension tag list, we document the tag ID values here, so that all parameters for opening a screen can be found in one place. NewScreen is initialized with the following information: ------------------------------------------------------------- Left = initial x-position of your screen (should be zero for releases prior to V36) Top = initial y-position of the opening screen (Note: Left and Top are specified relative to the Intuition's view, in same resolution as the screen pixels.) Width = the width for this screen's RastPort Height = the height for this screen's RastPort, or the constant STDSCREENHEIGHT to get the current default height (at this time guaranteed to be at least 200 rows). The normal width and height for a particular system is stored by the graphics.library in GfxBase->NormalDisplayRows and GfxBase->NormalDisplayColumns. These values will be different depending on factors such as PAL video and overscan. For V36, a new constant STDSCREENWIDTH is introduced. It serves the similar function for screen width. Both STDSCREENWIDTH and STDSCREENHEIGHT indicate that your screen RastPort is to be the same dimensions as your DisplayClip rectangle. If you do not specify either a standard or custom DisplayClip, the OSCAN_TEXT region will be used, which corresponds to the standard dimensions of V35 and earlier. Furthermore, if you are using OpenScreenTagList(), and you specify STDSCREENWIDTH, and you DO NOT provide a NewScreen pointer, and you DO NOT provide sA_Left, then Intuition will automatically set the LeftEdge of the screen to be the left edge of the screen's DisplayClip region. Likewise for STDSCREENHEIGHT and the screen's TopEdge. Depth = number of bitplanes DetailPen = pen number for details (like gadgets or text in title bar) The common value for this pen is 0. BlockPen = pen number for block fills (like title bar) The common value for this pen is 1. Type = screen type values Set these flags as desired from the set: CUSTOMSCREEN -- this is your own screen, not a system screen. CUSTOMBITMAP -- this custom screen has bit maps supplied in the bitmap field of the NewScreen structure. Intuition is not to allocate any raster bitmaps. SCREENBEHIND -- your screen will be created behind all other open screens. This allows a program to prepare imagery in the screen, change its colors, and so on, bringing it to the front when it is presentable. SCREENQUIET -- Intuition will not render system screen gadgets or screen title. In concert with the WFLG_RMBTRAP flag on all your screen's windows, this flag will prevent Intuition from rendering into your screen's bitplanes. Without WFLG_RMBTRAP (or using the IDCMP_MENUVERIFY facility to cancel menu operations), this flag will prevent Intuition from clearing your menu bar, which is probably unacceptable. The menu bar layer may still overwrite a portion of your screen bitmap when the screen is opened. (V36: it won't clobber your bits any more.) NS_EXTENDED for this screen to use extended attributes pointed to by the 'Extended' field, below. ViewModes = the appropriate argument for the data type ViewPort.Modes. These include: HIRES for this screen to be HIRES width. LACE for the display to switch to interlace. SPRITES for this screen to use sprites (the pointer sprite is always displayed) DUALPF for dual-playfield mode (not supported yet) [For V36: The ViewModes field is superseded by a TagItem with tag value SA_DisplayID.] Font = pointer to the default TextAttr structure for text in this screen and all windows that open in this screen. Text that uses this TextAttr includes title bars of both screen and windows, string gadgets, and menu titles. Of course, IntuiText that specifies a NULL TextAttr field will use the screen/window default fonts. NOTE: Intuition will *NOT* call OpenDiskFont(), so the TextAttr you supply must be in memory. The ways to ensure that are to either use a ROM font (Topaz 8 or 9) or first call OpenDiskFont() to load the font, and don't close it until after your screen is successfully opened. [For V36: this is superseded by SA_Font and SA_SysFont.] DefaultTitle = pointer to a line of text that will be displayed along the screen's title bar. Null terminated, or just a NULL pointer to get no text [For V36: superseded by SA_Title.] Gadgets = This field should be set to NULL, since no user gadgets may be attached to a screen with the current versions of Intuition. CustomBitMap = if you're not supplying a custom bitmap, this value is ignored. However, if you have your own display memory that you want used for this screen, the CustomBitMap field should point to the BitMap structure that describes your display memory. See the "Screens" chapter and the "Amiga ROM Kernel Manual" for more information about bitmaps. [For V36: this is superseded by SA_BitMap.] [ All TagItem extensions below are new for V36.] Extension = if NS_EXTENDED is set in NewScreen.Type, this pointer should point to an array (or chain of arrays) of TagItems, as defined in the include file . This field is only defined in the structure ExtNewScreen. The values to use for TagItem.ti_Tag are defined below. We recommend that V36-specific applications use the new Intuition entry point OpenScreenTagList(), rather than using this field. The ExtNewScreen structure is a convenient way to give V36 Intuition some information that V34 and earlier Intuition will ignore. Each TagItem is an optional tagged data structure which identifies an additional parameter to OpenScreen(). The applicable tag ID values for TagItem.ti_Tag and their corresponding data follow. Several of the tag items are alternative (and overriding) versions to familiar fields in NewScreen. (Defaults only apply if NewScreen == NULL). They are: SA_Left SA_Top SA_Width SA_Height The defaults for the SA_Left, SA_Top, SA_Width, and SA_Height tags end up being a bit complex. If none of these tags are specified, and no NewScreen structure is used, then the left/top/width/height correctly match the display clip of your screen (see SA_DClip and SA_Overscan). The difficulty comes with overscanned screens, because the normal value of SA_Left or SA_Top for such a screen may be non-zero. If a NewScreen structure is supplied, then the left/top/width/height come originally from there. If no NewScreen structure is supplied, but a non-default SA_Width (SA_Height) is specified, then SA_Left (SA_Top) defaults to zero instead. In these cases, the left and top edge may not be what you want. If you need to specify explicit width or height, or supply a NewScreen, you must supply correct values for SA_Left and SA_Top. The correct normal values are the display clip rectangle's MinX and MinY values respectively. If you are using the SA_DClip tag, then you already have a rectangle to consult for these values. If you are using SA_Overscan to get one of the standard overscan types, you may use QueryOverscan() to get a rectangle for that overscan type. SA_Depth (defaults to 1) SA_DetailPen (defaults to 0) SA_BlockPen (defaults to 1) SA_Title (defaults to NULL) SA_Font (defaults to NULL, meaning user's preferred monospace font) SA_BitMap (whose existence also implies CUSTOMBITMAP). Several tags are Booleans, which means that depending on whether their corresponding ti_Data field is zero (FALSE) or non-zero (TRUE), they specify Boolean attributes. The ones corresponding to Boolean flags in the NewScreen.Type field are: SA_ShowTitle (defaults to TRUE) SA_Behind (equiv. to SCREENBEHIND) (defaults to FALSE) SA_Quiet (equiv. to SCREENQUIET) (defaults to FALSE) The following tags provide extended information to Intuition when creating a screen: SA_Type: ti_Data corresponds to the SCREENTYPE bits of the NewScreen.Type field. This should be one of PUBLICSCREEN or CUSTOMSCREEN. The other bits of the NewScreen.Type field must be set with the appropriate tags (SA_Behind, SA_Quiet, etc.) SA_DisplayID: ti_Data is a 32-bit extended display mode ID, as defined in the include file (V39 and up) or in (V37 and V38). SA_Overscan: ti_Data contains a defined constant specifying one of the system standard overscan dimensions appropriate for the display mode of the screen. Used with the Width and Height dimensions STDSCREENWIDTH and STDSCREEN, this makes it trivial to open an overscanned or standard dimension screen. You may also hand-pick your various dimensions for overscanned or other screens, by specifying screen position and dimensions explicitly, and by using SA_DClip to explicitly specify an overscanned DisplayClip region. The values for ti_Data of this tag are as follows: OSCAN_TEXT - Text Overscan region. A region which is completely on screen and readable ("text safe"). A preferences data setting, this is backward equivalent with the old MoreRows, and specifies the DisplayClip and default dimensions of the Workbench screen. This is the default. OSCAN_STANDARD - Also a preferences setting, this specifies a rectangle whose edges are "just out of view." This yields the most efficient position and dimensions of on-monitor presentations, such as games and artwork. OSCAN_MAX - This is the largest rectangular region that the graphics library can handle "comfortably" for a given mode. Screens can smoothly scroll (hardware pan) within this region, and any DisplayClip or Screen region within this rectangle is also legal. It is not a preferences item, but reflects the limits of the graphics hardware and software. OSCAN_VIDEO - This is the largest region that the graphics library can display, comfortable or not. There is no guarantee that all smaller rectangles are valid. This region is typically out of sight on any monitor or TV, but provides our best shot at "edge-to-edge" video generation. Remember, using overscan drastically effects memory use and chip memory bandwidth. Always use the smallest (standard) overscan region that works for your application. SA_DClip: ti_Data is a pointer to a rectangle which explicitly defines a DisplayClip region for this screen. See QueryOverscan() for the role of the DisplayClip region. Except for overscan display screens, this parameter is unnecessary, and specifying a standard value using SA_Overscan is normally an easier way to get overscan. SA_AutoScroll: this is a Boolean tag item, which specifies that this screens is to scroll automatically when the mouse pointer reaches the edge of the screen. The operation of this requires that the screen dimensions be larger than its DisplayClip region. SA_PubName: If this field is present (and ti_Data is non-NULL), it means that the screen is a public screen, and that the public screen name string is pointed to by ti_Data. Public screens are opened in "PRIVATE" mode and must be made public using PubScreenStatus( screen, 0 ). SA_Pens: The ti_Data field (if non-NULL) points to a UWORD array of pen specification, as defined for struct DrawInfo. This array will be used to initialize the screen's DrawInfo.dri_Pens array. SA_Pens is also used to decide that a screen is ready to support the full-blown "new look" graphics. If you want the 3D embossed look, you must provide this tag, and the ti_Data value cannot be NULL. If it points to a "minimal" array, containing just the terminator ~0, you can specify "new look" without providing any values for the pen array; starting from V50, you can also pass a value of -1 as ti_Data to achieve the same result. The way the DrawInfo pens are determined is Intuition picks a default pen-array. Then, any pens you supply with SA_Pens override the defaults, up until the ~0 in your array. If the screen is monochrome or old-look, the default will be the standard two-color pens. If the screen is two or more planes deep, the default will be the standard four-color pens, which now include the new-look menu colors. If the screen has the SA_LikeWorkbench property, the default will be the user's preferred pen-array, changeable through preferences. The following two tag items specify the task and signal to be issued to notify when the last "visitor" window closes on a public screen. This support is to assist envisioned public screen manager programs. SA_PubTask: Task to be signalled. If absent (and SA_PubSig is valid), use the task which called OpenScreen() or OpenScreenTagList()). SA_PubSig: Data is a UBYTE signal number (not flag) used to notify a task when the last visitor window closes on a public screen. SA_Colors: ti_Data points to an array of ColorSpec structures (terminated with ColorIndex = -1) which specify initial values of the screen's color palette. SA_FullPalette: this is a Boolean attribute. Prior to V36, there were just 7 RGB color values that Intuition maintained in its user preferences (playfield colors 0-3, and colors 17-19 for the sprite). When opening a screen, the color map for the screens viewport is first initialized by graphics (graphics.library/GetColorMap()) then these seven values are overridden to take the preferences values. In V36, Intuition maintains a full set of 32 preferences colors; and starting with V50, it maintains a set of 256 preferences colors plus optional palette locking information. If you specify TRUE for SA_FullPalette, Intuition will override ALL color map entries with its full suite of preferred colors. (Defaults to FALSE). SA_ErrorCode: ti_Data points to a ULONG in which Intuition will stick an extended error code if OpenScreen[TagList]() fails. Values are of this include 0, for success, and: OSERR_NOMONITOR - monitor for display mode not available. OSERR_NOCHIPS - you need newer custom chips for display mode. OSERR_NOMEM - couldn't get normal memory OSERR_NOCHIPMEM - couldn't get chip memory OSERR_PUBNOTUNIQUE - public screen name already used OSERR_UNKNOWNMODE - don't recognize display mode requested OSERR_TOODEEP - screen too deep to be displayed on this hardware (V39) OSERR_ATTACHFAIL - An illegal attachment of screens was requested (V39) OSERR_NOTAVAILABLE - mode is not available for other reason OSERR_BADBITMAP - custom bitmap is not displayable (V51) NOTE: These values are not the same as some similar return values defined in graphics.library/ModeNotAvailable(). SA_SysFont: ti_Data selects one of the system standard fonts specified in preferences. This tag item overrides the NewScreen.Font field and the SA_Font tag item. Values recognized in ti_Data at present are: 0 - old DefaultFont, fixed-width, the default. 1 - Workbench screen preferred font. You have to be very font sensitive to handle a proportional or larger than traditional screen font. NOTE WELL: if you select sysfont 1, windows opened on your screen will not inherit the screen font, but rather the window RastPort will be initialized to the old-style DefaultFont (sysfont 0). Attached screen tags: V39 supports attached screens, where one or more child screens can be associated with a parent screen. Attached screens depth-arrange as a group, and always remain adjacent depth-wise. Independent depth-arrangement of child screens is possible through the V39 ScreenDepth() call. If a child screen is made non-draggable through {SA_Draggable, FALSE}, then it will drag exclusively with the parent. Normal child screens drag independently of the parent, but are pulled down when the parent is. Use the SA_Parent, SA_FrontChild, and SA_BackChild tags to attach screens. SA_Parent: If you wish to attach this screen to an already-open parent screen, use this tag and set ti_Data to point to the parent screen. See also SA_FrontChild and SA_BackChild. (V39). SA_FrontChild: If you wish to attach an already-open child screen to this screen, set ti_Data to point to the child screen. The child screen will come to the front of the family defined by the parent screen you are opening. See also SA_Parent and SA_BackChild. (V39) SA_BackChild: If you wish to attach an already-open child screen to this screen, set ti_Data to point to the child screen. The child screen will go to the back of the family defined by the parent screen you are opening. See also SA_Parent and SA_FrontChild. (V39) SA_BackFill: ti_Data is a pointer to a backfill hook for the screen's Layer_Info. (see layers.library/InstallLayerInfoHook()). (V39). SA_Draggable: ti_Data is a boolean. Set to FALSE if you wish your screen to be non-draggable. This tag should be used very sparingly!. Defaults to TRUE. For child screens (see SA_Parent, SA_FrontChild, and SA_BackChild) this tag has a slightly different meaning: non-draggable child screens are non-draggable with respect to their parent, meaning they always drag exactly with the parent, as opposed to having relative freedom. Also see ScreenPosition(). (V39) SA_Exclusive: ti_Data is a boolean. Set to TRUE if you never want your screen to share the display with another screen. This means that your screen can't be pulled down, and will not appear behind other screens that are pulled down. Your screen may still be depth arranged, though. Use this tag sparingly! Defaults to FALSE. Starting with V40, attached screens may be SA_Exclusive. Setting SA_Exclusive for each screen will produce an exclusive family. (V39). SA_SharePens: For those pens in the screen's DrawInfo->dri_Pens, Intuition obtains them in shared mode (see graphics.library/ObtainPen()). For compatibility, Intuition obtains the other pens of a public screen as PENF_EXCLUSIVE. Screens that wish to manage the pens themselves should generally set this tag to TRUE. This instructs Intuition to leave the other pens unallocated. Defaults to FALSE. (V39). SA_Colors32: Tag to set the screen's initial palette colors at 32 bits-per-gun. ti_Data is a pointer to a table to be passed to the graphics.library/LoadRGB32() function. This format supports both runs of color registers and sparse registers. See the autodoc for that function for full details. Any color set here has precedence over the same register set by SA_Colors. (V39). SA_Interleaved: ti_Data is a boolean. Set to TRUE to request an interleaved bitmap for your screen. Defaults to FALSE. If the system cannot allocate an interleaved bitmap for you, it will attempt to allocate a non-interleaved one (V39). SA_VideoControl: ti_Data points to a taglist that will be passed to VideoControl() after your screen is open. You might use this to turn on border-sprites, for example. (V39). SA_ColorMapEntries: ti_Data is the number of entries that you wish Intuition to allocate for this screen's ColorMap. While Intuition allocates a suitable number for ordinary use, certain graphics.library features require a ColorMap which is larger than default. (The default value is 1<