[Contents] [index] [Help] [Retrace] [browse <] [Browse >]

In order to ensure their best appearance, GadTools gadgets and menus need
information about the screen on which they will appear.  Before creating
any GadTools gadgets or menus, the program must get this information using
the getvisualinfo() call.

    APTR GetVisualInfoA( struct Screen *screen, struct TagItem *taglist );
    APTR GetVisualInfo( struct Screen *screen, Tag tag1, ... );

Set the screen argument to a pointer to the screen you are using.  The tag
arguments, tag1 or taglist, are reserved for future extensions.  Currently
none are recognized, so only TAG_END should be used.

The function returns an abstract handle called the VisualInfo.  For
GadTools gadgets, the ng_visualinfo field of the newgadget structure must
be set to this handle before the gadget can be added to the window.
GadTools menu layout and creation functions also require the VisualInfo
handle as an argument.

There are several ways to get the pointer to the screen on which the
window will be opened.  If the application has its own custom screen, this
pointer is known from the call to openscreen() or openscreentags().  if
the application already has its window opened on the Workbench or some
other public screen, the screen pointer can be found in window.wscreen.
Often the program will create its gadgets and menus before opening the
window.  In this case, use lockpubscreen() to get a pointer to the desired
public screen, which also provides a lock on the screen to prevent it from
closing.  See the chapters "intuition screens" and "intuition windows" for
more about public screens.

The VisualInfo data must be freed after all the gadgets and menus have
been freed but before releasing the screen.  Custom screens are released
by calling closescreen(), public screens are released by calling
closewindow() or unlockpubscreen(), depending on the technique used.  use
freevisualinfo() to free the visual info data.

    void FreeVisualInfo( APTR vi );

This function takes just one argument, the VisualInfo handle as returned
by getvisualinfo().  the sequence of events for using the visualinfo
handle could look like this:

    init()
    {
    myscreen = LockPubScreen(NULL);
    if (!myscreen)
        {
        cleanup("Failed to lock default public screen");
        }
    vi = GetVisualInfo(myscreen);
    if (!vi)
        {
        cleanup("Failed to GetVisualInfo");
        }
    /* Create gadgets here */
    ng.ng_VisualInfo = vi;
    ...
    }

    void cleanup(STRPTR errorstr)
    {
    /* These functions may be safely called with a NULL parameter: */
    FreeGadgets(glist);
    FreeVisualInfo(vi);

    if (myscreen)
        UnlockPubScreen(NULL, myscreen);

    printf(errorstr);
    }