BOOPSI Gadgets - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:10:52Z

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

← Older revision		Revision as of 19:10, 26 January 2025
Line 37:		Line 37:
	The formats of each of these BOOPSI messages differ, but they all have two things in common. Like all BOOPSI messages, each starts with their respective method ID. For each of these methods, the method ID field is followed by a pointer to a GadgetInfo structure (defined in <intuition/cghooks.h>). The GadgetInfo structure contains information about the display on which the gadget needs to render itself:		The formats of each of these BOOPSI messages differ, but they all have two things in common. Like all BOOPSI messages, each starts with their respective method ID. For each of these methods, the method ID field is followed by a pointer to a GadgetInfo structure (defined in <intuition/cghooks.h>). The GadgetInfo structure contains information about the display on which the gadget needs to render itself:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct GadgetInfo {		struct GadgetInfo {
	struct Screen *gi_Screen;		struct Screen *gi_Screen;
Line 86:		Line 86:
	Intuition uses the GM_DOMAIN method to determine the basic sizing requirements of an object. The domain is most often used by layout gadgets to aid in distributing the gadgets within the layout via GM_LAYOUT. The GM_DOMAIN method uses the gpDomain structure (defined in <intuition/gadgetclass.h>) as its message:		Intuition uses the GM_DOMAIN method to determine the basic sizing requirements of an object. The domain is most often used by layout gadgets to aid in distributing the gadgets within the layout via GM_LAYOUT. The GM_DOMAIN method uses the gpDomain structure (defined in <intuition/gadgetclass.h>) as its message:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct gpDomain		struct gpDomain
	{		{
Line 138:		Line 138:
	If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):		If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct gpInput /* Used by GM_GOACTIVE and GM_HANDLEINPUT */		struct gpInput /* Used by GM_GOACTIVE and GM_HANDLEINPUT */
	{		{
Line 194:		Line 194:
	After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message (defined in <intuition/gadgetclass.h>):		After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message (defined in <intuition/gadgetclass.h>):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct gpGoInactive		struct gpGoInactive
	{		{
Line 210:		Line 210:
	This method uses the same message structure as GM_HITTEST, struct gpHitTest, and operates similarly to GM_HITTEST. While a window is in help mode, when the user positions the pointer within the bounding box of a BOOPSI gadget that supports gadget help, Intuition sends the gadget a GM_HELPTEST message. After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message.		This method uses the same message structure as GM_HITTEST, struct gpHitTest, and operates similarly to GM_HITTEST. While a window is in help mode, when the user positions the pointer within the bounding box of a BOOPSI gadget that supports gadget help, Intuition sends the gadget a GM_HELPTEST message. After an active gadget deactivates, Intuition sends it a GM_GOINACTIVE message.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct gpHitTest		struct gpHitTest
	{		{
Line 234:		Line 234:
	When Intuition gets a left mouse button click in a window, one of the things it does is check through the window's list of gadgets to see if that click was inside the bounds of a gadget's Gadget structure (using the LeftEdge, TopEdge, Width, and Height fields). If it was (and that gadget is a BOOPSI gadget), Intuition sends that gadget a GM_HITTEST message (defined in <intuition/gadgetclass.h>):		When Intuition gets a left mouse button click in a window, one of the things it does is check through the window's list of gadgets to see if that click was inside the bounds of a gadget's Gadget structure (using the LeftEdge, TopEdge, Width, and Height fields). If it was (and that gadget is a BOOPSI gadget), Intuition sends that gadget a GM_HITTEST message (defined in <intuition/gadgetclass.h>):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct gpHitTest		struct gpHitTest
	{		{
Line 255:		Line 255:
	Intuition uses the GM_LAYOUT method to tell a GREL BOOPSI gadget that its window's dimensions have changed. The GM_LAYOUT method uses the gpLayout structure (defined in <intuition/gadgetclass.h>) as its message:		Intuition uses the GM_LAYOUT method to tell a GREL BOOPSI gadget that its window's dimensions have changed. The GM_LAYOUT method uses the gpLayout structure (defined in <intuition/gadgetclass.h>) as its message:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct gpLayout		struct gpLayout
	{		{
Line 283:		Line 283:
	Every time Intuition feels it is necessary to redraw a BOOPSI gadget, it sends a gadget a GM_RENDER message. The GM_RENDER message (defined in <intuition/gadgetclass.h>) tells a gadget to render itself:		Every time Intuition feels it is necessary to redraw a BOOPSI gadget, it sends a gadget a GM_RENDER message. The GM_RENDER message (defined in <intuition/gadgetclass.h>) tells a gadget to render itself:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct gpRender		struct gpRender
	{		{

Frédéric Khannouf: /* RKMButtonclass.c */

2024-09-10T09:06:10Z

RKMButtonclass.c

← Older revision		Revision as of 09:06, 10 September 2024
Line 326:		Line 326:
	While the user has the RKMButton selected, the gadget sends an OM_UPDATE message to its ICA_TARGET for every timer event the button sees.		While the user has the RKMButton selected, the gadget sends an OM_UPDATE message to its ICA_TARGET for every timer event the button sees.

	The gadget sends notification about its RKMBUT_Pulse attribute, which is the horizontal distance in screen pixels the mouse is from the center of the button.~~<br>~~		The gadget sends notification about its RKMBUT_Pulse attribute, which is the horizontal distance in screen pixels the mouse is from the center of the button.
	The gadget takes care of rendering all of its imagery (as opposed to using a BOOPSI image to do it).~~<br>~~		The gadget takes care of rendering all of its imagery (as opposed to using a BOOPSI image to do it).
	The gadget's imagery is scalable to any dimensions and can be set (using SetGadgetAttrs()) while the gadget is in place.~~<br>~~		The gadget's imagery is scalable to any dimensions and can be set (using SetGadgetAttrs()) while the gadget is in place.

	One possible use for such a gadget is as buttons for a prop gadget.		One possible use for such a gadget is as buttons for a prop gadget.

	If the user has the prop gadget's RKMButton selected, while the mouse is to the left of the button's center, the knob on the prop gadget moves left.~~<br>~~		If the user has the prop gadget's RKMButton selected, while the mouse is to the left of the button's center, the knob on the prop gadget moves left.
	While the mouse is to the right of the button's center, the knob on the prop gadget moves right.~~<br>~~		While the mouse is to the right of the button's center, the knob on the prop gadget moves right.
	The speed at which the knob moves is proportional to the horizontal distance from the mouse to the active RKMButton.~~<br>~~		The speed at which the knob moves is proportional to the horizontal distance from the mouse to the active RKMButton.

	<syntaxhighlight lang="cpp">		<syntaxhighlight lang="cpp">

Frédéric Khannouf: /* RKMButtonclass.c */ Little fixes and type castings to make g++ happy

2024-09-10T09:04:27Z

RKMButtonclass.c: Little fixes and type castings to make g++ happy

Show changes

Steven Solie: /* RKMButtonclass.c */

2014-05-16T16:50:48Z

RKMButtonclass.c

Show changes

Steven Solie at 20:09, 13 May 2013

2013-05-13T20:09:59Z

← Older revision		Revision as of 20:09, 13 May 2013
Line 457:		Line 457:
	"<-- Click to resize gadget Height",		"<-- Click to resize gadget Height",
	NULL);		NULL);
	MainLoop(~~TAG_DONE~~, 0L);		MainLoop(TAG_END, 0L);

	SetWindowTitles(w,		SetWindowTitles(w,
Line 499:		Line 499:
	ULONG done = FALSE;		ULONG done = FALSE;

	SetGadgetAttrs(but, w, NULL, attr, value, ~~TAG_DONE~~);		SetGadgetAttrs(but, w, NULL, attr, value, TAG_END);

	while (done == FALSE)		while (done == FALSE)
Line 723:		Line 723:
	tt[1].ti_Data = ((struct Gadget *)o)->GadgetID;		tt[1].ti_Data = ((struct Gadget *)o)->GadgetID;

	tt[2].ti_Tag = ~~TAG_DONE~~;		tt[2].ti_Tag = TAG_END;

	IDoSuperMethod(cl, o, OM_NOTIFY, tt, gpi->gpi_GInfo, flags);		IDoSuperMethod(cl, o, OM_NOTIFY, tt, gpi->gpi_GInfo, flags);

Steven Solie: /* GM_EXTENT */

2013-04-15T18:44:32Z

GM_EXTENT

← Older revision		Revision as of 18:44, 15 April 2013
Line 100:		Line 100:
	The gpd_Which field is used to determine which domain the caller is interested in: GDOMAIN_MINIMUM, GDOMAIN_NOMINAL or GDOMAIN_MAXIMUM. The object is expected to fill in the provided gpd_Domain with the width and height dimensions. The location coordinates are not used. The gpd_Attrs pointer, if not NULL, may contain additional tags which are defined on a per-class basis.		The gpd_Which field is used to determine which domain the caller is interested in: GDOMAIN_MINIMUM, GDOMAIN_NOMINAL or GDOMAIN_MAXIMUM. The object is expected to fill in the provided gpd_Domain with the width and height dimensions. The location coordinates are not used. The gpd_Attrs pointer, if not NULL, may contain additional tags which are defined on a per-class basis.

	==== GM_EXTENT ====		==== GM_EXTENT (V51) ====

	The GM_EXTENT method is used to ask the gadget what pixels (at least) it will fully redraw when its GM_RENDER method is invoked in the same context. By "fully redraw" we mean changing the pixel's color in a way that is totally unrelated to its previous value -- so this doesn't apply to alpha-blended pixels for example.		The GM_EXTENT method is used to ask the gadget what pixels (at least) it will fully redraw when its GM_RENDER method is invoked in the same context. By "fully redraw" we mean changing the pixel's color in a way that is totally unrelated to its previous value -- so this doesn't apply to alpha-blended pixels for example.

Steven Solie: /* Region and RastPort Support */

2013-04-15T18:43:50Z

Region and RastPort Support

← Older revision		Revision as of 18:43, 15 April 2013
Line 134:		Line 134:
	{{Note\|text=As of Intuition V51 the mask method is not yet implemented.}}		{{Note\|text=As of Intuition V51 the mask method is not yet implemented.}}

			==== GM_GOACTIVE/GM_HANDLEINPUT ====
	===== Region and RastPort Support =====

	If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):		If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):

Steven Solie: /* GM_GOACTIVE/GM_HANDLEINPUT */

2013-04-15T18:42:22Z

GM_GOACTIVE/GM_HANDLEINPUT

← Older revision		Revision as of 18:42, 15 April 2013
Line 134:		Line 134:
	{{Note\|text=As of Intuition V51 the mask method is not yet implemented.}}		{{Note\|text=As of Intuition V51 the mask method is not yet implemented.}}

			===== Region and RastPort Support =====
	==== GM_GOACTIVE/GM_HANDLEINPUT ====

	If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):		If a gadget returns GMR_GADGETHIT, Intuition will send it a GM_GOACTIVE message (defined in <intuition/gadgetclass.h>):
Line 160:		Line 160:
	For the GM_GOACTIVE method, the gpi_IEvent field points to the struct InputEvent that triggered the GM_GOACTIVE message. Unlike the GM_HANDLEINPUT message, GM_GOACTIVE's gpi_IEvent can be NULL. If the GM_GOACTIVE message was triggered by a function like intuition.library's ActivateGadget() and not by a real InputEvent (like the user clicking the gadget), the gpi_IEvent field will be NULL.		For the GM_GOACTIVE method, the gpi_IEvent field points to the struct InputEvent that triggered the GM_GOACTIVE message. Unlike the GM_HANDLEINPUT message, GM_GOACTIVE's gpi_IEvent can be NULL. If the GM_GOACTIVE message was triggered by a function like intuition.library's ActivateGadget() and not by a real InputEvent (like the user clicking the gadget), the gpi_IEvent field will be NULL.

	For gadgets that only want to become active as a direct result of a mouse click, this difference is important. For example, the prop gadget becomes active only when the user clicks on its knob. Because the only way the user can control the prop gadget is via the mouse, it does not make sense for anything but the mouse to activate the gadget. On the other hand, a string gadget doesn't care how it is activated because, as soon as ~~it‚Äôs~~ active, it gets user input from the keyboard rather than the mouse. Not all gadgets can become active. Some gadgets cannot become active because they have been temporarily disabled (their Gadget.Flags GFLG_DISABLED bit is set). Other gadgets will not become active because they don't need to process input. For example, a toggle gadget won't become active because it only needs to process one input event, the mouse click that toggles the gadget (which it gets from the GM_GOACTIVE message). If a toggle gadget gets a GM_GOACTIVE message and its gpi_IEvent field is not NULL, it will toggle its state and refuse to "go active".		For gadgets that only want to become active as a direct result of a mouse click, this difference is important. For example, the prop gadget becomes active only when the user clicks on its knob. Because the only way the user can control the prop gadget is via the mouse, it does not make sense for anything but the mouse to activate the gadget. On the other hand, a string gadget doesn't care how it is activated because, as soon as it's active, it gets user input from the keyboard rather than the mouse. Not all gadgets can become active. Some gadgets cannot become active because they have been temporarily disabled (their Gadget.Flags GFLG_DISABLED bit is set). Other gadgets will not become active because they don't need to process input. For example, a toggle gadget won't become active because it only needs to process one input event, the mouse click that toggles the gadget (which it gets from the GM_GOACTIVE message). If a toggle gadget gets a GM_GOACTIVE message and its gpi_IEvent field is not NULL, it will toggle its state and refuse to "go active".

	The GM_GOACTIVE method has to take care of any visual state changes to a gadget that a GM_GOACTIVE message might trigger. For example, the toggle gadget in the previous paragraph has to take care of toggling its visual state from selected imagery to unselected imagery. If the gadget goes through a state change when it becomes the active gadget, (like when a string gadget positions its cursor) GM_GOACTIVE has to take care of this.		The GM_GOACTIVE method has to take care of any visual state changes to a gadget that a GM_GOACTIVE message might trigger. For example, the toggle gadget in the previous paragraph has to take care of toggling its visual state from selected imagery to unselected imagery. If the gadget goes through a state change when it becomes the active gadget, (like when a string gadget positions its cursor) GM_GOACTIVE has to take care of this.

			===== Return Values =====

	The return values of both GM_GOACTIVE and GM_HANDLEINPUT tell Intuition whether or not the gadget wants to be active. A gadget's GM_GOACTIVE method returns GMR_MEACTIVE (defined in <intuition/gadgetclass.h>) if it wants to become the active gadget. A gadget's GM_HANDLEINPUT method returns GMR_MEACTIVE if it wants to remain the active gadget. If a gadget either does not want to become or remain the active gadget, it returns one of the "go inactive" return values:		The return values of both GM_GOACTIVE and GM_HANDLEINPUT tell Intuition whether or not the gadget wants to be active. A gadget's GM_GOACTIVE method returns GMR_MEACTIVE (defined in <intuition/gadgetclass.h>) if it wants to become the active gadget. A gadget's GM_HANDLEINPUT method returns GMR_MEACTIVE if it wants to remain the active gadget. If a gadget either does not want to become or remain the active gadget, it returns one of the "go inactive" return values:

Steven Solie: /* GM_EXTENT */

2013-04-15T18:40:47Z

GM_EXTENT

← Older revision		Revision as of 18:40, 15 April 2013
Line 101:		Line 101:

	==== GM_EXTENT ====		==== GM_EXTENT ====

			The GM_EXTENT method is used to ask the gadget what pixels (at least) it will fully redraw when its GM_RENDER method is invoked in the same context. By "fully redraw" we mean changing the pixel's color in a way that is totally unrelated to its previous value -- so this doesn't apply to alpha-blended pixels for example.

			Intuition uses that information for optimization purposes. During GUI refreshes, it will skip filling or erasing those pixels that the gadget would then completely re-render anyway. Supporting this method in your gadgets will help Intuition improve the smoothness of user interface refresh by preventing redundant graphic calls and minimizing "flicker" effects caused by background clearing especially during window resizes.

			===== Simple Support =====

			The easiest way to support GM_EXTENT is to make sure your gadget always fills every pixel within its dimensions and just return the relevant result value (GMR_FULLHBOX or GMR_FULLBBOX). In this case, you may safely ignore the actual message contents and the following text.

			If the above solution is not feasible (for instance because the gadget has an irregular or not fully connected shape) then you should check the gpe_Region and gpe_RPort message fields: if any of them is non-NULL you may decide to employ a more detailed way to tell the caller exactly what pixels your GM_RENDER method does fill.

			===== Region and RastPort Support =====

			If gpe_Region is non-NULL you can compose in it your gadget's shape by using graphics.library's XxxxRectRegion() functions. Remember to look at the gpe_Action field to determine what function to use. For example, if gpe_Action is GEXTENT_ADD you should use OrRectRegion(). Note you must NOT pre-clear or alter the initial region's contents in any way other than to compose your own gadget's shape. Once finished composing your gadget's shape in the region, return GMR_CLIPDONE to let the caller know you updated the region's contents.

			If gpe_RPort is non-NULL you can draw your gadget's shape into it just like you would do for a GM_RENDER message -- however, you're only allowed to use colors 0 or 1 because you're actually drawing into a single-bitplane mask. Again, check the gpe_Action field to find out whether you should actually set, clear or invert the pixels making up your gadget's shape in the mask. You are not allowed to alter any pixels other than those belonging to your gadget's shape nor to clear the mask's background before rendering. Once finished drawing your gadget's shape in the mask plane return GMR_MASKDONE to let the caller know you updated the mask's contents.

			If both gpe_Region and gpe_RPort are non-NULL you may simply choose the method which is most suited for your purposes. You don't have to support both for the same message. If you do, however, you can let the caller know by ORing together the appropriate return values. The region solution is best suited for gadgets made up of a few rectangular parts whereas the mask method is better in the case of more complex gadget shapes.

			===== Images =====

			If all or part of your gadget's rendering is performed by some BOOPSI image you could also try asking the image for its extent information by way of an IM_EXTENT or IM_EXTENTFRAME message (see [[BOOPSI_Images\|BOOPSI Images]]).

			If for whatever reasons your GM_EXTENT method finds itself unable to support any of the described solutions it should return GMR_INVALID. This particular return value will tell Intuition not to clip away the gadget's shape at all. While this is usually slower and more prone to flickering it will still produce correct graphic results. This is the same fallback applied for any gadgets not recognizing the GM_EXTENT method.

			===== Superclass Extent Handling =====

			Since it is very important that a gadget's GM_RENDER and GM_EXTENT methods remain synchronized the default behavior of a gadget class should be to only handle GM_EXTENT if it is the "true class" of the object the method is invoked on and just return GMR_INVALID otherwise. This is because a subclass might override the behavior of GM_RENDER in such a way that your class' GM_EXTENT results are no longer correct.

			If a gadget subclass needs and knows it's ok to let its superclass handle GM_EXTENT it must set the GPEF_ALLOWSUPER flag in gpe_Flags before calling IDoSuperMethodA() and clear it as soon as the call returns. If GPEF_ALLOWSUPER is set in gpe_Flags your gadget should accept and handle GM_EXTENT regardless of whether it is the true class or not.

			{{Note\|text=As of Intuition V51 the mask method is not yet implemented.}}

	==== GM_GOACTIVE/GM_HANDLEINPUT ====		==== GM_GOACTIVE/GM_HANDLEINPUT ====

Steven Solie: /* The BOOPSI Gadget Methods */

2013-04-15T18:29:18Z

The BOOPSI Gadget Methods

Show changes