Window Structures and Functions - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:05:52Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:05, 26 January 2025
Line 39:		Line 39:
	The Window structure is the main Intuition data structure used to represent a window. For the most part, applications treat this structure only as a handle. Window operations are performed by calling system functions that take Window as an argument instead of directly manipulating fields within the structure. However, there are some useful variables in a Window structure which are discussed in this section.		The Window structure is the main Intuition data structure used to represent a window. For the most part, applications treat this structure only as a handle. Window operations are performed by calling system functions that take Window as an argument instead of directly manipulating fields within the structure. However, there are some useful variables in a Window structure which are discussed in this section.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Window		struct Window
	{		{
Line 275:		Line 275:
	A window is opened and displayed by a call to one of the OpenWindow() functions: OpenWindow(), OpenWindowTagList() or OpenWindowTags().		A window is opened and displayed by a call to one of the OpenWindow() functions: OpenWindow(), OpenWindowTagList() or OpenWindowTags().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Window OpenWindowTagList( struct NewWindow newWindow, struct TagItem *tagList );		struct Window OpenWindowTagList( struct NewWindow newWindow, struct TagItem *tagList );
	struct Window OpenWindowTags( struct NewWindow newWindow, ULONG tag1Type, ... );		struct Window OpenWindowTags( struct NewWindow newWindow, ULONG tag1Type, ... );
Line 293:		Line 293:
	Here's an example showing how to open a new window using the OpenWindowTagList() function with window attributes set up in a TagItem array.		Here's an example showing how to open a new window using the OpenWindowTagList() function with window attributes set up in a TagItem array.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	** openwindowtags.c - open a window using tags.		** openwindowtags.c - open a window using tags.
Line 373:		Line 373:
	Depending on which function is used to open a window, the window's attributes may be specified using TagItems, or a NewWindow structure or an ExtNewWindow structure. In the code above, the window attributes are set up with an array of TagItems:		Depending on which function is used to open a window, the window's attributes may be specified using TagItems, or a NewWindow structure or an ExtNewWindow structure. In the code above, the window attributes are set up with an array of TagItems:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct TagItem win_tags[] =		struct TagItem win_tags[] =
	{		{
Line 394:		Line 394:
	Call the CloseWindow() function to close a window, remove its imagery from the display, and clean up any system resources used by the window. Typically, you call CloseWindow() when Intuition informs you that the user has selected the window's close gadget but this is not a requirement nor does the window have to be active to be closed.		Call the CloseWindow() function to close a window, remove its imagery from the display, and clean up any system resources used by the window. Typically, you call CloseWindow() when Intuition informs you that the user has selected the window's close gadget but this is not a requirement nor does the window have to be active to be closed.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID CloseWindow( struct Window *window );		VOID CloseWindow( struct Window *window );
	</syntaxhighlight>		</syntaxhighlight>
Line 426:		Line 426:
	== Simple Window on a Public Screen Example ==		== Simple Window on a Public Screen Example ==

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	** winpubscreen.c		** winpubscreen.c
Line 531:		Line 531:
	Two other functions, SetMenuStrip() and ResetMenuStrip(), are used to attach or update the menu strip for a window.		Two other functions, SetMenuStrip() and ResetMenuStrip(), are used to attach or update the menu strip for a window.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID ClearMenuStrip( struct Window *window );		VOID ClearMenuStrip( struct Window *window );
	BOOL SetMenuStrip( struct Window window, struct Menu menu );		BOOL SetMenuStrip( struct Window window, struct Menu menu );
Line 567:		Line 567:
	{{Note\|title=About Screen Coordinates\|text=The screen's actual position may not exactly equal the coordinates given in the LeftEdge and TopEdge fields of the Screen structure. This is due to hardware constraints that limit the fineness of the positioning of the underlying constructs. This may cause a window which is opened in the visible part of the screen to be incorrectly positioned by a small number of pixels in each direction. See the discussion of the screen's LeftEdge and TopEdge in [[Intuition_Screens\|Intuition Screens]] for more information.}}		{{Note\|title=About Screen Coordinates\|text=The screen's actual position may not exactly equal the coordinates given in the LeftEdge and TopEdge fields of the Screen structure. This is due to hardware constraints that limit the fineness of the positioning of the underlying constructs. This may cause a window which is opened in the visible part of the screen to be incorrectly positioned by a small number of pixels in each direction. See the discussion of the screen's LeftEdge and TopEdge in [[Intuition_Screens\|Intuition Screens]] for more information.}}

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* visiblewindow.c		/* visiblewindow.c
	**		**
Line 748:		Line 748:
	{{Note\|title=Gadgets Can Change Border Sizes\|text=The following calculations do not take application border gadgets into account. If the program adds gadgets into the window's borders, Intuition will expand the borders to hold the gadgets.}}		{{Note\|title=Gadgets Can Change Border Sizes\|text=The following calculations do not take application border gadgets into account. If the program adds gadgets into the window's borders, Intuition will expand the borders to hold the gadgets.}}

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	if (NULL != (screen = IIntuition->LockPubScreen(NULL)))		if (NULL != (screen = IIntuition->LockPubScreen(NULL)))
	{		{
Line 791:		Line 791:
	To change the sizing limits after the window has been opened, call WindowLimits() with the new values.		To change the sizing limits after the window has been opened, call WindowLimits() with the new values.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	BOOL WindowLimits( struct Window *window, LONG widthMin, LONG heightMin,		BOOL WindowLimits( struct Window *window, LONG widthMin, LONG heightMin,
	ULONG widthMax, ULONG heightMax );		ULONG widthMax, ULONG heightMax );
Line 802:		Line 802:
	Each window has its own window title and local screen title. The window title, if specified, is always displayed in the window. The local screen title, if specified, is only displayed in the screen's title bar when the window is active. If the window does not specify a local screen title, then the default screen title is used in the screen title bar when this window is active.		Each window has its own window title and local screen title. The window title, if specified, is always displayed in the window. The local screen title, if specified, is only displayed in the screen's title bar when the window is active. If the window does not specify a local screen title, then the default screen title is used in the screen title bar when this window is active.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID SetWindowTitles( struct Window *window, STRPTR windowTitle,		VOID SetWindowTitles( struct Window *window, STRPTR windowTitle,
	STRPTR screenTitle );		STRPTR screenTitle );
Line 839:		Line 839:
	The active window also has control over the pointer. If the active window changes the image for the pointer using the functions SetPointer() or ClearPointer(), the pointer image will change:		The active window also has control over the pointer. If the active window changes the image for the pointer using the functions SetPointer() or ClearPointer(), the pointer image will change:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID SetPointer( struct Window window, UWORD pointer, LONG height,		VOID SetPointer( struct Window window, UWORD pointer, LONG height,
	LONG width, LONG xOffset, LONG yOffset );		LONG width, LONG xOffset, LONG yOffset );
Line 860:		Line 860:
	Use the MoveWindow() function to move a window to a new position in the screen. Use SizeWindow() to change the size of the window:		Use the MoveWindow() function to move a window to a new position in the screen. Use SizeWindow() to change the size of the window:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID MoveWindow( struct Window *window, LONG dx, LONG dy );		VOID MoveWindow( struct Window *window, LONG dx, LONG dy );
	VOID SizeWindow( struct Window *window, LONG dx, LONG dy );		VOID SizeWindow( struct Window *window, LONG dx, LONG dy );
Line 869:		Line 869:
	ChangeWindowBox() allows an application to change the window size and position in a single call:		ChangeWindowBox() allows an application to change the window size and position in a single call:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID ChangeWindowBox( struct Window *window, LONG left, LONG top, LONG width, LONG height );		VOID ChangeWindowBox( struct Window *window, LONG left, LONG top, LONG width, LONG height );
	</syntaxhighlight>		</syntaxhighlight>
Line 877:		Line 877:
	To depth arrange windows under program control, use WindowToFront() and WindowToBack():		To depth arrange windows under program control, use WindowToFront() and WindowToBack():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID WindowToFront( struct Window *window );		VOID WindowToFront( struct Window *window );
	VOID WindowToBack( struct Window *window );		VOID WindowToBack( struct Window *window );
Line 886:		Line 886:
	To move a window in front of a specific, given window (as opposed to all windows), use MoveWindowInFrontOf():		To move a window in front of a specific, given window (as opposed to all windows), use MoveWindowInFrontOf():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID MoveWindowInFrontOf( struct Window window, struct Window behindWindow );		VOID MoveWindowInFrontOf( struct Window window, struct Window behindWindow );
	</syntaxhighlight>		</syntaxhighlight>
Line 892:		Line 892:
	To toggle the window size between its two zoom settings use ZipWindow(). This performs the same action that occurs when the user selects the zoom gadget:		To toggle the window size between its two zoom settings use ZipWindow(). This performs the same action that occurs when the user selects the zoom gadget:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID ZipWindow( struct Window *window );		VOID ZipWindow( struct Window *window );
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie: /* A Display Sized Window Example */

2015-11-03T20:42:54Z

A Display Sized Window Example

← Older revision		Revision as of 20:42, 3 November 2015
Line 653:		Line 653:
	** clip of the screen, use the VideoControl() command of the graphics library		** clip of the screen, use the VideoControl() command of the graphics library
	** to return a copy of the ViewPortExtra structure. See the Graphics		** to return a copy of the ViewPortExtra structure. See the Graphics
	** library ~~chapter~~ and Autodocs for more details.		** library articles and Autodocs for more details.
	*/		*/

Steven Solie: /* Opening a Window */

2015-11-03T20:42:35Z

Opening a Window

← Older revision		Revision as of 20:42, 3 November 2015
Line 287:		Line 287:
	OpenWindow() is available in all versions of the OS. Window attributes can be specified using a NewWindow structure but only a limited set of window attributes are available this way. To support both the new window features and compatibility with older versions of the OS, use OpenWindow() with an extended version of the NewWindow structure named ExtNewWindow. See the WFLG_NW_EXTENDED flag description in the "Window Attributes" section below for more information on using OpenWindow() with the extended NewWindow structure.		OpenWindow() is available in all versions of the OS. Window attributes can be specified using a NewWindow structure but only a limited set of window attributes are available this way. To support both the new window features and compatibility with older versions of the OS, use OpenWindow() with an extended version of the NewWindow structure named ExtNewWindow. See the WFLG_NW_EXTENDED flag description in the "Window Attributes" section below for more information on using OpenWindow() with the extended NewWindow structure.

	Further references to OpenWindow() in this ~~chapter~~ will apply to all three functions. These calls are the only proper method for allocating a Window structure. The tag based versions are recommended for V36 and later versions of the OS. Use the ExtNewWindow structure with OpenWindow() to provide backward compatibility.		Further references to OpenWindow() in this article will apply to all three functions. These calls are the only proper method for allocating a Window structure. The tag based versions are recommended for V36 and later versions of the OS. Use the ExtNewWindow structure with OpenWindow() to provide backward compatibility.

	== OpenWindowTagList() Example ==		== OpenWindowTagList() Example ==
Line 360:		Line 360:

	/* Normally this routine would contain an event loop like the one given		/* Normally this routine would contain an event loop like the one given
	** in the ~~chapter~~ "Intuition Input and Output Methods". Here we just		** in the article "Intuition Input and Output Methods". Here we just
	** wait for any messages we requested to appear at the Window's port.		** wait for any messages we requested to appear at the Window's port.
	*/		*/

Steven Solie: /* Setting Window Attributes */

2015-10-30T22:37:23Z

Setting Window Attributes

← Older revision		Revision as of 22:37, 30 October 2015
Line 388:		Line 388:
	These window attributes set the window's position (WA_Left, WA_Top) and size (WA_Width, WA_Height), request a close gadget on the window (WA_CloseGadget) and ask Intuition to send a message whenever the user activates the close gadget (WA_IDCMP).		These window attributes set the window's position (WA_Left, WA_Top) and size (WA_Width, WA_Height), request a close gadget on the window (WA_CloseGadget) and ask Intuition to send a message whenever the user activates the close gadget (WA_IDCMP).

	Throughout this ~~chapter~~ window attributes are referred to by their TagItem ID name (the name is always prefixed with "WA_"). See the section below on "Window Attributes" for a complete list.		Throughout this article window attributes are referred to by their TagItem ID name (the name is always prefixed with "WA_"). See the section below on "Window Attributes" for a complete list.

	= Closing Windows =		= Closing Windows =

Steven Solie: /* Windows and Screens */

2015-10-30T22:36:57Z

Windows and Screens

← Older revision		Revision as of 22:36, 30 October 2015
Line 418:		Line 418:
	Another method to open a visitor window on a public screen is to use the WA_PubScreen tag along with a pointer to the Screen structure of the public screen obtained via LockPubScreen().		Another method to open a visitor window on a public screen is to use the WA_PubScreen tag along with a pointer to the Screen structure of the public screen obtained via LockPubScreen().

	The application may also request the name of the "next" public screen, which allows windows to "jump" between public screens. This is done by closing the application window on the first screen and opening a new window on the next screen. (See ~~the~~ [[Intuition_Screens\|Intuition Screens]] ~~chapter~~ for more information on public and custom screens.)		The application may also request the name of the "next" public screen, which allows windows to "jump" between public screens. This is done by closing the application window on the first screen and opening a new window on the next screen. (See [[Intuition_Screens\|Intuition Screens]] for more information on public and custom screens.)

	If no action is taken by the programmer to open the window on a specific screen, the window will open on the default public screen (normally the Workbench). This behavior is shown in the above example using OpenWindowTagList().		If no action is taken by the programmer to open the window on a specific screen, the window will open on the default public screen (normally the Workbench). This behavior is shown in the above example using OpenWindowTagList().

Steven Solie: /* Opening a Window */

2015-10-30T22:36:06Z

Opening a Window

← Older revision		Revision as of 22:36, 30 October 2015
Line 283:		Line 283:
	The type of window and its attributes are specified in NewWindow or TagItem structures depending on which function is used. These functions all return a pointer to a new Window structure if they succeed. A NULL return indicates failure.		The type of window and its attributes are specified in NewWindow or TagItem structures depending on which function is used. These functions all return a pointer to a new Window structure if they succeed. A NULL return indicates failure.

	For the OpenWindowTagList() and OpenWindowTags() functions, window attributes are specified in TagItem structures which are paired data items specifying an attribute and its setting. (See ~~the "~~Utility Library~~" chapter~~ for more information on TagItems.)		For the OpenWindowTagList() and OpenWindowTags() functions, window attributes are specified in TagItem structures which are paired data items specifying an attribute and its setting. (See [[Utility_Library\|Utility Library]] for more information on TagItems.)

	OpenWindow() is available in all versions of the OS. Window attributes can be specified using a NewWindow structure but only a limited set of window attributes are available this way. To support both the new window features and compatibility with older versions of the OS, use OpenWindow() with an extended version of the NewWindow structure named ExtNewWindow. See the WFLG_NW_EXTENDED flag description in the "Window Attributes" section below for more information on using OpenWindow() with the extended NewWindow structure.		OpenWindow() is available in all versions of the OS. Window attributes can be specified using a NewWindow structure but only a limited set of window attributes are available this way. To support both the new window features and compatibility with older versions of the OS, use OpenWindow() with an extended version of the NewWindow structure named ExtNewWindow. See the WFLG_NW_EXTENDED flag description in the "Window Attributes" section below for more information on using OpenWindow() with the extended NewWindow structure.

Steven Solie: /* Windows and Screens */

2014-04-11T19:23:33Z

Windows and Screens

@@ Line 524: / Line 524: @@
+}
 </syntaxhighlight>
 = Graphics and Text in Windows =

Steven Solie: /* Custom Pointers */

2014-04-11T19:17:09Z

Custom Pointers

← Older revision		Revision as of 19:17, 11 April 2014
Line 835:		Line 835:

	ClearPointer() clears the custom pointer from the window and restores it to the default Intuition pointer, which is set by the user. Setting a pointer for a window is discussed further in [[Intuition_Pointer\|Intuition Pointer]].		ClearPointer() clears the custom pointer from the window and restores it to the default Intuition pointer, which is set by the user. Setting a pointer for a window is discussed further in [[Intuition_Pointer\|Intuition Pointer]].

			= Program Control of Window Arrangement =

			MoveWindow(), SizeWindow(), WindowToFront() and WindowToBack() allow the program to modify the size and placement of its windows. These calls are available in all versions of the operating system.

			MoveWindowInFrontOf(), ChangeWindowBox() and ZipWindow() provide more flexible control over the size and placement of windows.

			All of these functions are asynchronous. The window will not be affected by them immediately, rather, Intuition will act on the request the next time it receives an input event. Currently this happens at a minimum rate of ten times per second, and a maximum of sixty times per second. There is no guarantee that the operation has taken place when the function returns. In some cases, there are IDCMP messages which will inform the application when the change has completed (for example, an IDCMP_NEWSIZE event indicates that a resize operation has completed).

			Use the MoveWindow() function to move a window to a new position in the screen. Use SizeWindow() to change the size of the window:

			<syntaxhighlight>
			VOID MoveWindow( struct Window *window, LONG dx, LONG dy );
			VOID SizeWindow( struct Window *window, LONG dx, LONG dy );
			</syntaxhighlight>

			Note that both MoveWindow() and SizeWIndow() take the amount of change in each axis (delta values instead of absolute coordinates). To specify the coordinates as absolute numbers, use ChangeWindowBox(). The SizeWindow() function will respect the window's maximum and minimum dimensions only if the window has a sizing gadget.

			ChangeWindowBox() allows an application to change the window size and position in a single call:

			<syntaxhighlight>
			VOID ChangeWindowBox( struct Window *window, LONG left, LONG top, LONG width, LONG height );
			</syntaxhighlight>

			Note that the position and size values are absolutes and not deltas. The window's maximum and minimum dimensions are always respected.

			To depth arrange windows under program control, use WindowToFront() and WindowToBack():

			<syntaxhighlight>
			VOID WindowToFront( struct Window *window );
			VOID WindowToBack( struct Window *window );
			</syntaxhighlight>

			WindowToFront() depth arranges a given window in front of all other windows on its screen. WindowToBack() depth arranges a given window behind all other windows on its screen.

			To move a window in front of a specific, given window (as opposed to all windows), use MoveWindowInFrontOf():

			<syntaxhighlight>
			VOID MoveWindowInFrontOf( struct Window window, struct Window behindWindow );
			</syntaxhighlight>

			To toggle the window size between its two zoom settings use ZipWindow(). This performs the same action that occurs when the user selects the zoom gadget:

			<syntaxhighlight>
			VOID ZipWindow( struct Window *window );
			</syntaxhighlight>

			The two zoom settings are the initial size and position of the window when it was first opened and the alternate position specified with the WA_Zoom tag. If no WA_Zoom tag is provided, the alternate position is taken from the window's minimum dimensions, unless the window was opened at its minimum dimension. In that case, the alternate position is taken from the window's maximum dimension.

Steven Solie: /* Changing Pointer Position Reports */

2014-04-11T19:15:50Z

Changing Pointer Position Reports

← Older revision		Revision as of 19:15, 11 April 2014
Line 820:		Line 820:

	Mouse reporting may be turned on even if mouse movements were not activated when the window was opened. The proper IDCMP flags must be set for the window to receive the messages. See [[Intuition_Mouse\|Intuition Mouse]] for more details on enabling mouse reporting in an application.		Mouse reporting may be turned on even if mouse movements were not activated when the window was opened. The proper IDCMP flags must be set for the window to receive the messages. See [[Intuition_Mouse\|Intuition Mouse]] for more details on enabling mouse reporting in an application.

			= Custom Pointers =

			The active window also has control over the pointer. If the active window changes the image for the pointer using the functions SetPointer() or ClearPointer(), the pointer image will change:

			<syntaxhighlight>
			VOID SetPointer( struct Window window, UWORD pointer, LONG height,
			LONG width, LONG xOffset, LONG yOffset );

			VOID ClearPointer( struct Window *window );
			</syntaxhighlight>

			SetPointer() sets up the window with a sprite definition for a custom pointer. If the window is active, the change takes place immediately. The pointer will not change if an inactive window calls SetPointer(). In this way, each window may have its own custom pointer that is displayed only when the window is active.

			ClearPointer() clears the custom pointer from the window and restores it to the default Intuition pointer, which is set by the user. Setting a pointer for a window is discussed further in [[Intuition_Pointer\|Intuition Pointer]].

Steven Solie: /* Changing Message Queue Limits */

2014-04-11T19:14:49Z

Changing Message Queue Limits

← Older revision		Revision as of 19:14, 11 April 2014
Line 814:		Line 814:

	Note that real information may be lost if the queue fills and Intuition is forced to discard messages. See [[Intuition_Mouse\|Intuition Mouse]] for more information.		Note that real information may be lost if the queue fills and Intuition is forced to discard messages. See [[Intuition_Mouse\|Intuition Mouse]] for more information.

			= Changing Pointer Position Reports =

			Pointer position messages to a window may be turned on and off by simply setting or clearing the WFLG_REPORTMOUSE flag bit in Window->Flags, in an atomic way, as explained for the WA_RMBTrap tag in the "Window Attributes" section above. Using this direct method of setting the flag avoids the historic confusion on the ordering of the arguments of the ReportMouse() function call.

			Mouse reporting may be turned on even if mouse movements were not activated when the window was opened. The proper IDCMP flags must be set for the window to receive the messages. See [[Intuition_Mouse\|Intuition Mouse]] for more details on enabling mouse reporting in an application.