Autodoc corrections, additions.
[cake.git] / rom / intuition / openscreentaglist.c
blobed44b05099a0852883a09c6d5c986093642d80f7
1 /*
2 Copyright © 1995-2007, The AROS Development Team. All rights reserved.
3 Copyright © 2001-2003, The MorphOS Development Team. All Rights Reserved.
4 $Id$
5 */
7 #include "intuition_intern.h"
9 /*****************************************************************************
11 NAME */
12 #include <utility/tagitem.h>
13 #include <intuition/screens.h>
14 #include <proto/intuition.h>
16 AROS_LH2(struct Screen *, OpenScreenTagList,
18 /* SYNOPSIS */
19 AROS_LHA(struct NewScreen *, newScreen, A0),
20 AROS_LHA(struct TagItem *, tagList, A1),
22 /* LOCATION */
23 struct IntuitionBase *, IntuitionBase, 102, Intuition)
25 /* FUNCTION
26 Open a screen
28 INPUTS
29 newScreen - struct with screen specification. This is for compatibility
30 with OpenScreen() and usually set to NULL.
31 tagList - tags which specify the screen
33 TAGS
34 SA_Left
35 Default: 0
37 SA_Top
38 Default: 0
40 SA_Width
41 Default depends on display clip
43 SA_Height
44 Default depends on display clip
46 SA_Depth
47 Select depth of screen. This specifies how many
48 colors the screen can display.
49 Default: 1
51 SA_DetailPen
52 Pen number for details.
53 Default: 0
55 SA_BlockPen
56 Pen number for block fills.
57 Default: 1
59 SA_Title (STRPTR)
60 Default: NULL
62 SA_Font (struct TextAttr *)
63 Default: NULL, meaning user's preferred monospace font
65 SA_BitMap (struct BitMap *)
66 Provide a custom bitmap.
68 SA_ShowTitle (BOOL)
69 Default: TRUE
71 SA_Behind (BOOL)
72 Screen will be created behind other open screens.
73 Default: FALSE
75 SA_Quiet (BOOL)
76 Intuition doesn't draw system gadgets and screen title.
77 Defaults: FALSE
79 SA_Type
80 PUBLICSCREEN or CUSTOMSCREEN.
82 SA_DisplayID
83 32-bit display mode ID, as defined in the <graphics/modeid.h>.
85 SA_Overscan
86 Set an overscan mode.
88 Possible values:
90 OSCAN_TEXT - A region which is fully visible.
91 Recommended for text display.
93 OSCAN_STANDARD - A region whose edges are "just out of view."
94 Recommended for games and presentations.
96 OSCAN_MAX - Largest region which Intuition can handle comfortably.
98 OSCAN_VIDEO - Largest region the graphics.library can display.
100 Default: OSCAN_TEXT
102 SA_DClip (struct Rectangle *)
103 Define a DisplayClip region. See QueryOverscan().
104 It's easier to use SA_Overscan.
106 SA_AutoScroll (BOOL)
107 Screens can be larger than the DisplayClip region. Set this tag
108 to TRUE if you want to enable automatic scrolling when you reach
109 the edge of the screen with the mouse pointer.
111 SA_PubName (STRPTR)
112 Make this screen a public screen with the given name.
113 Screen is opened in "private" mode.
115 SA_Pens (UWORD *)
116 Define the pen array for struct DrawInfo. This enables
117 the 3D look.
119 This array contains often just the terminator ~0.
120 You define a list of pens which overwrite the DrawInfo pens.
121 The pen arrayy must be terminated with ~0.
123 SA_PubTask (struct Task *)
124 Task to be signalled, when last visitor window of a public
125 screen is closed.
127 SA_PubSig (UBYTE)
128 Signal number used to notify a task when the last visitor window
129 of a public screen is closed.
131 SA_Colors (struct ColorSpec *)
132 Screen's initial color palette. Array must be terminated
133 with ColorIndex = -1.
135 SA_FullPalette (BOOL)
136 Intuition maintains a set of 32 preference colors.
137 Default: FALSE
139 SA_ErrorCode (ULONG *)
140 Intuition puts additional error code in this field when
141 opening the screen failed.
142 OSERR_NOMONITOR - monitor for display mode not available.
143 OSERR_NOCHIPS - you need newer custom chips for display mode.
144 OSERR_NOMEM - couldn't get normal memory
145 OSERR_NOCHIPMEM - couldn't get chip memory
146 OSERR_PUBNOTUNIQUE - public screen name already used
147 OSERR_UNKNOWNMODE - don't recognize display mode requested
148 OSERR_TOODEEP - screen too deep to be displayed on
149 this hardware (V39)
150 OSERR_ATTACHFAIL - An illegal attachment of screens was
151 requested (V39)
153 SA_SysFont
154 Select screen font type. This overwrites SA_Font.
156 Values:
157 0 - Fixed-width font (old-style)
158 1 - Font which is set by font preferences editor. Note: windows opened
159 on this screen will still have the rastport initialized with the
160 fixed-width font (sysfont 0).
162 Default: 0
164 SA_Parent (struct Screen *)
165 Attach the screen to the given parent screen.
167 SA_FrontChild (struct Screen *)
168 Attach given child screen to this screen. Child screen
169 must already be open. The child screen will go to the
170 front of the screen group.
172 SA_BackChild (struct Screen *)
173 Attach given child screen to this screen. Child screen
174 must already be open. The child screen will go behind other
175 child screens.
177 SA_BackFill (struct Hook *)
178 Backfill hook (see layers.library/InstallLayerInfoHook() ).
180 SA_Draggable (BOOL)
181 Make screen draggable.
182 Default: TRUE
184 SA_Exclusive (BOOL)
185 Set to TRUE if the screen must not share the display with
186 other screens. The screen will not be draggable and doesn't
187 appear behind other screens, but it still is depth arrangeable.
188 Default: FALSE
190 SA_SharePens (BOOL)
191 Per default, Intuition obtains the pens of a public screen with PENF_EXCLUSIVE.
192 Set this to TRUE to instruct Intuition to leave the pens unallocated.
193 Default: FALSE
195 SA_Colors32 (ULONG *)
196 Data is forwarded to graphics.library/LoadRGB32().
197 Overwrites values which were set by SA_Colors.
199 SA_Interleaved (BOOL)
200 Request interleaved bimap. It this fails a non-interleaved
201 bitmap will be allocated.
202 Default: FALSE
204 SA_VideoControl (struct TagItem *)
205 Taglist which will be passed to VideoControl() after the
206 screen is open.
208 SA_ColorMapEntries:
209 Number of entries of the ColorMap.
210 Default: 1<<depth, but not less than 32
212 SA_LikeWorkbench (BOOL)
213 Inherit depth, colors, pen-array, screen mode, etc. from
214 the Workbench screen. Individual attributes can be overridden
215 with tags.
216 Default: FALSE
218 SA_MinimizeISG (BOOL)
219 Minimize the Inter-Screen-Gap. For compatibility,
221 RESULT
222 Pointer to screen or NULL if opening fails.
224 NOTES
225 If you need a pointer to the screen's bitmap use Screen->RastPort.BitMap
226 instead of &Screen->BitMap.
228 If you want DOS requester to appear on your screen you have to do:
229 process = FindTask(0);
230 process->pr_WindowPtr = (APTR) window;
231 The old value of pr->WindowPtr must be reset before you quit your
232 program.
234 EXAMPLE
236 BUGS
238 SEE ALSO
240 INTERNALS
242 HISTORY
243 29-10-95 digulla automatically created from
244 intuition_lib.fd and clib/intuition_protos.h
246 *****************************************************************************/
248 AROS_LIBFUNC_INIT
250 struct ExtNewScreen ns =
252 0, 0, -1, -1, 1, /* left, top, width, height, depth */
253 0, 1, /* DetailPen, BlockPen */
254 HIRES | LACE, /* ViewModes */
255 CUSTOMSCREEN | SHOWTITLE, /* Type */
256 NULL, /* Font */
257 NULL, /* DefaultTitle */
258 NULL, /* Gadgets */
259 NULL, /* CustomBitMap */
260 NULL /* Extension (taglist) */
263 DEBUG_OPENSCREENTAGLIST(dprintf("OpenScreenTagList: NewScreen 0x%lx Tags 0x%lx\n",
264 newScreen, tagList));
265 ns.DetailPen = GetPrivIBase(IntuitionBase)->DriPens4[DETAILPEN];
266 ns.BlockPen = GetPrivIBase(IntuitionBase)->DriPens4[BLOCKPEN];
268 if (newScreen)
269 CopyMem (newScreen, &ns, (newScreen->Type & NS_EXTENDED) ? sizeof (struct ExtNewScreen) :
270 sizeof (struct NewScreen));
272 if (tagList)
274 ns.Extension = tagList;
275 ns.Type |= NS_EXTENDED;
278 #ifdef __MORPHOS__
279 /* calling OpenScreen through the library vector causes a loop with cgx's patch. */
281 extern ULONG LIB_OpenScreen(void);
283 REG_A0 = (LONG)&ns;
284 REG_A6 = (LONG)IntuitionBase;
286 return (struct Screen *) LIB_OpenScreen();
288 #else
289 return OpenScreen ((struct NewScreen *)&ns);
290 #endif
292 AROS_LIBFUNC_EXIT
294 } /* OpenScreenTagList */