ReAction - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:14:15Z

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

← Older revision		Revision as of 19:14, 26 January 2025
Line 121:		Line 121:
	An attribute is a particular property or feature of an object. While some classes implement attributes that are specific (and only relevant) to themselves, there are certain attributes that are common for a particular group of classes, eg. gadgets. In the AmigaOS implementation, an object attribute takes the form of a ''tag'', which is a name/value pair. As most classes support multiple attributes, complete ''tag lists'' can be used to describe an object:		An attribute is a particular property or feature of an object. While some classes implement attributes that are specific (and only relevant) to themselves, there are certain attributes that are common for a particular group of classes, eg. gadgets. In the AmigaOS implementation, an object attribute takes the form of a ''tag'', which is a name/value pair. As most classes support multiple attributes, complete ''tag lists'' can be used to describe an object:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	GA_Text, "Don’t ever dare to click on me!",		GA_Text, "Don’t ever dare to click on me!",
	GA_ReadOnly, TRUE,		GA_ReadOnly, TRUE,
Line 153:		Line 153:
	Classes are, in fact, standard Amiga libraries. The data structure describing a BOOPSI class is called ClassLibrary. As you can see from the C-language definition below, the structure contains the standard ''struct Library'' plus some additional fields. This makes it possible to treat classes as normal libraries and, at the same time, support BOOPSI-specific features:		Classes are, in fact, standard Amiga libraries. The data structure describing a BOOPSI class is called ClassLibrary. As you can see from the C-language definition below, the structure contains the standard ''struct Library'' plus some additional fields. This makes it possible to treat classes as normal libraries and, at the same time, support BOOPSI-specific features:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct ClassLibrary		struct ClassLibrary
	{		{
Line 168:		Line 168:
	The following code snippet opens and closes the ReAction Layout Gadget class:		The following code snippet opens and closes the ReAction Layout Gadget class:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct ClassLibrary LayoutBase; / the class library base */		struct ClassLibrary LayoutBase; / the class library base */
	Class LayoutClass; / the class pointer */		Class LayoutClass; / the class pointer */
Line 181:		Line 181:
	The number refers to the class version, 52 being a sensible minimum. This particular OpenClass() call returns the Layout Gadget class library base (LayoutBase) and stores the class pointer in the LayoutClass variable. The call, if successful, also sets the cl_Class field in the ClassLibrary data structure (see the definition above) so when it, later, comes to actually using the class pointer, you can either keep the LayoutClass value, or you can retrieve the pointer from the library base (ie. its data structure) like this:		The number refers to the class version, 52 being a sensible minimum. This particular OpenClass() call returns the Layout Gadget class library base (LayoutBase) and stores the class pointer in the LayoutClass variable. The call, if successful, also sets the cl_Class field in the ClassLibrary data structure (see the definition above) so when it, later, comes to actually using the class pointer, you can either keep the LayoutClass value, or you can retrieve the pointer from the library base (ie. its data structure) like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	LayoutClass = LayoutBase->cl_Class;		LayoutClass = LayoutBase->cl_Class;
	</syntaxhighlight>		</syntaxhighlight>
Line 203:		Line 203:
	The following code instantiates a Layout Gadget object and a Page Gadget object. Both methods are shown here: the layout is created from the class pointer whereas the page is instantiated from the public name (remember that the Page Gadget class code is part of the Layout Gadget binary, so there is no class pointer for the page). When the objects are no longer needed, you are expected to call DisposeObject() to clean up after yourself. The function invokes the OM_DISPOSE method and frees all resources associated with the particular object instance:		The following code instantiates a Layout Gadget object and a Page Gadget object. Both methods are shown here: the layout is created from the class pointer whereas the page is instantiated from the public name (remember that the Page Gadget class code is part of the Layout Gadget binary, so there is no class pointer for the page). When the objects are no longer needed, you are expected to call DisposeObject() to clean up after yourself. The function invokes the OM_DISPOSE method and frees all resources associated with the particular object instance:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	Object LayoutGadget; / object pointers */		Object LayoutGadget; / object pointers */
	Object *PageGadget;		Object *PageGadget;
Line 228:		Line 228:
	Objects with children objects attached to them are disposed of together with all their children, including their children’s children (should there be any). In other words, only the ''parent object'' is disposed of. This feature is illustrated by the following example, in which the page gadget receives a child object – a layout gadget; this entire parent-child structure is subsequently attached to another layout as its child object. As you can see, only one DisposeObject() call is necessary:		Objects with children objects attached to them are disposed of together with all their children, including their children’s children (should there be any). In other words, only the ''parent object'' is disposed of. This feature is illustrated by the following example, in which the page gadget receives a child object – a layout gadget; this entire parent-child structure is subsequently attached to another layout as its child object. As you can see, only one DisposeObject() call is necessary:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	Object LayoutGadget_1; / object pointers */		Object LayoutGadget_1; / object pointers */
	Object *LayoutGadget_2;		Object *LayoutGadget_2;

Steven Solie at 21:03, 13 May 2013

2013-05-13T21:03:07Z

← Older revision		Revision as of 21:03, 13 May 2013
Line 126:		Line 126:
	BUTTON_Justification, BCJ_LEFT,		BUTTON_Justification, BCJ_LEFT,
	BUTTON_SoftStyle, FSF_ITALIC,		BUTTON_SoftStyle, FSF_ITALIC,
			TAG_END
	TAG_DONE
	</syntaxhighlight>		</syntaxhighlight>

	The tag list above describes a hypothetical Button Gadget object. The first two tags are applicable to gadget classes in general (“GA” standing for “Gadget Attribute”). They say that the gadget should display the text “Don’t ever dare to click on me!” and that it should be rendered as a non-selectable (read-only) GUI element. The other two tags are specific to the ReAction Button Gadget. They say, respectively, that the text in the gadget should be left-aligned and rendered in italics. ~~TAG_DONE~~ indicates the end of the tag list.		The tag list above describes a hypothetical Button Gadget object. The first two tags are applicable to gadget classes in general (“GA” standing for “Gadget Attribute”). They say that the gadget should display the text “Don’t ever dare to click on me!” and that it should be rendered as a non-selectable (read-only) GUI element. The other two tags are specific to the ReAction Button Gadget. They say, respectively, that the text in the gadget should be left-aligned and rendered in italics. TAG_END indicates the end of the tag list.

	==== Methods ====		==== Methods ====
Line 211:		Line 211:
	LayoutGadget = IIntuition->NewObject(LayoutClass, NULL,		LayoutGadget = IIntuition->NewObject(LayoutClass, NULL,
	LAYOUT_Orientation, LAYOUT_ORIENT_VERT,		LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
	~~TAG_DONE~~);		TAG_END);

	/* Instantiate the page gadget using the public class name. */		/* Instantiate the page gadget using the public class name. */
	PageGadget = IIntuition->NewObject(NULL, "page.gadget",		PageGadget = IIntuition->NewObject(NULL, "page.gadget",
	~~TAG_DONE~~);		TAG_END);

	/* Do something and, ultimately, dispose of both objects. */		/* Do something and, ultimately, dispose of both objects. */
Line 237:		Line 237:
	PAGE_Add, LayoutGadget_1 = IIntuition->NewObject(LayoutClass, NULL,		PAGE_Add, LayoutGadget_1 = IIntuition->NewObject(LayoutClass, NULL,
	LAYOUT_Orientation, LAYOUT_ORIENT_VERT,		LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
	~~TAG_DONE~~),		TAG_END),
	~~TAG_DONE~~);		TAG_END);

	/* Now instantiate another layout gadget and add the page structure		/* Now instantiate another layout gadget and add the page structure
Line 245:		Line 245:
	LAYOUT_Orientation, LAYOUT_ORIENT_VERT,		LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
	LAYOUT_AddChild, PageGadget,		LAYOUT_AddChild, PageGadget,
	~~TAG_DONE~~);		TAG_END);

	/* Do something and, ultimately, dispose of the parent object.		/* Do something and, ultimately, dispose of the parent object.

Daniel Jedlicka: /* Methods */

2012-12-12T06:50:30Z

Methods

← Older revision		Revision as of 06:50, 12 December 2012
Line 147:		Line 147:
	\|}		\|}

	The methods in the table above are defined at the highest (“rootclass”) level, ~~which~~ ~~means~~ ~~that~~ they are ~~applicable~~ to ~~all~~ ~~classes~~.		The methods in the table above are applicable to all classes because they are defined at the highest (“rootclass”) level in the BOOPSI class hierarchy. This is why they are also referred to as ''rootclass methods''.

	== Class Opening and Closing ==		== Class Opening and Closing ==

Daniel Jedlicka at 08:38, 10 December 2012

2012-12-10T08:38:56Z

← Older revision		Revision as of 08:38, 10 December 2012
Line 28:		Line 28:

	{\| class="wikitable"		{\| class="wikitable"
	! class \|\| public name (ClassID) \|\| function		! class \|\| public name (ClassID) \|\| function / GUI element type
	\|-		\|-
	\| ARexx \|\| arexx.class \|\|		\| ARexx \|\| arexx.class \|\| Simplifies the creation and usage of ARexx ports in your programs.
	\|-		\|-
	\| PopUpMenu \|\| popupmenu.class \|\|		\| PopUpMenu \|\| popupmenu.class \|\| Provides context (local) menus.
	\|-		\|-
			\| Requester \|\| requester.class \|\| Greatly extends the original concept of [[Intuition_Requesters_and_Alerts\|Intuition requesters]], providing several requester types with many features.
	\| Requester \|\| requester.class \|\|
	\|-		\|-
			\| Window \|\| window.class \|\| A powerful class to create windows with advanced features such as iconification, the AppWindow facility, or an automatic layouting system.
	\| Window \|\| window.class \|\|
	\|}		\|}

Line 42:		Line 42:

	{\| class="wikitable" style="text-align: left"		{\| class="wikitable" style="text-align: left"
	! class \|\| public name (ClassID) \|\| function		! class \|\| public name (ClassID) \|\| function / GUI element type
	\|-		\|-
	\| Button \|\| button.gadget \|\|		\| Button \|\| button.gadget \|\|
Line 94:		Line 94:

	{\| class="wikitable" style="text-align: left"		{\| class="wikitable" style="text-align: left"
	! class \|\| public name (ClassID) \|\| function		! class \|\| public name (ClassID) \|\| function / GUI element type
	\|-		\|-
	\| Bevel \|\| bevel.image \|\|		\| Bevel \|\| bevel.image \|\|
Line 147:		Line 147:
	\|}		\|}

	The methods in the table above are defined on the highest (“rootclass”) level, which means that they are applicable to all classes.		The methods in the table above are defined at the highest (“rootclass”) level, which means that they are applicable to all classes.

	== Class Opening and Closing ==		== Class Opening and Closing ==

Daniel Jedlicka at 06:39, 10 December 2012

2012-12-10T06:39:15Z

← Older revision		Revision as of 06:39, 10 December 2012
Line 12:		Line 12:

	; object-oriented		; object-oriented
	: All GUI elements created via the toolkit – windows, gadgets, images, even ARexx ports – are manipulated as ''objects'' of a certain ''class''. The class determines the look, function and general properties of the object; objects of the same class serve the same purpose and share the same properties. In a program, a GUI element (object) is an ''instance'' of a class, therefore object creation is often referred to as [[#Object Creation (Instantiation) and Disposal\|instantiation]].		: All GUI elements created via the toolkit – windows, gadgets, images, even ARexx ports – are manipulated as ''objects'' of a certain [[#Class Overview\|class]]. The class determines the look, function and general properties of the object; objects of the same class serve the same purpose and share the same properties. In a program, a GUI element (object) is an ''instance'' of a class, therefore object creation is often referred to as [[#Object Creation (Instantiation) and Disposal\|instantiation]].

	; modular and extensible		; modular and extensible
Line 21:		Line 21:

	; BOOPSI-compatible		; BOOPSI-compatible
	: Program GUIs created through ReAction can include other AmigaOS components based on BOOPSI, such as [[Datatypes_Library\|datatypes]] or Intuition’s internal BOOPSI classes.		: Program GUIs created through ReAction can include other AmigaOS components based on BOOPSI, such as [[Datatypes_Library\|datatypes]] or Intuition’s internal BOOPSI classes. On the other hand, ReAction is '''not''' compatible (= cannot exchange classes or combine GUI elements) with the MUI toolkit because the latter uses its own system of class management. Neither is ReAction compatible with the [[GadTools_Library\|GadTools]] toolkit because it is not based on BOOPSI.

	=== Class Overview ===		=== Class Overview ===

Daniel Jedlicka: Reworked the introductory section, added the Class Overview

2012-12-09T10:39:55Z

Reworked the introductory section, added the Class Overview

Show changes

Daniel Jedlicka: /* Object Creation (Instantiation) and Disposal */

2012-12-08T09:34:15Z

Object Creation (Instantiation) and Disposal

← Older revision		Revision as of 09:34, 8 December 2012
Line 101:		Line 101:
	In order to create a ReAction GUI element you have to ''instantiate its object'' from a particular class. Instantiation is performed through the Intuition function NewObject() which, if successful, returns an ''object pointer''. Internally, the function invokes the OM_NEW method, which every BOOPSI class must implement by specification and which creates an ''object instance''.		In order to create a ReAction GUI element you have to ''instantiate its object'' from a particular class. Instantiation is performed through the Intuition function NewObject() which, if successful, returns an ''object pointer''. Internally, the function invokes the OM_NEW method, which every BOOPSI class must implement by specification and which creates an ''object instance''.

			NewObject() takes three arguments as input:
	To tell NewObject() which particular class is to be instantiated from, you use either

	* ~~the~~ ''class pointer'', obtained from OpenClass() ~~– see above~~; or		* a ''class pointer'', as obtained from OpenClass();
	* ~~the~~ ''class public name'', if ~~the~~ ~~class~~ is ~~public.~~ ~~All ReAction classes are public~~ ~~classes.~~		* a ''class public name'' (also called ClassID), which is a text string;
			* a tag list describing object properties ([[#Attributes and Methods\|attributes]]).

	Using the class pointer is noticeably faster on lower-end systems. Instantiation via public names carries a certain overhead associated with walking through the system class list and processing name strings. For example, if twenty objects of the same class were to be instantiated using the class name, the NewObject() routine would go through the system list no less than twenty times, despite the class being identical! Compared to this, the class pointer is only obtained once – during OpenClass() – and points directly to the particular class without any further lookup. In other words, if you want your GUI to get created as fast as possible, use the class pointer in the NewObject() call whenever you can.		The first two arguments are mutually exclusive: one of them will always be NULL. You can either instantiate the object from the class pointer, or from the public name (provided that the class is public – all ReAction classes are public classes). Using the class pointer is noticeably faster on lower-end systems. Instantiation via public names carries a certain overhead associated with walking through the system class list and processing name strings. For example, if twenty objects of the same class were to be instantiated using the class name, the NewObject() routine would go through the system list no less than twenty times, despite the class being identical! Compared to this, the class pointer is only obtained once – during OpenClass() – and points directly to the particular class without any further lookup. In other words, if you want your GUI to get created as fast as possible, use the class pointer in the NewObject() call whenever you can.

	Classes that are part of another component (such as the “internal” BOOPSI classes in Intuition, or the ReAction Page Gadget class) are inherently public and can only be instantiated via their public name. As they are never opened directly (see [[#Class Opening and Closing\|Class Opening and Closing]] above), you don’t have access to their class pointer and must, therefore, use the name instead – there is no other way.		Classes that are part of another component (such as the “internal” BOOPSI classes in Intuition, or the ReAction Page Gadget class) are inherently public and can only be instantiated via their public name. As they are never opened directly (see [[#Class Opening and Closing\|Class Opening and Closing]] above), you don’t have access to their class pointer and must, therefore, use the name instead – there is no other way.

Daniel Jedlicka at 16:29, 7 December 2012

2012-12-07T16:29:17Z

@@ Line 26: / Line 26: @@
 BOOPSI objects are described by ''attributes'' and manipulated through ''methods''.
 An attribute is a particular property or feature of an object. While some classes implement attributes that are specific (and only relevant) to themselves, there are certain attributes that are common for a particular group of classes, eg. gadgets. In the AmigaOS implementation, an object attribute takes the form of a ''tag'', which is a name/value pair. As most classes support multiple attributes, complete ''tag lists'' can be used to describe an object:
@@ Line 38: / Line 40: @@
 The tag list above describes a hypothetical Button Gadget object. The first two tags are applicable to gadget classes in general (“GA” standing for “Gadget Attribute”). They say that the gadget should display the text “Don’t ever dare to click on me!” and that it should be rendered as a non-selectable (read-only) GUI element. The other two tags are specific to the ReAction Button Gadget. They say, respectively, that the text in the gadget should be left-aligned and rendered in italics. TAG_DONE indicates the end of the tag list.
 == Class Opening and Closing ==
@@ Line 79: / Line 99: @@
 == Object Creation (Instantiation) and Disposal ==
-In order to create a ReAction GUI element you have to ''instantiate its object'' from a particular class. Instantiation is performed through the Intuition function NewObject() which, if successful, returns an ''object pointer''. Internally, the function invokes a method called OM_NEW, which every BOOPSI class must implement and which creates an ''object instance''.
+In order to create a ReAction GUI element you have to ''instantiate its object'' from a particular class. Instantiation is performed through the Intuition function NewObject() which, if successful, returns an ''object pointer''. Internally, the function invokes the OM_NEW method, which every BOOPSI class must implement by specification and which creates an ''object instance''.
 To tell NewObject() which particular class is to be instantiated from, you use either

Daniel Jedlicka: Created the Attributes and Methods section

2012-12-07T15:50:30Z

Created the Attributes and Methods section

@@ Line 22: / Line 22: @@
 ; BOOPSI-compatible
 : Program GUIs created through ReAction can include other AmigaOS components based on BOOPSI, such as [[Datatypes_Library|datatypes]] or Intuition’s internal BOOPSI classes.
 == Class Opening and Closing ==

Daniel Jedlicka at 13:07, 7 December 2012

2012-12-07T13:07:02Z

← Older revision		Revision as of 13:07, 7 December 2012
Line 18:		Line 18:

	; layout-based		; layout-based
	: GUI elements provided by the toolkit are meant to be placed in a ''layout'': a structure determining how objects are positioned, sized and grouped in the GUI. Objects governed by a layout are not programmed for specific positions or sizes; instead, these parameters are automatically decided by the layout according to the properties of the individual objects.		: GUI elements provided by the toolkit are meant to be placed in a ''layout'': a hierarchical structure determining how objects are positioned, sized and grouped in the GUI. Objects governed by a layout are not programmed for specific positions or sizes; instead, these parameters are automatically decided by the layout according to the properties of the individual objects.

	; BOOPSI-compatible		; BOOPSI-compatible