From: <mie...@us...> - 2012-11-04 19:20:32
|
Revision: 8559 http://sourceforge.net/p/oorexx/code-0/8559 Author: miesfeld Date: 2012-11-04 19:20:29 +0000 (Sun, 04 Nov 2012) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:08:34 UTC (rev 8558) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:20:29 UTC (rev 8559) @@ -4638,6 +4638,7 @@ <para> Connecting this event and not using the <emphasis role="italic">willReply</emphasis> argument does not make much sense. The event handler really serves no purpose. + </para> </listitem></varlistentry> </variablelist> </listitem></varlistentry> |
From: <mie...@us...> - 2012-11-04 19:22:05
|
Revision: 8560 http://sourceforge.net/p/oorexx/code-0/8560 Author: miesfeld Date: 2012-11-04 19:22:02 +0000 (Sun, 04 Nov 2012) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:20:29 UTC (rev 8559) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:22:02 UTC (rev 8560) @@ -4975,6 +4975,7 @@ When the user does not cancel the edit operation, the operating system automatically changes the label of the item to what the user entered. To prevent this behavior, the programmer needs to use the new style event handler by using the <emphasis role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectListViewEvent"/> method. + </para> </listitem></varlistentry> </variablelist> </listitem></varlistentry> |
From: <mie...@us...> - 2012-11-04 19:24:54
|
Revision: 8561 http://sourceforge.net/p/oorexx/code-0/8561 Author: miesfeld Date: 2012-11-04 19:24:51 +0000 (Sun, 04 Nov 2012) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:22:02 UTC (rev 8560) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:24:51 UTC (rev 8561) @@ -4423,7 +4423,7 @@ ::method columnAction unguarded use arg id, column - lc = self~newListView("EMPLOYEES") + lc = self~mthNewClsListView("EMPLOYEES") lc~replaceStyle("REPORT", "SMALLICON EDIT SINGLESEL ASCENDING") if column > 0 then ... @@ -4483,7 +4483,7 @@ <para> In general, the programmer would connect both the BEGINEDIT and <xref linkend="evtListViewENDEDIT"/> notifications. Both of these event notifications have been enhanced since the original ooDialog implementation. If the <emphasis - role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectLiistViewEvent"/> method is omitted the old + role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectListViewEvent"/> method is omitted the old implementation is used. If the argument is not omitted, the new implementation is used. How the two event handlers work is described separately. </para> @@ -4543,7 +4543,7 @@ <listitem> <para> The Rexx list-view object whose underlying list-view control has sent the notification. This is a convenience for - the programmer. It is the same Rexx object the programmer would recieve through the <xref linkend="newListView"/> + the programmer. It is the same Rexx object the programmer would recieve through the <xref linkend="mthNewClsListView"/> method. Unlike the <emphasis role="italic">editCtrl</emphasis> object, this object is valid as long as the dialog is executing. </para> @@ -4695,7 +4695,7 @@ expose mailList ... - mailList = self~newListView(IDC_LV_ADDRESSES) + mailList = self~mthNewClsListView(IDC_LV_ADDRESSES) ... -- Since the methodName argument is omitted, ooDialog will construct a default @@ -4804,7 +4804,7 @@ <para> In general, the programmer would connect both the <xref linkend="evtListViewBEGINEDIT"/> and ENDEDIT notifications. Both of these event notifications have been enhanced since the original ooDialog implementation. If the <emphasis - role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectLiistViewEvent"/> method is omitted the old + role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectListViewEvent"/> method is omitted the old implementation is used. If the argument is not omitted, the new implementation is used. How the two event handlers work is described separately. </para> @@ -4859,7 +4859,7 @@ <listitem> <para> The Rexx list-view object whose underlying list-view control has sent the notification. This is a convenience for - the programmer. It is the same Rexx object the programmer would recieve through the <xref linkend="newListView"/> + the programmer. It is the same Rexx object the programmer would recieve through the <xref linkend="mthNewClsListView"/> method. </para> </listitem></varlistentry> |
From: <mie...@us...> - 2012-11-04 19:31:16
|
Revision: 8562 http://sourceforge.net/p/oorexx/code-0/8562 Author: miesfeld Date: 2012-11-04 19:31:14 +0000 (Sun, 04 Nov 2012) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:24:51 UTC (rev 8561) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-04 19:31:14 UTC (rev 8562) @@ -4423,7 +4423,7 @@ ::method columnAction unguarded use arg id, column - lc = self~mthNewClsListView("EMPLOYEES") + lc = self~newListView("EMPLOYEES") lc~replaceStyle("REPORT", "SMALLICON EDIT SINGLESEL ASCENDING") if column > 0 then ... @@ -4543,9 +4543,9 @@ <listitem> <para> The Rexx list-view object whose underlying list-view control has sent the notification. This is a convenience for - the programmer. It is the same Rexx object the programmer would recieve through the <xref linkend="mthNewClsListView"/> - method. Unlike the <emphasis role="italic">editCtrl</emphasis> object, this object is valid as long as the dialog - is executing. + the programmer. It is the same Rexx object the programmer would recieve through the <xref + linkend="mthNewListView"/> method. Unlike the <emphasis role="italic">editCtrl</emphasis> object, this object is + valid as long as the dialog is executing. </para> </listitem></varlistentry> </variablelist> @@ -4695,7 +4695,7 @@ expose mailList ... - mailList = self~mthNewClsListView(IDC_LV_ADDRESSES) + mailList = self~newListView(IDC_LV_ADDRESSES) ... -- Since the methodName argument is omitted, ooDialog will construct a default @@ -4859,8 +4859,8 @@ <listitem> <para> The Rexx list-view object whose underlying list-view control has sent the notification. This is a convenience for - the programmer. It is the same Rexx object the programmer would recieve through the <xref linkend="mthNewClsListView"/> - method. + the programmer. It is the same Rexx object the programmer would recieve through the <xref + linkend="mthNewListView"/> method. </para> </listitem></varlistentry> </variablelist> |
From: <mie...@us...> - 2012-11-08 03:21:55
|
Revision: 8575 http://sourceforge.net/p/oorexx/code-0/8575 Author: miesfeld Date: 2012-11-08 03:21:51 +0000 (Thu, 08 Nov 2012) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-08 01:00:26 UTC (rev 8574) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-08 03:21:51 UTC (rev 8575) @@ -7816,7 +7816,7 @@ implement a drag-and-drop handler. </para> </listitem></varlistentry> - <varlistentry id="kywTreeViewBEGINGEDIT" xreflabel="BEGINEDIT"><term>BEGINEDIT</term> + <varlistentry id="kywTreeViewBEGINEDIT" xreflabel="BEGINEDIT"><term>BEGINEDIT</term> <listitem> <para> Editing a label has been started. Do not connect this event if you are using the DEFAULTEDIT keyword. The results are |
From: <mie...@us...> - 2012-11-22 04:51:04
|
Revision: 8613 http://sourceforge.net/p/oorexx/code-0/8613 Author: miesfeld Date: 2012-11-22 04:51:01 +0000 (Thu, 22 Nov 2012) Log Message: ----------- ooDialog docs, fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 04:46:55 UTC (rev 8612) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 04:51:01 UTC (rev 8613) @@ -7443,7 +7443,7 @@ <para> The <emphasis role="italic">connectToolTipEvent</emphasis> method connects an <xref linkend="ovvEvents"/> notification - message from a <xref linkend="clsTooltip"/> control to a method in the Rexx dialog. + message from a <xref linkend="clsToolTip"/> control to a method in the Rexx dialog. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> |
From: <mie...@us...> - 2012-11-22 22:00:27
|
Revision: 8618 http://sourceforge.net/p/oorexx/code-0/8618 Author: miesfeld Date: 2012-11-22 22:00:24 +0000 (Thu, 22 Nov 2012) Log Message: ----------- ooDialog doc, fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 21:59:15 UTC (rev 8617) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-22 22:00:24 UTC (rev 8618) @@ -7688,8 +7688,8 @@ <listitem> <para> This index is set to the <emphasis role="italic">user data</emphasis> specified for the tool. For example, in the - <xref linkend="mthAddTool"/>, <xref linkend="mtAddToolEx"/>, or <xref linkend="mthAddToolRect"/> methods. If there is - no user data, the index is set to the <computeroutput>.nil</computeroutput> object. + <xref linkend="mthAddTool"/>, <xref linkend="mthAddToolEx"/>, or <xref linkend="mthAddToolRect"/> methods. If there + is no user data, the index is set to the <computeroutput>.nil</computeroutput> object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">FLAGS</emphasis></term> |
From: <mie...@us...> - 2012-11-28 00:57:30
|
Revision: 8633 http://sourceforge.net/p/oorexx/code-0/8633 Author: miesfeld Date: 2012-11-28 00:57:27 +0000 (Wed, 28 Nov 2012) Log Message: ----------- ooDialog doc, fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-28 00:50:36 UTC (rev 8632) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-28 00:57:27 UTC (rev 8633) @@ -9389,7 +9389,7 @@ This event notification has been enhanced since the original ooDialog implementation. However, the only enhancement is to allow the programmer to specify if the interepreter should wait for a return from the event handler. The aruments sent to the event handler remain the same. - If the <emphasis role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectTreeViewEvetn"/> method is + If the <emphasis role="italic">willReply</emphasis> argument to the <xref linkend="mthConnectTreeViewEvent"/> method is true, the interpreter will wait for the return from the event handler. If <emphasis role="italic">willReply</emphasis> is false, or omitted, the interpreter does not wait. </para> |
From: <mie...@us...> - 2012-11-29 04:17:35
|
Revision: 8640 http://sourceforge.net/p/oorexx/code-0/8640 Author: miesfeld Date: 2012-11-29 04:17:31 +0000 (Thu, 29 Nov 2012) Log Message: ----------- ooDialog doc, fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-29 04:14:10 UTC (rev 8639) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2012-11-29 04:17:31 UTC (rev 8640) @@ -7501,7 +7501,7 @@ This notification is sent when the ToolTip control needs to retrieve the text used to display a ToolTip window. </para> </listitem></varlistentry> - <varlistentry id="kywToolTipLINKCLICK" xreflabel="LINKCLICK"><term>POP</term> + <varlistentry id="kywToolTipPOP" xreflabel="POS"><term>POP</term> <listitem> <para> This notification is sent when a ToolTip is about to be hidden. |
From: <mie...@us...> - 2013-01-16 03:40:09
|
Revision: 8850 http://sourceforge.net/p/oorexx/code-0/8850 Author: miesfeld Date: 2013-01-16 03:40:06 +0000 (Wed, 16 Jan 2013) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2013-01-16 03:03:43 UTC (rev 8849) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2013-01-16 03:40:06 UTC (rev 8850) @@ -4665,7 +4665,7 @@ </para> <para> If the programmer specifies true for the <emphasis role="italic">willReply</emphasis> argument in the <xref - linkend="mthConnectLisvtViewEvent"/> method, then the event handler must return a value and the interpreter waits for this + linkend="mthConnectListViewEvent"/> method, then the event handler must return a value and the interpreter waits for this return. If the <emphasis role="italic">willReply</emphasis> argument is false, the event handler does not need to return a value and the interpreter does not wait for the return. However, it is good practice to always return a value from an event handler. The operating system ignores the value of the return, so any value can be returned. Zero makes a good return value @@ -5130,7 +5130,7 @@ </para> <para> If the programmer specifies true for the <emphasis role="italic">willReply</emphasis> argument in the <xref - linkend="mthConnectLisvtViewEvent"/> method, then the event handler must return a value and the interpreter waits for this + linkend="mthConnectListViewEvent"/> method, then the event handler must return a value and the interpreter waits for this return. If the <emphasis role="italic">willReply</emphasis> argument was false, the event handler does not need to return a value and the interpreter does not wait for the return. However, it is good practice to always return a value from an event handler. The operating system ignores the value of the return, so any value can be returned. Zero makes a good return value |
From: <mie...@us...> - 2013-06-25 02:29:17
|
Revision: 9326 http://sourceforge.net/p/oorexx/code-0/9326 Author: miesfeld Date: 2013-06-25 02:29:13 +0000 (Tue, 25 Jun 2013) Log Message: ----------- ooDialog doc - fix copy / paste error Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2013-06-24 21:30:27 UTC (rev 9325) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2013-06-25 02:29:13 UTC (rev 9326) @@ -1087,7 +1087,7 @@ </para> <para> If the programmer does not provide a matching method in the Rexx dialog, a syntax condition will be raised if any - sizing events happen. + activate events happen. </para> <para> The underlying dialog receives the WM_ACTIVATE message as the notification for this event. |
From: <mie...@us...> - 2013-12-29 22:25:43
|
Revision: 9769 http://sourceforge.net/p/oorexx/code-0/9769 Author: miesfeld Date: 2013-12-29 22:25:40 +0000 (Sun, 29 Dec 2013) Log Message: ----------- [feature-requests:#575] Send the Rexx Tab object to tab control event handlers [feature-requests:#574] Event connections should all have a 'willReply' argument Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-29 19:03:56 UTC (rev 9768) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-29 22:25:40 UTC (rev 9769) @@ -148,69 +148,38 @@ <para> However, having the interpreter waiting for the return of an event handling method could conceivably be a problem for some few existing programs. Since, in older ooDialog versions, the return from an event handler method was - meaningless, some programmers may not have returned from the method in a timely manner, and never realized this was a - mistake. In addition, there are a large number of event notifications in Windows where the operating system ignores - the reply. Therefore, the ooDialog framework uses two different ways to invoke the event handling method. The first, - preferred, method is for the interpreter to invoke the method directly, wait for the return, and then use the return - to reply to the Windows event notification. The second is to invoke the event handling method using the <emphasis - role="italic">startWith</emphasis>() method of the <computeroutput>Object</computeroutput> class. This starts the - event handling method concurrently, and the ooDialog framework replies to the Windows event notification immediately. + meaningless, some programmers may not have returned an actual value from the method, and / or they may not have returned + from the method in a timely manner. The programmer may not have realized this was a mistake. </para> <para> - In general, whether the ooDialog framework invokes the event handling method and waits for the return, or uses - <emphasis role="italic">startWith</emphasis>() and replies to the Windows event notification immediately is determined - using these rules: + In addition, there are a large number of event notifications in Windows where the operating system ignores the reply. + Therefore, the ooDialog framework uses three different ways to invoke the event handling method. This is controlled by the + <link linkend="sctCommonWillReply">willReply</link> argument that is common to all event connection methods. </para> -<orderedlist> -<listitem> <para> - Event connections made using the event connection methods that existed prior to ooDialog 4.2.0, using the existing - event keywords, and existing arguments, use <emphasis role="italic">startWith</emphasis> to invoke the event handlers. - The programmer can not change this. For the purpose of this discussion, these methods will be called existing - connection methods. + The first, preferred, method is for the interpreter to invoke the method directly, wait for the return, and then use the + return value to reply to the Windows event notification. The second is to return 0 immediately to the operaring system, + and invoke the event handling method to run concurrently as a separate activity. The third is to invoke the event handler + directly, wait for the reply from the event handler, but ignore the returned value. </para> -</listitem> -<listitem> +<note><title>Event handling methods must be public</title> <para> - All event connections made using event connection methods introduced after ooDialog 4.1.0 assume the programmer wants - the event handler invoked directly and for the ooDialog framework to wait for the return. These methods will be called - new connection methods. For instance, the <xref linkend="clsDateTimePicker"/> control did not exist in ooDialog 4.1.0, so - its event connection method, <xref linkend="mthConnectDateTimePickerEvent"/> falls into this category. + Event handling methods must be public, they <emphasis role="italic">can not</emphasis> be private. The dialog object has + no way of knowing an event has happened. Some object, some thing, outside of the dialog object, knows of the event. That + other object must notify the dialog that the event has happened. In this case the other object is the operating system. </para> -</listitem> -<listitem> <para> - For new connection methods, when the reply to an event notification has a meaning for the notification, the framework - always invokes the event handler directly and waits for the return. The programmer can not change this. If the - programmer does not want to reply to the event, then he should simply not connect the event. + Private methods of an object can not be invoked from outside of the object. If an event handling method is private, there + is no way for the operating systme to invoke that method to notify the dialog that the event has happened. </para> -</listitem> -<listitem> -<para> - All new connection methods have an optional argument that allows the programmer to specify whether she wants the - framework to wait for the return, or use <emphasis role="italic">startWith</emphasis> and reply immediately. When the - reply to an event is ignored by the operating system, the optional argument will be used to direct the framework to - invoke the event handler directly or use <emphasis role="italic">startWith</emphasis>. By default, the framework - invokes the connected method directly. -</para> -</listitem> -<listitem> -<para> - Over time, the existing connections will be enhanced to also take an optional argument. This will allow the - programmer to specify that the framework invoke the event handler directly and wait for the return. This enhancement - has started, but is far from complete. -</para> -</listitem> -<listitem> -<para> - The documentation for each event connection method, for each event, will specify how the event handler will be - invoked. -</para> -</listitem> -</orderedlist> +</note> +</section> + +<section id="sctCoding Event Handler Examples"><title>Coding Event Handler Examples</title> +<indexterm><primary>Coding Event Handler Examples</primary></indexterm> <para> - The following code snippets and examples expand on these details. + The following code snippets and examples expand on the discussion of how to code event handling methods. </para> <para> Best practice would be to always code event handlers as if they are expected to return a value to the operating @@ -224,9 +193,9 @@ the display. Note these points about the code snippet. Since the <emphasis role="italic">connectButtonEvent</emphasis> method is the replacement for the <xref linkend="ovvDeprecated"/> <emphasis role="italic">connectButtonNotify</emphasis> it is in essence an existing connection method, using the original - arguments. Therefore, the method is invoked from the message processing loop using <emphasis - role="italic">startWith</emphasis>. Because of this, technically, it does not have to be unguarded and does not have - to return a value. Nevertheless, it is the <emphasis role="italic">correct</emphasis> way to code the event handler. + arguments. Therefore, by default, the method is invoked from the message processing loop to run concurrently as a separate + activity. Because of this, technically, it does not have to be unguarded and does not have to return a value. Nevertheless, + the example is the <emphasis role="italic">correct</emphasis> way to code the event handler. <programlisting> <![CDATA[ ::method initDialog @@ -248,7 +217,7 @@ <para> Consider this snippet from a similar program, but where the push button starts a process that calculates the grains of sand in the universe. Since it is not expected that the calculation will finish in a reasonable amount of time, an - early reply is used to return a value in a timely manner. The handler also disables the push button so tha the user + early reply is used to return a value in a timely manner. The handler also disables the push button so that the user can not start a second calculation until the first calculation finishes. <programlisting> <![CDATA[ @@ -273,21 +242,25 @@ </para> <para> - The following examples are all for events where the event handler must return a value. + The following examples are all for events where having the interpreter wait for the returned value from the event handler + is the best way to handle the notifications. </para> <variablelist> <varlistentry id="exampleEventHandler1"><term><emphasis role="bold">Returning Values</emphasis></term> <listitem> <para> - The month <xref linkend="clsMonthCalendar"/> control has the - <xref linkend="evtMonthCalendarGETDAYSTATE"/> event that is sent to request information on how certain - days are to be shown. The programmer can customize the calendar by returning a set of days that should be displayed - in bold. For instance, in a business application paid holidays could be displayed in bold. + The <xref linkend="clsMonthCalendar"/> control has the <xref linkend="evtMonthCalendarGETDAYSTATE"/> event that is sent + to request information on how certain days are to be shown. The programmer can customize the calendar by returning a set + of days that should be displayed in bold. For instance, in a business application paid holidays could be displayed in + bold. </para> <para> Since the <emphasis role="italic">connectMonthCalendarEvent</emphasis> method did not exist in ooDialog 4.1.0 and - the return value for this event is meaningful, the second and third rules above apply. That is, the interpreter - invokes the event handler directly, waits for the reply, and the programmer can not change this behavior. + the return value for this event controls what the operating system does, the <link + linkend="sctCommonWillReply">willReply</link> argument is forced to true by the ooDialog framework. That is, the + interpreter invokes the event handler directly, waits for the reply value, and returns that value to the operating + system., The programmer can not change this behavior. If the programmer does not wish to return a meaningful value from + the event handler, the event should not be connected. </para> <programlisting> @@ -346,11 +319,10 @@ <varlistentry id="exampleEventHandler2"><term><emphasis role="bold">Event Synchronization</emphasis></term> <listitem> <para> - The <xref linkend="clsDateTimePicker"/> (date time picker) control has the - <xref linkend="mthConnectDateTimePickerEvent"/> event notification that is sent when the drop down calendar - is shown. This gives the programmer a chance to customize the month calendar that is shown. Since the month calendar - is not shown until the event handling method returns, replying directly to the notification allows the programmer to - completely finish the customizations before the month calendar appears on the screen. + The <xref linkend="clsDateTimePicker"/> control has the DROPDOWN event notification that is sent when the drop down + calendar is shown. This gives the programmer a chance to customize the month calendar that is shown. Since the month + calendar is not shown until the event handling method returns, replying directly to the notification allows the + programmer to completely finish the customizations before the month calendar appears on the screen. </para> <programlisting> @@ -376,12 +348,12 @@ </programlisting> <para> In the above example, the <emphasis role="italic">connectDateTimePickerEvent</emphasis> method did not exist in - ooDialog 4.1.0, but the return value for this event is ignored by the OS. Therefore, the second and fourth rules - above apply. That is, by default the interpreter invokes the event handler directly and waits for a reply. However - the programmer can change this behavior if he wants. If there is no reason to have the interpreter wait until the - event handler finishes, then the programmer could use the fourth optional argument. The - <computeroutput>.false</computeroutput> value tells the ooDialog framework to use the <emphasis - role="italic">startWith</emphasis> method to invoke the event handler. + ooDialog 4.1.0. Therefore, by default the interpreter invokes the event handler directly, waits for a reply, and expects + a returned value. However, the operating system ignores the actual value of the return. The programmer can change the + default behavior if he wants. If there is no reason to have the interpreter wait until the event handler finishes, then + the programmer could use the optional <emphasis role="italic">willReply</emphasis> argument. The + <computeroutput>.false</computeroutput> value tells the ooDialog framework to invoke the event handler to run + concurrently as a separate activity. </para> <programlisting> @@ -401,27 +373,51 @@ ]]> </programlisting> + <para> + However, if the programmer is going to customize the calendar, having the event handler run concurrently is likely to + have the calendar shown befor the customization is finished. So, it makes much more sense to at least use the <emphasis + role="italic">sync</emphasis> option in this way: + </para> +<programlisting> +<![CDATA[ + +::method initDialog + + self~connectDateTimePickerEvent(IDC_DTP, "DROPDOWN", onDropDown, 'SYNC') + ... + + +::method onDropDown unguarded + use arg idFrom, hwndFrom + + dt = self~newDateTimePicker(IDC_DTP); + monthCal = dt~getMonthCal + monthCal~setFirstDayOfWeek(3) + monthCal~addStyle("NOTODAY") + +]]> +</programlisting> </listitem></varlistentry> <varlistentry id="exampleEventHandler3"><term><emphasis role="bold">Veto Events</emphasis></term> <listitem> <para> - The <xref linkend="clsTab"/> control has the <xref linkend="mthConnectTabEvent"/> event. - It is sent when the user selects a different tab, and is sent <emphasis role="bold">before</emphasis> the selected - tab is changed. The programmer can <emphasis role="italic">veto</emphasis> the change to a new tab by returning - <computeroutput>.false</computeroutput> to the event notification, or allow the change by returning - <computeroutput>.true</computeroutput>. One reason for preventing the change might be that the user had entered - invalid data in the current tab page. + The <xref linkend="clsTab"/> control has the SELCHANGING event. It is sent when the user selects a different tab, and is + sent <emphasis role="bold">before</emphasis> the selected tab is changed. The programmer can <emphasis + role="italic">veto</emphasis> the change to a new tab by returning <computeroutput>.false</computeroutput> to the event + notification, or allow the change by returning <computeroutput>.true</computeroutput>. One reason for preventing the + change might be that the user had entered invalid data in the current tab page. </para> <para> <emphasis role="bold">Note:</emphasis> Since the <emphasis role="italic">connectTabEvent</emphasis> method is the replacement for the <emphasis role="italic">ovvDeprecated</emphasis> <emphasis - role="italic">connectTabNotify</emphasis> method, it essentially is a method that existed in ooDialog 4.1.0. The - above rules one and five apply. That is, when the same arguments are used as existed in 4.1.0, the event handler is - invoked using <emphasis role="italic">startWith</emphasis> and the interpreter does not wait for a return value. - With this behavior, it is impossible for the programmer to veto the change to a new tab. Therefore the programmer - has to use the fourth optional argument to change the default behavior. Specifying + role="italic">connectTabNotify</emphasis> method, it essentially is a method that existed in ooDialog 4.1.0. When the + same arguments are used as existed in 4.1.0, the default for <emphasis role="italic">willReply</emphasis> is false. The + event handler is invoked to run concurrently as a separate activity and the interpreter does not wait for a return value. + With this behavior, it is impossible for the programmer to veto the change to a new tab. Therefore the programmer has to + use the optional <emphasis role="italic">willReply</emphasis> argument to change the default behavior. Specifying <computeroutput>.true</computeroutput> causes the ooDialog framework to invoke the <emphasis - role="italic">onTabChanging</emphasis> method directly and wait for the return value. + role="italic">onTabChanging</emphasis> method directly, wait for the return value, and pass that value to the operating + system. </para> <programlisting> <![CDATA[ @@ -437,13 +433,13 @@ index = self~newTab(idFrom)~selectedIndex + 1 dlg = tabContent[index] - if dlg~validate then return .true + if dlg~allowChange then return .true else return .false ]]> </programlisting> <para> - In the above example, since the <emphasis role="italic">validate</emphasis> method is returning + In the above example, since the <emphasis role="italic">allowChange</emphasis> method is returning <computeroutput>.true</computeroutput> or <computeroutput>.false</computeroutput> the event handler could have been coded this way: </para> @@ -453,14 +449,14 @@ ... - return dlg~validate + return dlg~allowChange ]]> </programlisting> <para> The example used: <programlisting> <![CDATA[ - if dlg~validate then return .true + if dlg~allowChange then return .true else return .false ]]> </programlisting> @@ -471,8 +467,8 @@ <varlistentry id="exampleEventHandler4"><term><emphasis role="bold">Lengthy Processing</emphasis></term> <listitem> <para> - As previously noted, the Rexx programmer does not need to be overly worried about taking to much time to return a - value from an event handler. In most very case there is plenty of time to process the event and return a value. + As previously noted, the Rexx programmer does not need to be overly worried about taking too much time to return a + value from an event handler. In most every case there is plenty of time to process the event and return a value. However, sometimes the programmer may want to, or need to, do some lengthy processing in the event handler. For these cases, the programmer needs to figure out how to return a value from the event handler and also do the needed processing. This is really a <emphasis role="italic">concurrency</emphasis> problem, not an event handling problem. @@ -499,7 +495,7 @@ index = self~newTab(idFrom)~selectedIndex + 1 dlg = tabContent[index] - if \ dlg~validate then return .false -- Tab will not be changed + if \ dlg~allowChange then return .false -- Tab will not be changed reply .true -- Tab is changed for the user. @@ -521,7 +517,7 @@ index = self~newTab(idFrom)~selectedIndex + 1 dlg = tabContent[index] - if dlg~validate then do + if dlg~allowChange then do dp = .DataProcesser~new dp~start("processDlgData", dlg) return .true @@ -534,8 +530,51 @@ </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End Coding Event Handler Examples section --> + +<section id="sctCommonWillReply"><title>Common <emphasis role="italic">willReply</emphasis> argument</title> +<indexterm><primary>Common willReply argument</primary></indexterm> + +<para> + It is the intent that every event connection method have an optional <emphasis role="italic">willReply</emphasis> argument + to give the programmer some control of how the interpreter invokes the event handler. For each event connection method, 3 + values are accepted for the <emphasis role="italic">willReply</emphasis> argument: +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">.true</emphasis></term> + <listitem> + <para> + When <emphasis role="italic">willReply</emphasis> is true, the interpreter waits for the return value from the event + handler and enforces that the method has returned a value. That is, the event handling method must return some value. + That value is returned to the operating system. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">.false</emphasis></term> + <listitem> + <para> + When <emphasis role="italic">willReply</emphasis> is false, the interpreter immediately returns 0 to the operating + system. It then invokes the event handling method to run concurrently as a separate activity. The return from the event + handling method, if any, is ignored. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">sync</emphasis></term> + <listitem> + <para> + When <emphasis role="italic">willReply</emphasis> is the keyword <emphasis role="italic">sync</emphasis>, the interpreter + waits for the return from the event handler, but it discards the value returned. It does not enforce that a value is + actually returned. + </para> + </listitem></varlistentry> +</variablelist> +<para> + The default value if the argument is omitted varies depending on the event connection method. In general, the default for + event connections that existed prior to ooDialog 4.2.0 is false and for event connections that were added in ooDialog 4.2.0 + and afterwards is true. +</para> + +</section> <!-- End Common willReply argument section --> + <section id="sctMethodsEventNotification"><title>Method Table</title> <para> The following table list the methods of the <computeroutput>EventNotification</computeroutput> class: @@ -7834,7 +7873,7 @@ <varlistentry><term>event [required]</term> <listitem> <para> - A single keyword indicating which event is to be connected. The event keywords are: + A single keyword indicating which event is to be connected. Case is not significant. The event keywords are: <variablelist> <varlistentry><term>KEYDOWN</term> <listitem> @@ -7894,16 +7933,24 @@ <para> The return codes are: <variablelist> - <varlistentry><term>0</term> - <listitem><para>No error detected. - </para></listitem></varlistentry> - <varlistentry><term>-1</term> - <listitem><para>The resource ID could not be resolved or the event argument is - incorrect. - </para></listitem></varlistentry> - <varlistentry><term>1</term> - <listitem><para>The messages was not connected correctly. - </para></listitem></varlistentry> + <varlistentry><term>0</term> + <listitem> + <para> + No error detected. + </para> + </listitem></varlistentry> + <varlistentry><term>-1</term> + <listitem> + <para> + The resource ID could not be resolved or the event argument is incorrect. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + The messages was not connected correctly. + </para> + </listitem></varlistentry> </variablelist> </para> </listitem></varlistentry> @@ -8026,6 +8073,91 @@ </listitem></varlistentry> </variablelist> + +<section id="evtTabKEYDOWN" xreflabel="KEYDOWN"><title>KeyDown Event Handler</title> +<indexterm><primary>Tab class</primary><secondary>events</secondary><tertiary>KEYDOWN</tertiary></indexterm> +<para> + The event handler for the key down event is invoked when the user types a key when the tab control has the focus. +</para> +<para> + The <link linkend="sctCommonWillReply">willReply</link> argument in the <xref linkend="mthConnectTabEvent"/> method + determines the event handler needs to respond to the notification. +</para> + +<programlisting> +<![CDATA[ +::method onKeyDown unguarded + use arg id, vKey, tabControl + + return 0 +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method recieves 3 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The numeric resource ID of the tab control sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>vKey</term> + <listitem> + <para> + The virtual key code of the key typed. The <xref linkend="clsVK"/> class can be used to decode this value. + </para> + </listitem></varlistentry> + <varlistentry><term>arg2</term> + <listitem> + <para> + The Rexx <xref linkend="clsTab"/> object representing the underlying tab control that sent the notification. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The operating system ignores the return from this notification so 0 makes a good return value. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example lets the user navigate through the tabs by typing N for next tab, P for previous tab, HOME for the + first tab and END for the last tab: + +<programlisting> +<![CDATA[ +::method onKeyDown unguarded + use arg id, vKey, tabControl + + lastTab = tabControl~items + + select + when vKey == .VK~N then self~onNext + when vKey == .VK~P then self~onPrevious + when vKey == .VK~home then self~goTo(tabControl, 0) + when vKey == .VK~end then self~goTo(tabControl, lastTab) + otherwise nop -- ignore all other keys + end + -- End select + + return 0 + + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End KeyDown Event Handler --> </section> <section id="mthConnectToolBarEvent" xreflabel="connectToolBarEvent"><title>connectToolBarEvent</title> |
From: <mie...@us...> - 2013-12-29 23:58:52
|
Revision: 9771 http://sourceforge.net/p/oorexx/code-0/9771 Author: miesfeld Date: 2013-12-29 23:58:46 +0000 (Sun, 29 Dec 2013) Log Message: ----------- [feature-requests:#575] Send the Rexx Tab object to tab control event handlers [feature-requests:#574] Event connections should all have a 'willReply' argument Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-29 22:26:11 UTC (rev 9770) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-29 23:58:46 UTC (rev 9771) @@ -7875,19 +7875,19 @@ <para> A single keyword indicating which event is to be connected. Case is not significant. The event keywords are: <variablelist> - <varlistentry><term>KEYDOWN</term> + <varlistentry><term><xref linkend="evtTabKEYDOWN"/></term> <listitem> <para> The notification is sent when a key has been pressed while the tab control has the focus. </para> </listitem></varlistentry> - <varlistentry><term>SELCHANGE</term> + <varlistentry><term><xref linkend="evtTabSELCHANGE"/></term> <listitem> <para> A new tab has been selected in the tab control. This method is called after the selection has changed. </para> </listitem></varlistentry> - <varlistentry><term>SELCHANGING</term> + <varlistentry><term><xref linkend="evtTabSELCHANGING"/></term> <listitem> <para> A new tab has been selected in the tab control. This method is called before the selection is changed. The @@ -7918,11 +7918,9 @@ <varlistentry><term>willReply [optional]</term> <listitem> <para> - The <emphasis role="italic">willReply</emphasis> argument controls whether the interpreter - <link linkend="sctCodingEventHandlers">waits</link> for the reply from the event handler. The default is - <computeroutput>.false</computeroutput>, the interpreter will not wait for the reply. If <emphasis - role="italic">willReply</emphasis> is <computeroutput>.true</computeroutput>, the interpreter waits until the - event handling method returns a value. + The <link linkend="sctCommonWillReply">willReply</link> argument controls how the interpreter invokes the event + handler for the connected evetn. The default if <emphasis role="italic">willReply</emphasis> is omitted is + <computeroutput>.false</computeroutput>. </para> </listitem></varlistentry> </variablelist> @@ -7961,33 +7959,6 @@ linkend="sctCodingEventHandlers">coding</link> event handlers for additional information on event handlers. </para> <para> - The event-handling method for the KEYDOWN event receives two arguments: info about the event, the control ID of the - tab control is in the low order word of this argument. The second argument is the virtual key code that was pressed. - Use the the <xref linkend="clsVK"/> class to determine which key was pressed. Example: - -<programlisting> -<![CDATA[ -::method onKeyDown unguarded - use arg info, vkey - - id = .DlgUtil~loWord(info) - - if vKey == .VK~NEXT | vKey == .VK~PREVIOUS then do - -- do something ... - end - else if vKey == .VK~HOME | vKey == .VK~END then do - -- do something else ... - end - - -- Other keys are ignored - - return 0 - -]]> -</programlisting> - - </para> - <para> The event-handling method for the SELCHANGE event receives two arguments: info about the event, the control ID of the tab control is in the low order word of this argument. The second argument is the window handle of the tab control. Example: @@ -8081,7 +8052,7 @@ </para> <para> The <link linkend="sctCommonWillReply">willReply</link> argument in the <xref linkend="mthConnectTabEvent"/> method - determines the event handler needs to respond to the notification. + determines how the event handler needs to respond to the notification. </para> <programlisting> @@ -8156,10 +8127,184 @@ </para> </listitem></varlistentry> </variablelist> - </section> <!-- End KeyDown Event Handler --> -</section> + +<section id="evtTabSELCHANGE" xreflabel="SELCHANGE"><title>SelChange Event Handler</title> +<indexterm><primary>Tab class</primary><secondary>events</secondary><tertiary>SELCHANGE</tertiary></indexterm> +<para> + The event handler for the SELCHANGE event is invoked when the currently selected tab of the control has changed. Note that + the notification is sent after the change has happened. +</para> +<para> + The <link linkend="sctCommonWillReply">willReply</link> argument in the <xref linkend="mthConnectTabEvent"/> method + determines how the event handler needs to respond to the notification. +</para> + +<programlisting> +<![CDATA[ +::method onSelChange unguarded + use arg id, hwndFrom, tabControl + + return 0 +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method recieves 3 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The numeric resource ID of the tab control sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hwndFrom</term> + <listitem> + <para> + The window handle of the tab control sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>tabControl</term> + <listitem> + <para> + The Rexx <xref linkend="clsTab"/> object representing the underlying tab control that sent the notification. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The operating system ignores the return from this notification so 0 makes a good return value. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example comes from a program that sometimes allows hexidecimal numbers to be used and at other times does + not. When the user changes the tab to the one with index 3, and if hexidecimal numbers are currently allowed, the + hexidecimal entry field is enabled, otherwise it is disabled: +<programlisting> +<![CDATA[ +::method onSelChange unguarded + use arg id, hwndFrom, tabControl + + edit = self~newEdit(IDC_EDIT_HEX) + + if tabControl~selectedIndex == 3 & self~allowHexidecimal then edit~enable + else edit~disable + + return 0 +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End SelChange Event Handler --> + + +<section id="evtTabSELCHANGING" xreflabel="SELCHANGING"><title>SelChanging Event Handler</title> +<indexterm><primary>Tab class</primary><secondary>events</secondary><tertiary>SELCHANGING</tertiary></indexterm> +<para> + The event handler for the SELCHANGING event is invoked when the user has selected a new tab. The notification is sent + before the change has been made. +</para> +<para> + The <link linkend="sctCommonWillReply">willReply</link> argument in the <xref linkend="mthConnectTabEvent"/> method + determines how the event handler needs to respond to the notification. +</para> + +<programlisting> +<![CDATA[ +::method onSelChanging unguarded + use arg id, hwndFrom, tabControl + + return .true +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method recieves 3 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The numeric resource ID of the tab control sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>hwndFrom</term> + <listitem> + <para> + The window handle of the tab control sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>tabControl</term> + <listitem> + <para> + The Rexx <xref linkend="clsTab"/> object representing the underlying tab control that sent the notification. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + When the <emphasis role="italic">willReply</emphasis> argument was set to true in the connect tab event method, the event + handler must return true or false. A return of true allows the tab to be changed, a return of false prevents the tab from + changing. + </para> + <para> + When the <emphasis role="italic">willReply</emphasis> argument was set to false or SYNC in the connect tab event method, + the ooDialog framwork replies to the operating system allowing the the tab to change. The return from the event handler + is ignored, but returning 0 is best practice. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example validates the data entered on a page of the tab control when the user goes to switch pages. If + invalid data was entered on the current page of the tab control, the user is prevented from switching to a different tab + until she enters valid data. + + A message dialog might be put saying something like: <emphasis role="italic">Your work telephone number is required. + Please enter a valid telephone number before changing to a new page.</emphasis> +<programlisting> +<![CDATA[ +::method initDialog + + self~connectTabEvent(IDC_TAB, "SELCHANGING", .true) + +::method onSelChanging unguarded + use arg id, hwndFrom, tabControl + + currentTab = tabControl~selectedIndex + if \ self~validateTab(currentTab) then do + -- The programmer should put up a message explaining + -- why the page of the tab is not changing ... + return .false + end + + return .true +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End SelChanging Event Handler --> + +</section> <!-- End connectTabEvent() --> + <section id="mthConnectToolBarEvent" xreflabel="connectToolBarEvent"><title>connectToolBarEvent</title> <indexterm><primary>connectToolBarEvent</primary></indexterm> <indexterm><primary>dialog object</primary><secondary>connectToolBarEvent</secondary></indexterm> |
From: <mie...@us...> - 2013-12-30 00:10:44
|
Revision: 9772 http://sourceforge.net/p/oorexx/code-0/9772 Author: miesfeld Date: 2013-12-30 00:10:42 +0000 (Mon, 30 Dec 2013) Log Message: ----------- ooDialog docs - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-29 23:58:46 UTC (rev 9771) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-30 00:10:42 UTC (rev 9772) @@ -176,7 +176,7 @@ </section> -<section id="sctCoding Event Handler Examples"><title>Coding Event Handler Examples</title> +<section id="sctCodingEventHandlerExamples"><title>Coding Event Handler Examples</title> <indexterm><primary>Coding Event Handler Examples</primary></indexterm> <para> The following code snippets and examples expand on the discussion of how to code event handling methods. |
From: <mie...@us...> - 2013-12-30 00:29:02
|
Revision: 9773 http://sourceforge.net/p/oorexx/code-0/9773 Author: miesfeld Date: 2013-12-30 00:28:57 +0000 (Mon, 30 Dec 2013) Log Message: ----------- ooDialog docs - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-30 00:10:42 UTC (rev 9772) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-30 00:28:57 UTC (rev 9773) @@ -7958,73 +7958,6 @@ See the sections on <link linkend="sctConnectingEventHandlers">connecting</link> and <link linkend="sctCodingEventHandlers">coding</link> event handlers for additional information on event handlers. </para> - <para> - The event-handling method for the SELCHANGE event receives two arguments: info about the event, the control ID of - the tab control is in the low order word of this argument. The second argument is the window handle of the tab - control. Example: - -<programlisting> -<![CDATA[ -::method onSelChange unguarded - use arg info, hwndFrom - - id = .DlgUtil~loWord(info) - ... - - return 0 - -]]> -</programlisting> - - </para> - <para> - The event-handling method for the SELCHANGING event also receives two arguments. The arguments differ slightly - depending on the value of <emphasis role="italic">willReply</emphasis>. - </para> - <para> - If <emphasis role="italic">willReply</emphasis> is <computeroutput>.false</computeroutput>, the first argument is - info about the event, the control ID of the tab control is in the low order word of this argument. The second - argument is the window handle of the tab control. If <emphasis role="italic">willReply</emphasis> is - <computeroutput>.true</computeroutput>, the first argument is simply the control ID of the tab. The second argument - is the window handle of the tab control. Examples - -<programlisting> -<![CDATA[ - -::method initDialog - - self~connectTabEvent(IDC_TAB, "SELCHANGING") - -::method onSelChanging unguarded - use arg info, hwndFrom - - id = .DlgUtil~loWord(info) - ... - - return 0 - -/* This example allows the programmer to cancel the pending tab change. */ - -::method initDialog - - self~connectTabEvent(IDC_TAB, "SELCHANGING", .true) - -::method onSelChanging unguarded - use arg idFrom, hwndFrom - - currentTab = self~newTab(IDC_TAB)~selectedIndex - if \ self~validateTab(currentTab) then do - -- The programmer should put up a message explaining - -- why the page of the tab is not changing ... - return .false - end - - return .true - -]]> -</programlisting> - - </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> |
From: <mie...@us...> - 2013-12-31 03:06:15
|
Revision: 9781 http://sourceforge.net/p/oorexx/code-0/9781 Author: miesfeld Date: 2013-12-31 03:06:12 +0000 (Tue, 31 Dec 2013) Log Message: ----------- ooDialog doc, fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-31 03:04:36 UTC (rev 9780) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2013-12-31 03:06:12 UTC (rev 9781) @@ -7964,8 +7964,8 @@ </para> <para> The <link linkend="sctCommonWillReply">willReply</link> argument in the method connecting the scroll event, <xref - linkend="mthConnectScrolBarEvent"/>, <xref linkend="mthConnectAllSBEvents"/>, etc., determines how the event handler needs - to respond to the notification. + linkend="mthConnectScrollBarEvent"/>, <xref linkend="mthConnectAllSBEvents"/>, etc., determines how the event handler + needs to respond to the notification. </para> <programlisting> |
From: <mie...@us...> - 2014-01-04 17:47:03
|
Revision: 9799 http://sourceforge.net/p/oorexx/code-0/9799 Author: miesfeld Date: 2014-01-04 17:47:00 +0000 (Sat, 04 Jan 2014) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 17:38:20 UTC (rev 9798) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 17:47:00 UTC (rev 9799) @@ -8145,7 +8145,7 @@ </section> -<section id="sctConnecting Scroll Bar Events"><title>Connecting Scroll Bar Events</title> +<section id="sctConnectingScrollBarEvents"><title>Connecting Scroll Bar Events</title> <indexterm><primary>Connecting Scroll Bar Events</primary></indexterm> <para> |
From: <mie...@us...> - 2014-01-04 23:24:42
|
Revision: 9801 http://sourceforge.net/p/oorexx/code-0/9801 Author: miesfeld Date: 2014-01-04 23:24:39 +0000 (Sat, 04 Jan 2014) Log Message: ----------- [feature-requests:#574] Event connections should all have a 'willReply' argument [feature-requests:#579] Send Rexx dialog control object to event handling methods. Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 19:17:03 UTC (rev 9800) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 23:24:39 UTC (rev 9801) @@ -2848,21 +2848,21 @@ <para> Sent by a date and time picker (DTP) control when the user closes the drop-down month calendar. The month calendar is closed when the user chooses a date from the month calendar or clicks the drop-down arrow while - the calendar is open. The return value from the event handler is ignored for this event. + the calendar is open. The return value from the event handler is ignored by the operating system for this event. </para> </listitem></varlistentry> <varlistentry><term>DATETIMECHANGE</term> <listitem> <para> Sent by a date and time picker (DTP) control whenever a change occurs. The return value from the event - handler is ignored for this event. + handler is ignored by the operating system for this event. </para> </listitem></varlistentry> <varlistentry><term>DROPDOWN</term> <listitem> <para> Sent by a date and time picker (DTP) control when the user activates the drop-down month calendar. The return - value from the event handler is ignored for this event. + value from the event handler is ignored by the operating system for this event. </para> </listitem></varlistentry> <varlistentry><term>FORMAT</term> @@ -2903,14 +2903,15 @@ <listitem> <para> Notifies a date and time picker control's parent window, (which is the dialog window,) that the control has - lost the input focus. The return value from the event handler is ignored for this event. + lost the input focus. The return value from the event handler is ignored by the operating system for this event. </para> </listitem></varlistentry> <varlistentry><term>SETFOCUS</term> <listitem> <para> Notifies a date and time picker control's parent window, (which is the dialog window,) that the control has - received the input focus. The return value from the event handler is ignored for this event. + received the input focus. The return value from the event handler is ignored by the operating system for this + event. </para> </listitem></varlistentry> </variablelist> @@ -3021,7 +3022,7 @@ <programlisting> <![CDATA[ ::method onCloseUp unguarded - use arg idFrom, hwndFrom + use arg idFrom, hwndFrom, code, dtpObj return 0 ]]> @@ -3031,7 +3032,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives 2 arguments: + The event handling method receives r arguments: </para> <variablelist> <varlistentry><term>idFrom</term> @@ -3047,6 +3048,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3066,8 +3079,8 @@ <![CDATA[ ::method onCloseUp unguarded - expose dtp lastChange - use arg id, hwnd + expose lastChange + use arg id, hwnd, code, dtp newDate = dtp~getDateTime if newDate \= lastChange then do @@ -3102,7 +3115,7 @@ <programlisting> <![CDATA[ ::method onDateTimeChange unguarded - use arg dateTime, valid, idFrom, hwndFrom + use arg dateTime, valid, idFrom, hwndFrom, code, dtpObj return 0 ]]> @@ -3112,7 +3125,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives 4 arguments: + The event handling method receives 6 arguments: </para> <variablelist> <varlistentry><term>dateTime</term> @@ -3146,6 +3159,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3232,7 +3257,7 @@ <programlisting> <![CDATA[ ::method onDropDown unguarded - use arg idFrom, hwndFrom + use arg idFrom, hwndFrom, code, dtpObj return 0 ]]> @@ -3242,7 +3267,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The drop down event handler receives 2 arguments: + The drop down event handler receives 4 arguments: </para> <variablelist> <varlistentry><term>idFrom</term> @@ -3258,6 +3283,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3276,11 +3313,10 @@ Rexx month calendar object is no longer valid. </para> <para> - In Windows Vista and later versions of Windows, the DTP control has the - <xref linkend="mthSetMonthCalStyle"/> method which can be used to set the month calendar's style - once and the DTP control will then use that style each time it creates the month calendar. Therefore, the technique - of setting the month calendar style during the drop down event handler is really only needed for Windows XP and - earlier. + In Windows Vista and later versions of Windows, the DTP control has the <xref linkend="mthSetMonthCalStyle"/> method + which can be used to set the month calendar's style once and the DTP control will then use that style each time it + creates the month calendar. Therefore, the technique of setting the month calendar style during the drop down event + handler is really only needed for Windows XP and earlier. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example</emphasis></term> @@ -3293,8 +3329,6 @@ <![CDATA[ ::method initDialog - expose dtp - dtp = self~newDateTimePicker(IDC_DTP_APPOINTMENT_TIME); if .OS~isAtLeastVista then do @@ -3306,8 +3340,7 @@ ... ::method onDropDown unguarded - expose dtp - use arg idFrom, hwndFrom + use arg idFrom, hwndFrom, code, dtp -- We know this is not Vista or later, othewise we would not -- have gotten the event notification. @@ -3339,7 +3372,7 @@ <programlisting> <![CDATA[ ::method onFormat unguarded - use arg field, dateTime, idFrom, hwndFrom + use arg field, dateTime, idFrom, hwndFrom, code, dtpObj return text ]]> @@ -3349,7 +3382,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives 4 arguments: + The event handling method receives 6 arguments: </para> <variablelist> <varlistentry><term>field</term> @@ -3378,6 +3411,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3446,7 +3491,7 @@ <programlisting> <![CDATA[ ::method onFormatQuery unguarded - use arg field, size, id, hwnd + use arg field, size, id, hwnd, code, dtpObj return 0 ]]> @@ -3456,7 +3501,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives 4 arguments: + The event handling method receives 6 arguments: </para> <variablelist> <varlistentry><term>field</term> @@ -3485,6 +3530,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3510,8 +3567,8 @@ <![CDATA[ ::method onFormatQuery unguarded - expose dtp haveSizes xxSize xxxSize xxxxSize - use arg field, size, id, hwnd + expose haveSizes xxSize xxxSize xxxxSize + use arg field, size, id, hwnd, code, dtp if \ haveSizes then do xxSize = self~calcSize('XX') @@ -3555,7 +3612,7 @@ <programlisting> <![CDATA[ ::method onKeyDown unguarded - use arg field, dateTiem, vKey, idFrom, hwndFrom + use arg field, dateTiem, vKey, idFrom, hwndFrom, code, dtpObj return dateTime ]]> @@ -3565,7 +3622,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives xx arguments: + The event handling method receives 7 arguments: </para> <variablelist> <varlistentry><term>field</term> @@ -3601,6 +3658,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3641,7 +3710,7 @@ <![CDATA[ ::method onKeyDown unguarded - use arg field, dt, vKey, idFrom, hwndFrom + use arg field, dt, vKey, idFrom, hwndFrom, code, dtpObj select when field == 'XX' then do @@ -3684,7 +3753,7 @@ <programlisting> <![CDATA[ ::method onKillFocus unguarded - use arg idFrom, hwndFrom + use arg idFrom, hwndFrom, code, dtpObj return 0 ]]> @@ -3694,7 +3763,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The kill focus event handler receives 2 arguments: + The kill focus event handler receives 4 arguments: </para> <variablelist> <varlistentry><term>idFrom</term> @@ -3710,6 +3779,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3738,7 +3819,7 @@ <programlisting> <![CDATA[ ::method onSetFocus unguarded - use arg idFrom, hwndFrom + use arg idFrom, hwndFrom, code, dtpObj return 0 ]]> @@ -3748,7 +3829,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The set focus event handler receives 2 arguments: + The set focus event handler receives 4 arguments: </para> <variablelist> <varlistentry><term>idFrom</term> @@ -3764,6 +3845,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3790,7 +3883,7 @@ <programlisting> <![CDATA[ ::method onUserString unguarded - use arg dateTime, userStr, idFrom, hwndFrom + use arg dateTime, userStr, idFrom, hwndFrom, code, dtpObj return newDateTime ]]> @@ -3800,7 +3893,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method receives 4 arguments: + The event handling method receives 6 arguments: </para> <variablelist> <varlistentry><term>dateTime</term> @@ -3829,6 +3922,18 @@ The window handle of the date and time picker. </para> </listitem></varlistentry> + <varlistentry><term>code</term> + <listitem> + <para> + The date time picker event code the caused the event notification to be sent. + </para> + </listitem></varlistentry> + <varlistentry><term>dtpObj</term> + <listitem> + <para> + The Rexx date time picker object that represents the date time picker control that sent the notification. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -3876,7 +3981,7 @@ ::method onUserString unguarded expose resetting stInvalid - use arg dt, userStr, id, hwnd + use arg dt, userStr, id, hwnd, code, dtpObj stInvalid~setText('') @@ -3899,9 +4004,9 @@ </section> <!-- End UserString Event Handler --> - </section> <!-- End EventNotification::connectDateTimePickerEvent() --> + <section id="mthConnectDraw" xreflabel="connectDraw"><title>connectDraw</title> <indexterm><primary>connectDraw</primary></indexterm> <indexterm><primary>dialog object</primary><secondary>connectDraw</secondary></indexterm> @@ -3917,7 +4022,8 @@ <para> The <emphasis role="italic">connectDraw</emphasis> method connects the draw control event notification with a method in the Rexx dialog. This notification is sent to the underlying dialog by an owner-drawn button, combo box, list box, - or menu, when a visual aspect of the control or menu has changed. + static, or menu, when a visual aspect of the control or menu has changed. In addition, if a tab control or a list-view have + the owner draw fixed style, the also recieve the notifiction. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -3978,22 +4084,49 @@ <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The notification for the draw control is only sent to the above mentioned controls when they have the OWNERDRAW style. - The notification itself is to inform the application that it needs to draw the control at this time. Note that the - ooDialog framework is not well suited to drawing operations and it is unlikely that this notification is of much use - except in rare circumstances. + The notification for the draw control is only sent to the above mentioned controls when they have the OWNERDRAW or + OWNERDRAWFIXED styles. The notification itself is to inform the application that it needs to draw the control at this + time. Note that the ooDialog framework is not well suited to drawing operations and it is unlikely that this notification + is of much use except in rare circumstances. </para> <para> - The details for coding an event handler for the DRAW event are as follows: + See the sections on <link linkend="sctConnectingEventHandlers">connecting</link> and <link + linkend="sctCodingEventHandlers">coding</link> event handlers for additional information on event handlers. </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details:</emphasis></term> + <listitem> + <para> + Syntax errors are raised when incorrect usage is detected. + </para> + <para> + If the programmer does not provide a matching method in the Rexx dialog, a syntax condition will be raised if any + draw events happen. + </para> + <para> + In Windows itself, the dialog receives this event notification as a WM_DRAWITEM message. + </para> + </listitem></varlistentry> +</variablelist> + + +<section id="evtEventNotificationDRAW" xreflabel="DRAW"><title>Draw Event Handler</title> +<indexterm><primary>EventNotification class</primary><secondary>events</secondary><tertiary>DRAW</tertiary></indexterm> +<para> + The event handler for the Draw event is invoked when a button, combo box, list box, or menu, with the owner-draw style, + needs to be redrawn. +</para> +<para> + The <link linkend="sctCommonWillReply">willReply</link> argument in the <xref linkend="mthConnectDraw"/> method + determines how the event handler needs to respond to the notification. +</para> + <programlisting> <![CDATA[ -::method onDrawEvent unguarded - use arg id, pointer +::method onDraw unguarded + use arg id, pointer, cntrlObj - -- Do something - - return 0 + return zz ]]> </programlisting> @@ -4001,7 +4134,7 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 2 arguments: + The event handling method recieves xx arguments: </para> <variablelist> <varlistentry><term>id</term> @@ -4017,26 +4150,41 @@ access the data the pointer points to from the ooDialog program. </para> </listitem></varlistentry> + <varlistentry><term>cntrlObj</term> + <listitem> + <para> + The Rexx dialog control object that represents the control that needs to be drawn. If it is a menu item that needs to + be drawn, this may be the <computeroutput>.nil</computeroutput> object. <emphasis role="bold">Please Note:</emphasis> + In future versions of ooDialog this may be the Rexx menu object that contains the menu item needing to be drawn. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> -</variablelist> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details:</emphasis></term> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - Syntax errors are raised when incorrect usage is detected. + xx </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> <para> - If the programmer does not provide a matching method in the Rexx dialog, a syntax condition will be raised if any - draw events happen. + The following example ... + +<programlisting> +<![CDATA[ + + +]]> +</programlisting> </para> - <para> - In Windows itself, the dialog receives this event notification as a WM_DRAWITEM message. - </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End Draw Event Handler --> + +</section> <!-- End EventNotification::connectDraw() --> + <section id="mthConnectEditEvent" xreflabel="connectEditEvent"><title>connectEditEvent</title> <indexterm><primary>connectEditEvent</primary></indexterm> <programlisting> @@ -4302,6 +4450,166 @@ </section> <!-- End EventNotification::connectEditEvent() --> +<section id="mthConnectHelp" xreflabel="connectHelp"><title>connectHelp</title> +<indexterm><primary>connectHelp</primary></indexterm> +<indexterm><primary>dialog object</primary><secondary>connectHelp</secondary></indexterm> +<indexterm><primary>EventNotification class</primary><secondary>connectHelp</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--connectHelp(--+--------------+--)------------>< + +--methodName--+ +]]> +</programlisting> + +<para> + The <emphasis role="italic">connectHelp</emphasis> method connects the Windows Help event with a method in the dialog. The Windows Help + event occurs when the user presses the F1 key. (Only the Help events generated when the dialog is the active window + are connected.) +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The only argument is: + <variablelist> + <varlistentry><term>methodName [optional]</term> + <listitem> + <para> + The name of the method that to be invoked when the help event occurs. The name can not be the empty string. When + this argument is omitted the name defaults to <emphasis role="italic">onHelp</emphasis>. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + <variablelist> + <varlistentry><term>0</term> + <listitem> + <para> + No error. + </para> + </listitem></varlistentry> + <varlistentry><term>1</term> + <listitem> + <para> + An (internal) error prevented the message from being connected to a method. + </para> + </listitem></varlistentry> + </variablelist> + </para></listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Note that the Windows help event notification connected by this method is not the same as the help <emphasis + role="bold">command</emphasis> event notification <link linkend="sctStandardEventMethods">automatically</link> connected + when a dialog object is instantiated. + </para> + <para> + The method connected to the Help event will receive the following four arguments in the order listed: + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource ID of the dialog, dialog control, or menu item that had the focus when the F1 key was pressed. + </para> + </listitem></varlistentry> + <varlistentry><term>type</term> + <listitem> + <para> + Specifies if the ID in argument 1 was from a window (a dialog or dialog control) or from a menu item. This + argument will either be <computeroutput>WINDOW</computeroutput> or <computeroutput>MENU + </computeroutput>. + </para> + </listitem></varlistentry> + <varlistentry><term>mouseX</term> + <listitem> + <para> + The x coordinate of the mouse at the time the F1 key was pressed. This value is an absolute screen coordinate + (pixel) and note that the mouse will not necessarily be over the dialog. + </para> + </listitem></varlistentry> + <varlistentry><term>mouseY</term> + <listitem> + <para> + The y coordinate of the mouse at the time the F1 key was pressed. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details:</emphasis></term> + <listitem> + <para> + Syntax errors are raised when incorrect usage is detected. + </para> + <para> + If the programmer does not provide a matching method in the Rexx dialog, a syntax condition will be raised if any + help events happen. + </para> + <para> + In Windows itself, the dialog receives this notification as a WM_HELP message. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + +<programlisting> +<![CDATA[ + +::method init + self~init:super + ... + self~connectResize(onResize) + self~connectHelp(onHelp) + ... + +::method onHelp unguarded + use arg id, type, mouseX, mouseY + if type == "MENU" then w = 'Menu id' id; else w = 'Dialog id' id + say "Help request:" + say " " w + say " Mouse position x:" mouseX "y:" mouseY + + return 0 + +/* As the user presses the F1 key at various times when the dialog has the focus + * the output might be as follows: + */ + +Help request: + Dialog id 12 + Mouse position x: 420 y: 106 +Help request: + Menu id 60 + Mouse position x: 204 y: 93 +Help request: + Menu id 65 + Mouse position x: 203 y: 166 +Help request: + Dialog id 14 + Mouse position x: 218 y: 410 +Help request: + Dialog id 80 + Mouse position x: 387 y: 462 +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> +</section> + + +<section id="sctConnectingKeyPressEvents"><title>Connecting Key Press Events</title> +<indexterm><primary>Connecting Key Press Events</primary></indexterm> + +<para> + +</para> + <section id="mthConnectFKeyPressDialogObject" xreflabel="connectFKeyPress"><title>connectFKeyPress</title> <indexterm><primary>connectFKeyPress</primary><secondary>dialog object</secondary></indexterm> <indexterm><primary>EventNotification class</primary><secondary>connectFKeyPress</secondary></indexterm> @@ -4470,160 +4778,9 @@ </para> </listitem></varlistentry> </variablelist> -</section> -<section id="mthConnectHelp" xreflabel="connectHelp"><title>connectHelp</title> -<indexterm><primary>connectHelp</primary></indexterm> -<indexterm><primary>dialog object</primary><secondary>connectHelp</secondary></indexterm> -<indexterm><primary>EventNotification class</primary><secondary>connectHelp</secondary></indexterm> -<programlisting> -<![CDATA[ ->>--connectHelp(--+--------------+--)------------>< - +--methodName--+ -]]> -</programlisting> +</section> <!-- End EventNotification::connectFKeyPress() --> -<para> - The <emphasis role="italic">connectHelp</emphasis> method connects the Windows Help event with a method in the dialog. The Windows Help - event occurs when the user presses the F1 key. (Only the Help events generated when the dialog is the active window - are connected.) -</para> -<variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> - <listitem> - <para> - The only argument is: - <variablelist> - <varlistentry><term>methodName [optional]</term> - <listitem> - <para> - The name of the method that to be invoked when the help event occurs. The name can not be the empty string. When - this argument is omitted the name defaults to <emphasis role="italic">onHelp</emphasis>. - </para> - </listitem></varlistentry> - </variablelist> - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> - <listitem> - <para> - <variablelist> - <varlistentry><term>0</term> - <listitem> - <para> - No error. - </para> - </listitem></varlistentry> - <varlistentry><term>1</term> - <listitem> - <para> - An (internal) error prevented the message from being connected to a method. - </para> - </listitem></varlistentry> - </variablelist> - </para></listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - Note that the Windows help event notification connected by this method is not the same as the help <emphasis - role="bold">command</emphasis> event notification <link linkend="sctStandardEventMethods">automatically</link> connected - when a dialog object is instantiated. - </para> - <para> - The method connected to the Help event will receive the following four arguments in the order listed: - <variablelist> - <varlistentry><term>id</term> - <listitem> - <para> - The resource ID of the dialog, dialog control, or menu item that had the focus when the F1 key was pressed. - </para> - </listitem></varlistentry> - <varlistentry><term>type</term> - <listitem> - <para> - Specifies if the ID in argument 1 was from a window (a dialog or dialog control) or from a menu item. This - argument will either be <computeroutput>WINDOW</computeroutput> or <computeroutput>MENU - </computeroutput>. - </para> - </listitem></varlistentry> - <varlistentry><term>mouseX</term> - <listitem> - <para> - The x coordinate of the mouse at the time the F1 key was pressed. This value is an absolute screen coordinate - (pixel) and note that the mouse will not necessarily be over the dialog. - </para> - </listitem></varlistentry> - <varlistentry><term>mouseY</term> - <listitem> - <para> - The y coordinate of the mouse at the time the F1 key was pressed. - </para> - </listitem></varlistentry> - </variablelist> - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details:</emphasis></term> - <listitem> - <para> - Syntax errors are raised when incorrect usage is detected. - </para> - <para> - If the programmer does not provide a matching method in the Rexx dialog, a syntax condition will be raised if any - help events happen. - </para> - <para> - In Windows itself, the dialog receives this notification as a WM_HELP message. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - -<programlisting> -<![CDATA[ - -::method init - self~init:super - ... - self~connectResize(onResize) - self~connectHelp(onHelp) - ... - -::method onHelp unguarded - use arg id, type, mouseX, mouseY - if type == "MENU" then w = 'Menu id' id; else w = 'Dialog id' id - say "Help request:" - say " " w - say " Mouse position x:" mouseX "y:" mouseY - - return 0 - -/* As the user presses the F1 key at various times when the dialog has the focus - * the output might be as follows: - */ - -Help request: - Dialog id 12 - Mouse position x: 420 y: 106 -Help request: - Menu id 60 - Mouse position x: 204 y: 93 -Help request: - Menu id 65 - Mouse position x: 203 y: 166 -Help request: - Dialog id 14 - Mouse position x: 218 y: 410 -Help request: - Dialog id 80 - Mouse position x: 387 y: 462 -]]> -</programlisting> - </para> - </listitem></varlistentry> -</variablelist> -</section> - <section id="mthConnectKeyPressDialogObject" xreflabel="connectKeyPress"><title>connectKeyPress</title> <indexterm><primary>connectKeyPress</primary><secondary>dialog object</secondary></indexterm> <indexterm><primary>dialog object</primary><secondary>connectKeyPress</secondary></indexterm> @@ -4885,142 +5042,181 @@ <para> The ooDialog method connected to the key press event will receive the following five arguments in the order listed: <variablelist> - <varlistentry><term>keyCode</term> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry id="connectKeyPressExample"><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The following example is from a fictitious customer order system. As the user is filling out a customer order using + the customer order dialog, he has the F2 through F5 short cut keys available. F2 brings up a customer look up + dialog. F3 looks up info on the product number entered in an edit control. F4 resets the form by clearing all the + fields. F5 is used to print out the finished invoice. + +<programlisting> +<![CDATA[ +::method initDialog + + ... + + -- Capture F2 key presses, but not Ctrl-F2 or Alt-F2, etc.. + self~connectKeyPress(onF2, .VK~VK_F2, "NONE") + + -- Same idea for F3, F4, and F5. This uses the actual numeric value for the + -- keys without bothering to use the VK class to translate. + self~connectKeyPress(onF3, 114, "NONE") + self~connectKeyPress(onF4, 115, "NONE") + self~connectKeyPress(onF5, 116, "NONE") + + ... + +::method onF2 unguarded + self~showCustomerLookupDialog + return 0 + +::method onF3 unguarded + + prodNum = self~newEdit(IDC_EDIT_PRODUCT)~getText + if prodNum \== "" then self~showProductInfo(prodNum) + return 0 + +::method onF4 unguarded + self~resetAllFields + return 0 + +::method onF5 unguarded + self~printInvoice + return 0 + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End EventNotification::connectKeyPress() --> + +<section id="mthDisconnectKeyPressDialogObject" xreflabel="disconnectKeyPress"><title>disconnectKeyPress</title> +<indexterm><primary>disconnectKeyPress</primary><secondary>dialog object</secondary></indexterm> +<indexterm><primary>dialog object</primary><secondary>disconnectKeyPress</secondary></indexterm> +<indexterm><primary>EventNotification class</primary><secondary>disconnectFKeyPress</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--disconnectKeyPress(--+--------------+--)----->< + +--methodName--+ + +]]> +</programlisting> + +<para> + The <emphasis role="italic">disconnectKeyPress</emphasis> method disconnects a key press event from a method that was + previously connected using <xref linkend="mthConnectKeyPressDialogObject"/>, or + <xref linkend="mthConnectFKeyPressDialogObject"/>. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The single argument is: + <variablelist> + <varlistentry><term>methodName [optional]</term> <listitem> <para> - The numeric code of the key pressed. + If <emphasis role="italic">methodName</emphasis> is specified, only the key press events connected to that + method are disconnected. If the argument is omitted, then all key press events for the dialog will be + disconnected. </para> </listitem></varlistentry> - <varlistentry><term>shift</term> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + The possible return values are: + <variablelist> + <varlistentry><term>0</term> <listitem> <para> - A boolean (true or false) that denotes whether a shift key was down or up at the time of the key press. It will - be true if a shift key was down and false if the shift key was not down. + Success. </para> </listitem></varlistentry> - <varlistentry><term>control</term> + <varlistentry><term>-2</term> <listitem> <para> - True if a control key was down at the time of the key press, false if it was not. + While trying to disconnect the method, the underlying mechanism in the Windows API that is used to capture key + events had an error. This is unlikely to happen. </para> </listitem></varlistentry> - <varlistentry><term>alt</term> + <varlistentry><term>-7</term> <listitem> <para> - True if an alt key was down at the time of the key press, false if it was not. + Either the <emphasis role="italic">methodName</emphasis> method is already disconnected, or there are no methods + connected at all. </para> </listitem></varlistentry> - <varlistentry><term>extraInfo</term> - <listitem> - <para> - This argument is a string containing keywords. It supplies extra information about the keyboard state at the - time of a key press event. The string will contain some combination of these keywords - <variablelist> - <varlistentry><term>numOn</term> - <listitem> - <para> - Num Lock was on at the time of the key press event. - </para> - </listitem></varlistentry> - <varlistentry><term>numOff</term> - <listitem> - <para> - Num Lock was off. - </para> - </listitem></varlistentry> - <varlistentry><term>capsOn</term> - <listitem> - <para> - Caps Lock was on at the time of the key press event. - </para> - </listitem></varlistentry> - <varlistentry><term>capsOff</term> - <listitem> - <para> - Caps Lock was off. - </para> - </listitem></varlistentry> - <varlistentry><term>scrollOn</term> - <listitem> - <para> - Scroll Lock was on at the time of the key press event. - </para> - </listitem></varlistentry> - <varlistentry><term>scrollOff</term> - <listitem> - <para> - Scroll Lock was off. - </para> - </listitem></varlistentry> - <varlistentry><term>lShift</term> - <listitem> - <para> - The left shift key was down at the time of the key press event. - </para> - </listitem></varlistentry> - <varlistentry><term>rShift</term> - <listitem> - <para> - The right shift key was down. - </para> - </listitem></varlistentry> - <varlistentry><term>lControl</term> - <listitem> - <para> - The left control key was down at the time of the key press event. - </para> - </listitem></varlistentry> - <varlistentry><term>rControl</term> - <listitem> - <para> - The right control key was down. - </para> - </listitem></varlistentry> - <varlistentry><term>lAlt</term> - <listitem> - <para> - The left alt key was down at the time of the key press event. - </para> - </listitem></varlistentry> - <varlistentry><term>rAlt</term> - <listitem> - <para> - The right alt key was down. - </para> - </listitem></varlistentry> - </variablelist> - </para> - </listitem></varlistentry> </variablelist> </para> </listitem></varlistentry> - <varlistentry id="connectKeyPressExample"><term><emphasis role="bold">Example:</emphasis></term> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - The following example is from a fictitious customer order system. As the user is filling out a customer order using - the customer order dialog, he has the F2 through F5 short cut keys available. F2 brings up a customer look up - dialog. F3 looks up info on the product number entered in an edit control. F4 resets the form by clearing all the - fields. F5 is used to print out the finished invoice. + The dialog control object also has a <xref linkend="mthDisconnectKeyPressDialogControlObject"/> + method. The method of the dialog object (this method) can only disconnect key press events that were set with the + dialog object's versions of <xref linkend="mthConnectKeyPressDialogObject"/> and + <xref linkend="mthConnectFKeyPressDialogObject"/> methods. This method can not disconnect key press + events that were set with the dialog control object's versions of + <xref linkend="mthConnectKeyPressDialogControlObject"/> and + <xref linkend="mthConnectFKeyPressDialogControlObject"/> methods. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + Raises syntax errors when some incorrect usage is detected. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The following example is a variation on the <link linkend="connectKeyPressExample">example</link> shown for the + <xref linkend="mthConnectKeyPressDialogObject"/> method. It builds on the fictitious customer + order system. The F7 key saves the completed invoice into the system and enters a different phase of the companies + business process. At this point (for whatever fictitious business reason) the fields can no longer be cleared and + the user is not allowed to look up customer or product information. But, the user may still need to print the + invoice. To prevent the accidental press of the hot keys causing the wrong action, those key presses are + disconnected. + </para> + <para> + To demonstrate how key press connections can be added and removed through out the life time of the dialog, this + example adds the F9 hot key. F9 starts a new order entry cycle and re-connects the hot keys used during the + creation of a customer invoice. When the user then saves the next completed invoice, key press connections are + removed, when she starts a new invoice key press connections are restored. This cycle could continue though out the + day without the user ever closing the main dialog. <programlisting> <![CDATA[ + ::method initDialog ... -- Capture F2 key presses, but not Ctrl-F2 or Alt-F2, etc.. - self~connectKeyPress(onF2, .VK~VK_F2, "NONE") + self~connectKeyPress(onF2, .VK~F2, "NONE") - -- Same idea for F3, F4, and F5. This uses the actual numeric value for the - -- keys without bothering to use the VK class to translate. + -- Same idea for F3, F4, F5, and F7. This uses the actual numeric value for + -- the keys without bothering to use the .VK class to translate. self~connectKeyPress(onF3, 114, "NONE") self~connectKeyPress(onF4, 115, "NONE") self~connectKeyPress(onF5, 116, "NONE") + self~connectKeyPress(onF7, 118, "NONE") + self~connectKeyPress(onF9, 120, "NONE") ... ::method onF2 unguarded self~showCustomerLookupDialog + return 0 ::method onF3 unguarded @@ -5029,22 +5225,304 @@ if prodNum \== "" then self~showProductInfo(prodNum) return 0 -::method onF4 unguarded +::method onF4 self~resetAllFields return 0 -::method onF5 unguarded +::method onF5 self~printInvoice return 0 +::method onF7 + + self~saveToDataBase + self~disconnectKeyPress(onF2) + self~disconnectKeyPress(onF3) + self~disconnectKeyPress(onF4) + return 0 + +::method onF9 + + self~resetAllFields + self~connectKeyPress(onF2, 112, "NONE") + self~connectKeyPress(onF3, 114, "NONE") + self~connectKeyPress(onF4, 115, "NONE") + return 0 + ]]> </programlisting> </para> </listitem></varlistentry> </variablelist> -</section> +</section> <!-- End EventNotification::disconnectKeyPress() --> +<section id="mthHasKeyPressConnectionDialogObject" xreflabel="hasKeyPressConnection"><title>hasKeyPressConnection</title> +<indexterm><primary>hasKeyPressConnection</primary><secondary>dialog object</secondary></indexterm> +<indexterm><primary>dialog object</primary><secondary>hasKeyPressConnection</secondary></indexterm> +<indexterm><primary>EventNotification class</primary><secondary>hasKeyPressConnection</secondary></indexterm> +<programlisting> +<![CDATA[ +>>--hasKeyPressConnection(--+--------------+--)-->< + +--methodName--+ + +]]> +</programlisting> + +<para> + This method is used to query if a connection to a key press event already exists. +</para> +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para>The single optional argument is: + <variablelist> + <varlistentry><term>methodName [optional]</term> + <listitem> + <para> + Query if any key press events are connected to the specified method. If this argument is omitted, the query is if + any key press events are connected to <emphasis role="bold">any</emphasis> methods. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> + <listitem> + <para> + Returns <computeroutput>.true</computeroutput> if the method is connected to a key press event or + <computeroutput>.false</computeroutput> otherwise. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Details</emphasis></term> + <listitem> + <para> + The dialog control object also has a + <xref linkend="mthHasKeyPressConnectionDialogControlObject"/> method. The method of the dialog + object (this method) can only check for connections that were set with the dialog object's versions of + <xref linkend="mthConnectKeyPressDialogObject"/> and + <xref linkend="mthConnectFKeyPressDialogObject"/> methods. This method can not check for connections + that were set with the dialog control object's versions of + <xref linkend="mthConnectKeyPressDialogControlObject"/> and + <xref linkend="mthConnectFKeyPressDialogControlObject"/> methods. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example:</emphasis></term> + <listitem> + <para> + The following example could come from a dialog where the user has the option to use hot keys or not. When the + reset button is pushed the state of the dialog fields are reset. The hot keys enabled check box is set to reflect + whether hot keys are currently enabled or not. + +<programlisting> + +<![CDATA[ + +::method defineDialog + + ... + self~createCheckBox(IDC_CHECK_FKEYSENABlED, 30, 60, , , , "Hot Keys Enabled") + ... + self~createPushButton(IDC_PB_RESET, 60, 135, 45, 15, , "Reset", onReset) + ... + +::method onReset unguarded + + ... + if self~hasKeyPressConnection then + self~newCheckBox(IDC_CHECK_FKEYSENABlED)~check + else + self~newCheckBox(IDC_CHECK_FKEYSENABlED)~uncheck + ... + return 0 + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End EventNotification::hasKeyPressConnection() --> + +<section id="evtEventNotificationKEYPRESS" xreflabel="KEYPRESS"><title>KeyPress Event Handler</title> +<indexterm><primary>EventNotification class</primary><secondary>events</secondary><tertiary>KEYPRESS</tertiary></indexterm> +<para> + The event handler for the key press event is invoked when a key connected through the <xref + linkend="mthConnectKeyPressDialogObject"/> or the <xref linkend="mthConnectFKeyPressDialogObject"/> method is typed when the + dialog has the focus. +</para> +<para> + The interpreter replies immediately to the operating system when the key is pressed. Tthe event handler is then invoked + concurrently as a separate activity and the interpreter does not wait for the return. The value returned from the event + handler is ignored and the programmer need not return a value from the handerl. However, good practice would be to always + return a value from an event handler. +</para> + +<programlisting> +<![CDATA[ +::method onKeyPress unguarded + use arg keyCode, shift, control, alt, extraInfo + + return 0 +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method recieves 5 arguments: + </para> + <variablelist> + <varlistentry><term>keyCode</term> + <listitem> + <para> + The numeric code of the key pressed. + </para> + </listitem></varlistentry> + <varlistentry><term>shift</term> + <listitem> + <para> + A boolean (true or false) that denotes whether a shift key was down or up at the time of the key press. It will + be true if a shift key was down and false if the shift key was not down. + </para> + </listitem></varlistentry> + <varlistentry><term>control</term> + <listitem> + <para> + True if a control key was down at the time of the key press, false if it was not. + </para> + </listitem></varlistentry> + <varlistentry><term>alt</term> + <listitem> + <para> + True if an alt key was down at the time of the key press, false if it was not. + </para> + </listitem></varlistentry> + <varlistentry><term>extraInfo</term> + <listitem> + <para> + This argument is a string containing keywords. It supplies extra information about the keyboard state at the + time of a key press event. The string will contain some combination of these keywords + <variablelist> + <varlistentry><term>numOn</term> + <listitem> + <para> + Num Lock was on at the time of the key press event. + </para> + </listitem></varlistentry> + <varlistentry><term>numOff</term> + <listitem> + <para> + Num Lock was off. + </para> + </listitem></varlistentry> + <varlistentry><term>capsOn</term> + <listitem> + <para> + Caps Lock was on at the time of the key press event. + </para> + </listitem></varlistentry> + <varlistentry><term>capsOff</term> + <listitem> + <para> + Caps Lock was off. + </para> + </listitem></varlistentry> + <varlistentry><term>scrollOn</term> + <listitem> + <para> + Scroll Lock was on at the time of the key press event. + </para> + </listitem></varlistentry> + <varlistentry><term>scrollOff</term> + <listitem> + <para> + Scroll Lock was off. + </para> + </listitem></varlistentry> + <varlistentry><term>lShift</term> + <listitem> + <para> + The left shift key was down at the time of the key press event. + </para> + </listitem></varlistentry> + <varlistentry><term>rShift</term> + <listitem> + <para> + The right shift key was down. + </para> + </listitem></varlistentry> + <varlistentry><term>lControl</term> + <listitem> + <para> + The left control key was down at the time of the key press event. + </para> + </listitem></varlistentry> + <varlistentry><term>rControl</term> + <listitem> + <para> + The right control key was down. + </para> + </listitem></varlistentry> + <varlistentry><term>lAlt</term> + <listitem> + <para> + The left alt key was down at the time of the key press event. + </para> + </listitem></varlistentry> + <varlistentry><term>rAlt</term> + <listitem> + <para> + The right alt key was down. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The return value from the event handler is discarded. Zero would make a good value to return. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example comes from an application where the user can type F3 to close the current dialog and Alt-F3 to + close the entire application. The event handler checks that only the Alt key is down when the F3 key is pressed and + closes the application if that is true. Otherwise, if only the F3 key is pressed, then the handler closes the dialog: + +<programlisting> +<![CDATA[ +::method initDialog + self~connectKeyPress(onQuitKey, .VK~F3) + +::method onQuitKey + use arg key, shift, control, alt, info + say 'Key press:' key 'shift?' shift 'control?' control || - + ' alt?' alt 'extra info:' info + + if shift then return + if control then return + if alt then return self~quitApplication + + -- Only F3 is pressed, close this dialog + return self~cancel:super + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End KeyPress Event Handler --> + +</section> <!-- End Connecting Key Press Events section --> + + <section id="mthConnectListBoxEvent" xreflabel="connectListBoxEvent"><title>connectListBoxEvent</title> <indexterm><primary>connectListBoxEvent</primary></indexterm> <programlisting> @@ -8795,11 +9273,9 @@ <varlistentry><term>willReply [optional]</term> <listitem> <para> - The default behavior is for the interpreter to wait in the window <xref linkend="ovvWindowMessages"/> processing loop - for the return from the event handler, (the default for <emphasis role="italic">willReply</emphasis> is - <computeroutput>.true</computeroutput>). However, the operating system ignores the return from this event notification. - Specifying <computeroutput>.false</computeroutput> changes the default behavior so that the interpreter does not wait - for the return from the event handling method. + The <link linkend="sctCommonWillReply">willReply</link> argument controls how the interpreter invokes the event + handler for the connected event. The default if <emphasis role="italic">willReply</emphasis> is omitted is + <computeroutput>.true</computeroutput>. </para> </listitem></varlistentry> </variablelist> @@ -12672,252 +13148,4 @@ </para> </section> -<section id="mthDisconnectKeyPressDialogObject" xreflabel="disconnectKeyPress"><title>disconnectKeyPress</title> -<indexterm><primary>disconnectKeyPress</primary><secondary>dialog object</secondary></indexterm> -<indexterm><primary>dialog object</primary><secondary>disconnectKeyPress</secondary></indexterm> -<indexterm><primary>EventNotification class</primary><secondary>disconnectFKeyPress</secondary></indexterm> -<programlisting> -<![CDATA[ ->>--disconnectKeyPress(--+--------------+--)----->< - +--methodName--+ - -]]> -</programlisting> - -<para> - The <emphasis role="italic">disconnectKeyPress</emphasis> method disconnects a key press event from a method that was - previously connected using <xref linkend="mthConnectKeyPressDialogObject"/>, or - <xref linkend="mthConnectFKeyPressDialogObject"/>. -</para> -<variablelist> - <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> - <listitem> - <para> - The single argument is: - <variablelist> - <varlistentry><term>methodName [optional]</term> - <listitem> - <para> - If <emphasis role="italic">methodName</emphasis> is specified, only the key press events connected to that - method are disconnected. If the argument is omitted, then all key press events for the dialog will be - disconnected. - </para> - </listitem></varlistentry> - </variablelist> - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> - <listitem> - <para> - The possible return values are: - <variablelist> - <varlistentry><term>0</term> - <listitem> - <para> - Success. - </para> - </listitem></varlistentry> - <varlistentry><term>-2</term> - <listitem> - <para> - While trying to disconnect the method, the underlying mechanism in the Windows API that is used to capture key - events had an error. This is unlikely to happen. - </para> - </listitem></varlistentry> - <varlistentry><term>-7</term> - <listitem> - <para> - Either the <emphasis role="italic">methodName</emphasis> method is already disconnected, or there are no methods - connected at all. - </para> - </listitem></varlistentry> - </variablelist> - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> - <listitem> - <para> - The dialog control object also has a <xref linkend="mthDisconnectKeyPressDialogControlObject"/> - method. The method of the dialog object (this method) can only disconnect key press events that were set with the - dialog object's versions of <xref linkend="mthConnectKeyPressDialogObject"/> and - <xref linkend="mthConnectFKeyPressDialogObject"/> methods. This method can not disconnect key press - events that were set with the dialog control object's versions of - <xref linkend="mthConnectKeyPressDialogControlObject"/> and - <xref linkend="mthConnectFKeyPressDialogControlObject"/> methods. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Details</emphasis></term> - <listitem> - <para> - Raises syntax errors when some incorrect usage is detected. - </para> - </listitem></varlistentry> - <varlistentry><term><emphasis role="bold">Example:</emphasis></term> - <listitem> - <para> - The following example is a variation on the <link linkend="connectKeyPressExample">example</link> shown for the - <xref linkend="mthConnectKeyPressDialogObject"/> method. It builds on the fictitious customer - order system. The F7 key saves the completed invoice into the system and enters a different phase of the companies - business process. At this point (for whatever fictitious business reason) the fields can no longer be cleared and - the user is not allowed to look up customer or product information. But, the user may still need to print the - invoice. To prevent the accidental press of the hot keys causing the wrong action, those key presses are - disconnected. - </para> - <para> - To demonstrate how key press connections can be added and removed through out the life time of the dialog, this - example adds the F9 hot key. F9 starts a new order entry cycle and re-connects the hot keys used during the - creation of a customer invoice. When the user then saves the next completed invoice, key press connections are - removed, when she starts a new invoice key press connections are restored. This cycle could continue though out the - day without the user ever closing the main dialog. - -<programlisting> -<![CDATA[ - -::method initDialog - - ... - - -- Capture F2 key presses, but not Ctrl-F2 or Alt-F2, etc.. - self~connectKeyPress(onF2, .VK~F2, "NONE") - - -- Same idea for F3, F4, F5, and F7. This uses the actual numeric value for - -- the keys without bothering to use the .VK class to translate. - self~connectKeyPress(onF3, 114, "NONE") - self~connectKeyPress(onF4, 115, "NONE") - self~connectKeyPress(onF5, 116, "NONE") - self~connectKeyPress(onF7, 118, "NONE") - self~connectKeyPress(onF9, 120, "NONE") - - ... - -::method onF2 unguarded - self~showCustomerLookupDialog - - return 0 - -::method onF3 unguarded - - prodNum = self~newEdit(IDC_EDIT_PRODUCT)~getText - if prodNum \== "" then self~showProductInfo(prodNum) - return 0 - -::method onF4 - self~resetAllFields - return 0 - -::method onF5 - self~printInvoice - return 0 - -::method onF7 - - self~saveToDataBase - self~disconnectKeyPress(onF2) - self~disconnectKeyPress(onF3) - self~disconnectKeyPress(onF4) - return 0 - -::method onF9 - - self~resetAllFields - self~connectKeyPress(onF2, ... [truncated message content] |
From: <mie...@us...> - 2014-01-04 23:29:24
|
Revision: 9802 http://sourceforge.net/p/oorexx/code-0/9802 Author: miesfeld Date: 2014-01-04 23:29:21 +0000 (Sat, 04 Jan 2014) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 23:24:39 UTC (rev 9801) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 23:29:21 UTC (rev 9802) @@ -5037,14 +5037,6 @@ sent to the underlying dialog for a key stroke event. </para> </listitem></varlistentry> - <varlistentry id="connectKeyPressEventHandler"><term><emphasis role="bold">Event Handler Method Arguments:</emphasis></term> - <listitem> - <para> - The ooDialog method connected to the key press event will receive the following five arguments in the order listed: - <variablelist> - </variablelist> - </para> - </listitem></varlistentry> <varlistentry id="connectKeyPressExample"><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> |
From: <mie...@us...> - 2014-01-04 23:39:53
|
Revision: 9803 http://sourceforge.net/p/oorexx/code-0/9803 Author: miesfeld Date: 2014-01-04 23:39:50 +0000 (Sat, 04 Jan 2014) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 23:29:21 UTC (rev 9802) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-04 23:39:50 UTC (rev 9803) @@ -4690,15 +4690,15 @@ </para> <para> - The event handling method receives the same arguments as the <link linkend="connectKeyPressEventHandler">event</link> - handler for the <emphasis role="italic">connectKeyPress</emphasis> method. + Both the <emphasis role="italic">connectFKeyPress</emphasis> and the <xref linkend="mthConnectKeyPressDialogObject"/> + methods use the same event <link linkend="evtEventNotificationKEYPRESS">handler</link>. </para> <para> Unlike most other methods that connect event notifications, the underlying Windows dialog must exist before this - method can be used. That means it can be used in <xref linkend="mthInitDialog"/> or any time - thereafter. There is a maximum limit of 63 methods, per dialog, that can be connected to key press events. - Connections can be removed using the <xref linkend="mthDisconnectKeyPressDialogObject"/> - method if there is no longer a need for a notification of a key press. + method can be used. That means it can be used in <xref linkend="mthInitDialog"/> or any time thereafter. There is a + maximum limit of 63 methods, per dialog, that can be connected to key press events. Connections can be removed using the + <xref linkend="mthDisconnectKeyPressDialogObject"/> method if there is no longer a need for a notification of a key + press. </para> <para> The dialog control object also has a <xref linkend="mthConnectFKeyPressDialogControlObject"/>() @@ -4727,11 +4727,6 @@ If the programmer does not provide a matching method in the Rexx dialog, a syntax condition will be raised if any F Key key press events happen. </para> - <para> - Due to the nature of key press events, the low-level implementation of capturing the key strokes is different from - most of the other methods of the <computeroutput>EventNotification</computeroutput> class. There is no single message - sent to the underlying dialog for a key stroke event. - </para> </listitem> </varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> |
From: <mie...@us...> - 2014-01-07 01:28:58
|
Revision: 9807 http://sourceforge.net/p/oorexx/code-0/9807 Author: miesfeld Date: 2014-01-07 01:28:55 +0000 (Tue, 07 Jan 2014) Log Message: ----------- [feature-requests:#574] Event connections should all have a 'willReply' argument [feature-requests:#579] Send Rexx dialog control object to event handling methods. [feature-requests:#580] Send proper args to the DRAW event handler. Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-06 00:26:08 UTC (rev 9806) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-07 01:28:55 UTC (rev 9807) @@ -1983,8 +1983,8 @@ <listitem> <para> A numeric value that contains info about the event. The low order word contains the resource ID of the button sending - the event. The high order word contains the button event code. However, the ooDialog framework extracts these values - for you and sends them as the third and fourth arguments. + the event. The high order word contains the button event code. However, the ooDialog framework now extracts these + values for you and sends them as the third and fourth arguments. </para> </listitem></varlistentry> <varlistentry><term>hwnd</term> @@ -2351,7 +2351,7 @@ <programlisting> <![CDATA[ ::method onComboBoxEvent unguarded - use arg info, hwnd, info, notifyCode, comboBox + use arg info, hwnd, id, notifyCode, comboBox return 0 ]]> @@ -2370,7 +2370,8 @@ <para> A numeric value that contains info about the event. The low order word contains the resource ID of the combo box sending the event. The high order word contains the combo box event code. The <xref linkend="mthLoWord"/> and <xref - linkend="mthHiWord"/> methods of the <xref linkend="clsDlgUtil"/> class can be used to extract these values. + linkend="mthHiWord"/> methods of the <xref linkend="clsDlgUtil"/> class can be used to extract these values. However, + the ooDialog framework now extracts those values for you and sends them as the third and fourth arguments. </para> </listitem></varlistentry> <varlistentry><term>hwnd</term> @@ -4023,7 +4024,7 @@ The <emphasis role="italic">connectDraw</emphasis> method connects the draw control event notification with a method in the Rexx dialog. This notification is sent to the underlying dialog by an owner-drawn button, combo box, list box, static, or menu, when a visual aspect of the control or menu has changed. In addition, if a tab control or a list-view have - the owner draw fixed style, the also recieve the notifiction. + the owner draw fixed style, they also recieve the notifiction. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -4087,9 +4088,16 @@ The notification for the draw control is only sent to the above mentioned controls when they have the OWNERDRAW or OWNERDRAWFIXED styles. The notification itself is to inform the application that it needs to draw the control at this time. Note that the ooDialog framework is not well suited to drawing operations and it is unlikely that this notification - is of much use except in rare circumstances. + is of much use except when the drawing to be done is not very complex. </para> <para> + Prior to ooDialog 4.2.4, the arguments sent to the event handler for this connection were not helpful in attempting to do + owner draw. The arguments now sent to the event handler will make the task easier and ambitious programmers may want to + try owner draw in medium complex applications. <emphasis role="bold">Note</emphasis> however that the <emphasis + role="italic">willReply</emphasis> argument must be set to <computeroutput>.true</computeroutput> or <emphasis + role="italic">SYNC</emphasis> or the drawing efforts will produce highly unpredictable results. + </para> + <para> See the sections on <link linkend="sctConnectingEventHandlers">connecting</link> and <link linkend="sctCodingEventHandlers">coding</link> event handlers for additional information on event handlers. </para> @@ -4124,9 +4132,9 @@ <programlisting> <![CDATA[ ::method onDraw unguarded - use arg id, pointer, cntrlObj + use arg id, lp, drawObj, itemID, flags, hDC, rcItem, itemData - return zz + return .true ]]> </programlisting> @@ -4134,23 +4142,24 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves xx arguments: + The event handling method recieves 8 arguments: </para> <variablelist> <varlistentry><term>id</term> <listitem> <para> - The resource ID of the control that needs to be drawn. + The resource ID of the control that needs to be drawn. This value is not valid for menu items </para> </listitem></varlistentry> - <varlistentry><term>pointer</term> + <varlistentry><term>lp</term> <listitem> <para> The numeric value of a pointer to a memory location. This is of no use to the ooDialog programmer. There is no way to - access the data the pointer points to from the ooDialog program. + access the data the pointer points to from the ooDialog program. This argument is retained for backwards compatibility. + The following arguments contain the values of the data the pointer points to. They are the important arguments. </para> </listitem></varlistentry> - <varlistentry><term>cntrlObj</term> + <varlistentry><term>drawObj</term> <listitem> <para> The Rexx dialog control object that represents the control that needs to be drawn. If it is a menu item that needs to @@ -4158,23 +4167,332 @@ In future versions of ooDialog this may be the Rexx menu object that contains the menu item needing to be drawn. </para> </listitem></varlistentry> + <varlistentry><term>itemID</term> + <listitem> + <para> + The menu item ID for a menu item or the one-based index of the item in a list box or combo box. For an empty list box + or combo box, this member can be 0. This allows the application to draw only the focus rectangle at the coordinates + specified by the rcItem member even though there are no items in the control. This indicates to the user whether the + list box or combo box has the focus. Which keywords are present in the <emphasis role="italic">flags</emphasis> + determines whether the rectangle is to be drawn as though the list box or combo box has the focus. + </para> + </listitem></varlistentry> + <varlistentry><term>flags</term> + <listitem> + <para> + A list of the following keywords separated by spaces, case is not significant. The keywords are separated into 3 + groups, type, action, and state. The keywords in the same group all start with the same prefix, ODT_ for type, ODA_ for + action, and ODS_ for state. The list will contain at least one keyword from the type group. The keywords provide + information that allows the application to detemine what drawing operation needs to be done: + </para> + <para> + <simplelist type='vert' columns='3'> + <member>ODT_BUTTON </member> + <member>ODT_COMBOBOX </member> + <member>ODT_HEADER </member> + <member>ODT_LISTBOX </member> + <member>ODT_LISTVIEW </member> + <member>ODT_MENU </member> + <member>ODT_STATIC </member> + <member>ODT_TAB </member> + <member>ODT_UNKNOWN </member> + <member>ODA_DRAWENTIRE </member> + <member>ODA_FOCUS </member> + <member>ODA_SELECT </member> + <member>ODS_CHECKED </member> + <member>ODS_COMBOBOXEDIT </member> + <member>ODS_DEFAULT </member> + <member>ODS_DISABLED </member> + <member>ODS_FOCUS </member> + <member>ODS_GRAYED </member> + <member>ODS_HOTLIGHT </member> + <member>ODS_INACTIVE </member> + <member>ODS_NOACCEL </member> + <member>ODS_NOFOCUSRECT </member> + <member>ODS_SELECTED </member> + </simplelist> + <variablelist> + <varlistentry><term>ODT_BUTTON</term> + <listitem> + <para> + An owner-drawn button is sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_COMBOBOX</term> + <listitem> + <para> + A owner-drawn combo box is sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_HEADER</term> + <listitem> + <para> + A header control is sending the notification. It is unlikely this keyword will ever be seen. ooDialog does not yet + have support for header controls and MSDN does not document this. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_LISTBOX</term> + <listitem> + <para> + An owner-drawn list box is sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_LISTVIEW</term> + <listitem> + <para> + A list-view is sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_MENU</term> + <listitem> + <para> + An owner-drawn menu item is sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_STATIC</term> + <listitem> + <para> + An owner-drawn static control is sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_TAB</term> + <listitem> + <para> + A tab control is sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>ODT_UNKNOWN</term> + <listitem> + <para> + The notification was sent by something unexpected to the ooDialog framework. It is doubtful that this keyword will + ever be seen. + </para> + </listitem></varlistentry> + <varlistentry><term>ODA_DRAWENTIRE</term> + <listitem> + <para> + The entire control needs to be drawn. + </para> + </listitem></varlistentry> + <varlistentry><term>ODA_FOCUS</term> + <listitem> + <para> + The control has lost or gained the keyboard focus. The state keywords should be checked to determine whether the + control has the focus. + </para> + </listitem></varlistentry> + <varlistentry><term>ODA_SELECT</term> + <listitem> + <para> + The selection status has changed. The state keywords should be checked to determine the new selection state. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_CHECKED</term> + <listitem> + <para> + The menu item is to be checked. This keyword is used only in a menu. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_COMBOBOXEDIT</term> + <listitem> + <para> + The drawing takes place in the selection field (edit control) of an owner-drawn combo box. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_DEFAULT</term> + <listitem> + <para> + The item is the default item. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_DISABLED</term> + <listitem> + <para> + The item is to be drawn as disabled. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_FOCUS</term> + <listitem> + <para> + The item has the keyboard focus. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_GRAYED</term> + <listitem> + <para> + The item is to be grayed. This keyword is used only in a menu. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_HOTLIGHT</term> + <listitem> + <para> + The item is being hot-tracked, that is, the item will be highlighted when the mouse is on the item. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_INACTIVE</term> + <listitem> + <para> + The item is inactive and the window associated with the menu is inactive. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_NOACCEL</term> + <listitem> + <para> + The control is drawn without the keyboard accelerator cues. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_NOFOCUSRECT</term> + <listitem> + <para> + The control is drawn without focus indicator cues. + </para> + </listitem></varlistentry> + <varlistentry><term>ODS_SELECTED</term> + <listitem> + <para> + The menu item's status is selected. + </para> + </listitem></varlistentry> + </variablelist> + </para> + </listitem></varlistentry> + <varlistentry><term>hDC</term> + <listitem> + <para> + The <xref linkend="defDeviceContext"/> for the drawing area. This device context must be used to do the drawing. It is + passed by the operating system and <emphasis role="italic">must not</emphasis> freed by the application. In addition, + upon return from the event handler, the device context must be set back to the same state it was on entry to the event + handler. + </para> + </listitem></varlistentry> + <varlistentry><term>rcItem</term> + <listitem> + <para> + A <xref linkend="clsRect"/> object that defines the boundaries of the control to be drawn. This rectangle is in the + device context specified by the <emphasis role="italic">hDC</emphasis> argument. The operating system automatically + clips anything that the owner window draws in the device context for combo boxes, list boxes, and buttons, but does not + clip menu items. When drawing menu items, the owner window must not draw outside the boundaries of the rectangle + defined by this argument. + </para> + </listitem></varlistentry> + <varlistentry><term>itemData</term> + <listitem> + <para> + The item data associated with the menu item or control, or the <computeroutput>.nil</computeroutput> object when there + is no item data. Menu items and many dialog controls allow the application to associate a user object with each item. + However, ooDialog does not completely support this at this time. For instance, the <xref + linkend="mthGetItemDataClsListView"/> and <xref linkend="mthSetItemDataClsListView"/> methods support associating user + objects with the list-view items. But the support has not yet been added to combo boxes and list boxes. Because of + this, it is likely that the <emphasis role="italic">itemData</emphasis> argument will usually be the + <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> <listitem> <para> - xx + The MSDN documentation says that the event handler should return true when the application has handled the DRAW event + notification. Which implies that false should be returned otherwise. Therefore, the ooDialog programmer should probably + return true from the event handler. However, some experimentation with returning false has not shown any discernable + differeence than returning true. </para> </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> + <listitem> + <para> + Although this documentation says the the device context passed in the <emphasis role="italic">hDC</emphasis> argument + must be used to do the drawing in the event handler, ooDialog has examples that did not do this. Examples written prior + to ooDialog 4.2.0 did not have the device context passed into the event handler. These examples used the <xref + linkend="mthGetControlDC"/> method to get a device context for the owner-drawn control. This technique seems to work + okay. Nevertheless, if the ooDialog programmer is trying to use owner-drawn controls, it is highly likely that performing + the user drawing the way it is intended to be done is more likely to have success. + </para> + <para> + When the device context passed as the <emphasis role="italic">hDC</emphasis> argument is used to perform the drawing, as + intended by the operating system, it is critical that the <link linkend="sctCommonWillReply">willReply</link> argument be + set to true or <emphasis role="italic">SYNC</emphasis>. The result of any drawing operations done with the device context + when the interpreter does not wait for the event handler to return will be highly unpredictable. + </para> + </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example</emphasis></term> <listitem> <para> - The following example ... + The following example creates a large owner-drawn button that takes up most of the dialog. The client area of the button + is then used as a <emphasis role="italic">canvass</emphasis> to draw on. The event handler is invoked every time the + button needs to be drawn. The event handler draws a circle on the button area and writes <emphasis + role="italic">Circle</emphasis> on the button. This is a complete example that allows the user to experiment a little. An + interesting experiment is to uncomment the say statement in the <emphasis role="italic">drawIt</emphasis> method to see + when the event handler is executing: <programlisting> <![CDATA[ + dlg = .OwnerDrawDlg~new + if dlg~initCode <> 0 then return 99 + dlg~execute("SHOWTOP") +return 0 + +::requires "ooDialog.cls" + +::class 'OwnerDrawDlg' subclass UserDialog + +::method init + + forward class (super) continue + self~create(6, 15, 187, 135, "Owner-drawn Button Dialog", "CENTER") + + self~connectDraw(10, "drawIt", .true) + +::method defineDialog + self~createPushButton(10, 6, 6, 175, 123, "OWNER", "") + +::method drawIt unguarded + use arg id, lp, drawObj, itemID, flags, dc, r, itemData + + -- Uncomment this line to seen when the event handler is executed: + --say 'Draw It' + + -- Create a pen to draw a circle with. + pen = drawObj~createPen(5, "SOLID", 1) + oldPen = drawObj~objectToDc(dc, pen) + + -- Create a font to use to draw text with. + properties = .directory~new + properties~weight = 700 + properties~italic = .true + + font = drawObj~createFontEx("Arial", 24, properties) + oldFont = drawObj~fontToDC(dc, font) + + drawObj~transparentText(dc) + + -- Get the midpoint of the button rectangle and set the text align to center + pos = .Point~new(r~right % 2, r~bottom % 2) + oldAlign = drawObj~setTextAlign(dc, 'CENTER BASELINE NOUPDATECP') + + -- Get a rectangle indented 5 from the button's area. + dr = .Rect~new(r~left + 5, r~top + 5, r~right - 10, r~bottom - 10) + + -- Draw a circle, within the rectangle + drawObj~drawArc(dc, dr~left, dr~top, dr~right, dr~bottom) + + -- Write some text at the position we calculated above. + drawObj~writeDirect(dc, pos~x, pos~y, 'Circle') + + -- Now restore the DC so it is the same as passed into us. + drawObj~setTextAlign(dc, oldAlign) + drawObj~fontToDC(dc, oldFont) + drawObj~objectToDc(dc, oldPen) + + drawObj~opaqueText(dc) + + drawObj~deleteFont(font) + drawObj~deleteObject(pen) + + return .true + ]]> </programlisting> </para> @@ -4372,7 +4690,7 @@ <programlisting> <![CDATA[ ::method onEditEvent unguarded - use arg info, hwnd + use arg info, hwnd, id, notifyCode, controlObj return 0 ]]> @@ -4382,7 +4700,8 @@ <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The event handling method recieves 2 arguments: + The event handling method recieves 5 arguments. The first and second arguments need to be retained for backwards + compatibility, but only the last 3 arguments are really needed: </para> <variablelist> <varlistentry><term>info</term> @@ -4390,7 +4709,8 @@ <para> A numeric value that contains info about the event. The low order word contains the resource ID of the edit control sending the event. The high order word contains the edit control event code. The <xref linkend="mthLoWord"/> and <xref - linkend="mthHiWord"/> methods of the <xref linkend="clsDlgUtil"/> class can be used to extract these values. + linkend="mthHiWord"/> methods of the <xref linkend="clsDlgUtil"/> class can be used to extract these values. However, + the ooDialog framework now extracts those values for you and sends them as the third and fourth arguments. </para> </listitem></varlistentry> <varlistentry><term>hwnd</term> @@ -4399,6 +4719,26 @@ The window handle of the edit control that sent the notification. </para> </listitem></varlistentry> + <varlistentry><term>id</term> + <listitem> + <para> + The numeric resource id of the edit control sending the notification. + </para> + </listitem></varlistentry> + <varlistentry><term>notifyCode</term> + <listitem> + <para> + The numeric notification code of the event that caused the notification to be sent. Each dialog control has its own + specific notification codes. + </para> + </listitem></varlistentry> + <varlistentry><term>controlObj</term> + <listitem> + <para> + The Rexx edit control object that represents the underlying dialog control that sent the notification. It is possible + this will be the <computeroutput>.nil</computeroutput> object if some error happened, but this is very unlikely. + </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return:</emphasis></term> @@ -4410,30 +4750,29 @@ <varlistentry><term><emphasis role="bold">Example</emphasis></term> <listitem> <para> - The following example shows how to extract the resource ID of the edit control sending the notification and take some - action depending on which edit control sent the notification: + The following example connects several edit controls to the same event handle and then uses the <emphasis + role="italic">id</emphasis> argument to determine which edit control is sending the notification and take some action + specific to that edit control. The code is somewhat simplistic as it ignores what the notification code is. In a real + word program the actions taken would depend on what the event was: <programlisting> <![CDATA[ -::method playSong unguarded - use arg info, hwnd +::method onEditEvent unguarded + use arg info, hwnd, id, notifyCode, editObj - id = .DlgUtil~loWord(info) - if id == self~constDir[IDC_EDIT_AMOUNT] then do - ec = self~newEdit("IDC_EDIT_AMOUNT") - if ec~getText~space(0) \== "" & ec~getText~dataType("N") == 0 then do - ec~setModified(.false) - ec~select - ec~replaceSelText("0") + if id == .constDir[IDC_EDIT_AMOUNT] then do + if editObj~getText~space(0) \== "" & editObj~getText~dataType("N") == 0 then do + editObj~setModified(.false) + editObj~select + editObj~replaceSelText("0") end end - else if id == self~constDir[IDC_EDIT_ZIP] then do - ec = self~newEdit("IDC_EDIT_ZIP") - zip = ec~getText~strip + else if id == .constDir[IDC_EDIT_ZIP] then do + zip = editObj~getText~strip if \ self~validZipCode(zip) then doe -- Put up message box telling -- user what the problem is ... - ec~setText("") + editObj~setText("") end end @@ -4456,21 +4795,21 @@ <indexterm><primary>EventNotification class</primary><secondary>connectHelp</secondary></indexterm> <programlisting> <![CDATA[ ->>--connectHelp(--+--------------+--)------------>< - +--methodName--+ +>>--connectHelp(--+--------------+--+--------------+--)--------->< + +--methodName--+ +-,-willReply--+ ]]> </programlisting> <para> - The <emphasis role="italic">connectHelp</emphasis> method connects the Windows Help event with a method in the dialog. The Windows Help - event occurs when the user presses the F1 key. (Only the Help events generated when the dialog is the active window - are connected.) + The <emphasis role="italic">connectHelp</emphasis> method connects the Windows Help event with a method in the dialog. The + Windows Help event occurs when the user presses the F1 key. (Only the Help events generated when the dialog is the active + window are connected.) </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem> <para> - The only argument is: + The arguments are: <variablelist> <varlistentry><term>methodName [optional]</term> <listitem> @@ -4479,6 +4818,14 @@ this argument is omitted the name defaults to <emphasis role="italic">onHelp</emphasis>. </para> </listitem></varlistentry> + <varlistentry><term>willReply [optional]</term> + <listitem> + <para> + The <link linkend="sctCommonWillReply">willReply</link> argument controls how the interpreter invokes the event + handler for the connected event. The default if <emphasis role="italic">willReply</emphasis> is omitted is + <computeroutput>.false</computeroutput>. + </para> + </listitem></varlistentry> </variablelist> </para> </listitem></varlistentry> @@ -4568,11 +4915,11 @@ ... ::method onHelp unguarded - use arg id, type, mouseX, mouseY + use arg id, type, mouseX, mouseY, cntxID, helpObj if type == "MENU" then w = 'Menu id' id; else w = 'Dialog id' id say "Help request:" say " " w - say " Mouse position x:" mouseX "y:" mouseY + say " Mouse position x:" mouseX "y:" mouseY 'help object:' helpObj return 0 @@ -4582,32 +4929,176 @@ Help request: Dialog id 12 - Mouse position x: 420 y: 106 + Mouse position x: 420 y: 106 help object: a Button Help request: Menu id 60 - Mouse position x: 204 y: 93 + Mouse position x: 204 y: 93 help object: the NIL object Help request: Menu id 65 - Mouse position x: 203 y: 166 + Mouse position x: 203 y: 166 help object: the NIL object Help request: Dialog id 14 - Mouse position x: 218 y: 410 + Mouse position x: 218 y: 410 help object: a RadioButton Help request: Dialog id 80 - Mouse position x: 387 y: 462 + Mouse position x: 387 y: 462 help object: a Tab ]]> </programlisting> </para> </listitem></varlistentry> </variablelist> -</section> +<section id="evtEventNotificationHELP" xreflabel="HELP"><title>Help Event Handler</title> +<indexterm><primary>EventNotification class</primary><secondary>events</secondary><tertiary>HELP</tertiary></indexterm> +<para> + The event handler for the Help event is invoked when the user presses the F1 key when the active window is the dialog. +</para> +<para> + The <link linkend="sctCommonWillReply">willReply</link> argument in the <xref linkend="mthConnectEditEvent"/> method + determines how the event handler needs to respond to the notification. +</para> +<para> +<programlisting> +<![CDATA[ +::method onHelp unguarded + use arg id, type, mouseX, mouseY, cntxID, helpObj + + return .true +]]> +</programlisting> + +<variablelist> + <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> + <listitem> + <para> + The event handling method recieves 6 arguments: + </para> + <variablelist> + <varlistentry><term>id</term> + <listitem> + <para> + The resource ID of the dialog, dialog control, or menu item that had the focus when the F1 key was pressed. + </para> + </listitem></varlistentry> + <varlistentry><term>type</term> + <listitem> + <para> + Specifies if the ID in argument 1 was from a window (a dialog or dialog control) or from a menu item. This + argument will either be <computeroutput>WINDOW</computeroutput> or <computeroutput>MENU</computeroutput>. + </para> + </listitem></varlistentry> + <varlistentry><term>mouseX</term> + <listitem> + <para> + The x coordinate of the mouse at the time the F1 key was pressed. This value is an absolute screen coordinate + (pixel) and note that the mouse will not necessarily be over the dialog. + </para> + </listitem></varlistentry> + <varlistentry><term>mouseY</term> + <listitem> + <para> + The y coordinate of the mouse at the time the F1 key was pressed. The same caveats as for the <emphasis + role="italic">mouseX</emphasis> argument apply. + </para> + </listitem></varlistentry> + <varlistentry><term>cntxID</term> + <listitem> + <para> + The help context identifier of the dialog, control, or menu. ooDialog does not yet have good support for setting help + context IDs for dialogs or dialog controls. However, ooDialog does support setting the help ID for menus. therefor if + the <emphasis role="italic">type</emphasis> is <emphasis role="italic">WINDOW</emphasis>, this argument will probably + be 0. + </para> + </listitem></varlistentry> + <varlistentry><term>helpObj</term> + <listitem> + <para> + The Rexx dialog object or the Rexx dialog control object that had the focus when the F1 key was pressed. Otherwise, + the <computeroutput>.nil</computeroutput> object if it was a menu item that had the focus. <emphasis + role="bold">Note:</emphasis> It is anticipated that future versions of ooDialog will return the Rexx menu object that + contains the menu item instead of the <computeroutput>.nil</computeroutput> object. + </para> + </listitem></varlistentry> + </variablelist> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Return:</emphasis></term> + <listitem> + <para> + The MSDN documentation says to return true from the event handler. + </para> + </listitem></varlistentry> + <varlistentry><term><emphasis role="bold">Example</emphasis></term> + <listitem> + <para> + The following example shows a simple event handler that prints out the values of the arguments sent to it. This can be + useful is understanding how the event handler for the <emphasis role="italic">connectHelp</emphasis> method works: + +<programlisting> +<![CDATA[ + +::method init + expose menubar + + forward class (super) continue + + if \ self~createMenuBar then do + self~initCode = 1 + return + end + + self~connectHelp('onHelp', 'SYNC') + +::method onHelp unguarded + use arg id, type, x, y, cntxID, helpObj + + say 'onHelp' + say 'id:' id 'type:' type 'x:' x 'y:' y 'cntxID:' cntxID 'helpObj:' heldObj + + return .true + +/* Output might be for example: +onHelp +id: 1 type: WINDOW x: 796 y: 463 cntxID: 0 helpObj: a Button +onHelp +id: 2 type: WINDOW x: 796 y: 463 cntxID: 0 helpObj: a Button +onHelp +id: 1002 type: WINDOW x: 796 y: 463 cntxID: 0 helpObj: a Tab +onHelp +id: 65535 type: WINDOW x: 796 y: 463 cntxID: 0 helpObj: a GroupBox +onHelp +id: 1003 type: WINDOW x: 796 y: 463 cntxID: 0 helpObj: a RadioButton +onHelp +id: 833 type: MENU x: 976 y: 319 cntxID: 46 helpObj: The NIL object +onHelp +id: 821 type: MENU x: 976 y: 319 cntxID: 45 helpObj: The NIL object +onHelp +id: 821 type: MENU x: 323 y: 161 cntxID: 45 helpObj: The NIL object +onHelp +id: 812 type: MENU x: 323 y: 161 cntxID: 44 helpObj: The NIL object +onHelp +id: 1003 type: WINDOW x: 796 y: 375 cntxID: 0 helpObj: a RadioButton +onHelp +id: 1003 type: WINDOW x: 473 y: 347 cntxID: 0 helpObj: a RadioButton + +*/ + +]]> +</programlisting> + </para> + </listitem></varlistentry> +</variablelist> + +</section> <!-- End Help Event Handler --> + +</section> <!-- End EventNotification::connectHelp() --> + + <section id="sctConnectingKeyPressEvents"><title>Connecting Key Press Events</title> <indexterm><primary>Connecting Key Press Events</primary></indexterm> <para> - + This section contains methods related to connecting key press events. </para> <section id="mthConnectFKeyPressDialogObject" xreflabel="connectFKeyPress"><title>connectFKeyPress</title> @@ -5341,7 +5832,7 @@ <para> The interpreter replies immediately to the operating system when the key is pressed. Tthe event handler is then invoked concurrently as a separate activity and the interpreter does not wait for the return. The value returned from the event - handler is ignored and the programmer need not return a value from the handerl. However, good practice would be to always + handler is ignored and the programmer need not return a value from the handler. However, good practice would be to always return a value from an event handler. </para> @@ -5514,15 +6005,16 @@ <indexterm><primary>connectListBoxEvent</primary></indexterm> <programlisting> <![CDATA[ ->>--connectListBoxEvent(--id--,--event--+---------------+--)---->< - +-,--methodName-+ +>>--connectListBoxEvent(--id--,--event--+---------------+--+--------------+--)->< + +-,--methodName-+ +-,-willReply--+ ]]> </programlisting> -<para>The connectListBoxEvent method connects a particular -WM_NOTIFY message for a list box with a method. The WM_NOTIFY message -informs the dialog that an event has occurred in the list box.</para> +<para> + Connects a method in the Rexx dialog to the Windows <xref linkend="ovvEvents"/> notification from a <xref + linkend="clsListBox"/> control. +</para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> <listitem><para>The arguments are: |
From: <mie...@us...> - 2014-01-07 03:18:12
|
Revision: 9809 http://sourceforge.net/p/oorexx/code-0/9809 Author: miesfeld Date: 2014-01-07 03:18:09 +0000 (Tue, 07 Jan 2014) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-07 01:35:51 UTC (rev 9808) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-07 03:18:09 UTC (rev 9809) @@ -4957,7 +4957,6 @@ The <link linkend="sctCommonWillReply">willReply</link> argument in the <xref linkend="mthConnectEditEvent"/> method determines how the event handler needs to respond to the notification. </para> -<para> <programlisting> <![CDATA[ |
From: <mie...@us...> - 2014-01-09 01:22:45
|
Revision: 9817 http://sourceforge.net/p/oorexx/code-0/9817 Author: miesfeld Date: 2014-01-09 01:22:42 +0000 (Thu, 09 Jan 2014) Log Message: ----------- ooDialog doc - fig tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-09 00:57:23 UTC (rev 9816) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-09 01:22:42 UTC (rev 9817) @@ -6986,6 +6986,7 @@ return 0 ]]> +</programlisting> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -7010,7 +7011,7 @@ <listitem> <para> This argument reports whether the check box was checked or unchecked. Its value will be either - <emphasis role="italic">CHECKED</emphasis> or <emphasis role="italic">UNCHECKED</emphasis/> "" + <emphasis role="italic">CHECKED</emphasis> or <emphasis role="italic">UNCHECKED</emphasis>. </para> </listitem></varlistentry> <varlistentry><term>listView</term> @@ -7114,16 +7115,24 @@ <varlistentry><term>itemIndex</term> <listitem> <para> - The index of the item whose checkbox was changed. + The index of the item that was clicked on. </para> </listitem></varlistentry> - <varlistentry><term>state</term> + <varlistentry><term>columnIndex</term> <listitem> <para> - This argument reports whether the check box was checked or unchecked. Its value will be either <emphasis - role="italic">CHECKED</emphasis> or <emphasis role="italic">UNCHECKED</emphasis/>. + The index of the column in the item that was clicked on. If not in report view, this will always be 0. </para> </listitem></varlistentry> + <varlistentry><term>keyState</term> + <listitem> + <para> + One or more keywords, separated by blanks, that report the shift, alt, control key state. It will either be the single + key word: <emphasis role="italic">NONE</emphasis>, or any combination of <emphasis role="italic">SHIFT</emphasis> + <emphasis role="italic">CONTORL</emphasis> <emphasis role="italic">ALT</emphasis>. The keywords report which of the + keys were pressed at the time of the mouse click or double click. + </para> + </listitem></varlistentry> <varlistentry><term>listView</term> <listitem> <para> |
From: <mie...@us...> - 2014-01-10 01:30:02
|
Revision: 9824 http://sourceforge.net/p/oorexx/code-0/9824 Author: miesfeld Date: 2014-01-10 01:29:57 +0000 (Fri, 10 Jan 2014) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-10 01:05:55 UTC (rev 9823) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-10 01:29:57 UTC (rev 9824) @@ -7821,6 +7821,7 @@ <para> The resource ID of the list-view control that sent the notification. </para> + </listitem></varlistentry> <varlistentry><term>vKey</term> <listitem> <para> @@ -8038,6 +8039,7 @@ <para> The resource ID of the list-view control that sent the notification. </para> + </listitem></varlistentry> </variablelist> </listitem></varlistentry> |
From: <mie...@us...> - 2014-01-10 01:36:49
|
Revision: 9825 http://sourceforge.net/p/oorexx/code-0/9825 Author: miesfeld Date: 2014-01-10 01:36:43 +0000 (Fri, 10 Jan 2014) Log Message: ----------- ooDialog doc - fix tags Modified Paths: -------------- docs/trunk/oodialog/en-US/eventNotification.xml Modified: docs/trunk/oodialog/en-US/eventNotification.xml =================================================================== --- docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-10 01:29:57 UTC (rev 9824) +++ docs/trunk/oodialog/en-US/eventNotification.xml 2014-01-10 01:36:43 UTC (rev 9825) @@ -6494,14 +6494,14 @@ compatibility. </para> </listitem></varlistentry> - <varlistentry><term><xref linkend="evt ListViewSELECTCHANGED"/></term> + <varlistentry><term><xref linkend="evtListViewSELECTCHANGED"/></term> <listitem> <para> The selection state of an item changed. (The item was selected or unselected.) Use this keyword instead of the CHANGED keyword. </para> </listitem></varlistentry> - <varlistentry><term><xref linkend="evt ListViewSELECTFOCUSCHANGED"/></term> + <varlistentry><term><xref linkend="evtListViewSELECTFOCUSCHANGED"/></term> <listitem> <para> The selection state or the focus state of an item changed. This event argument combines the selection changed @@ -8303,7 +8303,7 @@ value from the event handler is ignored for this event. </para> </listitem></varlistentry> - <varlistentry><term><xref linkend="evtMonthCalendarSELCHANGE"/></term> + <varlistentry><term><xref linkend="evtMonthCalendarSELCHANGED"/></term> <listitem> <para> Sent by a month calendar control when the currently selected date or range of dates changes. The return value |