Event Driven Programming, Notifications - Revision history

Krashan: Added link to Polish version.

2011-01-18T12:35:29Z

Added link to Polish version.

AusPPC: minor readability fixes

2010-11-19T02:35:27Z

minor readability fixes

Show changes

Krashan: There is no limit on number of action arguments in MUIM_Notify().

2010-11-16T22:41:37Z

There is no limit on number of action arguments in MUIM_Notify().

Krashan: /* The Ideal MUI Main Loop */ Style.

2010-11-16T16:33:56Z

‎The Ideal MUI Main Loop: Style.

Krashan: Style.

2010-11-16T16:29:40Z

Style.

Krashan: /* The Ideal MUI Main Loop */ Contents.

2010-11-16T13:47:49Z

‎The Ideal MUI Main Loop: Contents.

Krashan: Contents.

2010-11-16T13:38:08Z

Contents.

Krashan: Contents.

2010-11-16T13:05:27Z

Contents.

Krashan at 12:57, 16 November 2010

2010-11-16T12:57:27Z

Krashan: Style.

2010-11-16T12:54:04Z

Style.

← Older revision		Revision as of 12:35, 18 January 2011
Line 1:		Line 1:
	''Grzegorz Kraszewski''		''Grzegorz Kraszewski''
		+
		+	----
		+	<small>This article in other languages: [[Programowanie sterowane zdarzeniami, notyfikacje\|Polish]]</small>

	==Event Driven Programming==		==Event Driven Programming==

@@ Line 28: / Line 28: @@
-There is one argument not explained with the above sentence, ''param_count'' namely. This is just the number of parameters following this argument. The minimum number of parameters is 1 (the action method identifier), the maximum one is 7, so the action performed on the target may have no more than 6 parameters.
+There is one argument not explained with the above sentence, ''param_count'' namely. This is just the number of parameters following this argument. The minimum number of parameters is 1 (the action method identifier), there is no upper limit other than the common sense.
 A notification is triggered when an attribute is set to a specified value. It is often useful to have a notification on '''any''' attribute change. A special value ''MUIV_EveryTime'' should be used as a triggering value in this case.
@@ Line 42: / Line 42: @@
 '''''MUIM_NoNotifySet()''''' works the same as ''MUIM_Set()'' with one important exception. It does not trigger any notifications set on the target object, on the attribute being changed. It is often used to avoid notification loops, not only in notification, but also standalone in the code.
-'''''MUIM_MultiSet()''''' allows for setting the same attribute to the same value for multiple objects. Objects are specified as the method arguments, the last, ending argument should be ''NULL''. When used in notification, it allows for up to 3 objects, due to the limit of total number of action arguments. Here is an example, disabling three buttons after a checkmark is deselected:
+'''''MUIM_MultiSet()''''' allows for setting the same attribute to the same value for multiple objects. Objects are specified as the method arguments, the last, ending argument should be ''NULL''. Here is an example, disabling three buttons after a checkmark is deselected:
   DoMethod(checkmark, MUIM_Notify, MUIA_Selected, FALSE, application, 7, MUIM_MultiSet,

@@ Line 96: / Line 96: @@
+  }
-The variable ''signals'' contains a bitmask of input event signals sent to the process by the operating system. Its initial value 0 means just "no signals". When the ''MUIM_Application_NewInput()'' method is performed on the application object, MUI sets signal bits for input events it expects in the ''signals'' variable. These signals are usually signals of application windows' message ports, where the ''Intuition'' sends input events. Then the application calls ''exec.library'' function ''Wait()''. Inside this function, the execution of the process is stopped. The process scheduler will not give any processor time to the process until one of signals in the mask arrives. Except of input event singals set by MUI, the system CTRL-C signal is added to the mask. Every well written MorphOS application should be breakable by sending this signal. It can be done in the console by pressing CTRL + C keys, or from tools like the TaskManager. When one of signals in the mask arrives to the process, the program returns from ''Wait()''. If the CTRL-C signal is detected, the main loop ends. If not, MUI decodes received input events basing on the received signal mask, translates events to changes of attributes of relevant objects and performs triggered notifications. All this happens inside the ''MUIM_Application_NewInput()'' method. Finally the signal mask is updated. If any notification called ''MUIM_Application_ReturnID()'' method, the identifier passed is returned as the result of ''MUIM_Application_NewInput()''. In case of receiving the special value ''MUIV_Application_ReturnID_Quit'' the loop ends.
+The variable ''signals'' contains a bitmask of input event signals sent to the process by the operating system. Its initial value 0 means just "no signals". When the ''MUIM_Application_NewInput()'' method is performed on the application object, MUI sets signal bits for input events it expects in the ''signals'' variable. These signals are usually signals of application windows' message ports, where the ''Intuition'' sends input events. Then the application calls ''exec.library'' function ''Wait()''. Inside this function, the execution of the process is stopped. The process scheduler will not give any processor time to the process until one of signals in the mask arrives. Except of input event singals set by MUI, the system CTRL-C signal is added to the mask. Every well written MorphOS application should be breakable by sending this signal. It can be done in the console by pressing CTRL + C keys, or from tools like the TaskManager. When one of signals in the mask arrives to the process, the program returns from ''Wait()''. If the CTRL-C signal is detected, the main loop ends. If not, MUI decodes received input events basing on the received signal mask, translates events to changes of attributes of relevant objects and performs triggered notifications. All this happens inside the ''MUIM_Application_NewInput()'' method. Finally the signal mask is updated. If any notification calls ''MUIM_Application_ReturnID()'' method, the identifier passed is returned as the result of ''MUIM_Application_NewInput()''. In case of receiving the special value ''MUIV_Application_ReturnID_Quit'' the loop ends.
 Any additional code inserted into the loop will introduce delay in GUI handling and redrawing. If a program does some processor intensive calculations, the best way to deal with them is to delegate them into a subprocess. Loading the main process with computational tasks ends up in a program percepted as slow and unresponsive to user actions.

← Older revision		Revision as of 16:29, 16 November 2010
Line 68:		Line 68:
	MUIM_Set, MUIA_Disabled, '''MUIV_NotTriggerValue''');		MUIM_Set, MUIA_Disabled, '''MUIV_NotTriggerValue''');

−	<small>''MUIV_EveryTime'', ''MUIV_TriggerValue'' and ''MUIV_NotTriggerValue'' are defined as particular values in the 32-bit range. Because of this, it is impossible to set a notification to the value 1 233 727 793 (which is ''MUIV_EveryTime''). It is also impossible to ~~use ''MUIM_Set()'' in a notification, setting~~ the value to a fixed number 1 233 727 793 (''MUIV_TriggerValue'') or 1 233 727 795 (''MUIV_NotTriggerValue'').</small>	+	<small>''MUIV_EveryTime'', ''MUIV_TriggerValue'' and ''MUIV_NotTriggerValue'' are defined as particular values in the 32-bit range. Because of this, it is impossible to set a notification on the value 1 233 727 793 (which is ''MUIV_EveryTime''). It is also impossible to set the value to a fixed number 1 233 727 793 (''MUIV_TriggerValue'') or 1 233 727 795 (''MUIV_NotTriggerValue'') using ''MUIM_Set()'' in a notification.</small>

← Older revision		Revision as of 13:47, 16 November 2010
Line 96:		Line 96:
	}		}

−	The variable ''signals'' contains a bitmask of input event signals sent to the process by the operating system. Its initial value 0 means just "no signals". When the ''MUIM_Application_NewInput()'' method is performed on the application object, MUI sets signal bits for input events it expects in the ''signals'' variable. These signals are usually signals of application windows' message ports, where the ''Intuition'' sends input events. Then the application calls ''exec.library'' function ''Wait()''. Inside this function, the execution of the process is stopped. The process scheduler will not give any processor time to the process until one of signals in the mask arrives. Except of input event singals set by MUI, the system CTRL-C signal is added to the mask. Every well written MorphOS application should be breakable by sending this signal. It can be done in the console by pressing CTRL + C keys, or from tools like the TaskManager. When one of signals in the mask arrives to the process, the program returns from ''Wait()''. If the CTRL-C signal is detected, the main loop ends. If not, MUI decodes received input events basing on the received signal mask, translates events to changes of attributes of relevant objects and performs triggered notifications. All this happens inside the ''MUIM_Application_NewInput()'' method. Finally the signal mask is updated. If any notification called ''MUIM_Application_ReturnID()'' method, the identifier passed is returned as the result of ''MUIM_Application_NewInput()''.	+	The variable ''signals'' contains a bitmask of input event signals sent to the process by the operating system. Its initial value 0 means just "no signals". When the ''MUIM_Application_NewInput()'' method is performed on the application object, MUI sets signal bits for input events it expects in the ''signals'' variable. These signals are usually signals of application windows' message ports, where the ''Intuition'' sends input events. Then the application calls ''exec.library'' function ''Wait()''. Inside this function, the execution of the process is stopped. The process scheduler will not give any processor time to the process until one of signals in the mask arrives. Except of input event singals set by MUI, the system CTRL-C signal is added to the mask. Every well written MorphOS application should be breakable by sending this signal. It can be done in the console by pressing CTRL + C keys, or from tools like the TaskManager. When one of signals in the mask arrives to the process, the program returns from ''Wait()''. If the CTRL-C signal is detected, the main loop ends. If not, MUI decodes received input events basing on the received signal mask, translates events to changes of attributes of relevant objects and performs triggered notifications. All this happens inside the ''MUIM_Application_NewInput()'' method. Finally the signal mask is updated. If any notification called ''MUIM_Application_ReturnID()'' method, the identifier passed is returned as the result of ''MUIM_Application_NewInput()''. In case of receiving the special value ''MUIV_Application_ReturnID_Quit'' the loop ends.
		+
		+	Any additional code inserted into the loop will introduce delay in GUI handling and redrawing. If a program does some processor intensive calculations, the best way to deal with them is to delegate them into a subprocess. Loading the main process with computational tasks ends up in a program percepted as slow and unresponsive to user actions.

@@ Line 68: / Line 68: @@
    MUIM_Set, MUIA_Disabled, '''MUIV_NotTriggerValue''');
-<small>''MUIV_EveryTime'', ''MUIV_TriggerValue'' and ''MUIV_NotTriggerValue'' are defined as particular values in the 32-bit range. Because of this, it is impossible to set a notification to the value 1 233 727 793 (which is ''MUIV_EveryTime''). It is also impossible to use ''MUIM_Set()'' in a notification, setting the value to 1 233 727 793 (''MUIV_TriggerValue'') or 1 233 727 795 (''MUIV_NotTriggerValue'').</small>
+<small>''MUIV_EveryTime'', ''MUIV_TriggerValue'' and ''MUIV_NotTriggerValue'' are defined as particular values in the 32-bit range. Because of this, it is impossible to set a notification to the value 1 233 727 793 (which is ''MUIV_EveryTime''). It is also impossible to use ''MUIM_Set()'' in a notification, setting the value to a fixed number 1 233 727 793 (''MUIV_TriggerValue'') or 1 233 727 795 (''MUIV_NotTriggerValue'').</small>
@@ Line 84: / Line 84: @@
 ==The Ideal MUI Main Loop==

← Older revision		Revision as of 13:05, 16 November 2010
Line 67:		Line 67:
	DoMethod(checkmark, MUIM_Notify, MUIA_Selected, MUIV_EveryTime, button, 3,		DoMethod(checkmark, MUIM_Notify, MUIA_Selected, MUIV_EveryTime, button, 3,
	MUIM_Set, MUIA_Disabled, '''MUIV_NotTriggerValue''');		MUIM_Set, MUIA_Disabled, '''MUIV_NotTriggerValue''');
		+
		+	<small>''MUIV_EveryTime'', ''MUIV_TriggerValue'' and ''MUIV_NotTriggerValue'' are defined as particular values in the 32-bit range. Because of this, it is impossible to set a notification to the value 1 233 727 793 (which is ''MUIV_EveryTime''). It is also impossible to use ''MUIM_Set()'' in a notification, setting the value to 1 233 727 793 (''MUIV_TriggerValue'') or 1 233 727 795 (''MUIV_NotTriggerValue'').</small>

@@ Line 30: / Line 30: @@
 There is one argument not explained with the above sentence, ''param_count'' namely. This is just the number of parameters following this argument. The minimum number of parameters is 1 (the action method identifier), the maximum one is 7, so the action performed on the target may have no more than 6 parameters.
-A notification is triggered when an attribute is set to a specified value. It is often useful to have a notification on '''any''' attribute change. A special value ''MUIV_Notify_EveryTime'' should be used as a triggering value in this case.
+A notification is triggered when an attribute is set to a specified value. It is often useful to have a notification on '''any''' attribute change. A special value ''MUIV_EveryTime'' should be used as a triggering value in this case.
 The target action of a notification can be any method. There are a few methods designed specifically to be used in notifications:

← Older revision		Revision as of 12:54, 16 November 2010
Line 51:		Line 51:
	'''''MUIM_CallHook()''''' calls an external callback function called a [[hook]]. It is often abused by programmers being reluctant to subclassing standard classes and implementing program functionality as new methods. Calling a method from a notification is usually faster and easier (a hook needs some additional structures to be defined).		'''''MUIM_CallHook()''''' calls an external callback function called a [[hook]]. It is often abused by programmers being reluctant to subclassing standard classes and implementing program functionality as new methods. Calling a method from a notification is usually faster and easier (a hook needs some additional structures to be defined).

−	'''''MUIM_Application_ReturnID()''''' returns a 32-bit integer number to [[#The_Ideal_MUI_Main_Loop\|the main loop]] of a MUI program. With this method MUI decentralized handling of input events can be turned into a centralized one. MUI programming beginners tend to abuse this method and redirect all the event handling back to the main loop, putting a big ''switch'' statement there. While rather simple, this programming technique should be avoided in favour of implementing program functionality in methods. Adding code inside the main loop ~~lowers~~ the GUI responsiveness. The only legitimate use of ''MUIM_Application_ReturnID()'' is to return a special value ''MUIV_Application_ReturnID_Quit'' used for ending the program.	+	'''''MUIM_Application_ReturnID()''''' returns a 32-bit integer number to [[#The_Ideal_MUI_Main_Loop\|the main loop]] of a MUI program. With this method MUI decentralized handling of input events can be turned into a centralized one. MUI programming beginners tend to abuse this method and redirect all the event handling back to the main loop, putting a big ''switch'' statement there. While rather simple, this programming technique should be avoided in favour of implementing program functionality in methods. Adding code inside the main loop degrades the GUI responsiveness. The only legitimate use of ''MUIM_Application_ReturnID()'' is to return a special value ''MUIV_Application_ReturnID_Quit'' used for ending the program.