BOOPSI 101 - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:20:41Z

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

← Older revision		Revision as of 19:20, 26 January 2025
Line 5:		Line 5:
	The Intuition functions '''NewObject()''' / '''NewObjectA()''' create a BOOPSI object using either "stack" of tags or predefined a tag list and returns a pointer to a new BOOPSI object:		The Intuition functions '''NewObject()''' / '''NewObjectA()''' create a BOOPSI object using either "stack" of tags or predefined a tag list and returns a pointer to a new BOOPSI object:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	Object object = NewObject(Class cl, ClassID classID, Tag tag1, ...);		Object object = NewObject(Class cl, ClassID classID, Tag tag1, ...);
	Object object = NewObjectA(Class cl, ClassID classID, const struct TagItem *tags);		Object object = NewObjectA(Class cl, ClassID classID, const struct TagItem *tags);
Line 18:		Line 18:
	Regardless of whether the tag list is defined elsewhere or within this function call, some list of "tags" is next proivided to define the characteristics of the new object. Each "tag" consists of a pair of values - each with specifically named "attribute" and it's proposed "value". Some general examples of such tags might be:		Regardless of whether the tag list is defined elsewhere or within this function call, some list of "tags" is next proivided to define the characteristics of the new object. Each "tag" consists of a pair of values - each with specifically named "attribute" and it's proposed "value". Some general examples of such tags might be:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	GA_Left, 100,		GA_Left, 100,
	REQ_TitleText, "Testing...",		REQ_TitleText, "Testing...",
Line 26:		Line 26:
	In the case of our requester example, we can use the '''NewObject{}''' function along with a "stack" of "tags" containing basic parameters to create a new requester object like this:		In the case of our requester example, we can use the '''NewObject{}''' function along with a "stack" of "tags" containing basic parameters to create a new requester object like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	reqobj = IIntuition->NewObject(NULL,"requester.class",		reqobj = IIntuition->NewObject(NULL,"requester.class",
	REQ_Type, REQTYPE_INFO,		REQ_Type, REQTYPE_INFO,
Line 42:		Line 42:
	To communicate with BOOPSI objects we send "BOOPSI Messages". Unlike traditional AmigaOS "Messages" used by the Exec, ARexx and for interprocess communications, BOOPSI messages are different and frequently rely on tag lists for their content. To "send" a BOOPSI Message to an existing object, we use the '''IDoMethod''' function (or its tag list based variant):		To communicate with BOOPSI objects we send "BOOPSI Messages". Unlike traditional AmigaOS "Messages" used by the Exec, ARexx and for interprocess communications, BOOPSI messages are different and frequently rely on tag lists for their content. To "send" a BOOPSI Message to an existing object, we use the '''IDoMethod''' function (or its tag list based variant):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	ULONG IDoMethod(Object *myobject, ULONG methodID, ...);		ULONG IDoMethod(Object *myobject, ULONG methodID, ...);
	ULONG IDoMethodA(Object *myobject, Msg boopsimessage);		ULONG IDoMethodA(Object *myobject, Msg boopsimessage);
Line 53:		Line 53:
	For a simple example, we can ask the BOOPSI requester object '''reqobj''' (created above) to show itself by sending this message:		For a simple example, we can ask the BOOPSI requester object '''reqobj''' (created above) to show itself by sending this message:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );		result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
	</syntaxhighlight>		</syntaxhighlight>
Line 63:		Line 63:
	With the '''IDoMethodA()''' variant, all of the above arguments have to be combined into a complete BOOPSI Message structure, '''boopsimessage'''. Again the layout of depends on the class and method. Every method's message starts off with a '''Msg''' (from <intuition/classusr.h>) and is followed by the class specific tags:		With the '''IDoMethodA()''' variant, all of the above arguments have to be combined into a complete BOOPSI Message structure, '''boopsimessage'''. Again the layout of depends on the class and method. Every method's message starts off with a '''Msg''' (from <intuition/classusr.h>) and is followed by the class specific tags:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	typedef struct {		typedef struct {
	ULONG MethodID; /* Method-specific data may follow this field */		ULONG MethodID; /* Method-specific data may follow this field */
Line 75:		Line 75:
	Every BOOPSI object is defined by a number of attributes. In the above example we defined our requester when we created the object with '''NewObject()'''. But an object's attributes are not necessarily static. An application can use the '''SetAttrs()''' function to change or set other attributes on an object:		Every BOOPSI object is defined by a number of attributes. In the above example we defined our requester when we created the object with '''NewObject()'''. But an object's attributes are not necessarily static. An application can use the '''SetAttrs()''' function to change or set other attributes on an object:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 IIntuition->SetAttrs( Object * object, Tag tag1, ... );		uint32 IIntuition->SetAttrs( Object * object, Tag tag1, ... );
	uint32 IIntuition->SetAttrsA( Object * object, const struct TagItem * tagList );		uint32 IIntuition->SetAttrsA( Object * object, const struct TagItem * tagList );
Line 82:		Line 82:
	In each case we have to provide a pointer to our object and then tag pairs with the Attribute identifiers and the replacement values. As an example, we can use the '''SetAttrs()''' function to reset the type and contents of our requester object from above and reuse the object to open a second, different requester for the user.		In each case we have to provide a pointer to our object and then tag pairs with the Attribute identifiers and the replacement values. As an example, we can use the '''SetAttrs()''' function to reset the type and contents of our requester object from above and reuse the object to open a second, different requester for the user.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	strcpy(buffer,"default string");		strcpy(buffer,"default string");
	result = IIntuition->SetAttrs( reqobj,		result = IIntuition->SetAttrs( reqobj,
Line 103:		Line 103:
	Just as we can set attributes of an existing BOOPSI object, we also have the ability to get the current settings from a object's attributes. Inquiring about a specific setting is done using the BOOPSI function '''GetAttr()''':		Just as we can set attributes of an existing BOOPSI object, we also have the ability to get the current settings from a object's attributes. Inquiring about a specific setting is done using the BOOPSI function '''GetAttr()''':

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 attr = GetAttr(uint32 attrID, Object object, uint32 storage);		uint32 attr = GetAttr(uint32 attrID, Object object, uint32 storage);
	</syntaxhighlight>		</syntaxhighlight>
Line 111:		Line 111:
	In the case of our requester example, there are only a few attributes to which values can be obtained. The following example will obtain the result code from the last use of the object:		In the case of our requester example, there are only a few attributes to which values can be obtained. The following example will obtain the result code from the last use of the object:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 lastresult;		uint32 lastresult;
	result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);		result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);
Line 118:		Line 118:
	Another example of the '''GetAttr''' function would be to retrieve the value a user provided in an Interger type requester. This information could be restrieved like this:		Another example of the '''GetAttr''' function would be to retrieve the value a user provided in an Interger type requester. This information could be restrieved like this:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	int32 userInt;		int32 userInt;
	result = IIntuition->GetAttr(REQI_Number, reqobj,&userInt);		result = IIntuition->GetAttr(REQI_Number, reqobj,&userInt);
Line 125:		Line 125:
	While the simple requester class is not a great example for getting a lot of attributes, BOOPSI provides a second pair of functions that uses taglists for obtaining multiple attributes in one call: '''GetAttrs()''' and '''GetAttrsA''':		While the simple requester class is not a great example for getting a lot of attributes, BOOPSI provides a second pair of functions that uses taglists for obtaining multiple attributes in one call: '''GetAttrs()''' and '''GetAttrsA''':

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	uint32 retval = GetAttrs(Object *object, Tag tag1, ...);		uint32 retval = GetAttrs(Object *object, Tag tag1, ...);
	uint32 retval = GetAttrsA(Object object, struct TagItem attrs);		uint32 retval = GetAttrsA(Object object, struct TagItem attrs);
Line 140:		Line 140:
	When an application is finally done with an object, it has to dispose of the object. To dispose of an object, use the Intuition function '''DisposeObject()''':		When an application is finally done with an object, it has to dispose of the object. To dispose of an object, use the Intuition function '''DisposeObject()''':

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void DisposeObject(Object *obj);		void DisposeObject(Object *obj);
	</syntaxhighlight>		</syntaxhighlight>
Line 148:		Line 148:
	In the case of our requester example, we would simply call:		In the case of our requester example, we would simply call:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IIntuition->DisposeObject(reqobj);		IIntuition->DisposeObject(reqobj);
	</syntaxhighlight>		</syntaxhighlight>
Line 182:		Line 182:
	Below is the complete example program that includes the above excerpts. This program will create a requester object, display a requester with buttons and one with a string gadget and print the results in the shell.		Below is the complete example program that includes the above excerpts. This program will create a requester object, display a requester with buttons and one with a string gadget and print the results in the shell.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/* Requesters Example		/* Requesters Example
	gcc -o Requesters Requesters.c -lauto		gcc -o Requesters Requesters.c -lauto

Daniel Jedlicka: Minor corrections (typos, dead link).

2018-06-02T20:02:37Z

Minor corrections (typos, dead link).

← Older revision		Revision as of 20:02, 2 June 2018
Line 10:		Line 10:
	</syntaxhighlight>		</syntaxhighlight>

	As mentioned previously (see [[BOOPSI#~~OOPSI_and_Tags~~\|BOOPSI and Tags]]), the '''NewObject()''' function has a variant that uses predefined tag lists ('''NewObjectA()'''), but here we will continue with the more commonly used stack based variant.		As mentioned previously (see [[BOOPSI#BOOPSI_and_Tags\|BOOPSI and Tags]]), the '''NewObject()''' function has a variant that uses predefined tag lists ('''NewObjectA()'''), but here we will continue with the more commonly used stack-based variant.

	In general, BOOPSI objects are "black boxes". This means the inner workings of BOOPSI objects are not visible to the application programmer, so the programmer does not know what goes on inside it. This really means the inner workings of these objects are none of your business. Unless otherwise documented, only use an object pointer as a handle to the object.		In general, BOOPSI objects are "black boxes". This means the inner workings of BOOPSI objects are not visible to the application programmer, so the programmer does not know what goes on inside it. This really means the inner workings of these objects are none of your business. Unless otherwise documented, only use an object pointer as a handle to the object.

	To create an object, '''NewObject()''' first needs to know whether we are creating an object from a public or private class. Typically any objects created from system gadgets are all public classes. In such cases, the '''cl''' argument (a pointer) would be set to NULL and '''classID''' argument set to the ~~text~~ name of the class (like "requesterclass" or "string.gadget"). If one wanted to create an object of a private class, the '''cl''' argument would be a pointer to that class and the '''classID''' would be ignored.		To create an object, '''NewObject()''' first needs to know whether we are creating an object from a public or private class. Typically any objects created from system gadgets are all public classes. In such cases, the '''cl''' argument (a class pointer) would be set to NULL and '''classID''' argument set to the public name of the class (a text string like "requesterclass" or "string.gadget"). If one wanted to create an object of a private class, the '''cl''' argument would be a pointer to that class and the '''classID''' would be ignored.

	Regardless of whether the tag list is defined elsewhere or within this function call, some list of "tags" is next proivided to define the characteristics of the new object. Each "tag" consists of a pair of values - each with specifically named "attribute" and it's proposed "value". Some general examples of such tags might be:		Regardless of whether the tag list is defined elsewhere or within this function call, some list of "tags" is next proivided to define the characteristics of the new object. Each "tag" consists of a pair of values - each with specifically named "attribute" and it's proposed "value". Some general examples of such tags might be:
Line 34:		Line 34:
	</syntaxhighlight>		</syntaxhighlight>

	If successful, the variable '''reqobj''' will contain a pointer to new a BOOPSI requester object. If unsuccessful, '''reqobj''' will be NULL. This is a place for a developer to apply some error trapping when an object couldn't be created - maybe our application ran out of memory? ~~maybe~~ some of the parameters (tags) were invalid?		If successful, the variable '''reqobj''' will contain a pointer to new a BOOPSI requester object. If unsuccessful, '''reqobj''' will be NULL. This is a place for a developer to apply some error trapping when an object couldn't be created - maybe our application ran out of memory? Maybe some of the parameters (tags) were invalid?

	Once the requester object has been created, we still won't see anything yet. Our new object is waiting in the wings for a BOOPSI message to show itself. This leads us to the next sections where we interact with the object we created.		Once the requester object has been created, we still won't see anything yet. Our new object is waiting in the wings for a BOOPSI message to show itself. This leads us to the next sections where we interact with the object we created.

Daniel Jedlicka: Fixed the size of chapter headings.

2018-06-02T19:45:39Z

Fixed the size of chapter headings.

Paul Sadlik: /* Getting an Object's Attributes */

2013-08-04T17:36:04Z

Getting an Object's Attributes

← Older revision		Revision as of 17:36, 4 August 2013
Line 115:		Line 115:
	uint32 lastresult;		uint32 lastresult;
	result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);		result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);
			</syntaxhighlight>

			Another example of the '''GetAttr''' function would be to retrieve the value a user provided in an Interger type requester. This information could be restrieved like this:

			<syntaxhighlight>
			int32 userInt;
			result = IIntuition->GetAttr(REQI_Number, reqobj,&userInt);
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie at 18:22, 19 June 2013

2013-06-19T18:22:26Z

← Older revision		Revision as of 18:22, 19 June 2013
Line 90:		Line 90:
	REQS_Buffer, buffer,		REQS_Buffer, buffer,
	REQS_MaxChars, sizeof(buffer) - 1,		REQS_MaxChars, sizeof(buffer) - 1,
	~~TAG_DONE~~);		TAG_END);
	result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );		result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
	</syntaxhighlight>		</syntaxhighlight>
Line 234:		Line 234:
	REQ_TitleText, "Requesters Example",		REQ_TitleText, "Requesters Example",
	REQ_BodyText, buffer,		REQ_BodyText, buffer,
	~~TAG_DONE~~);		TAG_END);

	// Was the requester object created?		// Was the requester object created?
Line 258:		Line 258:
	REQS_Buffer, buffer,		REQS_Buffer, buffer,
	REQS_MaxChars, sizeof(buffer) - 1,		REQS_MaxChars, sizeof(buffer) - 1,
	~~TAG_DONE~~);		TAG_END);

	/* tell object to show itself again		/* tell object to show itself again

Paul Sadlik at 20:48, 27 May 2013

2013-05-27T20:48:58Z

← Older revision		Revision as of 20:48, 27 May 2013
Line 1:		Line 1:

	In this section we will explore a simple example of creating, interacting with and disposing a simple BOOPSI object - a requester window. With these simple objects you can see the basic operations that are common to almost all BOOPSI objects. When using BOOPSI gadget objects there may be some changes in syntax (f.e., using '''SetGadgetAttrs() instead of '''SetAttrs()'''), but the concepts remain the same.		In this section we will explore a simple example of creating, interacting with and disposing a simple BOOPSI object - a requester window. With these simple objects you can see the basic operations that are common to almost all BOOPSI objects. When using BOOPSI gadget objects there may be some changes in syntax (f.e., using '''SetGadgetAttrs()''' instead of '''SetAttrs()'''), but the concepts remain the same.

	==== Creating an Object ====		==== Creating an Object ====

Paul Sadlik at 20:45, 27 May 2013

2013-05-27T20:45:11Z

← Older revision		Revision as of 20:45, 27 May 2013
Line 171:		Line 171:

	Of course, in the case of different classes and objects, the method would change with how the '''IDoMethod''' function was called on those objects.		Of course, in the case of different classes and objects, the method would change with how the '''IDoMethod''' function was called on those objects.

			==== Example Program ====

			Below is the complete example program that includes the above excerpts. This program will create a requester object, display a requester with buttons and one with a string gadget and print the results in the shell.

			<syntaxhighlight>
			/* Requesters Example
			gcc -o Requesters Requesters.c -lauto
			quit
			*/

			/*
			*
			************************************************************
			**
			** Created by: CodeBench 0.31 (20.5.2013)
			**
			** Project: OS4ex-Requesters
			**
			** A simple requester.class example used to demonstrate functionality.
			**
			** File: Requesters
			**
			** Date: 20-04-2013 20:43:23
			**
			** Version: 02
			**
			************************************************************
			*
			*/

			/* includes
			*/
			#include <exec/exec.h>
			#include <dos/dos.h>
			#include <intuition/intuition.h>
			#include <classes/requester.h>

			#include <proto/intuition.h>
			#include <proto/exec.h>
			#include <proto/dos.h>
			#include <proto/requester.h>

			#include <string.h>

			/* declarations
			*/
			Object *reqobj;
			struct orRequest reqmsg;
			char buffer[100];
			uint32 result = 0;

			int main()
			{

			/* create a new requester object
			*/
			strcpy(buffer,"Welcome to your\nfirst BOOPSI requester");

			reqobj = IIntuition->NewObject(NULL,"requester.class",
			REQ_Type, REQTYPE_INFO,
			REQ_TitleText, "Requesters Example",
			REQ_BodyText, buffer,
			TAG_DONE);

			// Was the requester object created?
			if (reqobj)
			{
			IDOS->Printf(" Requester object created\n");
			/* tell the object to show itself
			*/
			result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
			// How did things go?
			if (result)
			IDOS->Printf(" Req #1 - result code = %ld\n",result);
			else
			IDOS->Printf(" Req #1 - result = 0\n");

			/* reset object characteristics
			*/

			strcpy(buffer,"default string");
			result = IIntuition->SetAttrs( reqobj,
			REQ_Type, REQTYPE_STRING,
			REQ_BodyText, "please enter some text",
			REQS_Buffer, buffer,
			REQS_MaxChars, sizeof(buffer) - 1,
			TAG_DONE);

			/* tell object to show itself again
			*/
			result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
			// Did we get a good response?
			if (result>0)
			{
			IDOS->Printf(" Req #2 - result code = %ld\n",result);
			IDOS->Printf(" Req #2 - result text = %s\n",buffer);
			}
			else
			IDOS->Printf(" Req #2 - result = 0\n");

			/* Lets check some object attributes
			*/
			uint32 lastresult;

			result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);
			// Did we get some value?
			if (result>0)
			IDOS->Printf(" Last result code = %ld\n",lastresult);
			else
			IDOS->Printf(" This result = 0\n");

			/* Dispose of our requester object
			*/
			IIntuition->DisposeObject(reqobj);
			}
			else
			IDOS->Printf(" ERROR: Failed to create Requester object\n");

			return RETURN_OK;
			}
			</syntaxhighlight>

Paul Sadlik: /* What About the BOOPSI Messages and Methods? */

2013-05-27T20:16:41Z

What About the BOOPSI Messages and Methods?

← Older revision		Revision as of 20:16, 27 May 2013
Line 150:		Line 150:
	==== What About the BOOPSI Messages and Methods? ====		==== What About the BOOPSI Messages and Methods? ====

			In the above sections of this page, the functions used reflect BOOPSI messages and the underlying basic "methods" performed by a BOOPSI object. In the [[BOOPSI#OOP_Overview\|"OOP Overview"]] section we see how these saw how these common methods are practically universal to all BOOPSI classes. The above functions simply provide a wrapper for those common methods like this:

	[[BOOPSI#OOP_Overview\|"OOP Overview"]]

	According to the "OOP Overview" section, for an object to perform a method, something has to pass it a BOOPSI message. The previous section discussed using Intuition functions to ask an object to do things like set and get attributes. The functions in the previous section seem to completely ignore all that material about methods and messages. What happened to the methods and messages?

	Nothing; these functions don't ignore the OOP constructs, they just shield the programmer from them. Each of these functions corresponds to a BOOPSI method:

	{\| class="wikitable"		{\| class="wikitable"
	\| NewObject() \|\| OM_NEW		\| NewObject() \|\| OM_NEW
⚫	\|-
⚫	\| DisposeObject() \|\| OM_DISPOSE
	\|-		\|-
	\| SetAttrs()/SetGadgetAttrs() \|\| OM_SET		\| SetAttrs()/SetGadgetAttrs() \|\| OM_SET
Line 166:		Line 159:
	\| GetAttr() \|\| OM_GET		\| GetAttr() \|\| OM_GET
	\|-		\|-
		⚫	\| DisposeObject() \|\| OM_DISPOSE
	\| RefreshSetGadgetAttrs() \|\| OM_SET, GM_RENDER
	\|}		\|}

	These methods are defined on the rootclass level, so all BOOPSI classes inherit them. The Intuition functions that correspond to these methods take care of constructing and sending a BOOPSI message with the appropriate method ID and parameters.		These methods are defined on the rootclass level, so all BOOPSI classes inherit them. The Intuition functions that correspond to these methods take care of constructing and sending a BOOPSI message with the appropriate method ID and parameters.

			One last function had a more direct relationship to operation and methods of BOOPSI objects - in this case, causing our requester object to present itself :

			{\| class="wikitable"
			\| IDoMethod() \|\| RM_OPENREQ
		⚫	\|}

			Of course, in the case of different classes and objects, the method would change with how the '''IDoMethod''' function was called on those objects.

Paul Sadlik at 19:54, 27 May 2013

2013-05-27T19:54:37Z

← Older revision		Revision as of 19:54, 27 May 2013
Line 149:		Line 149:

	==== What About the BOOPSI Messages and Methods? ====		==== What About the BOOPSI Messages and Methods? ====


			[[BOOPSI#OOP_Overview\|"OOP Overview"]]

	According to the "OOP Overview" section, for an object to perform a method, something has to pass it a BOOPSI message. The previous section discussed using Intuition functions to ask an object to do things like set and get attributes. The functions in the previous section seem to completely ignore all that material about methods and messages. What happened to the methods and messages?		According to the "OOP Overview" section, for an object to perform a method, something has to pass it a BOOPSI message. The previous section discussed using Intuition functions to ask an object to do things like set and get attributes. The functions in the previous section seem to completely ignore all that material about methods and messages. What happened to the methods and messages?

Paul Sadlik: /* Disposing of an Object */

2013-05-27T19:43:05Z

Disposing of an Object

← Older revision		Revision as of 19:43, 27 May 2013
Line 139:		Line 139:

	As usual, we use a pointer to our object to indicate the object to be disposed.		As usual, we use a pointer to our object to indicate the object to be disposed.

			In the case of our requester example, we would simply call:

			<syntaxhighlight>
			IIntuition->DisposeObject(reqobj);
			</syntaxhighlight>

	In many cases - complex gadget GUI's being the prime example - when a BOOPSI object has connect "child" objects and it is disposed, then all children are also disposed. An example would be a window object and all the gadgets within that window. In any case, you must be careful not to dispose of an object that already been disposed.		In many cases - complex gadget GUI's being the prime example - when a BOOPSI object has connect "child" objects and it is disposed, then all children are also disposed. An example would be a window object and all the gadgets within that window. In any case, you must be careful not to dispose of an object that already been disposed.

← Older revision		Revision as of 19:45, 2 June 2018
Line 1:		Line 1:

	In this section we will explore a simple example of creating, interacting with and disposing a simple BOOPSI object - a requester window. With these simple objects you can see the basic operations that are common to almost all BOOPSI objects. When using BOOPSI gadget objects there may be some changes in syntax (f.e., using '''SetGadgetAttrs()''' instead of '''SetAttrs()'''), but the concepts remain the same.		In this section we will explore a simple example of creating, interacting with and disposing a simple BOOPSI object - a requester window. With these simple objects you can see the basic operations that are common to almost all BOOPSI objects. When using BOOPSI gadget objects there may be some changes in syntax (f.e., using '''SetGadgetAttrs()''' instead of '''SetAttrs()'''), but the concepts remain the same.

	==== Creating an Object ====		== Creating an Object ==

	The Intuition functions '''NewObject()''' / '''NewObjectA()''' create a BOOPSI object using either "stack" of tags or predefined a tag list and returns a pointer to a new BOOPSI object:		The Intuition functions '''NewObject()''' / '''NewObjectA()''' create a BOOPSI object using either "stack" of tags or predefined a tag list and returns a pointer to a new BOOPSI object:
Line 39:		Line 38:
	Once the requester object has been created, we still won't see anything yet. Our new object is waiting in the wings for a BOOPSI message to show itself. This leads us to the next sections where we interact with the object we created.		Once the requester object has been created, we still won't see anything yet. Our new object is waiting in the wings for a BOOPSI message to show itself. This leads us to the next sections where we interact with the object we created.

	==== Passing messages to an Object ====		== Passing messages to an Object ==

	To communicate with BOOPSI objects we send "BOOPSI Messages". Unlike traditional AmigaOS "Messages" used by the Exec, ARexx and for interprocess communications, BOOPSI messages are different and frequently rely on tag lists for their content. To "send" a BOOPSI Message to an existing object, we use the '''IDoMethod''' function (or its tag list based variant):		To communicate with BOOPSI objects we send "BOOPSI Messages". Unlike traditional AmigaOS "Messages" used by the Exec, ARexx and for interprocess communications, BOOPSI messages are different and frequently rely on tag lists for their content. To "send" a BOOPSI Message to an existing object, we use the '''IDoMethod''' function (or its tag list based variant):
Line 48:		Line 47:
	</syntaxhighlight>		</syntaxhighlight>

	The return value is class-dependent. The first argument to both of these functions points to the object that will receive the BOOPSI message.		The return value is class-dependent. The first argument to both of these functions points to the object that will receive the BOOPSI message.

	'''IDoMethod()''' then depends on the class and method being used for the contents of the rest of the message. Those elements may include a method name, tags, text or pointers. The class documentation will described those as well as whether the class expects any certain order of tags, etc.		'''IDoMethod()''' then depends on the class and method being used for the contents of the rest of the message. Those elements may include a method name, tags, text or pointers. The class documentation will described those as well as whether the class expects any certain order of tags, etc.

	For a simple example, we can ask the BOOPSI requester object '''reqobj''' (created above) to show itself by sending this message:		For a simple example, we can ask the BOOPSI requester object '''reqobj''' (created above) to show itself by sending this message:
Line 72:		Line 71:
	As mentioned above, there are variants of the '''IDoMethod()''' functions for specific uses, such as the '''DoGadgetMethod()''' function. In that case, the function passes additional information pertinent to GUI gadget objects.		As mentioned above, there are variants of the '''IDoMethod()''' functions for specific uses, such as the '''DoGadgetMethod()''' function. In that case, the function passes additional information pertinent to GUI gadget objects.

	==== Setting an Object's Attributes ====		== Setting an Object's Attributes ==

	Every BOOPSI object is defined by a number of attributes. In the above example we defined our requester when we created the object with '''NewObject()'''. But an object's attributes are not necessarily static. An application can use the '''SetAttrs()''' function to change or set other attributes on an object:		Every BOOPSI object is defined by a number of attributes. In the above example we defined our requester when we created the object with '''NewObject()'''. But an object's attributes are not necessarily static. An application can use the '''SetAttrs()''' function to change or set other attributes on an object:
Line 100:		Line 99:
	Again there is variant of the '''SetAttrs()''' function to be used with BOOPSI GUI gadgets: '''SetGadgetAttrs()'''.		Again there is variant of the '''SetAttrs()''' function to be used with BOOPSI GUI gadgets: '''SetGadgetAttrs()'''.

	==== Getting an Object's Attributes ====		== Getting an Object's Attributes ==

	Just as we can set attributes of an existing BOOPSI object, we also have the ability to get the current settings from a object's attributes. Inquiring about a specific setting is done using the BOOPSI function '''GetAttr()''':		Just as we can set attributes of an existing BOOPSI object, we also have the ability to get the current settings from a object's attributes. Inquiring about a specific setting is done using the BOOPSI function '''GetAttr()''':
Line 137:		Line 136:
	Unlike when creating and setting attributes on BOOPSI GUI gadgets, there are no GUI gadgets specific versions of the '''GetAttr''' family of functions. Instead, the '''GetAttr''' functions can also be used to obtain GUI gadget attributes where they are available (see the Class Reference and autodocs).		Unlike when creating and setting attributes on BOOPSI GUI gadgets, there are no GUI gadgets specific versions of the '''GetAttr''' family of functions. Instead, the '''GetAttr''' functions can also be used to obtain GUI gadget attributes where they are available (see the Class Reference and autodocs).

	==== Disposing of an Object ====		== Disposing of an Object ==

	When an application is finally done with an object, it has to dispose of the object. To dispose of an object, use the Intuition function '''DisposeObject()''':		When an application is finally done with an object, it has to dispose of the object. To dispose of an object, use the Intuition function '''DisposeObject()''':
Line 155:		Line 154:
	In many cases - complex gadget GUI's being the prime example - when a BOOPSI object has connect "child" objects and it is disposed, then all children are also disposed. An example would be a window object and all the gadgets within that window. In any case, you must be careful not to dispose of an object that already been disposed.		In many cases - complex gadget GUI's being the prime example - when a BOOPSI object has connect "child" objects and it is disposed, then all children are also disposed. An example would be a window object and all the gadgets within that window. In any case, you must be careful not to dispose of an object that already been disposed.

	==== What About the BOOPSI Messages and Methods? ====		== What About the BOOPSI Messages and Methods? ==

	In the above sections of this page, the functions used reflect BOOPSI messages and the underlying basic "methods" performed by a BOOPSI object. In the [[BOOPSI#OOP_Overview\|"OOP Overview"]] section we see how these saw how these common methods are practically universal to all BOOPSI classes. The above functions simply provide a wrapper for those common methods like this:		In the above sections of this page, the functions used reflect BOOPSI messages and the underlying basic "methods" performed by a BOOPSI object. In the [[BOOPSI#OOP_Overview\|"OOP Overview"]] section we see how these saw how these common methods are practically universal to all BOOPSI classes. The above functions simply provide a wrapper for those common methods like this:
Line 179:		Line 178:
	Of course, in the case of different classes and objects, the method would change with how the '''IDoMethod''' function was called on those objects.		Of course, in the case of different classes and objects, the method would change with how the '''IDoMethod''' function was called on those objects.

	==== Example Program ====		== Example Program ==

	Below is the complete example program that includes the above excerpts. This program will create a requester object, display a requester with buttons and one with a string gadget and print the results in the shell.		Below is the complete example program that includes the above excerpts. This program will create a requester object, display a requester with buttons and one with a string gadget and print the results in the shell.