AddGList()

Synopsis

UWORD AddGList(
         struct Window    * window,
         struct Gadget    * gadget,
         ULONG position,
         LONG numGad,
         struct Requester * requester );

Function

Add some gadgets to a window.

Inputs

window - Add gadgets to this window
gadget - This is the list of gadgets to add
position - Where to insert the gadgets in the list of gadgets
    already in the window. Use 0 to insert the gadgets
    before all others in the window or ~0 to append them.
numGad - How many gadgets of the list should be added.
    Use -1 to add all gadgets in the list.
requester - Pointer to the requester structure if the window is
    a requester.

Result

The actual position where the gadgets were inserted.

Notes

The gadgets will just be added. To make them visible, you must
refresh the window or the gadgets.

AllocRemember()

Synopsis

APTR AllocRemember(
         struct Remember ** rememberKey,
         ULONG size,
         ULONG flags );

Function

Allocate some memory and remeber it in the Remember-List.

Inputs

rememberKey - Store information in this list. Must be NULL for
              initial call.
size - How many bytes to allocate
flags - Attributes (see AllocMem())

Result

Pointer to the allocated memory or NULL.

Example

struct Remember *remkey;
remkey = NULL;
AllocRemember(&remkey, BUFSIZE, MEMF_ANY);
FreeRemember(&remkey, TRUE);

AllocScreenBuffer()

Synopsis

struct ScreenBuffer * AllocScreenBuffer(
         struct Screen * screen,
         struct BitMap * bitmap,
         ULONG flags );

Function

Allocate a ScreenBuffer (and BitMap) for double or multiple
buffering in Intuition screens. Use this function to obtain a
ScreenBuffer for the screen's initial BitMap and for all other
BitMaps you want to swap in.

This function also allocates a DBufInfo from graphics.library
The returned ScreenBuffer contains a pointer to that DBufInfo.
See graphics.library/AllocDBufInfo() for more information on
how to use this struct to obtain info when it is safe to render
into an old buffer and when to switch.

Inputs

screen - Screen to double-buffer
bitmap - You may pre-allocate a BitMap for CUSTOMBITMAP screens,
    and pass the pointer to get a ScreenBuffer referring to it.
    If you specify NULL, intuition will allocate the BitMap for
    you. For non-CUSTOMBITMAP screens this parameter must be NULL.
flags - A combination of these flags:
    SB_SCREEN_BITMAP for non-CUSTOMBITMAP screens to get a
    ScreenBuffer referring to the screen's actual BitMap
    (For CUSTOMBITMAP screens just pass the BitMap you used for
    OpenScreen() as the bitmap parameter)
    SB_COPY_BITMAP to copy the screen's BitMap intto the
    ScreenBuffer's BitMap. Use this to get intuition rendered
    stuff into your bitmap (such as menu-bars or gadgets).
    May be omitted if the screen has no intuition rendered stuff,
    as well as for allocating a ScreenBuffer for the screen's
    initial BitMap.

Result

Pointer to the allocated ScreenBuffer or NULL if function failed.

Notes

You may render into the resulting BitMap.
Use the sb_DBufInfo field to access graphics.library's ViewPort
buffering features to e.g check if it is safe to reuse the previous
BitMap. Otherwise you risk to write into the on-screen BitMap and
damage menu or gadget rendering.

AlohaWorkbench()

Synopsis

void AlohaWorkbench(
         struct MsgPort * wbmsgport );

Function

The WorkBench program wants to call this function to signal
Intuition that it is active or shutting down.
Intuition then uses the MsgPort to tell the WorkBench to open or
close its windows if the user called OpenWorkbench() or
CloseWorkbench().

When the MsgPort is non-NULL Intuition will send IntuiMessages to
it with the Class field set to WBENCHMESSAGE and Code field set to
either WBENCHOPEN or WBENCHCLOSE. Intuition assumes that when the
WorkBench task replies this messages, it already has opened/closed
its windows.

Inputs

wbmsgport - The MsgPort of the (initialized) WorkBench task or
            NULL if the task is shutting down.

Result

None.

Notes

This function is obsolete and should not be used directly by the
Workbench Application. Use workbench.library/RegisterWorkbench()
instead!

AutoRequest()

Synopsis

BOOL AutoRequest(
         struct Window    * window,
         struct IntuiText * body,
         struct IntuiText * posText,
         struct IntuiText * negText,
         ULONG pFlag,
         ULONG nFlag,
         ULONG width,
         ULONG height );

BeginRefresh()

Synopsis

void BeginRefresh(
         struct Window * window );

Function

Initializes optimized refreshing. It restricts redrawing to areas which
need refreshing after a window has been moved or has changed size.

Inputs

window - window which needs refreshing

Example

somewhere in your window's event handling loop:

case IDCMP_REFRESHWINDWOW:
    BeginRefresh(mywindow);
    EndRefresh(mywindow, TRUE);
    break;

Notes

Only simple graphics.library functions are allowed between
BeginRefresh() and EndRefresh().

BeginRefresh()/EndRefresh() should always be called when an
IDCMP_REFRESHWINDWOW message happens.

BuildEasyRequestArgs()

Synopsis

struct Window * BuildEasyRequestArgs(
         struct Window     * RefWindow,
         struct EasyStruct * easyStruct,
         ULONG IDCMP,
         APTR Args );

struct Window * BuildEasyRequest(
         struct Window     * RefWindow,
         struct EasyStruct * easyStruct,
         ULONG IDCMP,
         TAG tag, ... );

Function

Opens a requester, which provides one or more choices. The control is
returned to the application after the requester was opened. It is
handled by subsequent calls to SysReqHandler() and closed by calling
FreeSysRequest().

Inputs

RefWindow - A reference window. If NULL, the requester opens on
            the default public screen.
easyStruct - The EasyStruct structure (<intuition/intuition.h>),
             which describes the requester.
IDCMP - IDCMP flags, which should satisfy the requester, too. This is
        useful for requesters, which want to listen to disk changes,
        etc. Note that this is not a pointer to the flags as in
        EasyRequestArgs().
Args - The arguments for easyStruct->es_TextFormat.

Result

Returns a pointer to the requester. Use this pointer only for calls
to SysReqHandler() and FreeSysRequest().

BuildSysRequest()

Synopsis

struct Window * BuildSysRequest(
         struct Window * window,
         struct IntuiText * bodytext,
         struct IntuiText * postext,
         struct IntuiText * negtext,
         ULONG IDCMPFlags,
         WORD width,
         WORD height );

Function

Build and display a system requester.

Inputs

window - The window in which the requester will appear
bodytext - The Text to be shown in the body of the requester
postext - The Text to be shown in the positive choice gadget
negtext - The Text to be shown in the negative choice gadget
IDCMPFlags - The IDCMP Flags for this requester
width, height - The dimensions of the requester

ChangeDecoration()

Synopsis

void ChangeDecoration(
         ULONG ID,
         struct NewDecorator * nd );

Function

Setup a new decorator for intuition windows, screens or menus.

Inputs

ID - identifier for decorations, see screens.h
nd -  an ID dependent NewDecorator structure

Result

void - this Function cannot fail,

Notes

The function fails if screens are open, use ChangeIntuition() to notify applications that
the UI will be changed.

ChangeScreenBuffer()

Synopsis

ULONG ChangeScreenBuffer(
         struct Screen * screen,
         struct ScreenBuffer * screenbuffer );

Function

Do double or multiple buffering on an intuition screen in an
intuition-cooperative way.
The ScreenBuffer's BitMap will be installed on the specifies screen,
if possible.
After a signal from graphics.library, the previously installed
BitMap will be available for re-use.
Consult graphics.library/AllocDBufInfo() and
graphics.library/ChangeVPBitMap() for further information.

Inputs

screen - The screen this screenbuffer belongs to
screenbuffer - The screenbuffer obtained by AllocScreenBuffer()

Result

Non-zero if fuction succeeded, or zero if operation could not be
performed, eg. if user selects menus or gadgets.

Notes

You need not re-install the original ScreenBuffer before closing
a screen. Just FreeScreenBuffer() all buffers used for that screen.

ChangeWindowBox()

Synopsis

void ChangeWindowBox(
         struct Window * window,
         LONG left,
         LONG top,
         LONG width,
         LONG height );

Function

Set the new position and size of a window in one call.

Inputs

window - Change this window
left, top - New position
width, height - New size

Notes

This call is deferred. Wait() for IDCMP_CHANGEWINDOW if your
program depends on the new size.

ChangeWindowShape()

Synopsis

struct Region * ChangeWindowShape(
         struct Window * window,
         struct Region * newshape,
         struct Hook * callback );

Function

Make a window invisible.

Inputs

window - The window to affect.

ClearDMRequest()

Synopsis

BOOL ClearDMRequest(
         struct Window * window );

Function

Detach the DMRequest from the window

Inputs

window - The window from which the DMRequest is to be cleared

Result

TRUE if requester could successfully be detached.

ClearMenuStrip()

Synopsis

void ClearMenuStrip(
         struct Window * window );

Function

Detach menu stript from a window.
Call this function before you change memu data.

Inputs

window - the window from which the menu bar should be detached

ClearPointer()

Synopsis

void ClearPointer(
         struct Window * window );

Function

Reset the mousepointer of this window to the default one.
If the window is active during this call the pointer will
immediately change its shape.
Set custom mousepointers with SetPointer().

Inputs

window - The window of which the mousepointer will be cleared

CloseScreen()

Synopsis

BOOL CloseScreen(
         struct Screen * screen );

Function

Release all resources held by a screen and close it down visually.

Inputs

screen  --  pointer to the screen to be closed

Result

TRUE if the screen is successfully closed, FALSE if there were still
windows left on the screen (which means the screen is not closed).

CloseWindow()

Synopsis

void CloseWindow(
         struct Window * window );

Function

Closes a window. Depending on the display, this might not happen
at the time when this function returns, but you must not use
the window pointer after this function has been called.

Inputs

window - The window to close

Result

None.

Notes

The window might not have been disappeared when this function returns.

CloseWorkBench()

Synopsis

LONG CloseWorkBench();

Function

Attempt to close the Workbench screen. This will fail if there are any
non-Drawer windows open on it.

Result

success - TRUE if Workbench screen could be closed.

Notes

If the Workbench screen is already closed when this function is called,
FALSE is returned.

CurrentTime()

Synopsis

void CurrentTime(
         ULONG * seconds,
         ULONG * micros );

Function

Copies the current time into the argument pointers.

Inputs

seconds - ptr to ULONG varaible which will contain the current
    seconds after function call
micros - ptr to ULONG varaible which will contain the current
    microseconds after function call

Result

Copies the time values to the memory the arguments point to
Return value is not set.

Notes

Makes use of timer.library/timer.device

DisplayAlert()

Synopsis

BOOL DisplayAlert(
         ULONG alertnumber,
         UBYTE* string,
         UWORD height );

Function

Bring up an alert with the given message.
A system recoverable alert is a RECOVERY_ALERT which waits until
the user presses a mouse button. The display is then restored and
a boolean value will be returned showing if the has pressed the
left mouse button.
A DEADEND_ALERT is an alert from which the system cannot recover.
This alert immediately returns with FALSE after creating the
alert display.
If the system can not get enough memory for a RECOVERY_ALERT,
this function returns FALSE.

Inputs

alertnumber - The
string - The
height - The

Result

Always FALSE if DEADEND_ALERT. RECOVERY_ALERT returns TRUE if
the user pressed the left mouse button and FALSE for other
mouse button or if the alert could not be posted.

DisplayBeep()

Synopsis

void DisplayBeep(
         struct Screen * screen );

Function

The Amiga has no internal speaker, so it flashes the background
color of the specified screen as a signal. If the argument is
NULL all screens will be flashed.

Inputs

screen - The Screen that will be flashed.
    If NULL all screens will flash.

DisposeObject()

Synopsis

void DisposeObject(
         APTR object );

Function

Deletes a BOOPSI object. All memory associated with the object
is freed. The object must have been created with NewObject().
Some object contain other object which might be freed as well
when this function is used on the "parent" while others might
also contain children but won't free them. Read the documentation
of the class carefully to find out how it behaves.

Inputs

object - The result of a call to NewObject() or a similar function,
     may be NULL.

Result

None.

Notes

This functions sends OM_DISPOSE to the oejct.

DoGadgetMethodA()

Synopsis

IPTR DoGadgetMethodA(
         struct Gadget    * gad,
         struct Window    * win,
         struct Requester * req,
         Msg msg );

IPTR DoGadgetMethod(
         struct Gadget    * gad,
         struct Window    * win,
         struct Requester * req,
         TAG tag, ... );

Function

Invokes a BOOPSI method on an object with a GadgetInfo derived from
the supplied window or requester parameter.

Inputs

gad - The gadget to work on
win - The window which contains the gadget or the requester with
    the gadgets.
req - If the gadget is in a requester, you must specify that one,
    too.
message - Send this message to the gadget.

Result

The result depends on the contents of the message sent to the
gadget.

DoubleClick()

Synopsis

BOOL DoubleClick(
         ULONG sSeconds,
         ULONG sMicros,
         ULONG cSeconds,
         ULONG cMicros );

Function

Check if two times are within the doubleclick intervall.

Inputs

sSeconds, sMicros - Seconds and microseconds of the first event.
cSeconds, cMicros - Seconds and microseconds of the second event.

Result

TRUE if the times are within the doubleclick intervall, FALSE
otherwise.

DrawBorder()

Synopsis

void DrawBorder(
         struct RastPort * rp,
         struct Border   * border,
         LONG leftOffset,
         LONG topOffset );

Function

Draws one or more borders in the specified RastPort. Rendering
will start at the position which you get when you add the offsets
leftOffset and topOffset to the LeftEdge and TopEdge specified
in the Border structure. All coordinates are relative to that point.

Inputs

rp - The RastPort to render into
border - Information what and how to render
leftOffset, topOffset - Initial starting position

Result

None.

Example

// Draw a house with one stroke
// The drawing starts at the lower left edge
WORD XY[] =
{
    10, -10,
    10,   0,
     0, -10,
    10, -10,
     5, -15,
     0, -10,
     0,   0,
    10,   0,
};
struct Border demo =
{
    100, 100,   // Position
    1, 2,   // Pens
    JAM1,   // Drawmode
    8,      // Number of pairs in XY
    XY,     // Vector offsets
    NULL    // No next border
};

// Render the house with the bottom left edge at 150, 50
DrawBorder (rp, &demo, 50, -50);

DrawImage()

Synopsis

void DrawImage(
         struct RastPort * rp,
         struct Image    * image,
         LONG leftOffset,
         LONG topOffset );

Function

Draw an image.

Inputs

rp - The RastPort to render into
image - The image to render
leftOffset, topOffset - Where to place the image.

Result

None.

DrawImageState()

Synopsis

void DrawImageState(
         struct RastPort * rp,
         struct Image    * image,
         LONG leftOffset,
         LONG topOffset,
         ULONG state,
         struct DrawInfo * drawInfo );

Function

This function renders an image in a certain state.

Inputs

rp - Render in this RastPort
image - Render this image
leftOffset, topOffset - Add this offset to the position stored in the
    image.
state - Which state (see intuition/imageclass.h for possible
    values).
drawInfo - The DrawInfo from the screen.

Result

None.

Notes

DrawImageState(), handles both boopsi and conventional images.

DumpIntuiState()

Synopsis

void DumpIntuiState();

Function

Private: dump the internal state of intuition.

Result

none

EasyRequestArgs()

Synopsis

LONG EasyRequestArgs(
         struct Window     * window,
         struct EasyStruct * easyStruct,
         ULONG             * IDCMP_ptr,
         APTR argList );

LONG EasyRequest(
         struct Window     * window,
         struct EasyStruct * easyStruct,
         ULONG             * IDCMP_ptr,
         TAG tag, ... );

Function

Opens and handles a requester, which provides one or more choices.
It blocks the application until the user closes the requester.
Returned is an integer indicating which gadget had been selected.

Inputs

Window - A reference window. If NULL, the requester opens on
     the default public screen.
easyStruct - The EasyStruct structure (<intuition/intuition.h>)
    describing the requester.
IDCMP_Ptr - Pointer to IDCMP flags. The requester will be closed early
    if any of the specified message types is received. This is useful
    for requesters that want to listen to disk changes etc. The contents
    of this pointer is set to the IDCMP flag that caused the requester
    to close. This pointer may be NULL.
ArgList - The arguments for easyStruct->es_TextFormat.

Result

-1, if one of the IDCMP flags of IDCMP_ptr was set.
 0, if the rightmost button was clicked or an error occured.
 n, if the n-th button from the left was clicked.

EndRefresh()

Synopsis

void EndRefresh(
         struct Window * window,
         BOOL complete );

Function

Finishes refreshing which was initialized with BeginRefresh().
The argument |complete| is usually TRUE, It can be useful to
set it to FALSE when refreshing is split in several tasks.

Inputs

window   - the window to be refreshed
complete - BOOL which states if all refreshing is done

EndRequest()

Synopsis

void EndRequest(
         struct Requester * requester,
         struct Window * window );

Function

Remove a requester from the specified window.
Other open requesters of this window stay alive.

Inputs

requester - The requester to be deleted
window - The window to which the requester belongs

Result

None.

EndScreenNotify()

Synopsis

BOOL EndScreenNotify(
         IPTR notify );

Function

Remove a Screen Notifications from Intuition.

Inputs

notify - notification returned from StartScreenNotifyTagList()

Result

BOOL - if false Notification is in use and cannot be removed, try later

EraseImage()

Synopsis

void EraseImage(
         struct RastPort * rp,
         struct Image    * image,
         LONG leftOffset,
         LONG topOffset );

Function

Erase an image on the screen.

Inputs

rp - Render in this RastPort
image - Erase this image
leftOffset, topOffset - Add this offset the the position in the
    image.

Result

None.

FreeClass()

Synopsis

BOOL FreeClass(
         struct IClass * iclass );

Function

Only for class implementatores.

Tries to free a class which has been created with MakeClass() in the
first place. This will not succeed in all cases: Classes which
still have living objects or which are still beeing used by subclasses
can't simply be freed. In this case this call will fail.

Public classes will always be removed with RemoveClass() no matter
if FreeClass() would succeed or not. This gurantees that after the
call to FreeClass() no new objects can be created.

If you have a pointer to allocated memory in cl_UserData, you must
make a copy of that pointer, call FreeClass() and if the call
succeeded, you may free the memory. If you don't follow these rules,
you might end up with a class which is partially freed.

Inputs

iclass - The pointer you got from MakeClass().

Result

FALSE if the class couldn't be freed at this time. This can happen
either if there are still objects from this class or if the class
is used a SuperClass of at least another class.

TRUE if the class could be freed. You must not use iclass after
that.

Example

// Free a public class with dynamic memory in cl_UserD

int freeMyClass (Class * cl)
{
    struct MyPerClassData * mpcd;

    mpcd = (struct MyPerClassData *)cl->cl_UserData;

    if (FreeClass (cl)
    {
    FreeMem (mpcd, sizeof (struct MyPerClassData));
    return (TRUE);
    }

    return (FALSE);
}

Notes

*Always* calls RemoveClass().

FreeRemember()

Synopsis

void FreeRemember(
         struct Remember ** rememberKey,
         LONG reallyForget );

Function

Free memory allocated by AllocRemember().

Inputs

rememberKey  - address of a pointer to struct Remember
reallyForget - TRUE  release all memory
               FALSE release only link nodes

FreeScreenBuffer()

Synopsis

void FreeScreenBuffer(
         struct Screen * screen,
         struct ScreenBuffer * screenbuffer );

Function

Frees a ScreenBuffer allocated by AllocScreenBuffer() and releases
associated resources. You have to call this before closing your
screen.

Inputs

screen - The screen this screenbuffer belongs to
screenbuffer - The screenbuffer obtained by AllocScreenBuffer()
    It is safe to pass NULL.

Result

None.

Notes

When used SB_SCREEN_BITMAP on allocating the ScreenBuffer
(ie. the ScreenBuffer only refers to the screen's BitMap) you must
FreeScreenBuffer() the ScreenBuffer before closing the screen.
Intuition will recognize when FreeScreenBuffer() is called for the
currently installed ScreenBuffer that it must not free the BitMap.
This is left to the CloseScreen() function.

FreeScreenDrawInfo()

Synopsis

void FreeScreenDrawInfo(
         struct Screen   * screen,
         struct DrawInfo * drawInfo );

Function

Tell intuition that you have finished work with struct DrawInfo
returned by GetScreenDrawInfo()

Inputs

screen - The screen you passed to GetScreenDrawInfo()
drawInfo - The DrawInfo structure returned by GetScreenDrawInfo()

Result

None.

FreeSysRequest()

Synopsis

void FreeSysRequest(
         struct Window * window );

Function

Frees a requester made with BuildSysRequest() or
BuildEasyRequestArgs().

Inputs

Window - The requester to be freed. May be NULL or 1.

Bugs

BuildSysRequest() requesters not supported, yet.

GadgetMouse()

Synopsis

void GadgetMouse(
         struct Gadget     * gadget,
         struct GadgetInfo * ginfo,
         WORD              * mousepoint );

Function

Determines the current mouse position relative to the upper-left
corner of a custom gadget.
It is recommended not to call this function!

Inputs

gadget - The gadget to take as origin
ginfo - The GadgetInfo structure as passed to the custom gadget hook routine
mousepoint - Pointer to an array of two WORDs or a structure of type Point

Result

None. Fills in the two WORDs pointed to by mousepoint.

Notes

This function is useless, because programs which need this information
can get it in a cleaner way.
It is recommended not to call this function!

GetAttr()

Synopsis

ULONG GetAttr(
         ULONG attrID,
         Object * object,
         IPTR * storagePtr );

Function

Asks the specified object for the value of an attribute. This is not
possible for all attributes of an object. Read the documentation for
the class to find out which can be read and which can't.

Inputs

attrID - ID of the attribute you want
object - Ask the attribute from this object
storagePtr - This is a pointer to memory which is large enough
    to hold a copy of the attribute. Most classes will simply
    put a copy of the value stored in the object here but this
    behaviour is class specific. Therefore read the instructions
    in the class description carefully.

Result

Mostly TRUE if the method is supported for the specified attribute
and FALSE if it isn't or the attribute can't be read at this time.
See the classes documentation for details.

Notes

This function sends OM_GET to the object.

GetDefaultPubScreen()

Synopsis

struct Screen * GetDefaultPubScreen(
         UBYTE * nameBuffer );

Function

Returns the name of the current default public screen.
This will be "Workbench" if there is no default public screen.

Inputs

nameBuffer - A buffer of length MAXPUBSCREENNAME

Result

None.

Notes

Only Public Screen Manager utilities want to use this function
since it is easy to open a window on the default public screen
without specifying a name.

GetDefPrefs()

Synopsis

struct Preferences * GetDefPrefs(
         struct Preferences * prefbuffer,
         WORD size );

Function

Gets a copy of the Intuition default Preferences structure.

Inputs

prefbuffer - The buffer which contains your settings for the
    preferences.
size - The number of bytes of the buffer you want to be copied.

Result

Returns your parameter buffer.

GetPrefs()

Synopsis

struct Preferences * GetPrefs(
         struct Preferences * prefbuffer,
         WORD size );

Function

Gets a copy of the current Preferences structure.

Inputs

prefbuffer - The buffer which contains your settings for the
    preferences.
size - The number of bytes of the buffer you want to be copied.

Result

Returns your parameter buffer.

GetScreenData()

Synopsis

LONG GetScreenData(
         APTR buffer,
         ULONG size,
         ULONG type,
         struct Screen * screen );

Function

Copy part or all infos about a screen into a private buffer.

To copy the Workbench, one would call

    GetScreenData (buffer, sizeof(struct Screen), WBENCHSCREEN, NULL)

If the screen is not open, this call will open it. You can use
this function for these purposes:

1) Get information about the workbench in order to open a window
   on it (eg. size).
2) Clone a screen.

Inputs

buffer - The data gets copied here
size - The size of the buffer in bytes
type - The type of the screen as in OpenWindow().
screen - Ignored unless type is CUSTOMSCREEN.

Result

TRUE if successful, FALSE if the screen could not be opened.

GetScreenDrawInfo()

Synopsis

struct DrawInfo * GetScreenDrawInfo(
         struct Screen * screen );

Function

Returns a pointer to struct DrawInfo of the passed screen.
This data is READ ONLY. The version of the struct DrawInfo
is given in the dri_Version field.

Inputs

screen - The screen you want to get the DrawInfo from.
    Must be valid and open.

Result

Returns pointer to struct DrawInfo defined in intuition/screens.h

Notes

Call FreeScreenDrawInfo() after finishing using the pointer.
This function does not prevent the screen from being closed.

HelpControl()

Synopsis

void HelpControl(
         struct Window * window,
         ULONG flags );

Function

Turn on or off Gadget-Help for your window. Gadget-Help will also
be changed for all members of the same help-group to make
multiple-windows apps to behave well.

Inputs

window - The window to affect. All windows of the same help-goup will
    be affected as well.
flags - HC_GADGETHELP or zero for turning help on or off.

Result

None. Toggles gadget-help of one or more windows to on or off.

HideWindow()

Synopsis

VOID HideWindow(
         struct Window * window );

Function

Make a window invisible.

Inputs

window - The window to affect.

InitRequester()

Synopsis

void InitRequester(
         struct Requester * requester );

Function

    This function is OBSOLETE and should not be called. To preserve
compatibility with old programs, calling this function is a no-op.

Inputs

requester - The struct Requester to be initialized

Result

None.

Notes

This function is obsolete.

IntuiTextLength()

Synopsis

LONG IntuiTextLength(
         struct IntuiText * iText );

Function

Measure the length of the IntuiText passed to the function. Further
IntuiTexts in iText->NextText are ignored. The length is measured in
pixels.

Inputs

iText - The size of this text. If iText->ITextFont contains NULL,
    the systems font is used (and *not* the font of the currently
    active screen !).

Result

The width of the text in pixels.

IsWindowVisible()

Synopsis

LONG IsWindowVisible(
         struct Window * window );

Function

Check whether a window is visible or not. This does not
check whether the window is within the visible area of
the screen but rather whether it is in visible state.

Inputs

window - The window to affect.

Result

TRUE if window is currently visible, FALSE otherwise.

ItemAddress()

Synopsis

struct MenuItem * ItemAddress(
         struct Menu * menustrip,
         UWORD menunumber );

Function

Returns the address of the menuitem 'menunumber' of 'menustrip'.
The number is the one you get from intuition after the user has
selected a menu.
The menunumber must be well-defined.
Valid numbers are MENUNULL, which makes the routine return NULL,
or valid item number of your menustrip, which contains
- a valid menu number
- a valid item number
- if the menu-item has a sub-item, a valid sub-item number
Menu number and item number must be specified. Sub-item, if
available, is optional, therefore this function returns either
the item or sub-item.

Inputs

menustrip - Pointer to the first menu of the menustrip.
menunumber - Packed value describing the menu, item and if
    appropriate sub-item.

Result

Returns NULL for menunumber == MENUNULL or the address of the
menuitem described by menunumber.

LendMenus()

Synopsis

void LendMenus(
         struct Window * fromwindow,
         struct Window * towindow );

Function

This function 'lends' the menus of one window to another.
This makes the menu events (eg. menu button press) take place
in another window's menu (ie. the other window's strip and screen).
This function is used to unify two windows on different attached
screens. (Eg. a painting program with an attached palette screen
can open the menu on the main screen if the menu button is
pressed on the palette screen.

Inputs

fromwindow - This window's menu events will go to another window.
towindow - This is the window that will react on the menu actions
    of the other window. If NULL 'lending' will be turned off.

Result

None.

LockIBase()

Synopsis

ULONG LockIBase(
         ULONG What );

Function

Locks Intuition. While you hold this lock, no fields of Intuition
will change. Please release this as soon as possible.

Inputs

What - Which fields of Intuition should be locked. The only allowed
    value for this is currently 0 which means to lock everything.

Result

The result of this function must be passed to UnlockIBase().

Notes

You *must not* call this function if you have any locks on other
system resources like layers and LayerInfo locks.

lockPubClass()

Synopsis

void lockPubClass();

Function

Locks the public classes list.

LockPubScreen()

Synopsis

struct Screen * LockPubScreen(
         CONST_STRPTR name );

Function

Locks a public screen, thus preventing it from closing.
This is useful if you want to put up a visitor window on a public screen
and need to check some of the public screen's field first -- not locking
the screen may lead to the public screen not existing when your visitor
window is ready.

If you try to lock the Workbench screen or the default public screen
and there isn't any, the Workbench screen will be automatically opened
and locked.

Inputs

Name   --  Name of the public screen or NULL for the default public
           screen. The name "Workbench" refers to the Workbench screen.

Result

A pointer to the screen or NULL if something went wrong. Failure can
happen for instance when the public screen is in private state or doesn't
exist.

Example

To open a visitor window which needs information from the screen structure
of the public screen to open on, do this:

if((pubscreen = LockPubScreen("PubScreentoOpenon")) != NULL)
{
    ...check pubscreen's internal data...
OpenWindow(VisitorWindow, pubscreen);
UnlockPubScreen(NULL, pubscreen);
...use your visitor window...
CloseWindow(VisitorWindow);
}

Notes

You don't need to hold the lock when your visitor window is opened as
the pubscreen cannot be closed as long as there are visitor windows
on it.

LockPubScreenList()

Synopsis

struct List * LockPubScreenList();

Function

Arbitrates access to the system public screen list. This is for Public
Screen Manager programs only! The list should be locked for as short a
time as possible.

Notes

The list's nodes are PubScreenNodes as defined in <intuition/screens.h>.

MakeClass()

Synopsis

struct IClass * MakeClass(
         ClassID classID,
         ClassID superClassID,
         struct IClass * superClassPtr,
         ULONG instanceSize,
         ULONG flags );

Function

Only for class implementators.

This function creates a new public BOOPSI class. The SuperClass
should be another BOOPSI class; all BOOPSI classes are subclasses
of the ROOTCLASS.

SuperClasses can by private or public. You can specify a name/ID
for the class if you want it to become a public class. For public
classes, you must call AddClass() afterwards to make it public
accessible.

The return value contains a pointer to the IClass structure of your
class. You must specify your dispatcher in cl_Dispatcher. You can
also store shared data in cl_UserData.

To get rid of the class, you must call FreeClass().

Inputs

classID - NULL for private classes otherwise the name/ID of the
    public class.
superClassID - Name/ID of a public SuperClass. NULL is you don't
    want to use a public SuperClass or if you have the pointer
    your SuperClass.
superClassPtr - Pointer to the SuperClass. If this is non-NULL,
    then superClassID is ignored.
instanceSize - The amount of memory which your objects need (in
    addition to the memory which is needed by the SuperClass(es))
flags - For future extensions. To maintain comaptibility, use 0
    for now.

Result

Pointer to the new class or NULL if
- There wasn't enough memory
- The superclass couldn't be found
- There already is a class with the same name/ID.

Notes

No copy is made of classID. So make sure the lifetime of the contents
of classID is at least the same as the lifetime of the class itself.

MakeScreen()

Synopsis

LONG MakeScreen(
         struct Screen * screen );

Function

Create viewport of the screen.

Inputs

Pointer to your custom screen.

Result

Zero for success, non-zero for failure.

ModifyIDCMP()

Synopsis

BOOL ModifyIDCMP(
         struct Window * window,
         ULONG flags );

Function

This routine modifies the state of your window's IDCMP (Intuition
Direct Communication Message Port).

Depending on the current state in the IDCMPFlags of the window and
the specified flags these actions are possible:

IDCMP   flags   Action
  0   0 Nothing happens
  0  !=0    The flags are copied in the IDCMPFlags of the window
        and a MessagePort is created and stored in the
        UserPort of the window.
 !=0      0 The IDCMPFlags are cleared and the MessagePort in the
        UserPort is deleted.
 !=0     !=0    The flags are copied to the IDCMPFlags of the
        window.

Inputs

window - The window to change the IDCMPFlags in.
flags - New flags for the IDCMPFlags of the window. See
    intuition/intuition.h for the available flags.

Result

TRUE if the change could be made and FALSE otherwise.

Notes

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().

Intuition v50 features WA_UserPort tag, which allows to set
the UserPort at OpenWindow stage. Please note that using this tag
changes the behaviour of ModifyIDCMP() slightly. Creating/disposing
message ports is now up to the app. ModifyIDCMP(win,0) still clears
win->UserPort pointer, but the message port is NOT disposed - you
need to store it and dispose yourself! Also calling
ModifyIDCMP(win,someidcmp) on a window with NULL win->UserPort will
NOT create a new port!

ModifyProp()

Synopsis

void ModifyProp(
         struct Gadget    * gadget,
         struct Window    * window,
         struct Requester * requester,
         ULONG flags,
         ULONG horizPot,
         ULONG vertPot,
         ULONG horizBody,
         ULONG vertBody );

Function

Changes the values in the PropInfo-structure of a proportional
gadget and refreshes the display.

Inputs

gadget - Must be a PROPGADGET
window - The window which contains the gadget
requester - If the gadget has GTYP_REQGADGET set, this must be
    non-NULL.
flags - New flags
horizPot - New value for the HorizPot field of the PropInfo
vertPot - New value for the VertPot field of the PropInfo
horizBody - New value for the HorizBody field of the PropInfo
vertBody - New value for the VertBody field of the PropInfo

Result

None.

Notes

This function causes all gadgets from this gadget to the end of
the gadget list to be refreshed. If you want a better behaviour,
use NewModifProp().

MoveScreen()

Synopsis

void MoveScreen(
         struct Screen * screen,
         LONG dx,
         LONG dy );

Function

Move a screen by the specified amount in X/Y direction. The
resolution is always the screen resolution.

Inputs

screen - Move this screen
dx - Move it by this amount along the X axis (> 0 to the right,
    < 0 to the left).
dy - Move it by this amount along the Y axis (> 0 down, < 0 up)

Result

None.

Notes

Depending on other restrictions, the screen may not move as far
as specified. It will move as far as possible and you can check
LeftEdge and TopEdge of the screen to see how far it got.

MoveWindow()

Synopsis

void MoveWindow(
         struct Window * window,
         LONG dx,
         LONG dy );

Function

Change the position of a window on the screen.

Inputs

window - Move this window
dx, dy - Move it that many pixels along the axis (right, down)

Result

The window will move when the next input event will be received.

MoveWindowInFrontOf()

Synopsis

void MoveWindowInFrontOf(
         struct Window * window,
         struct Window * behindwindow );

Function

Arrange the relative depth of a window.

Inputs

window - the window to reposition
behindwindow - the window the other one will be brought in front of

Result

None.

NewModifyProp()

Synopsis

void NewModifyProp(
         struct Gadget    * gadget,
         struct Window    * window,
         struct Requester * requester,
         ULONG flags,
         ULONG horizPot,
         ULONG vertPot,
         ULONG horizBody,
         ULONG vertBody,
         LONG numGad );

Function

Changes the values in the PropInfo-structure of a proportional
gadget and refreshes the specified number of gadgets beginning
at the proportional gadget. If numGad is 0 (zero), then no
refreshing is done.

Inputs

gadget - Must be a PROPGADGET
window - The window which contains the gadget
requester - If the gadget has GTYP_REQGADGET set, this must be
    non-NULL.
flags - New flags
horizPot - New value for the HorizPot field of the PropInfo
vertPot - New value for the VertPot field of the PropInfo
horizBody - New value for the HorizBody field of the PropInfo
vertBody - New value for the VertBody field of the PropInfo
numGad - How many gadgets to refresh. 0 means none (not even
    the current gadget) and -1 means all of them.

Result

None.

NewObjectA()

Synopsis

APTR NewObjectA(
         struct IClass  * classPtr,
         UBYTE          * classID,
         struct TagItem * tagList );

APTR NewObject(
         struct IClass  * classPtr,
         UBYTE          * classID,
         TAG tag, ... );

Function

Use this function to create BOOPSI objects (BOOPSI stands for
"Basic Object Oriented Programming System for Intuition).

You may specify a class either by it's name (if it's a public class)
or by a pointer to its definition (if it's a private class). If
classPtr is NULL, classID is used.

Inputs

classPtr - Pointer to a private class (or a public class if you
    happen to have a pointer to it)
classID - Name of a public class
tagList - Initial attributes. Read the documentation of the class
    carefully to find out which attributes must be specified
    here and which can.

Result

A BOOPSI object which can be manipulated with general functions and
which must be disposed with DisposeObject() later.

Notes

This functions send OM_NEW to the dispatcher of the class.

NextObject()

Synopsis

APTR NextObject(
         APTR objectPtrPtr );

Function

Use this function to iterate through a list of BOOPSI objects.
You may do whatever you want with the object returned, even
remove it from the list or disposing it and then continue to
iterate thought the list.

Inputs

objectPtrPtr - the pointer to a variable. This must be the same
    variable, as long as you iterate though the same list. This
    variable must initially be filled with the lh_Head of a list.

Result

A BOOPSI object, which can be manipulated.

NextPubScreen()

Synopsis

UBYTE * NextPubScreen(
         struct Screen * screen,
         UBYTE * namebuff );

Function

Gets the next public screen in the system; this allows visitor windows
to jump among public screens in a cycle.

Inputs

screen    --  Pointer to the public screen your window is open in or
              NULL if you don't have a pointer to a public screen.
namebuff  --  Pointer to a buffer with (at least) MAXPUBSCREENNAME+1
              characters to put the name of the next public screen in.

Result

Returns 'namebuff' or NULL if there are no public screens.

Notes

We cannot guarantee that the public screen, the name of which you got
by using this function, is available when you call for instance
LockPubScreen(). Therefore you must be prepared to handle failure of
that kind of functions.
    This function may return the name of a public screen which is in
private mode.
    The cycle order is undefined, so draw no conclusions based on it!

ObtainGIRPort()

Synopsis

struct RastPort * ObtainGIRPort(
         struct GadgetInfo * gInfo );

Function

This function sets up a RastPort for exclusive use by custom
gadget hook routines. Call this function each time a hook
routine needs to render into the gadget and ReleaseGIRPort()
immediately afterwards.

Inputs

gInfo - Pointer to GadgetInfo structure, as passed to each
custom gadget hook function.

Result

Pointer to a RastPort you can render to. NULL if you aren't
allowed to render into this gadget.

Notes

If a routine passes a RastPort, eg. GM_RENDER, ObtainGIRPort()
needn't be called.

OffGadget()

Synopsis

void OffGadget(
         struct Gadget    * gadget,
         struct Window    * window,
         struct Requester * requester );

Function

Disable a gadget. It will appear ghosted.

Inputs

gadget - The gadget to deactivate
window - The window, the gadget is in
requester - The requester, the gadget is in or NULL if the
    gadget is in no requester

Result

None.

Notes

This function will update the gadget (unlike the original function
which would update all gadgets in the window).

OffMenu()

Synopsis

void OffMenu(
         struct Window    * window,
         UWORD menunumber );

Function

Disable a whole menu, an item or a sub-item depending on
the menunumber.

Inputs

window - The window, the menu belongs to
menunumber - The packed information on what piece of menu to disable

Result

None.

OnGadget()

Synopsis

void OnGadget(
         struct Gadget    * gadget,
         struct Window    * window,
         struct Requester * requester );

Function

Enable a gadget. It will appear normal.

Inputs

gadget - The gadget to deactivate
window - The window, the gadget is in
requester - The requester, the gadget is in or NULL if the
    gadget is in no requester

Result

None.

Notes

This function will update the gadget (unlike the original function
which would update all gadgets in the window).

OnMenu()

Synopsis

void OnMenu(
         struct Window    * window,
         UWORD menunumber );

Function

Enable a whole menu, an item or a sub-item depending on
the menunumber.

Inputs

window - The window, the menu belongs to
menunumber - The packed information on what piece of menu to enable

Result

None.

OpenScreen()

Synopsis

struct Screen * OpenScreen(
         struct NewScreen * newScreen );

OpenScreenTagList()

Synopsis

struct Screen * OpenScreenTagList(
         struct NewScreen * newScreen,
         struct TagItem   * tagList );

struct Screen * OpenScreenTags(
         struct NewScreen * newScreen,
         TAG tag, ... );

Function

Open a screen

Inputs

newScreen - struct with screen specification. This is for compatibility
            with OpenScreen() and usually set to NULL.
tagList   - tags which specify the screen

Result

Pointer to screen or NULL if opening fails.

Notes

If you need a pointer to the screen's bitmap use Screen->RastPort.BitMap
instead of &Screen->BitMap.

If you want DOS requester to appear on your screen you have to do:
    process = FindTask(0);
    process->pr_WindowPtr = (APTR) window;
The old value of pr->WindowPtr must be reset before you quit your
program.

OpenWindow()

Synopsis

struct Window * OpenWindow(
         struct NewWindow * newWindow );

Function

Opens a new window with the characteristics specified in
newWindow.

Inputs

newWindow - How you would like your new window.

Result

A pointer to the new window or NULL if it couldn't be
opened. Reasons for this might be lack of memory or illegal
attributes.

OpenWindowTagList()

Synopsis

struct Window * OpenWindowTagList(
         struct NewWindow * newWindow,
         struct TagItem   * tagList );

struct Window * OpenWindowTags(
         struct NewWindow * newWindow,
         TAG tag, ... );

Function

Open a new window.

Inputs

NewWindow - structure with window specification. This is for
            compatibility with OpenWindow() and usually set to NULL
tagList   - tags which specify appearance and behaviour of the window

Result

A pointer to the new window or NULL if it couldn't be
opened. Reasons for this might be lack of memory or illegal
attributes.

OpenWorkBench()

Synopsis

IPTR OpenWorkBench();

Function

Attempt to open the Workbench screen.

Inputs

None.

Result

Tries to (re)open WorkBench screen. If successful return value
is a pointer to the screen structure, which shouldn't be used,
because other programs may close the WorkBench and make the
pointer invalid.
If this function fails the return value is NULL.

PointInImage()

Synopsis

BOOL PointInImage(
         ULONG point,
         struct Image * image );

Function

Check whether a point is inside an image.

Inputs

point - This are the packed point coordinates. The X coordinate
    in in the upper 16 bits and the Y coordinate is in the
    lower 16 bits. The coordinates are signed.
image - Check against this image.

Result

TRUE is the point is inside the image, FALSE otherwise.

PrintIText()

Synopsis

void PrintIText(
         struct RastPort  * rp,
         struct IntuiText * iText,
         LONG leftOffset,
         LONG topOffset );

Function

Render an IntuiText in the specified RastPort with the
specified offset.

Inputs

rp - Draw into this RastPort
iText - Render this text
leftOffset, topOffset - Starting-Point. All coordinates in the
    IntuiText structures are relative to this point.

Result

None.

PubScreenStatus()

Synopsis

UWORD PubScreenStatus(
         struct Screen * Scr,
         UWORD StatusFlags );

Function

Change the status flags for a given public screen.

Inputs

Scr          --  The screen the flags of which to change.
StatusFlags  --  The new values for the flags, see <intuition/screens.h>
                 for further information on the flag bits.

Result

Clears bit 0 if the screen wasn't public or if it was impossible
to make private (PSNF_PRIVATE) as visitor windows are open on it.
The other bits in the return value are reserved for future use.

QueryOverscan()

Synopsis

LONG QueryOverscan(
         ULONG displayid,
         struct Rectangle * rect,
         WORD oscantype );

Function

Query overscan dimensions. The resulting rectangle can be used
with SA_DisplayID.

Overscan types:
OSCAN_TEXT: completely visible. Left/Top is always 0,0.
OSCAN_STANDARD: visible bounds of monitor. Left/Top may be negative.
OSCAN_MAX: The largest displayable region.
OSCAN_VIDEO: The absolute largest region that the graphics.library
  can display.  This region must be used as-is.

Inputs

displayid - ID to be queried
rect      - Pointer to struct Rectangle to store result
oscantype - OSCAN_TEXT, OSCAN_STANDARD, OSCAN_MAX, OSCAN_VIDEO

Result

TRUE  - Monitorspec exists
FALSE - Monitorspec doesn't exist

RefreshGadgets()

Synopsis

void RefreshGadgets(
         struct Gadget    * gadgets,
         struct Window    * window,
         struct Requester * requester );

Function

Refreshes all gadgets starting at the specified gadget.

Inputs

gadgets - The first gadget to be refreshed
window - The gadget must be in this window
requester - If any gadget has GTYP_REQGADGET set, this must
    point to a valid Requester. Otherwise the value is
    ignored.

Result

None.

Example

// Refresh all gadgets of a window
RefreshGadgets (win->FirstGadget, win, NULL);

Synopsis

void RefreshGList(
         struct Gadget    * gadgets,
         struct Window    * window,
         struct Requester * requester,
         LONG numGad );

Function

Refresh (draw anew) the specified number of gadgets starting
at the specified gadget.

Inputs

gadgets - This is the first gadget which will be refreshed.
window - The window which contains the gadget
requester - If the gadget has GTYP_REQGADGET set, this must be
    a pointer to a Requester; otherwise the value is
    ignored.
numGad - How many gadgets should be refreshed. The value
    may range from 0 to MAXLONG. If there are less gadgets
    in the list than numGad, only the gadgets in the
    list will be refreshed.

Result

None.

Example

// Refresh one gadget
RefreshGList (&gadget, win, NULL, 1);

// Refresh all gadgets in the window
RefreshGList (win->FirstGadget, win, NULL, -1L);

Notes

This function *must not* be called inside a
BeginRefresh()/EndRefresh() pair.

RefreshWindowFrame()

Synopsis

void RefreshWindowFrame(
         struct Window * window );

Function

Redraw window borders.

Inputs

window - pointer to a window whose borders should be redrawn

ReleaseGIRPort()

Synopsis

void ReleaseGIRPort(
         struct RastPort * rp );

Function

Release a RastPort previously obtained by ObtainGIRPort().

Inputs

rp - The result of ObtainGIRPort()

Result

None.

RemakeDisplay()

Synopsis

LONG RemakeDisplay();

Function

Remake the entire Intuition display.

Inputs

None.

Result

Zero for success, non-zero for failure.

RemoveClass()

Synopsis

void RemoveClass(
         struct IClass * classPtr );

Function

Makes a public class inaccessible. This function may be called
several times on the same class and even if the class never was
in the public list.

Inputs

classPtr - Pointer to the result of MakeClass(). May be NULL.

Result

None.

RemoveGadget()

Synopsis

UWORD RemoveGadget(
         struct Window * window,
         struct Gadget * gadget );

Function

Remove a gadget from the list of gadgets in a window.

Inputs

window - Remove the gadget from this list.
gadget - Remove this gadget.

Result

The position of the gadget or 0xFFFF if the gadget doesn't
exist or the gadget is the 65535th of the list.

RemoveGList()

Synopsis

UWORD RemoveGList(
         struct Window * remPtr,
         struct Gadget * gadget,
         LONG numGad );

Function

Remove sublist of gadgets from a window.

Inputs

remPtr - window from which gadgets should be removed
gadget - pointer gadget to be removed
numGad - number of gadgets to remove. Use -1 to remove
         all gadgets to the end of the list.

Result

Ordinal number of the removed gadget or -1 on failure

ReportMouse()

Synopsis

void ReportMouse(
         LONG flag,
         struct Window * window );

Function

Enable or disable the window flag REPORTMOUSE. If the flag is
set, you will receive IDCMP event every time the user moves
the mouse.

Inputs

flag - Enable (TRUE) or disable (FALSE) the reports.
window - Do it in this window.

Result

None.

Notes

As you might have noticed, the arguments are twisted.

Request()

Synopsis

BOOL Request(
         struct Requester * requester,
         struct Window * window );

Function

Add a requester to specified window and display it.

Inputs

requester - The requester to be displayed
window - The window to which the requester belongs

Result

TRUE if requester was opened successfully, FALSE else.

ResetMenuStrip()

Synopsis

BOOL ResetMenuStrip(
         struct Window * window,
         struct Menu * menu );

Function

Works like a "fast" SetMenuStrip() as it doesn't check Menu or
calculate internal values before attaching the Menu to the Window.
Use this function only if the Menu has been added before by
SetMenuStrip() and you changed nothing in the struct except
CHECKED and ITEMENABLED flags.

Inputs

window - The window to add the MenuStrip to
menu   - The menu to be added to the window above.

Result

Always TRUE.

Notes

    Yes, I do repeat it again:
Use this function only if the Menu has been added before by
SetMenuStrip() and you changed nothing in the struct except
CHECKED and ITEMENABLED flags.

RethinkDisplay()

Synopsis

LONG RethinkDisplay();

Function

Check and update, ie. redisplay the whole Intuition display.

Inputs

None.

Result

Zero for success, non-zero for failure.

ScreenDepth()

Synopsis

void ScreenDepth(
         struct Screen * screen,
         ULONG flags,
         APTR reserved );

Function

Move the specified screen to the front or back, based on passed flag.
If the screen is in a group, the screen will change its position in
the group only. If the screen is the parent of a group, the whole
group will be moved.

Inputs

screen - Move this screen.
flags - SDEPTH_TOFRONT or SDEPTH_TOBACK for bringing the screen to
    front or back.
    If the screen is a child of another screen you may specify
    SDEPTH_INFAMILY to move the screen within the family. If
    not specified the whole family will move.
reserved - For future use. MUST be NULL by now.

Result

None.

Notes

Only the owner of the screen should use SDEPTH_INFAMILY.
Intentionally commodities should not change the internal arrangement
of screen families.

Bugs

I am not sure, if it is enough, to just send a SNOTIFY message to one
screen.  I would suggest, the former FirstScreen gets a SDEPTH_TOBACK
message and the new FirstScreen gets a SDEPTH_TOFRONT message.
Currently only the screen supplied with ScreenDepth gets a message.

But those messages need to be sent in front of the actual
screen depth change because of the SNOTIFY_WAIT_REPLY-flag must be
able to block the action. But we only know after int_screendepth(),
if there was a change and which change took place.

So I leave it, as it is. This way SNOTIFY_WAIT_REPLY should work
at least. Is there something written in the AutoDocs, how this has
to be done (each screen gets a message)?

(o1i)

ScreenPosition()

Synopsis

void ScreenPosition(
         struct Screen * screen,
         ULONG flags,
         LONG x1,
         LONG y1,
         LONG x2,
         LONG y2 );

Function

Move a screen to the specified position or by the specified
increment. Resolution is always the screen resolution.
If this move would be out of bounds, the move is clipped at
these boundaries. The real new position can be obtained from
LeftEdge and TopEdge of the screen's structure.

Inputs

screen - Move this screen
flags - One of SPOS_RELATIVE, SPOS_ABSOLUTE or SPOS_MAKEVISIBLE
    Use SPOS_FORCEDRAG to override non-movable screens ie. screens
    opened with {SA_Draggable,FLASE} attribute.

    SPOS_RELATIVE (or NULL) moves the screen by a delta of x1,y1.

    SPOS_ABSOLUTE moves the screen to the specified position x1,y1.

    SPOS_MAKEVISIBLE moves an oversized scrolling screen to make
    the rectangle (x1,y1),(x2,y2) visible
x1,y1 - Absolute (SPOS_ABSOLUTE) or relative (SPOS_RELATIVE) coordinate
    to move screen, or upper-left corner of rectangle
    (SPOS_MAKEVISIBLE)
x2,y2 - Ignored with SPOS_ABSOLUTE and SPOS_RELATIVE.
    Lower-right corner of rectangle with SPOS_MAKEVISIBLE.

Result

None.

Notes

SPOS_FORCEDRAG should only be used by the owner of the screen.

ScreenToBack()

Synopsis

void ScreenToBack(
         struct Screen * screen );

Function

Move a screen behind all other screens. If the screen is in a
group, the screen will be moved behind all other screens in the
group only. If the screen is the parent of a group, the whole
group will be moved in the back.

Inputs

screen - Move this screen.

Result

You will see the screen move behind all other screens. If some
screen before this screen occupies the whole display, then it
will disappear completely. If all other screens occupy only part
of the display, the screen will appear behind the screens.

ScreenToFront()

Synopsis

void ScreenToFront(
         struct Screen * screen );

Function

Move a screen in front of all other screens. If the screen is in a
group, the screen will be moved in front of all other screens in the
group only. If the screen is the parent of a group, the whole
group will be moved in the front.

Inputs

screen - Move this screen.

Result

You will see the screen move in front of all other screens.

ScrollWindowRaster()

Synopsis

void ScrollWindowRaster(
         struct Window * win,
         WORD dx,
         WORD dy,
         WORD xmin,
         WORD ymin,
         WORD xmax,
         WORD ymax );

Function

Scrolls the content of the rectangle defined by (xmin,ymin)-
(xmax,ymax) by (dx,dy) towards (0,0). This function calls
ScrollRasterBF().
The advantage of this function over calling ScrollRasterBF() is
that the window will be informed about damages. A damage happens
if in a simple window parts from concelealed areas are scrolled
to visible areas. The visible areas will be blank as simple
windows store no data for concealed areas.
The blank parts that appear due to the scroll will be filled
with EraseRect() and are not considered damaged areas.

Inputs

win       - pointer to window in which to scroll
dx,dy     - scroll by (dx,dy) towards (0,0)
xmin,ymin - upper left corner of the rectangle that will be
            affected by the scroll
xmax,ymax - lower rigfht corner of the rectangle that will be
            affected by the scroll

SetAttrsA()

Synopsis

ULONG SetAttrsA(
         APTR object,
         struct TagItem * tagList );

ULONG SetAttrs(
         APTR object,
         TAG tag, ... );

Function

Changes several attributes of an object at the same time. How the
object interprets the new attributes depends on the class.

Inputs

object - Change the attributes of this object
tagList - This is a list of attribute/value-pairs

Result

Depends in the class. For gadgets, this value is non-zero if
they need redrawing after the values have changed. Other classes
will define other return values.

Notes

This function sends OM_SET to the object.

SetDefaultPubScreen()

Synopsis

void SetDefaultPubScreen(
         UBYTE * name );

Function

Specifies the default public screen for visitor windows to open up on.
    The screen is used when a requested public screen is not available
and the FALLBACK option is enabled or when the visitor window asks for
the default public screen.

Inputs

name  --  The name of the public screen that should be used as default,
          or NULL to specify the Workbench screen.

SetDMRequest()

Synopsis

BOOL SetDMRequest(
         struct Window * window,
         struct Requester * dmrequest );

Function

Try to set the DMRequest of a window.
A DMRequest is a requester that appears if the user double-clicks
with the menu button.
The new DMRequest will only be set if the old DMRequest is not in use.
The official way to change the DMRequest is to call ClearDMRequest()
until it returns TRUE and then call SetDMRequest().

Inputs

window - The window from which the DMRequest is to be set
dmrequest - Pointer to the requester

Result

TRUE if old DMRequest was not in use and therefore changed to
the new one, or FALSE if the old DMRequest was in use and could
not be set to the new one.

Notes

If the DMRequest has the POINTREL flag set, the DMR will show up
as close to the pointer as possible. The RelLeft/Top fields are
used to fine-tune the positioning.

SetEditHook()

Synopsis

struct Hook * SetEditHook(
         struct Hook * hook );

Function

Sets the global (default) string editing hook of intuition
string gadgets.

Inputs

The stringgagdget editing hook to replace the old one.

Result

The old edit hook.

SetGadgetAttrsA()

Synopsis

IPTR SetGadgetAttrsA(
         struct Gadget * gadget,
         struct Window * window,
         struct Requester * requester,
         struct TagItem * tagList );

IPTR SetGadgetAttrs(
         struct Gadget * gadget,
         struct Window * window,
         struct Requester * requester,
         TAG tag, ... );

Function

Sets some tags and provides gadget specific data. Prefer this to
SetAttrsA(), if you are manipulating gadgets.

Inputs

gadget - Change the attributes of this gadget
window - The window of the gadget
requester - The requester of the gadget (or NULL)
tagList - This is a list of attribute/value-pairs

Result

Depends in the class. For gadgets, this value is non-zero if
they need redrawing after the values have changed. Other classes
will define other return values.

Notes

This function sends OM_SET to the gadget object.

SetIPrefs()

Synopsis

ULONG SetIPrefs(
         APTR data,
         ULONG length,
         ULONG type );

Result

Depending on the operation

SetMenuStrip()

Synopsis

BOOL SetMenuStrip(
         struct Window * window,
         struct Menu   * menu );

Function

This function adds a MenuStrip to the Window, which can be invoked
by the user after this call by pressing the right mouse button.
Menus with no MenuItems will not be attached.

Inputs

window - The window to add the MenuStrip to
menu   - The menu to be added to the window above.

Result

TRUE if all menus have at least one menuitem.

Notes

This function calculates internal values and is therfore the
official way to add a new MenuStrip to Window.
Always do a ClearMenuStrip() before closing the Window or adding
another MenuStrip to the Window.

SetMouseQueue()

Synopsis

LONG SetMouseQueue(
         struct Window * window,
         UWORD queuelength );

Function

Change the number of mouse messages for your window to be allowed
to be outstanding.

Inputs

window - the window
queuelength - the number of mouse messages to be allowed to be
    outstanding

Result

Returns -1 if the window is unknown otherwise the old value of the
queuelength is returned.

Notes

There should be a function for changing the repeat key queue limit, too.

SetPointer()

Synopsis

void SetPointer(
         struct Window * window,
         UWORD         * pointer,
         LONG height,
         LONG width,
         LONG xOffset,
         LONG yOffset );

Function

Changes the shape of the mouse pointer for a given window.

Inputs

window - Change it for this window
pointer - The shape of the new pointer as a bitmap with depth 2.
height - Height of the pointer
width - Width of the pointer (must be <= 16)
xOffset, yOffset - The offset of the "hot spot" relative to the
    left, top edge of the bitmap.

SetPrefs()

Synopsis

struct Preferences * SetPrefs(
         struct Preferences * prefbuffer,
         LONG size,
         BOOL inform );

Function

Sets the current Preferences structure.

Inputs

prefbuffer - The buffer which contains your settings for the
    preferences.
size - The number of bytes of the buffer you want to be copied.
inform - If TRUE, all windows with IDCMP_NEWPREFS IDCMPFlags set
    get an IDCMP_NEWPREFS message.

Result

Returns your parameter buffer.

SetPubScreenModes()

Synopsis

UWORD SetPubScreenModes(
         UWORD modes );

Function

Specify global intuition public screen handling.

Inputs

modes  --  The new set of flags to consider. Currently defined flags are:
           SHANGHAI       Workbench windows are opened on the default
              public screen.
       POPPUBSCREEN   When a visitor window opens on a public screen,
              the screen is brought to front.

Result

The flags set before the change was made.

SetWindowPointerA()

Synopsis

void SetWindowPointerA(
         struct Window * window,
         struct TagItem * taglist );

void SetWindowPointer(
         struct Window * window,
         TAG tag, ... );

SetWindowTitles()

Synopsis

void SetWindowTitles(
         struct Window * window,
         CONST_STRPTR windowTitle,
         CONST_STRPTR screenTitle );

Function

Changes the current window and/or the screen title.

Inputs

window - Change the title for this window or the screen which the
    window contains.
windowTitle - New title for the window or ((UBYTE *)~0L) to keep the
    old title or NULL for no title. If you specify a string,
    this string is *NOT* copied.
screenTitle - New title for the screen of the window or ((UBYTE *)~0L)
    to keep the old title or NULL for no title. If you specify
    a title for the screen, this title will be shown when the
    window becomes active. If you specify a string, this string
    is *NOT* copied.

Result

None.

Notes

You should be careful with specifying a screen title because that
may irritate the user.

ShowTitle()

Synopsis

void ShowTitle(
         struct Screen * screen,
         BOOL ShowIt );

Function

Modify SHOWTITLE flag of the screen and refresh the screen and
its windows.
If ShowIt is TRUE the screen's title bar will be shown in front of
WFLG_BACKDROP windows. A value of FALSE will bring the title bar
behind all windows.

Result

None.

Notes

The default of the SHOWTITLE flag for new screens is TRUE.

ShowWindow()

Synopsis

VOID ShowWindow(
         struct Window * window );

Function

Make a window visible. This function does not bring the
window back into the visible area of the screen but rather
switches it into visible state.

Inputs

window - The window to affect.

SizeWindow()

Synopsis

void SizeWindow(
         struct Window * window,
         LONG dx,
         LONG dy );

Function

Modify the size of a window by the specified offsets.

Inputs

window - The window to resize.
dx - Add this to the width.
dy - Add this to the height.

Result

None.

Notes

The resize of the window may be delayed. If you depend on the
information that is has changed size, wait for IDCMP_NEWSIZE.

StartScreenNotifyTagList()

Synopsis

IPTR StartScreenNotifyTagList(
         struct TagItem * tags );

IPTR StartScreenNotifyTags(
         TAG tag, ... );

Function

Add Notifications to Intuition. You will be notified when
the screen changes.

Inputs

tags - see below

Result

The value is private, only a test against ZERO is allowed and means Failure

SysReqHandler()

Synopsis

LONG SysReqHandler(
         struct Window  * window,
         ULONG   * IDCMPFlagsPtr,
         BOOL WaitInput );

Function

Handles a requester, which was opened with BuildSysRequest() or
BuildEasyRequestArgs(). When this function is called all outstanding
IDCMP requests are processed. If an IDCMP request that would close
a normal EasyRequestArgs() is encountered, SysReqHandler() returns
with a return code equally to the return code EasyRequestArgs()
would have returned. You may call this function in synchronous or
asynchronous mode, by setting the WaitInput parameter.

Inputs

Window - The window pointer returned by either BuildSysRequest() or
         BuildEasyRequestArgs().
IDCMPFlagsPtr - Pointer to a ULONG to store the IDCMP flag that was
                received by the window. This will be set if you
                provided additional IDCMP flags to BuildSysRequest() or
                BuildEasyRequest(). You may set this to NULL. You must
                initialize the pointed to ULONG every time you call
                SysReqHandler().
WaitInput - Set this to TRUE, if you want this function to wait for
            the next IDCMP request, if there is none at the moment
            the function is called.

Result

-2, if the requester was not satisfied. Normally you want to call
    this function at least until this function returns something
    different than -2.
-1, if one of the IDCMP flags of idcmpPTR was set.
 0, if the rightmost button was clicked or an error occured.
 n, if the n-th button from the left was clicked.

Bugs

Gadget placing is still untidy.
Does not support BuildSysRequest() requesters, yet.