[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]


   NAME	
	OpenScreenTagList -- OpenScreen() with TagItem extension array. (V36)
	OpenScreenTags -- Varargs stub for OpenScreenTagList. (V36)

   SYNOPSIS
	Screen = OpenScreenTagList( NewScreen, TagItems )
	D0	  		    A0         A1

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

	Screen = OpenScreenTags( NewScreen, Tag1, ... )

	struct Screen *OpenScreenTags( struct NewScreen *,
		ULONG, ... );

   FUNCTION
	Provides an extension to the parameters passed to OpenScreen().
	This extensions is in the form of (a pointer to) an array of
	TagItem structures, which have to fields: ti_Tag, an ID identifying
	the meaning of the other field, ti_Data.  See <utility/tagitem.h>.

	The tag items can supplement or override the values in NewScreen.
	In fact, you can pass a NULL value of the NewScreen pointer.
	For that matter, if you pass NULL in both arguments, you'll get
	a screen with defaults in all fields, including display mode,
	depth, colors, dimension, title, and so on.  We ask that
	you at least supply a title when you open a screen.

	See OpenScreen() documentation for parameter specifications.

   INPUTS
 	NewScreen     - (optional) pointer to a NewScreen structure.
 	TagItems      - (optional) pointer to (an array of) TagItem
			structures, terminated by the value TAG_END.

   RESULT
 	Screen	- an open Intuition screen.  See OpenScreen() for
		extended error codes when Screen is returned NULL.

   EXAMPLE
	The version using a variable number of arguments must be
	created for each particular compiler, and may not have
	an analogue in all versions.  For vanilla, 32-bit C
	parameter passing conventions, this works (and will
	appear in amiga.lib):

	struct Screen	*
	OpenScreenTags( ns, tag1 )
	struct NewScreen	*ns;
	ULONG			tag1;
	{
	    struct Screen	*OpenScreenTagList();

	    return ( OpenScreenTagList( ns, (struct TagItem *) &tag1 ) );
	}

   NOTES
	We recommend this extension to OpenScreen() over using the
	field ExtNewScreen.Extension.  However, the ExtNewScreen.Extension
	is a convenient way to supply a few tags to V36 Intuition which
	will be ignored by V34 Intuition.  See OpenScreen() documentation
	for lots of details.

	A VERY IMPORTANT NOTE about the Screen->BitMap.  In the future,
	bitmaps will need to grow.  The embedded instance of a bitmap
	in the screen will no longer be large enough to hold the whole
	description of the bitmap.

	YOU ARE STRONGLY URGED to use Screen->RastPort.BitMap in place of
	&Screen->BitMap whenever and whereever possible.

   BUGS


   SEE ALSO
	OpenScreen()